@hominis/fireforge 0.40.0 → 0.42.0

package/dist/src/core/coverage-extend.js

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `test --build/--build-only --extend-coverage` (FORGE L1): unions the
+ * requested paths into the recorded `testPackagingCoverage` instead of
+ * replacing it, under an anchor guard.
+ *
+ * Coverage REPLACES by default for a documented reason
+ * (`build-baseline-types.ts`): every baseline write refreshes
+ * `packageableFingerprints` for ALL dirty packageable paths, so a blind
+ * union would whitewash an earlier scope's edited fixtures while
+ * `obj-*`/`_tests/` still holds that scope's stale staging. Extending is
+ * honest only while everything the PREVIOUS record vouched for is still
+ * true, which is what {@link checkExtendCoverageAnchor} and
+ * {@link checkExtendMozconfigAnchor} verify:
+ *
+ *   1. engine HEAD is unchanged — every committed edit is excluded;
+ *   2. every path the previous baseline fingerprinted still hashes to the
+ *      recorded digest — the earlier scope's staging inputs are byte-identical.
+ *      Files that became dirty SINCE that build are fine: the current
+ *      whole-tree `mach build faster` repackages `dist/` and vouches for them;
+ *   3. the generated `engine/mozconfig` is unchanged. Engine HEAD does not
+ *      cover this — the mozconfig is regenerated from project-side
+ *      `configs/*.mozconfig` templates plus `fireforge.json` on every build,
+ *      so two builds at the same engine SHA can configure differently.
+ *
+ * Every failure refuses fail-closed; the operator's remedy is always a plain
+ * scoped build, which resets the claim to the paths it actually vouches for.
+ *
+ * Known boundary, documented rather than closed: dirty NON-packageable
+ * fixtures under previously covered paths (plain test files, manifests
+ * `isPackageablePath` rejects) are invisible to check 2. Editing one
+ * uncommitted between two builds leaves the earlier scope's `_tests/`
+ * staging stale while extend still vouches for it. Plain REPLACE has no
+ * such window, because the earlier scope simply stops being covered.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
+import { getHead, isMissingHeadError } from './git.js';
+/** Filename of the generated mozconfig, relative to the engine directory. */
+const MOZCONFIG_FILENAME = 'mozconfig';
+/** How many diverged paths a refusal names before truncating. */
+const MAX_DIVERGED_REPORTED = 5;
+/**
+ * Verifies the parts of the anchor knowable before the build runs: a usable
+ * previous baseline, an unchanged engine HEAD, and byte-identical content
+ * for every path that baseline fingerprinted.
+ * @param engineDir - Path to the engine directory
+ * @param previousBaseline - Baseline recorded by the previous build
+ */
+export async function checkExtendCoverageAnchor(engineDir, previousBaseline) {
+    if (previousBaseline === undefined) {
+        return { ok: false, reason: 'no-baseline', detail: [] };
+    }
+    if (previousBaseline.mozconfigHash === undefined) {
+        return { ok: false, reason: 'no-mozconfig-hash', detail: [] };
+    }
+    const recordedFingerprints = previousBaseline.packageableFingerprints;
+    if (recordedFingerprints === undefined) {
+        return { ok: false, reason: 'no-fingerprints', detail: [] };
+    }
+    const currentHead = await readEngineHead(engineDir);
+    if (currentHead === undefined || previousBaseline.engineHeadSha === '') {
+        // An unborn or unreadable HEAD gives nothing to anchor to.
+        return { ok: false, reason: 'head-moved', detail: [] };
+    }
+    if (currentHead !== previousBaseline.engineHeadSha) {
+        return {
+            ok: false,
+            reason: 'head-moved',
+            detail: [`recorded ${previousBaseline.engineHeadSha}`, `current ${currentHead}`],
+        };
+    }
+    const diverged = [];
+    for (const [relPath, recordedHash] of Object.entries(recordedFingerprints)) {
+        const liveHash = await hashEngineFile(engineDir, relPath);
+        if (liveHash !== recordedHash)
+            diverged.push(relPath);
+    }
+    if (diverged.length > 0) {
+        return { ok: false, reason: 'fingerprint-diverged', detail: diverged.sort() };
+    }
+    return { ok: true };
+}
+/**
+ * Verifies the mozconfig half of the anchor. Split from
+ * {@link checkExtendCoverageAnchor} because it can only run AFTER
+ * `prepareBuildEnvironment` regenerates `engine/mozconfig` — that file is
+ * the one this build will configure with — and must still run BEFORE mach,
+ * so a refusal costs no build time.
+ * @param engineDir - Path to the engine directory
+ * @param previousBaseline - Baseline recorded by the previous build
+ */
+export async function checkExtendMozconfigAnchor(engineDir, previousBaseline) {
+    const recorded = previousBaseline?.mozconfigHash;
+    if (recorded === undefined) {
+        return { ok: false, reason: 'no-mozconfig-hash', detail: [] };
+    }
+    const live = await hashEngineFile(engineDir, MOZCONFIG_FILENAME);
+    if (live === undefined || live !== recorded) {
+        return { ok: false, reason: 'mozconfig-changed', detail: [] };
+    }
+    return { ok: true };
+}
+/**
+ * Unions the newly built paths onto the recorded claim. A `'full'` claim
+ * (or a pre-0.37.0 absent one, which means full historically) stays
+ * `'full'` — it already covers everything.
+ * @param previous - Coverage recorded by the previous build
+ * @param requested - Normalized request paths this build packaged
+ */
+export function unionTestPackagingCoverage(previous, requested) {
+    if (previous === undefined || previous === 'full') {
+        return 'full';
+    }
+    return [...new Set([...previous, ...requested])].sort();
+}
+/**
+ * Renders the fail-closed refusal for an anchor check that did not pass.
+ * Kept separate from the probes so tests can assert the structured result
+ * without matching copy.
+ * @param result - Failing result from an anchor check
+ */
+export function formatExtendCoverageRefusal(result) {
+    const remedy = 'Re-run without --extend-coverage: a plain scoped build REPLACES the coverage claim ' +
+        'with the paths it actually vouches for.';
+    switch (result.reason) {
+        case 'no-baseline':
+            return `--extend-coverage has nothing to extend: no previous build baseline is recorded. ${remedy}`;
+        case 'no-mozconfig-hash':
+            return ('--extend-coverage refused: the recorded baseline predates the mozconfig anchor, so it ' +
+                `cannot be proven that this build configures identically. ${remedy}`);
+        case 'no-fingerprints':
+            return ('--extend-coverage refused: the recorded baseline carries no packageable fingerprints, so ' +
+                `the earlier scope's staging inputs cannot be verified unchanged. ${remedy}`);
+        case 'head-moved':
+            return ('--extend-coverage refused: engine HEAD moved since the recorded build ' +
+                `(${result.detail.join(', ') || 'no usable HEAD'}), so the earlier scope's packaging is no ` +
+                `longer anchored. ${remedy}`);
+        case 'fingerprint-diverged':
+            return ('--extend-coverage refused: ' +
+                `${String(result.detail.length)} packageable file(s) the recorded build staged have changed ` +
+                `since (${formatDivergedPaths(result.detail)}). Extending would vouch for the earlier scope ` +
+                `while obj-*/_tests/ still holds its stale staging. ${remedy}`);
+        case 'mozconfig-changed':
+            return ('--extend-coverage refused: engine/mozconfig differs from the recorded build (it is ' +
+                'regenerated from configs/*.mozconfig and fireforge.json on every build, so engine HEAD ' +
+                `does not cover it). ${remedy}`);
+    }
+}
+function formatDivergedPaths(paths) {
+    const head = paths.slice(0, MAX_DIVERGED_REPORTED).join(', ');
+    const extra = paths.length - Math.min(paths.length, MAX_DIVERGED_REPORTED);
+    return extra > 0 ? `${head}, … (+${String(extra)} more)` : head;
+}
+/**
+ * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
+ * baseline writer produces. `undefined` on any IO error, which every caller
+ * treats as "cannot prove unchanged" — i.e. a refusal.
+ * @param engineDir - Path to the engine directory
+ * @param relPath - Engine-relative POSIX path
+ */
+export async function hashEngineFile(engineDir, relPath) {
+    try {
+        const buffer = await readFile(join(engineDir, relPath));
+        return createHash('sha256').update(buffer).digest('hex');
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT') {
+            return DELETED_FILE_FINGERPRINT;
+        }
+        verbose(`Extend-coverage anchor: could not hash ${relPath} — ${toError(error).message}`);
+        return undefined;
+    }
+}
+async function readEngineHead(engineDir) {
+    try {
+        return await getHead(engineDir);
+    }
+    catch (error) {
+        if (isMissingHeadError(error))
+            return undefined;
+        throw error;
+    }
+}

