@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/furnace-jsconfig.d.ts

@@ -11,10 +11,10 @@
  * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * `chrome://global/content/elements/` and whose mapped path resolves into
  * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig — including hand-written `paths`
- * entries pointing elsewhere — is preserved verbatim. No `baseUrl` is
+ * pruned). Everything else in the jsconfig, including hand-written `paths`
+ * entries pointing elsewhere, is preserved verbatim. No `baseUrl` is
  * required or written: relative `paths` resolve against the config file's
  * directory.
  */
@@ -32,13 +32,13 @@ export interface JsconfigSyncResult {
 }
 /**
  * Reconciles the managed `compilerOptions.paths` entries of the configured
- * jsconfig against the current Furnace workspace. Idempotent; writes only
- * when something actually changes; dry-run returns the diff without
+ * jsconfig against the current Furnace workspace. Idempotent, and writes
+ * only when something actually changes. Dry-run returns the diff without
  * writing.
  *
  * The consumer owns the jsconfig file: a missing file is an error with
  * guidance rather than a silent scaffold. JSONC comments and trailing commas
- * are preserved; Furnace edits only `compilerOptions.paths`.
+ * are preserved. Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
@@ -49,7 +49,7 @@ export declare function syncFurnaceJsconfigPaths(root: string, config: FurnaceCo
 }): Promise<JsconfigSyncResult>;
 /**
  * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only —
+ * that are missing or stale relative to the current workspace. Read-only:
  * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
  */
 export declare function findJsconfigPathsDrift(root: string, config: FurnaceConfig): Promise<JsconfigSyncResult>;

package/dist/src/core/furnace-jsconfig.js

@@ -12,10 +12,10 @@
  * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * `chrome://global/content/elements/` and whose mapped path resolves into
  * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig — including hand-written `paths`
- * entries pointing elsewhere — is preserved verbatim. No `baseUrl` is
+ * pruned). Everything else in the jsconfig, including hand-written `paths`
+ * entries pointing elsewhere, is preserved verbatim. No `baseUrl` is
  * required or written: relative `paths` resolve against the config file's
  * directory.
  */
