@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/commands/re-export-retired-declarations.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `re-export --expect-removed` drops the staged declarations whose
+ * `creates` path the run retires.
+ *
+ * Retiring a file would otherwise leave another patch's staged
+ * registration (or forward import) for it in place, unflagged until the
+ * per-patch lint after both re-exports reported `staged-dependency-unused`.
+ * The run that retires the path drops every such declaration, in any patch of the queue, in one manifest
+ * update, and names each one.
+ */
+import { withPatchDirectoryLock } from '../core/patch-lock.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from '../core/patch-manifest.js';
+import { info } from '../utils/logger.js';
+import { recordStagedDeclarationPrune, } from './re-export-stale-registrations.js';
+/**
+ * Finds the declarations whose `creates` path is retired and owned by no
+ * patch outside `retiring`.
+ *
+ * @param manifest - The queue to judge
+ * @param removed - The run's `--expect-removed` paths
+ * @param retiring - Patches whose ownership of a removed path does not
+ *   count: the selected owners in a dry run, whose rows are not rewritten
+ *   yet; nothing after the write, where a failed owner still owns its path
+ */
+function planRetiredDeclarationDrops(manifest, removed, retiring) {
+    const orphaned = new Set(removed.filter((file) => !manifest.patches.some((patch) => !retiring.has(patch.filename) && patch.filesAffected.includes(file))));
+    if (orphaned.size === 0)
+        return [];
+    const drops = [];
+    for (const patch of manifest.patches) {
+        const drop = planHolderDrop(patch, orphaned);
+        if (drop !== undefined)
+            drops.push(drop);
+    }
+    return drops;
+}
+function planHolderDrop(patch, orphaned) {
+    const forwardImports = patch.stagedDependencies?.forwardImports ?? [];
+    const registrations = patch.stagedDependencies?.registrations ?? [];
+    const dropped = [
+        ...registrations
+            .filter((entry) => orphaned.has(entry.creates))
+            .map((entry) => ({ kind: 'registration', ...entry })),
+        ...forwardImports
+            .filter((entry) => orphaned.has(entry.creates))
+            .map((entry) => ({ kind: 'import', ...entry })),
+    ];
+    if (dropped.length === 0)
+        return undefined;
+    const keptImports = forwardImports.filter((entry) => !orphaned.has(entry.creates));
+    const keptRegistrations = registrations.filter((entry) => !orphaned.has(entry.creates));
+    const staged = {
+        ...(keptImports.length > 0 ? { forwardImports: keptImports } : {}),
+        ...(keptRegistrations.length > 0 ? { registrations: keptRegistrations } : {}),
+    };
+    return {
+        holder: patch.filename,
+        dropped,
+        stagedDependencies: Object.keys(staged).length > 0 ? staged : undefined,
+    };
+}
+function reportRetiredDeclarationDrops(drops, isDryRun) {
+    const verb = isDryRun ? 'would drop' : 'drops';
+    for (const { holder, dropped } of drops) {
+        for (const entry of dropped) {
+            const what = entry.kind === 'registration'
+                ? `staged registration ${entry.file} "${entry.line.trim()}"`
+                : `staged forward-import ${entry.file} "${entry.specifier}"`;
+            info(`${holder}: ${verb} ${what}: --expect-removed retires ${entry.creates}.`);
+        }
+    }
+}
+/**
+ * Drops (or, in a dry run, names) every staged declaration whose `creates`
+ * path this run retired. Runs after the selected patches are written, so a
+ * path whose owner failed to re-export is still owned and its declarations
+ * stay.
+ */
+export async function dropRetiredPathDeclarations(args) {
+    const { manifest, isDryRun } = args;
+    const patchesDir = args.paths.patches;
+    const removed = args.options.expectRemoved ?? [];
+    const selected = new Set(args.selectedPatches.map((patch) => patch.filename));
+    if (removed.length === 0)
+        return;
+    if (isDryRun) {
+        reportRetiredDeclarationDrops(planRetiredDeclarationDrops(manifest, removed, selected), isDryRun);
+        return;
+    }
+    const drops = await withPatchDirectoryLock(patchesDir, async () => {
+        const current = await loadPatchesManifestForWrite(patchesDir);
+        if (!current)
+            return [];
+        const planned = planRetiredDeclarationDrops(current, removed, new Set());
+        const byHolder = new Map(planned.map((drop) => [drop.holder, drop]));
+        if (byHolder.size === 0)
+            return [];
+        await mutatePatchRowsInManifest(patchesDir, [...byHolder.keys()], (existing) => {
+            const drop = byHolder.get(existing.filename);
+            if (drop === undefined)
+                return null;
+            return drop.stagedDependencies === undefined
+                ? { unset: ['stagedDependencies'] }
+                : { set: { stagedDependencies: drop.stagedDependencies } };
+        });
+        return planned;
+    }, { command: 're-export' });
+    reportRetiredDeclarationDrops(drops, isDryRun);
+    for (const drop of drops) {
+        await recordStagedDeclarationPrune(patchesDir, drop.holder, drop.dropped, 'staged declarations on retired paths');
+    }
+}

