@hominis/fireforge 0.47.0 → 0.48.0

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

@@ -10,8 +10,10 @@
  * cost startup time but make results reproducible. The combined invocation
  * stays available via `--no-shard`.
  */
+import { join } from 'node:path';
 import { probeDisplaySleepState } from '../core/display-state.js';
 import { runMachTestSuite } from '../core/mach.js';
+import { parentExited } from '../core/parent-exit-watchdog.js';
 import { getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
@@ -21,6 +23,7 @@ import { TestFailureError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
+import { createHarnessTeardown } from './test-harness-teardown.js';
 import { emitHarnessVerdict } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
@@ -61,13 +64,14 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     let verdict;
     for (;;) {
         attempts += 1;
-        result = await runMachTestSuite(kind, {
-            engineDir: ctx.engineDir,
-            testPaths: paths,
-            args: extraArgs,
-            env,
-            fullOutput: ctx.fullOutput,
-        });
+        result = await runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env);
+        // The parent that was reading this run is gone and the watchdog has
+        // already killed the harness. Classifying the corpse would call it a
+        // harness crash and retry it under nobody's supervision.
+        if (parentExited()) {
+            throw new TestFailureError('The parent process exited while the harness was running; the harness tree was ' +
+                'terminated and the run ended without a result.', `mach ${kind}`, undefined, getActiveRunLogPath());
+        }
         result = await retryAfterXpcshellSymlinkRepair({
             engineDir: ctx.engineDir,
             objDir: ctx.objDir,
@@ -107,6 +111,31 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     }
     return { result, verdict, attempts, appdirInjectionAttempted, displayState };
 }
+/**
+ * One mach dispatch with its kill path attached: helper-pid tracking and
+ * post-close reaping, the process-group announcement, and the parent-exit
+ * watchdog for exactly as long as mach runs.
+ */
+async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env) {
+    const teardown = createHarnessTeardown({
+        objDir: ctx.objDir === undefined ? undefined : join(ctx.engineDir, ctx.objDir),
+        pgidFile: ctx.pgidFile,
+    });
+    try {
+        await teardown.prepare();
+        return await runMachTestSuite(kind, {
+            engineDir: ctx.engineDir,
+            testPaths: paths,
+            args: extraArgs,
+            env,
+            fullOutput: ctx.fullOutput,
+            teardown: teardown.hooks,
+        });
+    }
+    finally {
+        teardown.dispose();
+    }
+}
 /**
  * Probes the display's power state for a headed no-output stall, and only for
  * that shape. Every other outcome (a passing run, a real test failure, a

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

@@ -12,8 +12,16 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * of the others.
  */
 export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
+/** Additive keys a run can stamp on its verdict line. */
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped';
 /** Records an additive attribute for this run's verdict line. */
-export declare function setVerdictRunAttribute(key: 'shuffle', value: string): void;
+export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
+/**
+ * Adds to a counting attribute. The key appears only once the total is
+ * positive, so a run that reaped nothing prints the line it always did.
+ * Sums across the preflight census, every retry attempt and every shard.
+ */
+export declare function addVerdictRunCount(key: 'orphans-reaped', count: number): void;
 /**
  * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
  * repeated programmatic invocations (and tests) each get their own
@@ -49,7 +57,14 @@ export declare function emitPassVerdict(): void;
  */
 export declare function emitFailVerdict(reason: FireforgeVerdictReason, note?: string): void;
 /**
- * Emits the terminal verdict for a run killed by a signal.
+ * What ended a killed run: a signal FireForge received, or `parent-exit`,
+ * the parent-death watchdog's finding that the process above FireForge
+ * vanished (typically SIGKILLed by a supervisor) while a harness ran.
+ */
+export type KilledVerdictCause = NodeJS.Signals | 'parent-exit';
+/**
+ * Emits the terminal verdict for a run killed by a signal, or ended by
+ * FireForge itself because its parent died.
  *
  * Without it a killed run wrote no terminal line, so a log tail could not
  * distinguish "killed" from "still running" from "never started". Recovery
@@ -59,7 +74,7 @@ export declare function emitFailVerdict(reason: FireforgeVerdictReason, note?: s
  * line asserts a test run happened, and an interrupted `status` did not
  * have one.
  *
- * @param signal - The signal that terminated the run
+ * @param signal - The signal that terminated the run, or `parent-exit`
  * @returns True when a line was written
  */
-export declare function emitKilledVerdict(signal: NodeJS.Signals): boolean;
+export declare function emitKilledVerdict(signal: KilledVerdictCause): boolean;

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

@@ -7,15 +7,32 @@ let emitted = false;
  * Additive `key=value` attributes of the run in flight, appended to
  * whichever verdict line ends it. `shuffle` is the seed a `--shuffle` run
  * exported to the harness, so a red found by shuffling carries its own
- * reproduction on the one line an unattended reader keeps. Cleared by
+ * reproduction on the one line an unattended reader keeps. `orphans-reaped`
+ * is how many harness processes FireForge had to terminate itself, at
+ * preflight (survivors of an earlier run) or at teardown (helpers this run
+ * launched that outlived mach): a green after a reap is not the same
+ * finding as a green on a quiet machine. Cleared by
  * {@link resetVerdictEmission}, so a later run in the same process cannot
- * inherit it.
+ * inherit them.
  */
 const runAttributes = new Map();
 /** Records an additive attribute for this run's verdict line. */
 export function setVerdictRunAttribute(key, value) {
     runAttributes.set(key, value);
 }
+/**
+ * Adds to a counting attribute. The key appears only once the total is
+ * positive, so a run that reaped nothing prints the line it always did.
+ * Sums across the preflight census, every retry attempt and every shard.
+ */
+export function addVerdictRunCount(key, count) {
+    // Written as a negated `> 0` so a NaN (a stubbed census, a bad parse) is
+    // dropped rather than stamped on the line as `orphans-reaped=NaN`.
+    if (!(count > 0))
+        return;
+    const current = Number(runAttributes.get(key) ?? '0');
+    runAttributes.set(key, String(current + count));
+}
 /**
  * True once a test run has begun in this process.
  *
@@ -96,7 +113,8 @@ export function emitFailVerdict(reason, note) {
     writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}${suffix}`);
 }
 /**
- * Emits the terminal verdict for a run killed by a signal.
+ * Emits the terminal verdict for a run killed by a signal, or ended by
+ * FireForge itself because its parent died.
  *
  * Without it a killed run wrote no terminal line, so a log tail could not
  * distinguish "killed" from "still running" from "never started". Recovery
@@ -106,7 +124,7 @@ export function emitFailVerdict(reason, note) {
  * line asserts a test run happened, and an interrupted `status` did not
  * have one.
  *
- * @param signal - The signal that terminated the run
+ * @param signal - The signal that terminated the run, or `parent-exit`
  * @returns True when a line was written
  */
 export function emitKilledVerdict(signal) {

package/dist/src/commands/test.js

@@ -22,9 +22,10 @@ import { stripEnginePrefix } from '../utils/paths.js';
 import { runTestBuildPhase } from './test-build-phase.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-harness-env.js';
+import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
 import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
-import { emitFailVerdict, emitPassVerdict, resetVerdictEmission, verdictEmitted, } from './test-verdict.js';
+import { addVerdictRunCount, emitFailVerdict, emitPassVerdict, resetVerdictEmission, verdictEmitted, } from './test-verdict.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -227,7 +228,7 @@ async function ensureTestMarionettePortAvailable(port, binaryName, options, skip
     }
     await assertMarionettePortAvailable(port, { binaryName });
 }
