@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -16,17 +16,17 @@ 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, extend) {
+async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend) {
     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
         // pre-test build must never invalidate more of the objdir than a plain
-        // `mach build faster` would (field incident: a failed pre-test build
-        // was followed by a ~64-minute full rebuild where an incremental one
-        // should have sufficed).
+        // `mach build faster` would — a failed pre-test build followed by a full
+        // rebuild is an hour where an incremental one would have sufficed.
         const previousBaseline = await readBuildBaseline(projectRoot);
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
             previousBaseline,
+            refuseUnexportedDrift,
         });
         // The mozconfig half of the --extend-coverage anchor can
         // only be checked once prepareBuildEnvironment has regenerated
@@ -64,14 +64,13 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             s.stop('Build complete');
             // Same record, same failure tolerance as `fireforge build` /
             // `build --ui` (build.ts): a green pre-test build refreshes the
-            // stale-build baseline so a later plain `fireforge test` over the
-            // same files — in any invocation shape — is not refused. A failed
-            // write never fails the run. The coverage claim is scoped to the
-            // requested test paths, since a file-scoped `test --build` only
-            // guarantees packaging for those manifests. The previous baseline is
-            // passed through so a scoped write carries the static-components
-            // anchor forward (a `mach build faster` does not rebake
-            // components.conf into the compiled table).
+            // stale-build baseline so a later plain `fireforge test` over the same
+            // files is not refused. A failed write never fails the run. The
+            // coverage claim is scoped to the requested test paths, since a
+            // file-scoped `test --build` only guarantees packaging for those
+            // manifests. The previous baseline is passed through so a scoped write
+            // carries the static-components anchor forward — `mach build faster`
+            // does not rebake components.conf into the compiled table.
             try {
                 // Under --extend-coverage the claim is the UNION of the previous
                 // record and this build's paths, and the static-components anchor
@@ -113,6 +112,19 @@ function assertExtendCoverageUsage(options, normalizedPaths) {
         throw new InvalidArgumentError('--extend-coverage requires explicit test paths: a path-less build records full coverage, which already covers every path.', '--extend-coverage');
     }
 }
+/**
+ * Refuses `--refuse-unexported-drift` on a run that dispatches no build.
+ * The flag governs the PRE-TEST build only, so accepting it without
+ * `--build`/`--build-only` would arm a belt over work that never happens —
+ * exactly the silent no-op this release fixes elsewhere.
+ */
+function assertRefuseUnexportedDriftUsage(options) {
+    if (options.refuseUnexportedDrift !== true)
+        return;
+    if (options.build === true || options.buildOnly === true)
+        return;
+    throw new InvalidArgumentError('--refuse-unexported-drift requires --build or --build-only: it guards the pre-test build, and this run dispatches none.', '--refuse-unexported-drift');
+}
 /** Renders the `recordedBy` invocation string surfaced by `status --test-coverage`. */
 function describeBuildInvocation(extending, coverage) {
     const extendFlag = extending ? ' --extend-coverage' : '';
@@ -133,6 +145,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
     if (extending) {
         assertExtendCoverageUsage(options, normalizedPaths);
     }
+    assertRefuseUnexportedDriftUsage(options);
     if (options.build || options.buildOnly) {
         // A path-less `test --build` runs (and packages for) the full suite;
         // a scoped invocation only vouches for the requested paths. A SCOPED
@@ -152,7 +165,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
                 }
             }
         }
