@hominis/fireforge 0.47.1 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.48.0
+
+### Engine lifecycle
+
+- `download --force` asks before it discards work. It replaced `engine/` and deleted the backup without checking for applied patches, unexported edits or local commits. When the engine has changed paths or a HEAD off the recorded base commit, it now names the loss (changed paths, how many match the patch queue) and prompts. A non-interactive run refuses with exit 8 and prints the `--yes` form. A clean engine is replaced silently, as before.
+
+### Builds
+
+- `fireforge build` regenerates `engine/mozconfig` before its auto-configure, and a mozconfig that differs from the last successful build's is itself a configure trigger. Configure used to read the previous mozconfig, so a fix in `configs/*.mozconfig` (such as pinning `--with-macos-sdk` after the Xcode 27.0 update) could never take effect. The notice names the trigger. A baseline without `mozconfigHash` falls back to whether this run rewrote the file.
+
+### Smoke runs
+
+- **Default change:** `run --smoke-exit` launches on a fresh temporary profile unless `--profile <path>` names one. It ran against the developer's live profile, so leftover profile state could fail the release gate with nothing wrong in the tree.
+- New `run --profile <path>` and `run --temp-profile`, with or without `--smoke-exit`. FireForge creates the temporary profile, seeds the prefs `mach run` would, and removes it when the run ends, including on failure and SIGINT/SIGTERM. The next `run` sweeps one left by a SIGKILLed run.
+- For the record: mach's own flags are not forwarded. Desktop `mach run` has no `--profile`, and its `--temp-profile` leaks a directory in the objdir on every run.
+
+### Rebase
+
+- `rebase --dry-run` is real. It printed a patch count and exited 0 without testing a hunk. It now replays the queue onto the engine's HEAD in a throwaway index, walking the real run's context ladder, prints a verdict per patch (clean, reduced context, or reject with the files) and a tally, and exits 6 on any reject. `engine/` is never written.
+- The "from" version is the semantically oldest patch stamp, not the lexically smallest, so `153.10.0esr` no longer counts as older than `153.2.0esr`. A queue with several stamps prints the spread.
+- The header warns when `state.json`'s `downloadedVersion` is not the pinned target, meaning the download step has not run yet.
+
+### Performance
+
+- The worktree ownership scan behind `status`, `verify`, `doctor`, `import` and `discard` runs four git processes instead of one or more per managed file. On the Hominis tree (1,606 managed files) that was 1,625 spawns. `status --ownership` went from 13 to 16 s down to 5.7 s, and `verify` from 15 s to 7.6 s. Output is byte-identical to 0.47.1.
+- The batched untracked listing uses `ls-files -z`, so a non-ASCII name inside a collapsed directory is no longer expanded to a quoted path that names no file.
+
+### Typecheck and checkJs
+
+- The per-test-file checkJs programs share one parse of each lib, shim and helper file per run. On the Hominis queue (467 programs) the pass went from 66 to 85 s down to 22 to 25 s, with identical findings. This speeds up `typecheck` and every `lint --per-patch`, `export` or `re-export` that misses the lint cache.
+- `fireforge typecheck` keeps incremental build info per project in `.fireforge/typecheck/`, keyed so a shim, compiler or FireForge change never replays a stale verdict. New `typecheck --no-cache` checks from scratch and writes nothing. Nothing is written under `engine/`.
+- On the Hominis tree `typecheck` went from 93.8 s to 30.2 s.
+- For the record: the projects are not run in a worker pool. They took 6 of the 93.8 s; the per-file checkJs pass was the cost.
+
+### Re-export
+
+- A one-patch `re-export` roots its checkJs program at the patches it re-exports, as `lint --per-patch --patches` already did, instead of type-checking the whole queue. Cross-patch imports still resolve. On Hominis a cold `re-export <patch> --dry-run` went from 76.7 s to 8.0 s.
+- The queue lint context parses each patch once instead of once per created file: 3 to 4.4 s down to 0.3 s on 401 patches. Shared by `lint --per-patch`, `re-export`, `export` and `typecheck`.
+- `re-export` names its lint scope before the wait and prints a line when it builds a checkJs program. The elapsed time now includes the context build.
+
+### Patch queue and lint
+
+- New opt-in `patchLint.forwardRegistration: "extended"` widens `forward-registration` beyond test-manifest `support-files` to jar.mn lines, moz.build path tokens, test-manifest sections and `head`, and `customElements.js` chrome URLs. On the Hominis queue it finds 937 edges across 6 patches. The default (`"support-files"`) is unchanged. Each finding prints a `patch staged-dependency --add --kind registration` command, tested to quiet the queue without leaving `staged-dependency-unused` behind.
+- New public `findForwardRegistrations(patchesDir, { scope })` returns the same census as structured records.
+- New `lint --per-patch --notices summary|full`. `summary` prints one line per check instead of every NOTICE row (about 430 on a green Hominis queue). `full` stays the default and is unchanged. Errors, warnings and `--report` JSON are unaffected.
+
+### Programmatic API
+
+- New public `filesMeasuredByFileTooLarge(patchText)`: the files the `file-too-large` rule measures, which the rule itself now uses. A size-waiver audit can use the rule's own predicate. It covers the JS files a patch creates, not every created file, so `detectNewFilesInDiff` was not exported for this.
+
+### Doctor
+
+- New macOS `doctor` check: can the bootstrapped clang link against the SDK the build will use? Xcode 27.0 ships a `libSystem.tbd` the Mozilla clang/lld 21.1.8 rejects, and `mach configure` died with exit 5 without naming the cause. The check resolves the SDK from `engine/mozconfig` the way mach does, links a one-line C program, and on failure warns with clang's first error and the installed SDKs. It does nothing off macOS or without a bootstrapped clang.
+
 ## 0.47.0
 
 ### Test preflight

