@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/commands/config.js

@@ -89,7 +89,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         throw new GeneralError('No fireforge.json found. Run "fireforge setup" to create a project.');
     }
     if (value === undefined) {
-        // Get mode — read the raw document rather than the validated config so
+        // Get mode: read the raw document rather than the validated config so
         // keys persisted via `fireforge config <key> --force` remain readable.
         // `validateConfig` builds a typed clone containing only the known schema
         // fields, so relying on it here would hide forced-write keys and surface
@@ -110,7 +110,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         }
     }
     else {
-        // Set mode — validate key prefix
+        // Set mode: validate key prefix
         const topLevelKey = key.split('.')[0] ?? key;
         if (!SUPPORTED_CONFIG_ROOT_KEYS.includes(topLevelKey) &&
             !options.force) {
@@ -126,7 +126,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             // Serialise the read → mutate → write round-trip behind the sidecar
             // config lock so two concurrent `fireforge config` invocations cannot
             // each read the pre-state, mutate their own copy, and clobber each
-            // other on write — both exiting 0 with one key silently lost. Atomic
+            // other on write, both exiting 0 with one key silently lost. Atomic
             // file writes (temp + rename) are not enough on their own: the lost
             // update happens before the rename, inside the read-modify step.
             // Readers stay lock-free (see `withConfigFileLock`).
@@ -143,12 +143,12 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                 if (deepEqual(currentValue, parsedValue)) {
                     return true;
                 }
-                // `--force` is an escape hatch for *unknown* keys; it must not also
-                // let the user write a structurally invalid value for a *known* key.
+                // `--force` is an escape hatch for unknown keys. It must not also
+                // let the user write a structurally invalid value for a known key.
                 // Strict validation applies whenever the key is listed in
                 // SUPPORTED_CONFIG_PATHS, regardless of --force.
                 //
-                // BOTH branches seed the mutation from the raw on-disk document.
+                // Both branches seed the mutation from the raw on-disk document.
                 // Round-tripping the known-key branch through `loadConfig` →
                 // `validateConfig` builds a typed clone containing only the known
                 // schema fields, so any ordinary `fireforge config <key> <value>`
@@ -160,7 +160,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                 }
                 else {
                     // Mutate the raw document (preserving unknown keys), then run
-                    // strict validation on the RESULT — validateConfig checks the
+                    // strict validation on the result. validateConfig checks the
                     // known schema fields and ignores unknown keys, so this keeps
                     // exactly the old validation strength while writing the
                     // unstripped document.
@@ -174,7 +174,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         catch (error) {
             // Only value/validation problems are the user's "invalid value".
             // Lock-acquisition timeouts and I/O failures must keep their own
-            // types and messages — re-labelling a lock timeout as `Invalid value
+            // types and messages. Re-labelling a lock timeout as `Invalid value
             // for "<key>"` points diagnosis at the value (and returns the wrong
             // exit-code class) when the real problem is a concurrent fireforge
             // process holding the config lock.
@@ -195,7 +195,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
 /**
  * Structural equality check covering the shapes `fireforge config` accepts:
  * primitives (strings, numbers, booleans), `null`, arrays of primitives, and
- * nested objects. Used to short-circuit no-op writes — when the parsed value
+ * nested objects. Used to short-circuit no-op writes: when the parsed value
  * matches the current on-disk value, the mutate + write step is skipped
  * entirely.
  */

package/dist/src/commands/destructive-decision.d.ts

@@ -0,0 +1,19 @@
+import type { DestructiveOpResult } from '../core/destructive.js';
+/**
+ * Closes out a {@link DestructiveOpResult} and says whether to run the
+ * mutation.
+ *
+ * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
+ * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
+ * The dry-run wording is a user-facing contract that must not drift between
+ * commands, so it lives here. The declined wording is per-command and stays
+ * a parameter.
+ *
+ * `confirmDestructive` never mutates on its own, so a caller that forgets this
+ * check silently performs a "dry run" for real. That is why this returns a
+ * boolean the caller must act on instead of being a helper that returns void.
+ * @param decision - The result from `confirmDestructive`.
+ * @param declinedOutro - Outro to print when the operator answered "no".
+ * @returns True when the caller should proceed with the mutation.
+ */
+export declare function proceedAfterDecision(decision: DestructiveOpResult, declinedOutro: string): boolean;

package/dist/src/commands/destructive-decision.js

@@ -0,0 +1,31 @@
+import { outro } from '../utils/logger.js';
+/** The dry-run outro every command prints, spelled once. */
+const DRY_RUN_OUTRO = 'Dry run complete — no changes made';
+/**
+ * Closes out a {@link DestructiveOpResult} and says whether to run the
+ * mutation.
+ *
+ * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
+ * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
+ * The dry-run wording is a user-facing contract that must not drift between
+ * commands, so it lives here. The declined wording is per-command and stays
+ * a parameter.
+ *
+ * `confirmDestructive` never mutates on its own, so a caller that forgets this
+ * check silently performs a "dry run" for real. That is why this returns a
+ * boolean the caller must act on instead of being a helper that returns void.
+ * @param decision - The result from `confirmDestructive`.
+ * @param declinedOutro - Outro to print when the operator answered "no".
+ * @returns True when the caller should proceed with the mutation.
+ */
+export function proceedAfterDecision(decision, declinedOutro) {
+    if (decision === 'dry-run') {
+        outro(DRY_RUN_OUTRO);
+        return false;
+    }
+    if (decision === 'declined') {
+        outro(declinedOutro);
+        return false;
+    }
+    return true;
+}

package/dist/src/commands/discard.js

@@ -103,7 +103,7 @@ async function discardDirectoryEntries(projectRoot, engineDir, patchesDir, dirPa
             }
         }
         catch {
-            // Furnace config may not exist — skip silently
+            // Furnace config may not exist, so skip silently.
         }
         if (failures.length > 0) {
             throw new GeneralError(`Failed to discard ${failures.length} file(s) under ${dirPath}/. See warnings above.`);
@@ -131,7 +131,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
     const statusEntries = await expandUntrackedDirectoryEntries(paths.engine, await getWorkingTreeStatus(paths.engine));
     const statusEntry = statusEntries.find((entry) => entry.file === file || entry.originalPath === file);
     // Directory recursion fallback: when the explicit path does not match a
-    // single status entry but DOES correspond to one or more entries below it,
+    // single status entry but does correspond to one or more entries below it,
     // treat the input as a directory and discard everything inside. Otherwise
     // `discard <dir> --yes` fails with "no changes to discard" even though
     // `status --unmanaged` lists files under that directory, forcing the
@@ -159,8 +159,8 @@ export async function discardCommand(projectRoot, file, options = {}) {
         throw new GeneralError(`File "${file}" has no changes to discard.`);
     }
     if (options.dryRun) {
-        // Show the rename pair regardless of which side the operator passed —
-        // passing the NEW path of a rename used to hide that discarding also
+        // Show the rename pair regardless of which side the operator passed.
+        // Passing the new path of a rename used to hide that discarding also
         // resurrects the old path, exactly when the full picture matters most.
         info(`Would discard changes to: ${dryRunLabel(plan)}`);
         outro('Dry run complete — no changes made');
@@ -182,7 +182,7 @@ export async function discardCommand(projectRoot, file, options = {}) {
             }
         }
         catch {
-            // Furnace config may not exist — skip silently
+            // Furnace config may not exist, so skip silently.
         }
         outro(describeDiscardOutcome(plan, options.toUpstream === true));
     }

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.
      */
@@ -96,12 +96,6 @@ export interface DoctorCheckDefinition {
      */
     fix?: string;
 }
-/**
- * Resolves a {@link DoctorCheck} to its effective severity. `severity` is the
- * single source of truth; this exists so every consumer of a
- * `DoctorCheck[]` reads it the same way.
- */
-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,14 +4,6 @@
  * `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. `severity` is the
- * single source of truth; this exists so every consumer of a
- * `DoctorCheck[]` reads it the same way.
- */
-export function resolveDoctorSeverity(check) {
-    return check.severity;
-}
 /**
  * Builds a DoctorCheck object representing a successful "OK" check.
  */

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. */
@@ -27,21 +26,15 @@ export interface OrphanedHarnessWorker {
     cpuSeconds: number;
     command: string;
 }
-/**
- * Parses a `ps` TIME (accumulated CPU) value. Implemented in terms of
- * {@link parsePsDuration} — `time=` and `etime=` share one grammar, and a
- * second copy is how the two would drift.
- */
-export declare function parseCpuTime(time: string): number;
 /**
  * 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).
  */