@hominis/fireforge 0.16.5 → 0.17.0

package/dist/src/commands/lint.js

@@ -1,10 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { getStatusWithCodes, hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
+import { getModifiedFiles, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 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';
@@ -22,8 +23,19 @@ import { stripEnginePrefix } from '../utils/paths.js';
  * 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.
+ *
+ * When `binaryName` is provided, the aggregate-mode branch (no
+ * explicit file list) excludes paths under `browser/branding/<binaryName>/`
+ * from the diff. `status` classifies those paths as `branding` —
+ * tool-managed material the operator did not author directly — and
+ * the 2026-04-21 eval (Finding #2) reported that `fireforge lint` on
+ * a fresh project immediately failed `large-patch-lines` /
+ * `large-patch-files` / `missing-license-header` on the generated
+ * branding tree. File-list mode (explicit paths) preserves the
+ * previous behaviour: passing a branding file explicitly still lints
+ * it, so operators who need to audit branding content can do so.
  */
-async function resolveLintDiff(engineDir, files) {
+async function resolveLintDiff(engineDir, files, binaryName) {
     if (files.length > 0) {
         const collectedFiles = new Set();
         let fileStatuses;
@@ -83,6 +95,40 @@ async function resolveLintDiff(engineDir, files) {
         outro('Nothing to lint');
         return null;
     }
+    // Aggregate-mode branding exclusion. A fresh-setup workspace (after
+    // `fireforge setup` + `download` + `bootstrap` + `build`) carries a
+    // large tool-managed branding diff that the operator did not
+    // author; running the default lint against it fires size and
+    // license-header rules on content that was never intended to
+    // survive in the patch queue as-is. The exclusion mirrors the
+    // `branding` bucket in `fireforge status` so the two views stay
+    // consistent.
+    if (binaryName) {
+        const modified = await getModifiedFiles(engineDir);
+        const untracked = await getUntrackedFiles(engineDir);
+        const allPaths = [...new Set([...modified, ...untracked])];
+        const nonBrandingPaths = allPaths.filter((path) => !isBrandingManagedPath(path, binaryName));
+        const excludedCount = allPaths.length - nonBrandingPaths.length;
+        if (excludedCount > 0) {
+            info(`Excluded ${excludedCount} tool-managed branding file${excludedCount === 1 ? '' : 's'} from lint. Pass the path explicitly or use \`fireforge lint <path>\` to include them.`);
+        }
+        if (nonBrandingPaths.length === 0) {
+            info('No non-branding changes to lint.');
+            outro('Nothing to lint');
+            return null;
+        }
+        const diff = await getDiffForFilesAgainstHead(engineDir, nonBrandingPaths.sort());
+        if (!diff.trim()) {
+            info('No diff content to lint.');
+            outro('Nothing to lint');
+            return null;
+        }
+        return diff;
+    }
+    // Fallback path: no binaryName available (e.g. a legacy caller
+    // without a loaded config). Retain the pre-0.16.0 behaviour of
+    // linting the full diff so the lint surface is at least as broad
+    // as before.
     const diff = await getAllDiff(engineDir);
     if (!diff.trim()) {
         info('No diff content to lint.');
@@ -126,10 +172,15 @@ export async function lintCommand(projectRoot, files, options = {}) {
         await lintPerPatch(projectRoot, paths);
         return;
     }
-    const diff = await resolveLintDiff(paths.engine, files);
+    // Load the config before resolving the diff so we can pass
+    // `binaryName` into the aggregate-mode branding exclusion in
+    // `resolveLintDiff`. The config was previously loaded only after
+    // the diff was resolved; hoisting it is cheap and keeps the two
+    // call sites close together.
+    const config = await loadConfig(projectRoot);
+    const diff = await resolveLintDiff(paths.engine, files, config.binaryName);
     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
     // per-patch ownership resolver and the cross-patch rules.

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

@@ -1,9 +1,33 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+/**
+ * Options accepted by {@link resolveCommand}.
+ */
+export interface ResolveCommandOptions {
+    /**
+     * Skip the interactive "Have you finished fixing the files?"
+     * confirmation prompt and treat the resolution as complete.
+     *
+     * Motivating case (2026-04-21 eval, Finding #18): a scripted or
+     * CI-assisted recovery flow that has already completed the manual
+     * merge step cannot advance through `fireforge resolve` because the
+     * TTY guard refuses non-interactive invocations outright. `--yes`
+     * is the explicit opt-in for those flows: the operator is asserting
+     * they have already done the merge, and the command proceeds
+     * straight to the patch-refresh + state-clear path.
+     *
+     * The guard without `--yes` is preserved — running `resolve` with
+     * no TTY and no `--yes` still refuses so an accidental pipe-into
+     * invocation doesn't silently commit whatever the engine happens
+     * to contain.
+     */
+    yes?: boolean;
+}
 /**
  * Runs the resolve command to fix broken patches.
  * @param projectRoot - Root directory of the project
+ * @param options - Optional flags; see {@link ResolveCommandOptions}.
  */
-export declare function resolveCommand(projectRoot: string): Promise<void>;
+export declare function resolveCommand(projectRoot: string, options?: ResolveCommandOptions): Promise<void>;
 /** Registers the resolve command on the CLI program. */
 export declare function registerResolve(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/resolve.js

@@ -15,8 +15,9 @@ import { error as logError, info, intro, isCancel, outro, spinner, success, } fr
 /**
  * Runs the resolve command to fix broken patches.
  * @param projectRoot - Root directory of the project
+ * @param options - Optional flags; see {@link ResolveCommandOptions}.
  */
-export async function resolveCommand(projectRoot) {
+export async function resolveCommand(projectRoot, options = {}) {
     intro('FireForge Resolve');
     const paths = getProjectPaths(projectRoot);
     const state = await loadState(projectRoot);
@@ -35,17 +36,25 @@ export async function resolveCommand(projectRoot) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
-    if (!process.stdin.isTTY) {
-        throw new GeneralError('Cannot run "fireforge resolve" in non-interactive mode. Use a terminal with TTY support.');
+    // Non-interactive mode requires an explicit `--yes` to proceed: the
+    // operator is asserting the manual merge is complete and the
+    // refreshed diff is the one to record. Without `--yes`, an accidental
+    // pipe / CI shell could otherwise commit whatever the engine
+    // currently contains. 2026-04-21 eval (Finding #18): a scripted
+    // recovery flow was dead-ended by the unconditional TTY refusal.
+    if (!process.stdin.isTTY && !options.yes) {
+        throw new GeneralError('Cannot run "fireforge resolve" in non-interactive mode. Use a terminal with TTY support, or pass "--yes" to skip the interactive confirmation once the manual merge is complete.');
     }
-    const finished = await confirm({
-        message: 'Have you finished manually fixing the files in engine/?',
-        initialValue: true,
-    });
-    if (isCancel(finished) || !finished) {
-        info('Please fix the conflicts and run "fireforge resolve" again.');
-        outro('Resolution paused');
-        return;
+    if (!options.yes) {
+        const finished = await confirm({
+            message: 'Have you finished manually fixing the files in engine/?',
+            initialValue: true,
+        });
+        if (isCancel(finished) || !finished) {
+            info('Please fix the conflicts and run "fireforge resolve" again.');
+            outro('Resolution paused');
+            return;
+        }
     }
     const manifest = await loadPatchesManifest(paths.patches);
     if (!manifest) {
@@ -138,7 +147,7 @@ export async function resolveCommand(projectRoot) {
         });
         s.stop(`Updated ${patchFilename}`);
         success('Patch updated successfully and resolution state cleared.');
-        info('Run "fireforge import" to apply the remaining patches.');
+        info('Patch updated. Run "fireforge import" next to resume the queue from this point — resolve only refreshes the one broken patch, it does not continue applying the remaining patches itself.');
         outro('Resolution complete');
     }
     catch (error) {
@@ -151,9 +160,10 @@ export async function resolveCommand(projectRoot) {
 export function registerResolve(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('resolve')
-        .description('Update a broken patch with manual fixes and continue')
-        .action(withErrorHandling(async () => {
-        await resolveCommand(getProjectRoot());
+        .description('Update a broken patch with manual fixes (then run "fireforge import" to resume the queue)')
+        .option('-y, --yes', 'Skip the interactive confirmation prompt. Use for non-interactive automation flows (CI, scripted recovery) after the manual merge is complete.')
+        .action(withErrorHandling(async (options) => {
+        await resolveCommand(getProjectRoot(), options);
     }));
 }
 //# sourceMappingURL=resolve.js.map

package/dist/src/commands/status.js

@@ -1,19 +1,15 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { isBrandingManagedPath } from '../core/branding.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { getUntrackedFilesInDir } from '../core/git-status.js';
 import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
 import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-table.js';
-import { computePatchedContent } from '../core/patch-apply.js';
 import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { classifyFiles, } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { FIREFORGE_TMP_PATH_PATTERN, pathExists, readText } from '../utils/fs.js';
-import { info, intro, outro, verbose, warn } from '../utils/logger.js';
+import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
+import { info, intro, outro, warn } from '../utils/logger.js';
 /**
  * Status code descriptions for git status.
  */
@@ -179,87 +175,27 @@ async function expandDirectoryEntries(files, engineDir) {
 function filterFireForgeTempFiles(files) {
     return files.filter((entry) => !FIREFORGE_TMP_PATH_PATTERN.test(entry.file));
 }
-/**
- * Classifies files into patch-backed, unmanaged, or branding buckets.
- */
-async function classifyFiles(files, engineDir, patchesDir, binaryName, furnacePrefixes) {
-    const manifest = await loadPatchesManifest(patchesDir);
-    // Build set of all patch-claimed file paths
-    const patchClaimedFiles = new Set();
-    if (manifest) {
-        for (const patch of manifest.patches) {
-            for (const f of patch.filesAffected) {
-                patchClaimedFiles.add(f);
-            }
-        }
-    }
-    const results = [];
-    for (const entry of files) {
-        // Branding check first
-        if (isBrandingManagedPath(entry.file, binaryName)) {
-            results.push({ ...entry, classification: 'branding' });
-            continue;
-        }
-        // Furnace-managed component paths
-        if (furnacePrefixes.size > 0) {
-            let isFurnace = false;
-            for (const prefix of furnacePrefixes) {
-                if (entry.file.startsWith(prefix)) {
-                    isFurnace = true;
-                    break;
-                }
-            }
-            if (isFurnace) {
-                results.push({ ...entry, classification: 'furnace' });
-                continue;
-            }
-        }
-        // Not in any patch → unmanaged
-        if (!patchClaimedFiles.has(entry.file)) {
-            results.push({ ...entry, classification: 'unmanaged' });
-            continue;
-        }
-        // File is claimed by a patch — compare content
-        const primaryCode = getPrimaryStatusCode(entry.status);
-        if (primaryCode === 'D') {
-            // Deleted file: patch-backed only if patch expects deletion
-            const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
-            results.push({
-                ...entry,
-                classification: expected === null ? 'patch-backed' : 'unmanaged',
-            });
-            continue;
-        }
-        // File exists on disk — compare actual vs expected
-        try {
-            const [expected, actual] = await Promise.all([
-                computePatchedContent(patchesDir, engineDir, entry.file),
-                readText(join(engineDir, entry.file)),
-            ]);
-            results.push({
-                ...entry,
-                classification: actual === expected ? 'patch-backed' : 'unmanaged',
-            });
-        }
-        catch (error) {
-            verbose(`Treating ${entry.file} as unmanaged because patch-backed classification failed: ${toError(error).message}`);
-            // If we can't read the file, treat as unmanaged
-            results.push({ ...entry, classification: 'unmanaged' });
-        }
-    }
-    return results;
-}
 /**
  * Renders classified file status as machine-readable JSON to stdout.
  */
 async function renderJsonStatus(files, paths, projectRoot, binaryName) {
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
     const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
-    const output = classified.map((f) => ({
-        file: f.file,
-        status: f.status.trim(),
-        classification: f.classification,
-    }));
+    const output = classified.map((f) => {
+        const entry = {
+            file: f.file,
+            status: f.status.trim(),
+            classification: f.classification,
+        };
+        // `claimedBy` is an optional field present only on conflict
+        // entries, so non-conflict output stays byte-identical to the
+        // pre-0.16.0 shape (no unconditional schema change for the
+        // 99% of entries that are not cross-patch conflicts).
+        if (f.classification === 'conflict' && f.claimedBy && f.claimedBy.length > 0) {
+            entry.claimedBy = [...f.claimedBy];
+        }
+        return entry;
+    });
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
 }
 /**
@@ -394,65 +330,107 @@ export async function statusCommand(projectRoot, options = {}) {
     // Patch-aware classification
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
     const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
-    const unmanagedFiles = classified.filter((f) => f.classification === 'unmanaged');
-    const patchBackedFiles = classified.filter((f) => f.classification === 'patch-backed');
-    const brandingFiles = classified.filter((f) => f.classification === 'branding');
-    const furnaceFiles = classified.filter((f) => f.classification === 'furnace');
+    const buckets = {
+        conflict: classified.filter((f) => f.classification === 'conflict'),
+        unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
+        patchBacked: classified.filter((f) => f.classification === 'patch-backed'),
+        branding: classified.filter((f) => f.classification === 'branding'),
+        furnace: classified.filter((f) => f.classification === 'furnace'),
+    };
     // --unmanaged mode: only show unmanaged
     if (options.unmanaged) {
-        info(`${unmanagedFiles.length} unmanaged file${unmanagedFiles.length === 1 ? '' : 's'} (${files.length} total modified):\n`);
-        if (unmanagedFiles.length > 0) {
-            printStatusGroups(unmanagedFiles);
-            await printUnregisteredWarnings(unmanagedFiles, projectRoot, config.binaryName);
-        }
-        else {
-            info('No unmanaged changes');
-        }
-        outro(unmanagedFiles.length === 0
-            ? 'No unmanaged changes'
-            : `${unmanagedFiles.length} unmanaged change${unmanagedFiles.length === 1 ? '' : 's'}`);
+        await renderUnmanagedOnly(buckets.unmanaged, files.length, projectRoot, config.binaryName);
         return;
     }
-    // Default mode: three-bucket display
-    info(`${files.length} modified file${files.length === 1 ? '' : 's'}:\n`);
+    await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
+}
+async function renderUnmanagedOnly(unmanagedFiles, totalModified, projectRoot, binaryName) {
+    info(`${unmanagedFiles.length} unmanaged file${unmanagedFiles.length === 1 ? '' : 's'} (${totalModified} total modified):\n`);
     if (unmanagedFiles.length > 0) {
-        warn('Unmanaged changes:');
         printStatusGroups(unmanagedFiles);
-        await printUnregisteredWarnings(unmanagedFiles, projectRoot, config.binaryName);
+        await printUnregisteredWarnings(unmanagedFiles, projectRoot, binaryName);
+    }
+    else {
+        info('No unmanaged changes');
+    }
+    outro(unmanagedFiles.length === 0
+        ? 'No unmanaged changes'
+        : `${unmanagedFiles.length} unmanaged change${unmanagedFiles.length === 1 ? '' : 's'}`);
+}
+/**
+ * Renders the default five-bucket status display: conflicts first
+ * (they block export/import/rebase), then unmanaged, patch-backed,
+ * branding, and furnace-managed sections. Cross-bucket separators
+ * ensure the sections are visually distinct without trailing empty
+ * groups. Empty buckets are omitted — the very-empty case surfaces a
+ * single `No changes` line.
+ */
+async function renderDefaultStatus(totalModified, buckets, projectRoot, binaryName) {
+    const { conflict, unmanaged, patchBacked, branding, furnace } = buckets;
+    info(`${totalModified} modified file${totalModified === 1 ? '' : 's'}:\n`);
+    if (conflict.length > 0) {
+        // Surface cross-patch ownership conflicts at the top of the default
+        // output — they block export/import/rebase and want immediate
+        // attention. The `--ownership` view already renders the full table;
+        // here we just name the files and point the operator at the
+        // canonical recovery path.
+        warn('Cross-patch ownership conflicts (same file claimed by multiple patches):');
+        printStatusGroups(conflict);
+        for (const entry of conflict) {
+            if (entry.claimedBy && entry.claimedBy.length > 0) {
+                info(`  ${entry.file} — claimed by ${entry.claimedBy.join(', ')}`);
+            }
+        }
+        info('Run "fireforge status --ownership" for the full conflict table, then repartition with "fireforge re-export --files <paths> <patch>".');
     }
-    if (patchBackedFiles.length > 0) {
-        if (unmanagedFiles.length > 0)
+    if (unmanaged.length > 0) {
+        if (conflict.length > 0)
+            info('');
+        warn('Unmanaged changes:');
+        printStatusGroups(unmanaged);
+        await printUnregisteredWarnings(unmanaged, projectRoot, binaryName);
+    }
+    if (patchBacked.length > 0) {
+        if (conflict.length > 0 || unmanaged.length > 0)
             info('');
         warn('Patch-backed materialized changes:');
-        printStatusGroups(patchBackedFiles);
+        printStatusGroups(patchBacked);
     }
-    if (brandingFiles.length > 0) {
-        if (unmanagedFiles.length > 0 || patchBackedFiles.length > 0)
+    if (branding.length > 0) {
+        if (conflict.length > 0 || unmanaged.length > 0 || patchBacked.length > 0) {
             info('');
+        }
         warn('Tool-managed branding changes:');
-        printStatusGroups(brandingFiles);
+        printStatusGroups(branding);
     }
-    if (furnaceFiles.length > 0) {
-        if (unmanagedFiles.length > 0 || patchBackedFiles.length > 0 || brandingFiles.length > 0)
+    if (furnace.length > 0) {
+        if (conflict.length > 0 ||
+            unmanaged.length > 0 ||
+            patchBacked.length > 0 ||
+            branding.length > 0) {
             info('');
+        }
         warn('Furnace-managed component changes:');
-        printStatusGroups(furnaceFiles);
+        printStatusGroups(furnace);
     }
-    if (unmanagedFiles.length === 0 &&
-        patchBackedFiles.length === 0 &&
-        brandingFiles.length === 0 &&
-        furnaceFiles.length === 0) {
+    if (conflict.length === 0 &&
+        unmanaged.length === 0 &&
+        patchBacked.length === 0 &&
+        branding.length === 0 &&
+        furnace.length === 0) {
         info('No changes');
     }
     const parts = [];
-    if (unmanagedFiles.length > 0)
-        parts.push(`${unmanagedFiles.length} unmanaged`);
-    if (patchBackedFiles.length > 0)
-        parts.push(`${patchBackedFiles.length} patch-backed`);
-    if (brandingFiles.length > 0)
-        parts.push(`${brandingFiles.length} branding`);
-    if (furnaceFiles.length > 0)
-        parts.push(`${furnaceFiles.length} furnace`);
+    if (conflict.length > 0)
+        parts.push(`${conflict.length} conflict`);
+    if (unmanaged.length > 0)
+        parts.push(`${unmanaged.length} unmanaged`);
+    if (patchBacked.length > 0)
+        parts.push(`${patchBacked.length} patch-backed`);
+    if (branding.length > 0)
+        parts.push(`${branding.length} branding`);
+    if (furnace.length > 0)
+        parts.push(`${furnace.length} furnace`);
     outro(parts.join(', '));
 }
 /** Registers the status command on the CLI program. */

package/dist/src/commands/test.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 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 { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
@@ -148,10 +149,13 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         throw new GeneralError(`Tests require a completed build. ${detail}\n\n` +
             "Run 'fireforge build' first, then run 'fireforge test'.");
     }
+    // Load the project config once so both the build and the port
+    // probe have access to `binaryName` (the port probe uses it to
+    // recognise a fork-branded browser holding the Marionette port).
+    const projectConfig = await loadConfig(projectRoot);
     // Run incremental build if requested
     if (options.build) {
-        const config = await loadConfig(projectRoot);
-        await prepareBuildEnvironment(projectRoot, paths, config);
+        await prepareBuildEnvironment(projectRoot, paths, projectConfig);
         const s = spinner('Running incremental build...');
         const buildExitCode = await buildUI(paths.engine);
         if (buildExitCode !== 0) {
@@ -175,6 +179,15 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             warn(formatStaleBuildWarning(stale));
         }
     }
+    // Stale-browser probe: an interrupted earlier test run can leave a
+    // Firefox/ForgeFresh/Hominis instance listening on the Marionette
+    // control port, which breaks the next mach test launch with a
+    // bind error that points nowhere near the real cause. Raise a
+    // targeted refusal up front instead of letting mach surface the
+    // generic bind failure. 2026-04-21 eval (Finding #20): a stale
+    // `-marionette` process from `fresh/` poisoned a later test run in
+    // the sibling `hominis/` workspace.
+    await assertMarionettePortAvailable(undefined, { binaryName: projectConfig.binaryName });
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell

package/dist/src/commands/wire.js

@@ -4,7 +4,7 @@ import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wi
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
-import { DEFAULT_DOM_TARGET } from '../core/wire-dom-fragment.js';
+import { DEFAULT_DOM_TARGET, probeDomFragmentInsertionPoint } from '../core/wire-dom-fragment.js';
 import { coerceToCall, validateWireName as validateWireExpression } from '../core/wire-utils.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -83,6 +83,34 @@ function validateWireName(name) {
             'Path separators and parent-directory segments are not permitted.', 'name');
     }
 }
+/**
+ * Asserts that the resolved chrome document both exists on disk AND
+ * exposes an insertion anchor (`#include browser-sets.inc` or
+ * `<html:body>`) that `addDomFragment` can splice into. Fires the same
+ * check in dry-run and real-run mode, so the preview and execution
+ * agree on whether the target is wireable before any disk mutations
+ * happen. Before 0.16.0 this check only ran on the real branch, which
+ * let the dry-run produce a plausible-looking plan that the real run
+ * then refused with `Could not find insertion point in chrome document`.
+ */
+async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath) {
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(join(paths.engine, domTargetPath)))) {
+        throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
+            'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
+            'or pass --target <path>.', 'target');
+    }
+    try {
+        await probeDomFragmentInsertionPoint(paths.engine, domFilePath, domTargetPath);
+    }
+    catch (probeError) {
+        throw new InvalidArgumentError(`${probeError instanceof Error ? probeError.message : String(probeError)}\n` +
+            `The resolved chrome document ${domTargetPath} does not expose an insertion anchor ` +
+            'that `fireforge wire` recognises (`#include browser-sets.inc` or `<html:body>`). ' +
+            'Add one of those anchors to the chrome doc, or target a document that has them via ' +
+            '`--target <path>`.', 'target');
+    }
+}
 /**
  * Wires a chrome subscript into the browser.
  *
@@ -192,14 +220,12 @@ export async function wireCommand(projectRoot, name, options = {}) {
     }
     const domTargetPath = await resolveDomTargetPath(projectRoot, normalizedTarget);
     if (domFilePath) {
-        const paths = getProjectPaths(projectRoot);
-        if (!options.dryRun && !(await pathExists(join(paths.engine, domTargetPath)))) {
-            throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
-                'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
-                'or pass --target <path>.', 'target');
-        }
+        await assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath);
     }
-    // Verify the subscript file exists in engine/ (skip for dry-run)
+    // Verify the subscript file exists in engine/ (skip for dry-run:
+    // 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).
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
         const subscriptPath = join(paths.engine, subscriptDir, `${name}.js`);

package/dist/src/core/config.d.ts

@@ -52,5 +52,38 @@ export declare function writeConfig(root: string, config: FireForgeConfig): Prom
  * Writes a raw config document to fireforge.json.
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
+ *
+ * Individual writes are atomic via {@link writeJson} (temp file + rename),
+ * but atomicity alone does not prevent lost updates across concurrent
+ * writers: each writer reads an old copy, mutates its own in-memory view,
+ * and writes it back, so the second writer's rename clobbers the first
+ * writer's changes. Callers that do read → mutate → write must hold
+ * {@link withConfigFileLock} for the full round-trip to serialise
+ * against other writers.
  */
 export declare function writeConfigDocument(root: string, config: FireForgeConfig | Record<string, unknown>): Promise<void>;
+/**
+ * Runs an operation while holding a sidecar lock on `fireforge.json`.
+ *
+ * Motivating case (2026-04-21 eval): two concurrent `fireforge config
+ * <key> <value>` invocations each ran load → mutate → writeJson against
+ * the same on-disk fireforge.json. The second rename landed after the
+ * first, silently dropping the first writer's key — both commands exited
+ * `0`, but only one change survived. This helper turns the same
+ * read-modify-write sequence into a serialised operation so a concurrent
+ * writer now waits for the lock rather than racing on the document.
+ *
+ * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
+ * always use `writeJson`'s atomic temp-file + rename, so a reader observes
+ * either the pre- or post-write document but never a torn file. The lock
+ * only serialises writers against other writers.
+ *
+ * The lock is a sidecar directory `${config}.fireforge-config.lock`, and
+ * `withFileLock` handles stale-lock recovery (PID-alive probe, age-based
+ * fallback) — a crashed writer does not permanently block future writes.
+ *
+ * @param root - Root directory of the project
+ * @param operation - Async function to run while holding the lock
+ * @returns Whatever the operation returns
+ */
+export declare function withConfigFileLock<T>(root: string, operation: () => Promise<T>): Promise<T>;