@hominis/fireforge 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 0.41.0
+
+### Release and build integrity
+
+- Release publishing commits version bumps before building and enforces a clean tree with `FIREFORGE_PACK_STRICT=1`.
+- Builds stamp `dist/build-info.json`; installed `--version` output includes the commit and dirty-content hash.
+- Build baselines retain deletion tombstones, so removed packageable files and `components.conf` entries cannot look fresh.
+- `test --build` uses a full build for new `jar.mn` registrations; mixed-harness `--build-only` packages all requested paths once.
+- `--extend-coverage` unions scoped packaging coverage only while HEAD, packageable inputs, and `mozconfig` remain unchanged.
+- Shared build and engine preflights now reject incomplete builds and unborn engine repositories consistently.
+
+### Tests and verification trees
+
+- Tests emit exactly one final `FIREFORGE-VERDICT:` line with the correct pass/failure reason, including sharded, lock-timeout, crash, and inconclusive runs.
+- `tree exec` preserves the child verdict as the final stdout line; pre-spawn refusals emit no verdict.
+- Engine-integrity checks run before successful verdicts.
+- Browser preflight detects stale apps from the same objdir even after they release Marionette; `--kill-stale-marionette` can terminate them.
+- Mach commands use process groups and reap surviving browser or harness descendants.
+- `tree create --with-objdir` supports build-less tests after relocation and reconfiguration checks.
+- Tree creation refuses symlinked objdirs, cleans failed clones, validates markers, and handles unreadable locks fail-closed.
+- Tree freshness covers dirty engine content and patch bodies.
+- Tree creation skips unwanted `obj-*` directories before cloning and uses bounded concurrency.
+- `tree create --wait-lock` now matches its lock-refusal guidance.
+- Verification trees permit `re-export --dry-run`; mutating operations remain blocked.
+- Test assertion lint now recognizes real assertion calls, and critical modules have explicit coverage floors.
+
+### Status and diagnostics
+
+- Status classification reuses one patch context and classifies files through a bounded pool.
+- `status --json --summary` returns counts and offenders without the full file payload.
+- `status --json --include-ownership` adds ownership data without another scan.
+- JSON output drains fully through slow pipes, and machine-mode refusals route to stderr.
+- Multi-owner files remain conflicts even when Furnace-managed or generated branding paths.
+- Lock contention and unreadable/corrupt state now produce concise, accurate diagnostics.
+
+### Patch, export, and lint workflow
+
+- `export-all --exclude-furnace` keeps its filtered scope after license-header repair.
+- `re-export --expect <path>` permits intended drift and reports paths skipped by earlier refusals as not evaluated.
+- Missing drift baselines fail closed, binary patches compare by content, and partial or fully refused re-exports exit non-zero.
+- `re-export --dry-run` uses before/after fingerprints and cannot roll back another completed write.
+- Re-export builds checkJs once per run and reuses the per-patch cache; `--patches` subsets narrow computation.
+- Re-export probes and purity hashing use bounded concurrency; patch writes remain serial.
+- Patch lint rejects new imported system modules without a projected `moz.build` registration.
+- The checkJs cache hashes both configurable shims.
+- Export placement refusals print projected errors and identify renumbering consequences.
+- `patch rename` can recategorize and renumber atomically.
+- `patch move-files` and `patch split` use whole-queue projection lint, normalize names, and provide split guidance.
+- `patch move-files --create` names the required `--description` option.
+- Queue-mutating patch commands support `--wait-lock` and avoid unsafe stale-lock advice.
+- Staged-dependency declarations reject patch-name-shaped file arguments.
+- `CommandError` passes through the top-level handler without duplicate or JSON-corrupting output.
+
+### Furnace and validation
+
+- Furnace computes checksums once per apply and warns before overwriting divergent patch-owned files.
+- Furnace jsconfig synchronization includes `register: false` components.
+- Manifest-sync failures are visible, and repairs run under the Furnace lock.
+- `furnace validate --fix` changes only reported components and detects missing custom-element registrations.
+- Localization validation recognizes non-Latin text while exempting emoji and punctuation.
+- `furnace rename` uses single-pass, boundary-aware substitutions.
+- Rollback failures retain repair breadcrumbs for `doctor --repair-furnace`.
+- The reported no-change/apply-state disagreement was not reproducible and is regression-tested.
+
+### Safety, performance, and maintenance
+
+- Nano ID 3.3.18 resolves a high-severity audit finding.
+- Rebase loading distinguishes absent and corrupt sessions; `rebase --abort` can recover invalid state.
+- PID liveness treats `EPERM` as alive, preventing deletion through another user's lock.
+- The moz.build parser handles comments, quoted brackets/apostrophes, and unterminated lists.
+- Parser failures no longer silently certify validation success; internal invariant errors bypass fallback.
+- Toolchain probes, baseline fingerprints, cache hashes, and manifest reads use bounded concurrency.
+- Existing Git tuning remains enabled; fsmonitor stays disabled because of stale-daemon risk.
+- A persistent checkJs daemon remains deferred until safe invalidation is cheaper; see `docs/lint-daemon-design.md`.
+- Shared helpers replace duplicated preflights, error conversion, regex escaping, option parsing, object guards, and ESTree casts.
+- Four local ESLint rules prevent unsafe error casts, duplicate regex escaping, and empty JSDoc.
+- Oversized modules were split or simplified, silent degradations documented, and stale dead-code suppressions removed.
+- The release gate pins weak critical modules so aggregate coverage cannot hide local regressions.
+
 ## 0.40.0
 
 - **Dependencies: adopted all five open dependabot PRs (#48, #47, #45, #44, #42) after Go-based TypeScript 6 compatibility review** — the pinned `typescript ~6.0.0` (6.0.3 installed) constrained which upgrades were feasible; every bumped tool checked out: `typescript-eslint` declares peer `typescript >=4.8.4 <6.1.0`, `knip` carries no TypeScript dependency at all (oxc parser), and `dpdm` bundles its own nested TypeScript 5.9.3, so none touch the root compiler. Production: `acorn` 8.17.0→8.18.0 (lockfile-only) and `magic-string` 0.30.21→**1.1.0** — a major that only drops the CJS/UMD builds for pure ESM (FireForge is pure ESM; the five `MagicString` call sites use the unchanged core API). Dev: `@types/node` 26.1.2, `dpdm` 4.3.0, `eslint` 10.8.0, `eslint-plugin-jsdoc` 63.3.3, `knip` 6.29.0, `lint-staged` 17.3.0, `prettier` 3.9.6, `typescript-eslint` 8.66.0, `vite` 8.2.1, and `eslint-plugin-simple-import-sort` 13→**14** (breaking only for string-literal export names, which the codebase does not use); four of these resolved one patch/minor past PR #48's snapshot within the existing caret ranges (typescript-eslint 8.66.0 re-verified against the same `<6.1.0` peer window). CI: the SHA-pinned actions group (checkout 7.0.1 with `--unset`-escaping and branch-trim fixes, setup-node, codeql init/analyze). knip 6.29's stricter re-export tracking flagged seven type re-exports (`PatchCoverage`, `ClearablePatchMetadataField`, `PatchMetadataMutation{,Result}` in `patch-export.ts`; `ForwardImportEdge` in `patch-lint-reexports.ts`; `PatchManifestRowMutation{,Result}` in `patch-manifest.ts`) that no module, test, or public-API entry consumed via the barrel hop — a real 6.26 blind spot, so the dead re-exports were removed (the types stay exported from their defining modules). Verified by a full green `release:check`.

package/README.md

@@ -86,7 +86,8 @@ Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal
 (range-aware when `patchPolicy.ranges` is configured), `patch reorder` moves a patch, and
 `patch split <source> --files <paths...> --name <name>` carves files out of a patch into a
 new one as a single transaction — including staged-dependency owner rewrites — with
-`--dry-run` support.
+`--dry-run` support. `patch rename` also supports `--category` and `--order`; every
+queue-mutating patch command accepts `--wait-lock [seconds]`.
 
 `fireforge test <directory>` runs exactly that directory: FireForge enumerates the
 directory's test files and passes the explicit file list to mach in one invocation, so
@@ -98,14 +99,18 @@ instances do not exercise cross-argument state (`--no-shard` restores one combin
 invocation). Recognized harness crashes retry up to `--harness-retries <n>` times (default
 2), and `--perf-samples <path>` publishes a perf-sample artifact path to the harness
 (exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
+Every test run ends with one machine-readable `FIREFORGE-VERDICT: PASS|FAIL ...` line;
+automation should use it instead of the raw process code and treat a missing verdict as
+failure.
 Pathless test runs must choose a mode: `--auto` forwards mach's own auto-selection,
 `--doctor` runs the Marionette preflight only, and `--canary [path]` runs one short
 browser-chrome canary (`test.canaryPath` / `test.canaryTimeoutSeconds` in `fireforge.json`
 provide defaults). When packageable engine files changed since the last successful
 FireForge build, `test` fails before launching stale artifacts; use `--build` to refresh
-or `--allow-stale-build` only for intentional out-of-band rebuilds. If an interrupted
-browser holds the Marionette port, `--kill-stale-marionette` terminates recognized browser
-holders and still refuses unrelated listeners. In dev builds, files under `obj-*/dist/bin`
+or `--allow-stale-build` only for intentional out-of-band rebuilds. `--build-only`
+packages mixed-harness paths once; `--extend-coverage` safely retains prior scoped
+coverage. `--kill-stale-marionette` terminates recognized stale browsers. In dev builds,
+files under `obj-*/dist/bin`
 may be symlinks back into the source tree (notably prefs), so edit source prefs directly
 and keep a backup before bisection experiments.
 
@@ -141,7 +146,9 @@ override the loose baseline so calls to nonexistent harness members fail at expo
 For CI enforcement, `fireforge status --check` exits non-zero when any unmanaged,
 drifted, or conflicted file exists (`--fail-on <class,...>` tunes the policy set, and
 `--json` composes — the JSON stays parseable and its `files[]` entries name the owning
-`patch`). `lint --per-patch --report <path>` writes a machine-readable JSON report with
+`patch`). `--include-ownership` adds ownership rows to JSON status output. Scan-less
+`re-export` previews drift; `--refuse-foreign-drift --expect <path>` restricts it to
+intended files. `lint --per-patch --report <path>` writes a machine-readable JSON report with
 each patch's line count, tier, active size thresholds, issues, and lintIgnore-suppressed
 issues; the size metrics (`countNonBinaryDiffLines`, `resolvePatchSizeTier`,
 `getPatchSizeThresholds`) are also exported on the programmatic API.
@@ -149,11 +156,10 @@ issues; the size metrics (`countNonBinaryDiffLines`, `resolvePatchSizeTier`,
 For concurrent read-mostly verification beside a busy primary checkout,
 `fireforge tree create <name>` snapshots the project — applied engine tree included,
 `obj-*` excluded — into `.fireforge/trees/<name>` using filesystem copy-on-write (APFS
-clonefile / btrfs-XFS reflink; ~3 s for a 156 MB applied browser tree). Inside a tree,
-`status`, `lint`, `typecheck`, `verify`, `doctor`, and `export --dry-run` work unmodified
-with their own locks, while every mutating command is refused — patches and exports stay
-strictly serial in the primary tree. `tree list` reports staleness, `tree remove` deletes
-(refusing while a live process holds a tree lock), and `tree exec <name> -- <cmd>` runs a
+clonefile / btrfs-XFS reflink; ~3 s for a 156 MB applied browser tree). Read-only commands
+and export/re-export dry runs work inside a tree; mutations are refused. `--with-objdir`
+adds a safely relocated build for build-less tests. `tree list` reports staleness,
+`tree remove` deletes (refusing active locks), and `tree exec <name> -- <cmd>` runs a
 command inside a tree. Filesystems without CoW support refuse unless `--force-copy`
 explicitly accepts a full physical copy.
 

package/dist/bin/fireforge.js

@@ -17,6 +17,7 @@ import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight,
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
 import { waitForActiveChildShutdown } from '../src/utils/process.js';
+import { waitForStdioDrain } from '../src/utils/stdio-drain.js';
 /**
  * Upper bound (ms) the signal handler will wait for any in-flight critical
  * section (e.g. rebase apply + session persist) to finish before calling
@@ -34,13 +35,32 @@ const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
  * immediately, so an impatient operator is never stuck waiting.
  */
 const CHILD_SHUTDOWN_TIMEOUT_MS = 12_000;
+/**
+ * Upper bound (ms) a delayed exit waits for stdout/stderr to drain. When
+ * stdout is a pipe it is ASYNC, and `process.exit()` discards anything
+ * queued past the 64 KiB kernel buffer — which truncated the
+ * `status --json --fail-on` refusal payload for every piped consumer.
+ * Bounded so a stalled reader can never wedge a failing process; an
+ * EPIPE'd/closed pipe releases the wait immediately.
+ */
+const STDIO_FLUSH_TIMEOUT_MS = 5_000;
+/**
+ * Drains stdio, then exits. Every delayed exit routes through here — only
+ * the second-Ctrl+C force-exit (an explicit "out NOW") and this helper's
+ * own call terminate directly.
+ */
+function exitAfterStdioFlush(code) {
+    void waitForStdioDrain(STDIO_FLUSH_TIMEOUT_MS).finally(() => {
+        process.exit(code);
+    });
+}
 installBrokenPipeHandler();
 process.on('unhandledRejection', (reason) => {
     console.error('Fatal error (unhandled rejection):', reason instanceof Error ? reason.message : reason);
     if (reason instanceof Error && reason.stack) {
         console.error(reason.stack);
     }
-    process.exit(1);
+    exitAfterStdioFlush(1);
 });
 // SIGINT / SIGTERM handlers run any in-flight furnace rollback before
 // terminating. The library cannot call process.exit itself (the
@@ -81,7 +101,7 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // best-effort (errors are logged, not thrown).
             .then(() => forceReleaseFurnaceLocksForActiveOperations())
             .finally(() => {
-            process.exit(exitCode);
+            exitAfterStdioFlush(exitCode);
         });
     });
 }