package/dist/bin/fireforge.js

@@ -13,6 +13,7 @@ import { emitKilledVerdict } from '../src/commands/test-verdict.js';
 import { forceReleaseHeldLocksForSignal } from '../src/core/file-lock.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
 import { closeActiveRunLog } from '../src/core/run-log.js';
+import { removeActiveRunProfiles } from '../src/core/run-profile.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
 import { waitForActiveChildShutdown } from '../src/utils/process.js';
@@ -114,6 +115,10 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // loses the race to the exit below. Only a kill FireForge never saw
             // may leave the file behind.
             .then(() => removeActivePgidFile().catch(() => undefined))
+            // A `run --temp-profile` (the `--smoke-exit` default) owes the removal
+            // of its profile directory; the command's finally loses this race too.
+            // Runs after child shutdown, so the browser no longer holds the files.
+            .then(() => removeActiveRunProfiles())
             .finally(() => {
             exitAfterStdioFlush(exitCode);
         });

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.47.1",
-  "commit": "11b30621b46142df7a8035ae7b9e8a13936787bb",
-  "shortCommit": "11b30621b461",
+  "version": "0.48.0",
+  "commit": "9215c35e3907f14cc03379fb04c867ebd954085a",
+  "shortCommit": "9215c35e3907",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-09-13T19:20:10.389Z"
+  "buildTime": "2026-09-22T21:34:33.874Z"
 }

package/dist/src/commands/doctor-macos-sdk.d.ts

