@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -1,30 +1,29 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox
- * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a
- * few seconds into `mach configure` with a message whose remediation
- * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
- * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
- * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a few
+ * seconds into `mach configure` with a message whose remediation text names
+ * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
+ * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
+ * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
- *     the downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
- *     the minimums the tree itself declares against the host binaries
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *     downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory
- *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
- *     only, blocking builds whose current tool lived in the state dir
- *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
- *     mismatch only when a minimum was positively parsed AND at least
- *     one candidate resolved AND every resolved candidate is
- *     definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently — the
- *     mach-error-hints translator still catches the real configure
- *     failure downstream.
+ *     order: env override first, then the `~/.mozbuild` state-directory copy
+ *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
+ *     whose current tool lives in the state dir behind a stale PATH copy.
+ *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
+ *     positively parsed AND at least one candidate resolved AND every
+ *     resolved candidate is definitively lower. Any uncertainty (file moved
+ *     upstream, unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure failure
+ *     downstream.
  */
 /** Tools the preflight knows how to probe. */
 export type ToolchainTool = 'cbindgen' | 'rustc';

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

@@ -2,30 +2,29 @@
 /**
  * Toolchain-minimum awareness for Firefox source hops.
  *
- * When `fireforge download --force` moves the engine to a new Firefox
- * MAJOR version, the tree's declared toolchain minimums (cbindgen, Rust)
- * frequently move with it — and the first `fireforge build` then dies a
- * few seconds into `mach configure` with a message whose remediation
- * text names `./mach bootstrap`, the wrong tool for a FireForge-managed
- * repo (152.0b7 → 153.0b8 source-refresh drill: `ERROR: cbindgen version
- * 0.29.1 is too old. At least version 0.29.4 is required.`).
+ * When `fireforge download --force` moves the engine to a new Firefox MAJOR
+ * version, the tree's declared toolchain minimums (cbindgen, Rust)
+ * frequently move with it — and the first `fireforge build` then dies a few
+ * seconds into `mach configure` with a message whose remediation text names
+ * `./mach bootstrap`, the wrong tool for a FireForge-managed repo (e.g.
+ * `ERROR: cbindgen version 0.29.1 is too old. At least version 0.29.4 is
+ * required.`).
  *
  * Two layers:
- *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when
- *     the downloaded major differs from the previously downloaded one.
- *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing
- *     the minimums the tree itself declares against the host binaries
+ *  1. {@link formatMajorVersionHopNotice} — a post-download nudge when the
+ *     downloaded major differs from the previously downloaded one.
+ *  2. {@link runToolchainPreflight} — a cheap pre-build probe comparing the
+ *     minimums the tree itself declares against the host binaries
  *     `mach configure` will resolve, probing configure's own candidate
- *     order: env override first, then the `~/.mozbuild` state-directory
- *     copy bootstrap installs, then PATH (0.35.0 probed env-or-PATH
- *     only, blocking builds whose current tool lived in the state dir
- *     behind a stale PATH copy). Deliberately FAIL-SOFT: it reports a
- *     mismatch only when a minimum was positively parsed AND at least
- *     one candidate resolved AND every resolved candidate is
- *     definitively lower. Any uncertainty (file moved upstream,
- *     unparseable output, no candidate found) skips silently — the
- *     mach-error-hints translator still catches the real configure
- *     failure downstream.
+ *     order: env override first, then the `~/.mozbuild` state-directory copy
+ *     bootstrap installs, then PATH. Probing env-or-PATH alone blocks builds
+ *     whose current tool lives in the state dir behind a stale PATH copy.
+ *     Deliberately FAIL-SOFT: it reports a mismatch only when a minimum was
+ *     positively parsed AND at least one candidate resolved AND every
+ *     resolved candidate is definitively lower. Any uncertainty (file moved
+ *     upstream, unparseable output, no candidate found) skips silently — the
+ *     mach-error-hints translator still catches the real configure failure
+ *     downstream.
  */
 import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
@@ -61,16 +60,14 @@ const MINIMUM_DECLARATIONS = {
 /**
  * How each tool's host binary is resolved and its version parsed.
  *
- * `stateDirRelPaths` are the mach-state-directory locations `fireforge
- * bootstrap` (via mozboot) installs the tool to. mach's configure tries
- * the state directory BEFORE the PATH candidates (bindgen.configure's
- * toolchain search path lists `~/.mozbuild/cbindgen/cbindgen` first — a
- * configure log shows `trying cbindgen: ~/.mozbuild/cbindgen/cbindgen`
- * ahead of PATH), so the probe must too. 0.35.0 probed only env-or-PATH,
- * which failed a build configure would have accepted whenever an old
- * `~/.cargo/bin/cbindgen` shadowed a current bootstrap-installed copy
- * (field report: PATH 0.29.1 vs mozbuild 0.29.4, minimum 0.29.4). Rust
- * has no state-dir install — rustup owns it — so its list is empty.
+ * `stateDirRelPaths` are the mach-state-directory locations
+ * `fireforge bootstrap` (via mozboot) installs the tool to. mach's configure
+ * tries the state directory BEFORE the PATH candidates —
+ * bindgen.configure's toolchain search path lists `~/.mozbuild/cbindgen/
+ * cbindgen` first — so the probe must too. Probing only env-or-PATH fails a
+ * build configure would have accepted whenever an old `~/.cargo/bin/
+ * cbindgen` shadows a current bootstrap-installed copy. Rust has no
+ * state-dir install — rustup owns it — so its list is empty.
  */
 const HOST_PROBES = {
     // `mach configure` honours the CBINDGEN env option (bindgen.configure's

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

@@ -15,7 +15,7 @@
 import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { GeneralError } from '../errors/base.js';
-import { getTreeMarkerPath, readTreeMarkerState, } from './tree-store.js';
+import { getTreeMarkerPath, readTreeMarker, } from './tree-store.js';
 /**
  * Per-command verdicts. `allowed` runs unconditionally; `refused` never
  * runs in a tree; `conditional` consults `TREE_CONDITIONAL_CHECKS` with
@@ -135,7 +135,7 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
         let current = resolve(process.cwd());
         for (let depth = 0; depth < 50; depth++) {
             if (existsSync(join(current, 'fireforge.json'))) {
-                return { root: current, state: await readTreeMarkerState(current) };
+                return { root: current, state: await readTreeMarker(current) };
             }
             const parent = dirname(current);
             if (parent === current)
@@ -153,6 +153,16 @@ export async function runTreeGuardHook(rootCommandName, actionCommand) {
     // evidence that we cannot tell. Treating it as "not a tree" would grant the
     // full mutating command set to a snapshot on the strength of a file that
     // failed to parse, which is exactly backwards for a default-deny guard.
+    // A marker from a NEWER FireForge is not damaged, so the corrupt branch's
+    // remedies — recreate the tree, delete the stray marker — are actively
+    // wrong for it. Refuse with the upgrade instruction instead, and do NOT
+    // offer --ignore-corrupt-tree-marker: proceeding would mean acting on a
+    // marker whose fields this build does not understand.
+    if (state.kind === 'unsupported') {
+        if (TREE_COMMAND_VERDICTS[commandName] === 'allowed')
+            return;
+        throw new GeneralError(`Refusing "${[commandName, ...subcommands].join(' ')}": ${state.reason}`);
+    }
     if (state.kind === 'corrupt') {
         if (options['ignoreCorruptTreeMarker'] === true)
             return;

package/dist/src/core/tree-store.d.ts

@@ -33,13 +33,13 @@ export declare function withTreeLifecycleLock<T>(primaryRoot: string, operation:
  * Outcome of reading a tree marker.
  *
  * The three states must stay distinct because they carry opposite safety
- * meanings. `absent` means "this directory is not a tree", which is what lets
- * every mutating command run. `corrupt` means "this directory claims to be a
- * tree but we cannot read the claim" — collapsing it into `absent` (as a bare
- * `undefined` return does) hands a snapshot the full mutating command set on
- * the strength of a file we failed to parse, inverting `tree-guard.ts`'s
- * default-deny design. Deleting one field from a marker was enough to run
- * `reset` inside a clone.
+ * meanings. `absent` means "this directory is not a tree", which is what
+ * lets every mutating command run. `corrupt` means "this directory claims to
+ * be a tree but we cannot read the claim" — collapsing it into `absent` (as
+ * a bare `undefined` return does) hands a snapshot the full mutating command
+ * set on the strength of a file we failed to parse, inverting
+ * `tree-guard.ts`'s default-deny design. Deleting one field from a marker is
+ * enough to make `reset` runnable inside a clone.
  */
 export type TreeMarkerRead = {
     kind: 'absent';
@@ -49,31 +49,45 @@ export type TreeMarkerRead = {
 } | {
     kind: 'corrupt';
     reason: string;
+}
+/**
+ * Written by a NEWER FireForge. Distinct from `corrupt` because the remedy
+ * is the opposite: upgrade, do not delete.
+ */
+ | {
+    kind: 'unsupported';
+    reason: string;
 };
 /** Absolute path of a root's tree marker. */
 export declare function getTreeMarkerPath(root: string): string;
 /**
  * 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}.
+ * "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 tryReadTreeMarker}.
  *
  * 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.
+ * pre-check classifies a tree with an unreadable `.fireforge` as `absent`
+ * and hands it the full mutating command set.
  */
-export declare function readTreeMarkerState(root: string): Promise<TreeMarkerRead>;
+/**
+ * Naming convention for state-file readers:
+ *   - `readX(): Promise<XRead>` — the TRI-STATE read: absent, corrupt, or
+ *     valid.
+ *   - `tryReadX(): Promise<X | undefined>` — collapses absent and corrupt.
+ */
+export declare function readTreeMarker(root: string): Promise<TreeMarkerRead>;
 /**
  * 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`.
+ * proceed must call {@link readTreeMarker} and handle `corrupt`.
  */
-export declare function readTreeMarker(root: string): Promise<TreeMarker | undefined>;
+export declare function tryReadTreeMarker(root: string): Promise<TreeMarker | 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
@@ -92,18 +106,18 @@ export declare function computePrimaryFingerprint(primaryRoot: string): Promise<
 /** Validates a tree name: one path segment, no traversal. */
 export declare function assertValidTreeName(name: string): void;
 /**
- * Materialises the tree at `treeRoot` from `primaryRoot` using
- * `capability` ('none' = plain copy, already gated on --force-copy by
- * 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.
+ * Materialises the tree at `treeRoot` from `primaryRoot` using `capability`
+ * ('none' = plain copy, already gated on --force-copy by the caller).
+ *
+ * The engine is cloned one TOP-LEVEL entry at a time so unwanted `obj-*`
+ * directories are never traversed or materialised — on a Firefox tree, even
+ * CoW-cloning and then 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, 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 declare function cloneTree(args: {
     primaryRoot: string;

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

@@ -13,7 +13,7 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { lstat, readdir, readFile, realpath, rm } from 'node:fs/promises';
+import { cp, lstat, mkdir, 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';
@@ -26,6 +26,7 @@ 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 { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 import { cloneEntry } from './tree-cow.js';
 const TREE_MARKER_FILENAME = 'tree.json';
 const TREES_DIRNAME = 'trees';
@@ -56,16 +57,18 @@ export async function withTreeLifecycleLock(primaryRoot, operation) {
 /**
  * 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
+ * Checking only `schemaVersion` and `name` and asserting the rest is not
+ * enough: the unvalidated fields are consumed unguarded. `primaryRoot`
+ * reaches a user-facing refusal message in `tree-guard.ts`, and
  * `engineHead`/`patchesFingerprint` feed the staleness compare, where an
  * `undefined` from a truncated marker reports every tree as stale.
  */
+/** Schema version this build writes and understands. */
+const TREE_MARKER_SCHEMA_VERSION = 1;
 function isTreeMarker(value) {
     if (!isObject(value))
         return false;
-    return (value['schemaVersion'] === 1 &&
+    return (value['schemaVersion'] === TREE_MARKER_SCHEMA_VERSION &&
         typeof value['name'] === 'string' &&
         typeof value['primaryRoot'] === 'string' &&
         typeof value['createdAt'] === 'string' &&
@@ -82,20 +85,39 @@ export function getTreeMarkerPath(root) {
 }
 /**
  * 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}.
+ * "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 tryReadTreeMarker}.
  *
  * 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.
+ * pre-check classifies a tree with an unreadable `.fireforge` as `absent`
+ * and hands it the full mutating command set.
  */
-export async function readTreeMarkerState(root) {
+/**
+ * Naming convention for state-file readers:
+ *   - `readX(): Promise<XRead>` — the TRI-STATE read: absent, corrupt, or
+ *     valid.
+ *   - `tryReadX(): Promise<X | undefined>` — collapses absent and corrupt.
+ */
+export async function readTreeMarker(root) {
     const markerPath = getTreeMarkerPath(root);
     try {
         const raw = await readJson(markerPath);
+        // Version FIRST, and reported distinctly. Folding the schemaVersion
+        // check into `isTreeMarker` makes a marker from a NEWER FireForge read
+        // as "missing or mistypes a required field" — and `tree-guard.ts` is
+        // default-deny on corrupt, so the operator is locked out of every
+        // mutating command inside the tree by a message claiming the file is
+        // malformed when it is merely newer.
+        const version = checkDocumentVersion(raw, 'schemaVersion', TREE_MARKER_SCHEMA_VERSION);
+        if (version.kind === 'newer') {
+            return {
+                kind: 'unsupported',
+                reason: describeNewerDocument('tree marker', version.found, TREE_MARKER_SCHEMA_VERSION),
+            };
+        }
         if (!isTreeMarker(raw)) {
             verbose(`Malformed tree marker at ${markerPath}`);
             return { kind: 'corrupt', reason: 'the marker is missing or mistypes a required field' };
@@ -116,10 +138,10 @@ export async function readTreeMarkerState(root) {
  *
  * 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`.
+ * proceed must call {@link readTreeMarker} and handle `corrupt`.
  */
-export async function readTreeMarker(root) {
-    const state = await readTreeMarkerState(root);
+export async function tryReadTreeMarker(root) {
+    const state = await readTreeMarker(root);
     return state.kind === 'valid' ? state.marker : undefined;
 }
 /**
@@ -131,7 +153,7 @@ export async function readTreeMarker(root) {
  * 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);
+    const state = await readTreeMarker(projectRoot);
     if (state.kind !== 'valid' || state.marker.clonedObjdir === undefined)
         return;
     if (objDir !== state.marker.clonedObjdir) {
@@ -235,22 +257,21 @@ async function assertCloneSafeObjdir(engineDir, objDir, role) {
     }
 }
 /**
- * Materialises the tree at `treeRoot` from `primaryRoot` using
- * `capability` ('none' = plain copy, already gated on --force-copy by
- * 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.
+ * Materialises the tree at `treeRoot` from `primaryRoot` using `capability`
+ * ('none' = plain copy, already gated on --force-copy by the caller).
+ *
+ * The engine is cloned one TOP-LEVEL entry at a time so unwanted `obj-*`
+ * directories are never traversed or materialised — on a Firefox tree, even
+ * CoW-cloning and then 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, 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, withObjdir } = args;
-    const { mkdir, cp } = await import('node:fs/promises');
     if (withObjdir) {
         // Refuse a symlinked/escaping primary objdir BEFORE any copying: the
         // clone would carry the symlink and every later write would land in
@@ -303,7 +324,7 @@ export async function cloneTree(args) {
     }
     const { engineHead, engineFingerprint, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
     const marker = {
-        schemaVersion: 1,
+        schemaVersion: TREE_MARKER_SCHEMA_VERSION,
         name,
         primaryRoot,
         createdAt,
@@ -352,7 +373,7 @@ export async function listTrees(primaryRoot) {
         if (name.endsWith('.lock'))
             continue;
         const path = join(treesDir, name);
-        const marker = await readTreeMarker(path);
+        const marker = await tryReadTreeMarker(path);
         if (!marker) {
             entries.push({ name, path, createdAt: '(no marker)', staleness: 'unknown' });
             continue;
@@ -376,19 +397,19 @@ export async function listTrees(primaryRoot) {
  * 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.
+ * as alive. Returning `false` for EPERM lets a tree whose build lock is held
+ * by a live process running under a different uid pass the guard below and
+ * get `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.
+ * The `unknown` state is not theoretical. `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` lets `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 inspectTreeLock(lockPath) {
     if (!existsSync(lockPath))

package/dist/src/core/typecheck-shim.d.ts

@@ -40,13 +40,12 @@ export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harne
 export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
- * suppression let a module reference a name with no import or declaration
- * anywhere and still typecheck with 0 errors — the failure then surfaced
- * as a runtime `ReferenceError`. Both flows now report these at a
- * configurable severity (default `'warning'`: visible without breaking
- * gates; genuine shim gaps are silenced by adding the global to
- * `extraShim`, or per-run via the `'off'` setting).
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Suppressing them unconditionally lets
+ * a module reference a name with no import or declaration anywhere and still
+ * typecheck with 0 errors, so the failure surfaces as a runtime
+ * `ReferenceError`. Both flows report these at a configurable severity
+ * (default `'warning'`: visible without breaking gates; genuine shim gaps
+ * are silenced by adding the global to `extraShim`, or per-run via `'off'`).
  */
 export declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
 /** Hint appended to reported undefined-identifier diagnostics. */
@@ -61,25 +60,25 @@ export interface ComposedShim {
     extraShimAppended: boolean;
 }
 /**
- * Composes the synthetic shim source by concatenating the built-in
- * Firefox globals shim with the contents of an optional user-supplied
- * `.d.ts` file. The user file is appended verbatim — the augment
- * direction is intentional (declarations later in concat order
- * augment earlier ones), so a project that wants to refine `Services`
- * with a more specific type can do so by declaring it in the extra
- * shim, and members can be ADDED to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
- * see the module doc comment). Any triple-slash
- * `/// <reference path="…">` directives inside the
- * extra shim are inlined (resolved against the extra shim's own directory)
- * so they are not silently dropped at the synthetic shim path.
+ * Composes the synthetic shim source by concatenating the built-in Firefox
+ * globals shim with the contents of an optional user-supplied `.d.ts` file.
+ * The user file is appended verbatim — the augment direction is intentional
+ * (declarations later in concat order augment earlier ones), so a project
+ * that wants to refine `Services` with a more specific type can do so in the
+ * extra shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` — see
+ * the module doc comment). Any triple-slash `/// <reference path="…">`
+ * directives inside the extra shim are inlined (resolved against the extra
+ * shim's own directory) so they are not silently dropped at the synthetic
+ * shim path.
  *
- * Missing extra-shim files raise a clear error rather than failing
- * silently with a confusing "type not found" downstream — this is the
- * one config-driven path where a user typo in `fireforge.json`
- * produces a runtime error, so it needs to be unmistakable.
+ * Missing extra-shim files raise a clear error rather than failing silently
+ * with a confusing "type not found" downstream — this is the one
+ * config-driven path where a user typo in `fireforge.json` produces a
+ * runtime error, so it needs to be unmistakable.
  *
- * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param projectRoot - Absolute project root, used to resolve the relative
+ *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined): Promise<ComposedShim>;

package/dist/src/core/typecheck-shim.js

@@ -189,13 +189,12 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
 ]);
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
- * suppression let a module reference a name with no import or declaration
- * anywhere and still typecheck with 0 errors — the failure then surfaced
- * as a runtime `ReferenceError`. Both flows now report these at a
- * configurable severity (default `'warning'`: visible without breaking
- * gates; genuine shim gaps are silenced by adding the global to
- * `extraShim`, or per-run via the `'off'` setting).
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Suppressing them unconditionally lets
+ * a module reference a name with no import or declaration anywhere and still
+ * typecheck with 0 errors, so the failure surfaces as a runtime
+ * `ReferenceError`. Both flows report these at a configurable severity
+ * (default `'warning'`: visible without breaking gates; genuine shim gaps
+ * are silenced by adding the global to `extraShim`, or per-run via `'off'`).
  */
 export const UNDEFINED_IDENTIFIER_CODES = new Set([
     2304, // Cannot find name '{0}'.
@@ -242,25 +241,25 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
     return out.join('\n');
 }
 /**
- * Composes the synthetic shim source by concatenating the built-in
- * Firefox globals shim with the contents of an optional user-supplied
- * `.d.ts` file. The user file is appended verbatim — the augment
- * direction is intentional (declarations later in concat order
- * augment earlier ones), so a project that wants to refine `Services`
- * with a more specific type can do so by declaring it in the extra
- * shim, and members can be ADDED to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
- * see the module doc comment). Any triple-slash
- * `/// <reference path="…">` directives inside the
- * extra shim are inlined (resolved against the extra shim's own directory)
- * so they are not silently dropped at the synthetic shim path.
+ * Composes the synthetic shim source by concatenating the built-in Firefox
+ * globals shim with the contents of an optional user-supplied `.d.ts` file.
+ * The user file is appended verbatim — the augment direction is intentional
+ * (declarations later in concat order augment earlier ones), so a project
+ * that wants to refine `Services` with a more specific type can do so in the
+ * extra shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` — see
+ * the module doc comment). Any triple-slash `/// <reference path="…">`
+ * directives inside the extra shim are inlined (resolved against the extra
+ * shim's own directory) so they are not silently dropped at the synthetic
+ * shim path.
  *
- * Missing extra-shim files raise a clear error rather than failing
- * silently with a confusing "type not found" downstream — this is the
- * one config-driven path where a user typo in `fireforge.json`
- * produces a runtime error, so it needs to be unmistakable.
+ * Missing extra-shim files raise a clear error rather than failing silently
+ * with a confusing "type not found" downstream — this is the one
+ * config-driven path where a user typo in `fireforge.json` produces a
+ * runtime error, so it needs to be unmistakable.
  *
- * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param projectRoot - Absolute project root, used to resolve the relative
+ *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export async function composeShimSource(projectRoot, extraShimPath) {

package/dist/src/core/typecheck.js

@@ -89,8 +89,8 @@ export async function runTypecheck(projectRoot, cfg) {
     // override (a path, or `null` to opt out) when present, else the shared
     // top-level extraShim. A project that narrows `lib`/`types` can opt out of
     // a Gecko-lib shim hub that another project needs, so the composed shim is
-    // no longer injected identically everywhere. Compositions are cached by the
-    // resolved extraShim path so projects sharing a shim don't recompose it.
+    // not injected identically everywhere. Compositions are cached by the
+    // resolved extraShim path so projects sharing a shim do not recompose it.
     const shimCache = new Map();
     const composeForProject = async (extraShim) => {
         const key = extraShim ?? '';
@@ -222,12 +222,12 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         noEmit: true,
         allowJs: parsed.options.allowJs ?? true,
         checkJs: parsed.options.checkJs ?? true,
-        // No incremental sidecar, ever. A user jsconfig under `engine/` that
-        // sets `incremental` (or names a `tsBuildInfoFile`)
-        // would have this command drop a `.tsbuildinfo` inside the primary
-        // engine checkout — a second writer that invalidates a concurrent
-        // `fireforge test`'s engine fingerprint. This command emits nothing,
-        // so the sidecar buys nothing either.
+        // No incremental sidecar, ever. A user jsconfig under `engine/` that sets
+        // `incremental` (or names a `tsBuildInfoFile`) would have this command
+        // drop a `.tsbuildinfo` inside the primary engine checkout — a second
+        // writer that invalidates a concurrent `fireforge test`'s engine
+        // fingerprint. This command emits nothing, so the sidecar buys nothing
+        // either.
         incremental: false,
         // skipLibCheck is not forced; the user owns it via their jsconfig.
     };