@hominis/fireforge 0.34.1 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.35.0
+
+- Fixed the **patch symlink-escape guard being dead code**: the check meant to reject patches targeting a symlink that points outside `engine/` normalized the path text with `resolve()` but never followed the link, so it could not reject anything (the path had already passed the relative-containment check). Target validation now resolves the physical write destination with `realpath` — covering the direct symlink, a _dangling_ symlink (whose destination a write would still create), and a symlinked parent directory — and compares it against the real engine root. Regression tests pin all three escape shapes plus the two accept shapes (inside-tree link, plain new file).
+- Fixed `stampPatchVersions` mutating `patches.json` **without the shared patch-directory lock**: version stamping after `re-export --stamp` and at rebase completion now runs the manifest read-modify-write under `withPatchDirectoryLock`, so a concurrent export/reorder/metadata update can no longer interleave with the stamp and lose version stamps or clobber another manifest change. The function documents that the lock is not reentrant (callers must not already hold it), and a regression test pins that a held lock blocks the stamp until release.
+- Switched authoritative-state existence probes from the error-swallowing `pathExists` to `pathExistsStrict`, so an EACCES/EPERM now surfaces as an error instead of masquerading as "missing": the patches manifest probes (`loadPatchesManifestState`, `mutatePatchRowsInManifest`, the renumber phase checks, and `removePatchFileAndManifest`), the Firefox archive cache probes (`cacheEntryExists` and the tarball/metadata check in `validateCachedArchive` — a permission error probing the cache no longer reads as "invalid cache" and silently triggers a re-download into a directory that cannot be written anyway), and `isGitRepository` (an unreadable engine checkout no longer reports as "not a git repository", which used to route operators toward re-download advice). Soft probes (lock-file cleanup, optional-file checks) intentionally keep the forgiving behavior.
+- Added a **tar extraction preflight** to `extractTarXz`: before anything is written to disk, the archive listing (`tar -tf` for member names, `tar -tvf` for link targets, `LC_ALL=C`) is validated and the archive is rejected if any member name is absolute (POSIX or Windows drive/backslash rooted) or contains a `..` segment, or if any symlink/hardlink target is absolute or `..`-escaping (a relative target without `..` cannot leave the extraction root). Modern GNU tar / bsdtar refuse most of these shapes at extraction time already; the preflight makes the guarantee explicit and independent of the host tar's defaults. Each listing pass costs one full decompression, so the two run **concurrently** and overlap almost perfectly. Measured on a real Firefox ESR 140.9 source tarball (601 MB, bsdtar, macOS): each listing takes ~22 s, both concurrently still ~22 s wall, and extraction itself 58 s — so the preflight adds ~22 s (~38%) to this one-time step of `fireforge download`, versus ~44 s if the listings ran sequentially. Member names are deliberately taken from `-tf` (where the whole line is the name) rather than parsed out of the `-tvf` columns, because the adjacent uname/gname fields are attacker-controlled in a crafted archive and a date-shaped owner name could shift the column boundary and hide an absolute member name from the check. `ExtractionError.userMessage` now includes the underlying reason (this also surfaces the previously hidden tar exit code/stderr detail for ordinary extraction failures).
+- Extended the CI matrix with a **cross-platform unit-test subset**: the macOS and Windows smoke jobs now also run the path/fs/process/git/file-lock unit suites (previously Ubuntu-only via `release:check`), and the README's "never tested on Windows" claim was replaced with an accurate statement of what CI does and does not cover there.
+- Consolidated the mutation lifecycle safety design into an internal architecture doc, **`docs/lifecycle-invariants.md`**: the six invariants the destructive-operation contract, file locks, furnace rollback, signal-critical sections, and the bin signal pipeline uphold together, who owns which piece, the end-to-end SIGINT/SIGTERM sequence, and a decision table for choosing the right primitive for a new mutating command. Added **scenario tests for a signal during a compound mutation** (`signal-compound-mutation-scenario.test.ts`) that replicate the bin-handler composition exactly: exit is held until an in-flight "engine apply + state persist" pair completes, the hold is bounded so a stuck section cannot postpone exit forever, and furnace rollback + critical-section drain + lock force-release compose correctly.
+- Fixed `discard <directory>/` producing **doubled slashes** in the directory-fallback output: a trailing slash on the input was passed through and every message appended `/` again (`stories/furnace//`). The input is now normalized once on entry to the fallback. This was not purely cosmetic — the doubled slash also broke the Furnace-managed-prefix comparison when discarding a _parent_ directory of a managed prefix with a trailing-slash input, silently dropping the "managed by Furnace" warning; regression tests pin both the messages and the warning.
+- The installed-package smoke tests now **skip with a clear message when no npm executable is available** (npm_execpath unset and `npm` not on PATH, e.g. a container with only node + node_modules) instead of failing all three with an opaque `spawn npm ENOENT`.
+- The release workflow now installs the **exact npm version pinned in package.json's `packageManager` field** (derived at run time so the two cannot drift) instead of `npm@latest`, making releases reproducible and keeping a fresh npm major from changing publish behavior unreviewed.
+- Added a **toolchain preflight for Firefox source hops** (152.0b7 → 153.0b8 source-refresh drill: after `download --force` moved the engine to a new major, the first `fireforge build` died ~8s into `mach configure` with `cbindgen version 0.29.1 is too old. At least version 0.29.4 is required.` — and mach's own remediation text names `./mach bootstrap`, the wrong tool for a FireForge-managed repo). Three layers: (1) `fireforge download` now prints a one-line nudge when the downloaded MAJOR version differs from the previously recorded one ("toolchain minimums may have moved — consider running `fireforge bootstrap`"; quiet on first downloads and same-major re-downloads, and also emitted on the resume path); (2) `fireforge build` runs a cheap fail-soft preflight before any pre-build work, comparing the minimums the tree itself declares (`cbindgen_min_version` in `build/moz.configure/bindgen.configure`, mozboot's `MINIMUM_RUST_VERSION`) against the host binaries configure will resolve (honouring the `CBINDGEN`/`RUSTC` env overrides) and failing fast with `fireforge bootstrap` as the named remedy — only a definitively parsed minimum vs a definitively probed host version can fail it, so a moved declaration file or a missing binary skips silently instead of false-positiving; (3) the mach-error-hints translator learned the `… is too old. At least version … is required` and `Rust compiler/Cargo package manager … is too old` shapes, so a failure that still reaches mach (including the auto-configure path in `prepareBuildEnvironment`, which now feeds its captured output through the translator) names `fireforge bootstrap` right below the raw error.
+- Made the per-patch lint **Firefox-globals shim extensible and current**: the closed object-literal types for `ChromeUtils` and `Localization` in the checkJs/typecheck shim are now named global interfaces (`ChromeUtilsShim`, `LocalizationShim`/`LocalizationInstanceShim`), so a project's `patchLint.checkJsExtraShim` can ADD members through TypeScript interface merging (`interface ChromeUtilsShim { newApi(): any }`) instead of having no extension point at all (a second `declare var ChromeUtils` is a duplicate-identifier error — that asymmetry forced a drill workaround with a module-local typedef + bounded any-cast while whole-project `fireforge typecheck` accepted the same call via the engine's Gecko types). Added the Firefox 153 member that triggered this, `ChromeUtils.predictRemoteTypeForURI(uri, options)` (loose signature per the shim's pragmatic posture), and documented that the shim tracks upstream WebIDL additions per Firefox release. Regression tests pin both halves: the new member passes out of the box, and an extra-shim interface merge is typed (correct use passes, misuse is still flagged).
+- Changed `fireforge test <directory>` to select **exactly the named directory**: mach resolves test paths by string prefix, so a bare directory argument silently swept in prefix-named siblings (drill: `…/test/hominis` also ran `…/test/hominis-tiles` — 1224 tests instead of ~200, with no indication the scope widened). FireForge now normalizes directory arguments with a trailing `/` (which makes the prefix match exact) and, when prefix-matching sibling test directories exist, echoes what was selected and what was excluded with per-directory test-file counts plus how to include them as separate paths. Since FireForge already rejected non-existent paths, raw prefix-widening was never something an operator could invoke deliberately — it only ever happened by accident. Documented in `test --help`.
+- Made per-file test sharding **announce itself**: multi-path `fireforge test` runs print one notice that N paths run in isolated browser instances (one mach invocation per path) and that cross-file state is NOT exercised, pointing at `--no-shard` for a combined single-instance run. The silent default cost a real misdiagnosis during the drill: a two-file cross-file pollution repro "passed" because the headed comparison run was silently sharded, briefly blaming a suite-context bug on an upstream headless regression. The `--no-shard` help text now carries the same caveat.
+- Added a **headed-smoke contamination notice and `fireforge run --headless`**: when `--smoke-exit` launches headed on a non-CI host (CI env var unset), a one-line warning states that keyboard/mouse input during the window will contaminate the console capture and can fail the run (drill: a human interacted with the smoke window, the password-manager import scan probed an unreadable Chrome profile dir, and the resulting console errors initially read as a product regression). The new `--headless` flag forwards `--headless` to the browser in both smoke and plain launch modes for unattended checks.
+- Accepted the **verbatim upstream MPL-2.0 block header on new JS files regardless of the project license**: the `missing-license-header` carve-out whose own comment describes the copied-from-upstream case was gated on `license === 'MPL-2.0'`, making it dead code for EUPL/GPL/0BSD projects — a file legitimately carrying Mozilla's block header (including behind a leading editor-directive comment) had no sanctioned path and consumers carried repo-side audit workarounds (recorded 2026-07-04 in the Hominis FORGE.md). Only the upstream `/* … */` block form is accepted; the `// `-style MPL header FireForge generates for MPL projects still requires the project's own header on non-MPL projects, and non-JS styles are unchanged.
+- Added targeted tests and per-module coverage threshold pins for under-covered edge modules that the global threshold was masking: `signal-critical.ts` (first direct tests: body passthrough/cleanup, multi-section waits, bounded timeout, throwing sections), `bootstrap-checks.ts` (bootstrap output pattern detection incl. traceback/403 collapse and all origin-remote phrasings; SDK-probe branching), `discard.ts` (directory-recursion fallback incl. sibling-prefix safety, batch partial failures, dry-run/confirmation paths, Furnace-managed warnings), and the `furnace-validate-compatibility.ts` compose/CSS-hygiene warnings (`compose-not-referenced`/`compose-not-registered`, `excessive-important`, `missing-reduced-motion`).
+
 ## 0.34.0
 
 - Reworked the macOS resource-monitor (psutil) crash mitigation to an **in-process guard FireForge owns on its mach dispatches**: a `fireforge_mach_guard.pth` + module pair is installed directly into every discovered mach virtualenv site-packages (objdir `_virtualenvs` and the `~/.mozbuild` state dir) before each dispatch, because mach's venv re-exec drops `PYTHONPATH` and the 0.33.0 `sitecustomize.py` route never loaded (the env-var shim is retained only for the pre-venv bootstrap phase). The guard now covers the whole crash family: `psutil.virtual_memory`/`swap_memory`/`cpu_percent`/`cpu_times`/`disk_io_counters` are wrapped module-wide (which also covers the direct `psutil.virtual_memory()` call in `mozbuild.base._run_make`), and `SystemResourceMonitor` **construction** is guarded via an import hook that pre-populates `poll_interval` and degrades a partially-constructed monitor to a no-op — so the `AttributeError: ... poll_interval` variant can no longer escape a polling-only patch.
@@ -15,6 +34,10 @@
 - Added `furnace scan --track`, which persists every discovered untracked component into the `stock` section of furnace.json non-interactively (same locked, rollback-journaled write path as the interactive confirm flow). Scan's help and its non-interactive output now state that scan is report-only by default and where the inventory is consumed, ending the report-persist-nothing-explain-nothing behavior.
 - Added `furnace chrome-doc create --browser-window`, a browser.xhtml-like scaffold for the document that ships as the fork's main browser window: `<html id="main-window">` root with the `windowtype="navigator:browser"`/`chromehidden`/geometry-`persist` attributes platform C++ reads before scripts run, while keeping the generic scaffold's bootstrap wiring, sentinel, and (already-correct) jar.mn registrations. When the target document matches a configured `tokenHostDocuments` entry and the flag was not passed, create warns that the browser-window variant is probably intended.
 - Added `furnace create --test-dir <dir>` to redirect the `--with-tests` scaffold (browser-chrome and xpcshell styles) to any engine-relative directory under `browser/base/content/test/` — nested manifests register correctly — and made all test scaffolds collision-safe: existing `browser.toml`/`xpcshell.toml`/`chrome.toml` manifests are appended to (with a shared-manifest notice) instead of scaffolded over, and existing `head.js`/test implementation files are never overwritten.
+- Fixed the degraded-psutil guard wedging `mach build` at exit on flapping hosts (0.34.1 post-upgrade field report: psutil's vm/swap syscalls flap between working and degraded, the fallback swap reading arrived svmem-shaped (8 fields) where mozsystemmonitor's parent reconstructs a 6-field `sswap` via `self._swap_type(*swap_mem)`, so every collector sample was rejected — `resourcemonitor.py:766: UserWarning: failed to read the received data` — upstream's handler breaks its drain loop, the pipe fills, the collector child blocks in `send()` and never reads the terminate sentinel, and mach hangs forever in its atexit `waitpid`). The guard's fallback readings are now **per-function, arity-correct, module-level namedtuples** (svmem 8 / sswap 6 / scputimes 4 / sdiskio 6; psutil's own result classes are still preferred when resolvable) that pickle by reference across the collector pipe and survive `type(reading)(*values)` reconstruction in **either** flapping direction (real type + degraded reading, or degraded type + real reading); `cpu_percent`/`cpu_times` fallbacks honour `percpu=True` (return `[]`) for the collector child's per-CPU sampling, and the last-resort `_DegradedReading` now tolerates positional-field construction. The report's "factory resolution bypassed in the collector child" observation is consistent with the two-copy load (`sitecustomize` via PYTHONPATH plus the in-venv `.pth`) or degraded-import-time `psutil._psplatform` resolution — the fix no longer depends on psutil internals resolving, so it is robust to both.
+- Added **collector suppression on degradation** to the guard: any observed psutil degradation sets a process-wide flag, after which monitors are kept inert — `start` never spawns the mozsystemmonitor collector child — and a degraded transition (any wrapped monitor method raising) or a raising `stop` best-effort terminates a live collector child (`_process.terminate()` + bounded join) and drains the parent end of the pipe, so a malformed sample stream can never fail the command or wedge shutdown even if a future shape mismatch slips through. (The upstream enabler — mozsystemmonitor warning then `break`ing out of its drain loop without draining, leaving the pipe to fill — is worth reporting to Mozilla but is not FireForge-fixable.)
+- Fixed the same degradation **failing `mach build` after a fully successful compile** ("Error running mach" with complete, valid `dist/` artifacts): degraded aggregate methods now return zeroed shapes instead of `None` where callers subscript the result (`aggregate_io` → zeroed io namedtuple, so mozbuild's `log_resource_usage` no longer dies on `usage["io"].read_bytes` at `mozbuild/controller/building.py:526`; `aggregate_cpu_percent`/`aggregate_cpu_times` return `[]`/`0.0`/zeroed shapes per their `per_cpu` mode), and the guard additionally wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to warn-and-continue on any exception. Runtime-verified by new python3-executed regression tests covering per-function fallback arity, pickle/`type(*values)` round-trips in both flapping directions, collector suppression (stub monitor with upstream-named `_process`/`_pipe`), and the BuildMonitor wrap.
+- Taught the harness-crash classifier the post-success `AttributeError: 'NoneType' object has no attribute 'read_bytes'` traceback (protected builds retry it as crash-not-failure — with the fixed guard the incremental retry is cheap and green; real test failures still take precedence), and exempted the upstream drain-loop `failed to read the received data` warning from crash evidence so runs that complete despite the rejected-sample stream never classify as crashes.
 
 ## 0.33.0
 

package/README.md

@@ -88,13 +88,26 @@ Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal
 new one as a single transaction — including staged-dependency owner rewrites — with
 `--dry-run` support.
 
-`fireforge test` runs multiple test paths as sequential per-file shards by default
-(`--no-shard` restores one combined invocation), retries recognized harness crashes up to
-`--harness-retries <n>` times (default 2), and can publish a perf-sample artifact path to
-the harness via `--perf-samples <path>` (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
+`fireforge test <directory>` runs exactly that directory: the argument is normalized with a
+trailing `/` so mach's prefix-based path matching cannot silently sweep in sibling
+directories sharing the name prefix (excluded siblings are echoed with their test-file
+counts). Multiple test paths run as sequential per-file shards by default — announced with
+a notice, since isolated instances do not exercise cross-file state (`--no-shard` restores
+one combined invocation). Recognized harness crashes retry up to `--harness-retries <n>`
+times (default 2), and `--perf-samples <path>` publishes a perf-sample artifact path to the
+harness (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
 Design tokens are managed with `fireforge token add`; pass `--create-category` to declare a
 new category banner and insert the token in one step.
 
+For unattended smoke checks, `fireforge run --smoke-exit <s> --headless` launches the
+browser headless — a headed smoke window on a shared desktop absorbs live input, which
+contaminates the console capture (headed non-CI launches print a warning saying so).
+
+Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals shim that
+tracks upstream WebIDL additions per release; a project's `patchLint.checkJsExtraShim` can
+add members to the structured shim globals via TypeScript interface merging (e.g.
+`interface ChromeUtilsShim { newApi(): any }`).
+
 ## Rebasing Firefox Source
 
 When Mozilla publishes a new Firefox source release you need to update the configured version/product, download the new source code and reapply the patches:

package/dist/bin/fireforge.d.ts

@@ -6,5 +6,9 @@
  * All shared library code propagates errors via CommandError or
  * FireForgeError — never by terminating the process directly.
  *
+ * The signal pipeline below composes several lifecycle modules; the
+ * invariants it upholds (and who owns what) are documented in
+ * docs/lifecycle-invariants.md, and the composed behavior is pinned by
+ * src/core/__tests__/signal-compound-mutation-scenario.test.ts.
  */
 export {};

package/dist/bin/fireforge.js

@@ -7,6 +7,10 @@
  * All shared library code propagates errors via CommandError or
  * FireForgeError — never by terminating the process directly.
  *
+ * The signal pipeline below composes several lifecycle modules; the
+ * invariants it upholds (and who owns what) are documented in
+ * docs/lifecycle-invariants.md, and the composed behavior is pinned by
+ * src/core/__tests__/signal-compound-mutation-scenario.test.ts.
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';

package/dist/src/commands/build.js

@@ -7,6 +7,7 @@ import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
+import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -176,6 +177,18 @@ export async function buildCommand(projectRoot, options) {
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
+    // Toolchain preflight: compare the minimums the tree itself declares
+    // (cbindgen / rust) against the host binaries mach configure will
+    // resolve, and fail fast naming `fireforge bootstrap` instead of dying
+    // ~8s into configure with mach's "./mach bootstrap" remediation text
+    // (152.0b7 → 153.0b8 source-refresh drill). Fail-soft by design: only
+    // a definitively parsed minimum vs a definitively probed host version
+    // can fail here; anything uncertain proceeds to mach, where the
+    // mach-error-hints translator still names the right remedy.
+    const toolchainMismatches = await runToolchainPreflight(paths.engine);
+    if (toolchainMismatches.length > 0) {
+        throw new BuildError(formatToolchainMismatchMessage(toolchainMismatches), 'toolchain preflight');
+    }
     const buildCheck = await hasBuildArtifacts(paths.engine);
     if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
         throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);

package/dist/src/commands/discard.js

@@ -118,10 +118,14 @@ export async function discardCommand(projectRoot, file, options = {}) {
     // directory-with-trailing-slash form so a path like `foo/bar` doesn't
     // accidentally match `foo/bar2/file`.
     if (!statusEntry) {
-        const dirPrefix = file.endsWith('/') ? file : `${file}/`;
+        // Normalize the operator's input once: `discard foo/` (or `foo//`) must
+        // not produce doubled slashes in the messages and prefix comparisons
+        // below, which all append `/` themselves.
+        const dirPath = file.replace(/\/+$/, '');
+        const dirPrefix = `${dirPath}/`;
         const dirEntries = statusEntries.filter((entry) => entry.file.startsWith(dirPrefix) || entry.originalPath?.startsWith(dirPrefix));
         if (dirEntries.length > 0) {
-            await discardDirectoryEntries(projectRoot, paths.engine, file, dirEntries, options);
+            await discardDirectoryEntries(projectRoot, paths.engine, dirPath, dirEntries, options);
             return;
         }
         throw new GeneralError(`File "${file}" has no changes to discard.`);

package/dist/src/commands/download.js

@@ -2,7 +2,7 @@
 import { randomUUID } from 'node:crypto';
 import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths, loadConfig, updateState } from '../core/config.js';
+import { getProjectPaths, loadConfig, loadState, updateState } from '../core/config.js';
 import { withFileLock } from '../core/file-lock.js';
 import { downloadFirefoxSource, formatBytes } from '../core/firefox.js';
 import { getFurnacePaths, updateFurnaceState } from '../core/furnace-config.js';
@@ -10,6 +10,7 @@ import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRep
 import { restoreTrackedPath } from '../core/git-file-ops.js';
 import { getDirtyFiles } 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';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, pathExistsStrict, removeDir } from '../utils/fs.js';
@@ -196,8 +197,22 @@ async function downloadAndExtractFirefox(args) {
         throw error;
     }
 }
+/**
+ * Prints the major-version-hop toolchain nudge when this download moved
+ * the engine across a Firefox MAJOR version (152.0b7 → 153.0b8 drill:
+ * the first post-hop build died in `mach configure` on a moved cbindgen
+ * minimum, and nothing in the download output suggested re-running
+ * `fireforge bootstrap`). Quiet on first downloads and same-major
+ * re-downloads.
+ */
+function noteMajorVersionHop(previousVersion, version) {
+    const hopNotice = formatMajorVersionHopNotice(previousVersion, version);
+    if (hopNotice) {
+        info(hopNotice);
+    }
+}
 async function initializeDownloadedEngine(args) {
-    const { projectRoot, patchesDir, version, engineDir, replacementActivated, backupEngineDir } = args;
+    const { projectRoot, patchesDir, version, previousVersion, engineDir, replacementActivated, backupEngineDir, } = args;
     // Finding #17: the git indexing phase of `download` can block for
     // minutes on a ~600 MB Firefox tree. Emit a one-line heads-up banner
     // before the spinner starts so CI logs show the expected duration.
@@ -239,6 +254,7 @@ async function initializeDownloadedEngine(args) {
             baseCommit,
         });
         await noteUnappliedPatches(patchesDir);
+        noteMajorVersionHop(previousVersion, version);
         if (backupEngineDir) {
             await removeDir(backupEngineDir);
         }
@@ -264,6 +280,9 @@ export async function downloadCommand(projectRoot, options) {
     intro('FireForge Download');
     const config = await loadConfig(projectRoot), version = config.firefox.version;
     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;
     info(`Firefox version: ${version}`);
     await checkDiskSpace(projectRoot, 5 * 1024 * 1024 * 1024, warn);
     await withFileLock(join(paths.fireforgeDir, 'download.fireforge.lock'), async () => {
@@ -318,6 +337,7 @@ export async function downloadCommand(projectRoot, options) {
                                     baseCommit,
                                 });
                                 await noteUnappliedPatches(paths.patches);
+                                noteMajorVersionHop(previousVersion, version);
                                 outro(`Firefox ${version} is ready! (resumed from partial init)`);
                                 return;
                             }
@@ -388,6 +408,7 @@ export async function downloadCommand(projectRoot, options) {
             projectRoot,
             patchesDir: paths.patches,
             version,
+            previousVersion,
             engineDir: installEngineDir,
             replacementActivated,
             ...(backupEngineDir !== undefined ? { backupEngineDir } : {}),

package/dist/src/commands/run.js

@@ -124,7 +124,7 @@ export async function runCommand(projectRoot, options = {}) {
         return;
     }
     info('Launching browser...\n');
-    const exitCode = await run(paths.engine);
+    const exitCode = await run(paths.engine, options.headless ? ['--headless'] : []);
     // Exit-code whitelist:
     //   0   — clean shutdown
     //   130 — SIGINT (Ctrl+C), user-initiated termination
@@ -212,11 +212,22 @@ async function runSmokeExit(engineDir, options) {
         }
         findings.push({ stream, line });
     };
+    // A headed smoke window on a developer desktop absorbs live input:
+    // during the drill a human interacted with the window mid-run, the
+    // password-manager import scan probed an unreadable Chrome profile
+    // dir, and the resulting console errors failed the smoke run looking
+    // like a product regression. CI hosts (CI env var set) are assumed
+    // display-free/unattended, so the notice stays quiet there.
+    if (!options.headless && !process.env['CI']) {
+        warn('Headed smoke window: keyboard/mouse input during the window will contaminate the ' +
+            'console capture and can fail the run. Pass --headless (or run on an unattended host) ' +
+            'for reliable smoke checks.');
+    }
     info(`Launching browser (smoke-exit after ${String(smokeExit)}s)...\n`);
     const startedAt = Date.now();
     let result;
     try {
-        result = await runMachSmoke(['run'], engineDir, {
+        result = await runMachSmoke(options.headless ? ['run', '--headless'] : ['run'], engineDir, {
             smokeTimeoutMs,
             onStdoutLine: (line) => {
                 handleLine('stdout', line);
@@ -332,6 +343,7 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
     }, [])
         .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored.')
         .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
+        .option('--headless', 'Launch the browser with --headless. Recommended for --smoke-exit on a shared desktop: input into a headed smoke window contaminates the console capture.')
         .action(withErrorHandling(async (options) => {
         await runCommand(getProjectRoot(), pickDefined(options));
     }));

package/dist/src/commands/test.js

@@ -8,6 +8,7 @@ import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwarde
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
+import { analyzeTestPathScopes, formatScopeNotice } from '../core/test-path-scope.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
@@ -359,11 +360,27 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         extraArgs.push(...forwardedMachArgs);
     }
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort);
+    // Directory arguments mean EXACTLY that directory: mozbuild's test
+    // resolver matches paths by string prefix, so a bare directory arg
+    // silently swept in prefix-named siblings (152.0b7 → 153.0b8 drill:
+    // `…/test/hominis` also ran `…/test/hominis-tiles`, 1224 tests instead
+    // of ~200, with no indication the scope widened). The dispatch form
+    // gains a trailing `/` (making the prefix match exact) and any
+    // excluded prefix-siblings are echoed so the narrowed scope is
+    // visible. Classification above intentionally used the un-slashed
+    // forms; only the mach dispatch needs the exact-match shape.
+    const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
+    const dispatchPaths = scopes.map((scope) => scope.dispatchPath);
+    for (const scope of scopes) {
+        const notice = formatScopeNotice(scope);
+        if (notice)
+            info(notice);
+    }
     // xpcshell appdir auto-injection happens per harness invocation inside
     // `runTestsWithRetries` (src/commands/test-run.ts) so sharded runs probe
     // the manifest for each file individually. See src/core/xpcshell-appdir.ts
     // for the full motivation.
-    logTestSelection(normalizedPaths);
+    logTestSelection(dispatchPaths);
     const perfSampleEnv = buildPerfSampleEnv(projectRoot, projectConfig.binaryName, options.perfSamples);
     const runCtx = {
         engineDir: paths.engine,
@@ -380,14 +397,22 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // Multi-file requests shard into sequential single-file harness runs by
     // default (field report C3): one shared mochitest profile across files
     // bleeds pref/media-query state into later files. --no-shard restores
-    // the combined invocation.
-    if (normalizedPaths.length > 1 && options.shard !== false) {
-        await runShardedTests(runCtx, normalizedPaths, (outcome, path) => diagnoseShardOutcome(outcome, path, projectConfig.binaryName, postRebuildContext));
+    // the combined invocation. The default must not be SILENT (drill
+    // finding: a two-file cross-file pollution repro "passed" because the
+    // headed comparison run was sharded without saying so, briefly
+    // misattributing a suite-context bug to an upstream headless
+    // regression), so a one-line notice states what sharding does and
+    // does not exercise.
+    if (dispatchPaths.length > 1 && options.shard !== false) {
+        info(`Sharding: running ${dispatchPaths.length} test paths in isolated browser instances ` +
+            '(one mach invocation per path). Cross-file state is NOT exercised — pass --no-shard ' +
+            'for a combined single-instance run.');
+        await runShardedTests(runCtx, dispatchPaths, (outcome, path) => diagnoseShardOutcome(outcome, path, projectConfig.binaryName, postRebuildContext));
         return;
     }
     let outcome;
     try {
-        outcome = await runTestsWithRetries(runCtx, normalizedPaths);
+        outcome = await runTestsWithRetries(runCtx, dispatchPaths);
     }
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
@@ -427,7 +452,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     })
         .option('--generic-mach-test', 'Force dispatch through generic `mach test` instead of the suite-specific `mach xpcshell-test` / `mach mochitest` a single-suite run auto-selects (the suite-specific commands skip the mozlog resource monitor that crashes `mach test` on some hosts).')
-        .option('--no-shard', 'Run multiple test paths in one combined mach invocation instead of sequential per-file shards')
+        .option('--no-shard', 'Run multiple test paths in one combined mach invocation instead of sequential per-file shards (isolated instances do not exercise cross-file state, so use this to reproduce cross-file pollution bugs)')
         .option('--perf-samples <path>', 'Publish a perf-sample artifact path to the harness via <BINARYNAME>_PERF_SAMPLE_JSON (resolved against the project root)')
         .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) auto-forwarded mach args: --setpref=marionette.port=<n> (browser listener) and --marionette=127.0.0.1:<n> (mochitest client). Omits the client flag when --mach-arg already sets --marionette. Use when 2828 is busy or CI assigns another port.', (raw) => {
         const n = Number.parseInt(raw, 10);
@@ -436,6 +461,21 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         }
         return n;
     })
+        .addHelpText('after', [
+        '',
+        '[paths...] semantics: a directory argument selects EXACTLY that',
+        'directory. FireForge normalizes it with a trailing "/" before',
+        'handing it to mach, because mach resolves test paths by string',
+        'prefix and a bare directory name would silently sweep in sibling',
+        'directories sharing the prefix (e.g. foo also running foo-extras).',
+        'When such siblings exist, the excluded directories are listed with',
+        'their test-file counts; pass them as separate paths to include them.',
+        '',
+        'Multiple paths shard into sequential isolated harness runs (one',
+        'browser instance per path) by default, which does not exercise',
+        'cross-file state; --no-shard restores the combined single-instance',
+        'invocation.',
+    ].join('\n'))
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

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

@@ -15,6 +15,7 @@ import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceSta
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
 import { generateMozconfig, runMachCapture } from './mach.js';
+import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
 /**
@@ -31,6 +32,21 @@ function extractMachConfigureError(result) {
         return '';
     return combined.split('\n').slice(-40).join('\n').trim();
 }
+/**
+ * Builds the `BuildError` for a non-zero auto-configure exit: the output
+ * tail (so the underlying mozbuild failure survives), any matched
+ * mach-error hints (so e.g. a toolchain minimum that moved with a source
+ * hop names `fireforge bootstrap` on this path too, exactly like the
+ * protected build dispatch), and the stop rationale.
+ */
+function buildConfigureFailureError(captured) {
+    const detail = extractMachConfigureError(captured);
+    const hints = explainMachError(`${captured.stderr}\n${captured.stdout}`);
+    return new BuildError(`Backend regeneration failed: mach configure exited with code ${captured.exitCode}.` +
+        (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
+        (hints.length > 0 ? `\n\n${hints.map((hint) => `Hint: ${hint}`).join('\n')}` : '') +
+        '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
+}
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.
@@ -84,11 +100,9 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
                 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 — the generic message hid the actual cause.
-                    const detail = extractMachConfigureError(captured);
-                    throw new BuildError(`Backend regeneration failed: mach configure exited with code ${exitCode}.` +
-                        (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
-                        '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
+                    // of a bare exit code — 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)');

package/dist/src/core/firefox-cache.js

@@ -9,7 +9,7 @@ import { join } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { ChecksumMismatchError } from '../errors/download.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson, removeFile, writeJson } from '../utils/fs.js';
+import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { validateArchiveMetadata } from './firefox-archive.js';
@@ -49,8 +49,8 @@ export async function ensureCachedArchive(archive, cacheDir, onProgress, expecte
     });
 }
 async function cacheEntryExists(archive, cacheDir) {
-    return ((await pathExists(join(cacheDir, archive.filename))) ||
-        (await pathExists(join(cacheDir, archive.metadataFilename))));
+    return ((await pathExistsStrict(join(cacheDir, archive.filename))) ||
+        (await pathExistsStrict(join(cacheDir, archive.metadataFilename))));
 }
 /**
  * Validates a cached archive using sidecar metadata and SHA-256 checksum.
@@ -61,7 +61,10 @@ async function cacheEntryExists(archive, cacheDir) {
 async function validateCachedArchive(archive, cacheDir, expectedSha256) {
     const tarballPath = join(cacheDir, archive.filename);
     const metadataPath = join(cacheDir, archive.metadataFilename);
-    if (!(await pathExists(tarballPath)) || !(await pathExists(metadataPath))) {
+    // Deliberately outside the try/catch below: a permission error probing the
+    // cache must propagate instead of reading as "invalid cache" and triggering
+    // a re-download into a directory we cannot write anyway.
+    if (!(await pathExistsStrict(tarballPath)) || !(await pathExistsStrict(metadataPath))) {
         return false;
     }
     try {

package/dist/src/core/firefox-extract.d.ts

@@ -2,7 +2,27 @@
  * Firefox source extraction and installed version detection.
  */
 /**
- * Extracts a tar.xz archive.
+ * Validates entry names from a `tar -tf` listing.
+ * @param names - Listing lines (one member name per line)
+ * @returns The first unsafe member name, or null when all are safe
+ */
+export declare function findUnsafeArchiveEntryName(names: readonly string[]): string | null;
+/**
+ * Validates symlink and hardlink targets from a `tar -tvf` listing.
+ *
+ * A relative link target without `..` segments can only resolve inside the
+ * extraction root, so only absolute or `..`-containing targets are rejected.
+ * Symlinks are `l`-typed lines with a ` -> target` suffix (the LAST arrow is
+ * taken, so a link whose own name contains ` -> ` still parses to its real
+ * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
+ *
+ * @param verboseLines - `tar -tvf` listing lines
+ * @returns A description of the first unsafe link found, or null
+ */
+export declare function findUnsafeArchiveLink(verboseLines: readonly string[]): string | null;
+/**
+ * Extracts a tar.xz archive after a listing preflight that rejects
+ * path-traversal member names and escaping link targets.
  * @param archivePath - Path to the archive
  * @param destDir - Destination directory
  */

package/dist/src/core/firefox-extract.js

@@ -8,7 +8,111 @@ import { elapsedSince } from '../utils/elapsed.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { exec, executableExists } from '../utils/process.js';
 /**
- * Extracts a tar.xz archive.
+ * Returns true when an archive member path could land outside the
+ * extraction root: absolute (POSIX or Windows drive/backslash rooted) or
+ * containing a `..` segment.
+ */
+function isUnsafeArchivePath(path) {
+    if (path.startsWith('/') || path.startsWith('\\'))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(path))
+        return true;
+    return path.split(/[\\/]/).includes('..');
+}
+/**
+ * Validates entry names from a `tar -tf` listing.
+ * @param names - Listing lines (one member name per line)
+ * @returns The first unsafe member name, or null when all are safe
+ */
+export function findUnsafeArchiveEntryName(names) {
+    for (const raw of names) {
+        const name = raw.trim();
+        if (name.length === 0)
+            continue;
+        if (isUnsafeArchivePath(name))
+            return name;
+    }
+    return null;
+}
+/**
+ * Validates symlink and hardlink targets from a `tar -tvf` listing.
+ *
+ * A relative link target without `..` segments can only resolve inside the
+ * extraction root, so only absolute or `..`-containing targets are rejected.
+ * Symlinks are `l`-typed lines with a ` -> target` suffix (the LAST arrow is
+ * taken, so a link whose own name contains ` -> ` still parses to its real
+ * target); hardlinks print ` link to target` on GNU tar and bsdtar alike.
+ *
+ * @param verboseLines - `tar -tvf` listing lines
+ * @returns A description of the first unsafe link found, or null
+ */
+export function findUnsafeArchiveLink(verboseLines) {
+    for (const line of verboseLines) {
+        if (line.startsWith('l')) {
+            const arrow = line.lastIndexOf(' -> ');
+            if (arrow !== -1) {
+                const target = line.slice(arrow + 4).trim();
+                if (isUnsafeArchivePath(target))
+                    return `symlink target: ${target}`;
+                continue;
+            }
+        }
+        const hardlink = line.lastIndexOf(' link to ');
+        if (hardlink !== -1) {
+            const target = line.slice(hardlink + 9).trim();
+            if (isUnsafeArchivePath(target))
+                return `hardlink target: ${target}`;
+        }
+    }
+    return null;
+}
+/**
+ * Lists the archive and rejects members that could escape the extraction
+ * root before anything is written to disk: absolute names, `..` traversal,
+ * and symlink/hardlink targets that are absolute or `..`-escaping. Modern
+ * GNU tar / bsdtar refuse most of these at extraction time; the preflight
+ * makes the guarantee explicit and independent of the host tar's defaults.
+ *
+ * Two listings are needed because they answer different questions and
+ * neither is safe to derive from the other: member names come from `-tf`,
+ * where the whole line IS the name, while link targets only appear in
+ * `-tvf`. Names are deliberately NOT parsed out of the `-tvf` columns — the
+ * adjacent uname/gname fields are attacker-controlled in a crafted archive,
+ * so a date-shaped owner name could shift the column boundary and hide an
+ * absolute member name from the check. Each listing pass costs one full
+ * decompression, so the two run concurrently and overlap almost perfectly
+ * (they are CPU-bound on separate cores). Measured on a real Firefox ESR
+ * 140.9 source tarball (601 MB, bsdtar 3.5.3, macOS): -tf 21.7 s, -tvf
+ * 22.1 s, both concurrent 22 s wall, extraction itself 58 s (file-creation
+ * syscalls dominate it, not decompression) — so the preflight adds ~22 s
+ * (~38%) to this one-time extraction step, versus ~44 s if run
+ * sequentially.
+ */
+async function preflightArchiveEntries(archivePath) {
+    // LC_ALL=C keeps the -tvf column format stable for the link parse.
+    const listEnv = { LC_ALL: 'C', LANG: 'C' };
+    const [nameListing, verboseListing] = await Promise.all([
+        exec('tar', ['-tf', archivePath], { env: listEnv }),
+        exec('tar', ['-tvf', archivePath], { env: listEnv }),
+    ]);
+    if (nameListing.exitCode !== 0) {
+        throw new ExtractionError(archivePath, new Error(`tar -tf preflight exited with code ${nameListing.exitCode}:\n${nameListing.stderr}`));
+    }
+    const unsafeName = findUnsafeArchiveEntryName(nameListing.stdout.split('\n'));
+    if (unsafeName !== null) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: member name could escape the extraction root: ${unsafeName}`));
+    }
+    if (verboseListing.exitCode !== 0) {
+        throw new ExtractionError(archivePath, new Error(`tar -tvf preflight exited with code ${verboseListing.exitCode}:\n${verboseListing.stderr}`));
+    }
+    const unsafeLink = findUnsafeArchiveLink(verboseListing.stdout.split('\n'));
+    if (unsafeLink !== null) {
+        throw new ExtractionError(archivePath, new Error(`Archive rejected: link could escape the extraction root (${unsafeLink})`));
+    }
+}
+/**
+ * Extracts a tar.xz archive after a listing preflight that rejects
+ * path-traversal member names and escaping link targets.
  * @param archivePath - Path to the archive
  * @param destDir - Destination directory
  */
@@ -18,18 +122,24 @@ export async function extractTarXz(archivePath, destDir, onProgress) {
     }
     await ensureDir(destDir);
     const startedAt = Date.now();
-    onProgress?.(`Extracting source archive (${elapsedSince(startedAt)} elapsed)...`);
+    onProgress?.(`Validating source archive entries (${elapsedSince(startedAt)} elapsed)...`);
     const heartbeat = onProgress
         ? setInterval(() => {
             onProgress(`Extracting source archive (${elapsedSince(startedAt)} elapsed)...`);
         }, 15_000)
         : null;
     heartbeat?.unref();
-    const result = await exec('tar', ['-xf', archivePath, '-C', destDir]);
-    if (heartbeat)
-        clearInterval(heartbeat);
-    if (result.exitCode !== 0) {
-        throw new ExtractionError(archivePath, new Error(`tar exited with code ${result.exitCode}:\n${result.stderr}`));
+    try {
+        await preflightArchiveEntries(archivePath);
+        onProgress?.(`Extracting source archive (${elapsedSince(startedAt)} elapsed)...`);
+        const result = await exec('tar', ['-xf', archivePath, '-C', destDir]);
+        if (result.exitCode !== 0) {
+            throw new ExtractionError(archivePath, new Error(`tar exited with code ${result.exitCode}:\n${result.stderr}`));
+        }
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
     }
     onProgress?.(`Source archive extracted (${elapsedSince(startedAt)} elapsed)`);
 }