-async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, binaryName, options, objDir) {
+async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellOnly, projectConfig, options, objDir) {
     // A timed-out mochitest can leave the built app alive after its Marionette
     // listener has disappeared. The port probe cannot see that case, but the
     // survivor can still steal focus and wedge every later headed run.
@@ -249,14 +250,18 @@ async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellO
     // Helpers that outlived an earlier run (httpd, pywebsocket, ssltunnel,
     // moz-http2) slow every later run without appearing in its output. Both
     // harnesses are affected, so this census is not gated on xpcshellOnly.
-    await reportOrphanedHarnessProcesses(objDir, {
-        reap: options.reapOrphans === true,
+    // Reaping is opt-in per invocation (--reap-orphans) or per repo
+    // (test.reapOrphans: "reap"); a reap is stamped on the verdict line so a
+    // green after one is not mistaken for a green on a quiet machine.
+    const census = await reportOrphanedHarnessProcesses(objDir, {
+        reap: options.reapOrphans === true || projectConfig.test?.reapOrphans === 'reap',
     });
+    addVerdictRunCount('orphans-reaped', census.reaped);
     const forwardedPort = options.machArg
         ? extractForwardedMarionettePort(options.machArg)
         : undefined;
     const effectivePort = options.marionettePort ?? forwardedPort;
-    await ensureTestMarionettePortAvailable(effectivePort, binaryName, options, {
+    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
         xpcshellOnly,
         doctor: options.doctor === true,
     });
@@ -291,6 +296,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // exactly the runs whose only output a `tail` throws away. Closed in
     // `finally`, after the verdict line has already read the path.
     setActiveRunLog(await openRunLog(projectRoot, 'test'));
+    setActivePgidFile(options.pgidFile);
     try {
         await runTestCommandBody(projectRoot, testPaths, options);
     }
@@ -302,6 +308,9 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         throw error;
     }
     finally {
+        // A run that ends under FireForge's control owns no harness group any
+        // more; the file only outlives FireForge when FireForge was killed.
+        await removePgidFile(options.pgidFile);
         await closeActiveRunLog();
     }
 }
@@ -405,7 +414,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
-    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options, buildCheck.objDir);
+    const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig, options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,
@@ -434,17 +443,15 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     if (options.auto === true) {
         extraArgs.push('--auto');
     }