-        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage, extending ? { requestedPaths: normalizedPaths } : undefined);
+        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage, options.refuseUnexportedDrift === true, extending ? { requestedPaths: normalizedPaths } : undefined);
         info('');
         if (options.buildOnly) {
             // Union build for mixed harnesses: the coverage claim

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

@@ -7,6 +7,7 @@
  * `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 { 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';
@@ -32,35 +33,33 @@ function buildStaleBuildMessage(postRebuild) {
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
 }
 function hasStaleBuildArtifactsSignal(output) {
-    // Deliberately narrow: only fire on branding-specific resource paths
-    // that are always a stale-artifact symptom. The earlier pattern also
-    // matched `resource:///modules/distribution.sys.mjs`, which surfaced on
-    // real packaging / module-resolution failures too (e.g. a fork's
-    // `MyBrowserStore.sys.mjs` missing from the installed app dir after a
-    // successful build). That false-positive pushed operators toward
-    // "rebuild" advice for what was actually a module-registration issue.
+    // Deliberately narrow: only fire on branding-specific resource paths that
+    // are always a stale-artifact symptom. A pattern that also matches
+    // `resource:///modules/distribution.sys.mjs` fires on real packaging and
+    // module-resolution failures too — a fork's own `.sys.mjs` missing from
+    // the installed app dir after a successful build — pushing operators
+    // toward "rebuild" advice for a module-registration issue.
     return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
 /**
- * Fork-module-not-registered signal. 2026-04-21 eval Finding #14:
- * a fork's test failed with `Failed to load resource:///modules/mybrowser/
- * MyBrowserStore.sys.mjs`. The branding pattern happened to also match
- * because the test harness printed a branding warning during its
- * teardown, and the stale-build branch won by precedence — telling the
- * operator to rebuild when the real fix is to register the module in
- * the fork's `browser/modules/<binary>/moz.build`. Match a
- * `resource:///modules/<binaryName>/` pattern so fork-owned module
- * failures surface the right diagnosis.
+ * Fork-module-not-registered signal.
+ *
+ * A fork's test failing with `Failed to load
+ * resource:///modules/<binary>/Store.sys.mjs` can also match the branding
+ * pattern, because the harness prints a branding warning during teardown —
+ * and the stale-build branch then wins by precedence, telling the operator
+ * to rebuild when the real fix is to register the module in the fork's
+ * `browser/modules/<binary>/moz.build`. Matching a
+ * `resource:///modules/<binaryName>/` pattern surfaces the right diagnosis.
  */
 function hasForkModuleSignal(output, binaryName) {
-    // `binaryName` comes from fireforge.json, and config validation
-    // (`config-validate.ts:59-70`) bars only `..`, path separators, NUL and
-    // absolute paths — regex metacharacters get through. The inline escape
-    // this replaced wrote its character class as `[.*+?^${}()|[\\]\\\\]`,
-    // which closes early after the escaped backslash, so it escaped nothing:
-    // `my.browser` matched `myXbrowser`, and an unbalanced `(` or `[` threw a
-    // SyntaxError out of the failure-diagnosis path, replacing the real test
+    // `binaryName` comes from fireforge.json, and config validation bars only
+    // `..`, path separators, NUL and absolute paths — regex metacharacters get
+    // through. A hand-written character class is easy to get wrong (one that
+    // closes early after an escaped backslash escapes nothing), which makes
+    // `my.browser` match `myXbrowser` and lets an unbalanced `(` or `[` throw
+    // a SyntaxError out of the failure-diagnosis path, replacing the real test
     // failure with an opaque regex error.
     const pattern = new RegExp(`Failed to load resource:\\/\\/\\/modules\\/${escapeRegex(binaryName)}\\/`, 'i');
     return pattern.test(output);
@@ -130,8 +129,8 @@ function buildMochitestHttp3ServerMessage() {
  * captured output supports, throwing it as a domain error.
  *
  * The branch order is load-bearing: narrower signals are checked before
- * broader ones so, for example, a fork-owned module failure is not reported as
- * a stale build (2026-04-21 eval Finding #14).
+ * broader ones, so a fork-owned module failure is not reported as a stale
+ * build.
  */
 function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext) {
     if (result.exitCode === 0 || result.exitCode === 130)
@@ -158,24 +157,21 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
         throwGeneral(buildHarnessEarlyExitMessage(earlyExit, normalizedPaths));
     }
     // Fork-owned module load failures must beat the branding stale-build
-    // branch: 2026-04-21 eval (Finding #14) saw a fork's test fail with
-    // `Failed to load resource:///modules/mybrowser/MyBrowserStore.sys.mjs`
-    // while the harness teardown printed a branding warning that the old
-    // stale-build pattern matched, so the operator was told to rebuild
-    // when the real fix is to register the missing module.
+    // branch: a test failing with `Failed to load
+    // resource:///modules/<binary>/Store.sys.mjs` while the harness teardown
+    // prints a branding warning would otherwise be told to rebuild, when the
+    // real fix is to register the missing module.
     if (hasForkModuleSignal(combinedOutput, binaryName)) {
         throwGeneral(buildForkModuleMessage(binaryName));
     }
     // Branding-specific stale-build signals keep priority over the broader
     // xpcshell-appdir hint: when `chrome://branding/locale/brand.properties`
     // fails to resolve, the fix really is "rebuild", not "pass --app-path".
-    // But the stale-build check is now narrower — it no longer matches
-    // `resource:///modules/distribution.sys.mjs` alone, which was producing
-    // false-positive rebuild advice on fork-custom module-load failures
-    // (the eval saw this for `MyBrowserStore.sys.mjs`). Cases that once
-    // landed on `distribution.sys.mjs` fall through to xpcshell-appdir,
-    // which is the more useful diagnosis in practice for `Failed to load
-    // resource:///modules/…`.
+    // The stale-build check is narrow enough not to match
+    // `resource:///modules/distribution.sys.mjs` alone, which produced
+    // false-positive rebuild advice on fork-custom module-load failures; those
+    // cases fall through to xpcshell-appdir, the more useful diagnosis for
+    // `Failed to load resource:///modules/…`.
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
         throwGeneral(buildStaleBuildMessage(Boolean(failureContext)));
     }
@@ -194,7 +190,12 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
         info('Run "fireforge register <test-path>" to register it.');
     }
-    throw new BuildError(withContext(`Tests failed with exit code ${result.exitCode}. Check the output above for details.`), 'mach test');
+    // Last, and additive rather than a branch of its own: the run really did
+    // 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');
 }
 /**
  * Applies the harness-run verdict for a single (non-sharded) invocation:
@@ -225,10 +226,10 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
         throw new GeneralError(hint ? `${base}\n\n${hint}` : base);
     }
     if (outcome.verdict.kind === 'tests-ran-ok') {
-        // The verdict is authoritative over the raw exit code: a completed
-        // green embedded summary overrides a non-zero exit caused by harness
-        // noise (field report: fully green --no-shard runs exited 1, forcing
-        // operators to parse embedded summaries by hand).
+        // The verdict is authoritative over the raw exit code: a completed green
+        // embedded summary overrides a non-zero exit caused by harness noise,
+        // which would otherwise leave operators parsing embedded summaries by
+        // hand.
         if (outcome.verdict.greenSummaryOverride) {
             info(`Note: mach exited ${outcome.result.exitCode}, but the embedded suite summary completed ` +
                 'green (Unexpected results: 0). FireForge treats the run as passed; the non-zero exit ' +
@@ -243,8 +244,7 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
     }
     // A green-LOOKING summary rejected on crash/truncation evidence gets its
     // own explanation instead of the generic exit-code message — the operator
-    // must see WHY the green counts were not trusted (0.35.0 green-wash
-    // field report: SIGSEGV at file 2 of 8, `Passed: 2 / Failed: 0`).
+    // must see WHY the green counts were not trusted.
     if (outcome.verdict.greenSummaryRejected) {
         throw new GeneralError(buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode));
     }

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

@@ -58,6 +58,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--build', 'Run incremental UI build before testing')
         .option('--build-only', 'Run the scoped pre-test build (packaging exactly [paths...], mixed harnesses allowed) and exit without dispatching tests — one build covers both harness halves, then run each half without --build')
         .option('--extend-coverage', 'With --build/--build-only and explicit paths, union those paths into the recorded test-packaging coverage instead of replacing it, so an earlier scoped build stays covered. Refused when the build anchor moved (engine HEAD, mozconfig, or a previously fingerprinted packageable file changed).')
+        .option('--refuse-unexported-drift', 'With --build/--build-only, refuse (instead of warning) when the pre-test build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the same belt as "fireforge build --refuse-unexported-drift", armable from the scripted "test --build" shape the hazard actually shows up in')
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .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)')

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

@@ -1,14 +1,13 @@
 /**
- * Run orchestration for `fireforge test`: bounded harness-crash retries
- * (field reports C1/C2) and sequential per-file sharding of multi-path
- * invocations (field report C3).
+ * Run orchestration for `fireforge test`: bounded harness-crash retries and
+ * 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 shared mochitest profile made the second file time out at
- * window-open while each file passed in isolation. Sequential single-file
- * harness runs cost startup time but make results reproducible; the
- * combined invocation stays available via `--no-shard`.
+ * Sharding exists because passing several browser-chrome files to one mach
+ * 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
+ * stays available via `--no-shard`.
  */
 import { type DisplaySleepState } from '../core/display-state.js';
 import { type MachCommandResult } from '../core/mach.js';
