@hominis/fireforge 0.40.0 → 0.41.0

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

@@ -10,7 +10,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
 import { validateRegistrationPlacement, validateTagName } from './furnace-registration-validate.js';
 /**
@@ -62,7 +62,7 @@ function isInsideDOMContentLoaded(ancestors, content) {
         const ancestor = ancestors[i];
         if (!ancestor || ancestor.type !== 'CallExpression')
             continue;
-        const call = ancestor;
+        const call = asEstree(ancestor);
         if (call.callee.type === 'MemberExpression' &&
             call.callee.object.type === 'Identifier' &&
             call.callee.object.name === 'document' &&
@@ -87,18 +87,18 @@ function collectArrayDeclarations(ast) {
         enter(node) {
             if (node.type !== 'VariableDeclarator')
                 return;
-            const declarator = node;
+            const declarator = asEstree(node);
             if (declarator.id.type !== 'Identifier' || declarator.init?.type !== 'ArrayExpression') {
                 return;
             }
-            arrays.set(declarator.id.name, declarator.init);
+            arrays.set(declarator.id.name, asEstree(declarator.init));
         },
     });
     return arrays;
 }
 function resolveForOfArray(right, declaredArrays) {
     if (right.type === 'ArrayExpression') {
-        return right;
+        return asEstree(right);
     }
     if (right.type === 'Identifier') {
         return declaredArrays.get(right.name);
@@ -148,7 +148,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
         enter(node) {
             ancestors.push(node);
             if (node.type === 'ForOfStatement') {
-                const forOf = node;
+                const forOf = asEstree(node);
                 const array = resolveForOfArray(forOf.right, declaredArrays);
                 if (array) {
                     forOfs.push({
@@ -170,7 +170,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
     for (const el of array.elements) {
         if (!el || el.type !== 'ArrayExpression')
             continue;
-        const entryArr = el;
+        const entryArr = asEstree(el);
         const firstEl = entryArr.elements[0];
         if (!firstEl || firstEl.type !== 'Literal')
             continue;
@@ -181,7 +181,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
         const indent = detectIndent(content, entryArr.start);
         let innerIndent;
         if (isMultiLine) {
-            const firstElNode = firstEl;
+            const firstElNode = asEstree(firstEl);
             innerIndent = detectIndent(content, firstElNode.start);
         }
         entries.push({ tag, node: entryArr, isMultiLine, indent, innerIndent });

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

@@ -25,7 +25,7 @@
 import { join } from 'node:path';
 import MagicString from 'magic-string';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { parseScript, walkAST } from './ast-utils.js';
+import { asEstree, parseScript, walkAST } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
 /**
  * Expands `[start, end)` to consume a trailing comma and any whitespace up
@@ -147,7 +147,7 @@ function collectRemovalRanges(ast, content, tagName) {
             }
             // Standalone call: customElements.setElementCreationCallback(tag, …)
             if (node.type === 'CallExpression') {
-                const call = node;
+                const call = asEstree(node);
                 if (isStandaloneCallbackCallFor(call, tagName)) {
                     // Find the enclosing statement so we can delete `call(...);` as
                     // a unit, not just the call expression body.
@@ -158,7 +158,7 @@ function collectRemovalRanges(ast, content, tagName) {
                             continue;
                         if (ancestor.type === 'ExpressionStatement' ||
                             ancestor.type === 'VariableDeclaration') {
-                            enclosing = ancestor;
+                            enclosing = asEstree(ancestor);
                             break;
                         }
                     }
@@ -203,6 +203,9 @@ export async function removeCustomElementRegistration(engineDir, tagName) {
         ast = parseScript(content);
     }
     catch {
+        // An unparsable customElements.js is left untouched on purpose: this
+        // function only removes registrations, and editing a file it cannot parse
+        // risks corrupting it. The caller's regex fallback handles the retry.
         return;
     }
     const ranges = collectRemovalRanges(ast, content, tagName);

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

@@ -2,10 +2,6 @@
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-/** Escapes special regex characters in a literal string. */
-function escapeForRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Detects the indentation used by existing `content/global/elements/` lines
  * in jar.mn. Falls back to 3 spaces (the historical Firefox convention) when
