@hominis/fireforge 0.15.8 → 0.16.0

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

@@ -25,6 +25,26 @@ export interface LintCommandOptions {
      * rejected up-front rather than silently ignored.
      */
     onlyIntroduced?: boolean;
+    /**
+     * Lint each patch in the queue as its own isolated diff, rather than
+     * the aggregate `git diff HEAD` across all applied patches.
+     *
+     * Motivating case: running `fireforge lint` (no args) on a repo where
+     * `fireforge import` or `fireforge rebase` has just applied the full
+     * patch queue produces an aggregate diff (every patch's changes
+     * summed). The patch-size advisory rules (`large-patch-lines`,
+     * `large-patch-files`) then fire against the sum — e.g. "Patch is
+     * 37529 lines" on a queue of 22 individually-fine patches — which
+     * reads as a task-specific regression when it is really an artefact
+     * of the aggregation. `--per-patch` rescopes the diff to each patch's
+     * own `filesAffected`, honours the patch's own `lintIgnore`, and runs
+     * the cross-patch rules once over the whole queue so queue-level
+     * findings (duplicate creations, forward imports) still surface.
+     *
+     * Mutually exclusive with passing explicit file paths — the two
+     * scope contracts are different.
+     */
+    perPatch?: boolean;
 }
 /**
  * Runs the lint command to check engine changes against patch quality rules.

package/dist/src/commands/lint.js

@@ -8,40 +8,36 @@ import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } fro
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue } from '../core/patch-lint.js';
 import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
- * Runs the lint command to check engine changes against patch quality rules.
- * @param projectRoot - Root directory of the project
- * @param files - Optional file/directory paths to lint (relative to engine/)
- * @param options - Additional lint options such as `--since` diff-scoping
+ * Resolves the diff the lint command should run against. Returns `null` when
+ * there is nothing to lint (e.g. no matching files, clean tree, or empty
+ * diff content) — callers treat that as the early-exit signal and stop.
+ *
+ * Extracted from {@link lintCommand} so that function stays under the
+ * per-function LOC budget as the command grows; the two file-mode and
+ * aggregate-mode branches share no state with the post-lint reporting
+ * pipeline, so the split is a pure rename rather than a refactor.
  */