@@ -19,8 +18,8 @@ export declare const DEFAULT_HARNESS_RETRIES = 2;
  * Which mach command a run dispatches to. Single-suite runs use the
  * suite-specific command (`mach xpcshell-test` / `mach mochitest`), which
  * skips the mozlog resource monitor that crashes generic `mach test` on a
- * broken host (field report E1). `generic` is the historical `mach test`
- * path (mixed/all-tests runs, or the `--generic-mach-test` opt-out).
+ * broken host. `generic` is the plain `mach test` path (mixed/all-tests runs,
+ * or the `--generic-mach-test` opt-out).
  */
 export type TestSuite = 'xpcshell' | 'mochitest' | 'generic';
 /** Inputs shared by every harness invocation in one `fireforge test` run. */
@@ -63,11 +62,10 @@ export interface TestRunOutcome {
 export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]): Promise<TestRunOutcome>;
 /**
  * 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 directory still runs in ONE browser instance (cross-file
- * state carries within a directory run exactly like the pre-enumeration
- * behavior).
+ * 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
+ * directory still runs in ONE browser instance, keeping cross-file state
+ * behaviour within a directory run.
  */
 export interface ShardGroup {
     /** The path argument as the operator passed it (display label). */

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

@@ -1,18 +1,18 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Run orchestration for `fireforge test`: bounded harness-crash retries
- * (field reports C1/C2) and sequential per-file sharding of multi-path
- * invocations (field report C3).
+ * Run orchestration for `fireforge test`: bounded harness-crash retries and
+ * 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 shared mochitest profile made the second file time out at
- * window-open while each file passed in isolation. Sequential single-file
- * harness runs cost startup time but make results reproducible; the
- * combined invocation stays available via `--no-shard`.
+ * Sharding exists because passing several browser-chrome files to one mach
+ * 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
+ * stays available via `--no-shard`.
  */
 import { probeDisplaySleepState } from '../core/display-state.js';
 import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.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';
@@ -72,6 +72,14 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
             `${verdict.signature?.line ?? ''}\n` +
             `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
+    // read as two real assertion failures.
+    if (verdict.kind === 'test-failures' && verdict.note === undefined) {
+        const prefNote = changedPrefNoiseVerdictNote(`${result.stdout}\n${result.stderr}`);
+        if (prefNote !== undefined)
+            verdict = { ...verdict, note: prefNote };
+    }
     const displayState = await probeDisplayStateForStall(verdict, ctx.headless);
     if (displayState !== undefined) {
         const note = headedDisplayAsleepVerdictNote(verdict.signature, {
@@ -85,10 +93,10 @@ 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 common paths spawn nothing.
+ * 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
  */

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

@@ -9,25 +9,24 @@
 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 operator explicitly accepts the stale package risk.
+ * 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
- * 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 fixtures rather than failing, so the flag (which only
- * accepts stale CONTENT) must not be the trigger. Field incident: a
- * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
- * later run over different files timed out twice at 45s waiting on
- * `DOMAudioPlaybackStarted`.
+ * 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
+ * fixtures rather than failing, so the flag (which only accepts stale
+ * 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 a full-suite request would refuse a probe that touches
- * no fixtures. The stale-content refusal still applies to it unchanged.
+ * 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
+ * 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>;
 /**

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

@@ -11,25 +11,24 @@ import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredReques
 import { GeneralError } 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 operator explicitly accepts the stale package risk.
+ * 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
- * 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 fixtures rather than failing, so the flag (which only
- * accepts stale CONTENT) must not be the trigger. Field incident: a
- * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
- * later run over different files timed out twice at 45s waiting on
- * `DOMAudioPlaybackStarted`.
+ * 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
+ * fixtures rather than failing, so the flag (which only accepts stale
+ * 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 a full-suite request would refuse a probe that touches
- * no fixtures. The stale-content refusal still applies to it unchanged.
+ * 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
+ * a full-suite request would refuse a probe that touches no fixtures. The
+ * stale-content refusal still applies to it unchanged.
  */
 export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);

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

@@ -6,10 +6,12 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * invalid paths, port conflicts, config errors, spawn failures),
  * `inconclusive` marks a run whose harness result exists but cannot be
  * trusted because `engine/` changed (or became unprobeable one-sidedly)
- * while the tests ran, and `lock-timeout` marks a run that never started
- * because the engine session lock stayed contended past the wait budget.
+ * while the tests ran, `lock-timeout` marks a run that never started
+ * because the engine session lock stayed contended past the wait budget,
+ * and `killed` marks a run terminated by a signal before it could reach any
+ * of the others.
  */
-export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout';
+export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
 /**
  * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
  * repeated programmatic invocations (and tests) each get their own
@@ -30,3 +32,18 @@ export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?:
 export declare function emitPassVerdict(): void;
 /** Emits a FAIL verdict carrying an emission-layer reason code. */
 export declare function emitFailVerdict(reason: FireforgeVerdictReason): 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
+ * 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
+ * line asserts a test run happened, and an interrupted `status` did not
+ * have one.
+ *
+ * @param signal - The signal that terminated the run
+ * @returns True when a line was written
+ */
+export declare function emitKilledVerdict(signal: NodeJS.Signals): boolean;

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

@@ -1,6 +1,15 @@
 import { formatFireforgeVerdictLine } from '../core/test-harness-crash.js';
 import { setStdoutSealed } from '../utils/logger.js';
 let emitted = false;
+/**
+ * True once a test run has begun in this process.
+ *
+ * The signal path needs it: a `FIREFORGE-VERDICT` line claims a test run
+ * happened, and a Ctrl+C during `fireforge status` must not print one. Set
+ * by {@link resetVerdictEmission}, which `testCommand` already calls at
+ * entry, so nothing else has to remember to arm it.
+ */
+let armed = false;
 /**
  * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
  * repeated programmatic invocations (and tests) each get their own
@@ -8,6 +17,7 @@ let emitted = false;
  */
 export function resetVerdictEmission() {
     emitted = false;
+    armed = true;
     setStdoutSealed(false);
 }
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
@@ -46,3 +56,23 @@ export function emitPassVerdict() {
 export function emitFailVerdict(reason) {
     writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}`);
 }
+/**
+ * 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
+ * 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
+ * line asserts a test run happened, and an interrupted `status` did not
+ * have one.
+ *
+ * @param signal - The signal that terminated the run
+ * @returns True when a line was written
+ */
+export function emitKilledVerdict(signal) {
+    if (!armed || emitted)
+        return false;
+    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=killed signal=${signal}`);
+    return true;
+}