-    if (canaryPath !== undefined) {
+    if (canaryPath !== undefined)
         extraArgs.push(`--timeout=${canaryTimeoutSeconds(projectConfig)}`);
-    }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint
     // above for why). Appended after --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
-    if (forwardedMachArgs.length > 0) {
+    if (forwardedMachArgs.length > 0)
         extraArgs.push(...forwardedMachArgs);
-    }
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
     // Directory arguments mean exactly that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
@@ -482,6 +489,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         headless: options.headless === true,
         ...(options.fullOutput === true ? { fullOutput: true } : {}),
         ...(harnessEnv ? { env: harnessEnv } : {}),
+        pgidFile: options.pgidFile,
     };
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)

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

@@ -26,6 +26,11 @@ export interface TypecheckCommandOptions {
      * issues without waiting for the full set.
      */
     project?: string;
+    /**
+     * Build every project from scratch and write no incremental build info
+     * (`--no-cache`).
+     */
+    noCache?: boolean;
 }
 /**
  * Resolves the project list to type-check. `--project` wins over

package/dist/src/commands/typecheck.js

@@ -88,7 +88,9 @@ async function runTypecheckCommandBody(projectRoot, options) {
     // use so typecheck checks against the current workspace.
     await regenerateStaleGeneratedJsconfig(projectRoot);
     info(`Running typecheck across ${cfg.projects.length} project(s): ${cfg.projects.join(', ')}`);
-    const results = await runTypecheck(projectRoot, cfg);
+    const results = await runTypecheck(projectRoot, cfg, {
+        ...(options.noCache === true ? { noCache: true } : {}),
+    });
     // Fold the EXPORT-TIME authority into this pass. Per-patch lint runs
     // checkJs over the queue's patch-owned modules in relative isolation and
     // resolves imported typedefs differently from the whole-project pass, so
@@ -193,11 +195,15 @@ export function registerTypecheck(program, { getProjectRoot, withErrorHandling }
         .command('typecheck')
         .description('Run TypeScript type checking against project-owned jsconfig.json files (CI-grade, whole-project)')
         .option('--project <path>', 'Override typecheck.projects with a single jsconfig.json path (one-off run)')
+        .option('--no-cache', 'Check every project from scratch; neither read nor write the incremental build info in .fireforge/typecheck/')
         .action(withErrorHandling(async (options) => {
         const opts = {};
         if (options.project !== undefined) {
             opts.project = options.project;
         }
+        if (options.cache === false) {
+            opts.noCache = true;
+        }
         await typecheckCommand(getProjectRoot(), opts);
     }));
 }

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

@@ -58,6 +58,8 @@ export declare function isBackendInvalidatingFile(path: string): boolean;
  * 3. Sets up branding directory if not already done
  * 4. Applies Furnace components if furnace.json exists
  * 5. Generates mozconfig
+ * 6. Runs `mach configure` when a backend-invalidating input, including
+ * the mozconfig just generated, changed since the previous baseline
  *
  * @param projectRoot - Root directory of the project
  * @param paths - Resolved project paths

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

@@ -14,6 +14,7 @@ import { isBrandingSetup, setupBranding } from './branding.js';
 import { isBuildInputPath, isJarManifestPath } from './build-audit.js';
 import { evaluateJarManifestEscalation, formatJarEscalationNotice, } from './build-jar-escalation.js';
 import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
+import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { logApplyWarnings } from './furnace-apply-output.js';
@@ -231,6 +232,40 @@ async function applyFurnaceBeforeBuild(projectRoot) {
     }
     return furnaceApplied;
 }
+/**
+ * Runs the auto-configure step (`mach configure`) against the freshly
+ * generated mozconfig, surfacing the underlying mozbuild error on failure.
+ * @param engineDir - Path to the engine directory
+ * @param triggers - Why the backend is being regenerated, for the notice
+ */
+async function runAutoConfigure(engineDir, triggers) {
+    // Warning severity: this is the "why is this run slow" explanation,
+    // and an info-level line does not survive an agent output filter that
+    // keeps only warnings and errors.
+    notice(`Backend config changed; running backend regeneration first (${triggers}). Backend command: mach configure.`);
+    const configureSpinner = spinner('Running mach configure...');
+    try {
+        const captured = await runMachCapture(['configure'], engineDir);
+        const exitCode = captured.exitCode;
+        if (exitCode !== 0) {
+            configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
+            // Surface the underlying mozbuild error (e.g. UnsortedError)
+            // instead of a bare exit code, since the generic message hid the
+            // actual cause, plus any matched mach-error hints (see the helper).
+            throw buildConfigureFailureError(captured);
+        }
+        configureSpinner.stop('Backend regenerated successfully (mach configure exit code 0)');
+        info('Backend regeneration succeeded; continuing with build.');
+    }
+    catch (error) {
+        if (error instanceof BuildError) {
+            throw error;
+        }
+        configureSpinner.error('mach configure failed');
+        verbose(`Auto-configure error: ${toError(error).message}`);
+        throw new BuildError(`Backend regeneration failed while running mach configure: ${toError(error).message}. Build stopped because continuing would hide the real configure failure.`, 'mach configure', error instanceof Error ? error : undefined);
+    }
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Warns (or refuses) about unexported engine drift the writes below
@@ -239,6 +274,8 @@ async function applyFurnaceBeforeBuild(projectRoot) {
  * 3. Sets up branding directory if not already done
  * 4. Applies Furnace components if furnace.json exists
  * 5. Generates mozconfig
+ * 6. Runs `mach configure` when a backend-invalidating input, including
+ * the mozconfig just generated, changed since the previous baseline
  *
  * @param projectRoot - Root directory of the project
  * @param paths - Resolved project paths
@@ -259,11 +296,16 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         }
     }
     await reportUnexportedDriftBeforeOverwrite(projectRoot, config, options);