-export async function lintCommand(projectRoot, files, options = {}) {
-    intro('FireForge Lint');
-    // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
-    // without a revision to anchor the diff there is no "introduced" subset
-    // to scope to — reject the combination up-front so a misconfigured CI
-    // invocation fails loud instead of silently treating every error as
-    // cumulative and passing.
-    if (options.onlyIntroduced && !options.since) {
-        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
-    }
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    let diff;
+async function resolveLintDiff(engineDir, files) {
     if (files.length > 0) {
-        // Collect specific files/directories
         const collectedFiles = new Set();
         let fileStatuses;
         let untrackedFiles;
-        for (const inputPath of files) {
-            const fullInputPath = join(paths.engine, inputPath);
+        // Strip a leading `engine/` segment up-front so the rest of the lookup
+        // pipeline (directory stat, modified-files-in-dir, status probe) all
+        // see the engine-relative form. Without this, passing
+        // `engine/browser/base/content/foo.js` fell through to "No modified
+        // files found in the specified paths." because git sees every path
+        // relative to engine/. The same normalization runs in `register`,
+        // `test`, and `export` via `stripEnginePrefix`.
+        const normalizedFiles = files.map((inputPath) => stripEnginePrefix(inputPath));
+        for (const inputPath of normalizedFiles) {
+            const fullInputPath = join(engineDir, inputPath);
             let isDirectory = false;
             try {
                 const fileStat = await stat(fullInputPath);
@@ -52,47 +48,87 @@ export async function lintCommand(projectRoot, files, options = {}) {
             }
             if (isDirectory) {
                 const dirPath = inputPath.endsWith('/') ? inputPath.slice(0, -1) : inputPath;
-                const modifiedFiles = await getModifiedFilesInDir(paths.engine, dirPath);
-                const dirUntrackedFiles = await getUntrackedFilesInDir(paths.engine, dirPath);
+                const modifiedFiles = await getModifiedFilesInDir(engineDir, dirPath);
+                const dirUntrackedFiles = await getUntrackedFilesInDir(engineDir, dirPath);
                 for (const f of modifiedFiles)
                     collectedFiles.add(f);
                 for (const f of dirUntrackedFiles)
                     collectedFiles.add(f);
             }
             else {
-                if (!fileStatuses) {
-                    fileStatuses = await getStatusWithCodes(paths.engine);
-                }
-                if (!untrackedFiles) {
-                    untrackedFiles = await getUntrackedFiles(paths.engine);
-                }
+                if (!fileStatuses)
+                    fileStatuses = await getStatusWithCodes(engineDir);
+                if (!untrackedFiles)
+                    untrackedFiles = await getUntrackedFiles(engineDir);
                 const hasStatus = fileStatuses.some((s) => s.file === inputPath) || untrackedFiles.includes(inputPath);
-                if (hasStatus) {
+                if (hasStatus)
                     collectedFiles.add(inputPath);
-                }
             }
         }
         if (collectedFiles.size === 0) {
             info('No modified files found in the specified paths.');
             outro('Nothing to lint');
-            return;
+            return null;
         }
-        diff = await getDiffForFilesAgainstHead(paths.engine, [...collectedFiles].sort());
-    }
-    else {
-        // Lint all changes
-        if (!(await hasChanges(paths.engine))) {
-            info('No changes to lint.');
+        const diff = await getDiffForFilesAgainstHead(engineDir, [...collectedFiles].sort());
+        if (!diff.trim()) {
+            info('No diff content to lint.');
             outro('Nothing to lint');
-            return;
+            return null;
         }
-        diff = await getAllDiff(paths.engine);
+        return diff;
     }
+    if (!(await hasChanges(engineDir))) {
+        info('No changes to lint.');
+        outro('Nothing to lint');
+        return null;
+    }
+    const diff = await getAllDiff(engineDir);
     if (!diff.trim()) {
         info('No diff content to lint.');
         outro('Nothing to lint');
+        return null;
+    }
+    return diff;
+}
+/**
+ * Runs the lint command to check engine changes against patch quality rules.
+ * @param projectRoot - Root directory of the project
+ * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
+ */
+export async function lintCommand(projectRoot, files, options = {}) {
+    intro('FireForge Lint');
+    // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
+    // without a revision to anchor the diff there is no "introduced" subset
+    // to scope to — reject the combination up-front so a misconfigured CI
+    // invocation fails loud instead of silently treating every error as
+    // cumulative and passing.
+    if (options.onlyIntroduced && !options.since) {
+        throw new GeneralError('--only-introduced requires --since <git-rev> so introduced-vs-cumulative can be distinguished.');
+    }
+    // `--per-patch` rescopes the diff from "aggregate engine state" to "each
+    // patch's own filesAffected". Mixing in explicit file paths would produce
+    // an ambiguous set — is the file list an additional filter, or does it
+    // replace the per-patch scope? Reject up-front so the operator gets a
+    // clear error rather than a silently-narrowed result.
+    if (options.perPatch && files.length > 0) {
+        throw new GeneralError('--per-patch cannot be combined with explicit file paths. Pass either --per-patch or a file list, not both.');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    if (options.perPatch) {
+        await lintPerPatch(projectRoot, paths);
         return;
     }
+    const diff = await resolveLintDiff(paths.engine, files);
+    if (diff === null)
+        return;
     const config = await loadConfig(projectRoot);
     const filesAffected = extractAffectedFiles(diff);
     // Build patch queue context once so it can be shared between the
@@ -110,6 +146,19 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (ctx) {
         issues.push(...lintPatchQueue(ctx));
     }
+    // When a queue manifest exists AND files were NOT scoped explicitly, the
+    // "diff" we just linted is every applied patch summed together. Patch-
+    // size rules (`large-patch-lines`, `large-patch-files`) then fire against
+    // the aggregate rather than any individual patch, producing counts like
+    // "Patch is 37529 lines" that read as a task-specific regression but are
+    // really an artefact of aggregation. Surface a one-line note pointing at
+    // `--per-patch` so the operator knows the per-patch scope exists before
+    // they read the error message as "my queue is broken".
+    const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
+    if (aggregateHintApplicable &&
+        issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
+        info('NOTE: aggregate diff across all applied patches. Use `fireforge lint --per-patch` to lint each patch individually; patch-size rules fire against the sum in aggregate mode.');
+    }
     if (issues.length === 0) {
         success('No lint issues found.');
         outro('Lint passed');
@@ -164,13 +213,83 @@ export async function lintCommand(projectRoot, files, options = {}) {
     }
     outro('Lint passed with warnings');
 }
+/**
+ * Lints each patch in the queue as its own isolated diff, honouring
+ * per-patch `lintIgnore` entries. Cross-patch rules still run once over
+ * the whole queue so queue-level findings (duplicate creations, forward
+ * imports) are not lost by the rescoping.
+ *
+ * Kept separate from {@link lintCommand}'s aggregate path because the
+ * two scopes have genuinely different contracts — the aggregate path
+ * reports what `git diff HEAD` looks like right now, the per-patch
+ * path reports what each patch's own slice of that diff looks like.
+ * Sharing a loop would hide the distinction and force the caller to
+ * decide semantics mid-function.
+ */
+async function lintPerPatch(projectRoot, paths) {
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        info('No patches in manifest — nothing to lint per-patch.');
+        outro('Nothing to lint');
+        return;
+    }
+    const config = await loadConfig(projectRoot);
+    const ctx = await buildPatchQueueContext(paths.patches);
+    const issues = [];
+    let linted = 0;
+    for (const patch of manifest.patches) {
+        const existing = [];
+        for (const f of patch.filesAffected) {
+            if (await pathExists(join(paths.engine, f)))
+                existing.push(f);
+        }
+        if (existing.length === 0)
+            continue;
+        const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
+        if (!diff.trim())
+            continue;
+        const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+        const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore);
+        for (const issue of patchIssues) {
+            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
+        }
+        linted++;
+    }
+    // Cross-patch rules over the whole queue — rescoping per-patch would
+    // lose these findings, so they run exactly once against the full
+    // context.
+    issues.push(...lintPatchQueue(ctx));
+    if (issues.length === 0) {
+        success(`No lint issues found across ${linted} patch(es).`);
+        outro('Lint passed');
+        return;
+    }
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices)
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of warnings)
+        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of errors)
+        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+    info(`\nLint (per-patch over ${linted} patch(es)): ${errors.length} error(s), ${warnings.length} warning(s)`);
+    if (errors.length > 0) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
+    }
+    outro('Lint passed with warnings');
+}
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('lint [paths...]')
-        .description('Lint engine changes against patch quality rules')
+        .description('Lint engine changes against patch quality rules. Default: aggregate diff against HEAD ' +
+        '(every applied patch summed). Use --per-patch for per-patch scope, or pass explicit ' +
+        'file paths to narrow to those.')
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
+        .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -179,6 +298,9 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         if (options.onlyIntroduced !== undefined) {
             lintOptions.onlyIntroduced = options.onlyIntroduced;
         }
