@hominis/fireforge 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # 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`.
+- **New `fireforge tree` command: copy-on-write verification clones for concurrent read-mostly work** (FORGE G15, feature — every consumer parallelisation attempt dead-ended on the ONE applied engine tree: `engine/` is gitignored by design so git worktrees provide no isolation, and the repo-root build lock plus one objdir kept all fix/test/export work serial; measured on APFS, `engine/browser` — 11,513 files, 156 MB — clones via clonefile in ~3 s): `tree create <name>` snapshots the project (fireforge.json, configs, src, patches, components, and `engine/` with `obj-*` excluded) into `.fireforge/trees/<name>` via filesystem CoW (APFS clonefile / btrfs-XFS reflink, probed BY DOING in the destination directory), taken under the primary engine-session lock so a mid-mutation state is never captured; filesystems without CoW REFUSE honestly, with `--force-copy` opting into a full physical copy explicitly (never silently). A tree is a full project root, so `status`, `lint`, `typecheck`, `verify`, `doctor`, and `export --dry-run` run inside it unmodified with their own per-tree locks — while every mutating command (`export`, `re-export`, `patch *`, `token *`, `furnace *`, `build`, headed `run`, …) is refused via the `.fireforge/tree.json` marker and a default-deny verdict table enforced in one commander preAction hook (a drift test forces every new command to be classified); patches and exports stay strictly serial in the primary tree with no merge-back model. `tree list [--json]` reports staleness against the primary engine HEAD and `patches.json` fingerprint; `tree remove` refuses while a live process holds a tree lock and path-contains its delete; `tree exec <name> -- <cmd>` runs a command inside a tree; Windows is refused (POSIX clonefile/reflink only). **Deferred to 0.41.0 with the design recorded: `--with-objdir` and in-tree `test`** — mach objdirs embed absolute `topsrcdir`/`topobjdir` paths (FireForge's own `mach-build-artifacts.ts` parses them), so a cloned objdir would silently operate against the primary tree; a `mozinfo.json` preflight is the planned gate. New invariant 7 in `docs/lifecycle-invariants.md`. Pinned by `tree-cow.test.ts` (per-platform cp argv, probe verdicts), `tree-store.integration.test.ts` (snapshot contents/exclusions, independence, staleness, live-holder refusal), `tree-guard.test.ts` (verdict drift gate), and `tree.integration.test.ts` (real clone + real-program guard refusal).
+- **Previously deferred items, re-adjudicated for 0.40.0**: auto-`caffeinate` for headed macOS dispatches stays deferred (the 0.39.0 F17 message + operator rule works; auto-wrap adds TTY/permission complexity for little gain); real co-ownership of one upstream file by two patches stays deferred (design-level — shared-file diffs are pristine-baseline so co-ownership remains unrepresentable; the consumer's single-owner consolidation plus audit-side per-patch entry lists stands); `furnace create` maintaining the consumer jsconfig path mapping for new widget modules stays deferred this release (the JSONC-preserving edit machinery exists, but the mapping shape is consumer-project-specific — revisit with a concrete config contract).
+- **Concurrent xpcshell runs no longer collide on Firefox's fixed profile directory** (FORGE G15b, bug — the harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a fixed `$TMPDIR/firefox/xpcshellprofile`, so two overlapping `fireforge test` invocations corrupted each other's profiles; FireForge itself never set the variable): every harness invocation that can dispatch xpcshell (single runs, each shard, and generic `mach test` runs) now exports a fresh `mkdtemp` profile dir (`fireforge-xpcshell-profile-*`) into the mach environment via the new `withXpcshellProfileDir` helper and removes it after the run (best-effort — a cleanup failure warns and leaves the dir to the OS tmp reaper); the crash/symlink-repair retries within one invocation deliberately reuse the same directory, an operator-provided `XPCSHELL_TEST_PROFILE_DIR` is respected verbatim (and never deleted), and pure mochitest dispatches keep a byte-identical env. This is the independently-shippable half of the G15 verification-tree design — it also unblocks concurrent test runs from separate checkouts today. Pinned by uniqueness/opt-out/override/retry-reuse cases in `test-run-suite-dispatch.test.ts` and the lifecycle cases in `xpcshell-profile-dir.test.ts`.
+- **Per-patch lint can now typecheck patch-adopted test `.js` files against a consumer-configurable harness shim: `patchLint.checkJsTestFiles` + `patchLint.checkJsTestShim`** (FORGE G5, enforcement gap — honest framing: the consumer's seven TS2339s on `TestUtils.waitForCondition` were invisible to `lint --per-patch --max-warnings 0` not because the shim differed from the jsconfig projects', but because test `.js` files were never in the checkJs program at all — only new `.sys.mjs` modules were; the harness global that does not exist should fail at the patch boundary where the test was authored): opt-in (`checkJsTestFiles` requires `checkJs`; new failure surface, nonzero compile cost) extends the check set to patch-owned `browser_*`/`test_*`/`xpcshell_*` and `/test/`-path `.js` files, each checked as its OWN small script-scope program (mochitest scripts share top-level scope only with their directory's `head*.js` helpers, which are included as roots) against the built-in Firefox shim, a new loose built-in test-harness shim (`TestUtils`, `BrowserTestUtils`, `add_task`, `ok`/`is`, …), and the consumer's `checkJsTestShim` `.d.ts` — whose typed declarations compose BEFORE the loose baseline and therefore win, so a typed `TestUtils` there is exactly what turns the consumer's case into an export-time error. Wired identically into `lint --per-patch` (one merged lazy build per run) and the export/re-export path so the two agree; `typecheck.projectOverrides` remains typecheck-only by design (loading real jsconfig projects into per-patch lint's empty-tree compiler host would pull the Firefox tree in). Pinned by the was-never-checked gap pin, the TS2339-surfaces case, and the loose-baseline pass in `lint-per-patch-checkjs.integration.test.ts`, plus config cross-field validation in `config.test.ts`.
+- **Patch size metrics are now on the public API — `countNonBinaryDiffLines`, `resolvePatchSizeTier`, and the new `getPatchSizeThresholds` — plus a machine-readable per-patch report via `lint --per-patch --report <path>`** (FORGE G9, feature — the size counter `large-patch-lines` fires on was unreachable programmatically (`"./*": null` blocks deep imports and `src/index.ts` never exported it), so the consumer MIRRORED it to build waiver-freshness checks, a silent-divergence risk by construction): the three functions and the `PatchSizeTierDecision` type join the entry exports (pinned by `public-api.test.ts`), and the `--report` JSON (schemaVersion 1; requires `--per-patch`) carries per patch: filename, name, status (`linted`/`cached`/`skipped`), `lineCount` (non-binary diff lines), `filesAffected` count, the tier decision, the ACTIVE thresholds for that tier, the surfaced issues, and the lintIgnore-suppressed issues, plus run totals. Pinned by the report-shape assertions in `lint.integration.test.ts`.
+- **A size finding waived by `lintIgnore` no longer vanishes without a trace in per-patch mode** (FORGE G10, observability — the waiver filter dropped the whole issue including the measurement embedded in its message, so a waived patch's CURRENT size could not be read back from the tool that enforces it and waiver-cited counts had to be calibrated by hand; aggregate mode printed a suppressed count while per-patch printed nothing): the finding stays suppressed (no exit-code or `--max-warnings` effect) but its measurement is reported as `NOTICE [large-patch-lines] <patch>: suppressed by lintIgnore — Patch is N lines (hard limit: M) …` (likewise `large-patch-files` / `file-too-large`), the run summary adds `Suppressed k issue(s) via per-patch lintIgnore.` mirroring the aggregate wording, and suppressed issues plus the measured line count are carried through the per-patch lint cache (schema bump to v2, one-time cold cache) so a warm run can never report less than a cold one — the same F5-class hazard the run-level checkJs fix closed. Also available structurally in the `--report` JSON. Pinned by the waived-measurement case in `lint.integration.test.ts` and the cache round-trip in `lint-cache.test.ts`.
+- **Smoke-run summaries now attribute allowlist hits per entry, with zero-hit entries flagged as removal candidates** (FORGE G8, observability — `matchesAllowlist` returned a bare boolean and `compileAllowlistFromFile` discarded source line numbers, so an allowlist entry that silently stopped matching was undetectable and the consumer rebuilt per-entry replay in ~190 lines against a retained capture): compiled entries now carry their verbatim source and origin (`allow.txt:12`, `--console-allow #2` — file origins keep the ORIGINAL line numbers, comments included) via the new `CompiledAllowlistEntry` shape, `matchAllowlist` returns the first matching index (deterministic first-match attribution, replacing the boolean `matchesAllowlist`), and the post-run summary prints one `N×  <origin>  <source>` row per entry with `0×` rows suffixed `(never matched — candidate for removal)`. The three scalar counters and the exit contract (12/13) are unchanged; the human summary is the supported surface (no JSON sidecar this release). Pinned by the attribution rows in `run.test.ts` and the origin/first-match cases in `smoke-patterns.test.ts`.
+- **`lint --per-patch <patch…>` now works: positional arguments in per-patch mode select patches through the same alias resolution as `--patches`** (FORGE G14, ergonomics — the natural invocation `lint --per-patch a.patch b.patch` was rejected with the misleading "cannot be combined with explicit engine file paths" while the suggested form required retyping the list behind a flag): positionals are appended after explicit `--patches` entries and resolved tolerantly (filename, stem, manifest name, category-prefixed slug, or bare slug); a non-matching positional fails loud with `No patch in the queue matches "…". In --per-patch mode, positional arguments and --patches select patches … drop --per-patch to lint engine paths.` plus the available-patches listing, so an engine path can never silently lint the wrong thing. The `--patches` help notes the positional equivalence. Pinned by the positional-subset and unmatched-positional cases in `lint.test.ts`.
+- **`patch staged-dependency --remove` now accepts `--file` + `--specifier` alone, inferring `--creates` from a unique match; missing-flag errors name the actually-missing flags** (FORGE G12, ergonomics + message — the remove path demanded the full triple even when file+specifier identified exactly one entry, and every `Invalid Argument` printed `Argument: patch staged-dependency`, restating the command instead of the offending flag): a unique file+specifier(+`--owner`) match infers its `creates` with an `Inferred --creates …` notice; an ambiguous match refuses listing every candidate (`pass --creates to pick one`); no match keeps the honest exit-0 "no staged forward-import matched" summary. `--kind registration` gets the identical treatment keyed on `--line`. All `Argument:` lines in this command now name flags (`--specifier, --creates`, `--kind`, `--add/--remove/--clear`, …), and the `-y/--yes` help no longer claims a confirmation prompt exists (message-only — the command never prompted; the flag records scripted consent in the history log). Pinned by the inference, ambiguity, no-match, and attribution cases in `patch-tier-and-lint-ignore.integration.test.ts`.
+- **`token add` can no longer silently strand or skip a token when its category is wrong — every bypass around the missing-category refusal is closed** (FORGE G3, bug + claim partially REFUTED — the reported plain-path "missing category exits 0" is contradicted by the pre-existing `assertTokenCategoryExists` throw, pinned since before 0.39.0; the 19 observed silent no-ops reproduce only through three real bypasses, all fixed): (1) category banners now match EXACTLY (`/* = Name = */` text equality, multi-line block-line equality) instead of by substring, so a TOC comment mentioning "Colors — Terminal" or a `Colors — Canvas` banner can no longer satisfy a lookup for a different name — assert and writer share the matcher (new `token-category.ts`); (2) the whole-file idempotency check is replaced by a per-category one — a token already in the TARGET category skips with its location named (`already exists in category "X" (line N)`), while a token declared elsewhere in the base `:root` block REFUSES with `Token "…" is already declared outside category "…" (<file>:<line>, section "…")` instead of silently skipping and discarding `--create-category`; dark-`@media`/variant companion blocks are excluded from ownership; the exact name must match (`--foo` no longer collides with `--x-foo`); (3) `--variant` now validates `--category` against the file instead of silently discarding it, and `--variant` + `--create-category` is refused. Dry-run agrees with the real run on all three. Behavior change: loose banner matches that previously "worked" now fail loud with the existing available-categories listing. Pinned by the bypass matrix in `token-manager.test.ts`.
+- **Patch-lint `raw-color-value` no longer fires on hex colors inside CSS comments that span the context/added-line boundary** (FORGE G4, bug — the per-patch comment stripper only saw the joined added lines, so a `/*` opened on an unchanged context line never suppressed a hex mention on an added line; two prose references to a vendored sheet's black paint inside comments tripped the rule for the consumer on 2026-07-30): the diff branch now masks comments across the full post-patch file (spaces preserve line numbers; an unclosed trailing `/*` masks to EOF) via the new `extractAddedLineNumbersPerFile` diff walker, then scans only the patch's added line numbers. Inline `fireforge-ignore: raw-color-value` waivers keep matching against pre-strip text; the no-diff branch is unchanged; and when the diff's line numbers fall outside the on-disk file (drifted patch) the scan falls back to the previous joined-added-lines behavior instead of misattributing lines. Pinned by the boundary-spanning, still-fails-in-declaration, waiver, and drift-fallback cases in `patch-lint.test.ts`.
+- **`export --name ui-foo --category ui` now lands manifest `name: "foo"` in one step, and `--name <stem>.patch` no longer trips the dot validator** (FORGE G13, bug + message — the filename slug pipeline has stripped redundant category prefixes since 0.33.0 (and `.patch` suffixes since 0.39.0's F9) but the manifest display name kept the raw flag value, so a bare-filename-slug naming policy required a follow-up `patch rename --to` after every export): display names are normalized after category resolution with the same require-the-category-token rule as filenames via the new `normalizePatchDisplayName` (`NNN-ui-` / `ui-` prefixes stripped case-insensitively and repeatedly; a bare leading number is never stripped, so `2-step-verification` survives; the strip falls back to the stem rather than emptying the name), announced with `Patch name normalized: "ui-foo" → "foo" (the filename carries the order and category prefix).`; a trailing `.patch` is stripped before `validatePatchName` runs. Applies to `export` and `export-all`. `patch rename` additionally gains `-d` as an alias for `--description`; multi-target `re-export --scan --scan-file` remains deferred (file→patch assignment would be ambiguous — `--scan-files <manifest>` already serves bulk assignment). Pinned in `export-shared.test.ts` and `validation.test.ts`.
+- **New `status --check` (and `--fail-on <class,...>`) turns classification drift into a CI-enforceable non-zero exit** (FORGE G1, enforcement gap — every 0.39.0 status variant exited 0 even while reporting unmanaged/drifted/conflicted files, so "refuse if dirty" required every consumer to parse `--json` and re-implement the classification policy; combined with the G2 gap this let two manifest-registered proving suites ship into no patch while every advertised gate stayed green): `--check` fails with exit 1 whenever any `unmanaged`, `patch-owned-drift`, or `conflict` file exists, naming each offending classification with its first three paths (`status --check failed: 2 unmanaged (a, b), 1 patch-owned-drift (c). …`); `--fail-on` replaces the policy set (implying `--check`, refusing unknown values by naming the valid six); composes with the default view and `--json` (the JSON stays parseable on stdout, the refusal routes to stderr) and is refused alongside `--raw`/`--unmanaged`/`--ownership`/`--test-coverage`. A clean tree passes. Pinned by `status-check.test.ts` and the `--check` cases in `status.test.ts`.
+- **`status --json` files[] entries now carry a `patch` field naming the owning patch filename (`null` when unowned)** (FORGE G11, feature — the classifier resolved every file's owner at classify time and then discarded it for non-conflict entries, so resolving 16 drifted files to their patches meant scraping the human `--ownership` box table with `awk`): single-owner `patch-backed`, `patch-owned-drift`, and healthy single-owner `furnace` entries name their owner; `branding`, unowned `furnace`, and `conflict` entries report `null` (conflicts keep the existing `claimedBy` array — a single-owner field must not misrepresent a multi-claim). Additive to `schemaVersion: 1`, so consumers pinning the schema keep parsing; the post-slice re-export loop is now scriptable straight off `--json`. Pinned by the owner-matrix case in `status.test.ts`.
+- **Scan-less `re-export`'s adjacency notice is now classification-aware, and the new `--refuse-adjacent-unmanaged` flag upgrades it to a non-zero refusal that skips the write** (FORGE G2, bug + message — the claim that 0.39.0 was fully silent is partially REFUTED: the v0.27.2 sibling advisory did fire for the reported shape, a new test created beside a patch's owned tests, and is pinned by the pre-fix reproduction in `re-export.integration.test.ts`; but it counted tool-managed paths as "unowned siblings" and offered no enforcement). The notice now names only genuinely unmanaged adjacent files — generated branding paths and furnace-managed prefixes are excluded, while a brand-new unowned file under the branding root stays listed (the Assets.car precedent) — with the wording `found N unmanaged file(s) adjacent to this patch's ownership (<first 3>)`. Under `--refuse-adjacent-unmanaged` (scan-less path only; refused alongside `--scan`/`--files`) each offending patch is skipped unwritten and the run fails with one refusal naming every offender, so CI cannot ship a patch refresh past an unadopted file. Residual blind spot documented in-test: a new file in a cousin directory no owned file lives in is still unreported (recursive scans are too noisy on Firefox-sized trees). Pinned in `re-export.test.ts` (branding/furnace exclusion, skip-and-refuse) and `re-export.integration.test.ts`.
+- **`re-export` now retries once, after a 300 ms backoff, when a patch fails on transient git `index.lock` contention** (FORGE G7, bug — an external git process touching `engine/.git/index.lock` during the binary-staging `git add -N`/`git diff --binary` window permanently failed that patch while the run reported `Re-exported 1 of 2` and exited 0; the identical immediate rerun succeeded with no hand cleanup, which is exactly the shape an internal retry should absorb): lock-class failures are detected via the new `isGitIndexLockConflict` heuristic in `errors/git.ts` (a `GitIndexLockError`, or a `GitError` whose message pairs `index.lock` with lock phrasing), the retry re-enters the per-patch export from the top so it re-reads clean state, and a second failure keeps the honest `N of M` summary. Non-lock failures never retry. Partial-failure exit code is intentionally unchanged this release; a non-zero exit (or `--strict`) for partial runs is the recommended follow-up. Pinned by the retry, double-failure, partial-success, and no-retry cases in `re-export.test.ts` and the heuristic table in `git-index-lock.test.ts`.
+- **`export --before/--after` no longer refuses placements whose renumber never actually reaches a reserved range** (FORGE G6, bug — `computePlacementPlan` shifted every patch at or above the insertion point by +1, so any positional insert below a `patchPolicy.reservedRanges` block dragged the reserved patches into the rename map and tripped the up-front refusal even with free ordinals in between; in a ~230-patch tree with a 900-999 reserved block, `--before`/`--after` were effectively unavailable and every insert needed an explicit `--order`): the +1 cascade now stops at the first unoccupied ordinal — a gap absorbs the insert, so the tail beyond it (including any reserved block) keeps its numbering — while a genuinely contiguous run into the block still refuses with the same single up-front error. The same cascade serves `patch split` and `patch move-files --create` placements. Pinned by the stop-at-gap and contiguous-refusal cases in `export-placement-policy.test.ts` and the rewritten sparse-queue case in `export-flow.test.ts`.
+
 ## 0.39.0
 
 - **`fireforge discard` restores patch-claimed paths to their PATCH-APPLIED baseline instead of pristine upstream, and re-materializes patch-created files instead of deleting them** (FORGE F1, P0 data-loss bug — 15 `patch-backed`/`owned` engine files discarded with `--yes` came back as upstream Firefox artwork, `jar.mn` lost all 134 fork entries, and patch-created files like `hominis-start.html` were deleted outright, all under the message "File restored to original state"; recovery cost a full `reset` + 207-patch `import` + rebuild): discard now consults the manifest's ownership claims per status entry and restores claimed files by folding HEAD content through every affecting patch in order (`computePatchedContent`), leaving the post-`import` worktree convention intact (patch edits stay unstaged ` M`, patch creations stay untracked `??`); patch-deleted files are removed to match the baseline. The legacy semantics are an explicit opt-in via the new `--to-upstream` flag. Success messages name the baseline (`File restored to patch baseline (0001-ui-edit.patch)`, `File re-materialized from patch baseline (…)`, `File restored to pristine upstream (HEAD)`); directory mode applies the same rule per file and its outro buckets the outcomes (`3 file(s) restored: 1 to patch baseline, 1 re-materialized, 1 to upstream state`); dry-run lines annotate each path with its restore target. A corrupt manifest or an unreconstructible baseline REFUSES (naming `--to-upstream`) rather than silently reverting to HEAD; multi-owner (conflict) claims restore the cumulative baseline with a warning pointing at `status --ownership`. Pinned by `discard-patch-baseline.integration.test.ts` (the exact handoff shape: edit-patch + create-patch, dirty both, discard each, assert patch content and git state) and `discard-baseline.test.ts`.

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.
 
@@ -131,7 +136,32 @@ contaminates the console capture (headed non-CI launches print a warning saying
 Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals shim that
 tracks upstream WebIDL additions per release; a project's `patchLint.checkJsExtraShim` can
 add members to the structured shim globals via TypeScript interface merging (e.g.
-`interface ChromeUtilsShim { newApi(): any }`).
+`interface ChromeUtilsShim { newApi(): any }`). Opting into
+`patchLint.checkJsTestFiles: true` extends the pass to patch-owned test `.js` files
+(`browser_*`/`test_*`/`xpcshell_*` and `/test/` paths), each checked as its own small
+script-scope program against a loose built-in harness shim; `patchLint.checkJsTestShim`
+points at a project `.d.ts` whose typed declarations (e.g. a real `TestUtils` interface)
+override the loose baseline so calls to nonexistent harness members fail at export time.
+
+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`). `--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.
+
+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). 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.
 
 ## Rebasing Firefox Source
 

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

@@ -3,12 +3,13 @@ import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { Command, Help } from 'commander';
 import { COMMAND_MANIFEST } from './commands/manifest.js';
+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() {
@@ -99,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 —
@@ -117,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. */
@@ -245,11 +262,18 @@ 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']) {
             setVerbose(true);
         }
+    })
+        // Verification-tree guard (FORGE G15): when the cwd resolves into a
+        // tree snapshot, refuse mutating commands before their action runs —
+        // one hook covers every command regardless of how the cwd got there.
+        .hook('preAction', async (thisCommand, actionCommand) => {
+        await runTreeGuardHook(thisCommand.name(), actionCommand);
     });
     const groupedFormatter = buildGroupedHelpFormatter(COMMAND_MANIFEST);
     program.configureHelp({
@@ -275,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;
         }
     }