@@ -22,6 +18,7 @@ function detectJarMnIndent(lines) {
 }
 // Re-export everything from the AST module so existing imports keep working
 export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+import { escapeRegex } from '../utils/regex.js';
 import { JAR_MN } from './furnace-constants.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
@@ -66,7 +63,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     const lines = content.split('\n');
     // Filter to files not already registered. Use a word-boundary-aware
     // check so that "moz-card.css" does not match "moz-card-group.css".
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
         return 0;
     // Build new entry lines using the indent detected from existing entries.
@@ -141,8 +138,8 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
     const content = await readText(filePath);
     const lines = content.split('\n');
     const ftlFile = `${tagName}.ftl`;
-    const escapedTag = escapeForRegex(tagName);
-    const escapedChrome = escapeForRegex(chromeSubPath);
+    const escapedTag = escapeRegex(tagName);
+    const escapedChrome = escapeRegex(chromeSubPath);
     const presencePattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/${escapedTag}\\.ftl`, 'm');
     if (presencePattern.test(content)) {
         return 0;
@@ -176,7 +173,7 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
 }
 /** Detects locale jar.mn indentation by sampling an existing matching entry. */
 function detectLocaleJarMnIndent(lines, chromeSubPath) {
-    const escapedChrome = escapeForRegex(chromeSubPath);
+    const escapedChrome = escapeRegex(chromeSubPath);
     const pattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/`);
     for (const line of lines) {
         const match = pattern.exec(line);
@@ -202,7 +199,7 @@ export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeForRegex(chromeSubPath)}\\/${escapeForRegex(tagName)}\\.ftl`);
+    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`);
     const filtered = lines.filter((line) => !pattern.test(line));
     if (filtered.length === lines.length)
         return;
@@ -232,8 +229,8 @@ export async function removeJarMnEntries(engineDir, tagName) {
     // report). The legacy target-path match is kept as an OR for lines
     // written by older FireForge versions without a source mapping. Word
     // boundaries keep "moz-card" from matching "moz-card-group".
-    const sourcePattern = new RegExp(`\\(widgets/${escapeForRegex(tagName)}/`);
-    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
+    const sourcePattern = new RegExp(`\\(widgets/${escapeRegex(tagName)}/`);
+    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeRegex(tagName)}\\.`);
     const filtered = lines.filter((line) => !sourcePattern.test(line) && !legacyTargetPattern.test(line));
     if (filtered.length === lines.length)
         return;
@@ -296,7 +293,7 @@ export async function validateJarMnInsertionForFiles(engineDir, tagName, files)
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
         return;
     const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;

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

@@ -108,7 +108,7 @@ export async function restoreRollbackJournal(journal) {
             catch (error) {
                 errors.push({
                     path: filePath,
-                    error: error instanceof Error ? error.message : String(error),
+                    error: toError(error).message,
                 });
             }
         }

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

@@ -2,6 +2,7 @@
 import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { asEstree, getNodeSource, parseScript, walkAST } from './ast-utils.js';
@@ -116,7 +117,7 @@ export async function scanCustomElementsRegistrations(engineDir) {
         // Best-effort scanner: if upstream syntax changes or the file is damaged,
         // fall back to the old literal callback heuristic instead of failing the
         // whole scan command.
-        const reason = parseError instanceof Error ? parseError.message : String(parseError);
+        const reason = toError(parseError).message;
         warn(`AST parsing of customElements.js failed (${reason}). Falling back to regex-based heuristic. ` +
             'Results may be incomplete — run "fireforge furnace validate" to verify registration consistency.');
         verbose(`Scanner regex fallback activated due to parse error: ${reason}`);

package/dist/src/core/furnace-stale-export.js

@@ -20,6 +20,7 @@
  * block non-furnace patch work.
  */
 import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
@@ -89,7 +90,7 @@ export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
         return stale;
     }
     catch (error) {
-        verbose(`Stale-furnace export gate skipped due to an error: ${error instanceof Error ? error.message : String(error)}`);
+        verbose(`Stale-furnace export gate skipped due to an error: ${toError(error).message}`);
         return [];
     }
 }

package/dist/src/core/furnace-state-persist.d.ts

@@ -21,14 +21,13 @@
  * <name>` had exactly this bug while `furnace deploy <name>` documented
  * and avoided it).
  */
