@hominis/fireforge 0.52.0 → 0.54.0

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

@@ -1,7 +1,9 @@
 import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
 /**
  * Reason codes the emission layer can put on a `FIREFORGE-VERDICT: FAIL`
- * line. The first three mirror the harness classifier. `preflight` covers
+ * line. The first three mirror the harness classifier, as does
+ * `server-startup`: a harness-crash-class infrastructure failure where a
+ * mochitest server never came up, so no test ran. `preflight` covers
  * every failure before harness classification (missing/stale builds,
  * invalid paths, port conflicts, config errors, spawn failures),
  * `inconclusive` marks a run whose harness result exists but cannot be
@@ -11,9 +13,9 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * and `killed` marks a run terminated by a signal before it could reach any
  * of the others.
  */
-export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
+export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'server-startup' | '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' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'drift-tolerated' | 'lock' | 'jobs' | 'results';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'control-restore-build' | 'build-id' | 'drift-tolerated' | 'lock' | 'jobs' | 'upload-dirs' | 'results';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**

package/dist/src/commands/test.js

@@ -2,6 +2,7 @@
 import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
+import { readBuildId } from '../core/launchable-build.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
@@ -24,7 +25,7 @@ import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-
 import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, resolveCanaryPath, restartBetweenTestsArgs, } from './test-modes.js';
 import { orchestrateTestRuns } from './test-orchestrate.js';
-import { resolveLaunchablePathForTests, runTestPreLockPreflight, TEST_BUILD_PREFLIGHT, } from './test-prelock.js';
+import { rearmSpentWaits, resolveLaunchablePathForTests, runTestPreLockPreflight, TEST_BUILD_PREFLIGHT, } from './test-prelock.js';
 import { resetTestResults, withRawLogDir, writeTestResults } from './test-results.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
 import { emitFailVerdict, resetVerdictEmission, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
@@ -349,10 +350,21 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
         classification,
         normalizedPaths: hooks.coveragePaths ?? normalizedPaths,
         ...(hooks.fullBuildReason === undefined ? {} : { fullBuildReason: hooks.fullBuildReason }),
+        ...(hooks.controlBuild === undefined ? {} : { controlBuild: hooks.controlBuild }),
+        launchablePath,
     })) {
         return;
     }
-    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig, options, buildCheck.objDir);
+    // Which binary this run exercises, read after the pre-test build so it
+    // names the build the tests actually ran against (`moz:buildID`).
+    if (launchablePath !== undefined) {
+        const buildId = await readBuildId(paths.engine, launchablePath);
+        if (buildId !== undefined)
+            setVerdictRunAttribute('build-id', buildId);
+    }
+    // After a pre-test build, a busy browser or port is a peer that started
+    // during it; waiting it out keeps the build this run just paid for.
+    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig, options.build === true ? rearmSpentWaits(options) : options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,

package/dist/src/commands/token.js

@@ -42,8 +42,8 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
  *
  * A variant skip has no category to name, because the declaration lives in
  * a `:root<selector>` block, so the location reads as that block. The
- * variant path used to report no location at all, so a re-run meant to
- * change a value exited 0 having silently changed nothing.
+ * location matters: without it a re-run meant to change a value exits 0
+ * having silently changed nothing.
  *
  * @param tokenName - Full token name including prefix
  * @param result - Result carrying the skip location, when known

package/dist/src/commands/verify.js

@@ -328,7 +328,7 @@ export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('verify')
         .description('Read-only fsck for the patch queue (manifest + cross-patch lint)')
-        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Queue-wide findings stay; unowned worktree changes drop out')
+        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Queue-wide findings stay; unowned worktree changes drop out')
         .action(withErrorHandling(async (options) => {
         await verifyCommand(getProjectRoot(), options);
     }));

package/dist/src/commands/watch.js

@@ -195,7 +195,7 @@ export async function watchCommand(projectRoot) {
     catch (error) {
         throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
     }
-    // On Ctrl+C the bin signal handler now waits for the mach child to shut
+    // On Ctrl+C the bin signal handler waits for the mach child to shut
     // down (waitForActiveChildShutdown) before exiting, so this continuation
     // can run and whitelist the SIGINT exit code, though the bin may still
     // win the race and terminate first. Both outcomes are acceptable.

package/dist/src/commands/wire.js

@@ -208,7 +208,7 @@ function buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscrip
     };
 }
 /**
- * Surfaces any legacy parser fallbacks the wiring run consumed, so the
+ * Surfaces any regex parser fallbacks the wiring run consumed, so the
  * operator knows which files were mutated by the regex path rather than
  * the AST path.
  */

