@hominis/fireforge 0.16.5 → 0.18.0

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,13 +3,14 @@ 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';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 async function assertTestPathsExist(engineDir, testPaths) {
@@ -46,6 +47,32 @@ function hasStaleBuildArtifactsSignal(output) {
     return (/chrome:\/\/branding\/locale\/brand\.properties/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
+/**
+ * Fork-module-not-registered signal. 2026-04-21 eval Finding #14:
+ * a hominis test failed with `Failed to load resource:///modules/hominis/
+ * HominisStore.sys.mjs`. The branding pattern happened to also match
+ * because the test harness printed a branding warning during its
+ * teardown, and the stale-build branch won by precedence — telling the
+ * operator to rebuild when the real fix is to register the module in
+ * the fork's `browser/modules/<binary>/moz.build`. Match a
+ * `resource:///modules/<binaryName>/` pattern so fork-owned module
+ * failures surface the right diagnosis.
+ */
+function hasForkModuleSignal(output, binaryName) {
+    const pattern = new RegExp(`Failed to load resource:\\/\\/\\/modules\\/${binaryName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\/`, 'i');
+    return pattern.test(output);
+}
+function buildForkModuleMessage(binaryName) {
+    return (`Test failed to load a fork-owned module at resource:///modules/${binaryName}/*.sys.mjs.\n\n` +
+        'This is almost always a module-registration issue, not a stale build. The fork module directory is missing an entry that maps its file into the resource URI tree, so `ChromeUtils.importESModule` cannot resolve it.\n\n' +
+        'Check that:\n' +
+        `  - browser/modules/${binaryName}/moz.build lists the missing module in EXTRA_JS_MODULES.\n` +
+        `  - browser/modules/moz.build references the ${binaryName}/ subdirectory (DIRS += [...]).\n` +
+        '  - The last `fireforge build` (or `fireforge build --ui`) completed successfully against the current manifests. If the registration is new, the UI-faster build path may not pick it up — a full build may be required.\n\n' +
+        'Use `fireforge register browser/modules/' +
+        binaryName +
+        '/<file>.sys.mjs` to add the EXTRA_JS_MODULES entry if it is missing.');
+}
 // Detects the broader xpcshell symptom where every `resource:///modules/...`
 // import fails — the signature of xpcshell running with the wrong app-dir on
 // a manifest that sets `firefox-appdir = "browser"`. Checked AFTER the
@@ -86,13 +113,22 @@ function buildMochitestHttp3ServerMessage() {
         "  - The `BROWSER_CHROME_MANIFESTS` entry for your fork's chrome.manifest is registered.\n\n" +
         'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
 }
-function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted) {
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
     if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
         throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
     }
+    // Fork-owned module load failures must beat the branding stale-build
+    // branch: 2026-04-21 eval (Finding #14) saw a hominis test fail with
+    // `Failed to load resource:///modules/hominis/HominisStore.sys.mjs`
+    // while the harness teardown printed a branding warning that the old
+    // stale-build pattern matched, so the operator was told to rebuild
+    // when the real fix is to register the missing module.
+    if (hasForkModuleSignal(combinedOutput, binaryName)) {
+        throw new GeneralError(buildForkModuleMessage(binaryName));
+    }
     // Branding-specific stale-build signals keep priority over the broader
     // xpcshell-appdir hint: when `chrome://branding/locale/brand.properties`
     // fails to resolve, the fix really is "rebuild", not "pass --app-path".
@@ -148,13 +184,16 @@ 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) {
+        const buildResult = await buildUI(paths.engine);
+        if (buildResult.exitCode !== 0) {
             s.error('Pre-test build failed');
             throw new BuildError('Pre-test build failed', 'mach build faster');
         }
@@ -175,6 +214,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
@@ -187,13 +235,19 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             if (!preflight.ok) {
                 throw new GeneralError('Marionette preflight reported FAIL — see output above.');
             }
-            // Close the intro frame explicitly. Without an outro, clack's
-            // grouped-output mode left the PASS line hanging inside an
-            // unclosed tree — in the eval's non-TTY capture the info line
-            // itself failed to render, so `test --doctor` looked like it had
-            // exited silently after the spinner start line. The outro also
-            // gives scripts a deterministic "done" marker to parse.
-            outro(`Marionette preflight: PASS (${preflight.durationMs}ms)`);
+            // 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);
+            outro('Test completed');
+            process.stdout.write(`${summary}\n`);
             return;
         }
         if (!preflight.ok) {
@@ -243,7 +297,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
-    handleNonZeroTestExit(result, normalizedPaths, appdirInjection);
+    handleNonZeroTestExit(result, normalizedPaths, appdirInjection, projectConfig.binaryName);
 }
 /**
  * Resolves and (when applicable) appends an `--app-path=<abs>` arg to

package/dist/src/commands/token-coverage.js

@@ -2,7 +2,8 @@
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
-import { getStatusWithCodes, isGitRepository } from '../core/git.js';
+import { isGitRepository } from '../core/git.js';
+import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { measureTokenCoverage } from '../core/token-coverage.js';
 import { getTokensCssPath } from '../core/token-manager.js';
 import { GeneralError } from '../errors/base.js';
@@ -23,8 +24,14 @@ export async function tokenCoverageCommand(projectRoot) {
     }
     const config = await loadConfig(projectRoot);
     const tokensCssPath = getTokensCssPath(config.binaryName);
-    const files = await getStatusWithCodes(paths.engine);
-    const statusCssFiles = files
+    // Expand collapsed `?? dir/` untracked entries so untracked CSS files
+    // inside a new patch-added directory are included in coverage. Before
+    // this, an imported fork that added a new CSS tree saw "No modified
+    // CSS files" because `git status --porcelain` collapsed the directory
+    // and the file-extension filter could not see the .css inside.
+    const rawStatus = await getWorkingTreeStatus(paths.engine);
+    const expandedStatus = await expandUntrackedDirectoryEntries(paths.engine, rawStatus);
+    const statusCssFiles = expandedStatus
         .filter((f) => f.file.endsWith('.css') && f.file !== tokensCssPath)
         .map((f) => f.file);
     // Also scan CSS files deployed by Furnace custom components. Deployed

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

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

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

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

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

package/dist/src/core/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>;