-import { type applyAllComponents } from './furnace-apply.js';
+import { type ApplyAllComponentsResult } from './furnace-apply.js';
 import { type getFurnacePaths } from './furnace-config.js';
-type ApplyAllResult = Awaited<ReturnType<typeof applyAllComponents>>;
 /**
  * Counts applied entries that carry at least one BLOCKING step error
  * (advisory step errors are warnings and never fail a run).
  */
-export declare function getStepFailureCount(result: ApplyAllResult): number;
+export declare function getStepFailureCount(result: ApplyAllComponentsResult): number;
 /**
  * Decides whether a single-component apply/deploy completed cleanly enough
  * to persist its checksums into furnace-state.json.
@@ -40,7 +39,7 @@ export declare function getStepFailureCount(result: ApplyAllResult): number;
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
-export declare function shouldPersistSingleComponentState(result: ApplyAllResult, isDryRun: boolean): boolean;
+export declare function shouldPersistSingleComponentState(result: ApplyAllComponentsResult, isDryRun: boolean): boolean;
 /**
  * Validates and narrows the applied entry a named run should persist.
  *
@@ -52,7 +51,7 @@ export declare function shouldPersistSingleComponentState(result: ApplyAllResult
  *
  * @param commandLabel - Human label for error messages ("Deploy", "Apply")
  */
-export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllResult['applied'][number] | undefined): {
+export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllComponentsResult['applied'][number] | undefined): {
     name: string;
     type: 'override' | 'custom';
 };
@@ -69,4 +68,3 @@ export declare function persistSingleComponentState(projectRoot: string, applied
     name: string;
     type: 'override' | 'custom';
 }, furnacePaths: ReturnType<typeof getFurnacePaths>): Promise<void>;