-    // Auto-configure: if any backend-invalidating file (moz.build, moz.configure,
-    // Makefile.in) changed since the last successful build, run `mach configure`
-    // before the build step. Prevents incremental builds from silently skipping
-    // work against a stale recursive-make backend.
-    let reconfigured = false;
+    // Auto-configure census: if any backend-invalidating file (moz.build,
+    // moz.configure, Makefile.in) changed since the last successful build,
+    // `mach configure` runs before the build step. Prevents incremental builds
+    // from silently skipping work against a stale recursive-make backend. The
+    // configure itself waits until the mozconfig below has been regenerated:
+    // run earlier, it configured against the previous engine/mozconfig, and a
+    // configs/ fix for a failing configure (a pinned --with-macos-sdk) could
+    // never take effect because the failure stopped the build before the
+    // regeneration.
+    const configureTriggers = [];
     let fullBuildRequired = false;
     let fullBuildReason;
     if (options.previousBaseline) {
@@ -273,35 +315,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         fullBuildRequired = jarEscalation !== undefined;
         fullBuildReason = jarEscalation;
         if (invalidating.length > 0) {
-            // Warning severity: this is the "why is this run slow" explanation,
-            // and an info-level line does not survive an agent output filter that
-            // keeps only warnings and errors.
-            notice(`Backend config changed; running backend regeneration first (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched). Backend command: mach configure.`);
-            const configureSpinner = spinner('Running mach configure...');
-            try {
-                const captured = await runMachCapture(['configure'], paths.engine);
-                const exitCode = captured.exitCode;
-                if (exitCode !== 0) {
-                    configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-                    // Surface the underlying mozbuild error (e.g. UnsortedError)
-                    // instead of a bare exit code, since the generic message hid the
-                    // actual cause, plus any matched mach-error hints (see the helper).
-                    throw buildConfigureFailureError(captured);
-                }
-                else {
-                    configureSpinner.stop('Backend regenerated successfully (mach configure exit code 0)');
-                    info('Backend regeneration succeeded; continuing with build.');
-                    reconfigured = true;
-                }
-            }
-            catch (error) {
-                if (error instanceof BuildError) {
-                    throw error;
-                }
-                configureSpinner.error('mach configure failed');
-                verbose(`Auto-configure error: ${toError(error).message}`);
-                throw new BuildError(`Backend regeneration failed while running mach configure: ${toError(error).message}. Build stopped because continuing would hide the real configure failure.`, 'mach configure', error instanceof Error ? error : undefined);
-            }
+            configureTriggers.push(`${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched`);
         }
     }
     // Clean stories before build to ensure they don't leak into production binary
