@hominis/fireforge 0.44.0 → 0.44.2

package/dist/src/core/token-manager.js

@@ -11,7 +11,7 @@ import { loadFurnaceConfig } from './furnace-config.js';
 import { assertTokenCategoryExists, categoryHeaderExists, declareCategoryBanner, findCategorySection, findTokenDeclarationInRoot, } from './token-category.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
-import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, } from './token-variant.js';
+import { findVariantBlockDeclaration, insertVariantDeclaration, validateVariantSelector, variantBlockExists, variantBlockHasToken, variantBlockQualifier, } from './token-variant.js';
 /**
  * Dark mode behaviour for a token.
  *
@@ -95,7 +95,9 @@ function normalizeVariantOption(options) {
     }
     if (options.createCategory === true) {
         throw new InvalidArgumentError('--create-category cannot be combined with --variant; variant declarations are routed ' +
-            'into a :root<selector> block, not a category section.', 'variant');
+            'into a :root<selector> block, not a category section. Add the BASE token first ' +
+            '(with --create-category) to author the category, then add each variant with ' +
+            '--variant.', 'variant');
     }
     const result = validateVariantSelector(options.variant);
     if (!result.ok) {
@@ -103,6 +105,30 @@ function normalizeVariantOption(options) {
     }
     return result.value;
 }
+/**
+ * Narrows {@link AddTokenOptions.category} for the base-declaration path,
+ * which cannot proceed without one.
+ *
+ * `--category` used to be unconditionally required, INCLUDING under
+ * `--variant`, where the declaration is routed into a `:root<selector>`
+ * block and the category names nothing about where the token lands. The
+ * requirement existed so the argument would not be silently discarded —
+ * a fair goal that produced a mandatory argument describing nothing. Under
+ * a variant it is now optional; everywhere else this states the reason
+ * rather than leaving commander to print a bare "required option not
+ * specified".
+ *
+ * @param options - Token options
+ * @returns The category
+ */
+function requireCategory(options) {
+    if (options.category === undefined || options.category.trim() === '') {
+        throw new InvalidArgumentError('A base token declaration lands in a category section, so --category is required. ' +
+            'Pass --variant <selector> instead if this declaration belongs in a ' +
+            ':root<selector> block, where no category applies.', 'category');
+    }
+    return options.category;
+}
 /** Throws when the tokens CSS file is missing (variant mode skips category checks). */
 async function assertTokensCssExists(engineDir, tokensCssPath) {
     if (!(await pathExists(join(engineDir, tokensCssPath)))) {
@@ -112,15 +138,22 @@ async function assertTokensCssExists(engineDir, tokensCssPath) {
 /**
  * Routes a declaration into the top-level `:root<variant>` block — creating
  * the block after the base `:root` block if absent, or appending to it if
- * present. Idempotent within the block. Returns `{ added: false }` when the
- * token already lives in that block.
+ * present. Idempotent within the block.
+ *
+ * A skip carries the LOCATION of the existing declaration, mirroring
+ * {@link evaluateBaseTokenIdempotency}. The bare `{ added: false }` it used
+ * to return told the caller nothing, so a re-run intending to CHANGE a
+ * value exited 0 having changed nothing and said only "already exists" —
+ * while the base path had reported the category and line for the same
+ * situation all along.
  */
 async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant) {
     await assertTokensCssExists(engineDir, tokensCssPath);
     const filePath = join(engineDir, tokensCssPath);
     const lines = (await readText(filePath)).split('\n');
-    if (variantBlockHasToken(lines, variant, options.tokenName))
-        return { added: false };
+    const declared = findVariantBlockDeclaration(lines, variant, options.tokenName);
+    if (declared !== undefined)
+        return { added: false, existing: declared };
     const annotation = getModeAnnotation(options.mode, options.value);
     insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${options.value}; /* ${annotation} */`);
     await writeText(filePath, lines.join('\n'));
@@ -158,14 +191,17 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
-    // Variant mode targets a `:root<attr>` block, not a category section —
-    // but the required --category must still name a REAL category rather
-    // than being silently discarded (bypass 2).
+    // Variant mode targets a `:root<attr>` block, not a category section, so
+    // no category is consulted — and none is required. When one IS passed it
+    // is still checked, so a typo'd category is not silently accepted just
+    // because the flag happens to be inert here.
     if (normalizeVariantOption(options) !== undefined) {
-        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        if (options.category !== undefined && options.category.trim() !== '') {
+            await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        }
         return;
     }
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, requireCategory(options), options.createCategory === true);
 }
 /**
  * Adds a design token to the CSS file and documentation.
@@ -209,16 +245,19 @@ export async function addToken(root, options) {
     // docs row). Done before the base-CSS path so an override of an existing
     // base token is not short-circuited by the global idempotency check.
     if (normalizedVariant !== undefined) {
-        // The required --category must name a real category even though the
-        // declaration routes into the variant block (bypass 2).
-        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
-        const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
+        // A category is optional here and names nothing about where the
+        // declaration lands, but a category that was passed is still verified.
+        if (options.category !== undefined && options.category.trim() !== '') {
+            await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
+        }
+        const { added, existing } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
         return {
             cssAdded: added,
             docsAdded: false,
             unmappedAdded: false,
             countUpdated: false,
             skipped: !added,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // --- CSS file ---
@@ -234,7 +273,11 @@ export async function addToken(root, options) {
         };
     }
     // --- Documentation ---
-    const docsResult = await addTokenToDocs(engineDir, options, getModeAnnotation(options.mode, options.value));
+    // Only the base path reaches here (variant declarations returned above),
+    // so a category is guaranteed — `requireCategory` already ran inside
+    // `addTokenToCSS`. Re-narrowing rather than asserting keeps the docs
+    // input's required `category` honest.
+    const docsResult = await addTokenToDocs(engineDir, { ...options, category: requireCategory(options) }, getModeAnnotation(options.mode, options.value));
     return {
         cssAdded,
         docsAdded: docsResult.docsAdded,
@@ -274,6 +317,16 @@ function insertThemeAttributeOverrides(lines, options) {
         const value = pick === 'dark' ? options.darkValue : options.value;
         insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${value};`);
         written.push(`:root${variant}`);
+        // A qualified block is matched — skipping it is the worse failure, and
+        // the one that shipped — but the qualifier narrows where the token
+        // applies, so say which selector was written through rather than
+        // letting the operator meet the narrowing as a theme bug later.
+        const qualifier = variantBlockQualifier(lines, variant);
+        if (qualifier !== undefined && qualifier.length > 0) {
+            warn(`Wrote ${options.tokenName} into the qualified block ":root${variant}${qualifier}". ` +
+                `The "${qualifier}" qualifier narrows where this override applies; ` +
+                'add an unqualified block if it should apply to every case.');
+        }
     }
     return written;
 }
