@hominis/fireforge 0.44.1 → 0.44.3

package/dist/src/core/mach.js

@@ -10,6 +10,7 @@ import { explainMachError } from './mach-error-hints.js';
 import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, } from './mach-known-noise-filter.js';
 import { getPython } from './mach-python.js';
 import { installMachResourceGuard } from './mach-resource-shim.js';
+import { teeToRunLog, writeToActiveRunLog } from './run-log.js';
 import { detectHarnessCrashSignature } from './test-harness-crash.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
 // This block is a frozen compatibility list, not a barrel to grow: every name
@@ -90,6 +91,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const exitCode = await execStream(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
+        ...(options.envUnset ? { envUnset: options.envUnset } : {}),
         // Every capture dispatch (test suites, protected builds, package,
         // storybook) runs as a process-group leader and is group-reaped on
         // exit/abort — see ExecOptions.processGroup.
@@ -99,6 +101,12 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stdout.length > CAPTURE_TAIL_LIMIT) {
                 stdout = stdout.slice(-CAPTURE_TAIL_LIMIT);
             }
+            // RAW into the log, filtered into the echo. The log exists to be
+            // re-read after the fact by whoever is diagnosing the run, and the
+            // echo filter's whole purpose is to shorten what a HUMAN scrolls
+            // past — collapsing a traceback in the artifact would reintroduce
+            // the loss this log exists to prevent.
+            writeToActiveRunLog(data);
             process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
         },
         onStderr: (data) => {
@@ -106,6 +114,7 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
             }
+            writeToActiveRunLog(data);
             process.stderr.write(stderrFilter ? stderrFilter.transform(data) : data);
         },
     });
@@ -133,6 +142,10 @@ export async function runMachInheritCapture(args, engineDir, options = {}) {
     return execInheritCapture(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
+        ...(options.envUnset ? { envUnset: options.envUnset } : {}),
+        // This path streams through the collectors' mirror rather than per-chunk
+        // callbacks, so the run-log tee rides the mirror. `mach build` is here.
+        mirror: { stdout: teeToRunLog(process.stdout), stderr: teeToRunLog(process.stderr) },
         processGroup: true,
     });
 }