package/dist/src/commands/re-export-single.js

@@ -23,7 +23,7 @@ import { reportForeignDrift } from './re-export-drift.js';
 import { buildHunkSelectedDiff, hunkSelectionOf } from './re-export-hunks.js';
 import { assertRefreshedBodyHasNoNewQueueErrors, lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
 import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, scanPatchFilesForReExport, } from './re-export-scan.js';
-import { planStaleRegistrationDrop, recordStaleRegistrationDrop, reportStaleRegistrationDrop, } from './re-export-stale-registrations.js';
+import { findPendingRegistrationCreates, planStaleRegistrationDrop, recordStaleRegistrationDrop, reportStaleRegistrationDrop, } from './re-export-stale-registrations.js';
 const GIT_INDEX_LOCK_RETRY_MS = 300;
 /**
  * Retries a single patch re-export exactly once when the failure is
@@ -211,7 +211,7 @@ async function reExportSinglePatch(args) {
         return false;
     }
     const { updates, ignoreChecks, effectiveTier, existingIgnoreSet, flagIgnoreSet } = computeReExportUpdates(patch, options, currentFilesAffected);
-    const stalePlan = planStaleRegistrationDrop(manifest, patch, currentFilesAffected);
+    const stalePlan = planStaleRegistrationDrop(manifest, patch, currentFilesAffected, await findPendingRegistrationCreates(paths.engine, manifest, patch, currentFilesAffected, adjacentCtx.expectedNew));
     if (stalePlan !== undefined)
         reportStaleRegistrationDrop(patch.filename, stalePlan, isDryRun);
     const unset = applyStaleRegistrationDrop(stalePlan, updates);

package/dist/src/commands/re-export-stale-registrations.d.ts

@@ -1,18 +1,39 @@
-import type { PatchesManifest, PatchMetadata, PatchStagedDependencies, PatchStagedRegistration } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../types/commands/index.js';
 /** The holder's registrations split by whether the queue still owns `creates`. */
 export interface StaleRegistrationPlan {
     /** Registrations whose `creates` path no patch owns. */
     dropped: PatchStagedRegistration[];
+    /** Unowned registrations kept because their `creates` file is pending adoption. */
+    pending: PatchStagedRegistration[];
     /** The staged block to write, or undefined when nothing is left. */
     stagedDependencies: PatchStagedDependencies | undefined;
 }
+/**
+ * The unowned `creates` paths of `patch`'s registrations that are pending
+ * adoption: the file exists in `engine/`, or is an `--expect-new` path of
+ * this run. Such a registration is waiting for its subject patch's scan.
+ */
+export declare function findPendingRegistrationCreates(engineDir: string, manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[], expectedNew: ReadonlySet<string>): Promise<Set<string>>;
 /**
  * Finds `patch`'s registrations whose `creates` path no patch in the queue
- * owns, judging `patch` by the file list this re-export will write.
- * Returns undefined when nothing is stale.
+ * owns, judging `patch` by the file list this re-export will write. A
+ * registration whose `creates` path is in `pending` (see
+ * {@link findPendingRegistrationCreates}) is kept and reported instead.
+ * Returns undefined when nothing is stale or pending.
  */
-export declare function planStaleRegistrationDrop(manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[]): StaleRegistrationPlan | undefined;
-/** Names each dropped registration, in both a dry run and a write. */
+export declare function planStaleRegistrationDrop(manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[], pendingCreates?: ReadonlySet<string>): StaleRegistrationPlan | undefined;
+/** Names each dropped and each kept-pending registration, in both a dry run and a write. */
 export declare function reportStaleRegistrationDrop(patchFilename: string, plan: StaleRegistrationPlan, isDryRun: boolean): void;