+        if (options.perPatch !== undefined) {
+            lintOptions.perPatch = options.perPatch;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
 }

package/dist/src/commands/package.js

@@ -1,7 +1,8 @@
 import { validateBrandOverride } from '../core/brand-validation.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackage } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, machPackageCapture, } from '../core/mach.js';
+import { explainMachError } from '../core/mach-error-hints.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -49,9 +50,16 @@ export async function packageCommand(projectRoot, options) {
     info('Creating distribution package...');
     info('This may take a while.\n');
     const startTime = Date.now();
-    let exitCode;
+    let result;
     try {
-        exitCode = await machPackage(paths.engine);
+        // `machPackageCapture` streams output live AND captures the tail for
+        // post-run diagnostics. Previously `machPackage` inherited stdio
+        // only, so a targeted hint translator could not see the failure text.
+        // The captured stderr is fed through `explainMachError` below so
+        // recognised failure modes (notably the `packager.py` NoneType trip
+        // the evaluator hit on `hominis/`) get an actionable hint prepended
+        // to the raw mach output the operator already saw.
+        result = await machPackageCapture(paths.engine);
     }
     catch (error) {
         throw new BuildError('Package process failed to start', 'mach package', error instanceof Error ? error : undefined);
@@ -60,9 +68,12 @@ export async function packageCommand(projectRoot, options) {
     const minutes = Math.floor(duration / 60000);
     const seconds = Math.floor((duration % 60000) / 1000);
     const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
-    if (exitCode !== 0) {
+    if (result.exitCode !== 0) {
         error(`Packaging failed after ${timeStr}`);
-        throw new BuildError(`Packaging failed with exit code ${exitCode}`, 'mach package');
+        const combinedOutput = `${result.stdout}\n${result.stderr}`;
+        const hints = explainMachError(combinedOutput);
+        const hintBlock = hints.length > 0 ? `\n\nHint:\n${hints.map((h) => `  ${h}`).join('\n')}` : '';
+        throw new BuildError(`Packaging failed with exit code ${result.exitCode}.${hintBlock}`, 'mach package');
     }
     info(`\nPackage created in obj-*/dist/`);
     outro(`Packaging completed in ${timeStr}!`);

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

@@ -71,8 +71,12 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             'Remove those paths from --files or modify them before retrying.', '--files');
     }
     // Run the per-patch lint against the projected diff. This mirrors what
-    // runPatchLint does in the standard re-export path.
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint);
+    // runPatchLint does in the standard re-export path. The target patch's
+    // `lintIgnore` threads through so a shrink of an advisory-noisy-but-
+    // intentional patch (branding bundle, localised-resource pack) does not
+    // have to choose between `--skip-lint` (blunt) and the full rebase path.
+    const ignoreChecks = target.lintIgnore?.length ? new Set(target.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks);
     // Project the cross-patch context: replace the target entry with its
     // would-be shrunken self (new diff + new newFiles + new
     // modifiedFileAdditions). The projected entry must repopulate both

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

