@hominis/fireforge 0.43.1 → 0.44.0

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

@@ -3,14 +3,13 @@ export interface BuildIdentity {
     shortCommit: string;
     dirty: boolean;
     /**
-     * Content hash of the uncommitted diff, present only for a DIRTY
-     * installed build. 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.
+     * Content hash of the uncommitted diff, present only for a DIRTY installed
+     * build. 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 and a report against
+     * `<semver>+g<sha>.dirty` cannot be traced 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;
 }

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

@@ -1,20 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Build identity for `--version`. 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>]]`:
+ * Build identity for `--version`.
  *
- * - 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.
+ * Distinct builds shipping as the same plain semver leave consumers
+ * fingerprinting tarballs by sha256 to know which build a claim was verified
+ * against. `--version` 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).
+ * 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';

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

@@ -20,9 +20,8 @@ export declare function toError(error: unknown): Error;
  * 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".
+ * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
+ * code".
  */
 export declare function getNodeErrorCode(error: unknown): string | undefined;
 /**
@@ -32,10 +31,9 @@ export declare function getNodeErrorCode(error: unknown): string | undefined;
  * 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.
+ * Reading EPERM as dead in a predicate that gates a recursive delete removes
+ * a live build's tree clone or a live furnace lock out from under its owner.
+ * Any other errno is treated as "unknown, assume alive", the safe direction
+ * for every caller: it refuses rather than destroys.
  */
 export declare function isProcessAlive(pid: number): boolean;

package/dist/src/utils/errors.js

@@ -32,9 +32,8 @@ export function toError(error) {
  * 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".
+ * cross-realm throws, and an `instanceof Error` gate misclassifies it as "no
+ * code".
  */
 export function getNodeErrorCode(error) {
     if (typeof error === 'object' &&
@@ -52,11 +51,10 @@ export function getNodeErrorCode(error) {
  * 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.
+ * Reading EPERM as dead in a predicate that gates a recursive delete removes
+ * a live build's tree clone or a live furnace lock out from under its owner.
+ * Any other errno is treated as "unknown, assume alive", the safe direction
+ * for every caller: it refuses rather than destroys.
  */
 export function isProcessAlive(pid) {
     try {

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

@@ -12,6 +12,25 @@ export declare function setMachineOutputMode(enabled: boolean): void;
 export declare function isMachineOutputMode(): boolean;
 /** Seals (or unseals) stdout after a machine-readable final line. */
 export declare function setStdoutSealed(sealed: boolean): void;
+/**
+ * True when a machine-readable payload already owns stdout.
+ *
+ * The CLI error boundary consults this before emitting a `--json` error
+ * envelope: a command that wrote its payload and THEN refused (e.g.
+ * `status --json --fail-on`) must not have a second JSON document appended,
+ * which would break the "exactly one document" half of the contract in
+ * docs/machine-output.md.
+ */
+export declare function isStdoutSealed(): boolean;
+/**
+ * Checks if verbose mode is enabled.
+ *
+ * Exported so the CLI error boundary can decide whether to walk an error's
+ * `cause` chain.
+ *
+ * @returns True if verbose mode is enabled
+ */
+export declare function isVerbose(): boolean;
 /**
  * Displays a verbose/debug message (only shown if verbose mode is enabled).
  * @param message - Message to display
@@ -49,13 +68,13 @@ export declare const NOTICE_PREFIX = "[FireForge] NOTICE:";
  *
  * 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 were
+ * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
  * and errors, leaving a multi-minute build with no explanation and reading
  * as a hang. There are very few such lines and they are exactly the ones a
- * non-interactive operator needs, so they ride the warning channel and
- * carry {@link NOTICE_PREFIX} so a reader can still tell them apart from a
- * real warning.
+ * non-interactive operator needs, so they ride the warning channel and carry
+ * {@link NOTICE_PREFIX} so a reader can still tell them apart from a real
+ * warning.
  */
 export declare function notice(message: string): void;
 /** Logs an error message. */
@@ -80,12 +99,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
- * `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.
+ * `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
+ * already known not to be the sentinel. Keep the predicate form.
  */
 export declare function isCancel(value: unknown): value is symbol;
 /** Displays a titled note block for follow-up details. */

package/dist/src/utils/logger.js

@@ -9,11 +9,9 @@ let verboseMode = false;
  * 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.
- * Before this mode existed, clack's log helpers wrote styled warnings to
- * stdout *before* the JSON body — a truncated-directory warning during
- * `status --json` broke every `JSON.parse(stdout)` consumer, and error
- * objects on the machine contract were followed by a styled duplicate on
- * the same stream.
+ * Otherwise clack's log helpers write styled warnings to stdout *before* the
+ * JSON body — a truncated-directory warning during `status --json` breaks
+ * every `JSON.parse(stdout)` consumer.
  */
 let machineOutputMode = false;
 /**
@@ -50,6 +48,18 @@ let stdoutSealed = false;
 export function setStdoutSealed(sealed) {
     stdoutSealed = sealed;
 }
+/**
+ * True when a machine-readable payload already owns stdout.
+ *
+ * The CLI error boundary consults this before emitting a `--json` error
+ * envelope: a command that wrote its payload and THEN refused (e.g.
+ * `status --json --fail-on`) must not have a second JSON document appended,
+ * which would break the "exactly one document" half of the contract in
+ * docs/machine-output.md.
+ */
+export function isStdoutSealed() {
+    return stdoutSealed;
+}
 /** True when human output must avoid stdout. */
 function routeToStderr() {
     return machineOutputMode || stdoutSealed;
@@ -60,9 +70,13 @@ function writeDiagnostic(prefix, message) {
 }
 /**
  * Checks if verbose mode is enabled.
+ *
+ * Exported so the CLI error boundary can decide whether to walk an error's
+ * `cause` chain.
+ *
  * @returns True if verbose mode is enabled
  */
-function isVerbose() {
+export function isVerbose() {
     return verboseMode;
 }
 /**
@@ -128,13 +142,13 @@ export const NOTICE_PREFIX = '[FireForge] NOTICE:';
  *
  * 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 were
+ * one, sharding a run, skipping a step). Emitted through `info` they are
  * silently dropped by agent-facing output filters that keep only warnings
  * and errors, leaving a multi-minute build with no explanation and reading
  * as a hang. There are very few such lines and they are exactly the ones a
- * non-interactive operator needs, so they ride the warning channel and
- * carry {@link NOTICE_PREFIX} so a reader can still tell them apart from a
- * real warning.
+ * non-interactive operator needs, so they ride the warning channel and carry
+ * {@link NOTICE_PREFIX} so a reader can still tell them apart from a real
+ * warning.
  */
 export function notice(message) {
     if (routeToStderr()) {
@@ -238,12 +252,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
- * `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.
+ * `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
+ * already known not to be the sentinel. Keep the predicate form.
  */
 export function isCancel(value) {
     return p.isCancel(value);

package/dist/src/utils/machine-output.d.ts

@@ -0,0 +1,12 @@
+import { ExitCode } from '../errors/codes.js';
+/** Current envelope version. Bump only with a documented migration. */
+export declare const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
+/**
+ * Writes the machine-readable error envelope to stdout and throws the
+ * sentinel that carries the exit code to the entrypoint. Never returns.
+ *
+ * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
+ * @param message - Human-readable explanation, identical to the non-JSON text
+ * @param exitCode - Exit code to terminate with
+ */
+export declare function emitMachineError(code: string, message: string, exitCode?: ExitCode): never;

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

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `--json` envelope contract, in one place.
+ *
+ * Without a single owner, machine-readable output drifts into unrelated
+ * shapes: two commands sharing a `schemaVersion: 1` envelope can still
+ * disagree on failure, so a scripted consumer gets a parseable refusal from
+ * one and a bare non-zero exit from the other.
+ *
+ * The contract, documented in `docs/machine-output.md`:
+ *   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
+ *      stderr and cannot corrupt the payload.
+ */
+import { CommandError } from '../errors/base.js';
+import { ExitCode } from '../errors/codes.js';
+/** Current envelope version. Bump only with a documented migration. */
+export const MACHINE_OUTPUT_SCHEMA_VERSION = 1;
+/**
+ * Writes the machine-readable error envelope to stdout and throws the
+ * sentinel that carries the exit code to the entrypoint. Never returns.
+ *
+ * @param code - Stable machine-readable reason tag, e.g. `engine-missing`
+ * @param message - Human-readable explanation, identical to the non-JSON text
+ * @param exitCode - Exit code to terminate with
+ */
+export function emitMachineError(code, message, exitCode = ExitCode.GENERAL_ERROR) {
+    process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, error: message, code })}\n`);
+    throw new CommandError(exitCode);
+}

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

@@ -1,9 +1,18 @@
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
- * spread into typed option objects without assigning undefined to optional properties.
+ * 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`.
+ *
+ * @param obj - Object to filter
+ * @returns The same object with every `undefined`-valued key removed
  */
-export declare function pickDefined<T extends Record<string, unknown>>(obj: T): {
+export declare function pickDefined<T extends object>(obj: T): {
     [K in keyof T]+?: Exclude<T[K], undefined>;
 };
 import type { Command } from 'commander';
@@ -15,11 +24,10 @@ import type { Command } from 'commander';
  * 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 was the observed behavior for `run --smoke-exit abc` (plain Error),
- * `test --harness-retries 99` (GeneralError), and `export --order 0`
- * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
- * Every `.argParser()`/option-parser callback must be wrapped with this
- * helper (or throw commander's InvalidArgumentError directly).
+ * That covers a plain Error, a `GeneralError`, and even a FireForge
+ * `InvalidArgumentError`, whose `code` is a numeric ExitCode. Every
+ * `.argParser()`/option-parser callback must be wrapped with this helper (or
+ * throw commander's InvalidArgumentError directly).
  */
 export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw: string) => T;
 /**
@@ -30,23 +38,32 @@ export declare function commanderArgParser<T>(parse: (raw: string) => T): (raw:
  * .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.
+ * Commander types the default slot as `unknown`, so every open-coded copy
+ * carries an `[] as string[]` cast, and it is easy to mutate the accumulator
+ * in place instead of returning a new array. Returning a fresh array per
+ * call also means the default cannot be shared between two `.option()`
+ * registrations.
  */
 export declare function stringListOption(): [(value: string, previous: string[]) => string[], string[]];
+/** Environment variable naming a standing wait budget for the whole session. */
+export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
- * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
+ *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
  * - explicit value → integer validated into 1..3600.
  *
+ * The flag always wins over the environment: the environment expresses a
+ * default for a session, and an invocation that names a budget has said
+ * something more specific than the session did.
+ *
  * 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).
+ * 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.
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
 /**

package/dist/src/utils/options.js

@@ -2,19 +2,28 @@
 /**
  * Filters an object to only include keys whose values are not undefined.
  * Designed for use with exactOptionalPropertyTypes — the result can be
- * spread into typed option objects without assigning undefined to optional properties.
+ * 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`.
+ *
+ * @param obj - Object to filter
+ * @returns The same object with every `undefined`-valued key removed
  */
 export function pickDefined(obj) {
     const result = {};
-    for (const key of Object.keys(obj)) {
-        if (obj[key] !== undefined) {
-            result[key] = obj[key];
+    for (const [key, value] of Object.entries(obj)) {
+        if (value !== undefined) {
+            result[key] = value;
         }
     }
     return result;
 }
 import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
-import { GeneralError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from './errors.js';
 /**
  * Wraps an option-argument parser so its failures surface through
@@ -24,11 +33,10 @@ import { toError } from './errors.js';
  * 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 was the observed behavior for `run --smoke-exit abc` (plain Error),
- * `test --harness-retries 99` (GeneralError), and `export --order 0`
- * (FireForge InvalidArgumentError, whose `code` is a numeric ExitCode).
- * Every `.argParser()`/option-parser callback must be wrapped with this
- * helper (or throw commander's InvalidArgumentError directly).
+ * That covers a plain Error, a `GeneralError`, and even a FireForge
+ * `InvalidArgumentError`, whose `code` is a numeric ExitCode. Every
+ * `.argParser()`/option-parser callback must be wrapped with this helper (or
+ * throw commander's InvalidArgumentError directly).
  */
 export function commanderArgParser(parse) {
     return (raw) => {
@@ -48,31 +56,81 @@ export function commanderArgParser(parse) {
  * .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.
+ * Commander types the default slot as `unknown`, so every open-coded copy
+ * carries an `[] as string[]` cast, and it is easy to mutate the accumulator
+ * in place instead of returning a new array. Returning a fresh array per
+ * call also 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;
+/** Environment variable naming a standing wait budget for the whole session. */
+export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
+/** Bounds shared by the flag and the environment variable. */
+const MIN_WAIT_LOCK_SECONDS = 1;
+const MAX_WAIT_LOCK_SECONDS = 3600;
+/**
+ * Parses a wait budget from text, or undefined when it is not an integer in
+ * range. Shared by the flag and {@link WAIT_LOCK_ENV_VAR} so the two cannot
+ * drift on what they accept.
+ */
+function parseWaitLockSeconds(raw) {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < MIN_WAIT_LOCK_SECONDS || n > MAX_WAIT_LOCK_SECONDS) {
+        return undefined;
+    }
+    return n;
+}
+/**
+ * The standing wait budget from {@link WAIT_LOCK_ENV_VAR}, or undefined when
+ * it is unset or empty.
+ *
+ * Exists because a wait budget is a property of the SESSION, not of the
+ * invocation: a checkout worked by several concurrent agent sessions has a
+ * held lock as its normal state, and an unattended loop would otherwise have
+ * to thread `--wait-lock` through every command it issues — the one place
+ * it is easiest to forget, and the failure only shows up once the loop has
+ * already produced a tail of refusals.
+ *
+ * An unusable value is a usage error rather than a silent fall-back to
+ * fail-fast: the operator set it precisely because they did not want to
+ * discover the budget at refusal time.
+ */
+function waitLockSecondsFromEnv() {
+    const raw = process.env[WAIT_LOCK_ENV_VAR]?.trim();
+    if (raw === undefined || raw.length === 0) {
+        return undefined;
+    }
+    const parsed = parseWaitLockSeconds(raw);
+    if (parsed === undefined) {
+        throw new InvalidArgumentError(`${WAIT_LOCK_ENV_VAR} must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${raw}")`, WAIT_LOCK_ENV_VAR);
+    }
+    return parsed;
+}
 /**
  * Resolves the parsed `--wait-lock [seconds]` option value into a wait budget
  * in seconds for `withEngineSessionLock`:
- * - absent (`undefined`) → `undefined` (legacy ~1 s fail-fast),
+ * - absent (`undefined`) → {@link WAIT_LOCK_ENV_VAR} if set, else `undefined`
+ *   (the ~1 s fail-fast),
  * - bare flag (`true`) → {@link DEFAULT_WAIT_LOCK_SECONDS},
  * - explicit value → integer validated into 1..3600.
  *
+ * The flag always wins over the environment: the environment expresses a
+ * default for a session, and an invocation that names a budget has said
+ * something more specific than the session did.
+ *
  * 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).
+ * 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.
  */
 export function resolveWaitLockSeconds(value) {
     if (value === undefined || value === false) {
-        return undefined;
+        return waitLockSecondsFromEnv();
     }
     if (value === true) {
         return DEFAULT_WAIT_LOCK_SECONDS;
@@ -80,23 +138,21 @@ export function resolveWaitLockSeconds(value) {
     if (typeof value === 'number') {
         return value;
     }
-    const n = Number.parseInt(value, 10);
-    if (!Number.isFinite(n) || n < 1 || n > 3600) {
-        throw new GeneralError(`--wait-lock must be an integer in 1..3600 (got "${value}")`);
+    const parsed = parseWaitLockSeconds(value);
+    if (parsed === undefined) {
+        throw new GeneralError(`--wait-lock must be an integer in ${String(MIN_WAIT_LOCK_SECONDS)}..${String(MAX_WAIT_LOCK_SECONDS)} (got "${value}")`);
     }
-    return n;
+    return parsed;
 }
 /**
  * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
- * error.
+ * error — a command that rejects it with "unknown option" kills the whole
+ * sequence with a usage error instead of a lock message.
  *
- * `export` / `re-export` / `build` / `test` / `patch move-files` all
- * accept the flag; `status` and `patch staged-dependency` used to reject
- * it with "unknown option", which killed the whole sequence with a usage
- * error instead of a lock message. The flag is accepted and ignored here —
- * never silently repurposed — and the help text says so, so nobody reads
- * its presence as evidence that this command waits for anything.
+ * The flag is accepted and ignored here — never silently repurposed — and
+ * the help text says so, so nobody reads its presence as evidence that this
+ * command waits for anything.
  *
  * The value is parsed and validated exactly as the honoring variant does:
  * `--wait-lock nonsense` must still be a usage error everywhere, or the
@@ -134,5 +190,5 @@ export function ensureWaitLockOptionEverywhere(command) {
  * `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 command to release the contended lock, instead of failing on the default budget', 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. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }

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

@@ -4,15 +4,17 @@ export declare function normalizePathSlashes(path: string): string;
  * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
  * path so the same command invocation accepts both repo-root-relative paths
  * (`engine/browser/base/content/foo.js`) and engine-relative paths
- * (`browser/base/content/foo.js`). The match is case-insensitive because
- * default macOS and Windows filesystems treat `Engine/` and `engine/` as
- * the same directory; a literal lowercase-only check previously left `mach`
- * / the manifest writers resolving against a wrongly-cased prefix. Leading
- * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ * (`browser/base/content/foo.js`).
  *
- * The return value is trimmed of the same leading whitespace when the
- * prefix matched, and otherwise passed through verbatim — callers that
- * care about internal whitespace can trim on their side.
+ * The match is case-insensitive because default macOS and Windows
+ * filesystems treat `Engine/` and `engine/` as the same directory; a literal
+ * lowercase-only check leaves `mach` and the manifest writers resolving
+ * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * tab-completed inputs do not slip past the strip.
+ *
+ * The return value is trimmed of that leading whitespace when the prefix
+ * matched, and otherwise passed through verbatim — callers that care about
+ * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user
  * @returns Path relative to the engine directory (or the original when the

package/dist/src/utils/paths.js

@@ -18,15 +18,17 @@ export function normalizePathSlashes(path) {
  * Strips a leading `engine/` (or `engine\\`) segment from a user-supplied
  * path so the same command invocation accepts both repo-root-relative paths
  * (`engine/browser/base/content/foo.js`) and engine-relative paths
- * (`browser/base/content/foo.js`). The match is case-insensitive because
- * default macOS and Windows filesystems treat `Engine/` and `engine/` as
- * the same directory; a literal lowercase-only check previously left `mach`
- * / the manifest writers resolving against a wrongly-cased prefix. Leading
- * whitespace is ignored so tab-completed inputs don't slip past the strip.
+ * (`browser/base/content/foo.js`).
  *
- * The return value is trimmed of the same leading whitespace when the
- * prefix matched, and otherwise passed through verbatim — callers that
- * care about internal whitespace can trim on their side.
+ * The match is case-insensitive because default macOS and Windows
+ * filesystems treat `Engine/` and `engine/` as the same directory; a literal
+ * lowercase-only check leaves `mach` and the manifest writers resolving
+ * against a wrongly-cased prefix. Leading whitespace is ignored so
+ * tab-completed inputs do not slip past the strip.
+ *
+ * The return value is trimmed of that leading whitespace when the prefix
+ * matched, and otherwise passed through verbatim — callers that care about
+ * internal whitespace can trim on their side.
  *
  * @param filePath Path as provided by the user
  * @returns Path relative to the engine directory (or the original when the