package/dist/src/core/build-audit-resolve.d.ts

@@ -29,11 +29,10 @@ export declare function countTrailingSegmentMatches(a: string, b: string): numbe
  *
  * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
- * `build-audit.ts`). When the halves kept separate copies they disagreed,
- * so a source path could earn a selection bonus for a segment that
- * confirmation then rejected as meaningless, leaving the chosen artifact
- * unconfirmable. Any addition must apply to both halves, which is now
- * automatic.
+ * `build-audit.ts`). Separate copies would disagree, so a source path
+ * could earn a selection bonus for a segment that confirmation then
+ * rejected as meaningless, leaving the chosen artifact unconfirmable. One
+ * set makes every addition apply to both halves.
  */
 export declare const GENERIC_PATH_SEGMENTS: ReadonlySet<string>;
 /**

package/dist/src/core/build-audit-resolve.js

@@ -96,11 +96,10 @@ export function countTrailingSegmentMatches(a, b) {
  *
  * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
- * `build-audit.ts`). When the halves kept separate copies they disagreed,
- * so a source path could earn a selection bonus for a segment that
- * confirmation then rejected as meaningless, leaving the chosen artifact
- * unconfirmable. Any addition must apply to both halves, which is now
- * automatic.
+ * `build-audit.ts`). Separate copies would disagree, so a source path
+ * could earn a selection bonus for a segment that confirmation then
+ * rejected as meaningless, leaving the chosen artifact unconfirmable. One
+ * set makes every addition apply to both halves.
  */
 export const GENERIC_PATH_SEGMENTS = new Set([
     'content',

package/dist/src/core/build-audit-skip.d.ts

@@ -1,8 +1,8 @@
 /**
  * Why a changed engine path was not audited.
  *
- * The first four name skips that already existed as unstructured
- * `verbose()` strings. The last four are the 0.46.0 classifiers.
+ * Each reason is structured so summaries and machine output can count
+ * skips by cause instead of reading verbose log strings.
  */
 export type AuditSkipReason = 'not-packageable' | 'platform-gated' | 'platform-gated-ancestor' | 'tests-not-packaged' | 'source-unreadable' | 'branding-not-selected' | 'storybook-story' | 'declared-unpackaged';
 /** Render order for the `Packaged:` summary's per-class breakdown. */

package/dist/src/core/build-audit.d.ts

@@ -40,10 +40,9 @@ export interface AuditEntry {
     status: 'updated' | 'stale' | 'missing' | 'skipped';
     /**
      * Why a `skipped` entry was skipped. Present only for `skipped`. The
-     * reasons used to exist only as verbose log strings, so the summary line
-     * could report `4 missing` on a run with zero real misses and nothing in
-     * the counts distinguished a structural non-input from an unregistered
-     * file an operator must act on.
+     * reason lets the counts distinguish a structural non-input from an
+     * unregistered file an operator must act on, so the summary line never
+     * reports skips as misses.
      */
     skipReason?: AuditSkipReason;
 }

package/dist/src/core/build-baseline-types.d.ts

@@ -93,10 +93,11 @@ export interface BuildBaseline {
      * mozconfig and complete testInputFingerprints outside the rebuilt scope
      * remain anchored. Explicitly rebuilt paths may change. A failed anchor
      * replaces coverage with a dropped-path notice, or refuses when the caller
-     * required --extend-coverage. Legacy packageable-only anchors cannot retain
-     * coverage because they cannot prove test scripts and fixtures unchanged.
+     * required --extend-coverage. Anchors that fingerprint only packageable
+     * inputs cannot retain coverage because they cannot prove test scripts and
+     * fixtures unchanged.
      *
-     * Since 0.50.0 retention is decided per staged path: see
+     * Retention is decided per staged path: see
      * {@link BuildBaseline.testCoverageRecords} and
      * {@link BuildBaseline.fullCoverageAnchor}.
      */
@@ -151,6 +152,26 @@ export interface BuildBaseline {
      * session's scoped build replaced can tell whose build that was.
      */
     recorder?: BaselineRecorder;
+    /**
+     * Set when this build compiled a negative control into the binary
+     * (`test --negative-control --build` on compiled source). The source is
+     * restored byte-exact after the run, but the objdir binary keeps the
+     * mutation until a build recompiles it. FireForge runs that restore build
+     * itself, inside the same lock hold, and its baseline drops the stamp.
+     * A stamp still present (the run was killed, or the restore build
+     * failed) makes the next `fireforge test` refuse with `control-built`
+     * until `fireforge build` replaces the baseline.
+     */
+    controlBuild?: ControlBuildStamp;
+}
+/** See {@link BuildBaseline.controlBuild}. */
+export interface ControlBuildStamp {
+    /** The `--negative-control` diff file, as given. */
+    diffFile: string;
+    /** Engine-relative compiled targets the control edited. */
+    targets: string[];
+    /** ISO-8601 time the control was applied. */
+    appliedAt: string;
 }
 /** See {@link BuildBaseline.recorder}. */
 export interface BaselineRecorder {

package/dist/src/core/build-baseline-validate.d.ts

@@ -1,3 +1,32 @@
 import { type BuildBaseline } from './build-baseline-types.js';
-/** Validates persisted fields without converting malformed coverage into a full claim. */
+/**
+ * The first field of a persisted baseline that fails validation, and the
+ * offending value: what a refusal names so the operator can tell a scoped
+ * coverage claim from a corrupt marker.
+ */
+export interface BuildBaselineProblem {
+    /** Field path, e.g. `testPackagingCoverage[2]` or `testCoverageRecords["a/"]`. */
+    field: string;
+    /** The offending value, as found (may be any JSON value). */
+    value: unknown;
+}
+/** True when the problem sits in a packaging-coverage field. */
+export declare function isCoverageProblem(problem: BuildBaselineProblem): boolean;
+/** Renders a problem for a refusal: the field and a bounded JSON rendering of its value. */
+export declare function describeBuildBaselineProblem(problem: BuildBaselineProblem): string;
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim, and returns the first failing field with its value, or
+ * undefined when the baseline is valid.
+ *
+ * @param value - The parsed `last-build.json`
+ */
+export declare function findBuildBaselineProblem(value: unknown): BuildBaselineProblem | undefined;
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim. The boolean form of {@link findBuildBaselineProblem}.
+ *
+ * @internal Exported only so tests can reach it. Production reads go
+ * through `findBuildBaselineProblem`, which names the failing field.
+ */
 export declare function isBuildBaseline(value: unknown): value is BuildBaseline;

package/dist/src/core/build-baseline-validate.js

@@ -24,13 +24,14 @@ function isCoverageAnchor(value) {
         isFingerprint(value['mozconfigHash']) &&
         isFingerprintMap(value['fingerprints']));
 }
-function isCoverageRecordMap(value) {
+/** A `controlBuild` stamp: the control's diff file, its targets and when it went in. */
+function isControlBuildStamp(value) {
     return (isObject(value) &&
-        Object.entries(value).every(([path, record]) => isBaselinePath(path) &&
-            isCoverageAnchor(record) &&
-            isObject(record) &&
-            Array.isArray(record['inputs']) &&
-            record['inputs'].every(isBaselinePath)));
+        typeof value['diffFile'] === 'string' &&
+        Array.isArray(value['targets']) &&
+        value['targets'].every(isBaselinePath) &&
+        typeof value['appliedAt'] === 'string' &&
+        Number.isFinite(Date.parse(value['appliedAt'])));
 }
 /** A `recorder` stamp: an integer pid, an invocation id and an optional session id. */
 function isBaselineRecorder(value) {
@@ -39,43 +40,134 @@ function isBaselineRecorder(value) {
         typeof value['invocationId'] === 'string' &&
         (value['sessionId'] === undefined || typeof value['sessionId'] === 'string'));
 }
-/** Validates persisted fields without converting malformed coverage into a full claim. */
-export function isBuildBaseline(value) {
+/** Fields whose problem a scoped `test --build` can leave and a fresh one replaces. */
+const COVERAGE_FIELDS = ['testPackagingCoverage', 'testCoverageRecords', 'fullCoverageAnchor'];
+/** True when the problem sits in a packaging-coverage field. */
+export function isCoverageProblem(problem) {
+    return COVERAGE_FIELDS.some((field) => problem.field === field ||
+        problem.field.startsWith(`${field}[`) ||
+        problem.field.startsWith(`${field}.`));
+}
+/** Renders a problem for a refusal: the field and a bounded JSON rendering of its value. */
+export function describeBuildBaselineProblem(problem) {
+    let rendered;
+    try {
+        // JSON.stringify(undefined) returns undefined at runtime despite its type.
+        const json = JSON.stringify(problem.value);
+        rendered = json ?? 'undefined';
+    }
+    catch {
+        rendered = String(problem.value);
+    }
+    if (rendered.length > 120)
+        rendered = `${rendered.slice(0, 117)}...`;
+    return `${problem.field} = ${rendered}`;
+}
+function findFingerprintMapProblem(field, value) {
+    if (!isObject(value))
+        return { field, value };
+    for (const [path, fingerprint] of Object.entries(value)) {
+        if (!isBaselinePath(path))
+            return { field: `${field}[${JSON.stringify(path)}]`, value: path };
+        if (!isFingerprint(fingerprint)) {
+            return { field: `${field}[${JSON.stringify(path)}]`, value: fingerprint };
+        }
+    }
+    return undefined;
+}
+function findCoverageRecordProblem(value) {
+    const field = 'testCoverageRecords';
+    if (!isObject(value))
+        return { field, value };
+    for (const [path, record] of Object.entries(value)) {
+        const entry = `${field}[${JSON.stringify(path)}]`;
+        if (!isBaselinePath(path))
+            return { field: entry, value: path };
+        if (!isCoverageAnchor(record) || !isObject(record) || !Array.isArray(record['inputs'])) {
+            return { field: entry, value: record };
+        }
+        const inputs = record['inputs'];
+        const input = inputs.find((item) => !isBaselinePath(item));
+        if (input !== undefined)
+            return { field: `${entry}.inputs`, value: input };
+    }
+    return undefined;
+}
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim, and returns the first failing field with its value, or
+ * undefined when the baseline is valid.
+ *
+ * @param value - The parsed `last-build.json`
+ */
+export function findBuildBaselineProblem(value) {
     if (!isObject(value))
-        return false;
-    if (typeof value['engineHeadSha'] !== 'string' ||
-        typeof value['builtAt'] !== 'string' ||
-        !Number.isFinite(Date.parse(value['builtAt'])) ||
-        typeof value['binaryName'] !== 'string' ||
-        !/^[a-z][a-z0-9-]*$/.test(value['binaryName']))
-        return false;
+        return { field: '(root)', value };
+    if (typeof value['engineHeadSha'] !== 'string') {
+        return { field: 'engineHeadSha', value: value['engineHeadSha'] };
+    }
+    if (typeof value['builtAt'] !== 'string' || !Number.isFinite(Date.parse(value['builtAt']))) {
+        return { field: 'builtAt', value: value['builtAt'] };
+    }
+    if (typeof value['binaryName'] !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value['binaryName'])) {
+        return { field: 'binaryName', value: value['binaryName'] };
+    }
     for (const field of [
         'packageableFingerprints',
         'testInputFingerprints',
         'buildInputFingerprints',
     ]) {
-        if (value[field] !== undefined && !isFingerprintMap(value[field]))
-            return false;
+        if (value[field] === undefined)
+            continue;
+        const problem = findFingerprintMapProblem(field, value[field]);
+        if (problem !== undefined)
+            return problem;
     }
     const coverage = value['testPackagingCoverage'];
-    if (coverage !== undefined &&
-        coverage !== 'full' &&
-        !(Array.isArray(coverage) && coverage.every(isBaselinePath)))
-        return false;
-    if (value['mozconfigHash'] !== undefined && !isFingerprint(value['mozconfigHash']))
-        return false;
-    if (value['recordedBy'] !== undefined && typeof value['recordedBy'] !== 'string')
-        return false;
-    if (value['recorder'] !== undefined && !isBaselineRecorder(value['recorder']))
-        return false;
-    if (value['testCoverageRecords'] !== undefined &&
-        !isCoverageRecordMap(value['testCoverageRecords']))
-        return false;
-    if (value['fullCoverageAnchor'] !== undefined && !isCoverageAnchor(value['fullCoverageAnchor']))
-        return false;
+    if (coverage !== undefined && coverage !== 'full') {
+        if (!Array.isArray(coverage))
+            return { field: 'testPackagingCoverage', value: coverage };
+        const index = coverage.findIndex((path) => !isBaselinePath(path));
+        if (index >= 0) {
+            return { field: `testPackagingCoverage[${index}]`, value: coverage[index] };
+        }
+    }
+    if (value['mozconfigHash'] !== undefined && !isFingerprint(value['mozconfigHash'])) {
+        return { field: 'mozconfigHash', value: value['mozconfigHash'] };
+    }
+    if (value['recordedBy'] !== undefined && typeof value['recordedBy'] !== 'string') {
+        return { field: 'recordedBy', value: value['recordedBy'] };
+    }
+    if (value['recorder'] !== undefined && !isBaselineRecorder(value['recorder'])) {
+        return { field: 'recorder', value: value['recorder'] };
+    }
+    if (value['testCoverageRecords'] !== undefined) {
+        const problem = findCoverageRecordProblem(value['testCoverageRecords']);
+        if (problem !== undefined)
+            return problem;
+    }
+    if (value['fullCoverageAnchor'] !== undefined && !isCoverageAnchor(value['fullCoverageAnchor'])) {
+        return { field: 'fullCoverageAnchor', value: value['fullCoverageAnchor'] };
+    }
     const components = value['staticComponentsBaseline'];
-    return (components === undefined ||
-        (isObject(components) &&
+    if (components !== undefined &&
+        !(isObject(components) &&
             typeof components['engineHeadSha'] === 'string' &&
-            isFingerprintMap(components['fingerprints'])));
+            isFingerprintMap(components['fingerprints']))) {
+        return { field: 'staticComponentsBaseline', value: components };
+    }
+    if (value['controlBuild'] !== undefined && !isControlBuildStamp(value['controlBuild'])) {
+        return { field: 'controlBuild', value: value['controlBuild'] };
+    }
+    return undefined;
+}
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim. The boolean form of {@link findBuildBaselineProblem}.
+ *
+ * @internal Exported only so tests can reach it. Production reads go
+ * through `findBuildBaselineProblem`, which names the failing field.
+ */
+export function isBuildBaseline(value) {
+    return findBuildBaselineProblem(value) === undefined;
 }

package/dist/src/core/build-baseline.d.ts

@@ -15,7 +15,7 @@
  * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import { type BuildBaseline, type CoverageAnchor, type CoverageRecord, type TestPackagingCoverage } from './build-baseline-types.js';
+import { type BuildBaseline, type ControlBuildStamp, type CoverageAnchor, type CoverageRecord, type TestPackagingCoverage } from './build-baseline-types.js';
 /**
  * Which mach build produced the baseline being written. Decides whether
  * the `jar.mn` half of {@link BuildBaseline.buildInputFingerprints} is
@@ -35,7 +35,7 @@ export declare function getBuildBaselinePath(projectRoot: string): string;
  * Reads the last-build baseline if present. Returns undefined when no
  * previous successful build has been recorded. Builds can replace invalid
  * markers; dispatch preflights pass `refuse` so invalid coverage never
- * becomes the legacy implicit full claim.
+ * becomes the implicit full claim of a baseline without coverage.
  * @param projectRoot - Root directory of the project
  */
 export declare function readBuildBaseline(projectRoot: string, invalid?: 'ignore' | 'refuse'): Promise<BuildBaseline | undefined>;
@@ -85,6 +85,12 @@ export interface WriteBuildBaselineOptions {
      * escalation no full build has honoured.
      */
     buildKind?: BaselineBuildKind | undefined;
+    /**
+     * Stamp for a build that compiled a negative control into the binary.
+     * Omitted → field left off, which is how every other build clears it.
+     * See {@link BuildBaseline.controlBuild}.
+     */
+    controlBuild?: ControlBuildStamp | undefined;
 }
 /**
  * Records a successful build by writing a fresh baseline marker. Captures

package/dist/src/core/build-baseline.js

@@ -26,12 +26,11 @@ import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { isBuildInputPath, isJarManifestPath, isPackageablePath, isXpcomManifestPath, } from './build-audit.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
-import { isBuildBaseline } from './build-baseline-validate.js';
+import { describeBuildBaselineProblem, findBuildBaselineProblem, isCoverageProblem, } from './build-baseline-validate.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { getHead, hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
 import { historyRecordIdentity } from './history-log-file.js';
 /*
  * Keep the IO fan-out bounded: a patched Firefox checkout can carry hundreds
@@ -52,22 +51,31 @@ export function getBuildBaselinePath(projectRoot) {
  * Reads the last-build baseline if present. Returns undefined when no
  * previous successful build has been recorded. Builds can replace invalid
  * markers; dispatch preflights pass `refuse` so invalid coverage never
- * becomes the legacy implicit full claim.
+ * becomes the implicit full claim of a baseline without coverage.
  * @param projectRoot - Root directory of the project
  */
 export async function readBuildBaseline(projectRoot, invalid = 'ignore') {
     const path = getBuildBaselinePath(projectRoot);
+    let problem;
     try {
         const value = await readJson(path);
-        if (!isBuildBaseline(value))
-            throw new Error('invalid baseline fields');
+        problem = findBuildBaselineProblem(value);
+        if (problem !== undefined) {
+            throw new Error(`invalid baseline field ${describeBuildBaselineProblem(problem)}`);
+        }
         return value;
     }
     catch (error) {
         if (getNodeErrorCode(error) === 'ENOENT')
             return undefined;
         if (invalid === 'refuse') {
-            throw new PreflightRefusalError(`Build baseline ${path} is invalid: ${toError(error).message}. Run "fireforge build" to record a fresh baseline before dispatching tests.`, 'invalid-build-baseline');
+            // A coverage field is what a scoped `test --build` writes, so a fresh
+            // scoped build over the requested paths replaces it as well as a full
+            // one does.
+            const remedy = problem !== undefined && isCoverageProblem(problem)
+                ? 'The field is part of the packaging-coverage claim a scoped "fireforge test --build" records. Rerun this test with --build to record a fresh claim for its paths, or run "fireforge build" to record a full baseline.'
+                : 'Run "fireforge build" to record a fresh baseline before dispatching tests.';
+            throw new PreflightRefusalError(`Build baseline ${path} is invalid: ${toError(error).message}. ${remedy}`, 'invalid-build-baseline');
         }
         verbose(`Ignoring invalid build baseline ${path}: ${toError(error).message}`);
         return undefined;
@@ -87,7 +95,7 @@ function baselineRecorder() {
  * @param options - See {@link WriteBuildBaselineOptions}
  */
 export async function writeBuildBaseline(options) {
-    const { projectRoot, engineDir, binaryName, testPackagingCoverage, testCoverageRecords, fullCoverageAnchor, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', } = options;
+    const { projectRoot, engineDir, binaryName, testPackagingCoverage, testCoverageRecords, fullCoverageAnchor, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', controlBuild, } = options;
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -104,7 +112,7 @@ export async function writeBuildBaseline(options) {
     const packageableFingerprints = await collectPackageableFingerprints(engineDir);
     const testInputFingerprints = await collectDirtyFingerprints(engineDir, () => true, 'test staging fingerprint');
     const buildInputFingerprints = await collectBuildInputFingerprints(engineDir, previousBaseline, buildKind);
-    // A full-coverage write (and the legacy no-claim `fireforge build` shape)
+    // A full-coverage write (and a no-claim `fireforge build` record)
     // just recompiled the StaticComponents table, so it anchors the table to
     // the current engine state. A scoped write did not, so carry the previous
     // anchor forward verbatim.
@@ -128,6 +136,7 @@ export async function writeBuildBaseline(options) {
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
         ...(recordedBy !== undefined ? { recordedBy } : {}),
         recorder: baselineRecorder(),
+        ...(controlBuild !== undefined ? { controlBuild } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
@@ -202,14 +211,14 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
     try {
         const dirtyPaths = new Set();
         if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    dirtyPaths.add(trimmed);
-            }
-            for (const untracked of await getUntrackedFiles(engineDir)) {
-                dirtyPaths.add(untracked);
+            // NUL-separated and unquoted: git's default output backslash-quotes a
+            // non-ASCII path (`"a/\303\251.js"`), which is neither the file on
+            // disk nor a key the baseline validator accepts.
+            const worktreeDiff = await git(['-c', 'core.quotePath=false', 'diff', '--name-only', '-z', 'HEAD'], engineDir);
+            const untracked = await git(['-c', 'core.quotePath=false', 'ls-files', '--others', '--exclude-standard', '-z'], engineDir);
+            for (const path of `${worktreeDiff}\0${untracked}`.split('\0')) {
+                if (path.length > 0)
+                    dirtyPaths.add(path);
             }
         }
         const included = [...dirtyPaths].filter(includePath);

package/dist/src/core/build-jar-escalation.d.ts

@@ -2,10 +2,10 @@
  * Decides whether a changed `jar.mn` really forces the pre-test build to
  * escalate from `mach build faster` to a full `mach build`.
  *
- * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
- * minutes against ~20 s for a chrome-only slice and is paid twice per
- * green/no-change pair on a Furnace-touching slice. A downstream experiment
- * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
+ * Escalating on every changed jar.mn (`any changed jar.mn ⇒ full build`)
+ * costs ~10 minutes against ~20 s for a chrome-only slice and is paid twice
+ * per green/no-change pair on a Furnace-touching slice. A downstream
+ * experiment (two clean runs, 2026-08-29) showed that rule is over-broad
  * for the common case: a jar-only registration of a new content file added
  * to an existing `dist/bin` manifest was installed by a plain
  * `fireforge build --ui` both times: `faster/install_dist_bin_browser` named

package/dist/src/core/build-jar-escalation.js

@@ -3,10 +3,10 @@
  * Decides whether a changed `jar.mn` really forces the pre-test build to
  * escalate from `mach build faster` to a full `mach build`.
  *
- * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
- * minutes against ~20 s for a chrome-only slice and is paid twice per
- * green/no-change pair on a Furnace-touching slice. A downstream experiment
- * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
+ * Escalating on every changed jar.mn (`any changed jar.mn ⇒ full build`)
+ * costs ~10 minutes against ~20 s for a chrome-only slice and is paid twice
+ * per green/no-change pair on a Furnace-touching slice. A downstream
+ * experiment (two clean runs, 2026-08-29) showed that rule is over-broad
  * for the common case: a jar-only registration of a new content file added
  * to an existing `dist/bin` manifest was installed by a plain
  * `fireforge build --ui` both times: `faster/install_dist_bin_browser` named

package/dist/src/core/build-prepare.js

@@ -122,7 +122,7 @@ async function decideJarEscalation(engineDir, changed) {
     // build. Path-shape only: `evaluateJarManifestEscalation` decides whether a
     // given changed manifest actually forces one (a new manifest, or one that
     // redirects its install base directory), so an entry added to an existing
-    // `dist/bin` manifest no longer costs a ~10-minute build.
+    // `dist/bin` manifest does not cost a ~10-minute build.
     const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath));
     if (decision.cleared.length > 0) {
         verbose(`jar escalation: ${decision.cleared.length} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
@@ -241,9 +241,9 @@ async function applyFurnaceBeforeBuild(projectRoot, only) {
     }
     // The apply computed these (patch-owned engine files whose content
     // differed from components/ and were replaced). `furnace apply`
-    // prints them; this path used to drop them, so a negative control
-    // that edited a deployed Furnace file ran against the shipped code
-    // with a green result and only a checksum could tell.
+    // prints them, and so does this path: dropped silently, a negative
+    // control that edited a deployed Furnace file would run against the
+    // shipped code with a green result and only a checksum could tell.
     const overwriteCount = logApplyWarnings(result.warnings);
     if (overwriteCount > 0) {
         notice(`Furnace: ${overwriteCount} Furnace-managed engine file${overwriteCount === 1 ? '' : 's'} differed from components/ and ${overwriteCount === 1 ? 'was' : 'were'} REPLACED before this build. An engine-side edit to a Furnace-managed file (for example a negative control) did not run; edit the component source under components/ instead, or restore the edit after the build.`);