@hominis/fireforge 0.49.2 → 0.50.0

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

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `fireforge test` checks that run BEFORE the engine session lock.
+ *
+ * Everything here reads, never writes, so none of it needs the lock, and
+ * each check used to cost a full place in the lock queue before it could
+ * refuse:
+ *
+ *  - a missing launchable binary (a peer's interrupted build) refused only
+ *    after the wait, in every session, with nothing naming the cause;
+ *  - the named-file checkJs pass refused an `Element | null` after an
+ *    eighteen-minute queue;
+ *  - `--wait-browser` and `--wait-port` spent their budget holding the
+ *    lock, so every peer queued behind a run that was doing nothing.
+ *
+ * The in-lock ladder in `test.ts` still runs in full afterwards. That is
+ * the "re-check once under the lock": the waits this pass spent are
+ * stripped from the options it returns, so the in-lock browser and port
+ * checks probe once instead of waiting again.
+ */
+import { join } from 'node:path';
+import { describeBuildRunState, readBuildRunState } from '../core/build-run-record.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
+import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
+import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, extractForwardedMarionettePort, } from '../core/marionette-port.js';
+import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { waitBeforeLock } from '../core/preflight-wait.js';
+import { PreflightRefusalError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+import { stripEnginePrefix } from '../utils/paths.js';
+import { checkRequestedTestTypes } from './test-checkjs.js';
+import { assertPathlessTestMode, classifyBeforeDispatch, resolveCanaryPath } from './test-modes.js';
+/**
+ * Resolves the launchable binary a test run needs, or refuses naming why
+ * it is missing. The cause comes from the build run record, which any
+ * session's build writes, so a session that never ran the build can still
+ * say "a peer's build was interrupted" rather than only "the binary is
+ * missing".
+ *
+ * @param projectRoot - Project root
+ * @param engineDir - Absolute engine directory
+ * @param binaryName - Configured binary name
+ * @param objDir - Active objdir, when one exists
+ * @returns The engine-relative launchable path, or undefined without an objdir
+ */
+export async function resolveLaunchablePathForTests(projectRoot, engineDir, binaryName, objDir) {
+    if (!objDir)
+        return undefined;
+    const bundleCheck = await hasRunnableBundle(engineDir, binaryName, objDir);
+    if (bundleCheck.runnable)
+        return bundleCheck.expectedPath;
+    const expectedSuffix = bundleCheck.expectedPath
+        ? ` (expected at engine/${bundleCheck.expectedPath})`
+        : '';
+    const cause = describeBuildRunState(await readBuildRunState(projectRoot));
+    throw new PreflightRefusalError(`Tests require a complete launchable build${expectedSuffix}. ` +
+        'The obj-*/dist/ tree exists but the launchable binary is missing' +
+        (cause !== undefined
+            ? `.\n\n${cause}\n\n`
+            : ' — typically the result of an interrupted or partially failed `fireforge build`.\n\n') +
+        'Run "fireforge build" again and let it finish before retrying "fireforge test".', 'no-launchable-binary');
+}
+/** Build-artifact preflight wording for `fireforge test`. */
+export const TEST_BUILD_PREFLIGHT = {
+    label: 'Tests',
+    requirement: 'Tests require a completed build.',
+    remediation: "Run 'fireforge build' first, then run 'fireforge test'.",
+    requireExisting: true,
+};
+/**
+ * The head of the in-lock ladder, run early: argument shape, engine, build
+ * artifacts and config. Each refuses with exactly the message it gives
+ * under the lock. Returns undefined when there is no objdir to check
+ * further.
+ */
+async function loadPreLockContext(projectRoot, testPaths, options) {
+    assertPathlessTestMode(testPaths, options);
+    const paths = getProjectPaths(projectRoot);
+    await assertEngineExists(paths.engine);
+    const buildCheck = await hasBuildArtifacts(paths.engine);
+    assertBuildArtifacts(paths.engine, buildCheck, TEST_BUILD_PREFLIGHT);
+    const config = await loadConfig(projectRoot);
+    return buildCheck.objDir === undefined ? undefined : { paths, config, objDir: buildCheck.objDir };
+}
+/**
+ * Runs the lock-free checks and waits, and returns the options the in-lock
+ * run should use: with `waitBrowser`/`waitPort` removed when their budget
+ * was already spent here.
+ *
+ * @param projectRoot - Project root
+ * @param testPaths - Requested test paths
+ * @param options - Parsed test options
+ */
+export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
+    const context = await loadPreLockContext(projectRoot, testPaths, options);
+    if (context === undefined)
+        return options;
+    const { paths, config, objDir } = context;
+    let launchablePath;
+    try {
+        launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, config.binaryName, objDir);
+    }
+    catch (error) {
+        // A build in progress holds the engine lock and relinks the bundle
+        // before it lets go, so this run queues behind it rather than refusing.
+        if ((await readBuildRunState(projectRoot)).kind !== 'running')
+            throw error;
+        info('The launchable binary is missing while a build runs; queueing behind it.');
+    }
+    const canaryPath = resolveCanaryPath(options, config);
+    const normalizedPaths = (canaryPath !== undefined ? [canaryPath] : testPaths).map((path) => stripEnginePrefix(path).trim());
+    if (options.build === true || options.buildOnly === true) {
+        await checkRequestedTestTypes(paths, config, normalizedPaths);
+    }
+    return waitForResourcesBeforeLock(paths.engine, config, options, {
+        launchablePath,
+        normalizedPaths,
+    });
+}
+/** `options` without one wait budget, which this pass already spent. */
+function withoutOption(options, key) {
+    const rest = { ...options };
+    if (key === 'waitBrowser')
+        delete rest.waitBrowser;
+    else
+        delete rest.waitPort;
+    return rest;
+}
+/**
+ * Spends `--wait-browser` and `--wait-port` before the lock, mirroring
+ * which in-lock checks would apply to this run, and strips each budget it
+ * spent from the returned options.
+ */
+async function waitForResourcesBeforeLock(engineDir, config, options, request) {
+    if (options.waitBrowser === undefined && options.waitPort === undefined)
+        return options;
+    let xpcshellOnly;
+    try {
+        ({ xpcshellOnly } = await classifyBeforeDispatch(engineDir, request.normalizedPaths, {
+            allowMixed: true,
+        }));
+    }
+    catch {
+        return options;
+    }
+    const kill = options.killStaleMarionette === true;
+    let result = options;
+    const building = options.build === true || options.buildOnly === true;
+    if (options.waitBrowser !== undefined &&
+        request.launchablePath !== undefined &&
+        (building || !xpcshellOnly)) {
+        const binary = join(engineDir, request.launchablePath);
+        await waitBeforeLock(() => ensureLaunchableBrowserNotRunning(binary), resolveWaitLockSeconds(options.waitBrowser), 
+        // A stale browser the run may reap is not worth waiting out; the
+        // in-lock check terminates it.
+        kill ? ['stale-browser'] : []);
+        result = withoutOption(result, 'waitBrowser');
+    }
+    // Port waits stay under the lock with --kill-stale-marionette: a stale
+    // listener reads as busy until the in-lock pass reaps it, so waiting it
+    // out here would only burn the budget.
+    if (options.waitPort !== undefined && options.buildOnly !== true && !kill) {
+        const seconds = resolveWaitLockSeconds(options.waitPort);
+        if (!xpcshellOnly) {
+            await waitBeforeLock(() => ensureMochitestServerPortAvailable(undefined, { engineDir }), seconds);
+        }
+        if (!xpcshellOnly || options.doctor === true) {
+            const port = options.marionettePort ?? extractForwardedMarionettePort(options.machArg ?? []);
+            await waitBeforeLock(() => assertMarionettePortAvailable(port, { binaryName: config.binaryName }), seconds);
+        }
+        result = withoutOption(result, 'waitPort');
+    }
+    return result;
+}

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

