@hominis/fireforge 0.18.0 → 0.18.1

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

@@ -12,7 +12,7 @@
  */
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { getFurnacePaths, updateFurnaceState } from '../../core/furnace-config.js';
-import { getHead, isGitRepository, resetChanges } from '../../core/git.js';
+import { getHead, isGitRepository, isMissingHeadError, resetChanges } from '../../core/git.js';
 import { discoverPatches } from '../../core/patch-files.js';
 import { loadPatchesManifest } from '../../core/patch-manifest.js';
 import { hasActiveRebaseSession, saveRebaseSession } from '../../core/rebase-session.js';
@@ -40,6 +40,24 @@ async function handleFreshStart(projectRoot, options) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
+    // 2026-04-24 eval Finding 11: `rebase --dry-run` used to print
+    // "Dry run complete" without validating that the engine had a valid
+    // HEAD. A previous `download --force` abort could leave `.git/`
+    // initialized but unborn (no baseline commit); the real rebase then
+    // failed immediately with `fatal: ambiguous argument 'HEAD'` on the
+    // first `git rev-parse HEAD` call. Replicate the same baseline check
+    // here so dry-run mirrors the real-run preconditions and operators
+    // cannot mistake a broken baseline for a ready-to-rebase tree.
+    try {
+        await getHead(paths.engine);
+    }
+    catch (err) {
+        if (isMissingHeadError(err)) {
+            throw new GeneralError('Engine repository has no baseline commit yet — a previous "fireforge download" was interrupted before git created the initial Firefox source commit. ' +
+                'Re-run "fireforge download --force" to recreate the baseline repository cleanly, then retry the rebase.');
+        }
+        throw err;
+    }
     const config = await loadConfig(projectRoot);
     const currentVersion = config.firefox.version;
     const manifest = await loadPatchesManifest(paths.patches);

package/dist/src/commands/status.js

@@ -70,11 +70,39 @@ async function printUnregisteredWarnings(files, projectRoot, binaryName) {
     if (newFiles.length === 0)
         return;
     const registrableFiles = newFiles.filter((f) => matchesRegistrablePattern(f.file, binaryName));
-    const registrationChecks = await Promise.all(registrableFiles.map(async (f) => ({
-        file: f.file,
-        registered: await isFileRegistered(projectRoot, f.file),
-    })));
-    const unregistered = registrationChecks.filter((f) => !f.registered);
+    // `isFileRegistered` throws `GeneralError("Manifest not found: ...")` when a
+    // rule sees a file whose parent manifest does not yet exist on disk — e.g.
+    // a brand-new `browser/modules/<binary>/` directory with no `moz.build`.
+    // `status` is a read-only reporter; before 0.18.1 the rejected promise
+    // bubbled through `Promise.all` and exited status with code 1, breaking the
+    // "use status --unmanaged to discover new files before running register"
+    // workflow. We now bucket missing-manifest cases into a distinct warning
+    // list while still surfacing the same actionable signal. Other error
+    // shapes continue to propagate (permission denied, corrupt file, etc.) so
+    // we do not silently hide anything surprising.
+    const registrationChecks = await Promise.all(registrableFiles.map(async (f) => {
+        try {
+            return {
+                file: f.file,
+                registered: await isFileRegistered(projectRoot, f.file),
+                manifestMissing: false,
+                manifestMissingMessage: undefined,
+            };
+        }
+        catch (err) {
+            if (err instanceof GeneralError && /^Manifest not found:/i.test(err.message)) {
+                return {
+                    file: f.file,
+                    registered: false,
+                    manifestMissing: true,
+                    manifestMissingMessage: err.message,
+                };
+            }
+            throw err;
+        }
+    }));
+    const unregistered = registrationChecks.filter((f) => !f.registered && !f.manifestMissing);
+    const manifestMissing = registrationChecks.filter((f) => f.manifestMissing);
     if (unregistered.length > 0) {
         info('');
         warn('Potentially unregistered files:');
@@ -82,6 +110,17 @@ async function printUnregisteredWarnings(files, projectRoot, binaryName) {
             info(`  ${f.file} — run 'fireforge register ${f.file}'`);
         }
     }
+    if (manifestMissing.length > 0) {
+        info('');
+        warn('Files whose registration manifest does not exist yet:');
+        for (const f of manifestMissing) {
+            // `manifestMissingMessage` is always the specific
+            // "Manifest not found: <path>" string when manifestMissing is
+            // true (see the catch branch above that sets them together).
+            info(`  ${f.file} — ${f.manifestMissingMessage}`);
+            info(`    Create the parent manifest, then run 'fireforge register ${f.file}'.`);
+        }
+    }
 }
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.