-/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
+/** One declaration a re-export pruned, as the history log records it. */
+export type PrunedStagedDeclaration = ({
+    kind: 'registration';
+} & PatchStagedRegistration) | ({
+    kind: 'import';
+} & PatchStagedForwardImport);
+/**
+ * Records declarations a re-export pruned from one patch as a delta, like
+ * `staged-dependency --remove`.
+ */
+export declare function recordStagedDeclarationPrune(patchesDir: string, patchFilename: string, removed: readonly PrunedStagedDeclaration[], what: string): Promise<void>;
+/** Records the dropped registrations as a delta, like `staged-dependency --remove`. */
 export declare function recordStaleRegistrationDrop(patchesDir: string, patchFilename: string, plan: StaleRegistrationPlan): Promise<void>;

package/dist/src/commands/re-export-stale-registrations.js

@@ -3,23 +3,40 @@
  * Re-export prunes a staged registration the queue can no longer satisfy.
  *
  * A merge that deletes a file whose jar.mn line lives in another patch
- * left the staged registration on that patch: re-export kept it, lint then
- * warned `staged-dependency-unused`, and the stale declaration also kept
- * the holder measuring above a just-lowered size ceiling. When no patch in
+ * leaves the staged registration on that patch: lint warns
+ * `staged-dependency-unused`, and the stale declaration keeps the holder
+ * measuring above a just-lowered size ceiling. When no patch in
  * the queue owns a registration's `creates` path any more, the declaration
  * cannot be met, so the holder's own re-export drops it and says so.
+ *
+ * A registration whose `creates` file exists in `engine/`, or is an
+ * `--expect-new` path of the run, is kept: a manifest owner's re-export can
+ * run between declaring the registration and the scan that adopts the
+ * file, and pruning it there would break the scan that needs it next.
  */
+import { join } from 'node:path';
 import { appendHistoryBestEffort } from '../core/history-log.js';
+import { pathExists } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
 /**
- * Finds `patch`'s registrations whose `creates` path no patch in the queue
- * owns, judging `patch` by the file list this re-export will write.
- * Returns undefined when nothing is stale.
+ * The unowned `creates` paths of `patch`'s registrations that are pending
+ * adoption: the file exists in `engine/`, or is an `--expect-new` path of
+ * this run. Such a registration is waiting for its subject patch's scan.
  */
-export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected) {
-    const registrations = patch.stagedDependencies?.registrations ?? [];
-    if (registrations.length === 0)
-        return undefined;
+export async function findPendingRegistrationCreates(engineDir, manifest, patch, currentFilesAffected, expectedNew) {
+    const owned = ownedPaths(manifest, patch, currentFilesAffected);
+    const pending = new Set();
+    for (const registration of patch.stagedDependencies?.registrations ?? []) {
+        const creates = registration.creates;
+        if (owned.has(creates) || pending.has(creates))
+            continue;
+        if (expectedNew.has(creates) || (await pathExists(join(engineDir, creates)))) {
+            pending.add(creates);
+        }
+    }
+    return pending;
+}
+function ownedPaths(manifest, patch, currentFilesAffected) {
     const owned = new Set(currentFilesAffected);
     for (const entry of manifest.patches) {
         if (entry.filename === patch.filename)
@@ -27,10 +44,26 @@ export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected)
         for (const file of entry.filesAffected)
             owned.add(file);
     }
-    const dropped = registrations.filter((registration) => !owned.has(registration.creates));
-    if (dropped.length === 0)
+    return owned;
+}
+/**
+ * Finds `patch`'s registrations whose `creates` path no patch in the queue
+ * owns, judging `patch` by the file list this re-export will write. A
+ * registration whose `creates` path is in `pending` (see
+ * {@link findPendingRegistrationCreates}) is kept and reported instead.
+ * Returns undefined when nothing is stale or pending.
+ */
+export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected, pendingCreates = new Set()) {
+    const registrations = patch.stagedDependencies?.registrations ?? [];
+    if (registrations.length === 0)
         return undefined;
-    const kept = registrations.filter((registration) => owned.has(registration.creates));
+    const owned = ownedPaths(manifest, patch, currentFilesAffected);
+    const unowned = registrations.filter((registration) => !owned.has(registration.creates));
+    const pending = unowned.filter((registration) => pendingCreates.has(registration.creates));
+    const dropped = unowned.filter((registration) => !pendingCreates.has(registration.creates));
+    if (dropped.length === 0 && pending.length === 0)
+        return undefined;
+    const kept = registrations.filter((registration) => !dropped.includes(registration));
     const forwardImports = patch.stagedDependencies?.forwardImports ?? [];
     const staged = {
         ...(forwardImports.length > 0 ? { forwardImports } : {}),
@@ -38,25 +71,36 @@ export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected)
     };
     return {
         dropped,
+        pending,
         stagedDependencies: Object.keys(staged).length > 0 ? staged : undefined,
     };
 }