@@ -26,12 +26,33 @@ const TEST_HELP_TEXT = [
     'not exercise cross-argument state; --no-shard restores the',
     'combined single-instance invocation.',
     '',
+    'Mixed xpcshell and browser/mochitest paths run as two consecutive',
+    'mach invocations (xpcshell first) under one lock hold and one',
+    'verdict; with --build, one pre-test build packages both halves.',
+    '--repeat <n> and --negative-control <diff> run under one lock hold',
+    'too. Each sub-run prints a FIREFORGE-RUN: line (its own verdict',
+    'plus run=<i>/<n>) before the single aggregate verdict.',
+    '',
+    'A dev objdir symlinks chrome JS/CSS and widget files into engine/,',
+    'so the browser reads engine/ sources when it loads them, after the',
+    'build step: an edit made while a suite runs reaches that suite, and',
+    'a hand-made neuter must stay until the verdict line, not until',
+    '"Build complete", since one restored early is gone for later',
+    'shards. --negative-control applies its diff after the build and',
+    'restores it byte-exact only after the run, before the lock is',
+    'released.',
+    '',
     'Machine-readable verdict: every run (single, sharded, --canary,',
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|harness-arguments|test-failures|',
     '  no-tests|preflight|inconclusive|lock-timeout|killed] [checks=<n>]',
-    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
-    '  [log=<path>]',
+    '  [unexpected=<n>] [started=<n>/<m> first-unstarted=<path>]',
+    '  [shards=<p>/<t>] [(<note>)] [shuffle=<seed>]',
+    '  [runs=<p>/<n>] [control=caught|missed|inconclusive]',
+    '  [furnace-applied=<names>|furnace-apply=skipped] [log=<path>]',
+    "control= is a negative control's outcome: caught (went red on test",
+    'failures, as a control should; exit 0), missed (stayed green; exit',
+    '5) or inconclusive.',
     'shuffle=<seed> is the seed a --shuffle run exported to the harness.',
     "log=<path> names this run's complete output, written to",
     '.fireforge/logs/ as the run streams, so a piped or truncated run',
@@ -39,7 +60,11 @@ const TEST_HELP_TEXT = [
     'The status follows the harness classifier, not the raw exit code:',
     'a crash-classified run says FAIL reason=crash even at exit 0, and',
     'a green-summary-override pass says PASS despite a non-zero mach',
-    'exit. reason=preflight covers any failure before the harness ran',
+    'exit. An exit-0 run is still FAIL reason=test-failures when its',
+    'summary reports unexpected results, the browser shut down mid-test,',
+    'or a requested file never started; started=/first-unstarted= then',
+    'name how far it got and where a re-run has to pick up.',
+    'reason=preflight covers any failure before the harness ran',
     '(missing/stale build, invalid paths, port conflicts, config',
     'errors); reason=inconclusive means engine/ or perf power source',
     'changed while tests ran, so the result cannot be trusted;',
@@ -56,13 +81,33 @@ const TEST_HELP_TEXT = [
     '"(headed run stalled with the display asleep)" marks a no-output',
     'stall whose display was measured asleep. Key on this line',
     'instead of mach internals.',
+    '',
+    'Lock-free checks run before the engine lock is requested: a missing',
+    'launchable binary (with the build that left it missing, when one is',
+    'recorded), the named-file checkJs pass of --build, and the',
+    '--wait-browser/--wait-port budgets. Each is re-checked once under the',
+    'lock.',
 ].join('\n');
+function registerTestMultiRunOptions(test) {
+    return test
+        .option('--repeat <n>', 'Run the same paths n times under one engine-lock hold (a --build builds once); prints each run and aggregates runs=<passed>/<n> on the verdict', commanderArgParser((raw) => parsePositiveIntegerFlag('--repeat', raw)))
+        .option('--negative-control <diff>', 'Apply this reviewed git diff (engine/ or components/ sources; project-relative path) after the pre-test build and right before dispatch, restore it byte-exact after the run (also on failure, SIGINT and SIGTERM) before the lock is released, and report control=caught|missed|inconclusive on the verdict')
+        .option('--auto-ports', "Let a browser run proceed when the mochitest server or Marionette port is held by something that is not this checkout's own: the engine's harness falls back to a free port itself. Same as test.mochitestPorts: \"auto\". This checkout's own leftovers are still refused.");
+}
 function registerTestSharingOptions(test) {
     return test
         .option('--wait-browser [seconds]', 'Wait for this objdir browser before any deployment/build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
         .option('--wait-port [seconds]', 'Wait for the mochitest and Marionette ports (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--restart-between-tests', "Forward mochitest's --restart-between-tests: restart the browser between test files to expose undocumented cross-file dependencies (the shape a manifest's standalone key asks for). Mochitest dispatch only.")
+        .option('--keep-log <path>', "Also write this run's log to <path> (a directory receives it under its own name), outside .fireforge/logs/ retention. FIREFORGE_LOG_KEEP sets a session default.")
         .option('--profile-file <source=destination>', 'Merge a file into the harness profile, e.g. sheet.css=chrome/userChrome.css. Repeatable.', ...stringListOption());
 }
+/** Pre-test build options that shape the coverage claim and the Furnace step. */
+function registerTestBuildOptions(test) {
+    return test
+        .option('--extend-coverage', 'With --build/--build-only and explicit paths, refuse instead of dropping any earlier packaging claim. Scoped builds keep each earlier path by default while its own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged; this flag turns a drop into a refusal before the build.')
+        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out');
+}
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
     const test = program
@@ -72,7 +117,6 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--full-output', "Pass mozbuild's full verbosity through for the TEST phase. mozbuild quiets terminal output to warnings and errors when it detects a coding agent, which removes TEST_START and console INFO — the lines a hang or stall diagnosis needs. This unsets that detection for test dispatches only; the build phase stays quiet.")
         .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')
@@ -83,7 +127,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('--shuffle [seed]', 'Shuffle isolated mochitest path arguments in a repeatable seeded order (fresh seed when omitted). Native mach --shuffle within each invocation remains unseeded. Export FIREFORGE_SHUFFLE_SEED for custom task code and stamp shuffle=<seed> on the verdict. --no-shard disables the seeded argument permutation. Write --shuffle=<seed> or place it after the paths.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', raw)))
+        .option('--shuffle [seed]', 'Shuffle isolated mochitest path arguments in a repeatable seeded order (fresh seed when omitted). Native mach --shuffle within each invocation remains unseeded. Export FIREFORGE_SHUFFLE_SEED for custom task code and stamp shuffle=<seed> on the verdict. --no-shard disables the seeded argument permutation. A path-shaped argument right after the flag (browser_x.js, dir/) is a test path, not a seed.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shuffle', 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) {
@@ -102,14 +146,14 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     }))
         .addHelpText('after', TEST_HELP_TEXT);