@@ -89,9 +109,10 @@ installFurnaceSignalHandler('SIGINT', 130);
 installFurnaceSignalHandler('SIGTERM', 143);
 main().catch((error) => {
     if (error instanceof CommandError) {
-        process.exit(error.exitCode);
+        exitAfterStdioFlush(error.exitCode);
+        return;
     }
     // Truly unexpected — CommandError should have been thrown by withErrorHandling
     console.error('Fatal error:', error);
-    process.exit(1);
+    exitAfterStdioFlush(1);
 });

package/dist/build-info.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "version": "0.41.0",
+  "commit": "8d94512ea3928aa68b5525ddb73091fec73ce56c",
+  "shortCommit": "8d94512ea392",
+  "dirty": false,
+  "dirtyHash": null,
+  "buildTime": "2026-08-15T22:42:44.650Z"
+}

package/dist/src/cli.js

@@ -7,9 +7,9 @@ import { runTreeGuardHook } from './core/tree-guard.js';
 import { CancellationError, CommandError, FireForgeError } from './errors/base.js';
 import { ExitCode } from './errors/codes.js';
 import { ConfigNotFoundError } from './errors/config.js';
+import { getCliVersion } from './utils/build-info.js';
 import { toError } from './utils/errors.js';
-import { cancel, error as logError, setVerbose } from './utils/logger.js';
-import { getPackageVersion } from './utils/package-root.js';
+import { cancel, error as logError, setMachineOutputMode, setStdoutSealed, setVerbose, } from './utils/logger.js';
 const brokenPipeInstalledKey = Symbol.for('fireforge.cli.brokenPipeHandlerInstalled');
 const brokenPipeListenerKey = Symbol.for('fireforge.cli.brokenPipeHandlerListener');
 function getProcessState() {
@@ -100,6 +100,12 @@ export function withErrorHandling(handler) {
             await handler(...args);
         }
         catch (error) {
+            // Sentinel errors have already been rendered by the command. Passing
+            // them through prevents machine-readable refusal paths from acquiring
+            // an "Unexpected error" banner and stack trace on stderr.
+            if (error instanceof CommandError) {
+                throw error;
+            }
             if (error instanceof CancellationError) {
                 cancel('Operation cancelled');
                 // 130 (128+SIGINT) is the conventional "user interrupted" code —
@@ -118,6 +124,16 @@ export function withErrorHandling(handler) {
             }
             throw new CommandError(ExitCode.GENERAL_ERROR);
         }
+        finally {
+            // Central machine-mode and stdout-seal reset. Commands leave both
+            // ENGAGED while an error propagates (a mid-throw restore would route
+            // the styled error to stdout, corrupting the `--json`/`--raw` payload
+            // stream or displacing the FIREFORGE-VERDICT line); the reset happens
+            // here, after logError has picked its stream, so no state leaks into
+            // a subsequent in-process invocation.
+            setMachineOutputMode(false);
+            setStdoutSealed(false);
+        }
     };
 }
 /** Human-readable labels for command groups, in display order. */
