@hominis/fireforge 0.42.0 → 0.43.0

package/dist/src/core/file-lock.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { LockContentionError } from '../errors/base.js';
 import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
@@ -64,17 +64,107 @@ async function readLockOwner(lockPath) {
     }
     return { present: false };
 }
+/** Sibling directory in which waiters advertise themselves. */
+function lockWaitersDir(lockPath) {
+    return `${lockPath}.waiters`;
+}
+/** Parsed waiter-file name: `<startedAtMs>-<pid>-<uuid>`. */
+function parseWaiterFileName(name) {
+    const match = /^(\d+)-(\d+)-/.exec(name);
+    const startedAt = match?.[1];
+    const pid = match?.[2];
+    if (startedAt === undefined || pid === undefined)
+        return undefined;
+    return { startedAt: Number.parseInt(startedAt, 10), pid: Number.parseInt(pid, 10) };
+}
+/**
+ * Reads the live waiter queue around `lockPath`, dropping entries whose
+ * process is gone (a killed waiter must not inflate the depth forever).
+ *
+ * Advisory and fail-open: an unreadable registry reports an empty queue
+ * rather than failing whatever asked.
+ *
+ * @param lockPath - The lock directory whose queue to inspect
+ * @param selfStartedAt - This process's wait start, to compute `ahead`
+ */
+export async function readLockQueue(lockPath, selfStartedAt) {
+    let names;
+    try {
+        names = await readdir(lockWaitersDir(lockPath));
+    }
+    catch {
+        return { depth: 0, ahead: 0 };
+    }
+    const live = names
+        .map(parseWaiterFileName)
+        .filter((entry) => entry !== undefined)
+        .filter((entry) => isProcessAlive(entry.pid));
+    const ahead = selfStartedAt === undefined
+        ? 0
+        : live.filter((entry) => entry.startedAt < selfStartedAt).length;
+    return { depth: live.length, ahead };
+}
+/**
+ * Inspects a lock without acquiring it. Read-only and fail-open: a missing
+ * lock is reported as free, never as an error.
+ */
+export async function readLockStatus(lockPath) {
+    const queue = await readLockQueue(lockPath);
+    let heldForMs;
+    try {
+        // Clamped: filesystem mtime resolution can round a just-created lock
+        // fractionally ahead of `Date.now()`, and a negative age is nonsense
+        // in a status report.
+        heldForMs = Math.max(0, Date.now() - (await stat(lockPath)).mtimeMs);
+    }
+    catch {
+        return { held: false, queueDepth: queue.depth };
+    }
+    const owner = await readLockOwner(lockPath);
+    const holder = owner.present
+        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        : undefined;
+    return { held: true, holder, heldForMs, queueDepth: queue.depth };
+}
+/**
+ * Registers this process in the lock's waiter queue. Returns a
+ * deregistration function that is always safe to call (including when
+ * registration itself failed).
+ */
+async function registerWaiter(lockPath, startedAt) {
+    const dir = lockWaitersDir(lockPath);
+    const file = join(dir, `${String(startedAt)}-${String(process.pid)}-${randomUUID()}`);
+    try {
+        await ensureDir(dir);
+        await writeFile(file, `${String(process.pid)}\n`, 'utf-8');
+    }
+    catch (error) {
+        // Advisory only — never fail a lock acquisition over the queue display.
+        verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
+        return async () => {
+            /* nothing to remove */
+        };
+    }
+    return async () => {
+        await rm(file, { force: true });
+    };
+}
 /**
  * Reads the contended lock's owner and reports wait progress to the caller's
  * `onWaitProgress` callback. Failure to read the owner degrades to
  * `holder: undefined` — progress reporting must never break the wait loop.
  */
-async function reportWaitProgress(lockPath, waitedMs, timeoutMs, onWaitProgress) {
+async function reportWaitProgress(lockPath, waitedMs, timeoutMs, startedAt, onWaitProgress) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
         : undefined;
-    onWaitProgress({ waitedMs, timeoutMs, holder });
+    onWaitProgress({
+        waitedMs,
+        timeoutMs,
+        holder,
+        queue: await readLockQueue(lockPath, startedAt),
+    });
 }
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
@@ -209,6 +299,32 @@ async function releaseLock(lockPath, ownerToken, ownerFileWritten) {
     }
     await rm(lockPath, { recursive: true, force: true });
 }
