@hominis/fireforge 0.16.5 → 0.17.0

package/dist/src/core/config.js

@@ -8,11 +8,13 @@
  *   config-mutate.ts   — immutable config mutation
  *   config-state.ts    — state file management
  */
+import { basename } from 'node:path';
 import { ConfigError, ConfigNotFoundError } from '../errors/config.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
 export { CONFIG_FILENAME, CONFIGS_DIR, ENGINE_DIR, FIREFORGE_DIR, getProjectPaths, PATCHES_DIR, SRC_DIR, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
@@ -97,9 +99,50 @@ export async function writeConfig(root, config) {
  * 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 async function writeConfigDocument(root, config) {
     const paths = getProjectPaths(root);
     await writeJson(paths.config, config);
 }
+/**
+ * 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 async function withConfigFileLock(root, operation) {
+    const paths = getProjectPaths(root);
+    return withFileLock(createSiblingLockPath(paths.config, '.fireforge-config.lock'), operation, {
+        onTimeoutMessage: `Timed out waiting to update ${basename(paths.config)}. ` +
+            'If no other fireforge process is running, remove the stale lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge config lock for ${basename(paths.config)} ` +
+            `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
+    });
+}
 //# sourceMappingURL=config.js.map

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

@@ -111,9 +111,30 @@ export declare function writeFurnaceConfig(root: string, config: FurnaceConfig):
 export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export declare function createDefaultFurnaceConfig(): FurnaceConfig;
+export declare function createDefaultFurnaceConfig(options?: {
+    binaryName?: string;
+}): FurnaceConfig;
 /**
  * Loads furnace config if it exists, or creates and writes a default config.
  * @param root - Root directory of the project

package/dist/src/core/furnace-config.js

@@ -460,16 +460,39 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
 }
 /**
  * Creates a default furnace configuration.
- * @returns A valid empty FurnaceConfig
+ *
+ * When a `binaryName` is provided, the default config carries a
+ * `tokenPrefix` derived as `--<binaryName>-`. Without that default,
+ * `fireforge token coverage` on a fresh project reports `0 tokens` and
+ * labels every custom-property reference as `unknown` — the scan has
+ * no prefix to key off. The 2026-04-21 eval walked directly into this
+ * state (`furnace init` → `token add` → `token coverage` → zero
+ * tokens), and only recovered after hand-editing furnace.json. Deriving
+ * the prefix from the binary name matches the convention the scaffolded
+ * tokens CSS already uses for its `--<binaryName>-*` declarations.
+ *
+ * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers
+ * on the legacy no-arg call shape (existing tests, programmatic callers
+ * bootstrapping from a not-yet-loaded config) still get a valid config
+ * without a prefix; the CLI init path always has a `binaryName` from
+ * `fireforge.json` and always sets one.
+ *
+ * @param options - Optional init context; pass `{ binaryName }` to
+ *   derive the token prefix.
+ * @returns A valid FurnaceConfig
  */
-export function createDefaultFurnaceConfig() {
-    return {
+export function createDefaultFurnaceConfig(options = {}) {
+    const config = {
         version: 1,
         componentPrefix: 'moz-',
         stock: [],
         overrides: {},
         custom: {},
     };
+    if (options.binaryName && options.binaryName.length > 0) {
+        config.tokenPrefix = `--${options.binaryName}-`;
+    }
+    return config;
 }
 /**
  * Loads furnace config if it exists, or creates and writes a default config.

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

@@ -73,6 +73,37 @@ export declare function build(engineDir: string, jobs?: number): Promise<number>
  * @returns Exit code
  */
 export declare function buildUI(engineDir: string): Promise<number>;
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
+ */
+export declare function withBuildLock<T>(projectRoot: string, operation: () => Promise<T>): Promise<T>;
 /**
  * Runs the built browser.
  * @param engineDir - Path to the engine directory

package/dist/src/core/mach.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
@@ -165,6 +166,49 @@ export async function buildUI(engineDir) {
     }
     return result.exitCode;
 }
+/**
+ * Runs an operation while holding a sidecar build lock keyed on the
+ * project root. Concurrent `fireforge build` / `fireforge build --ui`
+ * invocations against the same tree serialise instead of racing through
+ * the mach obj-dir.
+ *
+ * Motivating case (2026-04-21 eval): a `fireforge build --ui` run
+ * kicked off while a full `fireforge build` was still in flight against
+ * the same engine tree accepted the command and handed off to `mach
+ * build faster`, which failed almost immediately with `No rule to make
+ * target 'XUL'`. The real problem is that the first build had not yet
+ * materialised the full backend; the operator was left staring at a
+ * low-level make error with no link to the actual cause (a concurrent
+ * build in flight). The lock intercepts the second invocation before
+ * it touches mach, and the refusal message names the PID currently
+ * holding the lock so the operator can decide whether to wait or
+ * investigate a hung process.
+ *
+ * Stale-lock recovery: the lock stores the owner PID; a crashed build
+ * (SIGINT, SIGTERM, or a kernel kill) leaves the lock dir behind but
+ * not the owning process, and `withFileLock` removes the lock on the
+ * next attempt when `process.kill(pid, 0)` shows the owner is gone.
+ *
+ * The project-root variant is the right granularity: a single machine
+ * may have several FireForge projects side by side, and nothing says
+ * they cannot build in parallel. The lock serialises *within* one
+ * project, not across unrelated ones.
+ *
+ * Returns whatever the inner operation returns.
+ */
+export async function withBuildLock(projectRoot, operation) {
+    const lockPath = createSiblingLockPath(join(projectRoot, '.fireforge-build'), '.lock');
+    return withFileLock(lockPath, operation, {
+        // Default lock timeout is 30s; bump to 24h so a slow full build does
+        // not trip the timeout while the second invocation waits. A real
+        // operator will ^C long before 24h elapses; the ceiling is there
+        // purely so a forgotten lock cannot wedge the command forever.
+        timeoutMs: 24 * 60 * 60 * 1000,
+        onTimeoutMessage: `Timed out waiting for the FireForge build lock at ${lockPath}. ` +
+            'If no other `fireforge build` is running, remove the lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge build lock ${basename(lockPath)} (age: ${Math.round(ageMs / 1000)}s). A previous build process may have crashed.`,
+    });
+}
 /**
  * Runs the built browser.
  * @param engineDir - Path to the engine directory

package/dist/src/core/marionette-port.d.ts

@@ -0,0 +1,50 @@
+/** Default Marionette control port set by `-marionette`. */
+export declare const DEFAULT_MARIONETTE_PORT = 2828;
+/**
+ * Information about a process holding the Marionette port.
+ */
+export interface MarionettePortHolder {
+    /** OS process ID. */
+    pid: number;
+    /** Process basename (e.g. `forgefresh`, `firefox`). */
+    command: string;
+    /**
+     * Full command line the holder was launched with, when the probe
+     * can recover it. `lsof` by itself only returns the basename, so
+     * POSIX callers see `command === commandLine`; Windows callers
+     * recover the full command line via `Get-Process`. Used to detect
+     * the `-marionette` flag, which positively identifies a stale
+     * browser rather than an unrelated listener.
+     */
+    commandLine: string;
+}
+/**
+ * Result of a Marionette port probe.
+ */
+export interface MarionettePortProbeResult {
+    /** True when something is listening on the probed port. */
+    inUse: boolean;
+    /** Details about the holder, when the probe recovered them. */
+    holder?: MarionettePortHolder;
+}
+/**
+ * Probes whether the Marionette port is currently bound by a
+ * listener. The probe is best-effort: missing tooling returns
+ * `{ inUse: false }` without failing.
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ */
+export declare function probeMarionettePort(port?: number): Promise<MarionettePortProbeResult>;
+/**
+ * Raises a targeted {@link GeneralError} when the Marionette port
+ * is held by a browser process; raises a softer warning-shaped
+ * error when the holder is unrelated (so the operator still sees
+ * a useful signal but can decide whether to wait it out).
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ * @param options - Extra context for the error message (the project's
+ *   `binaryName` is used to recognise fork-branded browser binaries).
+ */
+export declare function assertMarionettePortAvailable(port?: number, options?: {
+    binaryName?: string;
+}): Promise<void>;

package/dist/src/core/marionette-port.js

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marionette port probe.
+ *
+ * Gecko's Marionette control channel binds `127.0.0.1:2828` when a
+ * Firefox / ForgeFresh / Hominis instance is launched with
+ * `-marionette`. The `fireforge test` harness spawns the browser with
+ * that flag, so any test run needs the port to be free at start.
+ *
+ * Motivating case (2026-04-21 eval, Finding #20): an interrupted
+ * `fireforge test --headless` left an orphan
+ * `ForgeFresh.app/Contents/MacOS/forgefresh -marionette` process
+ * listening on 2828 with parent PID 1. The next `fireforge test` run
+ * — in a *different* FireForge project — failed immediately with a
+ * Marionette bind error, and FireForge's generic "re-run build" hint
+ * did not mention the stale listener. The probe in this module runs
+ * before every test launch, detects when the port is held, and —
+ * when the holder is a browser process (by command-line `-marionette`
+ * flag or by basename matching a known browser binary) — throws a
+ * targeted `GeneralError` naming the PID and the exact `kill` command
+ * to run.
+ *
+ * Cross-platform implementation:
+ *   - POSIX (macOS / Linux): `lsof -i tcp:<port> -P -n -sTCP:LISTEN`
+ *   - Windows: `Get-NetTCPConnection` via PowerShell, then
+ *     `Get-Process` to resolve the PID into a command line.
+ *
+ * Both paths tolerate missing tooling: if `lsof` / PowerShell isn't
+ * installed, the probe returns `{ inUse: false }` rather than failing
+ * the test run itself — the probe is a best-effort friendliness
+ * check, not a prerequisite.
+ */
+import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { getPlatform } from '../utils/platform.js';
+import { exec } from '../utils/process.js';
+/** Default Marionette control port set by `-marionette`. */
+export const DEFAULT_MARIONETTE_PORT = 2828;
+/** Basenames of browser binaries that ship a Marionette listener. */
+const BROWSER_BASENAMES = new Set([
+    'firefox',
+    'firefox-bin',
+    'firefox-esr',
+    'forgefresh',
+    'hominis',
+    'thunderbird',
+]);
+/**
+ * Returns `true` when the holder's command basename or command-line
+ * flags clearly identify it as a Firefox-family browser with
+ * Marionette enabled. Used to decide whether to raise a targeted
+ * "stale browser on port" error vs a soft "unrelated listener"
+ * warning.
+ *
+ * Includes the operator-provided `binaryName` from `fireforge.json`
+ * so a fork that ships under a custom name (e.g. Hominis'
+ * `hominis-nightly`) is still recognised as a browser.
+ */
+function isBrowserHolder(holder, binaryName) {
+    if (/\s-marionette(?:\s|$)/.test(holder.commandLine)) {
+        return true;
+    }
+    const name = holder.command.toLowerCase();
+    if (BROWSER_BASENAMES.has(name))
+        return true;
+    if (binaryName && name === binaryName.toLowerCase())
+        return true;
+    return false;
+}
+/**
+ * Probes the given port with `lsof` (macOS / Linux). Returns
+ * `{ inUse: false }` when the port is free OR when `lsof` is not
+ * available — the probe is a best-effort courtesy check, so a
+ * missing tool must not block the test run.
+ */
+async function probeWithLsof(port) {
+    try {
+        // `-sTCP:LISTEN` filters to listeners only; `-P -n` avoids
+        // service/host lookups (faster + no DNS-dependent flakiness).
+        // `-Fpcn` emits a machine-readable format: one field per line,
+        // with `p<pid>`, `c<command>`, `n<name>` records.
+        const result = await exec('lsof', ['-i', `tcp:${port}`, '-P', '-n', '-sTCP:LISTEN', '-Fpcn']);
+        // `lsof` exits 1 when no matches — that's "port is free", not an
+        // error. We key off stdout shape instead of exit code.
+        const stdout = result.stdout;
+        const lines = stdout.split(/\r?\n/).filter((l) => l.length > 0);
+        let pid = -1;
+        let command = '';
+        for (const line of lines) {
+            if (line.startsWith('p'))
+                pid = parseInt(line.slice(1), 10);
+            else if (line.startsWith('c'))
+                command = line.slice(1);
+        }
+        if (!Number.isFinite(pid) || pid < 0 || command === '') {
+            return { inUse: false };
+        }
+        // `lsof` does not return the full command line; `ps` does. A
+        // missing `ps` (exotic Linux container) falls back to `command`
+        // alone, which is still enough to match `BROWSER_BASENAMES`.
+        let commandLine = command;
+        try {
+            const psResult = await exec('ps', ['-p', String(pid), '-o', 'args=']);
+            const psLine = psResult.stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+            if (psLine)
+                commandLine = psLine.trim();
+        }
+        catch {
+            // ps not available — keep the basename.
+        }
+        return { inUse: true, holder: { pid, command, commandLine } };
+    }
+    catch (error) {
+        // `lsof` missing, or stdout parse failed. Treat as "unknown" ⇒
+        // port probe is silently skipped.
+        const message = toError(error).message;
+        if (/ENOENT|not found|command not found/i.test(message)) {
+            return { inUse: false };
+        }
+        return { inUse: false };
+    }
+}
+/**
+ * Probes the given port with PowerShell (Windows). Uses
+ * `Get-NetTCPConnection` to find listeners, then `Get-Process -Id`
+ * to resolve the process name and command line. Gracefully degrades
+ * when PowerShell is unavailable.
+ */
+async function probeWithPowerShell(port) {
+    const script = `$c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue;` +
+        ` if ($null -eq $c) { exit 0 }` +
+        ` $p = Get-Process -Id $c[0].OwningProcess -ErrorAction SilentlyContinue;` +
+        ` if ($null -eq $p) { exit 0 }` +
+        ` $w = Get-CimInstance Win32_Process -Filter "ProcessId = $($p.Id)" -ErrorAction SilentlyContinue;` +
+        ` Write-Output ("PID=" + $p.Id);` +
+        ` Write-Output ("NAME=" + $p.ProcessName);` +
+        ` if ($w -ne $null) { Write-Output ("CMD=" + $w.CommandLine) }`;
+    try {
+        const result = await exec('powershell.exe', [
+            '-NoProfile',
+            '-NonInteractive',
+            '-Command',
+            script,
+        ]);
+        const stdout = result.stdout;
+        const pidMatch = /PID=(\d+)/.exec(stdout);
+        const nameMatch = /NAME=([^\r\n]+)/.exec(stdout);
+        if (!pidMatch || !nameMatch)
+            return { inUse: false };
+        const pid = parseInt(pidMatch[1] ?? '', 10);
+        const command = (nameMatch[1] ?? '').trim();
+        const cmdMatch = /CMD=([^\r\n]+)/.exec(stdout);
+        const commandLine = cmdMatch ? (cmdMatch[1] ?? '').trim() : command;
+        if (!Number.isFinite(pid) || command === '')
+            return { inUse: false };
+        return { inUse: true, holder: { pid, command, commandLine } };
+    }
+    catch {
+        return { inUse: false };
+    }
+}
+/**
+ * Probes whether the Marionette port is currently bound by a
+ * listener. The probe is best-effort: missing tooling returns
+ * `{ inUse: false }` without failing.
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ */
+export async function probeMarionettePort(port = DEFAULT_MARIONETTE_PORT) {
+    let platform;
+    try {
+        platform = getPlatform();
+    }
+    catch {
+        return { inUse: false };
+    }
+    if (platform === 'darwin' || platform === 'linux') {
+        return probeWithLsof(port);
+    }
+    // win32
+    return probeWithPowerShell(port);
+}
+/**
+ * Raises a targeted {@link GeneralError} when the Marionette port
+ * is held by a browser process; raises a softer warning-shaped
+ * error when the holder is unrelated (so the operator still sees
+ * a useful signal but can decide whether to wait it out).
+ *
+ * @param port - Port to probe (default {@link DEFAULT_MARIONETTE_PORT}).
+ * @param options - Extra context for the error message (the project's
+ *   `binaryName` is used to recognise fork-branded browser binaries).
+ */
+export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PORT, options = {}) {
+    const probe = await probeMarionettePort(port);
+    if (!probe.inUse || !probe.holder)
+        return;
+    const holder = probe.holder;
+    if (isBrowserHolder(holder, options.binaryName)) {
+        const killHint = process.platform === 'win32'
+            ? `Stop-Process -Id ${holder.pid} -Force`
+            : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
+        throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+            `This is usually a browser left running by a previously interrupted "fireforge test" run. ` +
+            `Kill it with "${killHint}", then retry. ` +
+            `(If you expected ${holder.command} to be running on ${port}, stop it manually or pass ` +
+            `"--marionette-port <port>" to launch mach test on a different port.)`);
+    }
+    // Non-browser holder: mach test will still fail to bind, but the
+    // cause is not a stale FireForge-launched browser. Flag it
+    // explicitly so the operator can decide what to do instead of
+    // getting mach's bind error with no FireForge context.
+    throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
+        `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`);
+}
+//# sourceMappingURL=marionette-port.js.map

package/dist/src/core/patch-manifest-consistency.d.ts

@@ -14,11 +14,31 @@ export interface PatchManifestConsistencyIssue {
  * @returns Consistency issues between manifest metadata and on-disk patch files
  */
 export declare function validatePatchesManifestConsistency(patchesDir: string): Promise<PatchManifestConsistencyIssue[]>;
+/**
+ * Summary of a {@link rebuildPatchesManifest} run. `recoveredFilenames`
+ * lists patches whose manifest entry was reconstructed from filename,
+ * mtime, and diff alone (no pre-existing manifest entry to preserve).
+ * These entries carry generic descriptions and mtime-based
+ * timestamps; callers like `doctor --repair-patches-manifest` surface
+ * a per-patch review warning so operators know which metadata was
+ * invented vs which was restored.
+ */
+export interface RebuildPatchesManifestResult {
+    /** Rebuilt manifest, ready to be re-applied by callers (already persisted). */
+    manifest: PatchesManifest;
+    /**
+     * Filenames whose manifest entry had no pre-existing metadata to
+     * preserve — every descriptive field on these entries is inferred.
+     */
+    recoveredFilenames: string[];
+}
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
  * Existing metadata is preserved when possible; missing entries are recovered
  * from filename structure, patch contents, and file mtimes.
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
+ *   plus the filenames that were reconstructed from generic defaults.
  */
-export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<PatchesManifest>;
+export declare function rebuildPatchesManifest(patchesDir: string, fallbackSourceEsrVersion: string): Promise<RebuildPatchesManifestResult>;

package/dist/src/core/patch-manifest-consistency.js

@@ -85,6 +85,8 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  * from filename structure, patch contents, and file mtimes.
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - ESR version to use for recovered entries
+ * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
+ *   plus the filenames that were reconstructed from generic defaults.
  */
 export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
@@ -96,6 +98,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
     }
     const patches = await discoverPatches(patchesDir);
     const rebuiltPatches = [];
+    const recoveredFilenames = [];
     const highestFiniteOrder = patches.reduce((highest, patch) => {
         return Number.isFinite(patch.order) ? Math.max(highest, patch.order) : highest;
     }, 0);
@@ -106,6 +109,18 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
         const patchStats = await stat(patch.path);
         const inferred = inferPatchMetadataFromFilename(patch.filename);
         const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
+        if (!existing) {
+            // Track every filename that had no pre-existing manifest entry
+            // so callers can warn the operator per-patch. A missing entry
+            // means every descriptive field (`description`, `createdAt`,
+            // `category`) was invented rather than preserved. FireForge
+            // patch files carry no header metadata that could carry a
+            // human description forward, so full fidelity is impossible —
+            // visibility is the best we can offer. 2026-04-21 eval
+            // (Finding #17) tripped over silent overwrites of useful
+            // human-written descriptions during a recovery run.
+            recoveredFilenames.push(patch.filename);
+        }
         rebuiltPatches.push({
             filename: patch.filename,
             order: recoveredOrder,
@@ -124,7 +139,7 @@ export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersio
         patches: rebuiltPatches,
     };
     await savePatchesManifest(patchesDir, rebuiltManifest);
-    return rebuiltManifest;
+    return { manifest: rebuiltManifest, recoveredFilenames };
 }
 function normalizeFiles(files) {
     return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));

package/dist/src/core/status-classify.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Status classifier: partitions engine file changes into
+ * patch-backed / unmanaged / branding / furnace / conflict buckets.
+ *
+ * Extracted from `src/commands/status.ts` so that command file stays
+ * under the per-file line budget as the number of buckets grows.
+ */
+/**
+ * Classification buckets for engine file changes:
+ * - `patch-backed`: content matches the expected post-patch state —
+ *   normal after `fireforge import`.
+ * - `unmanaged`: edits not explained by any patch or tool — local
+ *   drift to export or discard.
+ * - `branding`: files under tool-managed branding paths, written by
+ *   FireForge's branding pipeline.
+ * - `furnace`: files under Furnace-managed component prefixes.
+ * - `conflict`: the file is claimed by two or more patches in
+ *   `patches.json`. The human `--ownership` mode already surfaces
+ *   this bucket as `CONFLICT`; the classification is carried through
+ *   the JSON pipeline so machine consumers can detect the same
+ *   ownership breakage the human output shows. Before 0.16.0,
+ *   cross-patch conflicts silently rolled into the `unmanaged` bucket
+ *   in `--json`, which misled scripts built on top of the JSON view
+ *   into treating the file as routine local drift.
+ */
+export type FileClassification = 'patch-backed' | 'unmanaged' | 'branding' | 'furnace' | 'conflict';
+export interface StatusFile {
+    status: string;
+    file: string;
+}
+export interface ClassifiedFile extends StatusFile {
+    classification: FileClassification;
+    /**
+     * Names of patch files that claim this path in `patches.json`.
+     * Populated only when `classification === 'conflict'` — single-claim
+     * patch-backed entries don't need to expose their owner because the
+     * single claim is fully captured by the classification itself.
+     */
+    claimedBy?: string[];
+}
+/**
+ * Classifies files into patch-backed, unmanaged, branding, furnace, or
+ * conflict buckets.
+ *
+ * Tracks patch ownership as a `Map<file, patchFilename[]>` rather than
+ * a plain `Set<file>` so the classifier can surface cross-patch
+ * ownership conflicts the same way the human `--ownership` mode does.
+ * The 2026-04-21 eval's `status --json` run reported
+ * `classification: "unmanaged"` on two files (`browser/base/jar.mn`,
+ * `browser/themes/shared/jar.inc.mn`) that `--ownership` correctly
+ * flagged as `CONFLICT`; the JSON output was effectively lying to
+ * machine consumers about the nature of the drift.
+ */
+export declare function classifyFiles(files: StatusFile[], engineDir: string, patchesDir: string, binaryName: string, furnacePrefixes: Set<string>): Promise<ClassifiedFile[]>;