package/dist/src/commands/test.js

@@ -4,7 +4,7 @@ import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
 import { assertMarionettePortAvailable } from '../core/marionette-port.js';
-import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
+import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
@@ -82,17 +82,22 @@ function hasXpcshellAppdirSignal(output) {
     return /Failed to load resource:\/\/\/modules\//i.test(output);
 }
 function buildXpcshellAppdirMessage(injectionAttempted) {
+    const isMacos = process.platform === 'darwin';
+    const macosNote = isMacos
+        ? 'Detected: macOS host. On macOS the xpcshell harness binds `-a` to `<obj>/dist/<App>.app/Contents/Resources` by default and frequently ignores `--app-path` overrides when the `.app` bundle is present — the surest fix is the `<appname>-appdir` migration below rather than trying to force a different path.\n\n'
+        : '';
     const triggerLines = injectionAttempted
-        ? 'FireForge auto-injected `--app-path=<absolute>` against the resolved obj-dir before mach test ran, but the failure persists. The injected path either does not match the appdir layout your harness expects, or the harness was built against a layout FireForge cannot probe (omni.ja-packed tree, alternate `dist/` shape).\n\n'
+        ? 'FireForge auto-injected `--app-path=<absolute>` against the resolved obj-dir before mach test ran, but the failure persists. The injected path either does not match the appdir layout your harness expects, or (on macOS) the harness bound `-a` to the `.app/Contents/Resources` default and ignored the override.\n\n'
         : 'Likely triggers:\n' +
             '  - The nearest xpcshell.toml sets `firefox-appdir = "browser"` but the harness reads `<appname>-appdir` instead — the literal `firefox-appdir` directive is silently ignored on rebranded forks (appname != "firefox").\n' +
             '  - FireForge could not find an xpcshell.toml above the test path, so the auto-injection never ran.\n\n';
     return ('xpcshell failed to load core resource:///modules/*.sys.mjs imports.\n\n' +
         'This is the canonical symptom of xpcshell running with the wrong app directory: the runtime resolves `resource:///modules/` against the parent of the expected app root, so every `ChromeUtils.importESModule("resource:///modules/…")` throws.\n\n' +
+        macosNote +
         triggerLines +
         'Options:\n' +
-        '  - Add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the xpcshell.toml [DEFAULT] so the harness reads the appname-keyed value directly.\n' +
-        '  - Pass overrides through `fireforge test <path> --mach-arg="--app-path=<absolute>"` to inject the path verbatim (operator overrides always win over auto-injection).\n' +
+        '  - Add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the xpcshell.toml [DEFAULT] so the harness reads the appname-keyed value directly. This is the most reliable fix on rebranded macOS builds.\n' +
+        '  - Pass overrides through `fireforge test <path> --mach-arg="--app-path=<absolute>"` to inject the path verbatim (operator overrides always win over auto-injection, but see the macOS caveat above).\n' +
         '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
         '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
 }
@@ -228,26 +233,32 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // no paths are supplied this is the only step — it's the fastest way to tell
     // marionette-wedged apart from test-discovery-failure.
     if (options.doctor) {
+        // Write the "Running marionette preflight..." banner via
+        // `process.stdout.write` directly before `info()` so non-TTY captures
+        // always see the banner even if clack's renderer defers output in
+        // pipe mode. `info()` is still called so TTY users keep the normal
+        // clack box-drawing framing.
+        process.stdout.write('Running marionette preflight...\n');
         info('Running marionette preflight...');
         const preflight = await runMarionettePreflight(paths.engine);
+        // 2026-04-24 eval Finding 7: the pre-0.18.1 code used
+        // `success()` + `outro()` + a direct `process.stdout.write` as a
+        // belt-and-suspenders but still reproducibly dropped the PASS summary
+        // under non-TTY capture (observed: `tee`-wrapped eval output saw only
+        // the intro). The fix writes the authoritative PASS/FAIL line via
+        // `process.stdout.write` as the very first output after the probe
+        // returns, so the captured stream has an unambiguous summary no
+        // matter what clack does on top. The clack-rendered banner
+        // (`info`/`warn`) is retained so TTY users keep the visual framing.
+        const directLine = formatMarionettePreflightLine(preflight);
+        process.stdout.write(`${directLine}\n`);
         reportMarionettePreflight(preflight);
         if (testPaths.length === 0) {
             if (!preflight.ok) {
                 throw new GeneralError('Marionette preflight reported FAIL — see output above.');
             }
-            // Belt-and-suspenders: write the PASS footer via `success()`
-            // AND `outro()` AND a direct stdout write. The eval
-            // reproducibly captured the intro + info line but nothing
-            // after the preflight returned, which we believe is a
-            // non-TTY clack rendering quirk that occasionally swallows
-            // the last log line before process exit. `success()` routes
-            // through a different clack entry point than `info()`, and
-            // `process.stdout.write` bypasses clack entirely so the
-            // PASS status is always visible in the captured output.
-            const summary = `Marionette preflight: PASS (${preflight.durationMs}ms)`;
-            success(summary);
+            success(directLine);
             outro('Test completed');
-            process.stdout.write(`${summary}\n`);
             return;
         }
         if (!preflight.ok) {

package/dist/src/commands/verify.js

@@ -14,19 +14,74 @@
  * Exits non-zero when any error-severity finding is reported so CI can
  * treat the output as pass/fail.
  */
+import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
 import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
+import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
 import { GeneralError } from '../errors/base.js';
-import { pathExists } from '../utils/fs.js';
+import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 /**
- * Reports duplicate `filesAffected` entries across patches — the manifest
- * consistency check only flags per-patch duplicates and orphan files, not
- * the case where two different patches claim the same path. `verify`
- * surfaces that here so it can be caught before `export`, `re-export`, or
- * `rebase` hit it.
+ * Walks each patch body in the manifest, extracts the set of
+ * component-shaped registration references it adds (widget paths
+ * implied by jar.mn + customElements.js; FTL paths implied by locale
+ * jar.mn), and confirms every reference is either created by some
+ * patch in the queue OR present as a tracked file in engine/. Any
+ * unreachable reference is a dangling-registration error — the patch
+ * registers a file that nothing in the world supplies, which fails at
+ * install time.
  */
+async function detectDanglingRegistrations(patchesDir, engineDir, patches) {
+    // Aggregate the set of all paths that any patch in the queue is
+    // responsible for (per `filesAffected`). We deliberately do NOT parse
+    // individual patch bodies for new-file creations here: `filesAffected`
+    // is already the contract manifest callers rely on, and
+    // `validatePatchesManifestConsistency` has already ensured the two
+    // are in sync. Using that list keeps this validator fast.
+    const coveredByPatches = new Set();
+    for (const patch of patches) {
+        for (const file of patch.filesAffected) {
+            coveredByPatches.add(file);
+        }
+    }
+    const issues = [];
+    for (const patch of patches) {
+        const patchPath = join(patchesDir, patch.filename);
+        if (!(await pathExists(patchPath)))
+            continue;
+        let body;
+        try {
+            body = await readText(patchPath);
+        }
+        catch {
+            // Bad file read is surfaced by the manifest consistency check
+            // already — skipping here avoids double-reporting the same issue.
+            continue;
+        }
+        const refs = collectPatchRegistrationReferences(body);
+        if (refs.length === 0)
+            continue;
+        for (const ref of refs) {
+            if (coveredByPatches.has(ref.targetPath))
+                continue;
+            // Engine existence check: if the target file is already present
+            // in engine/ (e.g. upstream Firefox ships it, or a separate
+            // baseline branch has it), the registration is not dangling.
+            // We cannot sanely probe "is this tracked by git" without a git
+            // round-trip; existence on disk is a close-enough proxy for
+            // verify's read-only context.
+            if (await pathExists(join(engineDir, ref.targetPath)))
+                continue;
+            issues.push({
+                patchFilename: patch.filename,
+                targetPath: ref.targetPath,
+                source: ref.source,
+            });
+        }
+    }
+    return issues;
+}
 function detectCrossPatchFileClaims(manifestPatches) {
     const claims = new Map();
     for (const patch of manifestPatches) {
@@ -97,6 +152,26 @@ export async function verifyCommand(projectRoot) {
                 warningCount += 1;
         }
     }
+    // 4. Registration-consequence consistency: walk each patch body and
+    // confirm that every widget / locale registration it adds has a
+    // corresponding file body covered by the patch queue OR present in
+    // the engine working tree. 2026-04-24 eval Finding 1: a patch
+    // produced by `export-all --exclude-furnace` referenced
+    // `toolkit/content/widgets/moz-qa-panel/*.mjs` via jar.mn /
+    // customElements.js edits, but the source files themselves were
+    // excluded from the patch. `verify` used to report "clean"; it now
+    // flags each dangling reference as a `dangling-registration` error
+    // naming the specific patch and target path.
+    if (manifest) {
+        const registrationIssues = await detectDanglingRegistrations(paths.patches, paths.engine, manifest.patches);
+        if (registrationIssues.length > 0) {
+            warn(`Dangling registration references (${registrationIssues.length}):`);
+            for (const issue of registrationIssues) {
+                warn(`  ${issue.patchFilename}: registers ${issue.targetPath} via ${issue.source}, but no patch body or engine file supplies it`);
+                errorCount += 1;
+            }
+        }
+    }
     if (errorCount === 0 && warningCount === 0) {
         success('Patch queue is consistent.');
         outro('Verify clean');

package/dist/src/commands/watch.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { delimiter, dirname } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
@@ -5,8 +7,8 @@ import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner } from '../utils/logger.js';
-import { exec, executableExists } from '../utils/process.js';
+import { info, intro, outro, spinner, verbose } from '../utils/logger.js';
+import { exec, findExecutable } from '../utils/process.js';
 const WATCHMAN_PROBE_TIMEOUT_MS = 5000;
 /**
  * Probes watchman by running `watchman --version`. A binary that exists
@@ -55,14 +57,21 @@ function buildWatchmanConfigureTimeMessage() {
 /**
  * Builds the generic unsupported-watch failure message.
  * @param exitCode - Exit code returned by `mach watch`
+ * @param watchmanPath - Optional absolute path to the resolved watchman binary; surfaced in the guidance so the operator can see whether FireForge actually found one.
  * @returns User-facing failure guidance
  */
-function buildUnsupportedWatchMessage(exitCode) {
+function buildUnsupportedWatchMessage(exitCode, watchmanPath) {
+    const watchmanLine = watchmanPath
+        ? `  - FireForge resolved watchman at ${watchmanPath} and prepended its directory to the mach subprocess PATH. If mach still did not see it, ensure that path is stable between runs.\n`
+        : '';
     return (`Watch failed with exit code ${exitCode}. Check the output above for details.\n\n` +
         'Common causes:\n' +
         '  - watchman is not installed or not in PATH right now\n' +
         '  - watchman was installed only after the current obj-* directory was configured; delete obj-* and rebuild\n' +
-        '  - mach watch is unsupported in the current objdir or build environment');
+        '  - mach watch is unsupported in the current objdir or build environment\n' +
+        watchmanLine +
+        '\n' +
+        'If the failure referenced `watch-project` / `FasterBuildException: timed out`, watchman is likely reachable via `which watchman` from your shell but missing from the subprocess PATH. FireForge now prepends the resolved watchman directory automatically; confirm your watchman install is on a stable path (e.g. /opt/homebrew/bin/watchman on macOS).');
 }
 /**
  * Detects the Firefox-side output produced when watchman was missing at configure time.
@@ -86,7 +95,17 @@ export async function watchCommand(projectRoot) {
     if (!(await pathExists(paths.engine))) {
         throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
-    if (!(await executableExists('watchman'))) {
+    // Resolve the watchman binary to an absolute path up-front so we can
+    // (a) refuse fast when it is missing AND (b) prepend its directory to
+    // the mach subprocess PATH. 2026-04-24 eval Finding 12: on macOS,
+    // `which watchman` from the interactive shell returns
+    // `/opt/homebrew/bin/watchman`, but the Node subprocess PATH
+    // frequently omits `/opt/homebrew/bin`, so the shell probe passed and
+    // mach's `watch-project` call then timed out because its own PATH
+    // lookup for watchman failed. Threading the directory through the
+    // subprocess env fixes it.
+    const watchmanPath = await findExecutable('watchman');
+    if (!watchmanPath) {
         throw new GeneralError('Watch mode requires watchman to be installed and available in PATH.\n\n' +
             'Install watchman first, then rerun "fireforge watch".');
     }
@@ -145,9 +164,26 @@ export async function watchCommand(projectRoot) {
     }
     info('Starting watch mode...');
     info('Press Ctrl+C to stop\n');
+    // Compose the subprocess env: start from the parent process env, then
+    // prepend the resolved watchman directory to PATH so the mach
+    // subprocess sees the same binary our probe just validated. Without
+    // this, a watchman install on `/opt/homebrew/bin` (the default
+    // homebrew prefix on Apple Silicon) is absent from the PATH Node
+    // inherits on spawn, and `mach watch` fails at the `watch-project`
+    // subscription step.
+    const watchmanDir = dirname(watchmanPath);
+    const existingPath = process.env['PATH'] ?? '';
+    const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
+    const watchmanEnv = pathSegments.includes(watchmanDir)
+        ? { ...process.env }
+        : {
+            ...process.env,
+            PATH: [watchmanDir, ...pathSegments].join(delimiter),
+        };
+    verbose(`watch: resolved watchman at ${watchmanPath}; forwarding directory in subprocess PATH.`);
     let result;
     try {
-        result = await watchWithOutput(paths.engine);
+        result = await watchWithOutput(paths.engine, { env: watchmanEnv });
     }
     catch (error) {
         throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
@@ -158,7 +194,7 @@ export async function watchCommand(projectRoot) {
             throw new GeneralError(buildWatchmanConfigureTimeMessage());
         }
         // 130 is SIGINT (Ctrl+C), which is expected
-        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode), 'mach watch');
+        throw new BuildError(buildUnsupportedWatchMessage(result.exitCode, watchmanPath), 'mach watch');
     }
     outro('Watch mode stopped');
 }

package/dist/src/core/furnace-constants.d.ts

@@ -4,6 +4,20 @@ export declare const CUSTOM_ELEMENTS_JS = "toolkit/content/customElements.js";
 export declare const JAR_MN = "toolkit/content/jar.mn";
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
+/**
+ * Suffix for the per-binary xpcshell scaffold parent directory. Components
+ * created with `furnace create --with-tests --xpcshell` land at
+ * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
+ * Centralised so `create` / `remove` / `rename` / `validate` all agree on
+ * the path template (2026-04-24 eval Finding 5).
+ */
+export declare const XPCSHELL_TEST_DIR_SUFFIX = "-xpcshell";
+/**
+ * Returns the engine-relative directory that holds xpcshell scaffolds for
+ * a given binary. Matches the form `create-xpcshell.ts` writes and the
+ * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
+ */
+export declare function xpcshellTestParentDir(binaryName: string): string;
 /** File extensions that constitute a Furnace component's source files. */
 export declare const COMPONENT_FILE_EXTENSIONS: readonly [".mjs", ".css", ".ftl"];
 /** Returns true when `fileName` has one of the standard component file extensions. */

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

@@ -5,6 +5,22 @@ export const CUSTOM_ELEMENTS_JS = 'toolkit/content/customElements.js';
 export const JAR_MN = 'toolkit/content/jar.mn';
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/**
+ * Suffix for the per-binary xpcshell scaffold parent directory. Components
+ * created with `furnace create --with-tests --xpcshell` land at
+ * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
+ * Centralised so `create` / `remove` / `rename` / `validate` all agree on
+ * the path template (2026-04-24 eval Finding 5).
+ */
+export const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
+/**
+ * Returns the engine-relative directory that holds xpcshell scaffolds for
+ * a given binary. Matches the form `create-xpcshell.ts` writes and the
+ * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
+ */
+export function xpcshellTestParentDir(binaryName) {
+    return `browser/base/content/test/${binaryName}${XPCSHELL_TEST_DIR_SUFFIX}`;
+}
 /** File extensions that constitute a Furnace component's source files. */
 export const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];
 /** Returns true when `fileName` has one of the standard component file extensions. */

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

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
-import { loadConfig } from './config.js';
+import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths, loadFurnaceConfig } from './furnace-config.js';
+import { xpcshellTestParentDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
 import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
@@ -175,6 +177,70 @@ export async function validateAllComponents(root) {
         existing.push(issue);
         results.set(issue.component, existing);
     }
+    // 2026-04-24 eval Finding 5: orphan xpcshell scaffold detection.
+    // `furnace create --with-tests --xpcshell` scaffolds a test directory
+    // at `browser/base/content/test/<binary>-xpcshell/<name>/`, and prior
+    // `furnace remove` + `furnace rename` flows did not touch that tree.
+    // A leftover scaffold whose `<name>` is not in furnace.json is almost
+    // always the aftermath of one of those incomplete flows; flag it as
+    // an `orphan-xpcshell-scaffold` error so operators know to delete or
+    // re-create the scaffold instead of discovering the mismatch only at
+    // test run time. Missing engine or missing scaffold parent directory
+    // both degrade silently — this check never introduces noise on a
+    // project that never used xpcshell scaffolding.
+    try {
+        const orphanIssues = await findOrphanXpcshellScaffolds(root, config);
+        for (const issue of orphanIssues) {
+            const existing = results.get(issue.component) ?? [];
+            existing.push(issue);
+            results.set(issue.component, existing);
+        }
+    }
+    catch {
+        // Validation degrades gracefully — the absence of an engine
+        // directory, permission denial reading the scaffold tree, or any
+        // other transient fs issue should never cascade into false
+        // "orphan" reports.
+    }
     return results;
 }
+/**
+ * Scans the per-binary xpcshell scaffold directory for entries whose
+ * component name is not present in furnace.json, and returns an
+ * `orphan-xpcshell-scaffold` issue for each one.
+ */
+async function findOrphanXpcshellScaffolds(root, config) {
+    const forgeConfig = await loadConfig(root);
+    const paths = getProjectPaths(root);
+    const parentRel = xpcshellTestParentDir(forgeConfig.binaryName);
+    const parentAbs = join(paths.engine, parentRel);
+    if (!(await pathExists(parentAbs)))
+        return [];
+    let entries;
+    try {
+        const dirents = await readdir(parentAbs, { withFileTypes: true });
+        entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+    }
+    catch {
+        return [];
+    }
+    const known = new Set([
+        ...Object.keys(config.custom),
+        ...Object.keys(config.overrides),
+        ...config.stock,
+    ]);
+    const issues = [];
+    for (const entry of entries) {
+        if (known.has(entry))
+            continue;
+        issues.push({
+            component: entry,
+            severity: 'error',
+            check: 'orphan-xpcshell-scaffold',
+            message: `Stale xpcshell test scaffold at ${parentRel}/${entry}/ — no matching component is declared in furnace.json. ` +
+                'Delete the scaffold directory manually, or re-run `fireforge furnace create --with-tests --xpcshell` for an existing component with the same name.',
+        });
+    }
+    return issues;
+}
 //# sourceMappingURL=furnace-validate.js.map

package/dist/src/core/git-base.d.ts

@@ -1,6 +1,31 @@
-/** Default timeout for `git add -A` on large trees (10 minutes). */
+/**
+ * Environment variable that overrides the monolithic `git add -A` timeout
+ * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
+ * filesystems legitimately exceeded the 10-minute default during a
+ * 140.10.0esr baseline indexing pass; making the cap overridable lets
+ * them retry without recompiling.
+ */
+export declare const GIT_ADD_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_TIMEOUT_MS";
+/**
+ * Environment variable that overrides the per-chunk `git add -- <dir>`
+ * timeout (milliseconds). Paired with {@link GIT_ADD_TIMEOUT_ENV_VAR} so
+ * both the monolithic attempt and the chunked fallback can be extended.
+ */
+export declare const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS";
+/**
+ * Resolved timeout for monolithic `git add -A`. Prefers
+ * {@link GIT_ADD_TIMEOUT_ENV_VAR} when present (and a positive
+ * integer) so operators on slow hosts can extend the default without
+ * rebuilding FireForge.
+ */
 export declare const GIT_ADD_TIMEOUT_MS: number;
-/** Timeout for chunked `git add` per top-level directory (20 minutes). */
+/**
+ * Resolved timeout for each chunk of the chunked fallback path. Grew
+ * from 20 to 30 minutes in 0.18.1 because the fallback is already the
+ * last line of defence before aborting — erring on the side of "complete
+ * the indexing" over "fail fast" matches the real-world recovery
+ * workflow.
+ */
 export declare const GIT_ADD_CHUNK_TIMEOUT_MS: number;
 /**
  * Structured git status entry derived from `git status --porcelain=v1 -z`.

package/dist/src/core/git-base.js

@@ -1,10 +1,48 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { GitError, GitNotFoundError } from '../errors/git.js';
 import { exec, executableExists } from '../utils/process.js';
+/**
+ * Environment variable that overrides the monolithic `git add -A` timeout
+ * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
+ * filesystems legitimately exceeded the 10-minute default during a
+ * 140.10.0esr baseline indexing pass; making the cap overridable lets
+ * them retry without recompiling.
+ */
+export const GIT_ADD_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_TIMEOUT_MS';
+/**
+ * Environment variable that overrides the per-chunk `git add -- <dir>`
+ * timeout (milliseconds). Paired with {@link GIT_ADD_TIMEOUT_ENV_VAR} so
+ * both the monolithic attempt and the chunked fallback can be extended.
+ */
+export const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS';
 /** Default timeout for `git add -A` on large trees (10 minutes). */
-export const GIT_ADD_TIMEOUT_MS = 10 * 60_000;
-/** Timeout for chunked `git add` per top-level directory (20 minutes). */
-export const GIT_ADD_CHUNK_TIMEOUT_MS = 20 * 60_000;
+const DEFAULT_GIT_ADD_TIMEOUT_MS = 10 * 60_000;
+/** Default timeout for chunked `git add` per top-level directory (30 minutes). */
+const DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS = 30 * 60_000;
+function resolveTimeoutFromEnv(envVar, fallbackMs) {
+    const raw = process.env[envVar];
+    if (raw === undefined || raw.length === 0)
+        return fallbackMs;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallbackMs;
+    return parsed;
+}
+/**
+ * Resolved timeout for monolithic `git add -A`. Prefers
+ * {@link GIT_ADD_TIMEOUT_ENV_VAR} when present (and a positive
+ * integer) so operators on slow hosts can extend the default without
+ * rebuilding FireForge.
+ */
+export const GIT_ADD_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_TIMEOUT_MS);
+/**
+ * Resolved timeout for each chunk of the chunked fallback path. Grew
+ * from 20 to 30 minutes in 0.18.1 because the fallback is already the
+ * last line of defence before aborting — erring on the side of "complete
+ * the indexing" over "fail fast" matches the real-world recovery
+ * workflow.
+ */
+export const GIT_ADD_CHUNK_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS);
 /**
  * Ensures git is available in the system.
  * @throws GitNotFoundError if git is not installed