@hominis/fireforge 0.17.0 → 0.18.1

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/commands/wire.js

@@ -226,6 +226,15 @@ export async function wireCommand(projectRoot, name, options = {}) {
     // dry-run is meant to preview the mutation plan without requiring
     // the subscript to already exist, matching the "plan before write"
     // pattern operators rely on for setup scripts).
+    //
+    // Dry-run keeps the existence check advisory rather than fatal: the
+    // "wire first, create file after" workflow is a legitimate use of
+    // preview, but operators who run dry-run over a typo were surprised
+    // when the real command then refused with `Subscript file not
+    // found`. 2026-04-23 eval (Finding in eval 2): dry-run produced a
+    // plausible plan and the non-dry-run invocation then errored. The
+    // info line surfaces the mismatch in preview mode so the operator
+    // can act on the warning before re-running without --dry-run.
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
         const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
@@ -234,6 +243,13 @@ export async function wireCommand(projectRoot, name, options = {}) {
                 'Create the file in engine/ before wiring.', 'name');
         }
     }
+    else {
+        const paths = getProjectPaths(projectRoot);
+        const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);
+        if (!(await pathExists(subscriptPath))) {
+            info(`Note: ${subscriptDir}/${name}.js does not exist yet — the real wire command will require it before writing. Create the file before re-running without --dry-run.`);
+        }
+    }
     if (options.dryRun) {
         printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
         return;

package/dist/src/core/browser-wire.js

@@ -2,8 +2,9 @@
 import { join, relative } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
 import { toRootRelativePath } from '../utils/paths.js';
-import { getProjectPaths } from './config.js';
+import { getProjectPaths, loadConfig } from './config.js';
 import { createRollbackJournal, restoreRollbackJournal, snapshotFile } from './furnace-rollback.js';
 import { registerBrowserContent } from './manifest-register.js';
 import { DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
@@ -63,18 +64,34 @@ export async function wireSubscript(root, name, options = {}) {
         await snapshotFile(journal, join(engineDir, effectiveDomTargetPath));
     }
     await snapshotFile(journal, join(engineDir, 'browser/base/jar.mn'));
+    // Compute the project-scoped patch-lint marker (`// <BINARY>:`) so
+    // every wire mutator can stamp it into the emitted comment block.
+    // Without this, `lintModificationComments` trips
+    // `missing-modification-comment` on wire-generated edits the next
+    // time the operator exports — the same tool wrote the code and a
+    // sibling tool then rejected it (eval 1 Finding #9). A broken config
+    // should not block the wire, so the fallback marker keeps the
+    // previous lint-friendly default when the config cannot be loaded.
+    let marker = 'FIREFORGE:';
+    try {
+        const config = await loadConfig(root);
+        marker = `${config.binaryName.toUpperCase()}:`;
+    }
+    catch (error) {
+        verbose(`Using default wire marker because fireforge.json could not be loaded: ${toError(error).message}`);
+    }
     try {
         // 1. Add subscript to browser-main.js
-        const subscriptAdded = await addSubscriptToBrowserMain(engineDir, name);
+        const subscriptAdded = await addSubscriptToBrowserMain(engineDir, name, marker);
         // 2. Add init expression to browser-init.js (if provided)
         let initAdded = false;
         if (options.init) {
-            initAdded = await addInitToBrowserInit(engineDir, options.init, options.after);
+            initAdded = await addInitToBrowserInit(engineDir, options.init, options.after, marker);
         }
         // 3. Add destroy expression to browser-init.js onUnload() (if provided)
         let destroyAdded = false;
         if (options.destroy) {
-            destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
+            destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy, marker);
         }
         // 4. Add #include directive to the top-level chrome document (if provided)
         let domInserted = false;

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

@@ -94,6 +94,16 @@ export function isPackageablePath(sourcePath) {
     }
     if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
         return false;
+    // `.inc.xhtml` fragments are consumed via `#include` from a registered
+    // chrome document and resolved at packaging time — they never ship as
+    // a standalone packaged artifact. 2026-04-21 eval (Finding #11):
+    // `fireforge build --ui` after `wire --dom` flagged the wired
+    // `*.inc.xhtml` as "missing packaged artifact" even though
+    // `register` correctly refuses to register it and the operator
+    // followed the documented workflow. Mirror the same carve-out the
+    // register rules apply.
+    if (sourcePath.endsWith('.inc.xhtml'))
+        return false;
     for (const ext of PACKAGEABLE_EXTENSIONS) {
         if (sourcePath.endsWith(ext))
             return true;

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

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

@@ -9,7 +9,7 @@ import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit, git } from './git-base.js';
 import { fileExistsInHead } from './git-file-ops.js';
-import { getUntrackedFiles } from './git-status.js';
+import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
     const result = await exec('git', args, { cwd: repoDir });
     if (allowedExitCodes.includes(result.exitCode)) {
@@ -183,7 +183,26 @@ export async function getAllDiff(repoDir) {
  */
 export async function getDiffForFilesAgainstHead(repoDir, files) {
     await ensureGit();
-    const uniqueFiles = [...new Set(files)].sort();
+    // Expand any directory entries (paths ending with `/`) into their
+    // individual untracked files before diffing. `git status --porcelain=v1`
+    // reports collapsed untracked directories as `?? dir/`, and every caller
+    // that feeds the aggregate working-tree state into this function must
+    // not trigger an EISDIR when the diff pass reads `dir/` as if it were a
+    // file. Belt-and-suspenders: the caller-side expansion in `lint.ts`
+    // and `export-all.ts` covers the common path, but a single bad call
+    // site re-introduced the bug in 0.17.0 — guarding here makes the
+    // regression impossible at this layer.
+    const expandedFiles = [];
+    for (const file of files) {
+        if (file.endsWith('/')) {
+            const inner = await getUntrackedFilesInDir(repoDir, file);
+            for (const entry of inner)
+                expandedFiles.push(entry);
+            continue;
+        }
+        expandedFiles.push(file);
+    }
+    const uniqueFiles = [...new Set(expandedFiles)].sort();
     const diffs = [];
     for (const file of uniqueFiles) {
         if (await fileExistsInHead(repoDir, file)) {