-/** Names each dropped registration, in both a dry run and a write. */
+/** Names each dropped and each kept-pending registration, in both a dry run and a write. */
 export function reportStaleRegistrationDrop(patchFilename, plan, isDryRun) {
     const verb = isDryRun ? 'would drop' : 'drops';
     for (const registration of plan.dropped) {
         info(`${patchFilename}: ${verb} staged registration ${registration.file} "${registration.line.trim()}": ` +
             `no patch in the queue creates ${registration.creates} any more.`);
     }
+    for (const registration of plan.pending) {
+        info(`${patchFilename}: staged registration ${registration.file} "${registration.line.trim()}" ` +
+            `for ${registration.creates} kept: file exists but no patch owns it yet.`);
+    }
 }
-/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
-export async function recordStaleRegistrationDrop(patchesDir, patchFilename, plan) {
+/**
+ * Records declarations a re-export pruned from one patch as a delta, like
+ * `staged-dependency --remove`.
+ */
+export async function recordStagedDeclarationPrune(patchesDir, patchFilename, removed, what) {
+    if (removed.length === 0)
+        return;
     await appendHistoryBestEffort(patchesDir, {
         operation: 're-export-staged-prune',
-        args: {
-            filename: patchFilename,
-            removed: plan.dropped.map((registration) => ({ kind: 'registration', ...registration })),
-        },
+        args: { filename: patchFilename, removed: [...removed] },
         result: 'ok',
-    }, `re-export pruned stale staged registrations on ${patchFilename}`);
+    }, `re-export pruned ${what} on ${patchFilename}`);
+}
+/** Records the dropped registrations as a delta, like `staged-dependency --remove`. */
+export async function recordStaleRegistrationDrop(patchesDir, patchFilename, plan) {
+    await recordStagedDeclarationPrune(patchesDir, patchFilename, plan.dropped.map((registration) => ({ kind: 'registration', ...registration })), 'stale staged registrations');
 }

package/dist/src/commands/re-export.js

@@ -17,6 +17,7 @@ import { reExportFilesInPlace } from './re-export-files.js';
 import { buildReExportLintContext, finishReExportLint } from './re-export-lint.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { validateExpectedRemovals } from './re-export-removed.js';
+import { dropRetiredPathDeclarations } from './re-export-retired-declarations.js';
 import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
 import { assignScanFileOwners, scanOptionsForPatch } from './re-export-scan-owner.js';
 import { reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
@@ -190,6 +191,9 @@ export async function reExportCommand(projectRoot, patches, options) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
     }
+    // Declarations on a path this run retired can never be met; drop them
+    // now rather than leave them for the next per-patch lint to report.
+    await dropRetiredPathDeclarations({ paths, manifest, options, selectedPatches, isDryRun });
     // `--stamp` only fires on a run where every selected patch refreshed
     // cleanly. A partial success would leave some patches with a stale body
     // but a new version, the opposite of the "what I tested, what the

package/dist/src/commands/rebase/continue.js

@@ -21,9 +21,9 @@ import { runPatchLoop } from './patch-loop.js';
  */
 export async function handleContinue(projectRoot, maxFuzz, waitLockSeconds) {
     intro('FireForge Rebase — Continue');
-    // A present-but-unreadable session is not "no session in progress". That
-    // conflation is what made a corrupt file unrecoverable. Name the file and
-    // point at --abort, which can now clear it.
+    // A present-but-unreadable session is not "no session in progress":
+    // treating it as one leaves a corrupt file unrecoverable. Name the file
+    // and point at --abort, which can clear it.
     const read = await readRebaseSession(projectRoot);
     if (!read.present)
         throw new NoRebaseSessionError();

package/dist/src/commands/register.js

@@ -32,9 +32,9 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     }
     // Accept either repo-root-relative (`engine/browser/...`) or
     // engine-relative (`browser/...`) inputs. Operators frequently paste
