@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/utils/build-info.d.ts

@@ -0,0 +1,31 @@
+/** Source identity of the running build. */
+export interface BuildIdentity {
+    shortCommit: string;
+    dirty: boolean;
+    /**
+     * Content hash of the uncommitted diff, present only for a DIRTY
+     * installed build (FORGE L8). Two packs from the same HEAD with
+     * different uncommitted content share `shortCommit` and the `.dirty`
+     * marker, so without this they report byte-identical `--version`
+     * strings — which is what made a field report against
+     * `0.41.0+g<sha>.dirty` impossible to trace back to a specific pack.
+     * Absent in a git checkout: identity there comes from live git, and
+     * hashing the full diff on every `--version` call is not worth it.
+     */
+    dirtyHash?: string;
+}
+/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+export declare function readBuildInfoFile(packageRoot: string): BuildIdentity | null;
+type GitRunner = (args: string[]) => string;
+/** @internal Live git identity of the checkout; null when git is unusable. */
+export declare function readGitBuildIdentity(runGit?: GitRunner): BuildIdentity | null;
+/**
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * null identity. The trailing content hash appears only for a dirty
+ * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * segment stays valid semver build metadata (dot-separated alphanumerics).
+ */
+export declare function formatVersionWithIdentity(version: string, identity: BuildIdentity | null): string;
+/** The `--version` string: semver plus build identity when known. */
+export declare function getCliVersion(): string;
+export {};

