@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -37,21 +37,21 @@ export interface DoctorCheckContext {
     /**
      * The parsed furnace config, set by the "Furnace configuration" check
      * when it succeeds. Later furnace checks read from this so they do not
-     * re-parse the file; undefined when the config could not be loaded.
+     * re-parse the file. Undefined when the config could not be loaded.
      */
     furnaceConfig: FurnaceConfig | undefined;
     /**
      * State this run actually mutated, one human-readable line per write.
      * Repairs run inside the check loop while the exit code is computed only
      * after every check, so a repair can land and the run still exit non-zero
-     * on an unrelated check — and a non-zero exit reads as "nothing happened".
+     * on an unrelated check, and a non-zero exit reads as "nothing happened".
      * The runner prints these before the summary in every branch so a write is
      * never invisible.
      */
     mutations: string[];
 }
 /**
- * Result a check may return. A single object is the common case; an array
+ * Result a check may return. A single object is the common case. An array
  * lets a single check emit multiple related rows (e.g. the engine branch
  * check which may report on branch + detached state together).
  */
@@ -85,7 +85,7 @@ export interface DoctorCheckDefinition {
     dependsOn?: readonly string[];
     /**
      * Runs the inspection. Throwing is shorthand for "this check failed with
-     * severity 'error'" — the runner converts the exception message into a
+     * severity 'error'": the runner converts the exception message into a
      * DoctorCheck. Returning a DoctorCheck (or array) lets the check control
      * severity, warnings, and fix hints directly.
      */

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

@@ -15,8 +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.
+            // `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;
         }
     }

package/dist/src/commands/doctor-furnace-config-sync.d.ts

@@ -2,11 +2,11 @@
  * "Furnace config sync" doctor check.
  *
  * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json` — typically the concurrent-override race, where two
+ * from `furnace.json`, typically the concurrent-override race, where two
  * parallel `furnace override` commands both leave their directory on disk
  * but only the second reaches `writeFurnaceConfig`. Under
  * `--repair-furnace`, override orphans are re-registered from the
- * `override.json` sidecar the command wrote during the copy phase; custom
+ * `override.json` sidecar the command wrote during the copy phase. Custom
  * orphans are listed for the operator to either re-run `furnace create`
  * against or delete manually, because custom components have no similar
  * persisted metadata.

package/dist/src/commands/doctor-furnace-config-sync.js

@@ -3,11 +3,11 @@
  * "Furnace config sync" doctor check.
  *
  * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json` — typically the concurrent-override race, where two
+ * from `furnace.json`, typically the concurrent-override race, where two
  * parallel `furnace override` commands both leave their directory on disk
  * but only the second reaches `writeFurnaceConfig`. Under
  * `--repair-furnace`, override orphans are re-registered from the
- * `override.json` sidecar the command wrote during the copy phase; custom
+ * `override.json` sidecar the command wrote during the copy phase. Custom
  * orphans are listed for the operator to either re-run `furnace create`
  * against or delete manually, because custom components have no similar
  * persisted metadata.