-    addWaitLockOption(registerTestSharingOptions(test)).action(withErrorHandling(async (paths, options) => {
+    addWaitLockOption(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test)))).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        // The engine session lock is acquired outside testCommand's own
-        // exactly-one-verdict guarantee, so a lock failure must emit here or
-        // the run ends with no FIREFORGE-VERDICT line at all.
+        // Fallback for a verdict testCommand did not emit (it takes the lock).
         resetVerdictEmission();
         try {
-            await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+            await testCommand(projectRoot, paths, pickDefined(options), (body) => withEngineSessionLock(projectRoot, 'test', body, {
+                waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+            }));
         }
         catch (error) {
             if (!verdictEmitted()) {

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

@@ -18,6 +18,7 @@ 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 { reportTestHost, sampleTestHost, stampPerfHost } from '../core/test-host-state.js';
+import { vetoIncompletePass } from '../core/test-run-completeness.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
 import { TestFailureError } from '../errors/build.js';
@@ -85,7 +86,9 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
             fullOutput: ctx.fullOutput,
         });
         const combined = `${result.stdout}\n${result.stderr}`;
-        verdict = classifyHarnessRun(result.exitCode, combined, paths);
+        // An exit-0 run is still not a pass when it stopped partway or
+        // reported unexpected results (see test-run-completeness.ts).
+        verdict = vetoIncompletePass(classifyHarnessRun(result.exitCode, combined, paths), combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)
             break;
         warn(`Harness crash detected (${verdict.signature?.reason ?? 'unknown shape'}): ` +

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

@@ -7,9 +7,12 @@
  * 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 { filterByCarriedFullCoverage } from '../core/coverage-dispatch.js';
+import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, FULL_SUITE_REQUEST, } from '../core/test-stale-check.js';
+import { formatStaleExemptions } from '../core/test-stale-exempt.js';
 import { PreflightRefusalError } from '../errors/base.js';