package/dist/src/utils/build-info.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Build identity for `--version` (FORGE K2/K3/L8). Three distinct builds
+ * shipped as plain "0.41.0" — consumers had to fingerprint tarballs by
+ * sha256 to know which build a claim was verified against. `--version`
+ * now reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
+ *
+ * - In a git checkout (dev runs via tsx), identity comes from live git —
+ *   a stale `dist/build-info.json` from an old build must never win.
+ * - In an installed package, it comes from `dist/build-info.json`,
+ *   stamped by scripts/generate-build-info.mjs at build/pack time.
+ * - When neither yields an identity, `--version` degrades to the plain
+ *   semver. Reading identity must never throw.
+ *
+ * Deliberately NOT wired into the per-patch lint cache key: identity
+ * would churn the cache on every commit at the same semver for no
+ * correctness gain (`getPackageVersion` stays the cache input).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getPackageRoot, getPackageVersion } from './package-root.js';
+import { isObject } from './validation.js';
+/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+export function readBuildInfoFile(packageRoot) {
+    try {
+        const raw = readFileSync(join(packageRoot, 'dist', 'build-info.json'), 'utf-8');
+        const data = JSON.parse(raw);
+        if (!isObject(data) || data['schemaVersion'] !== 1)
+            return null;
+        const shortCommit = data['shortCommit'];
+        const dirty = data['dirty'];
+        if (typeof shortCommit !== 'string' || shortCommit.length === 0)
+            return null;
+        const dirtyHash = data['dirtyHash'];
+        return {
+            shortCommit,
+            dirty: dirty === true,
+            ...(typeof dirtyHash === 'string' && dirtyHash.length > 0 ? { dirtyHash } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const defaultGitRunner = (args) => execFileSync('git', args, {
+    cwd: getPackageRoot(),
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+});
+/** @internal Live git identity of the checkout; null when git is unusable. */
+export function readGitBuildIdentity(runGit = defaultGitRunner) {
+    try {
+        const commit = runGit(['rev-parse', 'HEAD']).trim();
+        if (!/^[0-9a-f]{7,40}$/.test(commit))
+            return null;
+        const status = runGit(['status', '--porcelain']);
+        return { shortCommit: commit.slice(0, 12), dirty: status.length > 0 };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves the running build's identity: live git in a checkout (covers
+ * worktrees, whose `.git` is a file), else the stamped build-info file,
+ * else null. Never throws.
+ */
+function getBuildIdentity() {
+    try {
+        const packageRoot = getPackageRoot();
+        if (existsSync(join(packageRoot, '.git'))) {
+            return readGitBuildIdentity();
+        }
+        return readBuildInfoFile(packageRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * null identity. The trailing content hash appears only for a dirty
+ * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * segment stays valid semver build metadata (dot-separated alphanumerics).
+ */
+export function formatVersionWithIdentity(version, identity) {
+    if (identity === null)
+        return version;
+    if (!identity.dirty)
+        return `${version}+g${identity.shortCommit}`;
+    const contentHash = identity.dirtyHash === undefined ? '' : `.${identity.dirtyHash}`;
+    return `${version}+g${identity.shortCommit}.dirty${contentHash}`;
+}
+/** The `--version` string: semver plus build identity when known. */
+export function getCliVersion() {
+    return formatVersionWithIdentity(getPackageVersion(), getBuildIdentity());
+}

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

@@ -0,0 +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.
+ */
+/** 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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+/** Maps items with at most `limit` in-flight promises. Preserves order. */
+export async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await fn(items[index], index);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}

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

@@ -1,2 +1,41 @@
+/**
+ * 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
+ * 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
+ * that would like `getNodeErrorCode`) then closes the loop and fails the
+ * `dpdm --exit-code circular:1` release gate. A helper that needs an import
+ * belongs in a sibling leaf module, not here.
+ */
 /** Normalizes unknown throwables into an Error instance. */
 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
+ * cross-realm throws. Nine hand-rolled copies of this predicate existed
+ * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
+ * and so misclassified that shape 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.
+ *
+ * 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.
+ * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
+ * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
+ * build's tree clone and a live furnace lock were removed out from under
+ * their owner. Any other errno is treated as "unknown, assume alive", which
+ * is the safe direction for every caller: it refuses rather than destroys.
+ */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/src/utils/errors.js

@@ -1,4 +1,17 @@
 // SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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
+ * 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
+ * that would like `getNodeErrorCode`) then closes the loop and fails the
+ * `dpdm --exit-code circular:1` release gate. A helper that needs an import
+ * belongs in a sibling leaf module, not here.
+ */
 /** Normalizes unknown throwables into an Error instance. */
 export function toError(error) {
     if (error instanceof Error) {
@@ -12,3 +25,45 @@ export function toError(error) {
     }
     return new Error(typeof error === 'string' ? error : String(error), { cause: 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
+ * cross-realm throws. Nine hand-rolled copies of this predicate existed
+ * before 0.41.0, four of them (in `utils/fs.ts`) gated on `instanceof Error`
+ * and so misclassified that shape as "no code".
+ */
+export function getNodeErrorCode(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string') {
+        return error.code;
+    }
+    return 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.
+ *
+ * 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.
+ * Two copies of this predicate (`tree-store.ts`, `doctor-furnace.ts`) read
+ * EPERM as dead before 0.41.0, and both gated a recursive delete — a live
+ * build's tree clone and a live furnace lock were removed out from under
+ * their owner. Any other errno is treated as "unknown, assume alive", which
+ * is the safe direction for every caller: it refuses rather than destroys.
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return getNodeErrorCode(error) !== 'ESRCH';
+    }
+}

package/dist/src/utils/fs.js

@@ -2,6 +2,7 @@
 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';
 const RETRIABLE_REMOVE_ERRORS = new Set(['ENOTEMPTY', 'EBUSY', 'EPERM']);
 const RETRIABLE_RENAME_ERRORS = new Set(['EPERM', 'EACCES', 'EBUSY']);
 function sleep(ms) {
@@ -33,9 +34,7 @@ export async function pathExistsStrict(path) {
         return true;
     }
     catch (error) {
-        const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-            ? error.code
-            : undefined;
+        const code = getNodeErrorCode(error);
         if (code === 'ENOENT') {
             return false;
         }
@@ -68,9 +67,7 @@ export async function removeDir(path) {
             return;
         }
         catch (error) {
-            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-                ? error.code
-                : undefined;
+            const code = getNodeErrorCode(error);
             if (!code || !RETRIABLE_REMOVE_ERRORS.has(code) || attempt === 4) {
                 throw error;
             }
@@ -177,9 +174,7 @@ export async function writeFileAtomic(path, content) {
         existingMode = (await stat(path)).mode;
     }
     catch (error) {
-        const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-            ? error.code
-            : undefined;
+        const code = getNodeErrorCode(error);
         if (code !== 'ENOENT') {
             throw error;
         }
@@ -223,9 +218,7 @@ async function renameWithRetries(from, to) {
             return;
         }
         catch (error) {
-            const code = error instanceof Error && 'code' in error && typeof error.code === 'string'
-                ? error.code
-                : undefined;
+            const code = getNodeErrorCode(error);
             if (!code || !RETRIABLE_RENAME_ERRORS.has(code) || attempt === 4) {
                 throw error;
             }

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

@@ -10,6 +10,8 @@ export declare function setVerbose(enabled: boolean): void;
 export declare function setMachineOutputMode(enabled: boolean): void;
 /** True when machine-output mode is active. */
 export declare function isMachineOutputMode(): boolean;
+/** Seals (or unseals) stdout after a machine-readable final line. */
+export declare function setStdoutSealed(sealed: boolean): void;
 /**
  * Displays a verbose/debug message (only shown if verbose mode is enabled).
  * @param message - Message to display
@@ -54,7 +56,17 @@ export declare function formatErrorText(message: string): string;
 export declare function spinner(initialMessage: string): SpinnerHandle;
 /** Emits a cancellation message. */
 export declare function cancel(message: string): void;
-/** Checks whether a prompt result represents a user cancellation. */
-export declare function isCancel(value: unknown): boolean;
+/**
+ * Checks whether a prompt result represents a user cancellation.
+ *
+ * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * `p.isCancel` is itself a type predicate. This wrapper erased that narrowing
+ * by returning plain `boolean` until 0.41.0, which forced eleven `as string`
+ * / `as PatchCategory` / `as OverrideType` casts across six command modules
+ * on the *non*-cancelled branch, where the value is already known not to be
+ * the sentinel. Keep the predicate form: it is the single highest-leverage
+ * signature in the codebase for escape-hatch count.
+ */
+export declare function isCancel(value: unknown): value is symbol;
 /** Displays a titled note block for follow-up details. */
 export declare function note(message: string, title?: string): void;

package/dist/src/utils/logger.js

@@ -34,6 +34,26 @@ export function setMachineOutputMode(enabled) {
 export function isMachineOutputMode() {
     return machineOutputMode;
 }
+/**
+ * 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
+ * `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
+ * routes to stderr through the same diagnostic channel machine mode uses.
+ * `withErrorHandling`'s finally clears the seal (alongside machine mode).
+ */
+let stdoutSealed = false;
+/** Seals (or unseals) stdout after a machine-readable final line. */
+export function setStdoutSealed(sealed) {
+    stdoutSealed = sealed;
+}
+/** True when human output must avoid stdout. */
+function routeToStderr() {
+    return machineOutputMode || stdoutSealed;
+}
 /** Writes a plain diagnostic line to stderr (machine-mode side channel). */
 function writeDiagnostic(prefix, message) {
     process.stderr.write(`${prefix}${message}\n`);
@@ -52,7 +72,7 @@ function isVerbose() {
 export function verbose(message) {
     if (!isVerbose())
         return;
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('[debug] ', message);
         return;
     }
@@ -63,19 +83,19 @@ function supportsInteractiveSpinner() {
 }
 /** Displays the top-level intro banner for a command. */
 export function intro(message) {
-    if (machineOutputMode)
+    if (routeToStderr())
         return;
     p.intro(message);
 }
 /** Displays the closing outro banner for a command. */
 export function outro(message) {
-    if (machineOutputMode)
+    if (routeToStderr())
         return;
     p.outro(message);
 }
 /** Logs an informational message. */
 export function info(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('', message);
         return;
     }
@@ -83,7 +103,7 @@ export function info(message) {
 }
 /** Logs a success message. */
 export function success(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('', message);
         return;
     }
@@ -91,7 +111,7 @@ export function success(message) {
 }
 /** Logs a warning message. */
 export function warn(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('warning: ', message);
         return;
     }
@@ -99,7 +119,7 @@ export function warn(message) {
 }
 /** Logs an error message. */
 export function error(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('error: ', message);
         return;
     }
@@ -107,7 +127,7 @@ export function error(message) {
 }
 /** Logs an in-progress step message. */
 export function step(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('', message);
         return;
     }
@@ -115,7 +135,7 @@ export function step(message) {
 }
 /** Logs a plain message without a status prefix. */
 export function message(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('', message);
         return;
     }
@@ -135,7 +155,7 @@ export function formatErrorText(message) {
  * @returns Spinner handle with message(), stop(), and error() methods
  */
 export function spinner(initialMessage) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         // Spinner progress is diagnostics; keep stdout clean for the payload.
         return {
             message: (msg) => {
@@ -182,19 +202,29 @@ export function spinner(initialMessage) {
 }
 /** Emits a cancellation message. */
 export function cancel(message) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('cancelled: ', message);
         return;
     }
     p.cancel(message);
 }
-/** Checks whether a prompt result represents a user cancellation. */
+/**
+ * Checks whether a prompt result represents a user cancellation.
+ *
+ * Narrows to `symbol` — clack returns its cancel sentinel as a symbol and
+ * `p.isCancel` is itself a type predicate. This wrapper erased that narrowing
+ * by returning plain `boolean` until 0.41.0, which forced eleven `as string`
+ * / `as PatchCategory` / `as OverrideType` casts across six command modules
+ * on the *non*-cancelled branch, where the value is already known not to be
+ * the sentinel. Keep the predicate form: it is the single highest-leverage
+ * signature in the codebase for escape-hatch count.
+ */
 export function isCancel(value) {
     return p.isCancel(value);
 }
 /** Displays a titled note block for follow-up details. */
 export function note(message, title) {
-    if (machineOutputMode) {
+    if (routeToStderr()) {
         writeDiagnostic('', title ? `${title}: ${message}` : message);
         return;
     }

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

@@ -22,6 +22,21 @@ import type { Command } from 'commander';
  * helper (or throw commander's InvalidArgumentError directly).
  */
 export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;
+/**
+ * Commander plumbing for a repeatable string option, as a spreadable
+ * `[accumulator, default]` pair:
+ *
+ * ```ts
+ * .option('--mach-arg <arg>', 'Repeatable.', ...stringListOption())
+ * ```
+ *
+ * Seven call sites open-coded this, each with its own `[] as string[]`
+ * default — commander types that slot as `unknown`, so every one carried the
+ * cast. Two of the seven also mutated the accumulator in place rather than
+ * returning a new array. Returning a fresh array per call additionally means
+ * the default cannot be shared between two `.option()` registrations.
+ */
+export declare function stringListOption(): [(value: string, previous: string[]) => string[], string[]];
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
@@ -35,9 +50,11 @@ export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw:
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
 /**
- * Registers the shared `--wait-lock [seconds]` flag on an engine-mutating
- * command. The parsed option value is `true` for the bare flag or a validated
- * integer; feed it through {@link resolveWaitLockSeconds} at the call site to
- * obtain the `waitLockSeconds` for `withEngineSessionLock`.
+ * 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
+ * {@link resolveWaitLockSeconds} at the call site to obtain the
+ * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  */
 export declare function addWaitLockOption(command: Command): Command;

package/dist/src/utils/options.js

@@ -15,6 +15,7 @@ export function pickDefined(obj) {
 }
 import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
 import { GeneralError } from '../errors/base.js';
+import { toError } from './errors.js';
 /**
  * Wraps an option-argument parser so its failures surface through
  * commander's own invalid-argument channel.
@@ -35,10 +36,27 @@ export function commanderArgParser(parse) {
             return parse(raw);
         }
         catch (error) {
-            throw new CommanderInvalidArgumentError(error instanceof Error ? error.message : String(error));
+            throw new CommanderInvalidArgumentError(toError(error).message);
         }
     };
 }
+/**
+ * Commander plumbing for a repeatable string option, as a spreadable
+ * `[accumulator, default]` pair:
+ *
+ * ```ts
+ * .option('--mach-arg <arg>', 'Repeatable.', ...stringListOption())
+ * ```
+ *
+ * Seven call sites open-coded this, each with its own `[] as string[]`
+ * default — commander types that slot as `unknown`, so every one carried the
+ * cast. Two of the seven also mutated the accumulator in place rather than
+ * returning a new array. Returning a fresh array per call additionally means
+ * the default cannot be shared between two `.option()` registrations.
+ */
+export function stringListOption() {
+    return [(value, previous) => [...previous, value], []];
+}
 /** Wait budget applied when `--wait-lock` is passed without a value. */
 const DEFAULT_WAIT_LOCK_SECONDS = 60;
 /**
@@ -69,11 +87,13 @@ export function resolveWaitLockSeconds(value) {
     return n;
 }
 /**
- * Registers the shared `--wait-lock [seconds]` flag on an engine-mutating
- * command. The parsed option value is `true` for the bare flag or a validated
- * integer; feed it through {@link resolveWaitLockSeconds} at the call site to
- * obtain the `waitLockSeconds` for `withEngineSessionLock`.
+ * 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
+ * {@link resolveWaitLockSeconds} at the call site to obtain the
+ * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
  */
 export function addWaitLockOption(command) {
-    return command.option('--wait-lock [seconds]', 'Wait up to this many seconds (default 60) for another FireForge engine-mutating command to release the engine lock, instead of failing immediately', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
+    return command.option('--wait-lock [seconds]', 'Wait up to this many seconds (default 60) for another FireForge command to release the contended lock, instead of failing on the default budget', commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }

package/dist/src/utils/package-root.js

@@ -2,6 +2,8 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getNodeErrorCode, toError } from './errors.js';
+import { isObject } from './validation.js';
 function validatePackageMetadata(data, filePath) {
     if (typeof data !== 'object' || data === null) {
         throw new Error(`Invalid package metadata in ${filePath}: expected an object`);
@@ -48,10 +50,11 @@ export function getPackageRoot() {
             // to a wrong ancestor package (any parent exposing bin.fireforge) or
             // end in the unhelpful generic "could not locate" error, hiding the
             // actual syntax problem.
-            const code = error.code;
+            const code = getNodeErrorCode(error);
             if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-                throw new Error(`Found ${packagePath} but could not parse it: ` +
-                    (error instanceof Error ? error.message : String(error)), { cause: error });
+                throw new Error(`Found ${packagePath} but could not parse it: ` + toError(error).message, {
+                    cause: error,
+                });
             }
         }
         const parent = dirname(current);
@@ -63,7 +66,7 @@ export function getPackageRoot() {
 }
 /** @internal */
 export function isFireForgePackageMetadata(pkg) {
-    if (typeof pkg.bin !== 'object' || pkg.bin === null || Array.isArray(pkg.bin)) {
+    if (!isObject(pkg.bin)) {
         return false;
     }
     const bin = pkg.bin;

package/dist/src/utils/process-group.js

@@ -6,6 +6,7 @@
  * two modules do not import each other cyclically.
  */
 import { spawn } from 'node:child_process';
+import { getNodeErrorCode } from './errors.js';
 import { verbose, warn } from './logger.js';
 /**
  * Sends `signal` to the child's whole tree: the process GROUP on POSIX
@@ -99,8 +100,14 @@ async function listGroupSurvivors(pgid) {
         process.kill(-pgid, 0);
         return [{ pid: -1, command: 'unknown (pgrep unavailable; group still has live members)' }];
     }
-    catch {
-        return [];
+    catch (error) {
+        // Same errno semantics as `isProcessAlive` (which cannot be called here —
+        // it probes a single positive pid): only ESRCH proves the group is gone.
+        // EPERM means it exists under another uid, and an unrecognized failure is
+        // not evidence of absence — report survivors in both cases.
+        if (getNodeErrorCode(error) === 'ESRCH')
+            return [];
+        return [{ pid: -1, command: 'unknown (pgrep unavailable; group liveness probe denied)' }];
     }
 }
 function describeSurvivors(list) {
@@ -133,6 +140,8 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
         process.kill(-pgid, 'SIGTERM');
     }
     catch {
+        // The group vanished between the listing and the signal — nothing left to
+        // escalate against, so report the survivors collected so far.
         return { survivors };
     }
     await sweepDelay(graceMs);
@@ -142,6 +151,8 @@ export async function sweepProcessGroup(pgid, graceMs = SWEEP_GRACE_MS) {
             process.kill(-pgid, 'SIGKILL');
         }
         catch {
+            // The group died during the grace period, so the SIGKILL escalation has
+            // nothing to signal.
             return { survivors };
         }
         await sweepDelay(Math.min(200, graceMs));