@@ -32,18 +32,18 @@ import { getFurnacePaths } from './furnace-config.js';
 const CHROME_ELEMENTS_URL_PREFIX = 'chrome://global/content/elements/';
 /**
  * Computes the desired managed `paths` entries: one per `.mjs` file of
- * every custom component — registered or not — keyed by its deployed
+ * every custom component, registered or not, keyed by its deployed
  * chrome URL and mapped to the workspace source relative to the jsconfig
  * directory. `register: false` components (notably `kind: "library"`
- * base-class modules, which REQUIRE register: false) are included because
+ * base-class modules, which require register: false) are included because
  * deploy copies their files and writes jar.mn entries under
- * `content/global/elements/` unconditionally — only the customElements.js
- * registration is gated on `register` — so their chrome URLs are just as
+ * `content/global/elements/` unconditionally. Only the customElements.js
+ * registration is gated on `register`, so their chrome URLs are just as
  * real as a registered component's.
  *
- * Workspace sources (not deployed engine copies) are the mapping target —
- * they are the files developers edit, and they exist even when the engine
- * has not been deployed yet.
+ * The mapping target is the workspace source, not the deployed engine
+ * copy. Those are the files developers edit, and they exist even when the
+ * engine has not been deployed yet.
  */
 async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPath) {
     const jsconfigDir = dirname(jsconfigAbsPath);
@@ -58,7 +58,7 @@ async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPat
                 continue;
             // Emit a `./`-prefixed relative value. TypeScript treats a bare
             // `paths` value (`moz-widget/moz-widget.mjs`) as non-relative and
-            // rejects it without `baseUrl` (TS5090); a `./`-prefixed value
+            // rejects it without `baseUrl` (TS5090). A `./`-prefixed value
             // resolves against the jsconfig directory with no `baseUrl` (which
             // TS6 deprecates, TS5101). `../`-prefixed paths are already relative
             // and left untouched.
@@ -86,18 +86,19 @@ function isManagedEntry(key, value, jsconfigDir, customDir) {
         return false;
     // Containment via `relative`, not a string prefix: a hard-coded `'/'`
     // separator never matches the backslashes `resolve` emits on Windows, which
-    // demoted every managed entry to "unmanaged" there — no pruning, no updates.
+    // demoted every managed entry to "unmanaged" there, so no pruning and no
+    // updates.
     return isPathInsideRoot(customDir, resolve(jsconfigDir, value[0]));
 }
 /**
  * Reconciles the managed `compilerOptions.paths` entries of the configured
- * jsconfig against the current Furnace workspace. Idempotent; writes only
- * when something actually changes; dry-run returns the diff without
+ * jsconfig against the current Furnace workspace. Idempotent, and writes
+ * only when something actually changes. Dry-run returns the diff without
  * writing.
  *
  * The consumer owns the jsconfig file: a missing file is an error with
  * guidance rather than a silent scaffold. JSONC comments and trailing commas
- * are preserved; Furnace edits only `compilerOptions.paths`.
+ * are preserved. Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
@@ -143,8 +144,8 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
         ...(jsconfigObject.compilerOptions?.paths ?? {}),
     };
     const nextPaths = {};
-    // Preserve every unmanaged entry verbatim; prune managed entries that are
-    // no longer desired; update managed entries whose target moved.
+    // Preserve every unmanaged entry verbatim. Prune managed entries that are
+    // no longer desired. Update managed entries whose target moved.
     for (const [key, value] of Object.entries(currentPaths)) {
         if (!isManagedEntry(key, value, jsconfigDir, furnacePaths.customDir)) {
             nextPaths[key] = value;
@@ -157,8 +158,9 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
         }
         // Treat `./x` and bare `x` as equal so a previously-synced bare value (or
         // a hand-written `./` prefix) is not rewritten as "stale" on every run.
-        // The existing value is kept verbatim when equivalent — no churn either
-        // way; only a genuinely different target updates (to the `./` form).
+        // The existing value is kept verbatim when equivalent, so there is no
+        // churn either way. Only a genuinely different target updates (to the
+        // `./` form).
         if (!samePathValue(value[0], want[0] ?? '')) {
             result.updated.push(key);
             nextPaths[key] = want;
@@ -184,7 +186,7 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
 }
 /**
  * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only —
+ * that are missing or stale relative to the current workspace. Read-only:
  * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
  */
 export async function findJsconfigPathsDrift(root, config) {

package/dist/src/core/furnace-operation.d.ts

@@ -3,7 +3,7 @@ import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * The signal names the lifecycle wrapper knows how to react to. Spelled out
  * as a literal union (rather than `NodeJS.Signals`) so the public type
- * surface does not depend on the NodeJS global namespace — consumers of
+ * surface does not depend on the NodeJS global namespace. Consumers of
  * FireForge's published scoped npm package may compile against tsconfigs
  * that omit `@types/node`.
  */
@@ -36,9 +36,9 @@ export interface FurnaceOperationContext {
      * Bodies that catch-and-restore on their own (the `furnace/*` command
      * bodies, `furnace-apply`) call this from their catch block after the
      * restore, then re-throw. Without it the wrapper would restore the same
-     * journal again on the way out — harmless for the file writes, which are
-     * rename-based and converge, but it would race a second `pendingRepair`
-     * write against the state-file lock.
+     * journal again on the way out. That is harmless for the file writes,
+     * which are rename-based and converge, but it would race a second
+     * `pendingRepair` write against the state-file lock.
      */
     markRolledBack(): void;
 }
@@ -49,7 +49,7 @@ export interface RunFurnaceMutationOptions {
      * Used by dry-run paths where no engine mutation occurs.
      *
      * Note: a dry-run can overlap with a real mutation because it does not
-     * acquire the lock. This is safe because dry-runs only read; however, a
+     * acquire the lock. This is safe because dry-runs only read. However, a
      * dry-run that starts before a real mutation and finishes after it may
      * observe partially-written engine state. Accept this trade-off so that
      * concurrent dry-runs never block each other or a real apply.
@@ -58,11 +58,11 @@ export interface RunFurnaceMutationOptions {
     /**
      * Override the default 30 s furnace-lock timeout.
      *
-     * Set from the caller's resolved `--wait-lock` budget, so ONE flag governs
+     * Set from the caller's resolved `--wait-lock` budget, so one flag governs
      * both locks a furnace mutation takes. Before that it was declared and
      * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
      * engine session lock and then met `.fireforge/furnace.lock` with a fixed
-     * 30 s, which is the worst shape a budget can have — it pays the whole
+     * 30 s, which is the worst shape a budget can have: it pays the whole
      * wait and still refuses. When absent, {@link sessionWaitLockMs} supplies
      * the session-wide budget so the twelve furnace mutators that declare no
      * flag are covered too.
@@ -78,7 +78,7 @@ export interface RunFurnaceMutationOptions {
 /**
  * Converts a resolved `--wait-lock` budget in seconds into the
  * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out — so the caller can spread it
+ * lock. Undefined in, empty out, so the caller can spread it
  * unconditionally without assigning `undefined` under
  * `exactOptionalPropertyTypes`.
  *
@@ -94,7 +94,7 @@ export declare function waitLockMutationOptions(waitLockSeconds: number | undefi
  * Returns true while a signal-driven rollback is in progress. The bin entry
  * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
  * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite); production callers should not need it.
+ * (and the test suite). Production callers should not need it.
  */
 export declare function isSignalRollbackInFlight(): boolean;
 /**
@@ -105,7 +105,7 @@ export declare function isSignalRollbackInFlight(): boolean;
 export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdownSignal): Promise<void>;
 /**
  * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests; production callers should not
+ * for a given project root. Exposed for tests. Production callers should not
  * touch this directly.
  */
 export declare function getFurnaceLockPath(root: string): string;
@@ -119,10 +119,10 @@ export declare function getFurnaceLockPath(root: string): string;
  * restructure control flow through the engine's rollback path for a
  * cosmetic gain.
  *
- * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * The ordering is the part worth centralising: `markRolledBack()` must run
  * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. And the
- * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * lifecycle wrapper replaying the same journal on the way out. The
+ * original error is rethrown unless the rollback is what failed: the
  * operator needs to know what went wrong, and separately whether the engine
  * could be put back.
  *
@@ -130,7 +130,7 @@ export declare function getFurnaceLockPath(root: string): string;
  * @param journal - Rollback journal this body populated
  * @param error - The error the body threw
  * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never — always throws
+ * @returns Never, because it always throws
  */
 export declare function completeJournalRollback(ctx: FurnaceOperationContext, journal: RollbackJournal, error: unknown, options: {
     projectRoot: string;
@@ -144,11 +144,11 @@ export declare function completeJournalRollback(ctx: FurnaceOperationContext, jo
  * Forcibly removes the furnace lock directory for every active operation.
  *
  * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
- * }` never runs, so the lock directory survives the process. The next
+ * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
+ * }` never runs and the lock directory survives the process. The next
  * FireForge command then has to either wait out the staleness window or
  * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * the signal-handler pipeline before `process.exit`, so the lock is gone
  * by the time the next command starts.
  *
  * Errors are logged and swallowed: we do not want a slow I/O failure at
@@ -161,7 +161,7 @@ export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<v
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
  * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy; the CLI entrypoint's global signal handlers consult this
+ * working copy. The CLI entrypoint's global signal handlers consult this
  * registry and invoke rollback (writing a `pendingRepair` marker when needed)
  * if the user hits Ctrl+C mid-run.
  *
@@ -169,7 +169,7 @@ export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<v
  * the lock entirely (concurrent dry-runs are safe and shouldn't block each
  * other).
  *
- * The body receives a {@link FurnaceOperationContext}; it must call
+ * The body receives a {@link FurnaceOperationContext}. It must call
  * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
  * Bodies that don't manage a journal directly (e.g. apply, which delegates to
  * `applyAllComponents`) can pass an internal callback through.
@@ -188,5 +188,8 @@ export declare function recordFurnaceRollbackFailure(root: string, operation: Fu
  * reuse the module across tests, so the test suite must call this between
  * cases that exercise the signal pathway. Not exported from the package
  * entry point.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export declare function __resetFurnaceOperationStateForTests(): void;

package/dist/src/core/furnace-operation.js

@@ -14,7 +14,7 @@ const FURNACE_LOCK_FILENAME = 'furnace.lock';
 /**
  * Converts a resolved `--wait-lock` budget in seconds into the
  * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out — so the caller can spread it
+ * lock. Undefined in, empty out, so the caller can spread it
  * unconditionally without assigning `undefined` under
  * `exactOptionalPropertyTypes`.
  *
@@ -33,7 +33,7 @@ export function waitLockMutationOptions(waitLockSeconds) {
  * already has it.
  *
  * Must stay synchronous and must be called before the caller's first
- * await — that is what makes the claim atomic against the signal handler.
+ * await. That is what makes the claim atomic against the signal handler.
  *
  * @param operation - The in-flight operation to claim
  * @returns True when the caller now owns the rollback
@@ -52,7 +52,7 @@ let signalRollbackInFlight = false;
  * Returns true while a signal-driven rollback is in progress. The bin entry
  * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
  * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite); production callers should not need it.
+ * (and the test suite). Production callers should not need it.
  */
 export function isSignalRollbackInFlight() {
     return signalRollbackInFlight;
@@ -60,7 +60,7 @@ export function isSignalRollbackInFlight() {
 /**
  * Rolls back every in-flight furnace operation and writes a pendingRepair
  * marker for each. The bin entry point installs SIGINT/SIGTERM handlers that
- * call this and then exit; calling it directly from inside the library would
+ * call this and then exit. Calling it directly from inside the library would
  * violate the "process.exit only in bin" invariant. The function is also
  * exposed under this name so the test suite can exercise the teardown path
  * without going through `process.emit` / `process.exit`.
@@ -91,8 +91,9 @@ export async function rollbackActiveOperationsForSignal(signal) {
     // Snapshot the active operations so we don't race with `runFurnaceMutation`
     // clearing slots during normal completion. Filter completed bodies so a
     // body sitting in its finally-block cleanup window is not counted as live
-    // work — this would mis-trigger the rollback banner for plain `fireforge
-    // run` (which never registers a mutation but can receive SIGTERM).
+    // work. Counting it would mis-trigger the rollback banner for plain
+    // `fireforge run` (which never registers a mutation but can receive
+    // SIGTERM).
     const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
     if (snapshot.length === 0) {
         // Nothing to roll back. Stay silent so commands that never mutated (run,
@@ -124,9 +125,9 @@ export async function rollbackActiveOperationsForSignal(signal) {
             }
         }
         if (!op.journal) {
-            // The body had not yet handed us a journal — nothing to roll back. We
-            // still write a marker because the body may have started mutating the
-            // engine before reaching the registerJournal call.
+            // The body had not yet handed us a journal, so there is nothing to
+            // roll back. We still write a marker because the body may have started
+            // mutating the engine before reaching the registerJournal call.
             const cleanupSuffix = cleanupErrors.length > 0 ? `; cleanup errors: ${cleanupErrors.join('; ')}` : '';
             await persistPendingRepair(op.root, op.kind, `interrupted by ${signal} before any state was captured${cleanupSuffix}`).catch((error) => {
                 warn(`Could not persist pending-repair marker: ${toError(error).message}`);
@@ -190,7 +191,7 @@ async function rollbackOperationForThrow(operation) {
     }
     if (!operation.journal) {
         // Nothing was captured, so there is nothing to restore. Unlike the signal
-        // path we do NOT write a pendingRepair marker here: a body that threw
+        // path we do not write a pendingRepair marker here: a body that threw
         // before registering a journal is overwhelmingly a refusal raised during
         // pre-flight (a validation failure, a missing file), and marking the root
         // as needing repair would block every later furnace mutation behind a
@@ -243,7 +244,7 @@ async function persistPendingRepair(root, operation, reason) {
 }
 /**
  * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests; production callers should not
+ * for a given project root. Exposed for tests. Production callers should not
  * touch this directly.
  */
 export function getFurnaceLockPath(root) {
@@ -259,10 +260,10 @@ export function getFurnaceLockPath(root) {
  * restructure control flow through the engine's rollback path for a
  * cosmetic gain.
  *
- * The ordering is the part worth centralising: `markRolledBack()` MUST run
+ * The ordering is the part worth centralising: `markRolledBack()` must run
  * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. And the
- * ORIGINAL error is rethrown unless the rollback is what failed — the
+ * lifecycle wrapper replaying the same journal on the way out. The
+ * original error is rethrown unless the rollback is what failed: the
  * operator needs to know what went wrong, and separately whether the engine
  * could be put back.
  *
@@ -270,7 +271,7 @@ export function getFurnaceLockPath(root) {
  * @param journal - Rollback journal this body populated
  * @param error - The error the body threw
  * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never — always throws
+ * @returns Never, because it always throws
  */
 export async function completeJournalRollback(ctx, journal, error, options) {
     // This body owns its rollback end to end, so tell the lifecycle wrapper
@@ -289,11 +290,11 @@ export async function completeJournalRollback(ctx, journal, error, options) {
  * Forcibly removes the furnace lock directory for every active operation.
  *
  * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding — `withFileLock`'s `finally { rm
- * }` never runs, so the lock directory survives the process. The next
+ * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
+ * }` never runs and the lock directory survives the process. The next
  * FireForge command then has to either wait out the staleness window or
  * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline BEFORE `process.exit`, so the lock is gone
+ * the signal-handler pipeline before `process.exit`, so the lock is gone
  * by the time the next command starts.
  *
  * Errors are logged and swallowed: we do not want a slow I/O failure at
@@ -305,9 +306,9 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
     const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
     for (const lockPath of paths) {
         // Ownership-checked, like every other release path. The bare `rm` this
-        // replaced would delete a lock a DIFFERENT process had acquired in the
-        // window between our operation dying and this sweep running — the exact
-        // race `releaseLock`'s PID verification was added to close, reopened
+        // replaced would delete a lock a different process had acquired in the
+        // window between our operation dying and this sweep running. That is the
+        // exact race `releaseLock`'s PID verification was added to close, reopened
         // here because the sweeper has no acquisition token to check.
         const removed = await releaseLockIfOwned(lockPath);
         verbose(removed
@@ -319,7 +320,7 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
  * Runs a furnace-mutating body under the apply-wide lock and registers it
  * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
  * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy; the CLI entrypoint's global signal handlers consult this
+ * working copy. The CLI entrypoint's global signal handlers consult this
  * registry and invoke rollback (writing a `pendingRepair` marker when needed)
  * if the user hits Ctrl+C mid-run.
  *
@@ -327,7 +328,7 @@ export async function forceReleaseFurnaceLocksForActiveOperations() {
  * the lock entirely (concurrent dry-runs are safe and shouldn't block each
  * other).
  *
- * The body receives a {@link FurnaceOperationContext}; it must call
+ * The body receives a {@link FurnaceOperationContext}. It must call
  * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
  * Bodies that don't manage a journal directly (e.g. apply, which delegates to
  * `applyAllComponents`) can pass an internal callback through.
@@ -356,10 +357,10 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
     const token = nextOperationToken++;
     const operation = { root, kind, cleanups: [] };
     const lockPath = getFurnaceLockPath(root);
-    // An explicit budget wins; otherwise the session-wide one applies. Naming
-    // the lock in the refusal is load-bearing: a mutation takes two, and a
-    // message that says only "timed out" sends the operator to raise a budget
-    // that was already large enough for the OTHER lock.
+    // An explicit budget wins. Otherwise the session-wide one applies. Naming
+    // the lock in the refusal matters: a mutation takes two, and a message
+    // that says only "timed out" sends the operator to raise a budget that
+    // was already large enough for the other lock.
     const timeoutMs = options.lockTimeoutMs ?? sessionWaitLockMs();
     const lockOptions = {
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
@@ -374,14 +375,14 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
     return withFileLock(lockPath, async () => {
         // Everything the body does from here is serialized only by the furnace
         // lock, so confirm we are actually inside it before registering as a
-        // live mutation. The owner record is deliberately best-effort in
-        // `withFileLock` (a live holder can legitimately have no readable PID),
-        // so the PID half only tightens the check when a record is present —
-        // asserting on its existence would fire on a lock we really do hold.
+        // live mutation. The owner record is best-effort in `withFileLock`
+        // (a live holder can legitimately have no readable PID), so the PID
+        // half only tightens the check when a record is present. Asserting on
+        // its existence would fire on a lock we really do hold.
         const lockStatus = await readLockStatus(lockPath);
         assert(lockStatus.held, 'furnace lock held before the mutation body runs');
         assert(lockStatus.holder === undefined || lockStatus.holder.pid === process.pid, () => `furnace lock is owned by this process ` +
-            `(held by PID ${String(lockStatus.holder?.pid)}, we are ${String(process.pid)})`);
+            `(held by PID ${lockStatus.holder?.pid}, we are ${process.pid})`);
         activeOperations.set(token, operation);
         try {
             return await body({
@@ -401,8 +402,8 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
             // so it gets the same treatment. A bare finally here would
             // deregister the operation and mark it completed, removing it from
             // the signal handler's view too, so a body that threw outside its
-            // own catch — notably anywhere in `applyAllComponents` outside its
-            // two per-component try blocks — would leave the checkout torn with
+            // own catch (notably anywhere in `applyAllComponents` outside its
+            // two per-component try blocks) would leave the checkout torn with
             // no marker.
             //
             // This runs inside the withFileLock callback, so the furnace lock is
@@ -432,6 +433,9 @@ export async function recordFurnaceRollbackFailure(root, operation, reason) {
  * reuse the module across tests, so the test suite must call this between
  * cases that exercise the signal pathway. Not exported from the package
  * entry point.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export function __resetFurnaceOperationStateForTests() {
     activeOperations.clear();

package/dist/src/core/furnace-precondition.d.ts

@@ -3,14 +3,14 @@
  * `furnace.json` exists.
  *
  * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
- * because the error CLASS is load-bearing here, not cosmetic: `FurnaceError`
- * carries its own `userMessage` and exit code 9, so a helper raising
- * `GeneralError` would silently change both.
+ * because the error class matters here and is not merely cosmetic:
+ * `FurnaceError` carries its own `userMessage` and exit code 9, so a helper
+ * raising `GeneralError` would silently change both.
  *
- * Deliberately NOT routed through this helper — each informs rather than
- * refuses, and each says so at its own site: `furnace list`,
- * `furnace status`, `furnace init`, and `verify`. `furnace validate`
- * refusing is the intended line between inspecting and validating.
+ * Four sites are not routed through this helper: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. Each informs rather than
+ * refuses, and each says so at its own site. `furnace validate` refusing is
+ * the intended line between inspecting and validating.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
 import type { ProjectPaths } from '../types/index.js';
@@ -18,8 +18,8 @@ import type { ProjectPaths } from '../types/index.js';
 export interface FurnacePreconditionOptions {
     /**
      * Appended to the engine-missing refusal, e.g.
-     * `' to scaffold a chrome-doc.'`. The base message ends WITHOUT
-     * punctuation so the suffix reads as one sentence; callers passing nothing
+     * `' to scaffold a chrome-doc.'`. The base message ends without
+     * punctuation so the suffix reads as one sentence. Callers passing nothing
      * get a plain full stop.
      */
     engineMissingSuffix?: string;
@@ -48,7 +48,7 @@ export declare function assertFurnaceEngineReady(projectRoot: string, options?:
     paths: ProjectPaths;
 }>;
 /**
- * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * Asserts the full Furnace ladder (engine checkout, then `furnace.json`)
  * and returns the loaded config so callers do not read it a second time.
  *
  * @param projectRoot - Project root directory

package/dist/src/core/furnace-precondition.js

@@ -4,14 +4,14 @@
  * `furnace.json` exists.
  *
  * Kept separate from the `GeneralError` ladder in `engine-precondition.ts`
- * because the error CLASS is load-bearing here, not cosmetic: `FurnaceError`
- * carries its own `userMessage` and exit code 9, so a helper raising
- * `GeneralError` would silently change both.
+ * because the error class matters here and is not merely cosmetic:
+ * `FurnaceError` carries its own `userMessage` and exit code 9, so a helper
+ * raising `GeneralError` would silently change both.
  *
- * Deliberately NOT routed through this helper — each informs rather than
- * refuses, and each says so at its own site: `furnace list`,
- * `furnace status`, `furnace init`, and `verify`. `furnace validate`
- * refusing is the intended line between inspecting and validating.
+ * Four sites are not routed through this helper: `furnace list`,
+ * `furnace status`, `furnace init`, and `verify`. Each informs rather than
+ * refuses, and each says so at its own site. `furnace validate` refusing is
+ * the intended line between inspecting and validating.
  */
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists } from '../utils/fs.js';
@@ -47,7 +47,7 @@ export async function assertFurnaceEngineReady(projectRoot, options = {}) {
     return { paths };
 }
 /**
- * Asserts the full Furnace ladder — engine checkout, then `furnace.json` —
+ * Asserts the full Furnace ladder (engine checkout, then `furnace.json`)
  * and returns the loaded config so callers do not read it a second time.
  *
  * @param projectRoot - Project root directory

package/dist/src/core/furnace-refresh.d.ts

@@ -3,14 +3,26 @@ export interface RefreshFileResult {
     status: 'merged' | 'conflict' | 'unchanged' | 'new-file';
     conflictMarkers?: number;
 }
+export interface RefreshOverrideFileOptions {
+    /** Path to the engine git repository. */
+    engineDir: string;
+    /** Path to the current override file in the workspace. */
+    overridePath: string;
+    /** Engine-relative path for git show. */
+    engineRelPath: string;
+    /** The git ref at which the override was originally created. */
+    baseCommit: string;
+    /** Display name for the file. */
+    fileName: string;
+    /** When true, compute the merge but write nothing. */
+    dryRun?: boolean | undefined;
+    /** Conflict resolution preference handed to `git merge-file`. */
+    strategy?: 'ours' | 'theirs' | undefined;
+}
 /**
  * Refreshes a single override file against the current engine HEAD.
  *
- * @param engineDir - Path to the engine git repository
- * @param overridePath - Path to the current override file in the workspace
- * @param engineRelPath - Engine-relative path for git show
- * @param baseCommit - The git ref at which the override was originally created
- * @param fileName - Display name for the file
+ * @param options - See {@link RefreshOverrideFileOptions}
  * @returns Merge result with the updated content written to the override file
  */
-export declare function refreshOverrideFile(engineDir: string, overridePath: string, engineRelPath: string, baseCommit: string, fileName: string, dryRun?: boolean, strategy?: 'ours' | 'theirs'): Promise<RefreshFileResult>;
+export declare function refreshOverrideFile(options: RefreshOverrideFileOptions): Promise<RefreshFileResult>;

package/dist/src/core/furnace-refresh.js

@@ -81,24 +81,21 @@ async function threeWayMergeFile(base, ours, theirs, label, strategy) {
 /**
  * Refreshes a single override file against the current engine HEAD.
  *
- * @param engineDir - Path to the engine git repository
- * @param overridePath - Path to the current override file in the workspace
- * @param engineRelPath - Engine-relative path for git show
- * @param baseCommit - The git ref at which the override was originally created
- * @param fileName - Display name for the file
+ * @param options - See {@link RefreshOverrideFileOptions}
  * @returns Merge result with the updated content written to the override file
  */
-export async function refreshOverrideFile(engineDir, overridePath, engineRelPath, baseCommit, fileName, dryRun, strategy) {
+export async function refreshOverrideFile(options) {
+    const { engineDir, overridePath, engineRelPath, baseCommit, fileName, dryRun, strategy } = options;
     // Read the three versions
     const oursContent = await readText(overridePath);
     const baseContent = await getFileContentAtRef(engineDir, engineRelPath, baseCommit);
     if (baseContent === null) {
-        // File didn't exist at baseCommit — this is a new file introduced by the override
+        // File didn't exist at baseCommit: this is a new file introduced by the override
         return { fileName, status: 'new-file' };
     }
     const theirsContent = await getFileContentAtRef(engineDir, engineRelPath, 'HEAD');
     if (theirsContent === null) {
-        // File was removed upstream — no merge needed, keep the override as-is
+        // File was removed upstream, so no merge is needed. Keep the override as-is
         return { fileName, status: 'unchanged' };
     }
     // If upstream hasn't changed, nothing to merge