@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -1,10 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `doctor` check for stale furnace jar.mn registrations (0.34.0 field
- * report): a component-file rename left the old toolkit jar.mn line
- * pointing at the deleted file, every build failed at packaging, and
- * `doctor --repair-furnace` reported success without pruning. Split out
- * of `doctor-furnace.ts` to keep that file within the line budget.
+ * `doctor` check for stale furnace jar.mn registrations: a component-file
+ * rename can leave the old toolkit jar.mn line pointing at the deleted file,
+ * failing every build at packaging. Split out of `doctor-furnace.ts` to keep
+ * that file within the line budget.
  */
 import { getFurnacePaths } from '../core/furnace-config.js';
 import { findStaleJarMnEntries, pruneStaleJarMnEntries } from '../core/furnace-registration.js';
@@ -12,10 +11,9 @@ import { toError } from '../utils/errors.js';
 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 under an older FireForge). These break
- * `mach build` at packaging; `--repair-furnace` prunes them (0.34.0 field
- * report: doctor --repair-furnace reported success without pruning).
+ * pointing at component files that no longer exist in the workspace,
+ * typically left by a rename. These break `mach build` at packaging;
+ * `--repair-furnace` prunes them.
  */
 export const furnaceStaleJarRegistrationCheck = {
     name: 'Furnace jar.mn registrations',

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

@@ -4,15 +4,15 @@ import { join } from 'node:path';
 import { applyAllComponents } from '../core/furnace-apply.js';
 import { hasCustomEngineDrift, hasOverrideEngineDrift } from '../core/furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from '../core/furnace-config.js';
-import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from '../core/furnace-constants.js';
+import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir, WIDGETS_DIR, } from '../core/furnace-constants.js';
 import { getFurnaceLockPath, runFurnaceMutation } from '../core/furnace-operation.js';
 import { hasBlockingStepErrors } from '../core/furnace-step-errors.js';
 import { validateAllComponents } from '../core/furnace-validate.js';
 import { isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+import { furnaceConfigSyncCheck } from './doctor-furnace-config-sync.js';
 import { furnaceStaleJarRegistrationCheck } from './doctor-furnace-jar.js';
-import { furnaceManifestSyncCheck } from './doctor-furnace-manifest-sync.js';
 const ENGINE_REPAIRABLE_OPERATIONS = [
     'preview-teardown',
     'apply-rollback',
@@ -98,7 +98,7 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             continue;
         }
         try {
-            if (await hasOverrideEngineDrift(engineDir, componentDir, overrideConfig, ftlDir)) {
+            if (await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig)) {
                 drifted.push(name);
             }
         }
@@ -115,7 +115,7 @@ async function collectFurnaceDrift(projectRoot, engineDir, config, ftlDir) {
             continue;
         }
         try {
-            if (await hasCustomEngineDrift(projectRoot, name, componentDir, customConfig, ftlDir)) {
+            if (await hasCustomEngineDrift({ root: projectRoot, name, componentDir, ftlDir }, customConfig)) {
                 drifted.push(name);
             }
         }
@@ -336,7 +336,7 @@ const furnaceEnginePathsCheck = {
         const expectedPaths = [
             CUSTOM_ELEMENTS_JS,
             JAR_MN,
-            'toolkit/content/widgets',
+            WIDGETS_DIR,
             resolveFtlDir(ctx.furnaceConfig?.ftlBasePath),
             ...hostDocs,
         ];
@@ -437,18 +437,17 @@ async function readFurnaceLockPid(lockPath) {
     }
 }
 /**
- * "Furnace stale lock" check: detect and (under `--repair-furnace`)
- * remove a `.fireforge/furnace.lock` directory whose owner process is no
- * longer alive.
+ * "Furnace stale lock" check: detect and (under `--repair-furnace`) remove a
+ * `.fireforge/furnace.lock` directory whose owner process is no longer
+ * alive.
  *
  * This is the recovery path when the signal-handler sweep
  * (`forceReleaseFurnaceLocksForActiveOperations` in `bin/fireforge.ts`)
- * misses — e.g. a SIGKILL'd process that never got to run the handler, or
- * a lock created by an older FireForge release without a PID file. The
- * motivating eval scenario: SIGINT'ing `furnace preview` left the lock
- * behind, and the next `fireforge test --build` timed out waiting for it.
- * `doctor --repair-furnace` now clears the lock explicitly so the next
- * command runs immediately.
+ * 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
+ * next command runs immediately.
  */
 const furnaceStaleLockCheck = {
     name: 'Furnace lock',
@@ -466,16 +465,14 @@ const furnaceStaleLockCheck = {
         // 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
-        //      releases (or an externally-created lock directory) fall into
-        //      this bucket; the age gate avoids false positives on a lock
-        //      that was just acquired by a concurrent process that hadn't
-        //      written its PID yet.
+        //      releases (or an externally-created lock directory) fall into this
+        //      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. The local copy it replaced
-        // returned false for EPERM, so a furnace lock held by a live process
-        // owned by another uid was reported as "owner is no longer running"
-        // and deleted by --repair-furnace, dropping mutual exclusion under a
-        // concurrent furnace operation.
+        // `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.
         const ownerDead = pid !== null && !isProcessAlive(pid);
         const pidMissingAndOld = pid === null && (ageMs ?? 0) > 60_000;
         const isStale = ownerDead || pidMissingAndOld;
@@ -513,5 +510,5 @@ export const FURNACE_DOCTOR_CHECKS = [
     furnaceStaleLockCheck,
     furnaceEngineStateCheck,
     furnaceComponentValidationCheck,
-    furnaceManifestSyncCheck,
+    furnaceConfigSyncCheck,
 ];

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

@@ -1,23 +1,20 @@
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
- * item 9b).
+ * Doctor check for PRE-EXISTING orphaned test-harness workers.
  *
- * Field incident: a mach invocation that died at harness startup stranded a
- * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
- * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
- * days (~415 CPU-hours) undetected. 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), using the
- * detection recipe that found the incident process: PPID 1 + large
- * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
- * command line.
+ * A mach invocation that dies at harness startup can strand a Python
+ * `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
+ * 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 by design: FireForge never kills pre-existing processes it did
+ * not spawn — the check names each candidate and suggests the kill.
  *
- * Canary integration was deliberately skipped: the friction log asked for
- * doctor AND/OR `test --canary`, and adding a system-wide process scan to
- * the canary hot path buys no extra coverage over the doctor check.
+ * 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.
  */
 import type { DoctorCheckDefinition } from './doctor-check-core.js';
 /** One process matching the orphaned-harness-worker shape. */
@@ -31,10 +28,9 @@ export interface OrphanedHarnessWorker {
     command: string;
 }
 /**
- * Parses a `ps` TIME value in either dialect:
- *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
- *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
- * Returns NaN for unrecognized shapes.
+ * 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;
 /**

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

@@ -1,27 +1,25 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
- * item 9b).
+ * Doctor check for PRE-EXISTING orphaned test-harness workers.
  *
- * Field incident: a mach invocation that died at harness startup stranded a
- * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
- * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
- * days (~415 CPU-hours) undetected. 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), using the
- * detection recipe that found the incident process: PPID 1 + large
- * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
- * command line.
+ * A mach invocation that dies at harness startup can strand a Python
+ * `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
+ * 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 by design: FireForge never kills pre-existing processes it did
+ * not spawn — the check names each candidate and suggests the kill.
  *
- * Canary integration was deliberately skipped: the friction log asked for
- * doctor AND/OR `test --canary`, and adding a system-wide process scan to
- * the canary hot path buys no extra coverage over the doctor check.
+ * 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.
  */
 import { toError } from '../utils/errors.js';
 import { exec } from '../utils/process.js';
+import { parsePsDuration } from '../utils/ps-duration.js';
 import { ok, warning } from './doctor-check-core.js';
 /**
  * Command-line shapes of Python multiprocessing helper processes: the
@@ -32,36 +30,12 @@ const HARNESS_WORKER_COMMAND_PATTERN = /multiprocessing\.(?:spawn|forkserver)\b|
 /** Minimum accumulated CPU time before a match is reported (10 minutes). */
 const DEFAULT_MIN_CPU_SECONDS = 600;
 /**
- * Parses a `ps` TIME value in either dialect:
- *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
- *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
- * Returns NaN for unrecognized shapes.
+ * 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 function parseCpuTime(time) {
-    const trimmed = time.trim();
-    let days = 0;
-    let rest = trimmed;
-    const dayMatch = /^(\d+)-(.*)$/.exec(trimmed);
-    if (dayMatch) {
-        days = Number(dayMatch[1]);
-        rest = dayMatch[2] ?? '';
-    }
-    const parts = rest.split(':');
-    if (parts.length === 3) {
-        // hh:mm:ss (linux; seconds may not carry fractions but tolerate them)
-        const [h, m, s] = parts.map(Number);
-        if ([h, m, s].some((n) => Number.isNaN(n)))
-            return NaN;
-        return days * 86400 + (h ?? 0) * 3600 + (m ?? 0) * 60 + (s ?? 0);
-    }
-    if (parts.length === 2) {
-        // mm:ss.cc (darwin — the minutes field accumulates without wrapping)
-        const [m, s] = parts.map(Number);
-        if ([m, s].some((n) => Number.isNaN(n)))
-            return NaN;
-        return days * 86400 + (m ?? 0) * 60 + (s ?? 0);
-    }
-    return NaN;
+    return parsePsDuration(time);
 }
 /**
  * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness

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

@@ -0,0 +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.
+ */
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** Patch manifest consistency check, with its opt-in repair paths. */
+export declare const PATCH_MANIFEST_CONSISTENCY_CHECK: DoctorCheckDefinition;

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

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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.
+ */
+import { rebuildPatchesManifest, recommendManifestRepair, repairPatchesFilesAffected, validatePatchesManifestConsistency, } from '../core/patch-manifest.js';
+import { FireForgeError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { info, warn } from '../utils/logger.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+import { failure, ok, warning } from './doctor-check-core.js';
+const CHECK_NAME = 'Patch manifest consistency';
+/** Runs the narrow `filesAffected` repair over the drifted rows. */
+async function runFilesAffectedRepair(ctx, issues) {
+    const drifted = issues.filter((issue) => issue.code === 'files-affected-mismatch');
+    const otherCodes = [
+        ...new Set(issues.filter((issue) => issue.code !== 'files-affected-mismatch').map((issue) => issue.code)),
+    ].sort((left, right) => left.localeCompare(right));
+    if (drifted.length === 0) {
+        return failure(CHECK_NAME, `--repair-files-affected has nothing to repair: no filesAffected drift, but ${issues.length} ` +
+            `other issue(s) remain (${otherCodes.join(', ')}).`, recommendManifestRepair(issues));
+    }
+    const dryRun = ctx.options.dryRun === true;
+    const result = await repairPatchesFilesAffected(ctx.paths.patches, drifted.map((issue) => issue.filename), {
+        waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
+        command: 'doctor --repair-files-affected',
+        dryRun,
+    });
+    for (const repair of result.repairs) {
+        info(`  ${describeFilesAffectedRepair(repair, dryRun)}`);
+    }
+    for (const filename of result.skippedFilenames) {
+        warn(`Skipped ${filename}: it has no manifest row, or no patch file on disk. ` +
+            'That is a different consistency issue — re-run doctor without --repair-files-affected ' +
+            'to see it reported.');
+    }
+    if (result.written) {
+        ctx.mutations.push(`patches/patches.json — filesAffected corrected on ${describeCount(result.repairs.length)} (--repair-files-affected)`);
+    }
+    const remaining = otherCodes.length > 0
+        ? ` ${otherCodes.length} other issue type(s) remain: ${otherCodes.join(', ')}.`
+        : '';
+    if (otherCodes.length > 0) {
+        return failure(CHECK_NAME, `${summarizeFilesAffected(result.repairs.length, dryRun)}${remaining}`, recommendManifestRepair(issues.filter((issue) => issue.code !== 'files-affected-mismatch')));
+    }
+    return warning(CHECK_NAME, summarizeFilesAffected(result.repairs.length, dryRun));
+}
+function describeFilesAffectedRepair(repair, dryRun) {
+    const verb = dryRun ? 'would set' : 'set';
+    return `${repair.filename}: ${verb} filesAffected to ${repair.after.length} file(s) (was ${repair.before.length}).`;
+}
+function summarizeFilesAffected(count, dryRun) {
+    if (count === 0)
+        return 'No filesAffected drift to repair.';
+    return dryRun
+        ? `Dry run — would correct filesAffected on ${describeCount(count)}. Nothing was written.`
+        : `Corrected filesAffected on ${describeCount(count)}. No other manifest field was touched.`;
+}
+function describeCount(count) {
+    return `${count} patch${count === 1 ? '' : 'es'}`;
+}
+/** Runs the whole-manifest rebuild. */
+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
+    // 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". ' +
+            'If the drift is only in filesAffected, "fireforge doctor --repair-files-affected" needs no config.');
+    }
+    const dryRun = ctx.options.dryRun === true;
+    const repaired = await rebuildPatchesManifest(ctx.paths.patches, ctx.config.firefox.version, {
+        waitLockSeconds: resolveWaitLockSeconds(ctx.options.waitLock),
+        command: 'doctor --repair-patches-manifest',
+        dryRun,
+        ...(ctx.options.allowMetadataLoss === true ? { allowMetadataLoss: true } : {}),
+    });
+    // The repair path must not silently overwrite human-written
+    // descriptions on recovered entries, which leaves the queue less
+    // 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
+    // flagged.
+    for (const filename of repaired.recoveredFilenames) {
+        // Telling the operator to hand-edit patches.json contradicts the
+        // README and downstream docs, which treat the manifest as
+        // FireForge-owned. Point at the existing `re-export` / `export`
+        // workflow so the fix stays inside the tool: re-exporting the
+        // same files with an explicit `--description` overwrites the
+        // recovered entry with operator-supplied metadata and supersedes
+        // the mtime-based createdAt stamp.
+        warn(`Recovered manifest entry for ${filename} with generic description and mtime-based createdAt. ` +
+            'Re-export the affected files with `fireforge re-export <filename> --description "<your description>"` ' +
+            '(or `fireforge export <paths...> --name <name> --category <category> --description "<your description>"`) ' +
+            'to overwrite the reconstructed metadata, or accept the generic description if the original text is not recoverable. ' +
+            '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
+    // 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. ` +
+            'Restore the .patch file and re-run the repair if the entry should have survived.');
+    }
+    if (repaired.written) {
+        ctx.mutations.push('patches/patches.json — rebuilt from the on-disk patch files (--repair-patches-manifest)');
+    }
+    const patchCount = repaired.manifest.patches.length;
+    const recovered = repaired.recoveredFilenames.length > 0
+        ? ` (${repaired.recoveredFilenames.length} with reconstructed metadata — see warnings above)`
+        : '';
+    return warning(CHECK_NAME, dryRun
+        ? `Dry run — would rebuild patches.json from ${describeCount(patchCount)}${recovered}. Nothing was written.`
+        : `Rebuilt patches.json from ${describeCount(patchCount)}${recovered}. Review recovered metadata before release.`);
+}
+/** Patch manifest consistency check, with its opt-in repair paths. */
+export const PATCH_MANIFEST_CONSISTENCY_CHECK = {
+    name: CHECK_NAME,
+    dependsOn: ['fireforge.json is valid'],
+    run: async (ctx) => {
+        if (!(await pathExists(ctx.paths.patches))) {
+            return [];
+        }
+        const issues = await validatePatchesManifestConsistency(ctx.paths.patches);
+        if (issues.length === 0) {
+            return ok(CHECK_NAME);
+        }
+        const wantsFilesAffected = ctx.options.repairFilesAffected === true;
+        const wantsRebuild = ctx.options.repairPatchesManifest === true;
+        if (!wantsFilesAffected && !wantsRebuild) {
+            return failure(CHECK_NAME, issues.map((issue) => issue.message).join(' '), recommendManifestRepair(issues));
+        }
+        try {
+            return wantsFilesAffected
+                ? await runFilesAffectedRepair(ctx, issues)
+                : await runManifestRebuild(ctx);
+        }
+        catch (err) {
+            const error = toError(err);
+            // A refusal from the repair itself already carries the remedy that
+            // fits it (which flag, which file to fix). Appending the generic hint
+            // under it buries the specific one and reads as a second, vaguer
+            // instruction. Only an unexpected throw gets the generic hint.
+            return error instanceof FireForgeError
+                ? failure(CHECK_NAME, error.message)
+                : failure(CHECK_NAME, error.message, 'Repair failed. Fix the underlying patch metadata issue and retry the doctor command.');
+        }
+    },
+};