-import { warn } from '../utils/logger.js';
+import { info, warn } from '../utils/logger.js';
+import { describePerfStaleImpact } from './test-perf-scope.js';
 /**
  * Stale-build preflight: when `--build` was not requested, detect packageable
  * engine edits since the last successful build and fail up front unless the
@@ -34,34 +37,61 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);
     const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
     if (!dispatchesNoTests) {
-        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
-            // 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 enforceCoverageGate(engineDir, stale.baseline, normalizedPaths);
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
-    const staleMessage = stale.stale
-        ? `${formatStaleBuildWarning(stale)}\n\n` +
-            'Run `fireforge test --build` to refresh the packaged runtime first — that is almost ' +
-            'always the right move, because the usual cause is your own edit landing between the ' +
-            'last build and this run.\n\n' +
-            '`--allow-stale-build` is NOT the general escape hatch: it accepts a packaging that ' +
-            'predates the edit under test, so the run tests the OLD code. Pass it only when you ' +
-            'rebuilt out-of-band (outside FireForge) and know the packaged runtime already contains ' +
-            'the change.'
-        : undefined;
-    if (staleMessage !== undefined) {
-        if (options.allowStaleBuild === true) {
-            warn(staleMessage);
-        }
-        else {
-            throw new PreflightRefusalError(staleMessage, 'stale-build');
-        }
+    const exempt = stale.exempt ?? [];
+    if (!stale.stale && exempt.length > 0) {
+        info(`Stale-build preflight: ${exempt.length} edit(s) since the last build need no rebuild: ${formatStaleExemptions(exempt)}.`);
     }
+    if (!stale.stale)
+        return;
+    // The one-line repackaging command, so a build-less sitting (a perf
+    // series) can repackage and continue without dispatching anything.
+    const repackage = normalizedPaths.length > 0
+        ? `fireforge test --build-only ${normalizedPaths.join(' ')}`
+        : 'fireforge build --ui';
+    const perfImpact = options.perfSamples === undefined
+        ? ''
+        : `\n\n${await describePerfStaleImpact(engineDir, stale.changedPaths, normalizedPaths)}`;
+    const staleMessage = `${formatStaleBuildWarning(stale)}\n\n` +
+        'Run `fireforge test --build` to refresh the packaged runtime first — that is almost ' +
+        'always the right move, because the usual cause is your own edit landing between the ' +
+        'last build and this run. To repackage without running anything: ' +
+        `\`${repackage}\`.${perfImpact}\n\n` +
+        '`--allow-stale-build` is NOT the general escape hatch: it accepts a packaging that ' +
+        'predates the edit under test, so the run tests the OLD code. Pass it only when you ' +
+        'rebuilt out-of-band (outside FireForge) and know the packaged runtime already contains ' +
+        'the change.';
+    if (options.allowStaleBuild === true) {
+        warn(staleMessage);
+    }
+    else {
+        throw new PreflightRefusalError(staleMessage, 'stale-build');
+    }
+}
+/**
+ * Packaging-coverage refusal. A path outside the recorded scoped list is
+ * still covered while its own staging inputs are unchanged against a
+ * carried full-build anchor. The refusal names, per uncovered path, the
+ * inputs that changed.
+ */
+async function enforceCoverageGate(engineDir, baseline, normalizedPaths) {
+    const recordedCoverage = baseline?.testPackagingCoverage;
+    const outsideList = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
+    if (outsideList.length === 0)
+        return;
+    const remaining = await filterByCarriedFullCoverage(engineDir, baseline, outsideList, FULL_SUITE_REQUEST);
+    if (remaining.length === 0)
+        return;
+    const uncovered = remaining.map((request) => request.path);
+    // 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, baseline, uncovered);
+    throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests, {
+        changedInputs: Object.fromEntries(remaining.map((request) => [request.path, request.changed])),
+        carriesFullAnchor: baseline?.fullCoverageAnchor !== undefined,
+    }), 'coverage-replaced');
 }
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would

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

