@hominis/fireforge 0.44.1 → 0.44.2

package/dist/src/commands/re-export-scan.js

@@ -2,6 +2,7 @@
 import { dirname, join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { listTrackedInHead } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
@@ -85,7 +86,10 @@ async function scanPatchFilesTargeted(args) {
     const exists = await mapWithConcurrency(scanFiles, PATH_PROBE_CONCURRENCY, (file) => pathExists(join(engineDir, file)));
     for (const [index, file] of scanFiles.entries()) {
         if (exists[index] !== true) {
-            throw new InvalidArgumentError(`--scan-file path not found in engine/: ${file}`, '--scan-file');
+            throw new InvalidArgumentError(`--scan-file path not found in engine/: ${file}. ` +
+                '--scan-file brings a path INTO patch ownership, which needs content to diff. ' +
+                'If the path was deleted and the patch already owns it, a plain re-export now ' +
+                'captures the deletion — no scan flag is needed.', '--scan-file');
         }
         if (!currentSet.has(file))
             added.push(file);
@@ -93,9 +97,21 @@ async function scanPatchFilesTargeted(args) {
     const removed = await findRemovedFiles(currentFilesAffected, engineDir);
     return reportScanResult(currentFilesAffected, patchFilename, isDryRun, added.sort(), removed);
 }
+/**
+ * Paths that have genuinely left the patch's ownership: absent from disk AND
+ * untracked in engine HEAD.
+ *
+ * An absent path that IS tracked in HEAD is a DELETION, not a de-ownership.
+ * The diff carries it as a `deleted file mode` section, so it must stay in
+ * `filesAffected` — pruning it desynchronises the manifest from the patch
+ * body in the direction that hurts: the body says "delete this file", the
+ * file list says the patch has nothing to do with it.
+ */
 async function findRemovedFiles(files, engineDir) {
     const exists = await mapWithConcurrency(files, PATH_PROBE_CONCURRENCY, (file) => pathExists(join(engineDir, file)));
-    return files.filter((_, index) => exists[index] !== true).sort();
+    const absent = files.filter((_, index) => exists[index] !== true);
+    const trackedAbsent = await listTrackedInHead(engineDir, absent);
+    return absent.filter((file) => !trackedAbsent.has(file)).sort();
 }
 function reportScanResult(currentFilesAffected, patchFilename, isDryRun, added, removed) {
     for (const f of added)

package/dist/src/commands/re-export-single.js

@@ -9,6 +9,7 @@ import { getProjectPaths } from '../core/config.js';
 import { stdioIsInteractive } from '../core/destructive.js';
 import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { listTrackedInHead } from '../core/git-file-ops.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { isGitIndexLockConflict } from '../errors/git.js';
@@ -111,17 +112,28 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
     // --allow-stale-furnace) before diffing. Runs in dry-run too so the failure
     // surfaces early.
     await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
-    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
-    if (missingFiles.length === currentFilesAffected.length) {
+    const absentFiles = await findMissingFiles(paths.engine, currentFilesAffected);
+    // A path absent from disk but tracked in engine HEAD is a DELETION, and
+    // `git diff HEAD` renders it as a real `deleted file mode` section. Only
+    // a never-tracked path has nothing to diff. Skipping both alike meant a
+    // retired file quietly left the patch body while staying in its file
+    // list — the patch then claimed a file it could not restore.
+    const trackedAbsent = await listTrackedInHead(paths.engine, absentFiles);
+    const deletedFiles = absentFiles.filter((f) => trackedAbsent.has(f));
+    const untrackedAbsent = absentFiles.filter((f) => !trackedAbsent.has(f));
+    if (untrackedAbsent.length === currentFilesAffected.length) {
         warn(`Skipped ${patch.filename}: all affected files missing`);
-        warn(`Missing files: ${missingFiles.join(', ')}`);
+        warn(`Missing files: ${untrackedAbsent.join(', ')}`);
         return false;
     }
-    if (missingFiles.length > 0) {
-        warn(`${patch.filename}: missing files will be skipped: ${missingFiles.join(', ')}`);
+    if (untrackedAbsent.length > 0) {
+        warn(`${patch.filename}: missing files will be skipped: ${untrackedAbsent.join(', ')}`);
     }
-    const missingSet = new Set(missingFiles);
-    const existingFiles = currentFilesAffected.filter((f) => !missingSet.has(f));
+    if (deletedFiles.length > 0) {
+        info(`${patch.filename}: capturing deletion of ${deletedFiles.join(', ')}`);
+    }
+    const untrackedSet = new Set(untrackedAbsent);
+    const existingFiles = currentFilesAffected.filter((f) => !untrackedSet.has(f));
     const diffContent = await getDiffForFilesAgainstHead(paths.engine, existingFiles);
     assertScanFileAdditionsHaveDiffHunks({
         diffContent,

package/dist/src/commands/test-register.js

@@ -29,7 +29,10 @@ const TEST_HELP_TEXT = [
     '--doctor) ends with exactly one raw stdout line',
     '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
     '  no-tests|preflight|inconclusive|lock-timeout] [checks=<n>]',
-    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)]',
+    '  [unexpected=<n>] [shards=<p>/<t>] [(<note>)] [log=<path>]',
+    "log=<path> names this run's complete output, written to",
+    '.fireforge/logs/ as the run streams, so a piped or truncated run',
+    'still leaves a re-readable artifact.',
     'The status follows the harness classifier, not the raw exit code:',
     'a crash-classified run says FAIL reason=crash even at exit 0, and',
     'a green-summary-override pass says PASS despite a non-zero mach',
@@ -55,6 +58,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .command('test [paths...]')
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
+        .option('--full-output', "Pass mozbuild's full verbosity through for the TEST phase. mozbuild quiets terminal output to warnings and errors when it detects a coding agent, which removes TEST_START and console INFO — the lines a hang or stall diagnosis needs. This unsets that detection for test dispatches only; the build phase stays quiet.")
         .option('--build', 'Run incremental UI build before testing')
         .option('--build-only', 'Run the scoped pre-test build (packaging exactly [paths...], mixed harnesses allowed) and exit without dispatching tests — one build covers both harness halves, then run each half without --build')
         .option('--extend-coverage', 'With --build/--build-only and explicit paths, union those paths into the recorded test-packaging coverage instead of replacing it, so an earlier scoped build stays covered. Refused when the build anchor moved (engine HEAD, mozconfig, or a previously fingerprinted packageable file changed).')

package/dist/src/commands/test-run.d.ts

@@ -40,6 +40,11 @@ export interface TestRunContext {
     headless: boolean;
     /** Extra environment variables for the mach process. */
     env?: Record<string, string>;
+    /**
+     * Pass full mozbuild verbosity through for the TEST phase, by unsetting
+     * the coding-agent markers that quiet it. Off by default.
+     */
+    fullOutput?: boolean;
 }
 /** Outcome of one (possibly retried) harness invocation. */
 export interface TestRunOutcome {

package/dist/src/commands/test-run.js

@@ -60,10 +60,17 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     let verdict;
     for (;;) {
         attempts += 1;
-        result = env
-            ? await dispatch(ctx.engineDir, paths, extraArgs, env)
-            : await dispatch(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch);
+        // Arity is kept minimal when there is nothing extra to pass: the
+        // dispatchers' trailing parameters are optional, and appending explicit
+        // `undefined`s would only make every call site's shape depend on
+        // features the run is not using.
+        result =
+            ctx.fullOutput === true
+                ? await dispatch(ctx.engineDir, paths, extraArgs, env, true)
+                : env
+                    ? await dispatch(ctx.engineDir, paths, extraArgs, env)
+                    : await dispatch(ctx.engineDir, paths, extraArgs);
+        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch, ctx.fullOutput);
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)

package/dist/src/commands/test-verdict.js

@@ -1,3 +1,5 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { getActiveRunLogPath } from '../core/run-log.js';
 import { formatFireforgeVerdictLine } from '../core/test-harness-crash.js';
 import { setStdoutSealed } from '../utils/logger.js';
 let emitted = false;
@@ -38,7 +40,14 @@ function writeVerdictLine(line) {
     if (emitted)
         return;
     emitted = true;
-    process.stdout.write(`${line}\n`);
+    // The run log's path rides the verdict line because the verdict must stay
+    // the run's LAST stdout write — a separate announcement after it would
+    // break that contract, and one before it is the first thing a `tail` cuts.
+    // Appended as an additive `key=value`, so consumers that tokenize the line
+    // are unaffected and a truncated tail still says where the full output is.
+    const logPath = getActiveRunLogPath();
+    const suffix = logPath === undefined ? '' : ` log=${logPath}`;
+    process.stdout.write(`${line}${suffix}\n`);
     setStdoutSealed(true);
 }
 /**

package/dist/src/commands/test.js

@@ -8,6 +8,7 @@ import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { closeActiveRunLog, openRunLog, setActiveRunLog } from '../core/run-log.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
@@ -276,6 +277,10 @@ const TEST_BUILD_PREFLIGHT = {
 export async function testCommand(projectRoot, testPaths, options = {}) {
     intro('FireForge Test');
     resetVerdictEmission();
+    // Opened before ANY work so a preflight refusal is logged too — those are
+    // exactly the runs whose only output a `tail` throws away. Closed in
+    // `finally`, after the verdict line has already read the path.
+    setActiveRunLog(await openRunLog(projectRoot, 'test'));
     try {
         await runTestCommandBody(projectRoot, testPaths, options);
     }
@@ -284,6 +289,9 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             emitFailVerdict('preflight');
         throw error;
     }
+    finally {
+        await closeActiveRunLog();
+    }
 }
 /**
  * Verifies `engine/` did not change under the run before any PASS verdict
@@ -422,6 +430,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
         baseExtraArgs: extraArgs,
         harnessRetries,
         headless: options.headless === true,
+        ...(options.fullOutput === true ? { fullOutput: true } : {}),
         ...(perfSampleEnv ? { env: perfSampleEnv } : {}),
     };
     const postRebuildContext = options.build

package/dist/src/commands/token.js

@@ -35,6 +35,27 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
     }
     return normalizeTokenName(rawTokenName);
 }
+/**
+ * Reports a no-op add, naming WHERE the existing declaration lives.
+ *
+ * A variant skip has no category to name — the declaration lives in a
+ * `:root<selector>` block — so the location reads as that block. The
+ * variant path used to report no location at all, so a re-run meant to
+ * CHANGE a value exited 0 having silently changed nothing.
+ *
+ * @param tokenName - Full token name including prefix
+ * @param result - Result carrying the skip location, when known
+ * @param options - The invocation's options
+ */
+function reportSkippedToken(tokenName, result, options) {
+    const scope = options.variant !== undefined
+        ? `:root${options.variant}`
+        : `category "${result.skippedExisting?.category ?? options.category ?? ''}"`;
+    const where = result.skippedExisting
+        ? ` in ${scope} (line ${String(result.skippedExisting.line)}), unchanged`
+        : '';
+    info(`Token ${tokenName} already exists${where} (skipped)`);
+}
 /**
  * Adds a design token to the CSS file and documentation.
  *
@@ -68,8 +89,8 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
         await validateTokenAdd(projectRoot, {
             tokenName,
             value,
-            category: options.category,
             mode: options.mode,
+            ...(options.category !== undefined ? { category: options.category } : {}),
             ...(options.description !== undefined ? { description: options.description } : {}),
             ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
             ...(options.createCategory === true ? { createCategory: true } : {}),
@@ -83,7 +104,7 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
             info(`  Variant: :root${options.variant}`);
         }
         else {
-            info(`  Category: ${options.category}${options.createCategory === true ? ' (created if missing)' : ''}`);
+            info(`  Category: ${options.category ?? '(none)'}${options.createCategory === true ? ' (created if missing)' : ''}`);
         }
         info(`  Mode: ${options.mode}`);
         if (options.description)
@@ -96,24 +117,21 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     const result = await addToken(projectRoot, {
         tokenName,
         value,
-        category: options.category,
         mode: options.mode,
+        ...(options.category !== undefined ? { category: options.category } : {}),
         ...(options.description !== undefined ? { description: options.description } : {}),
         ...(options.darkValue !== undefined ? { darkValue: options.darkValue } : {}),
         ...(options.createCategory === true ? { createCategory: true } : {}),
         ...(options.variant !== undefined ? { variant: options.variant } : {}),
     });
     if (result.skipped) {
-        const where = result.skippedExisting
-            ? ` in category "${result.skippedExisting.category ?? options.category}" (line ${String(result.skippedExisting.line)})`
-            : '';
-        info(`Token ${tokenName} already exists${where} (skipped)`);
+        reportSkippedToken(tokenName, result, options);
     }
     else {
         const forgeConfig = await loadConfig(projectRoot);
         const tokensCssFile = getTokensCssPath(forgeConfig.binaryName).split('/').pop();
         if (result.categoryCreated)
-            success(`Created category "${options.category}"`);
+            success(`Created category "${options.category ?? ''}"`);
         if (result.cssAdded)
             success(`Added ${tokenName} to ${tokensCssFile}`);
         if (result.docsAdded)
@@ -141,7 +159,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     token
         .command('add <token-name> <value>')
         .description('Add a design token to CSS and documentation. The token name is a positional argument, but most tokens start with `--` (CSS custom property syntax), which Commander reads as an option flag. Use the standard `--` separator to mark the end of options before the token name, e.g. `fireforge token add --mode static --category Colors -- --my-token "#fff"`. Bare names without `--` are accepted directly and prefixed using the configured Furnace `tokenPrefix`.')
-        .requiredOption('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing")')
+        .option('--category <cat>', 'Token category (e.g., "Colors — Canvas", "Spacing"). Required for a base declaration; ' +
+        'not required with --variant, which routes into a :root<selector> block where no ' +
+        'category applies')
         .addOption(
     // Use Commander's .choices() so invalid --mode values are rejected with
     // the built-in "argument must be one of …" message and --help lists the
@@ -161,14 +181,16 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
         .option('--variant <selector>', 'Attribute selector fragment routing the declaration into a `:root<selector>` block ' +
         "(e.g. '[data-skin=precision]' or '[data-private]'); creates or updates the block. " +
-        'CSS-only — cannot be combined with --mode override.')
+        'CSS-only — cannot be combined with --mode override or --create-category. To author ' +
+        'a new category and its variants, add the BASE token first (with --create-category), ' +
+        'then add each variant with --variant.')
         .option('--create-category', 'Declare the category banner in the tokens CSS if it does not exist yet')
         .option('--dry-run', 'Show what would be changed without writing')
         .action(withErrorHandling(async (tokenName, value, options) => {
         await tokenAddCommand(getProjectRoot(), tokenName, value, {
-            category: options.category,
             mode: options.mode,
             ...pickDefined({
+                category: options.category,
                 description: options.description,
                 darkValue: options.darkValue,
                 dryRun: options.dryRun,

package/dist/src/core/build-audit.js

@@ -37,6 +37,7 @@ import { readdir, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { detectPlatformGate } from './build-audit-platform.js';
 import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
 import { countTrailingSegmentMatches, GENERIC_PATH_SEGMENTS, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
@@ -229,8 +230,11 @@ function isConfidentMatch(source, candidate) {
     if (countTrailingSegmentMatches(source, candidate) >= MIN_TRAILING_SEGMENT_OVERLAP) {
         return true;
     }
-    const sourceSegs = source.split('/').filter(Boolean);
-    const candSegs = candidate.split('/').filter(Boolean);
+    // The candidate is an absolute path built by `join` over a dist/ walk, so on
+    // Windows it arrives backslash-separated; a `/`-only split collapses it into
+    // one segment and the non-generic-segment bonus can never fire.
+    const sourceSegs = normalizePathSlashes(source).split('/').filter(Boolean);
+    const candSegs = normalizePathSlashes(candidate).split('/').filter(Boolean);
     const generic = GENERIC_PATH_SEGMENTS;
     // Skip the basename itself (which trail-matches by definition).
     for (let i = 0; i < sourceSegs.length - 1; i += 1) {

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

@@ -26,7 +26,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
-import { normalizePathSlashes } from '../utils/paths.js';
+import { isPathInsideRoot, normalizePathSlashes } from '../utils/paths.js';
 import { getFurnacePaths } from './furnace-config.js';
 /** Chrome URL prefix under which registered custom-element files deploy. */
 const CHROME_ELEMENTS_URL_PREFIX = 'chrome://global/content/elements/';
@@ -84,8 +84,10 @@ function isManagedEntry(key, value, jsconfigDir, customDir) {
         return false;
     if (!Array.isArray(value) || value.length !== 1 || typeof value[0] !== 'string')
         return false;
-    const target = resolve(jsconfigDir, value[0]);
-    return target.startsWith(resolve(customDir) + '/') || target === resolve(customDir);
+    // Containment via `relative`, not a string prefix: a hard-coded `'/'`
+    // separator never matches the backslashes `resolve` emits on Windows, which
+    // demoted every managed entry to "unmanaged" there — no pruning, no updates.
+    return isPathInsideRoot(customDir, resolve(jsconfigDir, value[0]));
 }
 /**
  * Reconciles the managed `compilerOptions.paths` entries of the configured

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

@@ -56,8 +56,16 @@ export interface RunFurnaceMutationOptions {
      */
     dryRun?: boolean;
     /**
-     * Override the default 30s lock timeout. The watch-mode caller may want a
-     * shorter window so an interactive rebuild fails fast instead of stalling.
+     * Override the default 30 s furnace-lock timeout.
+     *
+     * Set from the caller's resolved `--wait-lock` budget, so ONE flag governs
+     * both locks a furnace mutation takes. Before that it was declared and
+     * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
+     * engine session lock and then met `.fireforge/furnace.lock` with a fixed
+     * 30 s, which is the worst shape a budget can have — it pays the whole
+     * wait and still refuses. When absent, {@link sessionWaitLockMs} supplies
+     * the session-wide budget so the twelve furnace mutators that declare no
+     * flag are covered too.
      */
     lockTimeoutMs?: number;
     /**
@@ -67,6 +75,21 @@ export interface RunFurnaceMutationOptions {
      */
     skipPendingRepairCheck?: boolean;
 }
+/**
+ * Converts a resolved `--wait-lock` budget in seconds into the
+ * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
+ * lock. Undefined in, empty out — so the caller can spread it
+ * unconditionally without assigning `undefined` under
+ * `exactOptionalPropertyTypes`.
+ *
+ * A helper rather than three inline spreads: the seconds-to-milliseconds
+ * conversion is exactly the kind of thing that gets copied once correctly
+ * and once with the factor dropped.
+ *
+ * @param waitLockSeconds - Resolved budget in seconds, or undefined
+ * @returns `{ lockTimeoutMs }`, or `{}` when no budget applies
+ */
+export declare function waitLockMutationOptions(waitLockSeconds: number | undefined): Pick<RunFurnaceMutationOptions, 'lockTimeoutMs'>;
 /**
  * Returns true while a signal-driven rollback is in progress. The bin entry
  * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot

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

@@ -4,12 +4,30 @@ import { FurnaceError } from '../errors/furnace.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
+import { sessionWaitLockMs } from '../utils/options.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { readLockStatus, releaseLockIfOwned, withFileLock } from './file-lock.js';
 import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
 import { restoreRollbackJournal, restoreRollbackJournalOrThrow, } from './furnace-rollback.js';
 /** Sidecar lock filename used to serialize concurrent furnace mutations. */
 const FURNACE_LOCK_FILENAME = 'furnace.lock';
+/**
+ * Converts a resolved `--wait-lock` budget in seconds into the
+ * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
+ * lock. Undefined in, empty out — so the caller can spread it
+ * unconditionally without assigning `undefined` under
+ * `exactOptionalPropertyTypes`.
+ *
+ * A helper rather than three inline spreads: the seconds-to-milliseconds
+ * conversion is exactly the kind of thing that gets copied once correctly
+ * and once with the factor dropped.
+ *
+ * @param waitLockSeconds - Resolved budget in seconds, or undefined
+ * @returns `{ lockTimeoutMs }`, or `{}` when no budget applies
+ */
+export function waitLockMutationOptions(waitLockSeconds) {
+    return waitLockSeconds === undefined ? {} : { lockTimeoutMs: waitLockSeconds * 1000 };
+}
 /**
  * Claims the rollback for one operation, or reports that another path
  * already has it.
@@ -338,10 +356,17 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
     const token = nextOperationToken++;
     const operation = { root, kind, cleanups: [] };
     const lockPath = getFurnaceLockPath(root);
+    // An explicit budget wins; otherwise the session-wide one applies. Naming
+    // the lock in the refusal is load-bearing: a mutation takes two, and a
+    // message that says only "timed out" sends the operator to raise a budget
+    // that was already large enough for the OTHER lock.
+    const timeoutMs = options.lockTimeoutMs ?? sessionWaitLockMs();
     const lockOptions = {
-        ...(options.lockTimeoutMs !== undefined ? { timeoutMs: options.lockTimeoutMs } : {}),
-        onTimeoutMessage: `Timed out waiting for the furnace lock at ${lockPath}. ` +
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        onTimeoutMessage: `Timed out waiting for the FURNACE lock at ${lockPath} ` +
+            `(this is the second of the two locks a furnace mutation takes; the first is the engine session lock). ` +
             'Another fireforge furnace command may be running. ' +
+            'Raise the budget with --wait-lock <seconds> or FIREFORGE_WAIT_LOCK, which governs both. ' +
             'If no other process is running, remove the stale lock directory and retry.',
         onStaleLockMessage: (ageMs) => `Removing stale furnace lock (age: ${Math.round(ageMs / 1000)}s). ` +
             'A previous fireforge process may have crashed.',

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -47,6 +47,23 @@
  * @returns True when the recognized teardown traceback is present
  */
 export declare function hasKnownTeardownNoise(output: string): boolean;
+/**
+ * True when a SINGLE line is the documented teardown family's
+ * `AttributeError`.
+ *
+ * The line-level half of {@link hasKnownTeardownNoise}: the traceback FRAME
+ * lives on a neighbouring line, so a per-line test cannot apply the
+ * two-signal rule by itself. Callers pair this with
+ * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition —
+ * "this capture carries the incident, and THIS line is its header" — which
+ * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
+ * the same work it does everywhere else. A novel attribute is not this
+ * incident and must stay a candidate failure.
+ *
+ * @param line - A single output line
+ * @returns True when the line is the recognized teardown AttributeError
+ */
+export declare function isKnownTeardownNoiseLine(line: string): boolean;
 /**
  * Shared across the stdout and stderr filter instances of ONE mach run:
  * SUITE_END typically arrives on stdout while the teardown traceback lands

package/dist/src/core/mach-known-noise-filter.js

@@ -70,6 +70,25 @@ function isRecognizedTeardownNoise(block) {
 export function hasKnownTeardownNoise(output) {
     return isRecognizedTeardownNoise(output);
 }
+/**
+ * True when a SINGLE line is the documented teardown family's
+ * `AttributeError`.
+ *
+ * The line-level half of {@link hasKnownTeardownNoise}: the traceback FRAME
+ * lives on a neighbouring line, so a per-line test cannot apply the
+ * two-signal rule by itself. Callers pair this with
+ * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition —
+ * "this capture carries the incident, and THIS line is its header" — which
+ * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
+ * the same work it does everywhere else. A novel attribute is not this
+ * incident and must stay a candidate failure.
+ *
+ * @param line - A single output line
+ * @returns True when the line is the recognized teardown AttributeError
+ */
+export function isKnownTeardownNoiseLine(line) {
+    return KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(line);
+}
 /** Fresh per-run context — hand the same instance to both stream filters. */
 export function createTeardownNoiseContext() {
     return { shutdownSeen: false };

package/dist/src/core/mach.d.ts

@@ -25,6 +25,11 @@ export interface MachOptions {
      * the test dispatchers only.
      */
     annotateKnownTeardownNoise?: boolean;
+    /**
+     * Environment variables to unset for this dispatch. Threaded to the exec
+     * layer's {@link ExecOptions.envUnset}.
+     */
+    envUnset?: readonly string[];
 }
 /**
  * Result of running a mach command while capturing streamed output.
@@ -243,7 +248,7 @@ export declare function test(engineDir: string, testPaths?: string[], args?: str
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
 /**
  * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
  * capturing output. Unlike the generic `mach test`, the suite-specific
@@ -254,10 +259,10 @@ export declare function testWithOutput(engineDir: string, testPaths?: string[],
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.
  */
-export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;
 /**
  * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
  * capturing output. The suite-specific counterpart to {@link testWithOutput}
  * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
  */
-export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>, fullOutput?: boolean): Promise<MachCommandResult>;