package/dist/src/core/destructive.js

@@ -109,7 +109,9 @@ export async function confirmDestructive(input) {
         message: `${title} — proceed?`,
         initialValue: false,
     });
-    if (isCancel(confirmed) || confirmed !== true) {
+    // `isCancel` narrows the clack sentinel away, leaving a plain boolean —
+    // the defensive `!== true` this replaced is now provably redundant.
+    if (isCancel(confirmed) || !confirmed) {
         return 'cancelled';
     }
     return 'proceed';

package/dist/src/core/discard-baseline.js

@@ -20,7 +20,7 @@ import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { readText, removeFile, writeText } from '../utils/fs.js';
 import { discardStatusEntry, fileExistsInHead, listTrackedInHead, restoreTrackedPath, unstageFiles, } from './git-file-ops.js';
-import { createPatchedContentComputer } from './patch-apply.js';
+import { createPatchedContentContext } from './patch-apply.js';
 import { loadPatchesManifestState } from './patch-manifest-io.js';
 import { parseDiffSections } from './patch-parse.js';
 import { buildPatchClaims } from './status-classify.js';
@@ -53,7 +53,7 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
     if (claimedEntries.length === 0) {
         return planUpstreamDiscards(entries);
     }
-    const computePatched = await createPatchedContentComputer(patchesDir, engineDir);
+    const { computePatched } = await createPatchedContentContext(patchesDir, engineDir);
     const claimedFiles = [
         ...new Set(claimedEntries.flatMap((entry) => entry.originalPath !== undefined ? [entry.file, entry.originalPath] : [entry.file])),
     ];
@@ -84,8 +84,22 @@ export async function planDiscardBaselines(patchesDir, engineDir, entries) {
                 try {
                     sections = parseDiffSections(await readText(join(patchesDir, owner)));
                 }
-                catch {
-                    sections = [];
+                catch (error) {
+                    // Fail closed. Swallowing this yielded no sections, which falls
+                    // through to `return false` — "not deleted at baseline" — so a path
+                    // the owning patch DELETES would be restored as present, i.e.
+                    // rewritten instead of removed: silent data loss on the command
+                    // whose header promises a refusal for exactly this class of failure.
+                    //
+                    // In the current flow `computeExpected` above reads the same patch
+                    // first and refuses, so this is defence-in-depth against a TOCTOU
+                    // (the patch file removed or made unreadable mid-plan) rather than a
+                    // reachable branch today. It refuses with the same remediation as
+                    // its sibling so the two cannot drift into disagreeing.
+                    throw new GeneralError(`Cannot read the owning patch ${owner} to determine the baseline for ${path} ` +
+                        `(${toError(error).message}). ` +
+                        'Fix the owning patch, or pass --to-upstream to explicitly revert to pristine ' +
+                        'upstream (HEAD).');
                 }
                 sectionCache.set(owner, sections);
             }

package/dist/src/core/engine-precondition.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared engine precondition ladder for commands that read or mutate
+ * `engine/` through git.
+ *
+ * Five commands carried their own copy of this three-rung check, and **two of
+ * them were truncated**: `resolve.ts` and `token-coverage.ts` stopped after
+ * the `isGitRepository` rung and omitted the unborn-HEAD guard entirely
+ * (neither even imported `getHead`/`isMissingHeadError`). Both then went on to
+ * enumerate working-tree status, and against an unborn HEAD the whole
+ * ~300k-file Firefox tree reads as untracked — so an engine left half
+ * initialised by an interrupted `download` produced a nonsensical result
+ * rather than the actionable refusal the other three commands gave.
+ *
+ * The remediation paragraph also existed in three independently-editable
+ * copies that had already drifted. It lives here once now.
+ */
+/** Options for {@link assertEngineGitReady}. */
+export interface EngineGitReadyOptions {
+    /**
+     * Appended to the unborn-HEAD remediation, e.g. `', then retry the rebase.'`
+     * Preserves the one deliberate wording divergence between the copies. The
+     * base message deliberately ends WITHOUT punctuation so the suffix reads as
+     * one sentence; callers that pass nothing get a plain full stop.
+     */
+    unbornHeadSuffix?: string;
+}
+/**
+ * Asserts that `engineDir` exists, is a git repository, and has a baseline
+ * commit — in that order, so the operator gets the most specific applicable
+ * remediation rather than a downstream git error.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Optional per-command message tailoring
+ */
+export declare function assertEngineGitReady(engineDir: string, options?: EngineGitReadyOptions): Promise<void>;

package/dist/src/core/engine-precondition.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared engine precondition ladder for commands that read or mutate
+ * `engine/` through git.
+ *
+ * Five commands carried their own copy of this three-rung check, and **two of
+ * them were truncated**: `resolve.ts` and `token-coverage.ts` stopped after
+ * the `isGitRepository` rung and omitted the unborn-HEAD guard entirely
+ * (neither even imported `getHead`/`isMissingHeadError`). Both then went on to
+ * enumerate working-tree status, and against an unborn HEAD the whole
+ * ~300k-file Firefox tree reads as untracked — so an engine left half
+ * initialised by an interrupted `download` produced a nonsensical result
+ * rather than the actionable refusal the other three commands gave.
+ *
+ * The remediation paragraph also existed in three independently-editable
+ * copies that had already drifted. It lives here once now.
+ */
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { getHead, isGitRepository, isMissingHeadError } from './git.js';
+/** Remediation for an engine whose baseline commit was never created. */
+const UNBORN_HEAD_REMEDIATION = 'Engine repository has no baseline commit yet — a previous "fireforge download" was ' +
+    'interrupted before git created the initial Firefox source commit. ' +
+    // No terminating period: the suffix below supplies its own punctuation, and
+    // hardcoding one here rendered as "…cleanly., then retry the rebase."
+    'Re-run "fireforge download --force" to recreate the baseline repository cleanly';
+/**
+ * Asserts that `engineDir` exists, is a git repository, and has a baseline
+ * commit — in that order, so the operator gets the most specific applicable
+ * remediation rather than a downstream git error.
+ *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Optional per-command message tailoring
+ */
+export async function assertEngineGitReady(engineDir, options = {}) {
+    if (!(await pathExists(engineDir))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(engineDir))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    try {
+        await getHead(engineDir);
+    }
+    catch (headError) {
+        if (!isMissingHeadError(headError))
+            throw headError;
+        throw new GeneralError(`${UNBORN_HEAD_REMEDIATION}${options.unbornHeadSuffix ?? '.'}`);
+    }
+}

package/dist/src/core/engine-session-lock.d.ts

@@ -8,14 +8,51 @@ export interface EngineSessionLockOptions {
     waitLockSeconds?: number | undefined;
 }
 /**
- *
+ * Runs `operation` while holding the project's engine-session lock, so only
+ * one engine-mutating FireForge command touches `engine/` at a time.
  */
 export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
+ * Captures an opaque token describing the engine's current commit and working
+ * tree, for comparison by {@link assertEngineGenerationUnchanged}.
  *
+ * A failed probe yields a failure token. Callers must branch on
+ * {@link isUnavailableGenerationToken} rather than comparing the token,
+ * because a probe failure means "nothing was measured", not "nothing changed".
  */
 export declare function snapshotEngineGeneration(engineDir: string): Promise<string>;
 /**
+ * True when a generation token records a failed probe — i.e. nothing was
+ * measured, so the token must never be compared (or hashed) as if it
+ * described the engine's state.
+ */
+export declare function isUnavailableGenerationToken(token: string): boolean;
+/** Strips the marker prefix off an unavailable token for display. */
+export declare function unavailableGenerationReason(token: string): string;
+/**
+ * Throws when the engine's generation token differs from `before`, i.e. the
+ * engine was mutated by another writer while a test run was in flight.
+ *
+ * **An unmeasurable engine warns rather than throws.** `engine/` is not always
+ * a git checkout — `fireforge download` extracts a source tarball — so a
+ * failed probe is a legitimate state and must not fail the run.
+ *
+ * What it must also not do is pass *silently*. Before 0.41.0 the failure token
+ * was `unavailable:<message>` and was compared for equality like any other, so
+ * a git failure that reproduced across both probes (unreadable `.git`, a
+ * permissions problem, a corrupt index) produced identical tokens, took the
+ * `after === before` early return, and blessed a verdict the guard had never
+ * verified — the precise outcome this guard exists to prevent. Two *differing*
+ * failure messages were worse still: they fell through to the mutation branch
+ * and reported a spurious "engine/ changed".
  *
+ * The tolerance is deliberately limited to a probe that failed *both* times:
+ * that is the steady state of a non-git `engine/`, and it warns. A one-sided
+ * transition is not that state. `engine/` that was measurable and then was not
+ * means the second probe measured nothing about a checkout that demonstrably
+ * had something to measure; the reverse means there was never a baseline to
+ * compare against. Neither is a run whose verdict can be trusted, so both
+ * throw. Compare on the prefix rather than the token, because the token embeds
+ * the error message and two genuine failures rarely phrase it identically.
  */
 export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
-import { info } from '../utils/logger.js';
+import { toError } from '../utils/errors.js';
+import { info, warn } from '../utils/logger.js';
 import { withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
@@ -20,9 +21,16 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
     return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
 }
 /**
- *
+ * Runs `operation` while holding the project's engine-session lock, so only
+ * one engine-mutating FireForge command touches `engine/` at a time.
  */
 export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
+    // The lock is bypassed under test by default, and that is deliberate: the
+    // suite runs many engine-mutating commands in-process, which would either
+    // serialise on this lock or deadlock outright.
+    // `FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST=1` is what lets the lock's
+    // own tests opt back in. Do not delete this branch — it is the reason the
+    // suite completes, not an oversight.
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
         return operation();
@@ -41,13 +49,26 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
             }
             : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
+        // Reason first, remedy second (FORGE H5) — the no-flag default waits
+        // only ~1 s, so contention is the common case and `--wait-lock` is the
+        // genuine remedy. withFileLock appends the holder identification from
+        // the lock's owner metadata. The leading sentence is a message contract
+        // (pinned by engine-session-lock tests); extend, don't reword.
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
-            `Wait for it to finish, then retry \`${command}\`.`,
+            `Wait for it to finish, then retry \`${command}\` — or pass --wait-lock [seconds] ` +
+            `to wait for the lock (bare --wait-lock waits up to 60 seconds).`,
         onStaleLockMessage: (ageMs) => `Removed stale FireForge engine session lock (${Math.round(ageMs / 1000)}s old).`,
     });
 }