+/**
+ * Builds the contention refusal thrown when the wait budget expires.
+ *
+ * Typed as {@link LockContentionError} (a `FireForgeError`) so the CLI
+ * boundary prints the refusal as one clean line instead of an "Unexpected
+ * error" stack. Callers supplying `onTimeoutMessage` still get
+ * the holder identification appended — the reason-first copy stays theirs,
+ * the "who holds it" is ours.
+ */
+async function buildLockTimeoutError(lockPath, onTimeoutMessage, cause) {
+    const owner = await readLockOwner(lockPath);
+    const liveHolder = owner.present && isProcessAlive(owner.pid) ? owner : undefined;
+    const details = liveHolder !== undefined && liveHolder.metadata.length > 0
+        ? ` (${liveHolder.metadata.join(', ')})`
+        : '';
+    if (onTimeoutMessage !== undefined) {
+        const identifiedHolder = liveHolder !== undefined
+            ? ` The lock is held by PID ${String(liveHolder.pid)}${details}.`
+            : '';
+        return new LockContentionError(`${onTimeoutMessage}${identifiedHolder}`, cause);
+    }
+    const holderHint = liveHolder !== undefined
+        ? ` It is held by running process ${String(liveHolder.pid)}${details} — wait for it to finish, or stop it and retry.`
+        : ' If no other FireForge process is running, remove the lock directory and retry.';
+    return new LockContentionError(`Timed out waiting for file lock ${lockPath}.${holderHint}`, cause);
+}
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
 export async function withFileLock(lockPath, operation, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
@@ -220,51 +336,50 @@ export async function withFileLock(lockPath, operation, options = {}) {
     let lastStaleProbeAt;
     let currentPollMs = pollMs;
     let lastProgressAt = startedAt;
+    /** Set on first contention so an uncontended acquire costs nothing. */
+    let deregisterWaiter;
     await ensureDir(dirname(lockPath));
-    for (;;) {
-        try {
-            await mkdir(lockPath);
-            break;
-        }
-        catch (error) {
-            if (getNodeErrorCode(error) !== 'EEXIST') {
-                throw error;
+    try {
+        for (;;) {
+            try {
+                await mkdir(lockPath);
+                break;
             }
-            if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
-                lastStaleProbeAt = Date.now();
-                if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
-                    continue;
+            catch (error) {
+                if (getNodeErrorCode(error) !== 'EEXIST') {
+                    throw error;
+                }
+                // Advertise this waiter so the queue is visible to the wait output
+                // and to `fireforge status --lock`. Registered lazily:
+                // an uncontended acquisition never touches the registry.
+                deregisterWaiter ??= await registerWaiter(lockPath, startedAt);
+                if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
+                    lastStaleProbeAt = Date.now();
+                    if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
+                        continue;
+                    }
+                }
+                if (Date.now() >= deadline) {
+                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error);
+                }
+                if (options.onWaitProgress !== undefined &&
+                    options.waitProgressMs !== undefined &&
+                    Date.now() - lastProgressAt >= options.waitProgressMs) {
+                    lastProgressAt = Date.now();
+                    await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, startedAt, options.onWaitProgress);
+                }
+                await sleep(currentPollMs);
+                if (options.pollMaxMs !== undefined) {
+                    currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
                 }
-            }
-            if (Date.now() >= deadline) {
-                const owner = await readLockOwner(lockPath);
-                const holderHint = owner.present && isProcessAlive(owner.pid)
-                    ? ` It is held by running process ${String(owner.pid)}${owner.metadata.length > 0 ? ` (${owner.metadata.join(', ')})` : ''} — wait for it to finish, or stop it and retry.`
-                    : ' If no other FireForge process is running, remove the lock directory and retry.';
-                // Typed as LockContentionError (a FireForgeError) so the CLI
-                // boundary prints the refusal as one clean line instead of an
-                // "Unexpected error" stack (FORGE H5). Callers supplying
-                // onTimeoutMessage still get the holder identification appended —
-                // the reason-first copy stays theirs, the "who holds it" is ours.
-                const identifiedHolder = options.onTimeoutMessage !== undefined && owner.present && isProcessAlive(owner.pid)
-                    ? ` The lock is held by PID ${String(owner.pid)}${owner.metadata.length > 0 ? ` (${owner.metadata.join(', ')})` : ''}.`
-                    : '';
-                throw new LockContentionError(options.onTimeoutMessage !== undefined
-                    ? `${options.onTimeoutMessage}${identifiedHolder}`
-                    : `Timed out waiting for file lock ${lockPath}.${holderHint}`, error);
-            }
-            if (options.onWaitProgress !== undefined &&
-                options.waitProgressMs !== undefined &&
-                Date.now() - lastProgressAt >= options.waitProgressMs) {
-                lastProgressAt = Date.now();
-                await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, options.onWaitProgress);
-            }
-            await sleep(currentPollMs);
-            if (options.pollMaxMs !== undefined) {
-                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
             }
         }
     }
+    finally {
+        // Leaving the queue happens the moment we stop waiting — whether we
+        // acquired the lock or timed out.
+        await deregisterWaiter?.();
+    }
     // Stamp ownership (PID + per-acquisition token) into the lock directory so
     // stale-lock recovery can check liveness and release can verify the lock
     // is still ours before removing it.

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -8,7 +8,7 @@ interface DirectoryEntry {
 /**
  * True for a plain-file directory entry — symlinks and directories are
  * never copy candidates. Exported for the patch-owned overwrite probe
- * (FORGE J6), which walks the same override copy-candidate set as apply.
+ *, which walks the same override copy-candidate set as apply.
  */
 export declare function isRegularFile(entry: DirectoryEntry): boolean;
 /**

package/dist/src/core/furnace-apply-helpers.js

@@ -18,7 +18,7 @@ import { fileExistsInHead, restoreTrackedPath } from './git-file-ops.js';
 /**
  * True for a plain-file directory entry — symlinks and directories are
  * never copy candidates. Exported for the patch-owned overwrite probe
- * (FORGE J6), which walks the same override copy-candidate set as apply.
+ *, which walks the same override copy-candidate set as apply.
  */
 export function isRegularFile(entry) {
     if (!entry.isFile())

package/dist/src/core/furnace-apply-output.js

@@ -51,7 +51,7 @@ export function logApplyResult(result, isDryRun) {
             }
         }
     }
-    // Patch-owned overwrite warnings (FORGE J6) print on every non-dry-run
+    // Patch-owned overwrite warnings print on every non-dry-run
     // outcome — including the rolled-back branch, where the overwrite
     // happened before the rollback restored it and the operator still needs
     // to know the deployed copy was momentarily replaced.

package/dist/src/core/furnace-apply-overwrite-warn.d.ts

@@ -1,5 +1,5 @@
 /**
- * Patch-owned overwrite warnings for `furnace apply` (FORGE J6).
+ * Patch-owned overwrite warnings for `furnace apply`.
  *
  * For Furnace-managed components, apply OVERWRITES the deployed engine
  * copies with the `components/` sources. A fix made directly in `engine/`
@@ -26,7 +26,7 @@ export interface PatchOwnedOverwriteWarning {
     owners: string[];
 }
 /**
- * Loads the file → owning-patch map for the overwrite warning (FORGE J6).
+ * Loads the file → owning-patch map for the overwrite warning.
  * A missing or unreadable patches manifest degrades to an empty map — the
  * warning is advisory and must never block an apply.
  */

package/dist/src/core/furnace-apply-overwrite-warn.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch-owned overwrite warnings for `furnace apply` (FORGE J6).
+ * Patch-owned overwrite warnings for `furnace apply`.
  *
  * For Furnace-managed components, apply OVERWRITES the deployed engine
  * copies with the `components/` sources. A fix made directly in `engine/`
@@ -29,7 +29,7 @@ import { checkRegistrationConsistency } from './furnace-validate-registration.js
 import { loadPatchesManifest } from './patch-manifest.js';
 import { buildPatchClaims } from './status-classify.js';
 /**
- * Loads the file → owning-patch map for the overwrite warning (FORGE J6).
+ * Loads the file → owning-patch map for the overwrite warning.
  * A missing or unreadable patches manifest degrades to an empty map — the
  * warning is advisory and must never block an apply.
  */

package/dist/src/core/furnace-apply-undeploy-actions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Dry-run action builders for files deleted from a component workspace
  * since the last apply. Split out of `furnace-apply.ts` (at the per-file
- * line budget after the FORGE J6 overwrite-warning wiring); the real
+ * line budget after the overwrite-warning wiring); the real
  * undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig } from '../types/furnace.js';

package/dist/src/core/furnace-apply-undeploy-actions.js

@@ -2,7 +2,7 @@
 /**
  * Dry-run action builders for files deleted from a component workspace
  * since the last apply. Split out of `furnace-apply.ts` (at the per-file
- * line budget after the FORGE J6 overwrite-warning wiring); the real
+ * line budget after the overwrite-warning wiring); the real
  * undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import { join } from 'node:path';

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
+import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
@@ -320,6 +321,13 @@ export async function applyAllComponents(root, dryRun = false, options) {
     if (rollbackJournal && operationContext) {
         operationContext.registerJournal(rollbackJournal);
     }
+    // Everything below this line can write to the engine. A real apply that
+    // reached it without a journal would have no way back — neither the
+    // lifecycle wrapper's throw path nor the signal handler can restore what
+    // was never captured. `operationContext` is legitimately absent for the
+    // few callers that drive apply outside the wrapper, so the invariant is on
+    // the journal itself.
+    assert(dryRun || rollbackJournal !== undefined, 'rollback journal created before a real apply');
     const result = {
         applied: [],
         skipped: [],
@@ -336,7 +344,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
             throw new FurnaceError(`Component "${componentName}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, componentName);
         }
     }
-    // Patch-claim map for the overwrite warning (FORGE J6): loaded once per
+    // Patch-claim map for the overwrite warning: loaded once per
     // apply. A missing/unreadable manifest degrades to an empty map — the
     // warning is advisory and must never block the apply.
     const patchClaims = await loadPatchClaimsForApply(root);
@@ -377,6 +385,10 @@ export async function applyAllComponents(root, dryRun = false, options) {
     if (!dryRun) {
         if (result.errors.length > 0 || hasStepErrors) {
             if (rollbackJournal) {
+                // This branch owns the rollback for the collected-errors case, so the
+                // lifecycle wrapper must not restore the same journal again if the
+                // restore below throws on its way out.
+                operationContext?.markRolledBack();
                 try {
                     await restoreRollbackJournalOrThrow(rollbackJournal, 'Furnace apply failed');
                     result.rolledBack = true;

package/dist/src/core/furnace-config-custom.d.ts

@@ -6,9 +6,10 @@
  * each add their own validation branch.
  */
 import type { CustomComponentConfig } from '../types/furnace.js';
+import type { JsonObject } from '../types/json.js';
 /**
  * Validates a custom component config object.
  * @param data - Raw data to validate
  * @param name - Component name for error messages
  */
-export declare function parseCustomConfig(data: Record<string, unknown>, name: string): CustomComponentConfig;
+export declare function parseCustomConfig(data: JsonObject, name: string): CustomComponentConfig;

package/dist/src/core/furnace-config-order.d.ts

@@ -1,7 +1,8 @@
 import type { FurnaceConfig } from '../types/furnace.js';
+import type { JsonObject } from '../types/json.js';
 /**
  * Orders furnace.json output using the existing file as the primary key
  * sequence, preserving unknown extension keys and appending newly supported
  * fields only when needed.
  */
-export declare function orderFurnaceConfigForWrite(existing: Record<string, unknown> | undefined, config: FurnaceConfig): Record<string, unknown>;
+export declare function orderFurnaceConfigForWrite(existing: JsonObject | undefined, config: FurnaceConfig): JsonObject;

package/dist/src/core/furnace-config-order.js

@@ -1,4 +1,4 @@
-import { isObject } from '../utils/validation.js';
+import { isJsonObject } from '../utils/validation.js';
 const FURNACE_CONFIG_TOP_LEVEL_KEYS = new Set([
     'version',
     'componentPrefix',
@@ -30,9 +30,9 @@ function orderObjectLikeExisting(existing, next) {
     return ordered;
 }
 function orderComponentMapLikeExisting(existing, next) {
-    if (!isObject(next))
+    if (!isJsonObject(next))
         return next;
-    if (!isObject(existing))
+    if (!isJsonObject(existing))
         return next;
     const ordered = {};
     for (const key of Object.keys(existing)) {
@@ -40,7 +40,7 @@ function orderComponentMapLikeExisting(existing, next) {
             const existingValue = existing[key];
             const nextValue = next[key];
             ordered[key] =
-                isObject(existingValue) && isObject(nextValue)
+                isJsonObject(existingValue) && isJsonObject(nextValue)
                     ? orderObjectLikeExisting(existingValue, nextValue)
                     : nextValue;
         }
@@ -58,6 +58,11 @@ function orderComponentMapLikeExisting(existing, next) {
  * fields only when needed.
  */
 export function orderFurnaceConfigForWrite(existing, config) {
+    // FurnaceConfig is plain parsed-JSON data, but as an interface it carries
+    // no index signature, so the compiler cannot verify the JsonObject
+    // contract structurally — hence the double assertion. This is the one
+    // place a typed furnace config re-enters the raw-document world.
+    // eslint-disable-next-line no-restricted-syntax -- see above
     const next = config;
     if (!existing)
         return next;

package/dist/src/core/furnace-config-validate.d.ts

@@ -5,12 +5,13 @@
  * list, the named-component maps, and the optional-field tail.
  */
 import type { FurnaceConfig, OverrideComponentConfig } from '../types/furnace.js';
+import type { JsonObject, JsonValue } from '../types/json.js';
 /**
  * Validates an override component config object.
  * @param data - Raw data to validate
  * @param name - Component name for error messages
  */
-export declare function parseOverrideConfig(data: Record<string, unknown>, name: string): OverrideComponentConfig;
+export declare function parseOverrideConfig(data: JsonObject, name: string): OverrideComponentConfig;
 /**
  * Parses and validates the `stock` component list: lowercase identifiers,
  * no duplicates.
@@ -21,11 +22,11 @@ export declare function parseStockList(raw: unknown): string[];
  * map must be an object, every key a lowercase identifier, every value an
  * object handed to the kind-specific parser.
  */
-export declare function parseNamedComponentMap<T>(raw: unknown, kind: 'override' | 'custom', key: 'overrides' | 'custom', parse: (value: Record<string, unknown>, name: string) => T): Record<string, T>;
+export declare function parseNamedComponentMap<T>(raw: JsonValue | undefined, kind: 'override' | 'custom', key: 'overrides' | 'custom', parse: (value: JsonObject, name: string) => T): Record<string, T>;
 /**
  * Copies the validated optional fields (token settings, platform
  * prefixes, ftl/jsconfig/scan paths) from the migrated raw config onto
  * the typed config, re-validating the path-shaped ones against
  * traversal.
  */
-export declare function applyOptionalFurnaceFields(migrated: Record<string, unknown>, config: FurnaceConfig): void;
+export declare function applyOptionalFurnaceFields(migrated: JsonObject, config: FurnaceConfig): void;

package/dist/src/core/furnace-config-validate.js

@@ -6,7 +6,7 @@
  * list, the named-component maps, and the optional-field tail.
  */
 import { FurnaceError } from '../errors/furnace.js';
-import { isObject, isString } from '../utils/validation.js';
+import { isJsonObject, isString } from '../utils/validation.js';
 import { parseStringArray } from './furnace-config-array-utils.js';
 /**
  * Validates an override component config object.
@@ -62,7 +62,7 @@ export function parseStockList(raw) {
  * object handed to the kind-specific parser.
  */
 export function parseNamedComponentMap(raw, kind, key, parse) {
-    if (!isObject(raw)) {
+    if (!isJsonObject(raw)) {
         throw new FurnaceError(`Furnace config: "${key}" must be an object`);
     }
     const out = {};
@@ -70,7 +70,7 @@ export function parseNamedComponentMap(raw, kind, key, parse) {
         if (!/^[a-z][a-z0-9-]*$/.test(name)) {
             throw new FurnaceError(`Furnace config: ${kind} name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
         }
-        if (!isObject(value)) {
+        if (!isJsonObject(value)) {
             throw new FurnaceError(`Furnace config: ${kind} "${name}" must be an object`);
         }
         out[name] = parse(value, name);

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

@@ -93,6 +93,9 @@ export function validateFurnaceConfig(data) {
     if (!isObject(data)) {
         throw new FurnaceError('Furnace config must be an object');
     }
+    // Furnace config documents arrive from JSON.parse (loadFurnaceConfig /
+    // writeFurnaceConfig round-trips), which can only produce JSON values,
+    // so the object check above is the only invariant left to establish.
     // Run migration before validation so older configs are transparently upgraded.
     const migrated = migrateFurnaceConfig(data);
     if (migrated['version'] !== CURRENT_CONFIG_VERSION) {
@@ -356,6 +359,8 @@ export async function writeFurnaceConfig(root, config) {
     if (await pathExists(paths.furnaceConfig)) {
         try {
             const raw = await readJson(paths.furnaceConfig);
+            // JSON.parse output is JSON data by construction, so the object
+            // check is the only invariant left for the JsonObject contract.
             if (isObject(raw))
                 existing = raw;
         }

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

@@ -29,6 +29,18 @@ export interface FurnaceOperationContext {
      * collected, not re-thrown.
      */
     registerCleanup(cleanup: () => Promise<void>): void;
+    /**
+     * Declares that the body has already restored its own journal, so the
+     * wrapper's throw-path rollback must not restore it a second time.
+     *
+     * 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.
+     */
+    markRolledBack(): void;
 }
 /** Options for `runFurnaceMutation`. */
 export interface RunFurnaceMutationOptions {