@@ -246,6 +262,7 @@ export function createProgram() {
         .name('fireforge')
         .description('A build tool for customizing Firefox')
         .option('-v, --verbose', 'Enable debug output')
+        .option('--ignore-corrupt-tree-marker', 'Run even when .fireforge/tree.json exists but cannot be parsed. Without this the tree guard refuses, because an unreadable marker leaves it unknown whether this is a snapshot or the primary tree.')
         .hook('preAction', (thisCommand) => {
         const opts = thisCommand.opts();
         if (opts['verbose']) {
@@ -282,7 +299,7 @@ export async function main() {
     const userArgs = process.argv.slice(2);
     const hasSubcommand = userArgs.some((arg) => !arg.startsWith('-'));
     if (!hasSubcommand && userArgs.some((arg) => arg === '--version' || arg === '-V')) {
-        process.stdout.write(`${getPackageVersion()}\n`);
+        process.stdout.write(`${getCliVersion()}\n`);
         return;
     }
     const program = createProgram();

package/dist/src/commands/bootstrap.js

@@ -10,6 +10,7 @@ import { pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, warn } from '../utils/logger.js';
 import { detectBootstrapIssues, runPostBootstrapChecks } from './bootstrap-checks.js';
 import { reportDoctorResults } from './doctor.js';
+import { resolveDoctorSeverity } from './doctor-check-core.js';
 /**
  * Builds a human-readable failure message for hard failures (non-zero exit).
  * Used only when mach bootstrap itself reports failure.
@@ -67,7 +68,10 @@ export async function bootstrapCommand(projectRoot) {
     const issues = detectBootstrapIssues(output);
     if (issues.length > 0) {
         const checks = await runPostBootstrapChecks(issues);
-        const hasErrors = checks.some((c) => c.severity === 'error' || (!c.passed && !c.warning));
+        // Shares one resolver with reportDoctorResults so the two consumers of
+        // this same array cannot drift apart again — before 0.41.0 they
+        // disagreed on `passed: false, warning: true` with no severity.
+        const hasErrors = checks.some((c) => resolveDoctorSeverity(c) === 'error');
         info('');
         if (hasErrors) {
             warn('Bootstrap completed with issues:');

package/dist/src/commands/discard.js

@@ -3,13 +3,12 @@ import { confirm } from '@clack/prompts';
 import { Command } from 'commander';
 import { getProjectPaths } from '../core/config.js';
 import { applyDiscardBaseline, describeConflictWarning, describeDiscardBaseline, describeDiscardOutcome, planDiscardBaselines, planUpstreamDiscards, summarizeDiscardBaselines, } from '../core/discard-baseline.js';
+import { assertEngineGitReady } from '../core/engine-precondition.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
-import { getHead, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { GitError } from '../errors/git.js';
 import { toError } from '../utils/errors.js';
-import { pathExists } from '../utils/fs.js';
 import { info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
@@ -126,26 +125,7 @@ async function discardDirectoryEntries(projectRoot, engineDir, patchesDir, dirPa
 export async function discardCommand(projectRoot, file, options = {}) {
     intro('FireForge Discard');
     const paths = getProjectPaths(projectRoot);
-    // Check if engine exists
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    // Check if it's a git repository
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    // Unborn-HEAD guard (mirrors status): an interrupted download leaves a
-    // repo with no baseline commit, where the entire ~300k-file tree reads
-    // as untracked — a discard against that state is never what the operator
-    // wants, and the guidance names the actual fix.
-    try {
-        await getHead(paths.engine);
-    }
-    catch (headError) {
-        if (!isMissingHeadError(headError))
-            throw headError;
-        throw new GeneralError('Engine repository has no baseline commit yet — a previous "fireforge download" was interrupted before git created the initial Firefox source commit. Re-run "fireforge download --force" to recreate the baseline repository cleanly.');
-    }
+    await assertEngineGitReady(paths.engine);
     // Check if the file has changes
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);

package/dist/src/commands/doctor/post-rebase-audit.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../../utils/errors.js';
 import { pathExists, readText } from '../../utils/fs.js';
 import { ok, warning } from '../doctor-check-core.js';
 async function readEngineText(engineDir, relativePath) {
@@ -9,17 +10,28 @@ async function readEngineText(engineDir, relativePath) {
         return null;
     return readText(fullPath);
 }
+/**
+ * Collects every `browser.toml` under the engine's browser-chrome test tree.
+ *
+ * Reports unreadable directories separately from "none found": the consumer
+ * turns an empty result into the issue "no browser.toml files found", which is
+ * the opposite diagnosis from "the tree could not be read". A swallowed
+ * mid-walk EACCES also silently *shrank* the result set, so one unreadable
+ * subdirectory produced a false clean for that subtree.
+ */
 async function collectBrowserTomlFiles(root) {
     const testRoot = join(root, 'browser/base/content/test');
     if (!(await pathExists(testRoot)))
-        return [];
+        return { files: [], unreadable: [] };
     const result = [];
+    const unreadable = [];
     async function walk(absDir, relDir) {
         let entries;
         try {
             entries = await readdir(absDir, { withFileTypes: true });
         }
-        catch {
+        catch (error) {
+            unreadable.push(`${relDir || '.'} (${toError(error).message})`);
             return;
         }
         for (const entry of entries) {
@@ -34,11 +46,17 @@ async function collectBrowserTomlFiles(root) {
         }
     }
     await walk(testRoot, '');
-    return result.sort();
+    return { files: result.sort(), unreadable };
 }
 async function runPostRebaseAudit(ctx) {
     const issues = [];
     const engineDir = ctx.paths.engine;
+    // The four probes below are upstream-Firefox shape markers: each names a
+    // file and a token that a healthy post-rebase tree must still contain. A
+    // rebase that dropped a fork patch, or an upstream reorganisation, shows up
+    // as one of these going missing. The tokens are deliberately coarse — this
+    // is a smoke check that runs warn-only behind an opt-in flag, not a
+    // structural validator.
     const mozConfigure = await readEngineText(engineDir, 'browser/moz.configure');
     if (mozConfigure === null) {
         issues.push('browser/moz.configure is missing');
@@ -69,7 +87,12 @@ async function runPostRebaseAudit(ctx) {
         issues.push('toolkit/content/jar.mn has no widget/element exposure entries');
     }
     const browserTomls = await collectBrowserTomlFiles(engineDir);
-    if (browserTomls.length === 0) {
+    if (browserTomls.unreadable.length > 0) {
+        issues.push(`could not read ${String(browserTomls.unreadable.length)} ` +
+            `${browserTomls.unreadable.length === 1 ? 'directory' : 'directories'} under ` +
+            `browser/base/content/test: ${browserTomls.unreadable.join(', ')}`);
+    }
+    else if (browserTomls.files.length === 0) {
         issues.push('no browser.toml files found under browser/base/content/test');
     }
     if (issues.length === 0) {

package/dist/src/commands/doctor-check-core.d.ts

@@ -87,6 +87,26 @@ export interface DoctorCheckDefinition {
      */
     fix?: string;
 }
+/**
+ * Resolves a {@link DoctorCheck} to its effective severity, implementing the
+ * field-precedence contract documented on the interface
+ * (`src/types/commands/project.ts`):
+ *
+ *   1. `severity`, when present, is authoritative — regardless of `passed`.
+ *   2. Without `severity`, `passed: false` is an error unless `warning: true`
+ *      downgrades it to a warning.
+ *
+ * This is the single implementation on purpose. Before 0.41.0 there were two
+ * and they disagreed on exactly one cell: `reportDoctorResults` consulted
+ * `warning` only inside the `passed === true` branch, so the documented
+ * downgrade produced an error and a non-zero doctor exit, while
+ * `bootstrap.ts` — reading the same array one line earlier — classified it as
+ * a warning. No in-tree producer emitted that combination (`failure()` always
+ * sets `severity: 'error'`), so the contradiction was latent rather than
+ * observable; the interface is exported, so the next hand-rolled check would
+ * have hit it.
+ */
+export declare function resolveDoctorSeverity(check: DoctorCheck): 'ok' | 'warning' | 'error';
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  */

package/dist/src/commands/doctor-check-core.js

@@ -4,6 +4,34 @@
  * `doctor.ts` and sibling check modules. Kept separate so registries can import
  * these symbols without creating cycles through `doctor.ts`.
  */
+/**
+ * Resolves a {@link DoctorCheck} to its effective severity, implementing the
+ * field-precedence contract documented on the interface
+ * (`src/types/commands/project.ts`):
+ *
+ *   1. `severity`, when present, is authoritative — regardless of `passed`.
+ *   2. Without `severity`, `passed: false` is an error unless `warning: true`
+ *      downgrades it to a warning.
+ *
+ * This is the single implementation on purpose. Before 0.41.0 there were two
+ * and they disagreed on exactly one cell: `reportDoctorResults` consulted
+ * `warning` only inside the `passed === true` branch, so the documented
+ * downgrade produced an error and a non-zero doctor exit, while
+ * `bootstrap.ts` — reading the same array one line earlier — classified it as
+ * a warning. No in-tree producer emitted that combination (`failure()` always
+ * sets `severity: 'error'`), so the contradiction was latent rather than
+ * observable; the interface is exported, so the next hand-rolled check would
+ * have hit it.
+ */
+export function resolveDoctorSeverity(check) {
+    if (check.severity !== undefined) {
+        return check.severity;
+    }
+    if (check.warning) {
+        return 'warning';
+    }
+    return check.passed ? 'ok' : 'error';
+}
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  */

package/dist/src/commands/doctor-external-toolchains.js

@@ -15,6 +15,8 @@ async function resolveDeclaredTool(projectRoot, tool) {
             return found.exitCode === 0 ? line?.trim() : undefined;
         }
         catch {
+            // `xcrun -find` is absent or the tool is unknown — either way the tool has
+            // no resolvable path, which is what `undefined` means to the caller.
             return undefined;
         }
     }