-    // the former from the output of tab completion or `git status`, and
-    // the mismatch used to produce a "File not found" error that named
-    // the original path with no hint that dropping `engine/` would fix it.
+    // the former from the output of tab completion or `git status`, so
+    // both shapes resolve to the same path instead of a "File not found"
+    // error.
     const engineRelativePath = stripEnginePrefix(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
@@ -97,7 +97,8 @@ export function registerRegister(program, { getProjectRoot, withErrorHandling })
         .command('register <path>')
         .description('Register a file in the appropriate build manifest')
         .option('--dry-run', 'Show what would be changed without writing')
-        .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical)')
+        .option('--after <entry>', 'Place entry after line containing this substring (instead of alphabetical); for an ' +
+        'xpcshell test, after the whole section of the xpcshell.toml entry it names')
         .option('--create-manifest', 'Scaffold a missing manifest (directory moz.build with EXTRA_JS_MODULES / XPCSHELL_TESTS_MANIFESTS, or xpcshell.toml) and wire the parent DIRS chain instead of failing with "Manifest not found"')
         .action(withErrorHandling(async (path, options) => {
         await registerCommand(getProjectRoot(), path, pickDefined(options));

package/dist/src/commands/status-output.js

@@ -206,7 +206,11 @@ export function renderTestCoverageStatus(baseline) {
     }
     info(`Last build: ${baseline.builtAt}  (binary: ${baseline.binaryName}, ` +
         `engine HEAD: ${baseline.engineHeadSha || '(unborn)'})`);
-    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}`);
+    const recorder = baseline.recorder;
+    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}` +
+        (recorder === undefined
+            ? ''
+            : ` (pid ${recorder.pid}${recorder.sessionId !== undefined ? `, session ${recorder.sessionId}` : ''})`));
     const coverage = baseline.testPackagingCoverage;
     if (coverage === undefined) {
         info('Test packaging coverage: full (implicit — baseline predates coverage recording)');

package/dist/src/commands/status.js

@@ -409,7 +409,7 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported, ownership-conflict (a path claimed by more than one patch)')
         .option('--allow <classifications>', 'Comma-separated classification list that never fails --check, removed from the fail set (implies --check; same values as --fail-on)')
         .option('--fail-on-unknown', 'With --allow: also fail on every present classification that neither --fail-on nor --allow names, so a classification added in a later FireForge fails closed (implies --check)')
-        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
+        .option('--patches <names...>', 'Judge only the named patches: keeps the files each owns or claims and the ownership rows naming it (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Unmanaged files belong to no patch and drop out. Default view, --json and --ownership only')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

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

@@ -3,8 +3,7 @@
  * runs `furnace apply` over the whole `components/` tree, so a
  * `fireforge test --build` meant to capture the committed behaviour could
  * silently ship component edits nobody had deployed yet (another session's
- * included), and nothing in the test output said so. The applied names now
- * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * included). The applied names therefore ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
  * stands, naming the undeployed edits it left out.
  */
 import type { BuildPreparation } from '../core/build-prepare.js';

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

@@ -4,8 +4,7 @@
  * runs `furnace apply` over the whole `components/` tree, so a
  * `fireforge test --build` meant to capture the committed behaviour could
  * silently ship component edits nobody had deployed yet (another session's
- * included), and nothing in the test output said so. The applied names now
- * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * included). The applied names therefore ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
  * stands, naming the undeployed edits it left out.
  */
 import { listStaleFurnaceComponents } from '../core/furnace-staleness.js';

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

@@ -3,6 +3,7 @@
  * the per-file line budget): the incremental protected mach build with
  * its baseline write, and the `--build-only` union-build shape.
  */
+import type { ControlBuildStamp } from '../core/build-baseline-types.js';
 import type { TestOptions } from '../types/commands/index.js';
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import type { HarnessClassification } from './test-modes.js';
@@ -16,4 +17,13 @@ import type { HarnessClassification } from './test-modes.js';
 export declare function runTestBuildPhase(projectRoot: string, paths: ProjectPaths, projectConfig: FireForgeConfig, harnessRetries: number, options: TestOptions, request: {
     classification: HarnessClassification;
     normalizedPaths: string[];
+    /** Forces a full pre-test build (a compiled negative control). */
+    fullBuildReason?: string;
+    /** Recorded on the pre-test build's baseline (a compiled negative control). */
+    controlBuild?: ControlBuildStamp;
+    /**
+     * Engine-relative launchable binary: anchors the stale-compiled check,
+     * which refuses a build-less run and escalates a `--build` one.
+     */
+    launchablePath?: string | undefined;
 }): Promise<boolean>;

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