@@ -333,14 +347,32 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     const furnaceApplied = await applyFurnaceBeforeBuild(projectRoot);
     // Generate mozconfig
     const mozconfigSpinner = spinner('Generating mozconfig...');
+    let mozconfigWritten;
     try {
-        await generateMozconfig(paths.configs, paths.engine, config);
+        mozconfigWritten = await generateMozconfig(paths.configs, paths.engine, config);
         mozconfigSpinner.stop('mozconfig generated');
     }
     catch (error) {
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
+    // A changed mozconfig is itself backend-invalidating. Compare against the
+    // hash the last successful build recorded; a baseline from before that
+    // field existed falls back to whether this run rewrote the file.
+    if (options.previousBaseline) {
+        const recorded = options.previousBaseline.mozconfigHash;
+        const mozconfigChanged = recorded !== undefined
+            ? (await hashEngineFile(paths.engine, 'mozconfig')) !== recorded
+            : mozconfigWritten;
+        if (mozconfigChanged) {
+            configureTriggers.push('engine/mozconfig changed since the last build');
+        }
+    }
+    let reconfigured = false;
+    if (configureTriggers.length > 0) {
+        await runAutoConfigure(paths.engine, configureTriggers.join('; '));
+        reconfigured = true;
+    }
     return {
         furnaceApplied,
         reconfigured,

package/dist/src/core/config-paths.d.ts

@@ -7,7 +7,7 @@ export declare const FIREFORGE_DIR = ".fireforge";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "buildAudit", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "firefox.allowUnverifiedDownload", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "firefox.allowUnverifiedDownload", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "test.reapOrphans", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchLint.forwardRegistration", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

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

@@ -53,6 +53,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'test',
     'test.canaryPath',
     'test.canaryTimeoutSeconds',
+    'test.reapOrphans',
     'externalToolchains',
     'wire',
     'wire.subscriptDir',
@@ -67,6 +68,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint.jsdocClassMethods',
     'patchLint.testAssertionFloor',
     'patchLint.chromeScriptJsDoc',
+    'patchLint.forwardRegistration',
     'patchPolicy',
     'typecheck',
     'typecheck.projects',

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

@@ -45,6 +45,13 @@ export function parseTestBlock(rec, config) {
         }
         out.canaryTimeoutSeconds = canaryTimeout;
     }
+    const reapOrphans = testRec.raw('reapOrphans');
+    if (reapOrphans !== undefined) {
+        if (reapOrphans !== 'report' && reapOrphans !== 'reap') {
+            throw new ConfigError('Config field "test.reapOrphans" must be "report" or "reap"');
+        }
+        out.reapOrphans = reapOrphans;
+    }
     config.test = out;
 }
 /** Parses optional project-specific external toolchain doctor probes. */

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

@@ -376,6 +376,13 @@ function parsePatchLintBlock(rec) {
     if (fileSizeThresholds !== undefined) {
         out.fileSizeThresholds = parsePatchLintFileSizeThresholds(fileSizeThresholds);
     }
+    const forwardRegistration = rec.raw('forwardRegistration');
+    if (forwardRegistration !== undefined) {
+        if (forwardRegistration !== 'support-files' && forwardRegistration !== 'extended') {
+            throw new ConfigError('Config field "patchLint.forwardRegistration" must be one of: support-files, extended');
+        }
+        out.forwardRegistration = forwardRegistration;
+    }
     for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
         const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
         if (gate !== undefined)

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

@@ -53,11 +53,12 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     if (claimedEntries.length === 0) {
         return planUpstreamDiscards(entries);
     }
-    const { computePatched } = await createPatchedContentContext(patchesDir, engineDir);
+    const { computePatched, prefetchBase } = await createPatchedContentContext(patchesDir, engineDir);
     const claimedFiles = [
         ...new Set(claimedEntries.flatMap((entry) => entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file])),
     ];
     const trackedInHead = await listTrackedInHead(engineDir, claimedFiles);