+/** Prefix marking a generation token whose probe failed. */
+const UNAVAILABLE_PREFIX = 'unavailable:';
 /**
+ * Captures an opaque token describing the engine's current commit and working
+ * tree, for comparison by {@link assertEngineGenerationUnchanged}.
  *
+ * A failed probe yields a failure token. Callers must branch on
+ * {@link isUnavailableGenerationToken} rather than comparing the token,
+ * because a probe failure means "nothing was measured", not "nothing changed".
  */
 export async function snapshotEngineGeneration(engineDir) {
     try {
@@ -56,14 +77,67 @@ export async function snapshotEngineGeneration(engineDir) {
         return `${head}\0${status}`;
     }
     catch (error) {
-        return `unavailable:${error instanceof Error ? error.message : String(error)}`;
+        return `${UNAVAILABLE_PREFIX}${toError(error).message}`;
     }
 }
 /**
+ * True when a generation token records a failed probe — i.e. nothing was
+ * measured, so the token must never be compared (or hashed) as if it
+ * described the engine's state.
+ */
+export function isUnavailableGenerationToken(token) {
+    return token.startsWith(UNAVAILABLE_PREFIX);
+}
+/** Strips the marker prefix off an unavailable token for display. */
+export function unavailableGenerationReason(token) {
+    return token.slice(UNAVAILABLE_PREFIX.length);
+}
+/**
+ * Throws when the engine's generation token differs from `before`, i.e. the
+ * engine was mutated by another writer while a test run was in flight.
  *
+ * **An unmeasurable engine warns rather than throws.** `engine/` is not always
+ * a git checkout — `fireforge download` extracts a source tarball — so a
+ * failed probe is a legitimate state and must not fail the run.
+ *
+ * What it must also not do is pass *silently*. Before 0.41.0 the failure token
+ * was `unavailable:<message>` and was compared for equality like any other, so
+ * a git failure that reproduced across both probes (unreadable `.git`, a
+ * permissions problem, a corrupt index) produced identical tokens, took the
+ * `after === before` early return, and blessed a verdict the guard had never
+ * verified — the precise outcome this guard exists to prevent. Two *differing*
+ * failure messages were worse still: they fell through to the mutation branch
+ * and reported a spurious "engine/ changed".
+ *
+ * The tolerance is deliberately limited to a probe that failed *both* times:
+ * that is the steady state of a non-git `engine/`, and it warns. A one-sided
+ * transition is not that state. `engine/` that was measurable and then was not
+ * means the second probe measured nothing about a checkout that demonstrably
+ * had something to measure; the reverse means there was never a baseline to
+ * compare against. Neither is a run whose verdict can be trusted, so both
+ * throw. Compare on the prefix rather than the token, because the token embeds
+ * the error message and two genuine failures rarely phrase it identically.
  */
 export async function assertEngineGenerationUnchanged(engineDir, before) {
     const after = await snapshotEngineGeneration(engineDir);
+    const beforeUnavailable = isUnavailableGenerationToken(before);
+    const afterUnavailable = isUnavailableGenerationToken(after);
+    if (beforeUnavailable && afterUnavailable) {
+        warn('Could not verify that engine/ stayed unchanged while the tests ran ' +
+            `(${unavailableGenerationReason(after)}). If another writer touched engine/ during the run, ` +
+            'this verdict is stale.');
+        return;
+    }
+    if (beforeUnavailable || afterUnavailable) {
+        const detail = beforeUnavailable
+            ? `engine/ could not be probed before the run (${unavailableGenerationReason(before)}) but could be ` +
+                'probed afterwards, so there is no baseline to compare against.'
+            : `engine/ was probed before the run but could not be probed afterwards ` +
+                `(${unavailableGenerationReason(after)}), so nothing was measured to compare against.`;
+        throw new GeneralError(`${detail}\n\n` +
+            'This test verdict is inconclusive. Restore engine/ to a readable state, then rebuild ' +
+            'and rerun the affected tests.');
+    }
     if (after === before)
         return;
     throw new GeneralError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +

package/dist/src/core/file-lock.d.ts

@@ -48,5 +48,12 @@ export interface FileLockOptions {
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
+/**
+ * Filename of a lock directory's owner record, relative to the lock dir.
+ *
+ * Exported so external readers (`tree-store.ts`) share the constant instead of
+ * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
+ */
+export declare const LOCK_PID_FILE = "pid";
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;

package/dist/src/core/file-lock.js

@@ -2,7 +2,8 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import { toError } from '../utils/errors.js';
+import { LockContentionError } from '../errors/base.js';
+import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
@@ -22,33 +23,17 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
-function getNodeErrorCode(error) {
-    if (typeof error === 'object' &&
-        error !== null &&
-        'code' in error &&
-        typeof error.code === 'string') {
-        return error.code;
-    }
-    return undefined;
-}
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
-const LOCK_PID_FILE = 'pid';
 /**
- * Checks whether a process with the given PID is still running.
- * Uses `kill(pid, 0)` which sends no signal but checks existence.
+ * Filename of a lock directory's owner record, relative to the lock dir.
+ *
+ * Exported so external readers (`tree-store.ts`) share the constant instead of
+ * re-spelling `'pid'`; the file *format* is documented on {@link readLockOwner}.
  */
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return getNodeErrorCode(error) !== 'ESRCH';
-    }
-}
+export const LOCK_PID_FILE = 'pid';
 /**
  * Reads the owner PID (line 1), acquisition token (line 2), and diagnostic
  * metadata (lines 3+, see {@link FileLockOptions.ownerMetadata}) from a lock
@@ -242,12 +227,7 @@ export async function withFileLock(lockPath, operation, options = {}) {
             break;
         }
         catch (error) {
-            const isAlreadyLocked = typeof error === 'object' &&
-                error !== null &&
-                'code' in error &&
-                typeof error.code === 'string' &&
-                error.code === 'EEXIST';
-            if (!isAlreadyLocked) {
+            if (getNodeErrorCode(error) !== 'EEXIST') {
                 throw error;
             }
             if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
@@ -259,9 +239,19 @@ export async function withFileLock(lockPath, operation, options = {}) {
             if (Date.now() >= deadline) {
                 const owner = await readLockOwner(lockPath);
                 const holderHint = owner.present && isProcessAlive(owner.pid)
-                    ? ` It is held by running process ${String(owner.pid)} — wait for it to finish, or stop it and retry.`
+                    ? ` It is held by running process ${String(owner.pid)}${owner.metadata.length > 0 ? ` (${owner.metadata.join(', ')})` : ''} — wait for it to finish, or stop it and retry.`
                     : ' If no other FireForge process is running, remove the lock directory and retry.';
-                throw new Error(options.onTimeoutMessage ?? `Timed out waiting for file lock ${lockPath}.${holderHint}`, { cause: error });
+                // Typed as LockContentionError (a FireForgeError) so the CLI
+                // boundary prints the refusal as one clean line instead of an
+                // "Unexpected error" stack (FORGE H5). Callers supplying
+                // onTimeoutMessage still get the holder identification appended —
+                // the reason-first copy stays theirs, the "who holds it" is ours.
+                const identifiedHolder = options.onTimeoutMessage !== undefined && owner.present && isProcessAlive(owner.pid)
+                    ? ` The lock is held by PID ${String(owner.pid)}${owner.metadata.length > 0 ? ` (${owner.metadata.join(', ')})` : ''}.`
+                    : '';
+                throw new LockContentionError(options.onTimeoutMessage !== undefined
+                    ? `${options.onTimeoutMessage}${identifiedHolder}`
+                    : `Timed out waiting for file lock ${lockPath}.${holderHint}`, error);
             }
             if (options.onWaitProgress !== undefined &&
                 options.waitProgressMs !== undefined &&

package/dist/src/core/firefox.js

@@ -8,6 +8,7 @@
 import { randomUUID } from 'node:crypto';
 import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { ensureDir, removeDir } from '../utils/fs.js';
 import { resolveArchive } from './firefox-archive.js';
 import { ensureCachedArchive, invalidateArchiveCache } from './firefox-cache.js';
@@ -43,8 +44,8 @@ export function getTarballFilename(version, product = 'firefox', candidate) {
  * genuinely bad archive can never survive in the cache.
  */
 function isLikelyArchiveCorruptionError(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const code = error instanceof Error ? error.code : undefined;
+    const message = toError(error).message;
+    const code = getNodeErrorCode(error);
     if (code === 'ENOSPC' || code === 'EACCES' || code === 'EPERM' || code === 'EDQUOT') {
         return false;
     }
@@ -81,6 +82,8 @@ export async function sweepOrphanedEngineWorkDirs(destDir) {
         entries = await readdir(parent);
     }
     catch {
+        // An unreadable parent directory holds no sweepable work dirs. The sweep is
+        // best-effort housekeeping and must never fail the download it follows.
         return [];
     }
     const removed = [];