@hominis/fireforge 0.15.1 → 0.15.3

package/dist/src/core/furnace-validate-helpers.js

@@ -148,28 +148,88 @@ function isWithinLocalizedElement(content, matchIndex) {
     const tagContent = contentBefore.slice(lastTagOpen, matchIndex + 1);
     return /data-l10n-id\s*=/.test(tagContent);
 }
-/** Detects hardcoded user-visible template text that should usually be localized. */
+/**
+ * Detects hardcoded user-visible template text that should usually be
+ * localized.
+ *
+ * Scoped to three positive contexts rather than scanning the whole file,
+ * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
+ * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
+ * identifier literals that are never shown to a user. Only matches that
+ * actually enter a UI render path count:
+ *
+ *   1. Content inside a Lit `` html`…` `` tagged template literal.
+ *   2. The string literal on the RHS of `.textContent = "…"` or
+ *      `.innerHTML = "…"`.
+ *   3. The string literal assigned to an XUL-widget `label=`,
+ *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
+ *
+ * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
+ * findings (matches the pre-existing escape hatch).
+ */
 export function containsHardcodedTemplateText(content) {
     if (/furnace-ignore:\s*hardcoded-text/.test(content)) {
         return false;
     }
-    const textPattern = />([^<$\s][^<$]*)</g;
-    let textMatch;
-    while ((textMatch = textPattern.exec(content)) !== null) {
-        const text = textMatch[1]?.trim() ?? '';
-        if (/\$\{/.test(text)) {
-            continue;
-        }
-        if (Array.from(text).length <= 1) {
-            continue;
-        }
-        if (isSymbolOnlyText(text)) {
-            continue;
-        }
-        if (isWithinLocalizedElement(content, textMatch.index)) {
-            continue;
+    return (hasFlaggedTextInLitTemplates(content) ||
+        hasFlaggedTextInDomAssignment(content) ||
+        hasFlaggedTextInXulAttribute(content));
+}
+function isFlaggableText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    if (/\$\{/.test(trimmed))
+        return false;
+    if (Array.from(trimmed).length <= 1)
+        return false;
+    if (isSymbolOnlyText(trimmed))
+        return false;
+    return true;
+}
+function hasFlaggedTextInLitTemplates(content) {
+    // Match `html\`…\`` regions, anchored on a non-identifier char before `html`
+    // so substrings like `otherhtml` do not spuriously open a template.
+    const htmlPattern = /(?:^|[^a-zA-Z0-9_$])html`([\s\S]*?)`/g;
+    let litMatch;
+    while ((litMatch = htmlPattern.exec(content)) !== null) {
+        const region = litMatch[1] ?? '';
+        const textPattern = />([^<$\s][^<$]*)</g;
+        let textMatch;
+        while ((textMatch = textPattern.exec(region)) !== null) {
+            const text = textMatch[1] ?? '';
+            if (!isFlaggableText(text))
+                continue;
+            if (isWithinLocalizedElement(region, textMatch.index))
+                continue;
+            return true;
         }
-        return true;
+    }
+    return false;
+}
+function hasFlaggedTextInDomAssignment(content) {
+    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"` — these are
+    // user-visible render paths. Template-literal RHS is excluded (usually
+    // dynamic), matching the `${` guard used elsewhere in this helper.
+    const assignPattern = /\.(?:textContent|innerHTML)\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let match;
+    while ((match = assignPattern.exec(content)) !== null) {
+        const text = match[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
+    }
+    return false;
+}
+function hasFlaggedTextInXulAttribute(content) {
+    // Assignments like `node.setAttribute("label", "Save")` or JS-built XUL
+    // attributes `label="…"` / `title="…"` / `tooltiptext="…"` in template
+    // literals outside Lit blocks. Covers DOM built via createXULElement.
+    const setAttrPattern = /setAttribute\s*\(\s*["'](?:label|title|tooltiptext)["']\s*,\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let setAttrMatch;
+    while ((setAttrMatch = setAttrPattern.exec(content)) !== null) {
+        const text = setAttrMatch[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
     }
     return false;
 }
@@ -214,6 +274,27 @@ export function collectCssVariableReferences(cssContent) {
     }
     return referencedVariables;
 }
+/**
+ * Collects CSS custom property *declarations* — names appearing on the
+ * left-hand side of a `--name:` declaration. Used to auto-exempt
+ * component-local runtime variables from the token-prefix check: if the
+ * component both declares and consumes a variable in its own CSS file, it
+ * is a local runtime channel, not a design-token reference.
+ *
+ * The anchor `(?:^|[{;,\s])` rules out `var(--name)` occurrences (which are
+ * always preceded by `(`), so references are not mistaken for declarations.
+ */
+export function collectCssVariableDeclarations(cssContent) {
+    const declared = new Set();
+    const pattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+    let match;
+    while ((match = pattern.exec(cssContent)) !== null) {
+        const name = match[1];
+        if (name)
+            declared.add(name);
+    }
+    return declared;
+}
 async function collectInheritedOverrideVariables(tagName, config, root) {
     const inheritedVariables = new Set();
     const basePath = config.overrides[tagName]?.basePath;
@@ -234,12 +315,14 @@ async function collectInheritedOverrideVariables(tagName, config, root) {
 /** Builds token-validation context from the config allowlist and inherited override CSS. */
 export async function getTokenPrefixContext(tagName, type, config, root) {
     const allowlist = new Set(config.tokenAllowlist ?? []);
+    const runtimeVariables = new Set(config.runtimeVariables ?? []);
     if (type !== 'override' || !root) {
-        return { allowlist, inheritedOverrideVars: new Set() };
+        return { allowlist, inheritedOverrideVars: new Set(), runtimeVariables };
     }
     return {
         allowlist,
         inheritedOverrideVars: await collectInheritedOverrideVariables(tagName, config, root),
+        runtimeVariables,
     };
 }
 //# sourceMappingURL=furnace-validate-helpers.js.map

package/dist/src/core/furnace-validate-registration.d.ts

@@ -35,7 +35,7 @@ export declare function validateJarMnEntries(root: string, config: FurnaceConfig
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
  * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
  * furnace.json; the warning fires only when NONE of the configured
  * documents link the tokens CSS.

package/dist/src/core/furnace-validate-registration.js

@@ -216,7 +216,7 @@ const DEFAULT_TOKEN_HOST_DOCUMENTS = ['browser/base/content/browser.xhtml'];
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
  * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
  * furnace.json; the warning fires only when NONE of the configured
  * documents link the tokens CSS.

package/dist/src/core/mach-error-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/** A single translator entry. */
+export interface MachErrorHint {
+    /** Pattern to search within the captured mach stderr. */
+    pattern: RegExp;
+    /** Actionable, one-line hint to surface alongside the raw mach output. */
+    hint: string;
+}
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export declare const MACH_ERROR_HINTS: MachErrorHint[];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export declare function explainMachError(stderr: string): string[];

package/dist/src/core/mach-error-hints.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export const MACH_ERROR_HINTS = [
+    {
+        pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
+        hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
+            'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
+    },
+];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export function explainMachError(stderr) {
+    if (!stderr) {
+        return [];
+    }
+    const hits = [];
+    const seen = new Set();
+    for (const { pattern, hint } of MACH_ERROR_HINTS) {
+        if (pattern.test(stderr) && !seen.has(hint)) {
+            seen.add(hint);
+            hits.push(hint);
+        }
+    }
+    return hits;
+}
+//# sourceMappingURL=mach-error-hints.js.map

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

@@ -57,14 +57,17 @@ export declare function bootstrap(engineDir: string): Promise<number>;
  */
 export declare function bootstrapWithOutput(engineDir: string): Promise<MachCommandResult>;
 /**
- * Runs a full mach build.
+ * Runs a full mach build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output so operators get an actionable
+ * nudge alongside the cryptic mozbuild traceback.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
  * @returns Exit code
  */
 export declare function build(engineDir: string, jobs?: number): Promise<number>;
 /**
- * Runs a fast UI-only build.
+ * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output.
  * @param engineDir - Path to the engine directory
  * @returns Exit code
  */

package/dist/src/core/mach.js

@@ -2,7 +2,9 @@
 import { 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, execStream } from '../utils/process.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.
 export { buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
@@ -109,7 +111,23 @@ export async function bootstrapWithOutput(engineDir) {
     return runMachInheritCapture(['bootstrap', '--application-choice', 'browser'], engineDir);
 }
 /**
- * Runs a full mach build.
+ * Prints any matched {@link MachErrorHint} hints for the captured stderr.
+ * No-op when nothing matches. Always called before a non-zero exit propagates
+ * so the hint sits immediately below the raw mach error in the operator's
+ * terminal.
+ */
+function surfaceMachErrorHints(stderr) {
+    const hints = explainMachError(stderr);
+    if (hints.length === 0)
+        return;
+    for (const hint of hints) {
+        warn(`Hint: ${hint}`);
+    }
+}
+/**
+ * Runs a full mach build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output so operators get an actionable
+ * nudge alongside the cryptic mozbuild traceback.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
  * @returns Exit code
@@ -119,15 +137,24 @@ export async function build(engineDir, jobs) {
     if (jobs !== undefined) {
         args.push('-j', String(jobs));
     }
-    return runMach(args, engineDir, { inherit: true });
+    const result = await runMachInheritCapture(args, engineDir);
+    if (result.exitCode !== 0) {
+        surfaceMachErrorHints(result.stderr);
+    }
+    return result.exitCode;
 }
 /**
- * Runs a fast UI-only build.
+ * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output.
  * @param engineDir - Path to the engine directory
  * @returns Exit code
  */
 export async function buildUI(engineDir) {
-    return runMach(['build', 'faster'], engineDir, { inherit: true });
+    const result = await runMachInheritCapture(['build', 'faster'], engineDir);
+    if (result.exitCode !== 0) {
+        surfaceMachErrorHints(result.stderr);
+    }
+    return result.exitCode;
 }
 /**
  * Runs the built browser.

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

@@ -6,18 +6,17 @@
  * to discover"; this helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
- * The probe is intentionally narrow — it does not replace mach test or try
- * to execute anything via marionette. It spawns `mach run --marionette
- * --headless` (plus a throwaway profile) and waits for the marionette server
- * to accept a TCP connection on the conventional port. Any byte read from
- * the socket proves a handshake payload is being produced.
+ * The probe is a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
  */
 import { spawn } from 'node:child_process';
 import net from 'node:net';
 export interface MarionettePreflightResult {
     ok: boolean;
     durationMs: number;
-    /** Human-readable summary. */
+    /** Human-readable summary. On FAIL, prefixed with `[layer N/6: <name>]`. */
     detail: string;
 }
 export interface MarionettePreflightOptions {
@@ -25,13 +24,21 @@ export interface MarionettePreflightOptions {
     timeoutMs?: number;
     /** Overrides marionette TCP port — primarily used in tests. */
     port?: number;
+    /**
+     * Grace window after spawn() before the browser is considered "running
+     * OK." Catches immediate crashes (missing dylib, wrong CPU arch, corrupt
+     * profile) at the spawn layer rather than the handshake layer. Default:
+     * {@link SPAWN_SETTLE_MS}. Tests may set this to 0 to skip the settle.
+     */
+    spawnSettleMs?: number;
     /** Test seam: spawn and socket connect factories. */
     spawner?: typeof spawn;
     connect?: typeof net.createConnection;
 }
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * marionette socket within the budget; FAIL otherwise, with a diagnostic
+ * identifying which layer of the cascade broke. Always tears down the
  * spawned browser before returning.
  */
 export declare function runMarionettePreflight(engineDir: string, options?: MarionettePreflightOptions): Promise<MarionettePreflightResult>;

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

@@ -7,11 +7,10 @@
  * to discover"; this helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
- * The probe is intentionally narrow — it does not replace mach test or try
- * to execute anything via marionette. It spawns `mach run --marionette
- * --headless` (plus a throwaway profile) and waits for the marionette server
- * to accept a TCP connection on the conventional port. Any byte read from
- * the socket proves a handshake payload is being produced.
+ * The probe is a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
  */
 import { spawn } from 'node:child_process';
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -28,60 +27,112 @@ const MARIONETTE_PORT = 2828;
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
 /** Per-attempt socket connect timeout. Polling continues until the overall budget expires. */
 const SOCKET_ATTEMPT_TIMEOUT_MS = 2_000;
+/**
+ * Grace window after spawn() returns before we accept the child as
+ * "spawned OK". A browser binary that exits immediately (missing dylib,
+ * wrong CPU arch, corrupt profile) must be caught here — not 30 seconds
+ * later at the socket layer.
+ */
+const SPAWN_SETTLE_MS = 750;
 /** Tail of stderr preserved for FAIL diagnostics. */
 const STDERR_TAIL_LIMIT = 8 * 1024;
+/**
+ * Layer names, ordered by the probe sequence. Surfaced in `detail` so the
+ * operator sees which layer failed without having to guess.
+ */
+const LAYER_NAMES = [
+    'engine-present',
+    'mach-available',
+    'python-available',
+    'profile-creatable',
+    'browser-spawns',
+    'marionette-handshake',
+];
+function layerTag(name) {
+    const index = LAYER_NAMES.indexOf(name) + 1;
+    return `[layer ${index}/${LAYER_NAMES.length}: ${name}]`;
+}
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * marionette socket within the budget; FAIL otherwise, with a diagnostic
+ * identifying which layer of the cascade broke. Always tears down the
  * spawned browser before returning.
  */
 export async function runMarionettePreflight(engineDir, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+    const spawnSettleMs = options.spawnSettleMs ?? SPAWN_SETTLE_MS;
     const port = options.port ?? MARIONETTE_PORT;
     const spawnerFn = options.spawner ?? spawn;
     const connectFn = options.connect ?? net.createConnection;
     const startedAt = Date.now();
     const elapsed = () => Date.now() - startedAt;
+    // Layer 1: engine directory exists.
     if (!(await pathExists(engineDir))) {
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: 'Engine directory not found — run "fireforge download" first.',
-        };
+        return fail('engine-present', 'Engine directory not found — run "fireforge download" first.', elapsed());
     }
+    // Layer 2: mach binary resolves in the engine.
     try {
         await ensureMach(engineDir);
     }
     catch (error) {
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: `mach not available in engine: ${error.message}`,
-        };
+        return fail('mach-available', `mach not available in engine: ${error.message}`, elapsed());
+    }
+    // Layer 3: Python that mach requires is discoverable.
+    let python;
+    try {
+        python = await getPython(engineDir);
+    }
+    catch (error) {
+        return fail('python-available', `Python interpreter required by mach is not available: ${error.message}`, elapsed());
+    }
+    // Layer 4: throwaway browser profile directory is creatable.
+    let profileDir;
+    try {
+        profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
+    }
+    catch (error) {
+        return fail('profile-creatable', `Could not create a throwaway browser profile in ${tmpdir()}: ${error.message}`, elapsed());
     }
-    const python = await getPython(engineDir);
-    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
     let child;
     let stderrTail = '';
     try {
-        child = spawnerFn(python, [
-            join(engineDir, 'mach'),
-            'run',
-            '--marionette',
-            '--headless',
-            '--no-remote',
-            '-profile',
-            profileDir,
-        ], {
-            cwd: engineDir,
-            env: { ...process.env, MOZ_HEADLESS: '1' },
-            stdio: ['ignore', 'ignore', 'pipe'],
-        });
+        // Layer 5: browser spawns and does not crash within the settle window.
+        try {
+            child = spawnerFn(python, [
+                join(engineDir, 'mach'),
+                'run',
+                '--marionette',
+                '--headless',
+                '--no-remote',
+                '-profile',
+                profileDir,
+            ], {
+                cwd: engineDir,
+                env: { ...process.env, MOZ_HEADLESS: '1' },
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+        }
+        catch (error) {
+            return fail('browser-spawns', `Could not spawn mach run: ${error.message}`, elapsed());
+        }
+        const spawnedChild = child;
         child.stderr?.on('data', (data) => {
             const chunk = data.toString();
             stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
         });
-        const spawnedChild = child;
+        // Short settle window — catches "binary exits immediately" failures
+        // (missing dylib, wrong CPU arch, corrupt profile) before the socket
+        // poll swallows the full overall budget waiting for bytes that will
+        // never come.
+        const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
+        if (settleDeadline > 0) {
+            await delay(settleDeadline);
+        }
+        if (hasChildExited(spawnedChild)) {
+            return fail('browser-spawns', `Browser process exited during spawn (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
+        }
+        // Layer 6: marionette handshake within the remaining budget.
         const socketResult = await waitForMarionetteSocket(port, connectFn, () => {
             return elapsed() < timeoutMs && !hasChildExited(spawnedChild);
         });
@@ -95,19 +146,11 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // Child may have exited before the socket was ever ready — surface that
         // distinctly from "socket never answered" so the operator has a lead.
         if (hasChildExited(spawnedChild)) {
-            return {
-                ok: false,
-                durationMs: elapsed(),
-                detail: `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
-                    `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
-            };
+            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
-                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
-        };
+        return fail('marionette-handshake', `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
+            `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
     }
     finally {
         if (child && !hasChildExited(child)) {
@@ -137,6 +180,13 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         }
     }
 }
+function fail(layer, message, durationMs) {
+    return {
+        ok: false,
+        durationMs,
+        detail: `${layerTag(layer)} ${message}`,
+    };
+}
 /** Returns true when the child process has exited (normal or signaled). */
 function hasChildExited(child) {
     return child.exitCode !== null || child.signalCode !== null;

package/dist/src/core/patch-lint-cross.d.ts

@@ -91,7 +91,7 @@ export declare function collectNewFileCreatorsByPath(ctx: PatchQueueContext): Ma
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint-cross.js

@@ -114,7 +114,7 @@ export function collectNewFileCreatorsByPath(ctx) {
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint-diff-tag.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Diff-scoping for `fireforge lint`.
+ *
+ * Pre-existing patch-state errors and errors introduced by the current task
+ * print identically today, so triaging "is the diff I just produced clean?"
+ * requires mentally subtracting the pre-existing noise. This module
+ * classifies each lint issue as either `introduced` (the file was touched
+ * since the user-supplied git revision) or `cumulative` (pre-existing
+ * drift), without changing what the underlying rules emit.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Collects engine-relative paths that changed between `rev` and `HEAD`,
+ * plus any workdir modifications and untracked files. An empty set means
+ * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * in that case (operator ran `lint --since HEAD` with no pending work).
+ * @param engineDir Path to the engine git repository.
+ * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
+ */
+export declare function collectDiffFilePaths(engineDir: string, rev: string): Promise<Set<string>>;
+/**
+ * Annotates a list of lint issues with `introduced` / `cumulative` tags
+ * based on whether the issue's file is part of the supplied diff set.
+ * Mutates each issue in place AND returns the list for chaining.
+ *
+ * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
+ * describe queue-wide state — are always `cumulative` under `--since`
+ * because they describe drift accumulated across many commits, not a
+ * single current-task edit.
+ * @param issues Issues returned by the lint orchestrator.
+ * @param diffFiles File paths touched since the user's revision.
+ */
+export declare function tagLintIssues(issues: PatchLintIssue[], diffFiles: Set<string>): PatchLintIssue[];