@@ -378,6 +391,31 @@ export async function watchWithOutput(engineDir, options = {}) {
 export async function test(engineDir, testPaths = [], args = []) {
     return runMach(['test', ...testPaths, ...args], engineDir, { inherit: true });
 }
+/**
+ * Environment markers mozbuild reads to decide it is running under a coding
+ * agent (`mozbuild.util.is_running_under_coding_agent`), which quiets
+ * terminal output to warnings and errors.
+ *
+ * The quieting is genuinely useful for BUILDS — that is most of what an
+ * agent session prints — but it applies to test runs too, where it removes
+ * `TEST_START` and console INFO: exactly the lines a hang or stall
+ * diagnosis needs, and the ones FireForge's own classifier reads
+ * (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`). Unsetting
+ * the variable globally would give up the build half as well, so the
+ * dispatchers below unset it per TEST dispatch and leave the build path
+ * alone.
+ */
+const CODING_AGENT_ENV_MARKERS = ['CLAUDECODE'];
+/**
+ * The `envUnset` list for a test dispatch: the coding-agent markers when
+ * full verbosity was requested, nothing otherwise.
+ *
+ * Opt-in rather than unconditional: this changes how much a third party
+ * prints, and an operator who wants mozbuild's quieting should keep it.
+ */
+function testVerbosityEnvUnset(fullOutput) {
+    return fullOutput === true ? CODING_AGENT_ENV_MARKERS : undefined;
+}
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
  *
@@ -388,10 +426,12 @@ export async function test(engineDir, testPaths = [], args = []) {
  *   (merged over `process.env` by the exec layer). Used by
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
-export async function testWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function testWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['test', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }
@@ -405,10 +445,12 @@ export async function testWithOutput(engineDir, testPaths = [], args = [], env)
  * Signature mirrors {@link testWithOutput} so the two are interchangeable in
  * the dispatch path.
  */
-export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['xpcshell-test', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }
@@ -417,10 +459,12 @@ export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [
  * capturing output. The suite-specific counterpart to {@link testWithOutput}
  * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
  */
-export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env) {
+export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env, fullOutput) {
     const guard = await installMachResourceGuard(engineDir);
+    const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture(['mochitest', ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
+        ...(envUnset ? { envUnset } : {}),
         annotateKnownTeardownNoise: true,
     });
 }

package/dist/src/core/run-log.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-run output logs under `.fireforge/logs/`.
+ *
+ * A run's diagnosis used to exist in exactly one place: the terminal. Piping
+ * through `tail`/`grep` — the ergonomic default when output is long — keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * broke, and it launders the exit code besides. The operator rule ("never
+ * pipe a run") was written down three times downstream and broken after each
+ * writing, which is the tell that it is not an operator problem: the tool is
+ * the only party that can make the log survive the mistake.
+ *
+ * So `test` and `build` write their own complete copy as they stream, and the
+ * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
+ * backgrounded run then still leaves a re-readable artifact.
+ *
+ * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
+ * a run must never fail because one could not be opened, written, or pruned.
+ * Every entry point swallows its errors and degrades to "no log", which is
+ * exactly the behaviour that existed before this module.
+ */
+/** A run log sink. `write` never throws. */
+export interface RunLog {
+    /** Absolute path to the log file. */
+    path: string;
+    /** Appends raw output. Silently drops on any stream error. */
+    write: (chunk: string) => void;
+    /** Flushes and closes. Resolves even when the stream already failed. */
+    close: () => Promise<void>;
+}
+/** `.fireforge/logs` under `projectRoot`. */
+export declare function getRunLogDir(projectRoot: string): string;
+/**
+ * Opens `.fireforge/logs/<command>-<timestamp>.log` for a run, pruning older
+ * logs of the same kind first.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command kind, e.g. `test` or `build`
+ * @param now - Clock injection point for deterministic tests
+ * @returns The sink, or undefined when no log could be opened
+ */
+export declare function openRunLog(projectRoot: string, command: string, now?: Date): Promise<RunLog | undefined>;
+/** Installs (or clears, with `undefined`) the run log for this process. */
+export declare function setActiveRunLog(log: RunLog | undefined): void;
+/** Absolute path of the active run log, or undefined when none is open. */
+export declare function getActiveRunLogPath(): string | undefined;
+/** Appends to the active run log. A no-op when none is open. */
+export declare function writeToActiveRunLog(chunk: string): void;
+/** Closes and clears the active run log. Resolves even when none is open. */
+export declare function closeActiveRunLog(): Promise<void>;
+/**
+ * A writable that forwards to `base` AND to the active run log.
+ *
+ * Used by the stdio-inheriting capture path, whose collectors take a mirror
+ * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * exec layer already supports instead of growing a second hook.
+ *
+ * @param base - The stream to forward to (normally `process.stdout`)
+ * @returns A writable teeing into `base` and the run log
+ */
+export declare function teeToRunLog(base: NodeJS.WritableStream): NodeJS.WritableStream;

package/dist/src/core/run-log.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-run output logs under `.fireforge/logs/`.
+ *
+ * A run's diagnosis used to exist in exactly one place: the terminal. Piping
+ * through `tail`/`grep` — the ergonomic default when output is long — keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * broke, and it launders the exit code besides. The operator rule ("never
+ * pipe a run") was written down three times downstream and broken after each
+ * writing, which is the tell that it is not an operator problem: the tool is
+ * the only party that can make the log survive the mistake.
+ *
+ * So `test` and `build` write their own complete copy as they stream, and the
+ * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
+ * backgrounded run then still leaves a re-readable artifact.
+ *
+ * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
+ * a run must never fail because one could not be opened, written, or pruned.
+ * Every entry point swallows its errors and degrades to "no log", which is
+ * exactly the behaviour that existed before this module.
+ */
+import { createWriteStream } from 'node:fs';
+import { mkdir, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Writable } from 'node:stream';
+import { verbose } from '../utils/logger.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+/** Directory under `.fireforge/` holding run logs. */
+const LOGS_DIRNAME = 'logs';
+/**
+ * How many logs to keep per command kind. Retention is per-kind so a busy
+ * `test` loop cannot evict every `build` log, which is the pair an operator
+ * most often needs to read together.
+ */
+const RETAINED_LOGS_PER_COMMAND = 20;
+/** `.fireforge/logs` under `projectRoot`. */
+export function getRunLogDir(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, LOGS_DIRNAME);
+}
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what the pruning below relies on.
+ */
+function logTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * Makes room for one new log by deleting the oldest, so that at most
+ * {@link RETAINED_LOGS_PER_COMMAND} logs for `command` exist once the new
+ * one is created. Pruning runs BEFORE the file is opened — hence the
+ * `- 1`, without which the directory settles at N + 1.
+ *
+ * Best-effort: a failure here must not stop the run that is about to be
+ * logged.
+ */
+async function pruneRunLogs(dir, command) {
+    const keep = RETAINED_LOGS_PER_COMMAND - 1;
+    try {
+        const entries = await readdir(dir);
+        const mine = entries.filter((name) => name.startsWith(`${command}-`) && name.endsWith('.log'));
+        if (mine.length <= keep)
+            return;
+        // Names embed a lexically-sortable timestamp, so sorting is ordering by
+        // age without stat-ing every file.
+        const stale = mine.sort().slice(0, mine.length - keep);
+        await Promise.all(stale.map(async (name) => {
+            try {
+                await unlink(join(dir, name));
+            }
+            catch {
+                // A concurrent run may have pruned it already.
+            }
+        }));
+    }
+    catch (error) {
+        verbose(`Run-log pruning skipped: ${String(error)}`);
+    }
+}
+/**
+ * Opens `.fireforge/logs/<command>-<timestamp>.log` for a run, pruning older
+ * logs of the same kind first.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command kind, e.g. `test` or `build`
+ * @param now - Clock injection point for deterministic tests
+ * @returns The sink, or undefined when no log could be opened
+ */
+export async function openRunLog(projectRoot, command, now = new Date()) {
+    const dir = getRunLogDir(projectRoot);
+    let stream;
+    const path = join(dir, `${command}-${logTimestamp(now)}.log`);
+    try {
+        await mkdir(dir, { recursive: true });
+        await pruneRunLogs(dir, command);
+        stream = createWriteStream(path, { flags: 'a' });
+    }
+    catch (error) {
+        verbose(`Run log unavailable (${path}): ${String(error)}`);
+        return undefined;
+    }
+    // A stream error after open (disk full, a removed directory) must not
+    // become an unhandled 'error' event and kill the run the log exists to
+    // describe. Latch it and drop every later write.
+    let broken = false;
+    stream.on('error', (error) => {
+        broken = true;
+        verbose(`Run log write failed (${path}): ${error.message}`);
+    });
+    return {
+        path,
+        write: (chunk) => {
+            if (broken)
+                return;
+            try {
+                stream.write(chunk);
+            }
+            catch {
+                broken = true;
+            }
+        },
+        close: async () => {
+            await new Promise((resolve) => {
+                stream.end(() => {
+                    resolve();
+                });
+            });
+        },
+    };
+}
+/**
+ * The run log for the command currently executing, if any.
+ *
+ * Module state rather than a threaded parameter, for the same reason
+ * `test-verdict.ts` keeps its emitted-once flag here: the sink has to be
+ * reachable from `mach.ts`'s stream callbacks, which sit five frames below
+ * the command that opened it, behind dispatch signatures that exist to
+ * describe TESTS rather than logging. Threading it would have touched every
+ * dispatcher, the retry wrapper and the shard loop to deliver one pointer.
+ *
+ * One command runs per process, so a single slot is the whole lifetime.
+ */
+let activeRunLog;
+/** Installs (or clears, with `undefined`) the run log for this process. */
+export function setActiveRunLog(log) {
+    activeRunLog = log;
+}
+/** Absolute path of the active run log, or undefined when none is open. */
+export function getActiveRunLogPath() {
+    return activeRunLog?.path;
+}
+/** Appends to the active run log. A no-op when none is open. */
+export function writeToActiveRunLog(chunk) {
+    activeRunLog?.write(chunk);
+}
+/** Closes and clears the active run log. Resolves even when none is open. */
+export async function closeActiveRunLog() {
+    const log = activeRunLog;
+    activeRunLog = undefined;
+    await log?.close();
+}
+/**
+ * A writable that forwards to `base` AND to the active run log.
+ *
+ * Used by the stdio-inheriting capture path, whose collectors take a mirror
+ * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * exec layer already supports instead of growing a second hook.
+ *
+ * @param base - The stream to forward to (normally `process.stdout`)
+ * @returns A writable teeing into `base` and the run log
+ */
+export function teeToRunLog(base) {
+    return new Writable({
+        write(chunk, _encoding, callback) {
+            const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            base.write(text);
+            writeToActiveRunLog(text);
+            callback();
+        },
+    });
+}

package/dist/src/core/test-harness-output.d.ts

@@ -8,7 +8,30 @@ export interface PostRebuildFailureContext {
     requestedPaths: readonly string[];
     firstFailureLine?: string;
 }
-/** Finds the first high-signal failure line from captured mach test output. */
+/**
+ * Finds the first high-signal failure line from captured mach test output.
+ *
+ * Selection is FIRST-MATCHING-LINE, not first-matching-pattern, so the bare
+ * `AttributeError:` arm above has exactly the same standing as
+ * `TEST-UNEXPECTED-FAIL` — whichever appears earlier in the text wins. That
+ * is how a run whose real defect was an export shard's file-count assertion
+ * got diagnosed as the recognized mozsystemmonitor teardown crash: the
+ * information was present and the SELECTION was wrong, which is the
+ * expensive kind of wrong, because the named cause is a real, documented,
+ * unrelated upstream defect and therefore reads as an answer.
+ *
+ * So a capture carrying the recognized teardown incident gets two passes:
+ * candidates excluding its `AttributeError` header first, and only if that
+ * finds nothing does the full set apply. The narrowness the rest of the
+ * codebase maintains is preserved exactly — the exclusion is gated on
+ * `hasKnownTeardownNoise` for the WHOLE capture, so it requires both the
+ * closed attribute allowlist and a `resourcemonitor.py` frame. A novel
+ * attribute, or a traceback from anywhere else, stays a real failure and is
+ * still eligible to be reported.
+ *
+ * @param output - Raw captured stdout/stderr from the run
+ * @returns The chosen failure line, or the first non-empty line
+ */
 export declare function findFirstUsefulFailureLine(output: string): string | undefined;
 /** Starts a post-rebuild context block for a focused test failure. */
 export declare function createPostRebuildFailureContext(rebuildCommand: string, requestedPaths: readonly string[]): PostRebuildFailureContext;

package/dist/src/core/test-harness-output.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { hasKnownTeardownNoise, isKnownTeardownNoiseLine } from './mach-known-noise-filter.js';
 function getNonEmptyOutputLines(output) {
     return output
         .split(/\r?\n/)
@@ -8,23 +9,53 @@ function getNonEmptyOutputLines(output) {
 function findFirstMatchingLine(lines, patterns) {
     return lines.find((line) => patterns.some((pattern) => pattern.test(line)));
 }
-/** Finds the first high-signal failure line from captured mach test output. */
+const FAILURE_LINE_PATTERNS = [
+    /\bTEST-UNEXPECTED-[A-Z-]+\b/,
+    /\bPROCESS-CRASH\b/i,
+    /\bTIMEOUT\b/i,
+    /timed out/i,
+    /HominisBrowserUnavailableError/i,
+    /Marionette.*(?:session|startup|start).*fail/i,
+    /(?:failed|unable) to (?:start|create|open).*Marionette/i,
+    /SessionNotCreatedException/i,
+    /Browser process exited during spawn/i,
+    /Failed to load (?:resource|chrome):\/\//i,
+    /\b(?:Error|Exception|TypeError|ReferenceError|SyntaxError):\s+/,
+    /AttributeError:\s+/,
+];
+/**
+ * Finds the first high-signal failure line from captured mach test output.
+ *
+ * Selection is FIRST-MATCHING-LINE, not first-matching-pattern, so the bare
+ * `AttributeError:` arm above has exactly the same standing as
+ * `TEST-UNEXPECTED-FAIL` — whichever appears earlier in the text wins. That
+ * is how a run whose real defect was an export shard's file-count assertion
+ * got diagnosed as the recognized mozsystemmonitor teardown crash: the
+ * information was present and the SELECTION was wrong, which is the
+ * expensive kind of wrong, because the named cause is a real, documented,
+ * unrelated upstream defect and therefore reads as an answer.
+ *
+ * So a capture carrying the recognized teardown incident gets two passes:
+ * candidates excluding its `AttributeError` header first, and only if that
+ * finds nothing does the full set apply. The narrowness the rest of the
+ * codebase maintains is preserved exactly — the exclusion is gated on
+ * `hasKnownTeardownNoise` for the WHOLE capture, so it requires both the
+ * closed attribute allowlist and a `resourcemonitor.py` frame. A novel
+ * attribute, or a traceback from anywhere else, stays a real failure and is
+ * still eligible to be reported.
+ *
+ * @param output - Raw captured stdout/stderr from the run
+ * @returns The chosen failure line, or the first non-empty line
+ */
 export function findFirstUsefulFailureLine(output) {
     const lines = getNonEmptyOutputLines(output);
-    const matched = findFirstMatchingLine(lines, [
-        /\bTEST-UNEXPECTED-[A-Z-]+\b/,
-        /\bPROCESS-CRASH\b/i,
-        /\bTIMEOUT\b/i,
-        /timed out/i,
-        /HominisBrowserUnavailableError/i,
-        /Marionette.*(?:session|startup|start).*fail/i,
-        /(?:failed|unable) to (?:start|create|open).*Marionette/i,
-        /SessionNotCreatedException/i,
-        /Browser process exited during spawn/i,
-        /Failed to load (?:resource|chrome):\/\//i,
-        /\b(?:Error|Exception|TypeError|ReferenceError|SyntaxError):\s+/,
-        /AttributeError:\s+/,
-    ]);
+    if (hasKnownTeardownNoise(output)) {
+        const withoutNoise = lines.filter((line) => !isKnownTeardownNoiseLine(line));
+        const preferred = findFirstMatchingLine(withoutNoise, FAILURE_LINE_PATTERNS);
+        if (preferred !== undefined)
+            return preferred;
+    }
+    const matched = findFirstMatchingLine(lines, FAILURE_LINE_PATTERNS);
     return matched ?? lines[0];
 }
 /** Starts a post-rebuild context block for a focused test failure. */

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -4,11 +4,11 @@ export interface XpcshellRetryClassification {
     nonXpcshell: readonly string[];
 }
 /** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
-export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>) => Promise<MachCommandResult>;
+export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>, fullOutput?: boolean) => Promise<MachCommandResult>;
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
  * once. The retry uses the same `dispatch` (suite-specific or generic) the
  * caller is already running on, so an xpcshell-suite run repairs and re-runs
  * via `mach xpcshell-test` rather than falling back to the generic command.
  */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch, fullOutput?: boolean): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -7,12 +7,17 @@ import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
  * caller is already running on, so an xpcshell-suite run repairs and re-runs
  * via `mach xpcshell-test` rather than falling back to the generic command.
  */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput) {
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput, fullOutput) {
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
         const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
         if (repaired) {
+            // The repaired re-run is the same logical invocation, so it keeps
+            // the verbosity the run was started with.
+            if (fullOutput === true) {
+                return dispatch(engineDir, normalizedPaths, extraArgs, env, true);
+            }
             return env
                 ? dispatch(engineDir, normalizedPaths, extraArgs, env)
                 : dispatch(engineDir, normalizedPaths, extraArgs);

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

@@ -19,8 +19,13 @@ export interface AddTokenOptions {
     tokenName: string;
     /** CSS value (e.g., "1px", "var(--space-small)", "light-dark(#fff, #000)") */
     value: string;
-    /** Token category matching section headers in the CSS file */
-    category: string;
+    /**
+     * Token category matching section headers in the CSS file. Required for a
+     * base declaration; ignored — and no longer required — under
+     * {@link AddTokenOptions.variant}, which routes into a `:root<selector>`
+     * block and never touches a category section.
+     */
+    category?: string | undefined;
     /** Dark mode behavior */
     mode: TokenMode;
     /** Comment description for the CSS file */