@@ -0,0 +1,8 @@
+import type { DoctorCheck } from '../types/commands/index.js';
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** The bootstrapped clang mach uses on macOS. */
+export declare function bootstrappedClangPath(): string;
+/** Runs the check for one engine directory. */
+export declare function checkMacosSdkLink(engineDir: string): Promise<DoctorCheck>;
+/** Registry entry for the doctor runner. */
+export declare const MACOS_SDK_LINK_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-macos-sdk.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Doctor check: can the bootstrapped clang link against the macOS SDK the
+ * build will use?
+ *
+ * An Xcode update can ship an SDK whose `.tbd` stubs the pinned toolchain
+ * cannot read (Xcode 27.0's `libSystem.tbd` lists `arm64e.x1-macos`
+ * targets that clang/lld 21.1.8 rejects as "unknown architecture"). `mach
+ * configure` then dies at "checking what kind of list files are supported
+ * by the linker" with exit 5, and neither `build` nor `doctor` named the
+ * cause: the operator had to read `config.log`. This check links a trivial
+ * C program with the bootstrapped clang against the SDK the mozconfig
+ * selects, and on failure names the mismatch and lists the SDKs installed.
+ *
+ * darwin only, and only when a bootstrapped clang exists. A warning, never
+ * a failure: the SDK may be one the operator is about to replace.
+ */
+import { existsSync } from 'node:fs';
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mozbuildStateDir } from '../core/toolchain-preflight.js';
+import { toError } from '../utils/errors.js';
+import { exec } from '../utils/process.js';
+import { ok, warning } from './doctor-check-core.js';
+const CHECK_NAME = 'macOS SDK links with the bootstrapped clang';
+/** The bootstrapped clang mach uses on macOS. */
+export function bootstrappedClangPath() {
+    return join(mozbuildStateDir(), 'clang', 'bin', 'clang');
+}
+/**
+ * Sources a mozconfig with `ac_add_options` stubbed to print the
+ * `--with-macos-sdk=` value, which is how mach reads it. A mozconfig is a
+ * shell script: an SDK chosen by shell logic (the first of several
+ * candidates that exists) has no literal value to grep.
+ */
+const SDK_FROM_MOZCONFIG_SCRIPT = [
+    'ac_add_options() { for a in "$@"; do case "$a" in --with-macos-sdk=*) printf "%s\\n" "${a#--with-macos-sdk=}";; esac; done; }',
+    'mk_add_options() { :; }',
+    '. "$1"',
+].join('\n');
+/**
+ * Resolves the SDK the generated mozconfig selects (`--with-macos-sdk`),
+ * falling back to `xcrun --show-sdk-path`, which is what configure
+ * auto-detects when the mozconfig names none.
+ */
+async function resolveSelectedSdk(engineDir) {
+    const mozconfig = join(engineDir, 'mozconfig');
+    if (existsSync(mozconfig)) {
+        const sourced = await exec('/bin/sh', ['-c', SDK_FROM_MOZCONFIG_SCRIPT, 'sh', mozconfig], {
+            cwd: engineDir,
+            env: { topsrcdir: engineDir },
+            timeout: 10_000,
+        });
+        if (sourced.exitCode !== 0) {
+            return {
+                error: `engine/mozconfig failed while selecting the SDK: ${firstLine(sourced.stderr) ?? `exit ${sourced.exitCode}`}`,
+            };
+        }
+        const selected = sourced.stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .pop();
+        if (selected !== undefined)
+            return { sdk: selected, source: 'mozconfig' };
+    }
+    const xcrun = await exec('xcrun', ['--show-sdk-path'], { timeout: 10_000 });
+    const path = xcrun.stdout.trim();
+    if (xcrun.exitCode !== 0 || path.length === 0) {
+        return { error: `xcrun --show-sdk-path failed: ${firstLine(xcrun.stderr) ?? 'no output'}` };
+    }
+    return { sdk: path, source: 'xcrun' };
+}
+function firstLine(text) {
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+}
+/** Every macOS SDK directory on the host FireForge knows where to look for. */
+async function listInstalledSdks() {
+    const roots = [mozbuildStateDir(), '/Library/Developer/CommandLineTools/SDKs'];
+    const developer = await exec('xcode-select', ['-p'], { timeout: 10_000 });
+    if (developer.exitCode === 0 && developer.stdout.trim().length > 0) {
+        roots.push(join(developer.stdout.trim(), 'Platforms/MacOSX.platform/Developer/SDKs'));
+    }
+    const found = [];
+    for (const root of roots) {
+        try {
+            for (const entry of await readdir(root)) {
+                if (/^MacOSX.*\.sdk$/.test(entry))
+                    found.push(join(root, entry));
+            }
+        }
+        catch {
+            // A root that does not exist lists nothing.
+        }
+    }
+    return found;
+}
+/**
+ * Links `int main(void){return 0;}` with the bootstrapped clang (through
+ * its bundled lld, as the build does) against `sdk`, in a temp directory.
+ * @returns undefined on success, else the first error line clang printed
+ */
+async function probeSdkLink(clang, sdk) {
+    const dir = await mkdtemp(join(tmpdir(), 'fireforge-sdk-probe-'));
+    try {
+        await writeFile(join(dir, 'probe.c'), 'int main(void) { return 0; }\n');
+        const lld = existsSync(join(clang, '..', 'ld64.lld')) ? ['-fuse-ld=lld'] : [];
+        const linked = await exec(clang, ['-isysroot', sdk, ...lld, '-o', join(dir, 'probe'), join(dir, 'probe.c')], { timeout: 30_000 });
+        if (linked.exitCode === 0)
+            return undefined;
+        const output = `${linked.stderr}\n${linked.stdout}`;
+        return (output
+            .split('\n')
+            .map((line) => line.trim())
+            .find((line) => /error:/.test(line)) ??
+            firstLine(output) ??
+            `exit ${linked.exitCode}`);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}
+/** Runs the check for one engine directory. */
+export async function checkMacosSdkLink(engineDir) {
+    const selected = await resolveSelectedSdk(engineDir);
+    const fix = 'Pin an SDK the bootstrapped toolchain can link in configs/darwin.mozconfig ' +
+        '(ac_add_options --with-macos-sdk=<path>), then run fireforge build.';
+    if ('error' in selected) {
+        return warning(CHECK_NAME, selected.error, fix);
+    }
+    let failure;
+    try {
+        failure = await probeSdkLink(bootstrappedClangPath(), selected.sdk);
+    }
+    catch (error) {
+        failure = toError(error).message;
+    }
+    if (failure === undefined) {
+        return ok(CHECK_NAME, `OK (${selected.sdk}, from ${selected.source})`);
+    }
+    const installed = await listInstalledSdks();
+    return warning(CHECK_NAME, `The bootstrapped clang cannot link against ${selected.sdk} (from ${selected.source}): ${failure}. ` +
+        `mach configure fails at its linker probe the same way. Installed SDKs: ` +
+        (installed.length > 0 ? installed.join(', ') : 'none found') +
+        '.', fix);
+}
+/** Registry entry for the doctor runner. */
+export const MACOS_SDK_LINK_DOCTOR_CHECK = {
+    name: CHECK_NAME,
+    skipIf: (ctx) => process.platform !== 'darwin' || !ctx.engineExists || !existsSync(bootstrappedClangPath()),
+    run: (ctx) => checkMacosSdkLink(ctx.paths.engine),
+};

package/dist/src/commands/doctor.js

@@ -17,6 +17,7 @@ import { findExecutable } from '../utils/process.js';
 import { failure, ok, warning } from './doctor-check-core.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
+import { MACOS_SDK_LINK_DOCTOR_CHECK } from './doctor-macos-sdk.js';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
 import { PATCH_MANIFEST_CONSISTENCY_CHECK } from './doctor-patch-manifest.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
@@ -258,6 +259,7 @@ const DOCTOR_CHECKS = [
         },
     },
     ORPHANED_HARNESS_DOCTOR_CHECK,
