@hominis/fireforge 0.51.0 → 0.53.0

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,12 @@ 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
  * of dirty packageable paths and serial reads add directly to every build.
@@ -51,27 +51,41 @@ 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;
     }
 }
+/** This process's {@link BuildBaseline.recorder} stamp. */
+function baselineRecorder() {
+    const { pid, invocationId, sessionId } = historyRecordIdentity();
+    return { pid, invocationId, ...(sessionId !== undefined ? { sessionId } : {}) };
+}
 /**
  * Records a successful build by writing a fresh baseline marker. Captures
  * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
@@ -81,7 +95,7 @@ export async function readBuildBaseline(projectRoot, invalid = 'ignore') {
  * @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);
@@ -98,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.
@@ -121,6 +135,8 @@ export async function writeBuildBaseline(options) {
         ...(mozconfigHash !== undefined ? { mozconfigHash } : {}),
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
         ...(recordedBy !== undefined ? { recordedBy } : {}),
+        recorder: baselineRecorder(),
+        ...(controlBuild !== undefined ? { controlBuild } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
@@ -195,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.`);

package/dist/src/core/config-validate.js

@@ -74,10 +74,10 @@ function parseFirefoxBlock(rec) {
         throw new ConfigError('Config field "firefox.version" must be a valid Firefox version (e.g., "145.0")');
     }
     const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
-    // Uses the shared guard rather than a fourth copy of the member list. This
-    // is the fireforge.json read path: a product added to the union but not to
-    // the copy that used to live here would have been silently rejected from
-    // every project config.
+    // Uses the shared guard rather than a separate copy of the member list.
+    // This is the fireforge.json read path: a product added to the union but
+    // not to a local copy would be silently rejected from every project
+    // config.
     if (!isValidFirefoxProduct(firefoxProduct)) {
         throw new ConfigError(`Config field "firefox.product" must be one of: ${FIREFOX_PRODUCTS.join(', ')}`);
     }

package/dist/src/core/coverage-extend.d.ts

@@ -7,7 +7,7 @@
  * collapsing to this build's paths. `--extend-coverage` turns any drop into
  * a refusal before the build.
  *
- * Fingerprints must be complete: a legacy packageable-only record cannot
+ * Fingerprints must be complete: a record of packageable inputs only cannot
  * prove that a test fixture or manifest still matches its staged copy.
  */
 import type { BuildBaseline, CoverageAnchor, CoverageRecord, TestPackagingCoverage } from './build-baseline-types.js';