-export {};

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { hasRawCssColors } from '../utils/regex.js';
+import { escapeRegex, hasRawCssColors } from '../utils/regex.js';
 import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
 async function validateMjsCompatibility(mjsPath, tagName, isLibrary) {
     if (!(await pathExists(mjsPath)))
@@ -78,22 +78,19 @@ async function validateCssCompatibility(cssPath, tagName, type, config, root) {
  */
 function isReferencedAsElement(source, tagName) {
     // Match as an HTML element: <tagName or </tagName
-    const htmlPattern = new RegExp(`</?${escapeForValidation(tagName)}[\\s/>]`);
+    const htmlPattern = new RegExp(`</?${escapeRegex(tagName)}[\\s/>]`);
     if (htmlPattern.test(source))
         return true;
     // Match as a CSS tag selector: standalone word at start of line or after combinators
-    const cssPattern = new RegExp(`(?:^|[\\s,>+~])${escapeForValidation(tagName)}(?:[\\s,{:>+~.[#]|$)`, 'm');
+    const cssPattern = new RegExp(`(?:^|[\\s,>+~])${escapeRegex(tagName)}(?:[\\s,{:>+~.[#]|$)`, 'm');
     if (cssPattern.test(source))
         return true;
     // Also accept querySelector/querySelectorAll('tagName') as intentional usage
-    const querySelectorPattern = new RegExp(`querySelector(?:All)?\\(\\s*["'\`]${escapeForValidation(tagName)}(?:[\\s"'\`.,>+~:[#])`);
+    const querySelectorPattern = new RegExp(`querySelector(?:All)?\\(\\s*["'\`]${escapeRegex(tagName)}(?:[\\s"'\`.,>+~:[#])`);
     if (querySelectorPattern.test(source))
         return true;
     return false;
 }
-function escapeForValidation(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Validates that composed tags declared in furnace.json are actually referenced
  * in the component's source (.mjs and .css) in an HTML template or CSS context.

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

@@ -180,10 +180,42 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
     }
     return !NATIVE_CLICK_INTERACTIVE_TAGS.has(tagName);
 }
+/** ASCII punctuation that reads as decoration rather than localizable text. */
+const SYMBOL_ONLY_ASCII = '+-*=<>|/\\^~@#&!?%';
+/**
+ * Reports whether `text` is decoration (arrows, maths, emoji, bare
+ * punctuation) rather than user-facing prose that needs localizing.
+ *
+ * The letter/number/mark test comes first and is script-agnostic. Until
+ * 0.41.0 the only non-ASCII rule was `code > 0xff`, which classified *every*
+ * code point above U+00FF as a symbol — so all CJK, Cyrillic, Greek, Arabic,
+ * Hebrew, Devanagari and Thai text was exempted from a **localization**
+ * validator, i.e. the rule was blind to precisely the strings most likely to
+ * need translating.
+ *
+ * Combining marks are deliberately NOT counted as text: the check is an
+ * `every()`, so a script's base letters already disqualify the string, and
+ * treating marks as text would flag emoji carrying a variation selector
+ * (U+FE0F is category Mn — `⚙️` is U+2699 + U+FE0F).
+ *
+ * High code points that are not letters — emoji, arrows, CJK punctuation —
+ * stay exempt, which is the rule's original intent.
+ *
+ * A handful of emoji are ALSO Unicode letters, and the letter test alone gets
+ * them wrong. U+2139 (`ℹ`, the base of the very common `ℹ️`) is category Ll, so
+ * the `\p{L}` branch classified an info badge as prose needing localization.
+ * Non-ASCII code points carrying `Emoji` are therefore read as symbols before
+ * the letter test. The ASCII guard matters: `\p{Emoji}` also covers the digits
+ * `0`-`9`, `#` and `*`, which must keep their existing classification.
+ */
 function isSymbolOnlyText(text) {
     return Array.from(text).every((character) => {
         const code = character.codePointAt(0) ?? 0;
-        return code > 0xff || '+-*=<>|/\\^~@#&!?%'.includes(character);
+        if (code > 0x7f && /\p{Emoji}/u.test(character))
+            return true;
+        if (/[\p{L}\p{N}]/u.test(character))
+            return false;
+        return code > 0xff || SYMBOL_ONLY_ASCII.includes(character);
     });
 }
 function isWithinLocalizedElement(content, matchIndex) {

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

@@ -35,6 +35,18 @@ export async function validateRegistrationPatterns(root, config) {
     for (const [name, customConfig] of Object.entries(config.custom)) {
         if (!customConfig.register)
             continue;
+        // A component that is not mentioned at all is a distinct defect from one
+        // registered in the wrong block: `--fix` can repair the former (idempotent
+        // insert) but deliberately refuses the latter (moving code between blocks).
+        if (!isTagAlreadyRegistered(content, name)) {
+            issues.push({
+                component: name,
+                severity: 'error',
+                check: 'missing-custom-element-registration',
+                message: `${name} has register: true but no registration in ${CUSTOM_ELEMENTS_JS}. Run "fireforge furnace validate ${name} --fix" to add it.`,
+            });
+            continue;
+        }
         const stripped = stripJsComments(content);
         const tagPattern = new RegExp(`["']${escapeRegex(name)}["']`);
         if (tagPattern.test(stripped) && !isTagInCorrectCustomElementsPlacement(content, name, true)) {
@@ -268,6 +280,8 @@ async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
         entries = await readdir(contentDir);
     }
     catch {
+        // No readable chrome-document directory means no documents reference the
+        // tag, which is the same verdict as an empty directory.
         return [];
     }
     const alreadySet = new Set(already);
@@ -284,6 +298,8 @@ async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
             content = await readText(absPath);
         }
         catch {
+            // An unreadable chrome document cannot be searched for the tag; skip it and
+            // keep scanning the rest.
             continue;
         }
         if (content.includes(tagName)) {

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState } from './furnace-config.js';
@@ -109,7 +110,7 @@ export async function validateAllComponents(root) {
         validateComposesReferences(config.stock, config.overrides, config.custom);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = toError(err).message;
         // Attribute the issue to the first custom component with a bad composes reference
         for (const [name, cfg] of Object.entries(config.custom)) {
             if (cfg.composes) {
@@ -129,7 +130,7 @@ export async function validateAllComponents(root) {
         detectComposesCycles(config.custom);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = toError(err).message;
         // Attribute the cycle issue to the first custom component in the cycle
         for (const name of Object.keys(config.custom)) {
             if (config.custom[name]?.composes) {
@@ -274,6 +275,7 @@ async function findOrphanXpcshellScaffolds(root, config) {
         entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
     }
     catch {
+        // An unreadable parent directory yields no sibling component dirs.
         return [];
     }
     const known = new Set([

package/dist/src/core/git-diff.js

@@ -460,6 +460,15 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     // stage/unstage pair mutates the index, so it must not interleave with
     // another concurrent binary patch (see runWithBinaryStagingLock).
     return runWithBinaryStagingLock(async () => {
+        // Snapshot the path's exact index entry before touching it. The cleanup
+        // used to be a blanket `git reset HEAD -- <file>`, which restores the
+        // path to its HEAD state — for a path absent from HEAD that means
+        // *removing* whatever entry the index carried, so any staged state that
+        // arrived between the read-only diff above and this staging block (a
+        // concurrent writer, or a staged-add whose worktree file was deleted)
+        // was silently discarded (FORGE H1). Restoring the captured entry
+        // instead makes the cleanup exact regardless of how the entry got there.
+        const priorEntry = (await execGitWithAllowedExitCodes(repoDir, ['ls-files', '--stage', '--', filePath])).stdout;
         try {
             await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
             const diffResult = await execGitWithAllowedExitCodes(repoDir, [
@@ -471,8 +480,34 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
             return diffResult.stdout;
         }
         finally {
-            // Always unstage, even if diff fails
-            await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+            await restoreIndexEntry(repoDir, filePath, priorEntry);
         }
     });
 }
+/**
+ * Restores a path's index entry to a previously captured `ls-files --stage`
+ * snapshot after a temporary `--intent-to-add` staging. No prior entry means
+ * the temporary entry is dropped via `reset HEAD` (the path's HEAD state IS
+ * "absent" — this branch only runs for files untracked in HEAD). A prior
+ * stage-0 entry is re-pointed at its recorded mode and blob. Unmerged entries
+ * (stages 1–3) cannot be rebuilt through `--cacheinfo`; that degenerate state
+ * keeps the legacy reset-to-HEAD behavior rather than corrupting the conflict.
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @param priorEntry - Raw `git ls-files --stage -- <file>` output from before staging
+ */
+async function restoreIndexEntry(repoDir, filePath, priorEntry) {
+    const entryMatch = /^(\d{6}) ([0-9a-f]{4,64}) 0\t/.exec(priorEntry.trim());
+    const mode = entryMatch?.[1];
+    const oid = entryMatch?.[2];
+    if (mode === undefined || oid === undefined) {
+        await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+        return;
+    }
+    await execGitWithAllowedExitCodes(repoDir, [
+        'update-index',
+        '--add',
+        '--cacheinfo',
+        `${mode},${oid},${filePath}`,
+    ]);
+}

package/dist/src/core/lint-cache.d.ts

@@ -1,7 +1,7 @@
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type PatchQueueContext } from './patch-lint.js';
-export declare const LINT_CACHE_SCHEMA_VERSION = 2;
+export declare const LINT_CACHE_SCHEMA_VERSION = 3;
 export interface PerPatchLintCacheEntry {
     key: string;
     patchFilename: string;

package/dist/src/core/lint-cache.js

@@ -11,7 +11,11 @@ import { collectNewFileCreatorsByPath } from './patch-lint.js';
 // issues and the measured non-binary line count, so a warm run can report
 // waived size measurements identically to a cold one (the F5-class hazard:
 // a cache hit must never surface LESS than a fresh lint).
-export const LINT_CACHE_SCHEMA_VERSION = 2;
+// Schema 3 (FORGE H2): the key additionally content-hashes the
+// `patchLint.checkJsTestShim` file exactly as `checkJsExtraShim`'s already
+// was — before this, editing the test shim in place replayed every cached
+// verdict (the same warm-run-reports-less-than-cold hazard class).
+export const LINT_CACHE_SCHEMA_VERSION = 3;
 const LINT_IMPLEMENTATION_VERSION = 1;
 const LINT_CACHE_DIRNAME = 'lint-cache';
 const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
@@ -85,28 +89,44 @@ function buildOwnershipFingerprint(files, ctx) {
  * The key includes source, metadata, config, engine state, and ownership inputs.
  */
 export async function buildPerPatchLintCacheKey(input) {
+    // Hash in parallel, then insert in sorted order. The sort is load-bearing:
+    // `stableHash` below serialises this record, so insertion order is part of
+    // the cache key — assigning as results land would make the key
+    // nondeterministic. Hashing was strictly sequential until 0.41.0, in the hot
+    // path of the cache whose entire purpose is making lint faster.
+    const sortedFiles = [...input.existingFiles].sort((a, b) => a.localeCompare(b));
+    const hashes = await Promise.all(sortedFiles.map((file) => fileHash(join(input.engineDir, file))));
     const engineFiles = {};
-    for (const file of [...input.existingFiles].sort((a, b) => a.localeCompare(b))) {
-        engineFiles[file] = await fileHash(join(input.engineDir, file));
-    }
+    hashes.forEach((hash, index) => {
+        const file = sortedFiles[index];
+        if (file !== undefined)
+            engineFiles[file] = hash;
+    });
     const furnaceConfigPath = getFurnacePaths(input.projectRoot).furnaceConfig;
-    const extraShimPath = input.config.patchLint?.checkJsExtraShim;
-    const extraShim = extraShimPath === undefined
+    const shimHashOf = async (shimPath) => shimPath === undefined
         ? null
-        : {
-            path: extraShimPath,
-            hash: await fileHash(resolve(input.projectRoot, extraShimPath)),
-        };
+        : { path: shimPath, hash: await fileHash(resolve(input.projectRoot, shimPath)) };
+    // Both shims feed compiled checkJs programs, so both are content-hashed —
+    // the config block alone only carries their PATHS, and an in-place edit
+    // must invalidate the programs it feeds (FORGE H2).
+    const [extraShim, testShim] = await Promise.all([
+        shimHashOf(input.config.patchLint?.checkJsExtraShim),
+        shimHashOf(input.config.patchLint?.checkJsTestShim),
+    ]);
     return stableHash({
         cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
         engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
+        // Deliberately the PLAIN semver, not the +g<sha> build identity
+        // (FORGE K2): identity churns every commit at the same version and
+        // would invalidate the cache for no correctness gain.
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
         patchMetadata: normalizePatchMetadata(input.patch),
         lintConfig: normalizeLintConfig(input.config),
         furnaceConfig: await fileHash(furnaceConfigPath),
         checkJsExtraShim: extraShim,
+        checkJsTestShim: testShim,
         engineFiles,
         queueOwnership: buildOwnershipFingerprint(input.existingFiles, input.queueContext),
     });
@@ -150,6 +170,9 @@ export async function loadPerPatchLintCache(projectRoot) {
         return { schemaVersion: LINT_CACHE_SCHEMA_VERSION, entries };
     }
     catch {
+        // Any unreadable or malformed cache file is treated as a cold cache. The
+        // cache is a pure optimisation, so discarding it is always safe — the
+        // alternative is failing lint over a corrupt sidecar.
         return createEmptyPerPatchLintCache();
     }
 }

package/dist/src/core/mach-build-artifacts.d.ts

@@ -20,7 +20,11 @@ export interface BuildArtifactCheck {
 }
 /**
  * Checks if build artifacts exist in the engine directory.
- * Looks for obj-* directories with a dist subdirectory.
+ * Looks for obj-* directories with a dist subdirectory. Detection is
+ * deliberately symlink-agnostic — building/running against a symlinked
+ * objdir in place is the user's own arrangement; the clone path, where a
+ * symlink would route writes into the original build, refuses separately
+ * (`assertCloneSafeObjdir` in tree-store.ts).
  * @param engineDir - Path to the engine directory
  * @returns Build artifact check result
  */
@@ -112,3 +116,61 @@ export interface MozinfoRewriteResult {
  * @returns Result object; callers inspect `rewritten` and surface `reason`.
  */
 export declare function attemptMozinfoRewrite(engineDir: string, objDir: string): Promise<MozinfoRewriteResult>;
+/** Per-command wording for {@link assertBuildArtifacts}. */
+export interface BuildArtifactPreflightOptions {
+    /** Label passed to {@link buildArtifactMismatchMessage} (e.g. `'Tests'`). */
+    label: string;
+    /** Sentence naming what needs a build, e.g. `'Tests require a completed build.'` */
+    requirement: string;
+    /** Follow-up telling the operator what to run, shown after `requirement`. */
+    remediation: string;
+    /**
+     * Whether a missing/incomplete build is fatal. `fireforge build` runs
+     * legitimately with no artifacts and only enforces this under `--ui`, so it
+     * opts in rather than out.
+     */
+    requireExisting?: boolean;
+}
+/**
+ * Shared build-artifact preflight: rejects ambiguous multi-objdir checkouts,
+ * artifacts whose metadata points at another tree, and (when
+ * `requireExisting`) missing or incomplete builds — each with the actionable
+ * message for that case.
+ *
+ * Takes an already-probed {@link BuildArtifactCheck} rather than probing
+ * itself, so it stays a pure validator: callers keep their own
+ * `hasBuildArtifacts` call (which their suites already stub) and this function
+ * needs no test double of its own.
+ *
+ * Five commands carried a character-identical copy of this ladder, including
+ * the same `ambiguous && objDirs && objDirs.length > 0` expression that
+ * `BuildArtifactCheck`'s boolean-plus-optionals shape forces at every reader.
+ * The shape itself is unchanged — it has several producers and a documented
+ * refusal contract (see the containment predicates below) — but it is now
+ * destructured in exactly one place.
+ */
+export declare function assertBuildArtifacts(engineDir: string, buildCheck: BuildArtifactCheck, options: BuildArtifactPreflightOptions): void;
+/**
+ * Post-`mach configure` relocation check for a cloned objdir: confirms
+ * configure actually regenerated `<engineDir>/<objDir>` and that none of
+ * the four configure-generated root files (`config.status`, `backend.mk`,
+ * `Makefile`, `config/autoconf.mk`) still names `forbiddenDir` (the
+ * primary engine a relocated clone must never consult). Exit code 0 alone
+ * proves neither — a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
+ * different objdir entirely. Nested Makefiles are products of the verified
+ * `config.status` and are not scanned; `.deps` files are build products a
+ * configure cannot regenerate and are explicitly out of scope — any
+ * primary-path strings they retain are read-only staleness corrected by
+ * the first in-tree rebuild. Pure checker: returns a human-readable
+ * violation, or `undefined` when clean; callers own the error type and
+ * remediation copy. Unreadable metadata is itself a violation (fail
+ * closed).
+ */
+export declare function findObjdirRelocationViolation(args: {
+    /** The relocated (tree) engine directory configure ran in. */
+    engineDir: string;
+    /** The obj-* directory name configure was expected to target. */
+    objDir: string;
+    /** The primary engine dir whose absolute path must not appear. */
+    forbiddenDir: string;
+}): Promise<string | undefined>;