+    await prefetchBase(claimedFiles);
     const computeExpected = async (path) => {
         try {
             return await computePatched(path);

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

@@ -433,15 +433,13 @@ export async function withFileLock(lockPath, operation, options = {}) {
                         continue;
                     }
                 }
-                if (Date.now() >= deadline) {
-                    // The queue is read here, not carried over from the last progress
-                    // probe: the position the wait reached is the one number that says
-                    // whether a larger budget would have helped, and it must not depend
-                    // on a probe having happened to land inside the budget. We are still
-                    // registered at this point. `deregisterWaiter` runs in the `finally`
-                    // below, which is only entered once this refusal has been built.
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
-                }
+                // The probe runs before the deadline check, so a due progress line is
+                // written before the refusal that follows it, never lost to it. On a
+                // slow host (a cold Windows CI runner) the first iteration alone, with
+                // its waiter registration and stale probe, can outlast a short budget;
+                // checked the other way round, the wait timed out having reported
+                // nothing, and an advance that probe would have seen could not extend
+                // the deadline it was about to miss.
                 if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
                     lastProbeAt = Date.now();
                     // Report the budget that is currently in force, not the one
@@ -473,6 +471,15 @@ export async function withFileLock(lockPath, operation, options = {}) {
                         }
                     }
                 }
+                if (Date.now() >= deadline) {
+                    // The queue is read here, not carried over from the last progress
+                    // probe: the position the wait reached is the one number that says
+                    // whether a larger budget would have helped, and it must not depend
+                    // on a probe having happened to land inside the budget. We are still
+                    // registered at this point. `deregisterWaiter` runs in the `finally`
+                    // below, which is only entered once this refusal has been built.
+                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
+                }
                 await sleep(currentPollMs);
                 if (options.pollMaxMs !== undefined) {
                     currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);

package/dist/src/core/forward-registrations.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Public, queue-level entry point to the `forward-registration` census.
+ *
+ * A consumer that keeps its own audit (a ratchet baseline over forward
+ * edges, say) runs the rule's own predicate here instead of mirroring it.
+ * Lives apart from the rule module because it builds the queue context,
+ * which imports the rule back.
+ */
+import type { FireForgeConfig } from '../types/config.js';
+import type { ForwardRegistration, ForwardRegistrationScope } from './patch-lint-forward-registration-extended.js';
+/** Options for {@link findForwardRegistrations}. */
+export interface FindForwardRegistrationsOptions {
+    /**
+     * Which carriers to check. Defaults to `'extended'` (every carrier the
+     * rule can resolve), since a census wants the whole picture whatever the
+     * lint gate is configured to enforce.
+     */
+    scope?: ForwardRegistrationScope;
+    /** Project config, for the queue's patchPolicy ordering context. Optional. */
+    config?: FireForgeConfig;
+}
+/**
+ * Lists every undeclared forward registration in a patch queue: a line a
+ * patch adds (to a test manifest, jar.mn, moz.build or customElements.js)
+ * that names a file only a later-ordered patch creates. Each record carries
+ * the paste-and-run `patch staged-dependency` command that declares it.
+ *
+ * @param patchesDir - The project's `patches/` directory
+ * @param options - Scope and optional config
+ * @returns One record per (patch, carrier file, created file)
+ */
+export declare function findForwardRegistrations(patchesDir: string, options?: FindForwardRegistrationsOptions): Promise<ForwardRegistration[]>;
+export type { ForwardRegistration, ForwardRegistrationKind, ForwardRegistrationScope, } from './patch-lint-forward-registration-extended.js';

package/dist/src/core/forward-registrations.js

@@ -0,0 +1,16 @@
+import { buildPatchQueueContext } from './patch-lint-cross.js';
+import { collectForwardRegistrations } from './patch-lint-forward-registration.js';
+/**
+ * Lists every undeclared forward registration in a patch queue: a line a
+ * patch adds (to a test manifest, jar.mn, moz.build or customElements.js)
+ * that names a file only a later-ordered patch creates. Each record carries
+ * the paste-and-run `patch staged-dependency` command that declares it.
+ *
+ * @param patchesDir - The project's `patches/` directory
+ * @param options - Scope and optional config
+ * @returns One record per (patch, carrier file, created file)
+ */
+export async function findForwardRegistrations(patchesDir, options = {}) {
+    const ctx = await buildPatchQueueContext(patchesDir, options.config);
+    return collectForwardRegistrations(ctx, options.scope ?? 'extended');
+}