package/dist/src/commands/doctor-post-rebase-audit.d.ts

@@ -0,0 +1,2 @@
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+export declare const POST_REBASE_AUDIT_CHECK: DoctorCheckDefinition;

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

@@ -1,9 +1,9 @@
 // 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';
+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) {
     const fullPath = join(engineDir, relativePath);
     if (!(await pathExists(fullPath)))

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

@@ -12,18 +12,16 @@
 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 warn loudly with a pointer at
- * `fireforge status --ownership` + `fireforge verify`.
+ * 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
+ * warn loudly with a pointer at `fireforge status --ownership` +
+ * `fireforge verify`.
  *
- * Before 0.16.1 this check warned on every dirty row regardless of
- * ownership and told the operator to export/discard/reset — advice
- * that was actively destructive on a patch-backed import (eval
- * Finding: a correctly imported 126-file patch stack was reported as
- * unhealthy and the suggested fix would have dropped the entire
- * import). Returns `undefined` when the worktree is clean so the
- * caller can emit its own ok() row.
+ * Ownership is what makes the advice safe: warning on every dirty row and
+ * telling the operator to export/discard/reset is actively destructive on a
+ * patch-backed import, where the suggested fix would drop the entire patch
+ * stack. Returns `undefined` when the worktree is clean so the caller can
+ * emit its own ok() row.
  */
 export declare function inspectEngineWorkingTree(ctx: DoctorCheckContext): Promise<DoctorCheck | undefined>;

package/dist/src/commands/doctor-working-tree.js

@@ -28,19 +28,17 @@ function formatManagedDetail(counts) {
         .join(', ');
 }
 /**
- * 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 warn loudly with a pointer at
- * `fireforge status --ownership` + `fireforge verify`.
+ * 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
+ * warn loudly with a pointer at `fireforge status --ownership` +
+ * `fireforge verify`.
  *
- * Before 0.16.1 this check warned on every dirty row regardless of
- * ownership and told the operator to export/discard/reset — advice
- * that was actively destructive on a patch-backed import (eval
- * Finding: a correctly imported 126-file patch stack was reported as
- * unhealthy and the suggested fix would have dropped the entire
- * import). Returns `undefined` when the worktree is clean so the
- * caller can emit its own ok() row.
+ * Ownership is what makes the advice safe: warning on every dirty row and
+ * telling the operator to export/discard/reset is actively destructive on a
+ * patch-backed import, where the suggested fix would drop the entire patch
+ * stack. Returns `undefined` when the worktree is clean so the caller can
+ * emit its own ok() row.
  */
 export async function inspectEngineWorkingTree(ctx) {
     const { paths } = ctx;
@@ -82,12 +80,7 @@ export async function inspectEngineWorkingTree(ctx) {
     const managedTotal = counts.branding + counts.furnace + counts.patchBacked + counts.patchOwnedDrift;
     if (counts.unmanaged === 0) {
         const managedDetail = formatManagedDetail(counts);
-        return {
-            name: 'Engine working tree',
-            passed: true,
-            severity: 'ok',
-            message: `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`,
-        };
+        return ok('Engine working tree', `${managedTotal} tool-managed change${managedTotal === 1 ? '' : 's'} (${managedDetail}), 0 unmanaged. Use "fireforge status --ownership" for details.`);
     }
     const managedTail = managedTotal > 0
         ? ` (${managedTotal} other change${managedTotal === 1 ? '' : 's'} are tool-managed: ${formatManagedDetail(counts)}).`

package/dist/src/commands/doctor.d.ts

@@ -29,7 +29,7 @@ export declare const DOCTOR_CHECK_ORDER: readonly string[];
  * @param checks - The check results to display
  * @returns The exit code reflecting the overall result
  */
-export declare function reportDoctorResults(checks: DoctorCheck[]): ExitCode;
+export declare function reportDoctorResults(checks: DoctorCheck[], mutations?: readonly string[]): ExitCode;
 /**
  * Result of the doctor command, carrying the exit code so the caller
  * (or test) can inspect it without relying on process.exitCode.