@@ -32,10 +32,10 @@ import { failure, ok, warning } from './doctor-check-core.js';
  * to catch. The caller surfaces the failure instead.
  */
 async function listComponentDirs(dir) {
-    // `pathExistsStrict`, not `pathExists`: the latter answers `false` for EVERY
+    // `pathExistsStrict`, not `pathExists`: the latter answers `false` for every
     // access error, so an unreadable components directory reported "no orphans",
-    // i.e. a clean check — the same fail-open the comment above rejects for
-    // `readdir`. Only ENOENT means genuinely absent.
+    // i.e. a clean check. That is the same fail-open the comment above rejects
+    // for `readdir`. Only ENOENT means genuinely absent.
     if (!(await pathExistsStrict(dir)))
         return [];
     const entries = await readdir(dir, { withFileTypes: true });
@@ -48,7 +48,7 @@ async function recoverOverrideConfig(overrideDir, name) {
     // outer-snapshot config and drops the sibling write's addition.
     //
     // No `pathExists` precheck: it collapses "absent" and "unreadable" into
-    // the same `false`, and both outcomes lead here anyway — a missing file
+    // the same `false`, and both outcomes lead here anyway. A missing file
     // lands in the catch below with the same `undefined` result.
     const sidecarPath = join(overrideDir, name, 'override.json');
     try {
@@ -79,7 +79,7 @@ async function recoverOverrideConfig(overrideDir, name) {
     catch {
         // Unreadable or malformed sidecar. Returning `undefined` here is the same
         // value as "no sidecar present", so the caller reports the override as
-        // unrecoverable — which is the safe direction (it never invents config),
+        // unrecoverable. That is the safe direction (it never invents config),
         // but the operator sees "no valid override.json" rather than "the
         // override.json is corrupt". The remediation is identical either way.
         return undefined;
@@ -125,7 +125,7 @@ function emptyOutcome() {
 }
 /**
  * Re-registers override orphans and deletes empty custom orphan directories,
- * under ONE furnace lock held across both.
+ * under one furnace lock held across both.
  *
  * Two things this must not do, both of which reproduce the lost-write race the
  * check exists to clean up after:
@@ -133,9 +133,9 @@ function emptyOutcome() {
  * 1. Write back a decision made before the lock. The orphan list is computed
  *    from a config snapshot loaded well before we hold anything, so by the
  *    time we can write, a concurrent `furnace override` may have registered
- *    the same name — writing our sidecar-reconstructed entry over it discards
+ *    the same name. Writing our sidecar-reconstructed entry over it discards
  *    a live write, and a concurrent `furnace create` registering the name
- *    under `custom` would leave it in BOTH maps, a state nothing validates.
+ *    under `custom` would leave it in both maps, a state nothing validates.
  *    Every orphan is therefore re-checked against `freshConfig` inside the
  *    lock and skipped when it is no longer orphaned.
  * 2. Delete custom directories outside the lock. `repairCustomOrphans` used to
@@ -148,12 +148,12 @@ async function repairOrphans(projectRoot, orphans) {
     if (orphans.overrides.length === 0 && orphans.customNames.length === 0)
         return outcome;
     const lockPath = getFurnaceLockPath(projectRoot);
-    // One catch covers four distinct phases; naming the one that failed keeps
-    // the report honest — a lock timeout otherwise renders as "failed while
+    // One catch covers four distinct phases. Naming the one that failed keeps
+    // the report honest. A lock timeout otherwise renders as "failed while
     // writing furnace.json", the phase least likely to have been reached.
     // Held in an object rather than two `let`s: the lock callback mutates them
     // from inside a closure, and TS's control-flow analysis does not propagate
-    // that through the call — it would narrow both to their initial literals
+    // that through the call, so it would narrow both to their initial literals
     // in the catch below.
     const progress = { phase: 'waiting for the furnace lock', persisted: false };
     try {
@@ -165,7 +165,7 @@ async function repairOrphans(projectRoot, orphans) {
                 progress.phase = 'writing furnace.json';
                 await writeFurnaceConfig(projectRoot, freshConfig);
             }
-            // From here the restore (if any) is on disk; a later failure must not
+            // From here the restore (if any) is on disk. A later failure must not
             // report the whole repair as if it never happened.
             progress.persisted = true;
             progress.phase = 'cleaning custom orphan directories';
@@ -188,11 +188,11 @@ async function repairOrphans(projectRoot, orphans) {
     }
     return outcome;
 }
-/** Override half of {@link repairOrphans}; mutates `freshConfig` in place. */
+/** Override half of {@link repairOrphans}. Mutates `freshConfig` in place. */
 function repairOverridesLocked(freshConfig, orphans, outcome) {
     for (const orphan of orphans) {
         if (orphan.name in freshConfig.overrides || orphan.name in freshConfig.custom) {
-            // Registered while we waited for the lock — no longer an orphan, and
+            // Registered while we waited for the lock, so no longer an orphan, and
             // writing over it would either discard that write or duplicate the name
             // across `overrides` and `custom`.
             outcome.reconciled.push(orphan.name);
@@ -207,15 +207,15 @@ function repairOverridesLocked(freshConfig, orphans, outcome) {
         }
     }
 }
-/** Custom half of {@link repairOrphans}; must run under the same lock. */
+/** Custom half of {@link repairOrphans}. Must run under the same lock. */
 async function deleteEmptyCustomOrphans(projectRoot, freshConfig, customNames, outcome) {
     if (customNames.length === 0)
         return;
     const furnacePaths = getFurnacePaths(projectRoot);
     for (const name of customNames) {
         if (name in freshConfig.custom || name in freshConfig.overrides) {
-            // A name that was orphaned in BOTH trees is reconciled once, not once
-            // per tree — the report reads "Skipped 2 names (x, x)" otherwise.
+            // A name orphaned in both trees is reconciled once rather than once
+            // per tree. The report reads "Skipped 2 names (x, x)" otherwise.
             if (!outcome.reconciled.includes(name))
                 outcome.reconciled.push(name);
             continue;
@@ -237,7 +237,7 @@ async function deleteEmptyCustomOrphans(projectRoot, freshConfig, customNames, o
             // `rmdir`, not `rm`: `rm` without `{ recursive: true }` throws EISDIR on
             // a directory, so on a real filesystem this branch always failed and the
             // "deleted N empty directories" report was unreachable. `rmdir` is also
-            // the exact semantics wanted here — it refuses a non-empty directory,
+            // the exact semantics wanted here: it refuses a non-empty directory,
             // which keeps the emptiness check above from being the only safeguard.
             await rmdir(dir);
             outcome.deleted.push(name);

package/dist/src/commands/doctor-furnace-jar.d.ts

@@ -8,7 +8,7 @@ import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /**
  * "Furnace jar.mn registrations" check: detect widget registration lines
  * pointing at component files that no longer exist in the workspace,
- * typically left by a rename. These break `mach build` at packaging;
+ * typically left by a rename. These break `mach build` at packaging.
  * `--repair-furnace` prunes them.
  */
 export declare const furnaceStaleJarRegistrationCheck: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-jar.js

@@ -12,7 +12,7 @@ import { failure, ok, warning } from './doctor-check-core.js';
 /**
  * "Furnace jar.mn registrations" check: detect widget registration lines
  * pointing at component files that no longer exist in the workspace,
- * typically left by a rename. These break `mach build` at packaging;
+ * typically left by a rename. These break `mach build` at packaging.
  * `--repair-furnace` prunes them.
  */
 export const furnaceStaleJarRegistrationCheck = {

package/dist/src/commands/doctor-furnace.js

@@ -50,7 +50,7 @@ async function clearPendingRepairMarker(projectRoot) {
  * `stock` and name is the tag name.
  *
  * Stock components are never checksummed by apply, so they never appear
- * in the state file — any stock-prefixed entry is automatically stale.
+ * in the state file, so any stock-prefixed entry is automatically stale.
  */
 function collectStaleChecksumKeys(appliedChecksums, config) {
     const stale = [];
@@ -103,7 +103,7 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             }
         }
         catch {
-            // Drift check throws on unreadable paths; treat as drift so the
+            // Drift check throws on unreadable paths. Treat as drift so the
             // operator is told to run apply rather than swallowing the error.
             drifted.push(name);
         }
@@ -120,9 +120,9 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             }
         }
         catch {
-            // A drift probe that cannot complete is reported AS drift: the doctor check
-            // must not claim a component is clean when it failed to look. Mirrors the
-            // documented twin above.
+            // A drift probe that cannot complete is reported as drift: the doctor
+            // check must not claim a component is clean when it failed to look.
+            // Mirrors the documented twin above.
             drifted.push(name);
         }
     }
@@ -182,7 +182,7 @@ const furnaceStateConsistencyCheck = {
         }
         const ghostSet = new Set();
         for (const key of staleKeys) {
-            // Keys look like "override/<name>/<file>" — the ghost component is
+            // Keys look like "override/<name>/<file>", so the ghost component is
             // the first two segments joined for display purposes.
             const segments = key.split('/');
             if (segments.length >= 2) {
@@ -214,14 +214,14 @@ const furnaceStateConsistencyCheck = {
 };
 /**
  * "Furnace engine state" check: detect the `pendingRepair` marker set by
- * a failed preview teardown AND any on-disk drift between the workspace
+ * a failed preview teardown and any on-disk drift between the workspace
  * and the engine. Repair runs `applyAllComponents` to reconcile and
  * clears the marker on success.
  */
 const furnaceEngineStateCheck = {
     name: 'Furnace engine state',
     dependsOn: ['Furnace configuration'],
-    // Requires both a furnace project AND an engine checkout — the drift
+    // Requires both a furnace project and an engine checkout: the drift
     // oracles resolve engine paths, so a missing engine dir would throw.
     skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig || !ctx.engineExists,
     run: async (ctx) => {
@@ -286,16 +286,16 @@ const furnaceEngineStateCheck = {
         }
         // Repair path: run apply to reconcile the engine with the workspace
         // state, then clear the pendingRepair marker on success. We re-run
-        // apply even when only the marker is set — the marker exists
-        // specifically because the last mutation could not clean up, so the
-        // cheapest honest thing we can do is re-reconcile end-to-end.
+        // apply even when only the marker is set. The marker exists
+        // specifically because the last mutation could not clean up, so
+        // re-reconciling end-to-end is the cheapest honest thing to do.
         try {
             const applyResult = await runRepairApply(ctx.projectRoot);
             const totalFailures = countApplyFailures(applyResult);
             if (totalFailures > 0) {
                 return failure('Furnace engine state', `Repair attempted but apply reported ${totalFailures} failure${totalFailures === 1 ? '' : 's'} (first: ${firstApplyFailure(applyResult)}).`, 'Fix the underlying component issue and retry the doctor command.');
             }
-            // Apply succeeded — clear the pendingRepair marker so subsequent
+            // Apply succeeded, so clear the pendingRepair marker so subsequent
             // doctor runs stop reporting the issue. updateFurnaceState merges
             // its return value via `validateFurnaceState` which simply writes
             // whatever object we return, so dropping the key from the spread
@@ -356,9 +356,9 @@ const furnaceEnginePathsCheck = {
 /**
  * Furnace Storybook backend check: verifies that the engine contains the
  * Storybook workspace required by `furnace preview`. Missing Storybook
- * support is a warning, not a failure, since furnace works fine without
- * preview — but operators should know upfront rather than discovering it
- * mid-command.
+ * support is a warning rather than a failure, since furnace works fine
+ * without preview. Operators should still know upfront rather than
+ * discovering it mid-command.
  */
 const furnaceStorybookCheck = {
     name: 'Furnace Storybook backend',
@@ -422,7 +422,7 @@ const furnaceComponentValidationCheck = {
 /**
  * Reads the owner PID from a furnace lock directory. Returns `null` when
  * the PID file is missing, unreadable, or does not parse as a finite
- * integer — the caller then falls back to an age-only heuristic.
+ * integer. The caller then falls back to an age-only heuristic.
  */
 async function readFurnaceLockPid(lockPath) {
     try {
@@ -443,10 +443,10 @@ async function readFurnaceLockPid(lockPath) {
  *
  * This is the recovery path when the signal-handler sweep
  * (`forceReleaseFurnaceLocksForActiveOperations` in `bin/fireforge.ts`)
- * misses — a SIGKILL'd process that never ran the handler, or a lock created
+ * misses: a SIGKILL'd process that never ran the handler, or a lock created
  * by an older FireForge release without a PID file. SIGINT'ing `furnace
  * preview` leaves the lock behind, and the next `fireforge test --build`
- * then times out waiting for it; `doctor --repair-furnace` clears it so the
+ * then times out waiting for it. `doctor --repair-furnace` clears it so the
  * next command runs immediately.
  */
 const furnaceStaleLockCheck = {
@@ -464,12 +464,12 @@ const furnaceStaleLockCheck = {
         const ageSuffix = ageMs !== undefined ? ` (age: ${Math.round(ageMs / 1000)}s)` : '';
         // Two signals mark a lock as stale:
         //   1. PID file says owner is dead → unambiguous, remove immediately.
-        //   2. PID file absent AND lock is older than 60s → older FireForge
+        //   2. PID file absent and lock is older than 60s → older FireForge
         //      releases (or an externally-created lock directory) fall into this
-        //      bucket; the age gate avoids false positives on a lock just
+        //      bucket. The age gate avoids false positives on a lock just
         //      acquired by a concurrent process that has not written its PID yet.
         //
-        // `isProcessAlive` treats EPERM as ALIVE. Returning false for EPERM
+        // `isProcessAlive` treats EPERM as alive. Returning false for EPERM
         // reports a furnace lock held by a live process owned by another uid as
         // "owner is no longer running", and --repair-furnace then deletes it,
         // dropping mutual exclusion under a concurrent furnace operation.
@@ -477,7 +477,7 @@ const furnaceStaleLockCheck = {
         const pidMissingAndOld = pid === null && (ageMs ?? 0) > 60_000;
         const isStale = ownerDead || pidMissingAndOld;
         if (!isStale) {
-            // Lock is held by a running FireForge process — nothing to report.
+            // Lock is held by a running FireForge process, so nothing to report.
             return ok('Furnace lock');
         }
         const description = ownerDead

package/dist/src/commands/doctor-orphaned-harness.d.ts

@@ -1,20 +1,19 @@
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers.
+ * Doctor check for pre-existing orphaned test-harness workers.
  *
  * A mach invocation that dies at harness startup can strand a Python
- * `multiprocessing` spawn worker plus its resource tracker; the worker
+ * `multiprocessing` spawn worker plus its resource tracker. The worker
  * reparents to launchd (PPID 1) and busy-spins at 100% CPU indefinitely.
- * The dispatch-side fix is the process-group reaping in `utils/process.ts`;
- * this check covers orphans that predate it (or leaked from non-FireForge
+ * The dispatch-side fix is the process-group reaping in `utils/process.ts`.
+ * This check covers orphans that predate it (or leaked from non-FireForge
  * invocations), detecting them by PPID 1 + large accumulated CPU TIME + a
  * `multiprocessing.spawn`/`resource_tracker` command line.
  *
- * Report-only by design: FireForge never kills pre-existing processes it did
- * not spawn — the check names each candidate and suggests the kill.
+ * Report-only: FireForge never kills pre-existing processes it did not
+ * spawn, so the check names each candidate and suggests the kill.
  *
- * Deliberately not wired into `test --canary`: a system-wide process scan on
- * the canary hot path buys no coverage the doctor check does not already
- * give.
+ * Not wired into `test --canary`: a system-wide process scan on the canary
+ * hot path buys no coverage the doctor check does not already give.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /** One process matching the orphaned-harness-worker shape. */
@@ -31,11 +30,11 @@ export interface OrphanedHarnessWorker {
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
  * workers: PPID 1 (reparented to init/launchd), a multiprocessing
  * worker/tracker command line, and at least `minCpuSeconds` of accumulated
- * CPU time. Pure — fixture-testable without spawning anything.
+ * CPU time. Pure, so it is fixture-testable without spawning anything.
  */
 export declare function findOrphanedHarnessWorkers(psOutput: string, minCpuSeconds?: number): OrphanedHarnessWorker[];
 /**
- * Doctor check reporting orphaned harness workers. Windows has no `ps`;
+ * Doctor check reporting orphaned harness workers. Windows has no `ps`, so
  * the check is skipped there (best-effort platform gap, matching the
  * process-group reaper's POSIX-only sweep).
  */

package/dist/src/commands/doctor-orphaned-harness.js

@@ -1,21 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers.
+ * Doctor check for pre-existing orphaned test-harness workers.
  *
  * A mach invocation that dies at harness startup can strand a Python
- * `multiprocessing` spawn worker plus its resource tracker; the worker
+ * `multiprocessing` spawn worker plus its resource tracker. The worker
  * reparents to launchd (PPID 1) and busy-spins at 100% CPU indefinitely.
- * The dispatch-side fix is the process-group reaping in `utils/process.ts`;
- * this check covers orphans that predate it (or leaked from non-FireForge
+ * The dispatch-side fix is the process-group reaping in `utils/process.ts`.
+ * This check covers orphans that predate it (or leaked from non-FireForge
  * invocations), detecting them by PPID 1 + large accumulated CPU TIME + a
  * `multiprocessing.spawn`/`resource_tracker` command line.
  *
- * Report-only by design: FireForge never kills pre-existing processes it did
- * not spawn — the check names each candidate and suggests the kill.
+ * Report-only: FireForge never kills pre-existing processes it did not
+ * spawn, so the check names each candidate and suggests the kill.
  *
- * Deliberately not wired into `test --canary`: a system-wide process scan on
- * the canary hot path buys no coverage the doctor check does not already
- * give.
+ * Not wired into `test --canary`: a system-wide process scan on the canary
+ * hot path buys no coverage the doctor check does not already give.
  */
 import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
@@ -33,7 +32,7 @@ const DEFAULT_MIN_CPU_SECONDS = 600;
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
  * workers: PPID 1 (reparented to init/launchd), a multiprocessing
  * worker/tracker command line, and at least `minCpuSeconds` of accumulated
- * CPU time. Pure — fixture-testable without spawning anything.
+ * CPU time. Pure, so it is fixture-testable without spawning anything.
  */
 export function findOrphanedHarnessWorkers(psOutput, minCpuSeconds = DEFAULT_MIN_CPU_SECONDS) {
     const workers = [];
@@ -88,7 +87,7 @@ async function runOrphanedHarnessCheck() {
         'FireForge never kills pre-existing processes automatically.');
 }
 /**
- * Doctor check reporting orphaned harness workers. Windows has no `ps`;
+ * Doctor check reporting orphaned harness workers. Windows has no `ps`, so
  * the check is skipped there (best-effort platform gap, matching the
  * process-group reaper's POSIX-only sweep).
  */

package/dist/src/commands/doctor-patch-manifest.d.ts

@@ -1,7 +1,8 @@
 /**
  * The patch-manifest consistency check and its two repair paths, split out of
  * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
- * consumed by the doctor registry; no registrar is exported and none is wanted.
+ * consumed by the doctor registry. No registrar is exported and none is
+ * wanted.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /** Patch manifest consistency check, with its opt-in repair paths. */

package/dist/src/commands/doctor-patch-manifest.js

@@ -2,7 +2,8 @@
 /**
  * The patch-manifest consistency check and its two repair paths, split out of
  * `doctor.ts` for the line budget. Exports a single `DoctorCheckDefinition`
- * consumed by the doctor registry; no registrar is exported and none is wanted.
+ * consumed by the doctor registry. No registrar is exported and none is
+ * wanted.
  */
 import { rebuildPatchesManifest, recommendManifestRepair, repairPatchesFilesAffected, validatePatchesManifestConsistency, } from '../core/patch-manifest.js';
 import { FireForgeError } from '../errors/base.js';
@@ -65,8 +66,8 @@ function describeCount(count) {
 async function runManifestRebuild(ctx) {
     // Repair stamps sourceEsrVersion into every recovered entry. If the
     // earlier "fireforge.json is valid" check failed, ctx.config is
-    // undefined and we must refuse rather than fabricate a fallback —
-    // persisting 'unknown' into manifest metadata is hard to reverse
+    // undefined and we must refuse rather than fabricate a fallback.
+    // Persisting 'unknown' into manifest metadata is hard to reverse
     // and would mislead every later command that reads it.
     if (!ctx.config) {
         return failure(CHECK_NAME, 'Cannot repair patches.json: fireforge.json could not be loaded, so the Firefox version to stamp into recovered manifest entries is unknown.', 'Fix the fireforge.json errors reported above and re-run "fireforge doctor --repair-patches-manifest". ' +
@@ -84,7 +85,7 @@ async function runManifestRebuild(ctx) {
     // trustworthy as an audit trail. The rebuilder returns the list of
     // filenames whose metadata was entirely invented, named explicitly
     // here so the operator knows which patches to review. Entries that
-    // WERE preserved (only `filesAffected` / ordering drifted) are not
+    // were preserved (only `filesAffected` / ordering drifted) are not
     // flagged.
     for (const filename of repaired.recoveredFilenames) {
         // Telling the operator to hand-edit patches.json contradicts the
@@ -101,8 +102,8 @@ async function runManifestRebuild(ctx) {
             'Avoid hand-editing patches.json — FireForge owns that file and will regenerate it on the next manifest consistency pass.');
     }
     // A row whose patch file is gone is dropped by the rebuild. That is
-    // correct — the patch file is the source of truth — but a manifest that
-    // quietly loses rows is exactly what makes a repair hard to audit
+    // correct, since the patch file is the source of truth, but a manifest
+    // that quietly loses rows is what makes a repair hard to audit
     // afterwards, so each one is named.
     for (const filename of repaired.droppedFilenames) {
         warn(`Dropped the manifest entry for ${filename}: no such patch file on disk. ` +

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

@@ -16,7 +16,7 @@ async function readEngineText(engineDir, relativePath) {
  * 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
+ * mid-walk EACCES also silently shrank the result set, so one unreadable
  * subdirectory produced a false clean for that subtree.
  */
 async function collectBrowserTomlFiles(root) {
@@ -54,7 +54,7 @@ async function runPostRebaseAudit(ctx) {
     // 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
+    // as one of these going missing. The tokens are coarse on purpose: 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');

package/dist/src/commands/doctor-source-pin.d.ts

@@ -1,29 +1,29 @@
 /**
- * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * Doctor check comparing the configured Firefox source pin against what the
  * engine checkout actually is.
  *
  * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
  * beside hand-maintained policy sections. That is convenient and it is also
- * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
- * accidental reformat, say — silently reverts an uncommitted pin along with
+ * the whole problem: a routine `git checkout -- fireforge.json` (undoing an
+ * accidental reformat, say) silently reverts an uncommitted pin along with
  * it, and nothing afterwards reports that the pin and the checkout have
- * diverged. The tell in the field was a gate flipping green with no change
- * that should have made it green.
+ * diverged. In the field this showed up as a gate flipping green with no
+ * change that should have made it green.
  *
- * This is deliberately not a lock and not a refusal: a tree may legitimately
- * be mid-migration between two versions. It only makes a mismatched tree
- * VISIBLE, which is all that was missing.
+ * This is not a lock and not a refusal: a tree may legitimately be
+ * mid-migration between two versions. It only makes a mismatched tree
+ * visible, which is all that was missing.
  *
  * Scope is limited by what is actually recorded. `firefox.product`,
- * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
- * disk — `.fireforge/state.json` records only `downloadedVersion` and
- * `baseCommit` — so there is nothing to compare them against and the check
+ * `firefox.sha256` and `firefox.candidate` have no counterpart anywhere on
+ * disk (`.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit`), so there is nothing to compare them against and the check
  * says nothing about them rather than implying it verified them.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /**
  * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
- * dependency on the config check that populates `ctx.config`; skipped
+ * dependency on the config check that populates `ctx.config`. It is skipped
  * entirely without an engine, where there is nothing to compare.
  */
 export declare const SOURCE_PIN_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-source-pin.js

@@ -1,24 +1,24 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * Doctor check comparing the configured Firefox source pin against what the
  * engine checkout actually is.
  *
  * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
  * beside hand-maintained policy sections. That is convenient and it is also
- * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
- * accidental reformat, say — silently reverts an uncommitted pin along with
+ * the whole problem: a routine `git checkout -- fireforge.json` (undoing an
+ * accidental reformat, say) silently reverts an uncommitted pin along with
  * it, and nothing afterwards reports that the pin and the checkout have
- * diverged. The tell in the field was a gate flipping green with no change
- * that should have made it green.
+ * diverged. In the field this showed up as a gate flipping green with no
+ * change that should have made it green.
  *
- * This is deliberately not a lock and not a refusal: a tree may legitimately
- * be mid-migration between two versions. It only makes a mismatched tree
- * VISIBLE, which is all that was missing.
+ * This is not a lock and not a refusal: a tree may legitimately be
+ * mid-migration between two versions. It only makes a mismatched tree
+ * visible, which is all that was missing.
  *
  * Scope is limited by what is actually recorded. `firefox.product`,
- * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
- * disk — `.fireforge/state.json` records only `downloadedVersion` and
- * `baseCommit` — so there is nothing to compare them against and the check
+ * `firefox.sha256` and `firefox.candidate` have no counterpart anywhere on
+ * disk (`.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit`), so there is nothing to compare them against and the check
  * says nothing about them rather than implying it verified them.
  */
 import { getFirefoxVersion } from '../core/firefox.js';
@@ -40,8 +40,8 @@ async function runSourcePinCheck(ctx) {
     let actual;
     try {
         // A blank or whitespace-only version.txt (a truncated write, a partial
-        // extraction) carries no version to compare — treat it as absent rather
-        // than reporting the engine as being at version "".
+        // extraction) carries no version to compare, so treat it as absent
+        // rather than reporting the engine as being at version "".
         actual = (await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
     }
     catch (error) {
@@ -70,7 +70,7 @@ async function runSourcePinCheck(ctx) {
 }
 /**
  * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
- * dependency on the config check that populates `ctx.config`; skipped
+ * dependency on the config check that populates `ctx.config`. It is skipped
  * entirely without an engine, where there is nothing to compare.
  */
 export const SOURCE_PIN_DOCTOR_CHECK = {

package/dist/src/commands/doctor-working-tree.d.ts

@@ -3,18 +3,18 @@
  *
  * Partitions engine-tree dirtiness into `branding`, `patch-backed`,
  * `furnace`, `conflict`, and `unmanaged` buckets, and only warns on the
- * last two — everything else is tool-managed state that the operator
+ * last two. Everything else is tool-managed state that the operator
  * did not author directly.
  *
  * Split out of `doctor.ts` so that file stays under the per-file LOC
- * budget; see the call site in `runEngineGitChecks`.
+ * budget. See the call site in `runEngineGitChecks`.
  */
 import type { DoctorCheck } from '../types/commands/index.js';
 import type { DoctorCheckContext } from './doctor-check-core.js';
 /**
  * Inspects the engine working tree and returns a single `DoctorCheck`.
  * Ownership-aware: patch-backed / branding / furnace rows are reported as OK
- * with an ownership summary; unmanaged drift warns; cross-patch conflicts
+ * with an ownership summary. Unmanaged drift warns. Cross-patch conflicts
  * warn loudly with a pointer at `fireforge status --ownership` +
  * `fireforge verify`.
  *