@@ -7,10 +7,12 @@
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { applyMozconfigAnchor, formatCoverageRetentionNotice, formatExtendCoverageRefusal, planCoverageRetention, recordScopedCoverage, } from '../core/coverage-extend.js';
+import { normalizeRequestPath } from '../core/coverage-records.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
 import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
+import { findCompiledSourcesNewerThanBinary, formatStaleCompiledBuildNotice, } from '../core/test-stale-check.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -27,7 +29,7 @@ import { emitPassVerdict } from './test-verdict.js';
  * @param options - See {@link RunPreTestBuildOptions}
  */
 async function runPreTestBuild(options) {
-    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, } = options;
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, fullBuildReason, controlBuild, } = options;
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -66,17 +68,16 @@ async function runPreTestBuild(options) {
             if (retentionNotice !== undefined)
                 notice(retentionNotice);
         }
-        const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
-        if (preparation.fullBuildRequired) {
+        const fullBuild = preparation.fullBuildRequired || fullBuildReason !== undefined;
+        const buildKind = fullBuild ? 'full' : 'faster';
+        if (fullBuild) {
             // Warning severity rather than info: agent-facing output filters
             // keep warnings and errors only, and this is the line that explains an
             // otherwise unexplained multi-minute build.
-            notice(preparation.fullBuildReason ??
+            notice((preparation.fullBuildRequired ? preparation.fullBuildReason : fullBuildReason) ??
                 'A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
         }
-        const s = spinner(preparation.fullBuildRequired
-            ? 'Running required full build...'
-            : 'Running incremental build...');
+        const s = spinner(fullBuild ? 'Running required full build...' : 'Running incremental build...');
         // The pre-test build routes through the same protected mach dispatch as
         // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
         // the uniform recognized-crash retry budget, with a fresh mach process
@@ -116,12 +117,13 @@ async function runPreTestBuild(options) {
                     ...recorded,
                     previousBaseline,
                     recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
-                    staticComponentsHandling: preparation.fullBuildRequired
+                    staticComponentsHandling: fullBuild
                         ? 'refresh'
                         : plan !== undefined && (plan.keepFull || Object.keys(plan.retained).length > 0)
                             ? 'carry-forward'
                             : 'auto',
                     buildKind,
+                    controlBuild,
                 });
             }
             catch (baselineError) {
@@ -131,8 +133,8 @@ async function runPreTestBuild(options) {
         }
         s.error('Pre-test build failed');
         throw new BuildError(result.crashSignature
-            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, 'mach build faster')
-            : 'Pre-test build failed', preparation.fullBuildRequired ? 'mach build' : 'mach build faster');
+            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, fullBuild ? 'mach build' : 'mach build faster')
+            : 'Pre-test build failed', fullBuild ? 'mach build' : 'mach build faster');
     });
 }
 /**
@@ -201,7 +203,7 @@ function describeBuildInvocation(extending, coverage) {
  * next steps, and emits the run's single `PASS` verdict.
  */
 export async function runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, request) {
-    const { classification, normalizedPaths } = request;
+    const { classification, normalizedPaths, controlBuild, launchablePath } = request;
     const extending = options.extendCoverage === true;
     if (extending) {
         assertExtendCoverageUsage(options, normalizedPaths);
@@ -214,19 +216,28 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         // rebuild also cannot regenerate the compiled StaticComponents table,
         // so it runs the components.conf gate up-front (the path-less shape
         // refreshes the anchor itself and skips it).
-        const coverage = normalizedPaths.length === 0 ? 'full' : normalizedPaths;
-        if (normalizedPaths.length > 0) {
+        // Coverage paths are recorded normalized (no trailing slash, no `./`):
+        // the baseline validator refuses the raw `dir/` CLI shape, which would
+        // block every later plain `fireforge test`. A request
+        // for the engine root (`.`) packages everything, so it records `'full'`.
+        const coveragePaths = normalizedPaths.map(normalizeRequestPath);
+        const coverage = coveragePaths.length === 0 || coveragePaths.includes('')
+            ? 'full'
+            : [...new Set(coveragePaths)];
+        if (coverage !== 'full') {
             const previousBaseline = await readBuildBaseline(projectRoot);
             await enforceStaticComponentsGate(paths.engine, previousBaseline, options);
             if (extending) {
                 // Staging-input half of the plan, before the build lock: a refusal
                 // here costs neither build time nor the lock.
-                const plan = await planCoverageRetention(paths.engine, previousBaseline, normalizedPaths);
+                const plan = await planCoverageRetention(paths.engine, previousBaseline, coverage);
                 if (plan.dropped.length > 0) {
                     throw new GeneralError(formatExtendCoverageRefusal(plan.dropped));
                 }
             }
         }
+        const fullBuildReason = request.fullBuildReason ??
+            (await describeCompiledEscalation(projectRoot, paths.engine, launchablePath));
         await runPreTestBuild({
             projectRoot,
             paths,
@@ -234,7 +245,9 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             harnessRetries,
             testPackagingCoverage: coverage,
             refuseUnexportedDrift: options.refuseUnexportedDrift === true,
-            extend: extending ? { requestedPaths: normalizedPaths } : undefined,
+            extend: extending && coverage !== 'full' ? { requestedPaths: coverage } : undefined,
+            fullBuildReason,
+            controlBuild,
             furnace: await planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths),
         });
         info('');
@@ -249,7 +262,29 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         }
     }
     else {
-        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths);
+        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths, {
+            launchablePath,
+        });
     }
     return false;
 }