@@ -6,7 +6,7 @@ import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, } from '../core/patch-manifest.js';
+import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -59,6 +59,31 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     if (options.scan) {
         currentFilesAffected = await scanPatchFiles(currentFilesAffected, paths.engine, manifest, patch.filename, isDryRun);
     }
+    else if (options.files === undefined) {
+        // Finding #16: when neither `--scan` nor `--files` is set and some
+        // of the manifest's claimed files no longer exist on disk, the
+        // re-export silently writes a refreshed body whose filesAffected
+        // still names the vanished paths. That is the documented contract,
+        // but it is also a footgun — a later `verify` then fails on
+        // manifest-consistency with no obvious trigger. Emit one advisory
+        // warning up-front when we can detect the drift cheaply, so the
+        // operator has a chance to re-run with `--scan` or `--files`
+        // before the stale filesAffected lands in patches.json.
+        const missingFiles = [];
+        for (const file of currentFilesAffected) {
+            if (!(await pathExists(join(paths.engine, file)))) {
+                missingFiles.push(file);
+            }
+        }
+        if (missingFiles.length > 0) {
+            warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
+                `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
+                `filesAffected unchanged and the missing entries will be preserved — ` +
+                `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
+                `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
+                `or pass --files <paths> to set the list explicitly.`);
+        }
+    }
     // --- Explicit file-subset path ---
     // When --files is given, the target filesAffected is authoritative — drop
     // anything not in the list, add anything new. This is the surgical repair
@@ -97,7 +122,14 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         warn(`Skipped ${patch.filename}: no changes (files unchanged from HEAD)`);
         return false;
     }
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint);
+    // Thread the patch's own `lintIgnore` list through so the per-patch
+    // suppression honoured by export/export-all is also honoured here.
+    // Without this, `re-export` could not refresh an advisory-noisy but
+    // intentional patch (a cohesive branding bundle, a localised-resource
+    // pack) without either `--skip-lint` (too blunt) or falling through to
+    // the full `rebase` flow (which internally skips the lint pipeline).
+    const ignoreChecks = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
     }
@@ -219,13 +251,16 @@ export async function reExportCommand(projectRoot, patches, options) {
     }
     const config = await loadConfig(projectRoot);
     let reExported = 0;
+    const reExportedFilenames = [];
     const progress = spinner('Preparing re-export...');
     for (const patch of selectedPatches) {
         progress.message(`Re-exporting ${patch.filename}...`);
         try {
             const exported = await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config);
-            if (exported)
+            if (exported) {
                 reExported++;
+                reExportedFilenames.push(patch.filename);
+            }
         }
         catch (error) {
             warn(`Failed to re-export ${patch.filename}`);
@@ -236,14 +271,34 @@ export async function reExportCommand(projectRoot, patches, options) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
     }
+    // `--stamp` only fires on a run where every selected patch refreshed
+    // cleanly. A partial success would leave some patches with a stale body
+    // but a new version — the opposite of the "what I tested, what the
+    // manifest says" invariant `sourceEsrVersion` exists to record. A
+    // non-empty `reExportedFilenames` with fewer entries than `selectedPatches`
+    // means a lint failure or missing-file skip landed somewhere in the loop,
+    // which we refuse to version-stamp through.
+    const shouldStamp = options.stamp === true && !isDryRun && reExported > 0 && reExported === selectedPatches.length;
+    if (shouldStamp) {
+        await stampPatchVersions(paths.patches, reExportedFilenames, config.firefox.version);
+    }
     if (isDryRun) {
         progress.stop('Dry run complete');
         success(`[dry-run] Would re-export ${reExported} of ${selectedPatches.length} patch(es)`);
+        if (options.stamp === true) {
+            info(`[dry-run] Would stamp sourceEsrVersion=${config.firefox.version} on ${reExported} patch(es)`);
+        }
         outro('Dry run complete');
     }
     else {
         progress.stop('Re-export complete');
         success(`Re-exported ${reExported} of ${selectedPatches.length} patch(es)`);
+        if (shouldStamp) {
+            success(`Stamped sourceEsrVersion=${config.firefox.version} on ${reExportedFilenames.length} patch(es)`);
+        }
+        else if (options.stamp === true && reExported !== selectedPatches.length) {
+            warn('--stamp was requested but some patches failed or were skipped; refusing to stamp a partial set.');
+        }
         outro('Re-export complete');
     }
 }
@@ -251,7 +306,9 @@ export async function reExportCommand(projectRoot, patches, options) {
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('re-export [patches...]')
-        .description('Re-export existing patches from current engine state')
+        .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
+        'state. Does NOT change sourceEsrVersion by default — use --stamp or run rebase for ' +
+        'version stamping.')
         .option('-a, --all', 'Re-export all patches')
         .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
         .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
@@ -262,6 +319,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('-y, --yes', 'Skip confirmation when --files shrinks a patch (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
+        .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceEsrVersion in patches.json to firefox.version from fireforge.json. No effect on a partial run.")
         .action(withErrorHandling(async (patches, options) => {
         await reExportCommand(getProjectRoot(), patches, pickDefined(options));
     }));

package/dist/src/commands/register.js

@@ -6,23 +6,7 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-/**
- * Strips a leading `engine/` segment (either separator flavour) from a
- * user-supplied path so operators can pass either a repo-root-relative
- * path (`engine/browser/base/content/foo.xhtml`) or an engine-relative
- * path (`browser/base/content/foo.xhtml`). The engine-relative form is
- * what the manifest writers expect; without this normalisation, the
- * former failed with a misleading "File not found in engine" pointing
- * at a doubled path like `engine/engine/browser/...` that operators
- * had no way to spot from the error message alone.
- */
-function normalizeEngineRelativePath(filePath) {
-    if (filePath.startsWith('engine/'))
-        return filePath.slice('engine/'.length);
-    if (filePath.startsWith('engine\\'))
-        return filePath.slice('engine\\'.length);
-    return filePath;
-}
+import { stripEnginePrefix } from '../utils/paths.js';
 /**
  * Registers a file in the appropriate build manifest.
  *
@@ -50,7 +34,7 @@ export async function registerCommand(projectRoot, filePath, options = {}) {
     // the former from the output of tab completion or `git status`, and
     // the mismatch used to produce a "File not found" error that named
     // the original path with no hint that dropping `engine/` would fix it.
-    const engineRelativePath = normalizeEngineRelativePath(filePath);
+    const engineRelativePath = stripEnginePrefix(filePath);
     // Verify the file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);

package/dist/src/commands/run.js

@@ -2,9 +2,9 @@
 import { createWriteStream } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { getProjectPaths } from '../core/config.js';
+import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, run, runMachSmoke, } from '../core/mach.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke, } from '../core/mach.js';
 import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
@@ -94,6 +94,27 @@ export async function runCommand(projectRoot, options = {}) {
         throw new GeneralError(`Run requires a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first, then rerun 'fireforge run'.");
     }
+    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a
+    // build that configured but hasn't yet produced the launchable binary
+    // (common in a long real Firefox compile that the operator stopped
+    // and restarted) passes that check, and `mach run` then fails on the
+    // missing binary path. `hasRunnableBundle` narrows the probe to the
+    // actual executable so `fireforge run` refuses with a targeted
+    // message before handing control to mach. `fireforge watch` stays
+    // permissive and instead surfaces the same information as a banner
+    // suffix; watch is supposed to drive rebuilds of partially-built
+    // trees, so blocking there would defeat the feature.
+    if (buildCheck.objDir) {
+        const config = await loadConfig(projectRoot);
+        const bundleCheck = await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir);
+        if (!bundleCheck.runnable) {
+            const expected = bundleCheck.expectedPath ?? `dist/bin/${config.binaryName}`;
+            throw new GeneralError(`Run requires a completed build that produced the launchable bundle. ` +
+                `Build artifacts exist in ${buildCheck.objDir}/ but the expected binary at ${expected} is missing — ` +
+                `the build may have aborted or is still in progress.\n\n` +
+                "Run 'fireforge build' and wait for it to finish before retrying 'fireforge run'.");
+        }
+    }
     // Warn if Furnace components changed since the last apply
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures

