@hominis/fireforge 0.18.0 → 0.18.2

package/dist/src/commands/patch/tier.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch tier <name>` — sets or clears `PatchMetadata.tier` on
+ * a single patch without rewriting the `.patch` file body.
+ *
+ * Companion to `fireforge re-export <name> --tier <tier>`. Re-export is
+ * the right tool when the patch body itself needs to be regenerated; this
+ * subcommand exists for the metadata-only adjustment, where the operator
+ * has discovered (e.g. from a `lint --per-patch` warning) that the
+ * threshold-tier override should be set but the patch body is already
+ * correct. Avoiding the re-export saves the engine read + diff
+ * regeneration roundtrip and leaves the `.patch` file's mtime alone.
+ *
+ * Modes are mutually exclusive: exactly one of `--tier <branding>` or
+ * `--clear` must be supplied per invocation.
+ */
+import { Option } from 'commander';
+import { getProjectPaths } from '../../core/config.js';
+import { appendHistory } from '../../core/destructive.js';
+import { updatePatchMetadata } from '../../core/patch-export.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { pickDefined } from '../../utils/options.js';
+/**
+ * Runs the `patch tier` command: updates `PatchMetadata.tier` on the
+ * named patch (or clears the field) and writes the manifest.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest `name`
+ * @param options - Command options
+ */
+export async function patchTierCommand(projectRoot, identifier, options = {}) {
+    const isDryRun = options.dryRun === true;
+    intro(isDryRun ? 'FireForge patch tier (dry run)' : 'FireForge patch tier');
+    // Mode mutex: a single invocation either sets or clears the tier.
+    // Combining both is ambiguous — the operator's intent is not obvious
+    // and silently picking one would mask the typo.
+    const setting = options.tier !== undefined;
+    const clearing = options.clear === true;
+    if (setting && clearing) {
+        throw new InvalidArgumentError('--tier and --clear are mutually exclusive. Pick one mode per invocation.', 'patch tier');
+    }
+    if (!setting && !clearing) {
+        throw new InvalidArgumentError('Specify --tier <tier> to set the override, or --clear to remove it.', 'patch tier');
+    }
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.patches))) {
+        throw new GeneralError('Patches directory not found.');
+    }
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('No patches in manifest.');
+    }
+    const target = resolvePatchIdentifier(identifier, manifest.patches);
+    if (!target) {
+        const available = manifest.patches
+            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
+            .join(', ');
+        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+    }
+    const before = target.tier;
+    const after = setting ? options.tier : undefined;
+    if (before === after) {
+        info(after === undefined
+            ? `${target.filename}: tier is already absent — no change.`
+            : `${target.filename}: tier is already "${after}" — no change.`);
+        outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch tier (no-op)');
+        return;
+    }
+    const action = after === undefined
+        ? `clear tier (was "${before}")`
+        : before === undefined
+            ? `set tier to "${after}"`
+            : `change tier from "${before}" to "${after}"`;
+    if (isDryRun) {
+        info(`[dry-run] ${target.filename}: would ${action}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    // Single write under the patch directory lock (delegated inside
+    // updatePatchMetadata). Setting routes through `updates`; clearing
+    // routes through `unsetFields` so TypeScript's exact optional types
+    // do not have to carry an explicit `undefined` on the `tier` field.
+    if (after !== undefined) {
+        await updatePatchMetadata(paths.patches, target.filename, { tier: after });
+    }
+    else {
+        await updatePatchMetadata(paths.patches, target.filename, {}, ['tier']);
+    }
+    try {
+        await appendHistory(paths.patches, {
+            operation: 'patch-tier',
+            args: {
+                filename: target.filename,
+                ...(before !== undefined ? { before } : {}),
+                ...(after !== undefined ? { after } : {}),
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            result: 'ok',
+        });
+    }
+    catch (historyError) {
+        warn(`History log append failed after patch tier committed (${target.filename}): ${toError(historyError).message}`);
+    }
+    info(`${target.filename}: ${action}.`);
+    outro('Patch tier complete');
+}
+/**
+ * Registers the `patch tier` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchTier(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    parent
+        .command('tier <name>')
+        .description('Set or clear PatchMetadata.tier on a single patch (no .patch body rewrite). Use --tier <branding> to set, --clear to remove.')
+        .addOption(new Option('--tier <tier>', 'Force the tier override on the patch (only "branding" recognised)').choices(['branding']))
+        .option('--clear', 'Remove the tier override (restores tier auto-detection)')
+        .option('--dry-run', 'Show what would change without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .action(withErrorHandling(async (name, options) => {
+        const { tier, ...rest } = options;
+        await patchTierCommand(getProjectRoot(), name, {
+            ...pickDefined(rest),
+            ...(tier !== undefined ? { tier: tier } : {}),
+        });
+    }));
+}
+//# sourceMappingURL=tier.js.map

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

@@ -11,6 +11,85 @@ import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
 import { runPatchLint } from './export-shared.js';
+/**
+ * Computes the effective `tier` and `lintIgnore` carrying both the
+ * patch's existing values and the CLI flag overrides. Pure helper —
+ * extracted from {@link reExportFilesInPlace} both to share with the
+ * standard re-export path conceptually and to keep the orchestrator
+ * function under the per-file LOC budget.
+ *
+ * Tier resolution: the CLI flag takes precedence; the patch's existing
+ * tier is the fallback. Lint-ignore resolution: union of the patch's
+ * existing list and the CLI flag values, de-duplicated; an empty
+ * result returns `undefined` so the caller can drop the field rather
+ * than write an empty array.
+ */
+function resolveEffectiveTierAndLintIgnore(target, options) {
+    const existingIgnoreSet = new Set(target.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const effectiveTier = options.tier ?? target.tier;
+    return { effectiveTier, effectiveLintIgnore, flagIgnoreSet };
+}
+/**
+ * Projects the cross-patch context (replace the target entry with its
+ * shrunken self), runs the patch-queue lint against the projection,
+ * and returns a conflict report only for regressions introduced *by*
+ * this shrink. Pre-existing cross-patch errors are surfaced as a
+ * non-blocking warning so the user does not walk away thinking the
+ * queue is clean. Extracted from {@link reExportFilesInPlace} to keep
+ * the orchestrator function under the per-file LOC budget.
+ */
+async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const projectedNewFiles = new Map();
+    for (const path of detectNewFilesInDiff(projectedDiff)) {
+        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
+    }
+    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
+    const projectedEntries = baseCtx.entries.map((entry) => {
+        if (entry.filename !== targetFilename)
+            return entry;
+        return {
+            ...entry,
+            diff: projectedDiff,
+            newFiles: projectedNewFiles,
+            modifiedFileAdditions: projectedModifiedFileAdditions,
+        };
+    });
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    if (baselineIssues.length > 0 && regressions.length === 0) {
+        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
+            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
+    }
+    if (regressions.length === 0)
+        return null;
+    return {
+        reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
+        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+    };
+}
+/**
+ * Builds the `Partial<PatchMetadata>` payload for the `--files` write,
+ * folding in the CLI flag overrides for `tier` and `lintIgnore` only
+ * when the operator actually asked for them. Extracted to keep
+ * {@link reExportFilesInPlace} under the per-file LOC budget.
+ */
+function buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet) {
+    const updates = {
+        filesAffected: actualProjectedFiles,
+    };
+    if (options.tier !== undefined) {
+        updates.tier = options.tier;
+    }
+    if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+        updates.lintIgnore = effectiveLintIgnore;
+    }
+    return updates;
+}
 /**
  * Handles `re-export --files` end-to-end: computes the projected diff,
  * runs the per-patch and cross-patch lint against a context in which the
@@ -77,50 +156,13 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // have to choose between `--skip-lint` (blunt) and the full rebase path.
     // `target.tier` threads the explicit branding-threshold opt-in for
     // the branding patch that also touches a non-allowlisted sibling.
-    const ignoreChecks = target.lintIgnore?.length ? new Set(target.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, target.tier);
-    // 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
-    // source-site maps so the forward-import rule sees imports the
-    // shrunken diff would add — or stop adding — consistently with how a
-    // real rebuild would see them.
-    const baseCtx = await buildPatchQueueContext(paths.patches);
-    const projectedNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(projectedDiff)) {
-        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
-    }
-    const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
-    const projectedEntries = baseCtx.entries.map((entry) => {
-        if (entry.filename !== target.filename)
-            return entry;
-        return {
-            ...entry,
-            diff: projectedDiff,
-            newFiles: projectedNewFiles,
-            modifiedFileAdditions: projectedModifiedFileAdditions,
-        };
-    });
-    // Baseline-vs-projected diffing: only regressions introduced *by* this
-    // shrink should block. A pre-existing cross-patch error elsewhere in
-    // the queue must not prevent the user from shrinking an unrelated
-    // patch (which is often exactly the tool they reach for to repair
-    // such a queue).
-    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
-    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
-    const conflicts = regressions.length > 0
-        ? {
-            reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
-            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
-        }
-        : null;
-    // Surface pre-existing errors as a non-blocking warning so the user
-    // doesn't walk away thinking the queue is clean.
-    if (baselineIssues.length > 0 && regressions.length === 0) {
-        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
-            `cross-patch error(s) unrelated to this shrink. Run "fireforge verify" to list them.`);
-    }
+    // CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (matching the
+    // standard re-export path).
+    const { effectiveTier, effectiveLintIgnore, flagIgnoreSet } = resolveEffectiveTierAndLintIgnore(target, options);
+    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    await runPatchLint(paths.engine, actualProjectedFiles, projectedDiff, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
+    const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff);
     // Shrinks are destructive (previously-owned files become unmanaged).
     // Additive-only changes still deserve a prompt because --files asserts
     // an authoritative file set.
@@ -163,7 +205,8 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // directory lock as the mutation (via the onCommitted hook) so two
     // concurrent re-exports cannot interleave records and a crash between
     // mutation and append cannot orphan the audit trail.
-    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, { filesAffected: actualProjectedFiles }, async () => {
+    const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
+    await updatePatchAndMetadata(paths.patches, target.filename, projectedDiff, filesUpdates, async () => {
         await appendHistory(paths.patches, {
             operation: 're-export-files',
             args: {

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
 import { confirm, multiselect } from '@clack/prompts';
+import { Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
@@ -204,10 +205,29 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     // The paired `patch.tier` threads the explicit branding-threshold
     // opt-in the same way, for the branding patch that also touches a
     // non-allowlisted registration sibling.
-    const ignoreChecks = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, patch.tier);
+    //
+    // The CLI flags `--tier` and `--lint-ignore` participate too, with
+    // append/union semantics on the lint-ignore list (the operator's
+    // intuition for "I want this patch to also suppress X" — explicit
+    // removal lives on the `fireforge patch lint-ignore` subcommand).
+    // Computed before the lint pass so the new intent takes effect on
+    // this invocation, not the next one.
+    const existingIgnoreSet = new Set(patch.lintIgnore ?? []);
+    const flagIgnoreSet = new Set(options.lintIgnore ?? []);
+    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
+    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    const effectiveTier = options.tier ?? patch.tier;
+    await runPatchLint(paths.engine, existingFiles, diffContent, config, options.skipLint, undefined, ignoreChecks, effectiveTier);
     if (isDryRun) {
         info(`[dry-run] ${patch.filename}: ${existingFiles.length} file(s)`);
+        if (effectiveTier !== undefined && effectiveTier !== patch.tier) {
+            info(`[dry-run] ${patch.filename}: tier would become ${effectiveTier}`);
+        }
+        const addedIgnores = [...flagIgnoreSet].filter((id) => !existingIgnoreSet.has(id));
+        if (addedIgnores.length > 0) {
+            info(`[dry-run] ${patch.filename}: lintIgnore would gain ${addedIgnores.join(', ')}`);
+        }
     }
     else {
         // Atomic body + manifest update under a single patch-directory lock.
@@ -215,9 +235,16 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         // sequence allows a concurrent `resolve` / `rebase --continue` / `patch
         // compact` / `patch reorder` to rewrite the manifest between the two
         // writes and leave patch body and `filesAffected` disagreeing.
-        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, {
+        const updates = {
             filesAffected: currentFilesAffected,
-        });
+        };
+        if (options.tier !== undefined) {
+            updates.tier = options.tier;
+        }
+        if (effectiveLintIgnore !== undefined && flagIgnoreSet.size > 0) {
+            updates.lintIgnore = effectiveLintIgnore;
+        }
+        await updatePatchAndMetadata(paths.patches, patch.filename, diffContent, updates);
         // Keep the in-memory manifest in sync so subsequent iterations (notably
         // `--all --scan`, where `getClaimedFiles` reads from this manifest) see
         // the just-written `filesAffected`. The on-disk write above is the
@@ -228,7 +255,7 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
             if (existingEntry) {
                 manifest.patches[patchIndex] = {
                     ...existingEntry,
-                    filesAffected: currentFilesAffected,
+                    ...updates,
                 };
             }
         }
@@ -291,6 +318,15 @@ export async function reExportCommand(projectRoot, patches, options) {
             throw new InvalidArgumentError('--files operates on exactly one target patch. Pass a single patch identifier.', '--files');
         }
     }
+    // --tier and --lint-ignore are per-patch metadata edits; combining them
+    // with --all silently rewrites every patch's tier/ignore list, which is
+    // virtually always wrong (different patches have different shapes).
+    // Refuse the combination so the operator must enumerate the targets.
+    const usingTierFlag = options.tier !== undefined;
+    const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
+    if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {
+        throw new InvalidArgumentError('--tier and --lint-ignore require explicit patch identifiers and cannot be combined with --all (different patches typically need different metadata).', '--all');
+    }
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
     if (!(await pathExists(paths.engine))) {
@@ -396,8 +432,15 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .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.")
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', (value, prev) => [...prev, value], [])
         .action(withErrorHandling(async (patches, options) => {
-        await reExportCommand(getProjectRoot(), patches, pickDefined(options));
+        const { tier, lintIgnore, ...rest } = options;
+        await reExportCommand(getProjectRoot(), patches, {
+            ...pickDefined(rest),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
+        });
     }));
 }
 //# sourceMappingURL=re-export.js.map

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) {