+/**
+ * Why a `--build` run's pre-test build must be a full `mach build` although
+ * nothing asked for one: compiled sources changed after the binary was
+ * linked, or the binary still carries a negative control a killed run (or a
+ * failed restore build) left compiled in. `mach build faster` compiles
+ * nothing, so either would otherwise survive the build.
+ */
+async function describeCompiledEscalation(projectRoot, engineDir, launchablePath) {
+    const baseline = await readBuildBaseline(projectRoot);
+    const stale = await findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath);
+    if (stale !== undefined && stale.paths.length > 0)
+        return formatStaleCompiledBuildNotice(stale);
+    const stamp = baseline?.controlBuild;
+    if (stamp !== undefined) {
+        return (`The binary was built with the negative control ${stamp.diffFile} applied and not ` +
+            'rebuilt since; escalating this pre-test build to a full mach build so it recompiles ' +
+            'the restored source.');
+    }
+    return undefined;
+}

package/dist/src/commands/test-control-restore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The restore build after a compiled negative control.
+ *
+ * A control on compiled source is applied before a full pre-test build, so
+ * the binary under test carries it. Restoring the source byte-exact after
+ * the run does not unbuild it: the objdir binary keeps the mutation until a
+ * build recompiles the original. Every later `fireforge test` would then
+ * test the control. The orchestrator therefore runs one more full
+ * `mach build` right after a successful restore, still under the same
+ * engine-session hold, and its baseline drops the `controlBuild` stamp the
+ * control's build recorded. When that build fails, or the run never gets
+ * here (killed), the stamp stays and the next `fireforge test` refuses with
+ * `note=control-built` until `fireforge build` replaces it.
+ */
+import type { ControlBuildStamp } from '../core/build-baseline-types.js';
+/** Outcome of {@link runControlRestoreBuild}, stamped as `control-restore-build=`. */
+export type ControlRestoreBuildOutcome = 'done' | 'failed';
+/**
+ * Whether the recorded baseline is the one this run's control build wrote:
+ * only then did a build compile the control in (a failed control build
+ * writes no baseline, and its restored source's fresh mtime trips the
+ * stale-compiled check instead).
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ */
+export declare function controlBuildRecorded(projectRoot: string, stamp: ControlBuildStamp): Promise<boolean>;
+/**
+ * Rebuilds the binary after a compiled control was restored: a full
+ * protected `mach build` under the build lock, then a baseline without the
+ * stamp. The previous baseline's packaging-coverage claim is carried
+ * forward unchanged, since recompiling the restored source stages no tests.
+ * Never throws: a failure leaves the stamp in place, which is the refusal
+ * the next run needs.
+ *
+ * @param projectRoot - Project root
+ * @param stamp - The stamp this run's control build recorded
+ * @param harnessRetries - Recognized-crash retry budget for the build
+ */
+export declare function runControlRestoreBuild(projectRoot: string, stamp: ControlBuildStamp, harnessRetries: number | undefined): Promise<ControlRestoreBuildOutcome>;