@@ -304,7 +357,8 @@ function insertDarkModeOverride(lines, options) {
  */
 async function addTokenToCSS(engineDir, options, tokensCssPath) {
     const filePath = join(engineDir, tokensCssPath);
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
+    const category = requireCategory(options);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, category, options.createCategory === true);
     const content = await readText(filePath);
     const lines = content.split('\n');
     // Per-category idempotency: a declaration in the TARGET
@@ -324,11 +378,11 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     // token insertion — the file is written exactly once, so a failure
     // between "banner declared" and "token inserted" cannot occur.
     let categoryCreated = false;
-    if (options.createCategory === true && !categoryHeaderExists(lines, options.category)) {
-        declareCategoryBanner(lines, options.category, tokensCssPath);
+    if (options.createCategory === true && !categoryHeaderExists(lines, category)) {
+        declareCategoryBanner(lines, category, tokensCssPath);
         categoryCreated = true;
     }
-    const { categoryLine, sectionEnd } = findCategorySection(lines, options.category, tokensCssPath);
+    const { categoryLine, sectionEnd } = findCategorySection(lines, category, tokensCssPath);
     // Build the insertion lines
     const insertLines = [];
     if (options.description) {

package/dist/src/core/token-variant.d.ts

@@ -9,6 +9,7 @@
  * `:root<variant>` block so `token-manager.ts` can splice a declaration into
  * it, keeping all token authoring in the CLI.
  */
+import type { TokenDeclarationLocation } from './token-category.js';
 /**
  * Outcome of {@link validateVariantSelector}. `ok: true` carries the
  * normalized (quoted) selector fragment; `ok: false` carries a
@@ -36,8 +37,41 @@ export declare function validateVariantSelector(raw: unknown): VariantValidation
  * the block, which is only wanted for the explicit `--variant` flow.
  */
 export declare function variantBlockExists(lines: string[], variant: string): boolean;
+/**
+ * The pseudo-class qualifier on the matched `:root<variant>` block, or
+ * `undefined` when no block matched. `''` for an unqualified block.
+ *
+ * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
+ * writing into that block scopes the declaration to the qualified case, and
+ * that may not be what the operator meant. Matching it is still the right
+ * call — silently skipping it is the worse failure, and the one that
+ * shipped — but the override path uses this to say out loud which selector
+ * it wrote through, so the narrowing is a visible decision rather than a
+ * theme bug discovered later.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
+ * @returns The qualifier, or undefined when no block matched
+ */
+export declare function variantBlockQualifier(lines: string[], variant: string): string | undefined;
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
+/**
+ * Locates an existing declaration of `tokenName` inside the
+ * `:root<variant>` block, or `undefined` when the block has none (or does
+ * not exist).
+ *
+ * The located form of {@link variantBlockHasToken}: the variant add path
+ * reports a skip the way the base path does — naming the block and the
+ * line — instead of returning a bare boolean that leaves a no-op re-run
+ * indistinguishable from a write.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment
+ * @param tokenName - Full token name including prefix
+ * @returns The declaration's 1-based line, or undefined
+ */
+export declare function findVariantBlockDeclaration(lines: string[], variant: string, tokenName: string): TokenDeclarationLocation | undefined;
 /**
  * Splices `declLine` into the `:root<variant>` block, creating the block
  * (after the base `:root` block) when absent or appending after the last

package/dist/src/core/token-variant.js

@@ -52,6 +52,48 @@ export function validateVariantSelector(raw) {
 function canonicalSelector(selector) {
     return selector.replace(/\s+/g, '').replace(/["']/g, '');
 }
+/**
+ * Splits the `:root[…]` selector on `line` into its attribute run and any
+ * trailing qualifier, or `null` when the line carries none.
+ *
+ * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
+ * so that pattern backtracks quadratically on a line repeating `:root[`
+ * (CodeQL `js/polynomial-redos`). This walk is linear and allocation-free
+ * per group.
+ *
+ * It consumes CONSECUTIVE `[…]` groups and stops at the first character that
+ * is not `[`. The previous implementation instead sliced to the LAST `]`
+ * before the brace, which kept multi-attribute selectors comparing as a
+ * whole — that property is preserved here, since consecutive groups are all
+ * consumed — but it also swallowed a pseudo-class tail. On
+ * `:root[data-theme="light"]:not([data-private]) {` the last `]` is the one
+ * inside `:not(…)`, so the computed fragment was
+ * `:root[data-theme="light"]:not([data-private]` and the canonical
+ * comparison could never match. The unqualified
+ * `:root[data-theme="dark"] { }` beside it matched fine, and that asymmetry
+ * WAS the bug: an override add mirrored itself into the dark block and
+ * silently skipped the light one, which is precisely the half-finished
+ * themed edit `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
+ */
+function rootAttributeSelector(line) {
+    const start = line.indexOf(':root[');
+    if (start === -1)
+        return null;
+    const brace = line.indexOf('{', start);
+    const limit = brace === -1 ? line.length : brace;
+    let cursor = start + ':root'.length;
+    let end = cursor;
+    while (cursor < limit && line[cursor] === '[') {
+        const close = line.indexOf(']', cursor);
+        if (close === -1 || close >= limit)
+            break;
+        cursor = close + 1;
+        end = cursor;
+    }
+    if (end === start + ':root'.length)
+        return null;
+    return { attributes: line.slice(start, end), qualifier: line.slice(end, limit).trim() };
+}
 /**
  * Finds the top-level `:root<variant>` block whose attribute selector
  * matches `variant` (compared canonically). Returns the opening-brace and
@@ -66,8 +108,8 @@ function findVariantBlock(lines, variant) {
     const want = canonicalSelector(`:root${variant}`);
     for (let i = 0; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
-        const match = /:root\[[^{]*\]/.exec(line);
-        if (!match || canonicalSelector(match[0]) !== want)
+        const selector = rootAttributeSelector(line);
+        if (selector === null || canonicalSelector(selector.attributes) !== want)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
         if (openLine === -1) {
@@ -86,7 +128,7 @@ function findVariantBlock(lines, variant) {
         const close = findBlockCloseIndex(stripped, openLine);
         if (close === -1)
             continue;
-        return { open: openLine, close };
+        return { open: openLine, close, qualifier: selector.qualifier };
     }
     return null;
 }
@@ -116,16 +158,64 @@ function findVariantBlockInsertionPoint(lines) {
 export function variantBlockExists(lines, variant) {
     return findVariantBlock(lines, variant) !== null;
 }
+/**
+ * The pseudo-class qualifier on the matched `:root<variant>` block, or
+ * `undefined` when no block matched. `''` for an unqualified block.
+ *
+ * A qualifier such as `:not([data-private])` is semantically LOAD-BEARING:
+ * writing into that block scopes the declaration to the qualified case, and
+ * that may not be what the operator meant. Matching it is still the right
+ * call — silently skipping it is the worse failure, and the one that
+ * shipped — but the override path uses this to say out loud which selector
+ * it wrote through, so the narrowing is a visible decision rather than a
+ * theme bug discovered later.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
+ * @returns The qualifier, or undefined when no block matched
+ */
+export function variantBlockQualifier(lines, variant) {
+    return findVariantBlock(lines, variant)?.qualifier;
+}
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export function variantBlockHasToken(lines, variant, tokenName) {
+    return findVariantBlockDeclaration(lines, variant, tokenName) !== undefined;
+}
+/**
+ * Locates an existing declaration of `tokenName` inside the
+ * `:root<variant>` block, or `undefined` when the block has none (or does
+ * not exist).
+ *
+ * The located form of {@link variantBlockHasToken}: the variant add path
+ * reports a skip the way the base path does — naming the block and the
+ * line — instead of returning a bare boolean that leaves a no-op re-run
+ * indistinguishable from a write.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param variant - Attribute selector fragment
+ * @param tokenName - Full token name including prefix
+ * @returns The declaration's 1-based line, or undefined
+ */
+export function findVariantBlockDeclaration(lines, variant, tokenName) {
     const block = findVariantBlock(lines, variant);
     if (!block)
-        return false;
-    const blockText = lines
-        .slice(block.open, block.close + 1)
+        return undefined;
+    // Comments are stripped across the WHOLE block before scanning, matching
+    // what the boolean form always did: a `/* … */` spanning several lines
+    // must not leave its tail looking like a declaration.
+    const blockLines = lines.slice(block.open, block.close + 1);
+    // Blank the comment's CHARACTERS rather than deleting it: removing a
+    // multi-line comment outright collapses its lines and shifts every line
+    // number after it, which is the one thing this function exists to report.
+    const stripped = blockLines
         .join('\n')
-        .replace(/\/\*[\s\S]*?\*\//g, '');
-    return blockText.includes(`${tokenName}:`);
+        .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
+        .split('\n');
+    for (let i = 0; i < stripped.length; i++) {
+        if ((stripped[i] ?? '').includes(`${tokenName}:`))
+            return { line: block.open + i + 1 };
+    }
+    return undefined;
 }
 /**
  * Splices `declLine` into the `:root<variant>` block, creating the block

package/dist/src/core/tree-store.js

@@ -443,7 +443,11 @@ async function inspectTreeLock(lockPath) {
  */
 export async function removeTree(primaryRoot, name, options = {}) {
     assertValidTreeName(name);
-    const treesDir = getTreesDir(primaryRoot);
+    // Both sides resolved: the containment prefix has to be in the same form as
+    // the path it guards. `getTreesDir` is a `join`, so on Windows it yields a
+    // drive-less path while `resolve` below adds the drive letter — the prefix
+    // test then failed for EVERY tree and refused each removal as an escape.
+    const treesDir = resolve(getTreesDir(primaryRoot));
     const treeRoot = resolve(treesDir, name);
     if (!treeRoot.startsWith(treesDir + sep) || basename(treeRoot) !== name) {
         throw new GeneralError(`Refusing to remove "${name}": resolved path escapes the trees directory.`);

package/dist/src/core/typecheck.js

@@ -22,6 +22,7 @@ import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
@@ -239,7 +240,12 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     // file — and never write it to disk. The CompilerHost below serves
     // it from `shimSource` for `fileExists`/`readFile`/`getSourceFile`.
     const projectDir = dirname(absConfig);
-    const shimPath = resolve(projectDir, `.fireforge-${SHIM_FILENAME}`);
+    // Forward slashes deliberately: TypeScript normalizes every `fileName` it
+    // hands a CompilerHost, on every platform. A shim path carrying Windows
+    // separators never matches those callbacks, so the shim is not served (its
+    // globals report as undefined identifiers) and its own diagnostics are not
+    // filtered out below — the pass reports failures that do not exist.
+    const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
     const rootFiles = [...parsed.fileNames, shimPath];
     const defaultHost = ts.createCompilerHost(options);
     const host = {

package/dist/src/types/commands/options.d.ts

@@ -539,6 +539,12 @@ export interface RunOptions {
 export interface TestOptions {
     /** Run tests in headless mode */
     headless?: boolean;
+    /**
+     * Pass mozbuild's full verbosity through for the TEST phase by unsetting
+     * the coding-agent markers it quiets output on. Off by default, because
+     * that quieting is worth keeping for builds.
+     */
+    fullOutput?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
     /**
@@ -652,6 +658,12 @@ export interface FurnaceApplyOptions {
     force?: boolean;
     /** Watch component directories and re-apply on changes */
     watch?: boolean;
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace preview command.
@@ -670,6 +682,12 @@ export interface FurnaceDeployOptions {
     force?: boolean;
     /** Skip the validation step (apply only, no accessibility/compatibility checks) */
     skipValidate?: boolean;
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace refresh command.
@@ -692,6 +710,12 @@ export interface FurnaceSyncOptions {
     dryRun?: boolean;
     /** Conflict resolution strategy for three-way merge (ours = keep local, theirs = accept upstream) */
     strategy?: 'ours' | 'theirs';
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default.
+     * Threaded to the furnace lock `runFurnaceMutation` takes INSIDE the
+     * engine session lock, so one flag governs both.
+     */
+    waitLockSeconds?: number;
 }
 /**
  * Options for the furnace validate command.
@@ -965,7 +989,12 @@ export interface StatusOptions {
  * Options for the token add command.
  */
 export interface TokenAddOptions {
-    category: string;
+    /**
+     * Required for a base declaration; optional under
+     * {@link TokenAddOptions.variant}, which routes into a `:root<selector>`
+     * block where no category applies.
+     */
+    category?: string;
     mode: string;
     description?: string;
     darkValue?: string;
@@ -987,7 +1016,30 @@ export interface DoctorOptions {
      * the patch manifest under that lock.
      */
     waitLock?: number | boolean;
+    /**
+     * Rebuild patches.json from the on-disk patch files, preserving every
+     * field the patch bodies cannot express. Refused when patches.json exists
+     * but cannot be parsed, unless `allowMetadataLoss` is also set.
+     */
     repairPatchesManifest?: boolean;
+    /**
+     * Repair only the `filesAffected` lists that disagree with their patch
+     * body. Narrower than `repairPatchesManifest`: it rewrites one field on the
+     * drifted rows and leaves every other row byte-identical, and it needs no
+     * project config, so it works on a project whose fireforge.json is broken.
+     */
+    repairFilesAffected?: boolean;
+    /**
+     * Accept the whole-manifest metadata reinvention that rebuilding an
+     * unparseable patches.json implies. Only meaningful with
+     * `repairPatchesManifest`.
+     */
+    allowMetadataLoss?: boolean;
+    /**
+     * Project what a requested repair would change and write nothing. Refused
+     * without a repair flag rather than accepted as a silent no-op.
+     */
+    dryRun?: boolean;
     /**
      * Clear a stale `pendingResolution` marker, but only after the same
      * read-only queue health checks used by `fireforge verify` report no

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

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+/** The `env` / `envUnset` slice of exec options this module needs. */
+export interface ChildEnvOptions {
+    /** Variables to add or overwrite on top of `process.env`. */
+    env?: Record<string, string> | undefined;
+    /** Variables to remove after the merge. */
+    envUnset?: readonly string[] | undefined;
+}
+/**
+ * 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
+ * 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
+ * `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;

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

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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.
+ */
+/**
+ * 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
+ * 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
+ * `delete obj[key]` because the key is computed.
+ *
+ * @param options - Options carrying `env` / `envUnset`
+ * @returns The environment to hand `spawn`
+ */
+export function buildChildEnv(options) {
+    const merged = { ...process.env, ...options.env };
+    for (const key of options.envUnset ?? []) {
+        Reflect.deleteProperty(merged, key);
+    }
+    return merged;
+}

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

@@ -66,6 +66,28 @@ export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
  * 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
+ * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
+ *
+ * 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
+ * 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
+ * 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
+ * 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.
+ *
+ * @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
@@ -85,5 +107,11 @@ export declare function ensureWaitLockOptionEverywhere(command: Command): void;
  * 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
+ * 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.
  */
 export declare function addWaitLockOption(command: Command): Command;

package/dist/src/utils/options.js

@@ -144,6 +144,31 @@ export function resolveWaitLockSeconds(value) {
     }
     return parsed;
 }
+/**
+ * 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
+ * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
+ * 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
+ * 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
+ * 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.
+ *
+ * @returns The session budget in milliseconds, or undefined
+ */
+export function sessionWaitLockMs() {
+    const seconds = waitLockSecondsFromEnv();
+    return seconds === undefined ? undefined : seconds * 1000;
+}
 /**
  * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
@@ -188,7 +213,13 @@ export function ensureWaitLockOptionEverywhere(command) {
  * 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
+ * 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.
  */
 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. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
+    return command.option('--wait-lock [seconds]', `Wait up to this many seconds (default 60) for another FireForge command to release EVERY lock this command takes, 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)));
 }