package/dist/src/commands/status.js

@@ -12,7 +12,7 @@ import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/pa
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText } from '../utils/fs.js';
+import { FIREFORGE_TMP_PATH_PATTERN, pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, verbose, warn } from '../utils/logger.js';
 /**
  * Status code descriptions for git status.
@@ -164,6 +164,21 @@ async function expandDirectoryEntries(files, engineDir) {
     }
     return { entries: expanded, truncations };
 }
+/**
+ * Strips entries whose path matches the atomic-temp-file shape
+ * FireForge's own `writeText` produces (see
+ * {@link import('../utils/fs.js').FIREFORGE_TMP_PATH_PATTERN}). Those
+ * files only exist for the duration of a write + rename and should
+ * never appear in `status` output; filtering them here keeps every
+ * status mode (default, raw, unmanaged, ownership, json) symmetric so
+ * the operator never sees a `.mozconfig.fireforge-tmp-<pid>-<uuid>`
+ * entry mid-write. Files named for unrelated reasons (e.g. a user's
+ * `.bashrc.fireforge-tmp-backup` without the PID+UUID tail) do not
+ * match the pattern and pass through unfiltered.
+ */
+function filterFireForgeTempFiles(files) {
+    return files.filter((entry) => !FIREFORGE_TMP_PATH_PATTERN.test(entry.file));
+}
 /**
  * Classifies files into patch-backed, unmanaged, or branding buckets.
  */
@@ -277,7 +292,11 @@ export async function statusCommand(projectRoot, options = {}) {
         const ownershipExpansion = (await isGitRepository(paths.engine))
             ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
             : { entries: [], truncations: [] };
-        const rawFilesOwnership = ownershipExpansion.entries;
+        // Filter atomic-write temp files (Finding #18) so a mid-flight
+        // `.fireforge-tmp-<pid>-<uuid>` artefact never shows up in any
+        // status mode. The pattern is tight enough to let legitimately
+        // similar names through.
+        const rawFilesOwnership = filterFireForgeTempFiles(ownershipExpansion.entries);
         renderTruncationBanner(ownershipExpansion.truncations);
         // Only walk the patch bodies when the directory actually exists.
         // Fresh projects with no patch queue yet pass through with an empty
@@ -313,7 +332,10 @@ export async function statusCommand(projectRoot, options = {}) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
     const rawFiles = await getStatusWithCodes(paths.engine);
-    const { entries: files, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    const { entries: expanded, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
+    // Strip atomic-write temp files (Finding #18) before every mode
+    // branch so raw / unmanaged / default / json all agree.
+    const files = filterFireForgeTempFiles(expanded);
     renderTruncationBanner(truncations);
     if (files.length === 0) {
         info('No modified files');