@@ -13,7 +13,7 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  */
 export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
 /** Additive keys a run can stamp on its verdict line. */
-export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**
@@ -30,6 +30,15 @@ export declare function addVerdictRunCount(key: 'orphans-reaped', count: number)
 export declare function resetVerdictEmission(): void;
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
 export declare function verdictEmitted(): boolean;
+/** Installs (or, with `undefined`, removes) the sub-run capture slot. */
+export declare function setVerdictCapture(slot: {
+    line?: string;
+} | undefined): void;
+/**
+ * Emits a multi-run aggregate verdict. `body` is everything after the
+ * `FIREFORGE-VERDICT: ` prefix.
+ */
+export declare function emitAggregateVerdict(body: string): void;
 /**
  * Emits the classifier-derived verdict for a completed harness run, with
  * the aggregate `shards=<passed>/<total>` suffix for sharded runs.

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

@@ -51,11 +51,31 @@ export function resetVerdictEmission() {
     emitted = false;
     armed = true;
     runAttributes.clear();
+    capture = undefined;
     setStdoutSealed(false);
 }
+/**
+ * The sub-run capture slot of a multi-run invocation (`--repeat`, mixed
+ * harnesses, `--negative-control`; see `test-orchestrate.ts`). While one is
+ * installed, a sub-run's verdict line is recorded here, first write wins as
+ * on stdout, and nothing is printed or sealed, so the invocation can still
+ * end with its own single aggregate line.
+ */
+let capture;
 /** True once this run has written its `FIREFORGE-VERDICT:` line. */
 export function verdictEmitted() {
-    return emitted;
+    return capture === undefined ? emitted : capture.line !== undefined;
+}
+/** Installs (or, with `undefined`, removes) the sub-run capture slot. */
+export function setVerdictCapture(slot) {
+    capture = slot;
+}
+/**
+ * Emits a multi-run aggregate verdict. `body` is everything after the
+ * `FIREFORGE-VERDICT: ` prefix.
+ */
+export function emitAggregateVerdict(body) {
+    writeVerdictLine(`FIREFORGE-VERDICT: ${body}`);
 }
 /**
  * Writes the run's single verdict line to raw stdout (clack's renderer can
@@ -68,6 +88,10 @@ export function verdictEmitted() {
  * rendering after an emit-then-throw path, routes to stderr.
  */
 function writeVerdictLine(line) {
+    if (capture !== undefined) {
+        capture.line ??= line;
+        return;
+    }
     if (emitted)
         return;
     emitted = true;
@@ -130,6 +154,9 @@ export function emitFailVerdict(reason, note) {
 export function emitKilledVerdict(signal) {
     if (!armed || emitted)
         return false;
+    // A kill ends the whole invocation, so a sub-run capture must not
+    // swallow the one line that says so.
+    capture = undefined;
     writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=killed signal=${signal}`);
     return true;
 }

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

@@ -10,8 +10,13 @@ import type { TestOptions } from '../types/commands/index.js';
  * 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.
+ * The lock-free checks (launchable binary, named-file checkJs, the
+ * `--wait-browser`/`--wait-port` budgets) run first, outside `underLock`,
+ * so a run that would be refused or would only wait never holds a place in
+ * the engine lock queue. See `test-prelock.ts`.
  * @param projectRoot - Root directory of the project
  * @param testPaths - Test file or directory paths
  * @param options - Test options
+ * @param underLock - Runs the rest of the command under the engine session lock
  */
-export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions): Promise<void>;
+export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions, underLock?: (body: () => Promise<void>) => Promise<void>): Promise<void>;