+    MACOS_SDK_LINK_DOCTOR_CHECK,
     {
         name: 'Patches directory exists',
         run: async (ctx) => {

package/dist/src/commands/download.js

@@ -9,7 +9,7 @@ import { downloadFirefoxSource, formatBytes, sweepOrphanedEngineWorkDirs, } from
 import { clearAppliedFurnaceState } from '../core/furnace-config.js';
 import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRepository, } from '../core/git.js';
 import { restoreTrackedPath } from '../core/git-file-ops.js';
-import { getDirtyFiles } from '../core/git-status.js';
+import { getDirtyFiles, getWorkingTreeStatus } from '../core/git-status.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { formatMajorVersionHopNotice } from '../core/toolchain-preflight.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
@@ -17,6 +17,7 @@ import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, pathExistsStrict, removeDir } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+import { confirmDirtyEngineReset } from './rebase/confirm.js';
 /**
  * Collects the set of patch-touched files from the manifest.
  * Returns an empty set when the patches directory or manifest is absent.
@@ -35,6 +36,47 @@ async function getPatchTouchedFiles(patchesDir) {
     }
     return files;
 }
+/**
+ * Describes what a forced replacement would discard from an existing
+ * engine: changed paths against HEAD (tracked edits, applied patches, new
+ * untracked files; ignored paths such as the objdir are not work), and a
+ * HEAD that moved off the recorded base commit. Returns `undefined` when
+ * nothing would be lost, including an engine that is not a git repository
+ * or has no commit yet: that is the broken tree `--force` exists to replace.
+ */
+async function describeForcedReplacementLoss(engineDir, patchesDir, baseCommit) {
+    if (!(await isGitRepository(engineDir)))
+        return undefined;
+    let head;
+    try {
+        head = await getHead(engineDir);
+    }
+    catch (error) {
+        if (isMissingHeadError(error))
+            return undefined;
+        throw error;
+    }
+    const entries = await getWorkingTreeStatus(engineDir);
+    const headMoved = baseCommit !== undefined && head !== baseCommit;
+    if (entries.length === 0 && !headMoved)
+        return undefined;
+    const parts = [];
+    if (entries.length > 0) {
+        const patchFiles = [...(await getPatchTouchedFiles(patchesDir))];
+        const claimed = entries.filter((entry) => entry.file.endsWith('/')
+            ? patchFiles.some((file) => file.startsWith(entry.file))
+            : patchFiles.includes(entry.file)).length;
+        const unclaimed = entries.length - claimed;
+        parts.push(`engine/ has ${entries.length} changed path(s) against HEAD: ` +
+            `${claimed} match the patch queue, ${unclaimed} do not` +
+            (unclaimed > 0 ? ' (unexported work that exists nowhere else).' : '.'));
+    }
+    if (headMoved) {
+        parts.push(`engine/ HEAD ${head.slice(0, 12)} is not the recorded base commit ${baseCommit.slice(0, 12)}, so commits made in engine/ are discarded too.`);
+    }
+    parts.push('--force replaces the whole directory.');
+    return parts.join(' ');
+}
 /**
  * Restores patch-touched files to their committed (HEAD) state so that a
  * subsequent `fireforge import` does not see spurious uncommitted changes.
@@ -279,7 +321,8 @@ export async function downloadCommand(projectRoot, options) {
     const paths = getProjectPaths(projectRoot);
     // Captured before any state update so the post-download major-hop
     // notice compares against what was actually on disk until now.
-    const previousVersion = (await loadState(projectRoot)).downloadedVersion;
+    const previousState = await loadState(projectRoot);
+    const previousVersion = previousState.downloadedVersion;
     info(`Firefox version: ${version}`);
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
     // A legitimate holder of this lock runs for 10+ minutes (download +
@@ -381,6 +424,23 @@ export async function downloadCommand(projectRoot, options) {
                 }
                 throw new EngineExistsError(paths.engine);
             }
+            // The replacement deletes the old tree once the new one is active,
+            // so anything not in patches/ is gone for good. Ask before fetching.
+            const loss = await describeForcedReplacementLoss(paths.engine, paths.patches, previousState.baseCommit);
+            if (loss !== undefined &&
+                !(await confirmDirtyEngineReset({
+                    engineDir: paths.engine,
+                    yes: options.yes ?? false,
+                    dirty: true,
+                    refusalDetail: loss,
+                    nonInteractiveCommand: 'fireforge download --force --yes',
+                    argumentName: '--yes',
+                    warningMessage: loss,
+                    promptMessage: 'Discard the existing engine/ and download a fresh one?',
+                    cancelMessage: 'Download cancelled; engine/ left untouched',
+                }))) {
+                return;
+            }
             replacementEngineDir = `${paths.engine}.replacement-${randomUUID()}`;
             backupEngineDir = `${paths.engine}.backup-${randomUUID()}`;
             installEngineDir = replacementEngineDir;
@@ -436,7 +496,8 @@ export function registerDownload(program, { getProjectRoot, withErrorHandling })
     program
         .command('download')
         .description('Download Firefox source')
-        .option('-f, --force', 'Force re-download, removing existing source')
+        .option('-f, --force', 'Force re-download; discards engine/ including applied patches and unexported edits')
+        .option('-y, --yes', 'With --force: replace a dirty engine/ without the confirmation prompt')
         .action(withErrorHandling(async (options) => {
         await downloadCommand(getProjectRoot(), pickDefined(options));
     }));

package/dist/src/commands/import.js

@@ -30,13 +30,16 @@ function isSafeIoFallback(error) {
     const code = getNodeErrorCode(error);
     return code !== undefined && SAFE_IO_FALLBACK_CODES.has(code);
 }
-/** Concurrency bound for per-file classification (each call spawns git). */
+/** Concurrency bound for per-file classification (reads and patch replays). */
 const UNMANAGED_CLASSIFY_CONCURRENCY = 8;
 async function getUnmanagedDirtyFiles(engineDir, patchesDir, dirtyFiles) {
     // One manifest+patch-discovery load for the whole batch (the per-call
     // computePatchedContent re-read everything for every file), and bounded
     // concurrency instead of an unbounded Promise.all over git spawns.
-    const { computePatched: computeExpected } = await createPatchedContentContext(patchesDir, engineDir);
+    const { computePatched: computeExpected, prefetchBase } = await createPatchedContentContext(patchesDir, engineDir);
+    // One `git cat-file --batch` for every HEAD blob instead of a `git show`
+    // per dirty file.
+    await prefetchBase(dirtyFiles);
     const classifications = await mapWithConcurrency(dirtyFiles, UNMANAGED_CLASSIFY_CONCURRENCY, async (file) => {
         try {
             const [expected, exists] = await Promise.all([

package/dist/src/commands/lint-per-patch.js

@@ -138,7 +138,7 @@ const SUPPRESSED_SIZE_CHECKS = new Set([
  * filename-prefixed issue rows, and the cache writes, all in the same
  * sequence a serial run produced. Returns the run tallies.
  */
-async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
+async function applyPerPatchResults(subset, results, issues, checkJs, cache, heldNotices) {
     const totals = {
         linted: 0,
         skipped: 0,
@@ -190,6 +190,10 @@ async function applyPerPatchResults(subset, results, issues, checkJs, cache) {
         for (const suppressedIssue of result.suppressedIssues) {
             if (!SUPPRESSED_SIZE_CHECKS.has(suppressedIssue.check))
                 continue;
+            if (heldNotices !== undefined) {
+                heldNotices.push({ check: suppressedIssue.check, patch: patch.filename, suppressed: true });
+                continue;
+            }
             info(`NOTICE [${suppressedIssue.check}] ${patch.filename}: suppressed by lintIgnore — ${suppressedIssue.message}`);
         }
         totals.suppressed += result.suppressedIssues.length;
@@ -232,7 +236,10 @@ async function lintSubsetConcurrently(subset, lintCtx) {
  * prints the per-patch summary, and applies the failure criteria
  * (errors, `--max-warnings`) by throwing GeneralError.
  */
-function reportPerPatchOutcome(issues, linted, skipped, options) {
+function reportPerPatchOutcome(issues, linted, skipped, options, heldNotices) {
+    if (heldNotices !== undefined) {
+        reportNoticeSummary(heldNotices, issues);
+    }
     if (issues.length === 0) {
         if (linted === 0 && skipped > 0) {
             info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
@@ -247,8 +254,10 @@ function reportPerPatchOutcome(issues, linted, skipped, options) {
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
     const notices = issues.filter((i) => i.severity === 'notice');
-    for (const issue of notices)
-        info(`NOTICE ${formatPatchLintIssue(issue)}`);
+    if (heldNotices === undefined) {
+        for (const issue of notices)
+            info(`NOTICE ${formatPatchLintIssue(issue)}`);
+    }
     for (const issue of warnings)
         warn(formatPatchLintIssue(issue));
     for (const issue of errors)
@@ -272,6 +281,34 @@ function reportPerPatchOutcome(issues, linted, skipped, options) {
         outro('Lint passed');
     }
 }
+/**
+ * `--notices summary`: one line per check instead of one per finding, for
+ * a green queue whose hundreds of NOTICE lines are reviewed waivers and
+ * under-threshold measurements. The full list stays in `--report`.
+ * Errors and warnings are never summarised.
+ */
+function reportNoticeSummary(heldNotices, issues) {
+    const byCheck = new Map();
+    const tally = (check, patch, suppressed) => {
+        const entry = byCheck.get(check) ?? { count: 0, suppressed: 0, patches: new Set() };
+        entry.count += 1;
+        if (suppressed)
+            entry.suppressed += 1;
+        entry.patches.add(patch);
+        byCheck.set(check, entry);
+    };
+    for (const held of heldNotices)
+        tally(held.check, held.patch, held.suppressed);
+    for (const issue of issues) {
+        if (issue.severity !== 'notice')
+            continue;
+        tally(issue.check, issue.patches?.[0] ?? issue.file.split(' :: ')[0] ?? issue.file, false);
+    }
+    for (const [check, entry] of [...byCheck].sort(([a], [b]) => a.localeCompare(b))) {
+        const suppressed = entry.suppressed > 0 ? `, ${entry.suppressed} of them suppressed by lintIgnore` : '';
+        info(`NOTICE [${check}]: ${entry.count} across ${entry.patches.size} patch(es)${suppressed} (see --report)`);
+    }
+}
 /**
  * Resolves the `--patches <name…>` subset filter against the manifest,
  * matching each requested name tolerantly (exact filename, filename ±
@@ -394,7 +431,8 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
         engineHeadSha,
         checkJs,
     });
-    const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache);
+    const heldNotices = options.notices === 'summary' ? [] : undefined;
+    const { linted, skipped, cacheDirty, reusedCacheEntries, suppressed } = await applyPerPatchResults(subset, results, issues, checkJs, cache, heldNotices);
     for (const issue of lintPatchQueue(ctx)) {
         if (isSubset && !subsetTouchedFiles.has(issue.file))
             continue;
@@ -411,5 +449,5 @@ async function lintPerPatchInner(projectRoot, paths, options = {}) {
     if (options.report !== undefined) {
         await writePerPatchLintReport(options.report, subset, results);
     }
-    reportPerPatchOutcome(issues, linted, skipped, options);
+    reportPerPatchOutcome(issues, linted, skipped, options, heldNotices);
 }

package/dist/src/commands/lint-per-run-checkjs.d.ts

@@ -52,6 +52,9 @@ export interface PerRunCheckJs {
     /** True when this file kind participates in the run's checkJs surface
      *  (`.sys.mjs`, plus test scripts when `checkJsTestFiles` is on). */
     isRelevant: (file: string) => boolean;
+    /** The program's roots under `rootScopePatches`, or undefined for the
+     *  whole queue. A file outside it is resolvable but never checked. */
+    rootScope: ReadonlySet<string> | undefined;
 }
 /**
  * Builds the per-run checkJs program controller when `patchLint.checkJs` is

package/dist/src/commands/lint-per-run-checkjs.js

@@ -97,5 +97,6 @@ export function buildPerRunCheckJs(projectRoot, paths, config, ctx, rootScopePat
             return issues;
         },
         isRelevant: (file) => file.endsWith('.sys.mjs') || (testFilesEnabled && isTestScriptFile(file)),
+        rootScope: scopedRoots,
     };
 }

package/dist/src/commands/lint.js

@@ -236,6 +236,9 @@ function validateLintFlags(options) {
     if (options.report !== undefined && !options.perPatch) {
         throw new InvalidArgumentError('--report requires --per-patch.', '--report');
     }
+    if (options.notices !== undefined && !options.perPatch) {
+        throw new InvalidArgumentError('--notices requires --per-patch.', '--notices');
+    }
 }
 /**
  * Aggregate-mode patch-size softening: when the linted diff is every
@@ -499,6 +502,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
         .option('--report <path>', 'With --per-patch, write a machine-readable JSON report (per-patch size metrics, tier, thresholds, issues, and lintIgnore-suppressed issues) to <path>.')
+        .option('--notices <mode>', 'With --per-patch: "full" (default) prints every NOTICE line; "summary" prints one line per check with its count and patch count. The full list stays in --report. Errors and warnings always print in full.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -526,6 +530,12 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.report !== undefined) {
             lintOptions.report = options.report;
         }
+        if (options.notices !== undefined) {
+            if (options.notices !== 'summary' && options.notices !== 'full') {
+                throw new InvalidArgumentError(`--notices must be "summary" or "full" (got "${options.notices}").`, '--notices');
+            }
+            lintOptions.notices = options.notices;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
     const lintCache = lint

package/dist/src/commands/re-export-lint.d.ts

@@ -44,8 +44,23 @@ export interface ReExportLintContext {
     /** The pre-existing-queue-errors note is printed once per invocation. */
     queueBaselineWarned: boolean;
 }
-/** Builds the once-per-invocation lint context. */
-export declare function buildReExportLintContext(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, noCache: boolean): Promise<ReExportLintContext>;
+/**
+ * Builds the once-per-invocation lint context.
+ *
+ * The checkJs program is rooted at the patches being re-exported, exactly as
+ * `lint --per-patch --patches` roots it at its subset: the rest of the
+ * queue stays resolvable, so cross-patch imports type-check identically,
+ * but nothing else is parsed or checked. Unscoped, a one-patch re-export
+ * that missed the lint cache type-checked the whole queue (76 s on a
+ * 401-patch queue) to report on one patch.
+ *
+ * @param projectRoot - FireForge project root
+ * @param paths - Resolved project paths
+ * @param config - Loaded configuration
+ * @param noCache - Skip the per-patch lint result cache (`--no-cache`)
+ * @param scopePatches - Filenames of the patches this run re-exports
+ */
+export declare function buildReExportLintContext(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, noCache: boolean, scopePatches: ReadonlySet<string>): Promise<ReExportLintContext>;
 /** Fresh lint payload carried to the post-write cache store. */
 export interface ReExportLintResult {
     issues: PatchLintIssue[];

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

@@ -32,15 +32,39 @@ import { reportPatchLintOutcome } from './export-shared.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 import { projectEntryBody } from './patch/entry-projection.js';
 import { formatForwardImportRemedy } from './re-export-scan.js';
-/** Builds the once-per-invocation lint context. */
-export async function buildReExportLintContext(projectRoot, paths, config, noCache) {
+/**
+ * Builds the once-per-invocation lint context.
+ *
+ * The checkJs program is rooted at the patches being re-exported, exactly as
+ * `lint --per-patch --patches` roots it at its subset: the rest of the
+ * queue stays resolvable, so cross-patch imports type-check identically,
+ * but nothing else is parsed or checked. Unscoped, a one-patch re-export
+ * that missed the lint cache type-checked the whole queue (76 s on a
+ * 401-patch queue) to report on one patch.
+ *
+ * @param projectRoot - FireForge project root
+ * @param paths - Resolved project paths
+ * @param config - Loaded configuration
+ * @param noCache - Skip the per-patch lint result cache (`--no-cache`)
+ * @param scopePatches - Filenames of the patches this run re-exports
+ */
+export async function buildReExportLintContext(projectRoot, paths, config, noCache, scopePatches) {
     const patchQueueCtx = (await pathExists(paths.patches))
         ? await buildPatchQueueContext(paths.patches, config)
         : undefined;
     const checkJs = patchQueueCtx
-        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx)
+        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx, scopePatches)
         : undefined;
     const cache = noCache ? undefined : await loadPerPatchLintCache(projectRoot);
+    if (patchQueueCtx) {
+        // The queue rules and the projection below read every patch, so the
+        // wait is named rather than left behind one spinner line.
+        info(`Lint scope: queue rules over all ${patchQueueCtx.entries.length} patch(es); ` +
+            `checkJs rooted at the ${scopePatches.size} re-exported patch(es); ` +
+            (cache === undefined
+                ? 'lint cache off (--no-cache).'
+                : `lint cache ${Object.keys(cache.entries).length === 0 ? 'empty' : 'loaded'}.`));
+    }
     const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
     return {
         projectRoot,
@@ -123,7 +147,12 @@ export async function lintReExportedPatch(args) {
     lintOptions.onSuppressed = (suppressed) => suppressedIssues.push(...suppressed);
     if (checkJs) {
         const created = checkJsFilesInDiff(diffContent, checkJs);
-        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f));
+        if (created.size > 0) {
+            info(`checkJs: type-checking ${created.size} file(s) of ${patch.filename} (lint cache ${cache ? 'miss' : 'off'}).`);
+        }
+        // A file the scoped program does not root at would be resolvable but
+        // never checked, so it takes the per-patch build too.
+        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f) && (checkJs.rootScope?.has(f) ?? true));
         if (allKnown) {
             // Slice this patch's findings out of the one queue-wide program.
             lintOptions.precomputedCheckJs = await checkJs.sliceFor(created);