@@ -70,9 +70,11 @@ export interface RecordedCoverage {
  *
  * @param engineDir - Path to the engine directory
  * @param plan - Plan after {@link applyMozconfigAnchor}
- * @param requested - Normalized request paths this build packaged
+ * @param requestedPaths - Request paths this build packaged. Normalized
+ *   here (no trailing slash, no `./`): the baseline validator rejects the
+ *   raw CLI shapes, and a baseline it rejects refuses every later run.
  */
-export declare function recordScopedCoverage(engineDir: string, plan: CoverageRetentionPlan, requested: string[]): Promise<RecordedCoverage>;
+export declare function recordScopedCoverage(engineDir: string, plan: CoverageRetentionPlan, requestedPaths: string[]): Promise<RecordedCoverage>;
 /** Renders one dropped claim with its cause. */
 export declare function describeDroppedClaim(claim: DroppedClaim): string;
 /**

package/dist/src/core/coverage-extend.js

@@ -8,7 +8,7 @@
  * collapsing to this build's paths. `--extend-coverage` turns any drop into
  * a refusal before the build.
  *
- * Fingerprints must be complete: a legacy packageable-only record cannot
+ * Fingerprints must be complete: a record of packageable inputs only cannot
  * prove that a test fixture or manifest still matches its staged copy.
  */
 import { toError } from '../utils/errors.js';
@@ -163,11 +163,16 @@ export async function applyMozconfigAnchor(engineDir, plan) {
  *
  * @param engineDir - Path to the engine directory
  * @param plan - Plan after {@link applyMozconfigAnchor}
- * @param requested - Normalized request paths this build packaged
+ * @param requestedPaths - Request paths this build packaged. Normalized
+ *   here (no trailing slash, no `./`): the baseline validator rejects the
+ *   raw CLI shapes, and a baseline it rejects refuses every later run.
  */
-export async function recordScopedCoverage(engineDir, plan, requested) {
+export async function recordScopedCoverage(engineDir, plan, requestedPaths) {
     if (plan.keepFull)
         return { testPackagingCoverage: 'full' };
+    const requested = [
+        ...new Set(requestedPaths.map(normalizeRequestPath).filter((path) => path.length > 0)),
+    ];
     const records = { ...plan.retained };
     try {
         const state = await readEngineContentState(engineDir);

package/dist/src/core/coverage-records.d.ts

@@ -1,11 +1,10 @@
 /**
  * Per-path packaging-coverage anchors for scoped `fireforge test --build`.
  *
- * A scoped build used to carry one claim anchored to the whole engine, so
- * any edit outside the new scope (a peer's, on a shared engine, nearly
- * always) replaced it. Each staged request path now carries its own anchor
- * restricted to its own staging inputs, and a claim is dropped only when
- * one of those inputs changed.
+ * Each staged request path carries its own anchor restricted to its own
+ * staging inputs, and a claim is dropped only when one of those inputs
+ * changed. One claim anchored to the whole engine would be replaced by any
+ * edit outside the new scope (a peer's, on a shared engine, nearly always).
  *
  * The staging inputs of a request path are its manifest directory (the
  * nearest directory at or above it that holds a test manifest) plus every

package/dist/src/core/coverage-records.js

@@ -2,11 +2,10 @@
 /**
  * Per-path packaging-coverage anchors for scoped `fireforge test --build`.
  *
- * A scoped build used to carry one claim anchored to the whole engine, so
- * any edit outside the new scope (a peer's, on a shared engine, nearly
- * always) replaced it. Each staged request path now carries its own anchor
- * restricted to its own staging inputs, and a claim is dropped only when
- * one of those inputs changed.
+ * Each staged request path carries its own anchor restricted to its own
+ * staging inputs, and a claim is dropped only when one of those inputs
+ * changed. One claim anchored to the whole engine would be replaced by any
+ * edit outside the new scope (a peer's, on a shared engine, nearly always).
  *
  * The staging inputs of a request path are its manifest directory (the
  * nearest directory at or above it that holds a test manifest) plus every

package/dist/src/core/destructive.d.ts

@@ -128,8 +128,8 @@ export declare function confirmDestructive(input: DestructiveOpInput): Promise<D
 /**
  * Appends a single JSONL record to the project's patch history log
  * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
- * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
- * moved there first).
+ * otherwise; a log found at `patches/.fireforge-history.jsonl` is moved
+ * there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log

package/dist/src/core/destructive.js

@@ -159,8 +159,8 @@ export async function confirmDestructive(input) {
 /**
  * Appends a single JSONL record to the project's patch history log
  * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
- * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
- * moved there first).
+ * otherwise; a log found at `patches/.fireforge-history.jsonl` is moved
+ * there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log

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

@@ -30,7 +30,7 @@ export interface DiscardBaselinePlan {
     /** Rename/copy only: baseline content for `originalPath` when that side is claimed. */
     expectedOriginalContent?: string | null;
 }
-/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` shape. */
 export declare function planUpstreamDiscards(entries: readonly GitStatusEntry[]): DiscardBaselinePlan[];
 /**
  * Plans the restore target for each status entry. Entries claimed by the
@@ -47,7 +47,7 @@ export declare function planDiscardBaselines(patchesDir: string, engineDir: stri
  * Applies one restore plan. Patch-claimed paths end up exactly as `import`
  * leaves them: patched content as an unstaged worktree state (tracked files
  * read ` M`, created files `??`), nothing staged. Unmanaged plans delegate
- * to the legacy {@link discardStatusEntry} mechanics.
+ * to the plain git {@link discardStatusEntry} mechanics.
  */
 export declare function applyDiscardBaseline(engineDir: string, plan: DiscardBaselinePlan): Promise<void>;
 /** One-line annotation for dry-run listings and confirmation summaries. */

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

@@ -24,7 +24,7 @@ import { createPatchedContentContext } from './patch-apply.js';
 import { loadPatchesManifestState } from './patch-manifest-io.js';
 import { parseDiffSections } from './patch-parse.js';
 import { buildPatchClaims } from './status-classify.js';
-/** Builds an all-unmanaged plan set, the `--to-upstream` (legacy) shape. */
+/** Builds an all-unmanaged plan set, the `--to-upstream` shape. */
 export function planUpstreamDiscards(entries) {
     return entries.map((entry) => ({ entry, kind: 'unmanaged', owners: [], conflicted: false }));
 }
@@ -151,7 +151,7 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
  * Applies one restore plan. Patch-claimed paths end up exactly as `import`
  * leaves them: patched content as an unstaged worktree state (tracked files
  * read ` M`, created files `??`), nothing staged. Unmanaged plans delegate
- * to the legacy {@link discardStatusEntry} mechanics.
+ * to the plain git {@link discardStatusEntry} mechanics.
  */
 export async function applyDiscardBaseline(engineDir, plan) {
     if (plan.kind === 'unmanaged') {
@@ -173,7 +173,7 @@ export async function applyDiscardBaseline(engineDir, plan) {
         await writeText(join(engineDir, entry.file), plan.expectedContent);
     }
     // A rename/copy's original side restores to its baseline too: the patch
-    // baseline when claimed, else the legacy HEAD restore (matching what
+    // baseline when claimed, else the HEAD restore (matching what
     // discardStatusEntry does for that side).
     if (entry.originalPath !== undefined) {
         if (plan.expectedOriginalContent !== undefined) {

package/dist/src/core/engine-session-lock.d.ts

@@ -77,7 +77,7 @@ export declare function generationDeltaPaths(before: string, after: string): {
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
- * The refusal used to say only that the engine changed, which left the
+ * A refusal that said only that the engine changed would leave the
  * operator to reconstruct the writer by hand: `find -newermt` against the
  * run window, minus the objdir, minus git's own bookkeeping. Everything
  * needed to answer it is already in the two tokens, so the refusal answers

package/dist/src/core/engine-session-lock.js

@@ -281,7 +281,7 @@ export function generationDeltaPaths(before, after) {
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
- * The refusal used to say only that the engine changed, which left the
+ * A refusal that said only that the engine changed would leave the
  * operator to reconstruct the writer by hand: `find -newermt` against the
  * run window, minus the objdir, minus git's own bookkeeping. Everything
  * needed to answer it is already in the two tokens, so the refusal answers

package/dist/src/core/file-lock-owner.d.ts

@@ -46,11 +46,11 @@ export declare function readLockOwner(lockPath: string): Promise<LockOwner>;
  * time, own start tick, diagnostic metadata) into a lock directory it has
  * just created, and reads the record back to prove it landed.
  *
- * The write is fatal. It used to be best-effort, on the theory that stale
- * recovery would fall back to the age heuristic, but that heuristic reaps
- * any owner-less lock after five minutes, and the build lock legitimately
- * holds for hours. A holder whose record failed to write was therefore
- * reaped mid-build and a second process entered the critical section. On
+ * The write is fatal rather than best-effort. Stale recovery could fall
+ * back to the age heuristic, but that heuristic reaps any owner-less lock
+ * after five minutes, and the build lock legitimately holds for hours. A
+ * holder whose record failed to write would be reaped mid-build and a
+ * second process would enter the critical section. On
  * failure the just-created lock directory is removed (nothing else can own
  * it yet) and a {@link GeneralError} names the cause.
  *

package/dist/src/core/file-lock-owner.js

@@ -141,11 +141,11 @@ async function readBackLockOwner(lockPath) {
  * time, own start tick, diagnostic metadata) into a lock directory it has
  * just created, and reads the record back to prove it landed.
  *
- * The write is fatal. It used to be best-effort, on the theory that stale
- * recovery would fall back to the age heuristic, but that heuristic reaps
- * any owner-less lock after five minutes, and the build lock legitimately
- * holds for hours. A holder whose record failed to write was therefore
- * reaped mid-build and a second process entered the critical section. On
+ * The write is fatal rather than best-effort. Stale recovery could fall
+ * back to the age heuristic, but that heuristic reaps any owner-less lock
+ * after five minutes, and the build lock legitimately holds for hours. A
+ * holder whose record failed to write would be reaped mid-build and a
+ * second process would enter the critical section. On
  * failure the just-created lock directory is removed (nothing else can own
  * it yet) and a {@link GeneralError} names the cause.
  *

package/dist/src/core/file-lock-queue.js

@@ -3,18 +3,16 @@
  * Waiter tickets for `withFileLock`: who is queued for a contended lock, in
  * what order, and whose turn it is.
  *
- * The queue started as a display: waiters advertised themselves so the wait
- * line could say "You are next", but the grant itself was a free-for-all of
- * `mkdir` polls. A waiter whose poll interval had backed off to 2 s lost
- * every free moment to later arrivals polling at 100 ms, so a run told it
- * was next for twenty minutes watched three later runs take the lock in
- * turn. The tickets now decide the grant: only the head of the queue may
- * attempt the lock, so the position printed is the position honoured.
+ * The tickets decide the grant: only the head of the queue may attempt the
+ * lock, so the position printed is the position honoured. A free-for-all of
+ * `mkdir` polls would let later arrivals polling at 100 ms take every free
+ * moment from a waiter whose poll interval had backed off to 2 s, so a run
+ * told it was next could watch later runs take the lock in turn.
  *
  * A ticket is a file in `<lock>.waiters/` named
  * `<startedAtMs>-<pid>-<uuid>`. Arrival order is the wait start, with the
  * whole name as a tie-break so every reader sorts the queue identically.
- * Because a ticket now blocks everyone behind it, a ticket whose owner is
+ * Because a ticket blocks everyone behind it, a ticket whose owner is
  * gone must not hold the queue: a dead PID (or a reused one, where the
  * start-tick check can tell) drops out and its ticket is removed, and a
  * ticket its owner has stopped refreshing drops out without being removed,

package/dist/src/core/file-lock-shared.d.ts

@@ -1,10 +1,10 @@
 /**
  * Shared holds on a FireForge directory lock.
  *
- * Every lock used to be exclusive, so two build-less `fireforge test` runs
- * on one objdir, each with its own profile and (under auto ports) its own
- * ports, still waited for each other: the gate's browser tiers ran strictly
- * serially on a 14-core host. A shared hold lets such runs overlap while
+ * Two build-less `fireforge test` runs on one objdir, each with its own
+ * profile and (under auto ports) its own ports, have no reason to wait for
+ * each other; with only exclusive holds the gate's browser tiers would run
+ * strictly serially on a many-core host. A shared hold lets such runs overlap while
  * anything that writes (a build, a re-export, a test run that builds)
  * still holds the lock alone.
  *

package/dist/src/core/file-lock-shared.js

@@ -2,10 +2,10 @@
 /**
  * Shared holds on a FireForge directory lock.
  *
- * Every lock used to be exclusive, so two build-less `fireforge test` runs
- * on one objdir, each with its own profile and (under auto ports) its own
- * ports, still waited for each other: the gate's browser tiers ran strictly
- * serially on a 14-core host. A shared hold lets such runs overlap while
+ * Two build-less `fireforge test` runs on one objdir, each with its own
+ * profile and (under auto ports) its own ports, have no reason to wait for
+ * each other; with only exclusive holds the gate's browser tiers would run
+ * strictly serially on a many-core host. A shared hold lets such runs overlap while
  * anything that writes (a build, a re-export, a test run that builds)
  * still holds the lock alone.
  *

package/dist/src/core/file-lock.js

@@ -269,10 +269,9 @@ async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause, queue) {
  *
  * The queue is read at the moment the budget expires rather than taken from
  * the last progress probe. A probe snapshot is up to one `waitProgressMs`
- * stale, and, the reason this changed, it may not exist at all: a short
- * budget can expire before the first probe lands (a slow runner's
- * `registerWaiter` alone can outlast it), and a caller that configured no
- * probe at all never had one. Both used to lose the position silently.
+ * stale, and it may not exist at all: a short budget can expire before the
+ * first probe lands (a slow runner's `registerWaiter` alone can outlast it),
+ * and a caller that configured no probe at all never has one.
  */
 function formatQueuePositionReached(queue) {
     if (queue.depth === 0)
@@ -423,12 +422,10 @@ export async function withFileLock(lockPath, operation, options = {}) {
                 // buys a fresh budget, because the wait is working. Only a queue
                 // that stops moving starves, which is the case the timeout is for.
                 //
-                // The first observation is a seed, never an advance. `bestAhead`
-                // used to start `undefined`, so the opening probe always satisfied
-                // this test and handed out a free full budget: a `--wait-lock 300`
-                // run outlived its 300 s even against a queue that never moved
-                // once, which is the "it does not reliably give up after N
-                // seconds" behaviour a downstream fork reported.
+                // The first observation is a seed, never an advance. Counted as an
+                // advance, the opening probe would hand out a free full budget: a
+                // `--wait-lock 300` run would outlive its 300 s even against a queue
+                // that never moved once.
                 if (hardDeadline !== undefined) {
                     if (bestAhead === undefined) {
                         bestAhead = probe.queue.ahead;

package/dist/src/core/firefox.js

@@ -96,8 +96,8 @@ export async function downloadFirefoxSource(options) {
         await removeDir(tempDir);
         // Only throw away the ~600 MB cached archive when the failure indicts
         // the archive, not the environment. ENOSPC, a permission problem in
-        // destDir, or tar disappearing mid-run used to invalidate a perfectly
-        // good download and force a full re-fetch on retry.
+        // destDir, or tar disappearing mid-run leaves a perfectly good download
+        // that a retry can reuse without a full re-fetch.
         if (isLikelyArchiveCorruptionError(error)) {
             await invalidateArchiveCache(archive, cacheDir);
         }

package/dist/src/core/furnace-apply-overwrite-warn.d.ts

@@ -13,7 +13,7 @@
  * The per-file byte comparison already exists:
  * `checkRegistrationConsistency` for custom components (fragment- and
  * ftl-aware) and the copy-candidate walk for overrides. This module only
- * surfaces what was previously computed and thrown away.
+ * surfaces what those comparisons compute.
  */
 import type { CustomComponentConfig, OverrideComponentConfig } from '../types/furnace.js';
 /** One deployed, patch-owned file about to be overwritten with different bytes. */

package/dist/src/core/furnace-apply-overwrite-warn.js

@@ -14,7 +14,7 @@
  * The per-file byte comparison already exists:
  * `checkRegistrationConsistency` for custom components (fragment- and
  * ftl-aware) and the copy-candidate walk for overrides. This module only
- * surfaces what was previously computed and thrown away.
+ * surfaces what those comparisons compute.
  */
 import { readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';

package/dist/src/core/furnace-apply.js

@@ -258,9 +258,9 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 filesAffectedTotal.push(...removed);
             }
             if (!dryRun) {
-                // Runs unconditionally. The `changed === true` path used to skip
-                // drift detection entirely, which is when a deployed engine-only
-                // fix gets silently replaced (J6).
+                // Runs unconditionally, including on the `changed === true` path:
+                // that is when a deployed engine-only fix gets silently replaced
+                // (J6).
                 recordOverwriteWarnings(result, await findPatchOwnedOverwrites({
                     type: 'custom',
                     root,

package/dist/src/core/furnace-config-validate-exceptions.d.ts

@@ -1,8 +1,9 @@
 import { type FurnaceOptInCheck, type FurnaceValidationException } from '../types/furnace.js';
 /**
- * Parses `validationExceptions[]`: `{ component, check, tag?, reason }`
- * objects, no other keys, every field a non-empty string, and no two
- * entries for the same component, check and tag.
+ * Parses `validationExceptions[]`: `{ component, check, tag?, file?, reason }`
+ * objects, no other keys, every field a non-empty string, at most one of
+ * `tag` and `file` (a bare file name of the component), and no two entries
+ * for the same component, check and scope.
  */
 export declare function parseValidationExceptions(raw: unknown): FurnaceValidationException[];
 /**