@hominis/fireforge 0.40.0 → 0.42.0

package/dist/src/core/tree-store.js

@@ -12,16 +12,24 @@
  * `tree remove` + `tree create`.
  */
 import { createHash } from 'node:crypto';
-import { readdir, readFile, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { lstat, readdir, readFile, realpath, rm } from 'node:fs/promises';
 import { basename, join, resolve, sep } from 'node:path';
 import { GeneralError } from '../errors/base.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { withFileLock } from './file-lock.js';
+import { verbose, warn } from '../utils/logger.js';
+import { isObject } from '../utils/validation.js';
+import { getBuildBaselinePath } from './build-baseline.js';
+import { LOCK_PID_FILE, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
+import { getAllDiff } from './git-diff.js';
+import { attemptMozinfoRewrite } from './mach-build-artifacts.js';
 import { cloneEntry } from './tree-cow.js';
 const TREE_MARKER_FILENAME = 'tree.json';
 const TREES_DIRNAME = 'trees';
+const TREE_CLONE_CONCURRENCY = 8;
 /**
  * Top-level entries never cloned into a tree: per-tree state must start
  * clean (`.fireforge/`), locks are never inherited, the destructive-
@@ -45,38 +53,137 @@ export async function withTreeLifecycleLock(primaryRoot, operation) {
         onTimeoutMessage: 'Another fireforge tree create/remove is in progress. Wait for it to finish, then retry.',
     });
 }
-/** Reads the tree marker for a project root, or undefined when not a tree. */
-export async function readTreeMarker(root) {
-    const markerPath = join(root, '.fireforge', TREE_MARKER_FILENAME);
-    if (!(await pathExists(markerPath)))
-        return undefined;
+/**
+ * Validates every field of a tree marker.
+ *
+ * The read below checked only `schemaVersion` and `name` and asserted the
+ * rest, but the unvalidated fields are consumed unguarded: `primaryRoot`
+ * reaches a user-facing refusal message (`tree-guard.ts:105`), and
+ * `engineHead`/`patchesFingerprint` feed the staleness compare, where an
+ * `undefined` from a truncated marker reports every tree as stale.
+ */
+function isTreeMarker(value) {
+    if (!isObject(value))
+        return false;
+    return (value['schemaVersion'] === 1 &&
+        typeof value['name'] === 'string' &&
+        typeof value['primaryRoot'] === 'string' &&
+        typeof value['createdAt'] === 'string' &&
+        (typeof value['engineHead'] === 'string' || value['engineHead'] === null) &&
+        (value['engineFingerprint'] === undefined ||
+            typeof value['engineFingerprint'] === 'string' ||
+            value['engineFingerprint'] === null) &&
+        (typeof value['patchesFingerprint'] === 'string' || value['patchesFingerprint'] === null) &&
+        (value['clonedObjdir'] === undefined || typeof value['clonedObjdir'] === 'string'));
+}
+/** Absolute path of a root's tree marker. */
+export function getTreeMarkerPath(root) {
+    return join(root, '.fireforge', TREE_MARKER_FILENAME);
+}
+/**
+ * Reads the tree marker for a project root, distinguishing "not a tree" from
+ * "a tree whose marker we could not read". Callers that make a safety decision
+ * (the guard hook, the no-nesting refusal) must use this rather than
+ * {@link readTreeMarker}.
+ *
+ * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
+ * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
+ * the marker" is not evidence that there is no marker — a `pathExists`
+ * pre-check here classified a tree with an unreadable `.fireforge` as
+ * `absent` and handed it the full mutating command set.
+ */
+export async function readTreeMarkerState(root) {
+    const markerPath = getTreeMarkerPath(root);
     try {
         const raw = await readJson(markerPath);
-        if (raw.schemaVersion !== 1 || typeof raw.name !== 'string')
-            return undefined;
-        return raw;
+        if (!isTreeMarker(raw)) {
+            verbose(`Malformed tree marker at ${markerPath}`);
+            return { kind: 'corrupt', reason: 'the marker is missing or mistypes a required field' };
+        }
+        return { kind: 'valid', marker: raw };
     }
     catch (error) {
+        const code = getNodeErrorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { kind: 'absent' };
         verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
-        return undefined;
+        return { kind: 'corrupt', reason: `the marker could not be read (${toError(error).message})` };
+    }
+}
+/**
+ * Reads the tree marker for a project root, or undefined when it is absent
+ * OR unreadable.
+ *
+ * For display and best-effort paths only (`tree list` renders an unreadable
+ * marker as staleness 'unknown'). Anything that decides whether a mutation may
+ * proceed must call {@link readTreeMarkerState} and handle `corrupt`.
+ */
+export async function readTreeMarker(root) {
+    const state = await readTreeMarkerState(root);
+    return state.kind === 'valid' ? state.marker : undefined;
+}
+/**
+ * Refuses a build-less in-tree `test` when the objdir preflight found is not
+ * the one this tree's marker vouched for as rewritten-and-reconfigured. A
+ * mismatch means an objdir appeared in the tree through some path other than
+ * `tree create --with-objdir` (manual copy, partial restore), so nothing
+ * proves it was relocated — running against it could consult primary paths.
+ * No-op outside a tree; a corrupt marker is already refused by the guard.
+ */
+export async function assertObjdirMatchesTreeMarker(projectRoot, objDir) {
+    const state = await readTreeMarkerState(projectRoot);
+    if (state.kind !== 'valid' || state.marker.clonedObjdir === undefined)
+        return;
+    if (objDir !== state.marker.clonedObjdir) {
+        throw new GeneralError(`This verification tree's marker records "${state.marker.clonedObjdir}" as its cloned build, ` +
+            `but the preflight found ${objDir === undefined ? 'no objdir' : `"${objDir}"`}. ` +
+            'Only the objdir cloned by tree create --with-objdir is proven to be relocated to this tree. ' +
+            'Remove and re-create the tree (fireforge tree remove/create).');
     }
 }
-/** Current primary-side snapshot identity (engine HEAD + patches.json hash). */
+/** Current primary-side snapshot identity, including dirty source and patch bodies. */
 export async function computePrimaryFingerprint(primaryRoot) {
+    const engineDir = join(primaryRoot, 'engine');
     let engineHead;
     try {
-        engineHead = (await git(['rev-parse', 'HEAD'], join(primaryRoot, 'engine'))).trim();
+        engineHead = (await git(['rev-parse', 'HEAD'], engineDir)).trim();
     }
     catch {
+        // An engine that is missing, unborn, or not a git checkout has no HEAD to
+        // fingerprint. `null` is a legal marker value and reads as 'unknown', which
+        // `listTrees` renders as staleness 'unknown' rather than a false 'fresh'.
         engineHead = null;
     }
-    const patchesJson = join(primaryRoot, 'patches', 'patches.json');
-    const patchesFingerprint = (await pathExists(patchesJson))
-        ? createHash('sha256')
-            .update(await readFile(patchesJson))
-            .digest('hex')
-        : null;
-    return { engineHead, patchesFingerprint };
+    let engineFingerprint;
+    try {
+        engineFingerprint = createHash('sha256')
+            .update(await getAllDiff(engineDir))
+            .digest('hex');
+    }
+    catch {
+        engineFingerprint = null;
+    }
+    const patchesDir = join(primaryRoot, 'patches');
+    let patchesFingerprint = null;
+    try {
+        if (await pathExists(patchesDir)) {
+            const hash = createHash('sha256');
+            for (const name of (await readdir(patchesDir))
+                .filter((entry) => entry.endsWith('.patch') || entry === 'patches.json')
+                .sort()) {
+                hash
+                    .update(name)
+                    .update('\0')
+                    .update(await readFile(join(patchesDir, name)))
+                    .update('\0');
+            }
+            patchesFingerprint = hash.digest('hex');
+        }
+    }
+    catch {
+        patchesFingerprint = null;
+    }
+    return { engineHead, engineFingerprint, patchesFingerprint };
 }
 /** Validates a tree name: one path segment, no traversal. */
 export function assertValidTreeName(name) {
@@ -84,54 +191,156 @@ export function assertValidTreeName(name) {
         throw new GeneralError(`Invalid tree name "${name}". Use a single path segment of letters, digits, ".", "_" or "-".`);
     }
 }
+/**
+ * Refuses an objdir that is not a plain directory physically inside
+ * `engineDir` — every `cp` mode `cloneEntry` uses preserves symlinks, so
+ * a symlinked `engine/obj-*` would be cloned as a symlink pointing back
+ * at the original (primary or fully external) build, and the clone's
+ * mozinfo rewrite and `_virtualenvs` removal would then mutate that
+ * original through the link. Checks lstat (the entry itself must be a
+ * real directory) AND realpath containment (a real directory reached
+ * through a symlinked parent resolves elsewhere) — the rewriter's
+ * lexical `resolve()` paths cannot detect either. Also validates the
+ * name as a single `obj-*` path segment. Role `'primary'` guards before
+ * any copying starts; `'cloned'` re-checks the tree's copy before any
+ * write goes through it (defense in depth).
+ */
+async function assertCloneSafeObjdir(engineDir, objDir, role) {
+    const where = role === 'primary' ? 'engine/' : "the tree's engine/";
+    if (!/^obj-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(objDir) || objDir.includes('..')) {
+        throw new GeneralError(`Invalid objdir name "${objDir}". Expected a single obj-* path segment of letters, digits, ".", "_" or "-".`);
+    }
+    const objDirPath = join(engineDir, objDir);
+    let stats;
+    try {
+        stats = await lstat(objDirPath);
+    }
+    catch (error) {
+        throw new GeneralError(`tree create --with-objdir cannot stat ${where}${objDir}: ${toError(error).message}`);
+    }
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new GeneralError(`tree create --with-objdir refuses ${where}${objDir}: it is ${stats.isSymbolicLink() ? 'a symlink' : 'not a directory'}. A cloned symlinked objdir would be rewritten through the link, mutating the ` +
+            'original build it points at. Replace it with a real directory or create the tree ' +
+            'without --with-objdir.');
+    }
+    const [realObjDir, realEngineDir] = await Promise.all([
+        realpath(objDirPath),
+        realpath(engineDir),
+    ]);
+    if (realObjDir !== join(realEngineDir, objDir)) {
+        throw new GeneralError(`tree create --with-objdir refuses ${where}${objDir}: it resolves to ${realObjDir}, ` +
+            `outside ${realEngineDir}. An objdir reached through a symlink would be rewritten ` +
+            'in place, mutating the original build. Replace it with a real directory or create ' +
+            'the tree without --with-objdir.');
+    }
+}
 /**
  * Materialises the tree at `treeRoot` from `primaryRoot` using
  * `capability` ('none' = plain copy, already gated on --force-copy by
- * the caller). The engine tree is cloned whole and its `obj-*` build
- * directories removed afterwards — CoW removal is cheap, and per-entry
- * recursion into a Firefox tree is fragile. A fresh `.fireforge/` is
- * created with only `state.json` (when present) and the tree marker.
+ * the caller). The engine is cloned one TOP-LEVEL entry at a time so unwanted
+ * `obj-*` directories are never traversed or materialised. That distinction
+ * is substantial on Firefox trees: even CoW-cloning and deleting an objdir
+ * touches metadata for millions of build outputs. With `withObjdir` exactly
+ * that objdir is included — after {@link assertCloneSafeObjdir}
+ * refuses symlinked or engine-escaping objdirs before any copying —
+ * rewritten to the tree (see below), and
+ * reconfigured in-tree via the caller-supplied `reconfigure` hook. A
+ * fresh `.fireforge/` is created with only `state.json` (when present),
+ * the last-build baseline (withObjdir only), and the tree marker.
  */
 export async function cloneTree(args) {
-    const { primaryRoot, treeRoot, name, capability, createdAt } = args;
+    const { primaryRoot, treeRoot, name, capability, createdAt, withObjdir } = args;
     const { mkdir, cp } = await import('node:fs/promises');
-    await mkdir(treeRoot, { recursive: true });
-    for (const entry of await readdir(primaryRoot)) {
-        if (isExcludedRootEntry(entry))
-            continue;
-        await cloneEntry(capability, join(primaryRoot, entry), join(treeRoot, entry));
+    if (withObjdir) {
+        // Refuse a symlinked/escaping primary objdir BEFORE any copying: the
+        // clone would carry the symlink and every later write would land in
+        // the original build (see assertCloneSafeObjdir).
+        await assertCloneSafeObjdir(join(primaryRoot, 'engine'), withObjdir.objDir, 'primary');
     }
-    // A cloned objdir embeds absolute topsrcdir/topobjdir paths back into
-    // the PRIMARY tree (mach-build-artifacts.ts parses exactly those), so
-    // in-tree builds/tests would silently operate against the primary —
-    // remove the clones; `tree` is read-verification only in 0.40.0.
+    await mkdir(treeRoot, { recursive: true });
+    const rootEntries = (await readdir(primaryRoot)).filter((entry) => !isExcludedRootEntry(entry));
     const engineDir = join(treeRoot, 'engine');
-    if (await pathExists(engineDir)) {
-        for (const entry of await readdir(engineDir)) {
-            if (entry.startsWith('obj-')) {
-                await rm(join(engineDir, entry), { recursive: true, force: true });
-            }
+    await mapWithConcurrency(rootEntries, TREE_CLONE_CONCURRENCY, async (entry) => {
+        if (entry !== 'engine') {
+            await cloneEntry(capability, join(primaryRoot, entry), join(treeRoot, entry));
+            return;
         }
+        const primaryEngineDir = join(primaryRoot, 'engine');
+        await mkdir(engineDir, { recursive: true });
+        const engineEntries = (await readdir(primaryEngineDir)).filter((engineEntry) => !engineEntry.startsWith('obj-') || engineEntry === withObjdir?.objDir);
+        await mapWithConcurrency(engineEntries, TREE_CLONE_CONCURRENCY, async (engineEntry) => {
+            await cloneEntry(capability, join(primaryEngineDir, engineEntry), join(engineDir, engineEntry));
+        });
+    });
+    // A selected objdir embeds absolute topsrcdir/topobjdir paths back into
+    // the PRIMARY tree. It is rewritten below before the marker records it as
+    // usable; no other objdir ever enters the snapshot.
+    if (await pathExists(engineDir)) {
         // Defensive: never inherit a mid-operation git index lock.
         await rm(join(engineDir, '.git', 'index.lock'), { force: true });
     }
+    if (withObjdir) {
+        await rewriteClonedObjdir(engineDir, withObjdir.objDir);
+        // Regenerate configure output (config.status, backend.mk, Makefile,
+        // config/autoconf.mk) against the tree's paths — the mozinfo rewrite
+        // alone leaves those naming the primary. A failed reconfigure throws
+        // before the marker below records the objdir as usable (fail-closed).
+        await withObjdir.reconfigure(engineDir);
+    }
     await mkdir(join(treeRoot, '.fireforge'), { recursive: true });
     const stateJson = join(primaryRoot, '.fireforge', 'state.json');
     if (await pathExists(stateJson)) {
         await cp(stateJson, join(treeRoot, '.fireforge', 'state.json'));
     }
-    const { engineHead, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
+    if (withObjdir) {
+        // The in-tree stale-build and static-components gates anchor on the
+        // last-build baseline; without the copy they would read `undefined`
+        // and degrade to first-build semantics inside a fully built tree.
+        const baseline = getBuildBaselinePath(primaryRoot);
+        if (await pathExists(baseline)) {
+            await cp(baseline, getBuildBaselinePath(treeRoot));
+        }
+    }
+    const { engineHead, engineFingerprint, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
     const marker = {
         schemaVersion: 1,
         name,
         primaryRoot,
         createdAt,
         engineHead,
+        engineFingerprint: engineFingerprint ?? null,
         patchesFingerprint,
+        ...(withObjdir ? { clonedObjdir: withObjdir.objDir } : {}),
     };
     await writeJson(join(treeRoot, '.fireforge', TREE_MARKER_FILENAME), marker);
     return marker;
 }
+/**
+ * Points the cloned objdir at the tree: rewrites mozinfo.json's
+ * topsrcdir/topobjdir (and an in-tree mozconfig) via the same
+ * safe-relocation rewriter `build --rewrite-mozinfo` uses, refusing
+ * fail-closed when its safety rules cannot prove the rewrite correct —
+ * a tree must never hold an objdir that still names the primary. Before
+ * any write, the cloned objdir is re-checked as a real directory inside
+ * the tree ({@link assertCloneSafeObjdir}) so no write ever goes through
+ * a symlink into the original build. The cloned `_virtualenvs` are
+ * removed outright: their scripts carry primary-tree shebang paths, and
+ * mach rebuilds venvs in-tree on first use. The configure-generated root
+ * files (config.status, backend.mk, Makefile, config/autoconf.mk) still
+ * name the primary after this rewrite; they are regenerated by the
+ * in-tree `mach configure` the caller supplies to {@link cloneTree},
+ * which runs before the marker is written.
+ */
+async function rewriteClonedObjdir(engineDir, objDir) {
+    await assertCloneSafeObjdir(engineDir, objDir, 'cloned');
+    const rewrite = await attemptMozinfoRewrite(engineDir, objDir);
+    if (!rewrite.rewritten) {
+        throw new GeneralError(`Cannot keep the cloned build: ${rewrite.reason ?? 'mozinfo.json rewrite refused'}. ` +
+            'The objdir would still operate against the primary tree. ' +
+            'Re-run tree create without --with-objdir, or rebuild the primary objdir with "fireforge build" and retry.');
+    }
+    await rm(join(engineDir, objDir, '_virtualenvs'), { recursive: true, force: true });
+}
 /** Lists trees with staleness against the current primary state. */
 export async function listTrees(primaryRoot) {
     const treesDir = getTreesDir(primaryRoot);
@@ -150,47 +359,68 @@ export async function listTrees(primaryRoot) {
         }
         const staleness = marker.engineHead !== current.engineHead
             ? 'stale (engine advanced)'
-            : marker.patchesFingerprint !== current.patchesFingerprint
-                ? 'stale (patches changed)'
-                : 'fresh';
+            : marker.engineFingerprint !== undefined &&
+                marker.engineFingerprint !== current.engineFingerprint
+                ? 'stale (engine worktree changed)'
+                : marker.patchesFingerprint !== current.patchesFingerprint
+                    ? 'stale (patches changed)'
+                    : 'fresh';
         entries.push({ name, path, createdAt: marker.createdAt, staleness });
     }
     return entries;
 }
-/** Uses `kill(pid, 0)` — no signal sent, just an existence check. */
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
- * Returns the live holder PID of a mkdir-style lock directory, if any.
- * Reads the lock's `pid` file directly (line 1 = PID — the format
- * `file-lock.ts` documents as stable) instead of exporting file-lock
- * internals.
+ * Classifies a mkdir-style lock directory. Reads the lock's owner file
+ * directly (line 1 = PID — the format `file-lock.ts` documents as stable,
+ * whose name it shares via {@link LOCK_PID_FILE}) instead of exporting
+ * file-lock internals.
+ *
+ * Liveness comes from the shared {@link isProcessAlive}, which treats EPERM
+ * as alive. The local copy this replaced returned `false` for EPERM, so a
+ * tree whose build lock was held by a live process running under a different
+ * uid passed the guard below and was `rm -rf`'d mid-build.
+ *
+ * The `unknown` state is not a theoretical case. `withFileLock` takes the lock
+ * by creating the directory and only *then* writes the owner file, treating a
+ * write failure as non-fatal — so every acquisition passes through a window in
+ * which the lock is genuinely held and has no readable PID, and a read-only or
+ * full filesystem leaves it that way for the lock's whole life. Reporting that
+ * as `free` let `removeTree` recursively delete a tree out from under a live
+ * build. `file-lock.ts` reaches the same conclusion for its own stale
+ * recovery, where an unreadable PID falls back to an age-only heuristic rather
+ * than assuming the lock is abandoned.
  */
-async function liveLockHolder(lockPath) {
+async function inspectTreeLock(lockPath) {
+    if (!existsSync(lockPath))
+        return { kind: 'free' };
+    let pidLine;
     try {
-        const pidLine = (await readFile(join(lockPath, 'pid'), 'utf-8')).split('\n')[0] ?? '';
-        const pid = parseInt(pidLine.trim(), 10);
-        if (Number.isFinite(pid) && isProcessAlive(pid))
-            return pid;
+        pidLine = (await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8')).split('\n')[0] ?? '';
     }
-    catch {
-        // No lock / unreadable pid file — treat as not held.
+    catch (error) {
+        // A lock cleanly released between the existence probe above and this read
+        // leaves no directory behind — that is a release, not an unreadable owner,
+        // and demanding --force for it would be a spurious refusal.
+        if (!existsSync(lockPath))
+            return { kind: 'free' };
+        return {
+            kind: 'unknown',
+            reason: `its owner record is missing or unreadable (${toError(error).message})`,
+        };
+    }
+    const pid = parseInt(pidLine.trim(), 10);
+    if (!Number.isFinite(pid)) {
+        return { kind: 'unknown', reason: 'its owner record does not name a process id' };
     }
-    return undefined;
+    return isProcessAlive(pid) ? { kind: 'held', pid } : { kind: 'free' };
 }
 /**
  * Removes one tree. Refuses when a live process holds the tree's build
- * or engine-session lock, and never deletes a path outside the trees
- * directory (containment check before `rm -rf`).
+ * or engine-session lock — or when a lock directory exists whose ownership
+ * cannot be established, which `--force` overrides — and never deletes a path
+ * outside the trees directory (containment check before `rm -rf`).
  */
-export async function removeTree(primaryRoot, name) {
+export async function removeTree(primaryRoot, name, options = {}) {
     assertValidTreeName(name);
     const treesDir = getTreesDir(primaryRoot);
     const treeRoot = resolve(treesDir, name);
@@ -204,11 +434,19 @@ export async function removeTree(primaryRoot, name) {
         join(treeRoot, '.fireforge-build.lock'),
         join(treeRoot, '.fireforge', 'engine-session.lock'),
     ]) {
-        const holder = await liveLockHolder(lockPath);
-        if (holder !== undefined) {
-            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(holder)}) holds ${lockPath}. ` +
+        const state = await inspectTreeLock(lockPath);
+        if (state.kind === 'held') {
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(state.pid)}) holds ${lockPath}. ` +
                 'Wait for it to finish, then retry.');
         }
+        if (state.kind === 'unknown' && options.force !== true) {
+            throw new GeneralError(`Refusing to remove tree "${name}": ${lockPath} exists but ${state.reason}, so it may be ` +
+                'held by a live process. Wait for any in-flight build or test to finish; if none is ' +
+                'running, re-run with --force to delete the tree and the stale lock.');
+        }
+        if (state.kind === 'unknown') {
+            warn(`Removing tree "${name}" through ${lockPath}, whose ownership is unknown (--force).`);
+        }
     }
     await rm(treeRoot, { recursive: true, force: true });
 }

package/dist/src/core/typecheck.js

@@ -19,6 +19,7 @@
  * at `npm install typescript`.
  */
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
@@ -113,7 +114,7 @@ export async function runTypecheck(projectRoot, cfg) {
         catch (err) {
             // A missing or unreadable shim fails only the project(s) that use it,
             // not the whole run — projects with a different (or no) shim still run.
-            const message = err instanceof Error ? err.message : String(err);
+            const message = toError(err).message;
             results.push({
                 project: projectPath,
                 issues: [

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

@@ -8,7 +8,7 @@ import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, parseScript } from './ast-utils.js';
+import { asEstree, detectIndent, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
@@ -36,7 +36,10 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
         throw new BuildError('Could not find onUnload/uninit method body via AST');
     }
     // Insert at top of method body (LIFO ordering)
-    const firstStmt = body.body[0];
+    // `noUncheckedIndexedAccess` makes this `Statement | undefined`; narrow
+    // before casting rather than laundering the undefined through the cast.
+    const firstRaw = body.body[0];
+    const firstStmt = firstRaw ? asEstree(firstRaw) : undefined;
     let insertPos;
     let indent;
     if (firstStmt) {
@@ -114,7 +117,15 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     if (destroyPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

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

@@ -8,7 +8,7 @@ import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
@@ -18,6 +18,30 @@ const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
  * fallback code paths agree on the shape.
  */
 const DEFAULT_MARKER = 'FIREFORGE:';
+/**
+ * Default insertion point: after the last consecutive fireforge block, or at
+ * the top of the method body when there is none.
+ *
+ * Both callers below — the `--after`-target-not-found fallthrough and the
+ * no-`--after` default — ran a character-for-character copy of this ladder,
+ * including both throw guards. `browser-init.js` is written through those two
+ * independent paths and they MUST emit identical blocks, so having one
+ * implementation enforces the invariant rather than merely tidying.
+ */
+function resolveDefaultInsertion(content, body, fireforgeBlocks) {
+    if (fireforgeBlocks.length > 0) {
+        const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
+        if (!lastBlock)
+            throw new GeneralError('Unexpected empty fireforgeBlocks array');
+        return { insertPos: lastBlock.end, indent: detectIndent(content, lastBlock.start) };
+    }
+    const firstStmt = body.body[0];
+    if (firstStmt) {
+        const insertPos = asEstree(firstStmt).start;
+        return { insertPos, indent: detectIndent(content, insertPos) };
+    }
+    return { insertPos: body.start + 1, indent: '    ' };
+}
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
@@ -47,7 +71,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
     const fireforgeBlocks = [];
     for (const stmt of body.body) {
         if (stmt.type === 'TryStatement') {
-            const tryNode = stmt;
+            const tryNode = asEstree(stmt);
             const src = getNodeSource(content, tryNode);
             if (/typeof\s+\w+\s*!==\s*"undefined"/.test(src)) {
                 fireforgeBlocks.push(tryNode);
@@ -68,47 +92,12 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
         }
         else {
             // --after target not found: fall through to default (after last fireforge block)
-            if (fireforgeBlocks.length > 0) {
-                const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
-                if (!lastBlock)
-                    throw new GeneralError('Unexpected empty fireforgeBlocks array');
-                insertPos = lastBlock.end;
-                indent = detectIndent(content, lastBlock.start);
-            }
-            else {
-                // No fireforge blocks, insert at top of method body
-                const firstStmt = body.body[0];
-                if (firstStmt) {
-                    insertPos = firstStmt.start;
-                    indent = detectIndent(content, insertPos);
-                }
-                else {
-                    insertPos = body.start + 1;
-                    indent = '    ';
-                }
-            }
+            ({ insertPos, indent } = resolveDefaultInsertion(content, body, fireforgeBlocks));
         }
     }
     else {
         // Default: insert after the last consecutive fireforge block at the start
-        if (fireforgeBlocks.length > 0) {
-            const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
-            if (!lastBlock)
-                throw new GeneralError('Unexpected empty fireforgeBlocks array');
-            insertPos = lastBlock.end;
-            indent = detectIndent(content, lastBlock.start);
-        }
-        else {
-            const firstStmt = body.body[0];
-            if (firstStmt) {
-                insertPos = firstStmt.start;
-                indent = detectIndent(content, insertPos);
-            }
-            else {
-                insertPos = body.start + 1;
-                indent = '    ';
-            }
-        }
+        ({ insertPos, indent } = resolveDefaultInsertion(content, body, fireforgeBlocks));
     }
     const block = [
         `${indent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
@@ -224,7 +213,15 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     if (initPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }