@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/utils/child-env.d.ts

@@ -2,10 +2,10 @@
  * Environment construction for spawned children.
  *
  * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget; the logic belongs to the exec layer.
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /** The `env` / `envUnset` slice of exec options this module needs. */
-export interface ChildEnvOptions {
+interface ChildEnvOptions {
     /** Variables to add or overwrite on top of `process.env`. */
     env?: Record<string, string> | undefined;
     /** Variables to remove after the merge. */
@@ -15,16 +15,17 @@ export interface ChildEnvOptions {
  * The child's environment: `process.env`, with `env` merged over it, then
  * every `envUnset` key removed.
  *
- * One helper rather than five inline spreads — the removal step is easy to
+ * One helper rather than five inline spreads: the removal step is easy to
  * add at four of the five spawn sites and forget at the fifth, which would
  * make the option silently inert exactly where it was not tested.
  *
- * Removal is a real removal, not an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
- * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * Removal is a real removal rather than an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
+ * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
  * `delete obj[key]` because the key is computed.
  *
  * @param options - Options carrying `env` / `envUnset`
  * @returns The environment to hand `spawn`
  */
 export declare function buildChildEnv(options: ChildEnvOptions): NodeJS.ProcessEnv;
+export {};

package/dist/src/utils/child-env.js

@@ -3,19 +3,19 @@
  * Environment construction for spawned children.
  *
  * Its own module rather than a helper inside `process.ts` only because that
- * file sits on a 500-line budget; the logic belongs to the exec layer.
+ * file sits on a 500-line budget. The logic belongs to the exec layer.
  */
 /**
  * The child's environment: `process.env`, with `env` merged over it, then
  * every `envUnset` key removed.
  *
- * One helper rather than five inline spreads — the removal step is easy to
+ * One helper rather than five inline spreads: the removal step is easy to
  * add at four of the five spawn sites and forget at the fifth, which would
  * make the option silently inert exactly where it was not tested.
  *
- * Removal is a real removal, not an assignment to `''`: mozbuild's
- * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
- * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * Removal is a real removal rather than an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` only for its
+ * presence, so an empty value would not unset it. `Reflect.deleteProperty` rather than
  * `delete obj[key]` because the key is computed.
  *
  * @param options - Options carrying `env` / `envUnset`

package/dist/src/utils/concurrency.d.ts

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept deliberately tiny: one order-preserving
- * mapper, no queues, no cancellation.
+ * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
+ * queues, no cancellation.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/src/utils/concurrency.js

@@ -1,8 +1,8 @@
 /**
  * Bounded-concurrency helpers shared by commands that fan out per-file IO
  * (status classification, import's unmanaged-dirty guard, re-export scans,
- * the dry-run purity guard). Kept deliberately tiny: one order-preserving
- * mapper, no queues, no cancellation.
+ * the dry-run purity guard). Kept tiny: one order-preserving mapper, no
+ * queues, no cancellation.
  */
 /** Maps items with at most `limit` in-flight promises. Preserves order. */
 export async function mapWithConcurrency(items, limit, fn) {

package/dist/src/utils/elapsed.js

@@ -1,5 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
-/** Formats elapsed milliseconds for progress messages. */
+/**
+ * Formats a duration in milliseconds as `Xm Ys`, or `Ys` under a minute.
+ *
+ * The single spelling of FireForge's elapsed-time wording: `build` and
+ * `package` each hand-rolled the same minute/second split, so a change to
+ * the format silently applied to some progress lines and not others.
+ *
+ * @param ms - Duration in milliseconds. Negative input is clamped to zero.
+ * @returns The duration as `Xm Ys`, or `Ys` when under one minute.
+ */
 function formatElapsed(ms) {
     const totalSeconds = Math.max(0, Math.round(ms / 1000));
     const minutes = Math.floor(totalSeconds / 60);

package/dist/src/utils/errors.d.ts

@@ -1,9 +1,9 @@
 /**
  * Throwable normalisation primitives.
  *
- * **This module must import nothing.** It sits at the very bottom of the
- * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it — so it is the one place a shared helper can live and be
+ * This module must import nothing. It sits at the very bottom of the
+ * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it), so it is the one place a shared helper can live and be
  * provably cycle-immune. Adding an import here makes that whole subtree
  * reachable from every util, and any future `src/errors/*` module wanting a
  * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
@@ -17,18 +17,18 @@ export declare function toError(error: unknown): Error;
  * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
  * unknown throwable, or `undefined` when the value carries no string `code`.
  *
- * The check is deliberately structural rather than `error instanceof Error`:
- * a plain object carrying `.code` — exactly the shape {@link toError} exists
- * to normalise — reaches errno consumers through rejected promises and
+ * The check is structural rather than `error instanceof Error`: a plain
+ * object carrying `.code` (exactly the shape {@link toError} exists to
+ * normalise) reaches errno consumers through rejected promises and
  * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
  * code".
  */
 export declare function getNodeErrorCode(error: unknown): string | undefined;
 /**
  * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
  *
- * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
  * Reading EPERM as dead in a predicate that gates a recursive delete removes

package/dist/src/utils/errors.js

@@ -2,9 +2,9 @@
 /**
  * Throwable normalisation primitives.
  *
- * **This module must import nothing.** It sits at the very bottom of the
- * dependency graph — 81 modules across `core/`, `commands/`, `utils/` and
- * `bin/` reach it — so it is the one place a shared helper can live and be
+ * This module must import nothing. It sits at the very bottom of the
+ * dependency graph (81 modules across `core/`, `commands/`, `utils/` and
+ * `bin/` reach it), so it is the one place a shared helper can live and be
  * provably cycle-immune. Adding an import here makes that whole subtree
  * reachable from every util, and any future `src/errors/*` module wanting a
  * util back (`errors/git.ts` already carries a mirrored index-lock heuristic
@@ -29,9 +29,9 @@ export function toError(error) {
  * Extracts a Node errno string (`ENOENT`, `EACCES`, `EPERM`, …) from an
  * unknown throwable, or `undefined` when the value carries no string `code`.
  *
- * The check is deliberately structural rather than `error instanceof Error`:
- * a plain object carrying `.code` — exactly the shape {@link toError} exists
- * to normalise — reaches errno consumers through rejected promises and
+ * The check is structural rather than `error instanceof Error`: a plain
+ * object carrying `.code` (exactly the shape {@link toError} exists to
+ * normalise) reaches errno consumers through rejected promises and
  * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
  * code".
  */
@@ -46,9 +46,9 @@ export function getNodeErrorCode(error) {
 }
 /**
  * Checks whether a process with the given PID is still running, using
- * `kill(pid, 0)` — no signal is sent, only the existence check is performed.
+ * `kill(pid, 0)`: no signal is sent, only the existence check is performed.
  *
- * Only `ESRCH` ("no such process") means dead. **`EPERM` means ALIVE**: the
+ * Only `ESRCH` ("no such process") means dead. `EPERM` means alive: the
  * process exists but is owned by another uid, which happens routinely with
  * root-owned builds, `sudo`, shared CI runners and container UID mismatches.
  * Reading EPERM as dead in a predicate that gates a recursive delete removes

package/dist/src/utils/fs.d.ts

@@ -95,7 +95,7 @@ export declare function copyDir(src: string, dest: string): Promise<void>;
  * artefacts out of their listings without racing the rename.
  *
  * Intentionally anchored so a legitimately-named backup file like
- * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is not treated
  * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
  */
 export declare const FIREFORGE_TMP_PATH_PATTERN: RegExp;

package/dist/src/utils/fs.js

@@ -3,13 +3,9 @@ import { randomUUID } from 'node:crypto';
 import { access, chmod, copyFile as fsCopyFile, lstat, mkdir, open, readdir, readFile, rename, rm, stat, statfs, } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { getNodeErrorCode } from './errors.js';
+import { sleep } from './sleep.js';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
 const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
-function sleep(ms) {
-    return new Promise((resolve) => {
-        setTimeout(resolve, ms);
-    });
-}
 /**
  * Checks if a path exists.
  * @param path - Path to check
@@ -19,8 +15,7 @@ export async function pathExists(path) {
         await access(path);
         return true;
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }
@@ -92,8 +87,7 @@ export async function isSymlink(path) {
     try {
         return (await lstat(path)).isSymbolicLink();
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }
@@ -208,9 +202,9 @@ export async function writeFileAtomic(path, content) {
 /**
  * Renames the temp file over its destination, retrying transient sharing
  * violations. On Windows, a rename onto a target that another writer is
- * concurrently replacing — or that an antivirus/indexer briefly holds open —
+ * concurrently replacing (or that an antivirus/indexer briefly holds open)
  * fails with EPERM/EACCES/EBUSY even though the same rename succeeds a moment
- * later; POSIX renames never hit this. Non-retriable codes and exhausted
+ * later. POSIX renames never hit this. Non-retriable codes and exhausted
  * budgets rethrow, so a genuine permission problem still surfaces.
  */
 async function renameWithRetries(from, to) {
@@ -234,15 +228,16 @@ async function syncParentDir(path) {
         directoryHandle = await open(dirname(path), 'r');
         await directoryHandle.sync();
     }
-    catch (error) {
-        void error;
+    catch {
+        // Best-effort durability: a directory that cannot be opened or fsynced
+        // (network mounts, Windows) must not fail the write it was protecting.
     }
     finally {
         try {
             await directoryHandle?.close();
         }
-        catch (error) {
-            void error;
+        catch {
+            // Nothing left to do. The handle is being discarded either way.
         }
     }
 }
@@ -277,7 +272,7 @@ export async function copyDir(src, dest) {
  * artefacts out of their listings without racing the rename.
  *
  * Intentionally anchored so a legitimately-named backup file like
- * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is NOT treated
+ * `.notes.fireforge-tmp-backup` (no PID+UUID continuation) is not treated
  * as one of our temps. The full shape is `.<filename>.fireforge-tmp-<pid>-<uuid>`.
  */
 export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9a-f-]{36}$/i;
@@ -286,8 +281,8 @@ export const FIREFORGE_TMP_PATH_PATTERN = /(^|\/)\.[^/]+\.fireforge-tmp-\d+-[0-9
  *
  * Each invocation gets its own path via PID + UUID, so concurrent writers
  * targeting the same destination never interfere with each other. Cleanup of
- * the temp file is the caller's responsibility on error; we intentionally do
- * NOT glob-delete peer temp files here to avoid racing with other writers.
+ * the temp file is the caller's responsibility on error. We intentionally do
+ * not glob-delete peer temp files here to avoid racing with other writers.
  */
 function createAtomicTempPath(path) {
     const directory = dirname(path);
@@ -311,7 +306,7 @@ function createAtomicTempPath(path) {
 export async function checkDiskSpace(path, minBytes, onLowSpace) {
     try {
         const stats = await statfs(path);
-        // bavail = blocks available to UNPRIVILEGED users; bfree includes the
+        // bavail = blocks available to UNPRIVILEGED users. bfree includes the
         // root-reserved blocks (typically 5% on ext4), so it over-reported free
         // space and silently suppressed the low-space warning exactly when it
         // mattered.
@@ -326,7 +321,7 @@ export async function checkDiskSpace(path, minBytes, onLowSpace) {
     }
     catch {
         // statfs may not be available on all platforms or the path may
-        // not exist yet — silently degrade rather than blocking the operation.
+        // not exist yet, so silently degrade rather than blocking the operation.
         return undefined;
     }
 }

package/dist/src/utils/hash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Computes the hexadecimal SHA-256 digest of a string or buffer.
+ *
+ * Eleven sites across `src/core/` inlined the same
+ * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
+ * fingerprints and content addresses. They all share this helper instead, so
+ * the digest algorithm and encoding are decided in exactly one place.
+ *
+ * @param input - Data to digest, as a UTF-8 string or a raw buffer.
+ * @returns The 64-character lowercase hexadecimal digest.
+ */
+export declare function sha256Hex(input: string | Buffer): string;

package/dist/src/utils/hash.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
+/**
+ * Computes the hexadecimal SHA-256 digest of a string or buffer.
+ *
+ * Eleven sites across `src/core/` inlined the same
+ * `createHash('sha256').update(input).digest('hex')` chain for cache keys,
+ * fingerprints and content addresses. They all share this helper instead, so
+ * the digest algorithm and encoding are decided in exactly one place.
+ *
+ * @param input - Data to digest, as a UTF-8 string or a raw buffer.
+ * @returns The 64-character lowercase hexadecimal digest.
+ */
+export function sha256Hex(input) {
+    return createHash('sha256').update(input).digest('hex');
+}

package/dist/src/utils/line-dispatch.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
+ * a sibling so the exec module stays within its size budget. The contract
+ * (terminators, partial-line cap) is documented on the function.
+ */
+/**
+ * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
+ * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
+ * matters for progress-bar style output (mach, cargo) that repaints a line
+ * with carriage returns and never sends a newline, which otherwise
+ * accumulates indefinitely. A single trailing `\r` is held back since it may
+ * be the first half of a `\r\n` pair split across chunks. Returns the
+ * remaining partial line. Callers keep accumulating into it.
+ */
+export declare function dispatchCompleteLines(buffer: string, cb: ((line: string) => void) | undefined): string;

package/dist/src/utils/line-dispatch.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Line splitting for the smoke-run stream dispatch in `process.ts`. Kept as
+ * a sibling so the exec module stays within its size budget. The contract
+ * (terminators, partial-line cap) is documented on the function.
+ */
+/**
+ * Cap on the partial-line tail kept between chunks. A child emitting one
+ * enormous line with no terminator (minified JS dumped to stderr, a raw
+ * binary blob) would otherwise grow the buffer without bound: the 50 MB cap
+ * guards the collector, not these line buffers. When the tail exceeds the
+ * cap it is dispatched as a synthetic (oversized) line so the matchers still
+ * see its content, then the buffer resets.
+ */
+const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
+/**
+ * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
+ * `\n`, `\r\n`, and lone `\r` as line terminators. The lone-`\r` case
+ * matters for progress-bar style output (mach, cargo) that repaints a line
+ * with carriage returns and never sends a newline, which otherwise
+ * accumulates indefinitely. A single trailing `\r` is held back since it may
+ * be the first half of a `\r\n` pair split across chunks. Returns the
+ * remaining partial line. Callers keep accumulating into it.
+ */
+export function dispatchCompleteLines(buffer, cb) {
+    let searchFrom = 0;
+    for (;;) {
+        const nl = buffer.indexOf('\n', searchFrom);
+        const cr = buffer.indexOf('\r', searchFrom);
+        const idx = nl === -1 ? cr : cr === -1 ? nl : Math.min(nl, cr);
+        if (idx === -1)
+            break;
+        if (buffer[idx] === '\r' && idx === buffer.length - 1) {
+            // Possible first half of a chunk-split \r\n, so wait for the next chunk.
+            break;
+        }
+        const line = buffer.slice(0, idx);
+        const terminatorLength = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? 2 : 1;
+        buffer = buffer.slice(idx + terminatorLength);
+        searchFrom = 0;
+        cb?.(line);
+    }
+    if (buffer.length > MAX_PARTIAL_LINE_SIZE) {
+        cb?.(buffer);
+        return '';
+    }
+    return buffer;
+}

package/dist/src/utils/logger.d.ts

@@ -64,9 +64,9 @@ export declare function warn(message: string): void;
 export declare const NOTICE_PREFIX = "[FireForge] NOTICE:";
 /**
  * Logs one of FireForge's own "why this is happening / why this is slow"
- * explanations at WARNING severity.
+ * explanations at warning severity.
  *
- * These lines are not warnings about the operator's code — they explain a
+ * These lines are not warnings about the operator's code. They explain a
  * decision FireForge just made (escalating an incremental build to a full
  * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
@@ -98,10 +98,10 @@ export declare function cancel(message: string): void;
 /**
  * Checks whether a prompt result represents a user cancellation.
  *
- * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * Narrows to `symbol`: clack returns its cancel sentinel as a symbol and
  * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
  * that narrowing and forces `as string` / `as PatchCategory` casts across
- * the command modules on the *non*-cancelled branch, where the value is
+ * the command modules on the non-cancelled branch, where the value is
  * already known not to be the sentinel. Keep the predicate form.
  */
 export declare function isCancel(value: unknown): value is symbol;

package/dist/src/utils/logger.js

@@ -6,11 +6,11 @@ let verboseMode = false;
 /**
  * Whether machine-output mode is active (`--json` / `--raw`).
  *
- * In machine mode, stdout belongs EXCLUSIVELY to the machine-readable
+ * In machine mode, stdout belongs exclusively to the machine-readable
  * payload: all human-facing diagnostics (intro/outro banners, info, warn,
  * error, steps, notes) are routed to stderr as plain unstyled lines.
- * Otherwise clack's log helpers write styled warnings to stdout *before* the
- * JSON body — a truncated-directory warning during `status --json` breaks
+ * Otherwise clack's log helpers write styled warnings to stdout before the
+ * JSON body, and a truncated-directory warning during `status --json` breaks
  * every `JSON.parse(stdout)` consumer.
  */
 let machineOutputMode = false;
@@ -35,11 +35,11 @@ export function isMachineOutputMode() {
 /**
  * Whether stdout is sealed behind a machine-readable final line.
  *
- * The `FIREFORGE-VERDICT:` contract promises that line as the run's LAST
- * stdout write — but emit-then-throw failure paths rethrow into
+ * The `FIREFORGE-VERDICT:` contract promises that line as the run's last
+ * stdout write, but emit-then-throw failure paths rethrow into
  * `withErrorHandling`, whose clack error/cancel rendering lands on stdout
  * in non-machine mode, displacing the verdict from the final line. The
- * verdict sink seals stdout the moment it writes; every later logger call
+ * verdict sink seals stdout the moment it writes. Every later logger call
  * routes to stderr through the same diagnostic channel machine mode uses.
  * `withErrorHandling`'s finally clears the seal (alongside machine mode).
  */
@@ -138,9 +138,9 @@ export function warn(message) {
 export const NOTICE_PREFIX = '[FireForge] NOTICE:';
 /**
  * Logs one of FireForge's own "why this is happening / why this is slow"
- * explanations at WARNING severity.
+ * explanations at warning severity.
  *
- * These lines are not warnings about the operator's code — they explain a
+ * These lines are not warnings about the operator's code. They explain a
  * decision FireForge just made (escalating an incremental build to a full
  * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
@@ -196,7 +196,7 @@ export function formatErrorText(message) {
  */
 export function spinner(initialMessage) {
     if (routeToStderr()) {
-        // Spinner progress is diagnostics; keep stdout clean for the payload.
+        // Spinner progress is diagnostics. Keep stdout clean for the payload.
         return {
             message: (msg) => {
                 writeDiagnostic('', msg);
@@ -251,10 +251,10 @@ export function cancel(message) {
 /**
  * Checks whether a prompt result represents a user cancellation.
  *
- * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * Narrows to `symbol`: clack returns its cancel sentinel as a symbol and
  * `p.isCancel` is itself a type predicate. Returning plain `boolean` erases
  * that narrowing and forces `as string` / `as PatchCategory` casts across
- * the command modules on the *non*-cancelled branch, where the value is
+ * the command modules on the non-cancelled branch, where the value is
  * already known not to be the sentinel. Keep the predicate form.
  */
 export function isCancel(value) {

package/dist/src/utils/machine-output.js

@@ -11,8 +11,8 @@
  *   1. Success writes exactly one JSON document to stdout.
  *   2. Failure writes exactly one `{ schemaVersion, error, code }` document
  *      to stdout, then exits non-zero.
- *   3. Machine mode is engaged BEFORE any output, so every diagnostic —
- *      including one rendered later by `withErrorHandling` — routes to
+ *   3. Machine mode is engaged before any output, so every diagnostic,
+ *      including one rendered later by `withErrorHandling`, routes to
  *      stderr and cannot corrupt the payload.
  */
 import { CommandError } from '../errors/base.js';

package/dist/src/utils/options.d.ts

@@ -1,13 +1,14 @@
+import type { Command } from 'commander';
 /**
  * Filters an object to only include keys whose values are not undefined.
- * Designed for use with exactOptionalPropertyTypes — the result can be
+ * Designed for use with exactOptionalPropertyTypes: the result can be
  * spread into typed option objects without assigning undefined to optional
  * properties.
  *
  * Constrained to `object`, not `Record<string, unknown>`: a named interface
  * has no index signature, so the narrower constraint rejects exactly the
  * annotations this helper is most useful with. Nothing in the body needs the
- * index signature — the key walk goes through `Object.keys`.
+ * index signature, since the key walk goes through `Object.keys`.
  *
  * @param obj - Object to filter
  * @returns The same object with every `undefined`-valued key removed
@@ -15,13 +16,12 @@
 export declare function pickDefined<T extends object>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
-import type { Command } from 'commander';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
  *
  * Commander only treats errors whose `code` is `'commander.invalidArgument'`
- * as argument-validation failures; anything else re-throws out of
+ * as argument-validation failures. Anything else re-throws out of
  * `parseAsync`, BYPASSING `withErrorHandling` entirely and landing in the
  * bin's `main().catch` as an unformatted `Fatal error: …` dump with exit 1.
  * That covers a plain Error, a `GeneralError`, and even a FireForge
@@ -62,25 +62,25 @@ export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
  * Accepts the raw string too, so it doubles as the option's arg parser (wrap
  * with {@link commanderArgParser} so failures surface through commander's
  * invalid-argument channel). In that role the value is never `undefined`, so
- * the environment fallback cannot leak into flag PARSING — only into flag
- * ABSENCE, which is where it belongs.
+ * the environment fallback cannot leak into flag parsing, only into flag
+ * absence, which is where it belongs.
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
 /**
- * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * The session-wide wait budget in milliseconds, or undefined when none is
  * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
  *
- * Exists for the SECONDARY locks a command takes after the one its
+ * Exists for the secondary locks a command takes after the one its
  * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
- * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * session lock and then `.fireforge/furnace.lock`. Only the first had a
  * budget, so a contended deploy died on the file lock's fixed 30 s while
  * its operator believed a much larger budget was in force. Threading the
- * flag reaches the three furnace commands that declare it — this reaches
+ * flag reaches the three furnace commands that declare it. This reaches
  * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
  * `override`, `chrome-doc`, …), which have no flag to thread but are just
  * as contended.
  *
- * Deliberately env-only: a flag belongs to one invocation and is passed
+ * Env-only: a flag belongs to one invocation and is passed
  * explicitly where it applies, while the environment is exactly the place a
  * session-wide default is expressed. An explicit budget at a call site
  * always wins over this.
@@ -88,12 +88,6 @@ export declare function resolveWaitLockSeconds(value: string | number | boolean
  * @returns The session budget in milliseconds, or undefined
  */
 export declare function sessionWaitLockMs(): number | undefined;
-/**
- * True when `command` already declares `--wait-lock` itself. Used by the
- * CLI wiring to add the accept-and-ignore variant only where the honoring
- * one is absent.
- */
-export declare function hasWaitLockOption(command: Command): boolean;
 /**
  * Recursively gives every command in the tree a `--wait-lock` flag: the
  * honoring registration where one already exists, the accept-and-ignore
@@ -104,12 +98,12 @@ export declare function ensureWaitLockOptionEverywhere(command: Command): void;
  * Registers the shared `--wait-lock [seconds]` flag on a lock-taking
  * command (the engine session lock for engine-mutating commands, the patch
  * directory lock for queue-mutating ones). The parsed option value is `true`
- * for the bare flag or a validated integer; feed it through
+ * for the bare flag or a validated integer. Feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  *
- * A command can take MORE than one lock — a furnace mutation takes the
- * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * A command can take more than one lock (a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock`) and the budget
  * has to reach all of them or the flag is a half-truth. The secondary locks
  * read the session budget through {@link sessionWaitLockMs} rather than
  * having it threaded to every call site.