@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -32,29 +32,29 @@ const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_
 const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
 /**
  * Splits a run of consecutive attribute fragments into its groups, or
- * returns `null` when the run is not exactly that — a group that does not
+ * returns `undefined` when the run is not exactly that — a group that does not
  * open with `[`, an unclosed group, an empty run, or a group whose name or
  * value is not identifier-safe.
  *
  * @param run - The `[…][…]` text with no `:root` prefix
- * @returns The individual fragments, or null when the run is not valid
+ * @returns The individual fragments, or undefined when the run is not valid
  */
 function splitAttributeGroups(run) {
     const groups = [];
     let cursor = 0;
     while (cursor < run.length) {
         if (run[cursor] !== '[')
-            return null;
+            return undefined;
         const close = run.indexOf(']', cursor);
         if (close === -1)
-            return null;
+            return undefined;
         const group = run.slice(cursor, close + 1);
         if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
-            return null;
+            return undefined;
         groups.push(group);
         cursor = close + 1;
     }
-    return groups.length > 0 ? groups : null;
+    return groups.length > 0 ? groups : undefined;
 }
 /** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
 function normalizeAttributeFragment(group) {
@@ -96,10 +96,10 @@ export function validateVariantSelector(raw) {
     // The parse must have consumed the WHOLE fragment: anything it declined to
     // read (a stray space, a trailing combinator) is text the matcher would
     // not see either, so accepting it would author a block nothing can find.
-    if (parts === null || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
+    if (parts === undefined || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
         return reject;
     const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
-    if (groups === null)
+    if (groups === undefined)
         return reject;
     let qualifier = '';
     if (parts.qualifier !== '') {
@@ -112,7 +112,7 @@ export function validateVariantSelector(raw) {
         }
         else {
             const innerGroups = splitAttributeGroups(inner);
-            if (innerGroups === null)
+            if (innerGroups === undefined)
                 return reject;
             const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
             qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
@@ -131,7 +131,7 @@ function canonicalSelector(selector) {
 }
 /**
  * Splits the `:root[…]` selector on `line` into its attribute run and any
- * trailing qualifier, or `null` when the line carries none.
+ * trailing qualifier, or `undefined` when the line carries none.
  *
  * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
  * so that pattern backtracks quadratically on a line repeating `:root[`
@@ -155,7 +155,7 @@ function canonicalSelector(selector) {
 function rootAttributeSelector(line) {
     const start = line.indexOf(':root[');
     if (start === -1)
-        return null;
+        return undefined;
     const brace = line.indexOf('{', start);
     const limit = brace === -1 ? line.length : brace;
     let cursor = start + ':root'.length;
@@ -168,13 +168,13 @@ function rootAttributeSelector(line) {
         end = cursor;
     }
     if (end === start + ':root'.length)
-        return null;
+        return undefined;
     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
- * closing-brace line indices, or `null` when no such block exists.
+ * closing-brace line indices, or `undefined` when no such block exists.
  *
  * Scans a comment-stripped mirror of `lines` so braces inside comments do
  * not offset the depth counter; the returned indices line up with the
@@ -189,10 +189,9 @@ function findVariantBlock(lines, variant) {
     const requested = rootAttributeSelector(`:root${variant} {`);
     const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
     const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
-    for (let i = 0; i < stripped.length; i++) {
-        const line = stripped[i] ?? '';
+    for (const [i, line] of stripped.entries()) {
         const selector = rootAttributeSelector(line);
-        if (selector === null || canonicalSelector(selector.attributes) !== want)
+        if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
         // An UNqualified request still matches a qualified block: that is the
         // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
@@ -219,7 +218,7 @@ function findVariantBlock(lines, variant) {
             continue;
         return { open: openLine, close, qualifier: selector.qualifier };
     }
-    return null;
+    return undefined;
 }
 /**
  * Returns the line index at which a brand-new `:root<variant>` block should
@@ -229,8 +228,8 @@ function findVariantBlock(lines, variant) {
  */
 function findVariantBlockInsertionPoint(lines) {
     const stripped = stripBlockCommentsInLines(lines);
-    for (let i = 0; i < stripped.length; i++) {
-        if (/^\s*:root\s*\{/.test(stripped[i] ?? '')) {
+    for (const [i, line] of stripped.entries()) {
+        if (/^\s*:root\s*\{/.test(line)) {
             const close = findBlockCloseIndex(stripped, i);
             if (close !== -1)
                 return close + 1;
@@ -245,7 +244,7 @@ function findVariantBlockInsertionPoint(lines) {
  * the block, which is only wanted for the explicit `--variant` flow.
  */
 export function variantBlockExists(lines, variant) {
-    return findVariantBlock(lines, variant) !== null;
+    return findVariantBlock(lines, variant) !== undefined;
 }
 /**
  * The pseudo-class qualifier on the matched `:root<variant>` block, or
@@ -300,8 +299,8 @@ export function findVariantBlockDeclaration(lines, variant, tokenName) {
         .join('\n')
         .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
         .split('\n');
-    for (let i = 0; i < stripped.length; i++) {
-        if ((stripped[i] ?? '').includes(`${tokenName}:`))
+    for (const [i, line] of stripped.entries()) {
+        if (line.includes(`${tokenName}:`))
             return { line: block.open + i + 1 };
     }
     return undefined;

package/dist/src/core/toolchain-preflight.js

@@ -121,7 +121,7 @@ export function formatMajorVersionHopNotice(previousVersion, newVersion) {
         return undefined;
     if (previousMajor === newMajor)
         return undefined;
-    return (`Firefox major version changed (${String(previousMajor)} → ${String(newMajor)}): ` +
+    return (`Firefox major version changed (${previousMajor} → ${newMajor}): ` +
         'upstream toolchain minimums (cbindgen, Rust, …) may have moved with it. ' +
         'Consider running "fireforge bootstrap" before the next build.');
 }

package/dist/src/core/tree-cow.d.ts

@@ -2,8 +2,6 @@
 export type CloneExecutor = (command: string, args: string[]) => Promise<void>;
 /** How this host can materialise a tree. */
 export type CowCapability = 'clonefile' | 'reflink' | 'none';
-/** Per-platform `cp` argv prefix for a CoW copy of one entry. */
-export declare function cowCopyArgs(capability: Exclude<CowCapability, 'none'>): string[];
 /**
  * Probes CoW support in `dir` by cloning a tiny probe file there.
  * Non-darwin/linux platforms report 'none' without probing.

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

@@ -20,11 +20,11 @@ import { exec } from '../utils/process.js';
 const defaultExecutor = async (command, args) => {
     const result = await exec(command, args);
     if (result.exitCode !== 0) {
-        throw new Error(`${command} ${args.join(' ')} failed (exit ${String(result.exitCode)}): ${result.stderr}`);
+        throw new Error(`${command} ${args.join(' ')} failed (exit ${result.exitCode}): ${result.stderr}`);
     }
 };
 /** Per-platform `cp` argv prefix for a CoW copy of one entry. */
-export function cowCopyArgs(capability) {
+function cowCopyArgs(capability) {
     return capability === 'clonefile' ? ['-c', '-R', '-p'] : ['--reflink=always', '-a'];
 }
 /**

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

@@ -19,6 +19,7 @@ import { GeneralError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose, warn } from '../utils/logger.js';
 import { isObject } from '../utils/validation.js';
 import { getBuildBaselinePath } from './build-baseline.js';
@@ -128,7 +129,7 @@ export async function readTreeMarker(root) {
         const code = getNodeErrorCode(error);
         if (code === 'ENOENT' || code === 'ENOTDIR')
             return { kind: 'absent' };
-        verbose(`Unreadable tree marker at ${markerPath}: ${String(error)}`);
+        verbose(`Unreadable tree marker at ${markerPath}: ${toError(error).message}`);
         return { kind: 'corrupt', reason: `the marker could not be read (${toError(error).message})` };
     }
 }
@@ -178,9 +179,7 @@ export async function computePrimaryFingerprint(primaryRoot) {
     }
     let engineFingerprint;
     try {
-        engineFingerprint = createHash('sha256')
-            .update(await getAllDiff(engineDir))
-            .digest('hex');
+        engineFingerprint = sha256Hex(await getAllDiff(engineDir));
     }
     catch {
         engineFingerprint = null;
@@ -461,7 +460,7 @@ export async function removeTree(primaryRoot, name, options = {}) {
     ]) {
         const state = await inspectTreeLock(lockPath);
         if (state.kind === 'held') {
-            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${String(state.pid)}) holds ${lockPath}. ` +
+            throw new GeneralError(`Refusing to remove tree "${name}": a live process (pid ${state.pid}) holds ${lockPath}. ` +
                 'Wait for it to finish, then retry.');
         }
         if (state.kind === 'unknown' && options.force !== true) {

package/dist/src/core/typecheck.js

@@ -144,7 +144,7 @@ export async function runTypecheck(projectRoot, cfg) {
  */
 function resolveProjectExtraShim(cfg, projectPath) {
     const overrides = cfg.projectOverrides;
-    if (overrides && Object.prototype.hasOwnProperty.call(overrides, projectPath)) {
+    if (overrides && Object.hasOwn(overrides, projectPath)) {
         const value = overrides[projectPath];
         return value === null ? undefined : value;
     }
@@ -298,7 +298,7 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         }
         issues.push(diagnosticToIssue(ts, diag, absConfig, projectPath));
     }
-    verbose(`typecheck: ${projectPath} — analyzed ${String(parsed.fileNames.length)} file(s), found ${String(issues.length)} issue(s)`);
+    verbose(`typecheck: ${projectPath} — analyzed ${parsed.fileNames.length} file(s), found ${issues.length} issue(s)`);
     return {
         project: projectPath,
         issues,

package/dist/src/core/wire-dom-fragment.js

@@ -12,6 +12,7 @@ import { dirname, join, relative } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { toRootRelativePath } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { tokenizeXhtml } from './wire-utils.js';
 export const DEFAULT_DOM_TARGET = 'browser/base/content/browser.xhtml';
@@ -22,23 +23,11 @@ export function addDomFragmentTokenized(content, includeDirective) {
     const lines = content.split('\n');
     const tokens = tokenizeXhtml(lines);
     // Find the #include browser-sets.inc token
-    let insertIndex = -1;
-    for (let i = 0; i < tokens.length; i++) {
-        const token = tokens[i];
-        if (token && token.type === 'macro' && token.raw.includes('browser-sets.inc')) {
-            insertIndex = i;
-            break;
-        }
-    }
+    let insertIndex = tokens.findIndex((token) => token.type === 'macro' && token.raw.includes('browser-sets.inc'));
     if (insertIndex === -1) {
         // Fallback: after <html:body>
-        for (let i = 0; i < tokens.length; i++) {
-            const token = tokens[i];
-            if (token && token.type === 'xml' && /<html:body/.test(token.raw)) {
-                insertIndex = i + 1;
-                break;
-            }
-        }
+        const bodyIndex = tokens.findIndex((token) => token.type === 'xml' && /<html:body/.test(token.raw));
+        insertIndex = bodyIndex === -1 ? -1 : bodyIndex + 1;
     }
     if (insertIndex === -1) {
         throw new GeneralError('Could not find insertion point in chrome document');
@@ -69,7 +58,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
     }
     const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     const content = await readText(targetAbsPath);
     if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
@@ -109,7 +98,7 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
     // contains it, so this must track the chrome doc's location, not a
     // hardcoded `browser/base/content/`.
     const targetDir = dirname(targetPath);
-    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
+    const includePath = normalizePathSlashes(relative(targetDir, safeDomFilePath));
     const includeDirective = `#include ${includePath}`;
     let content = await readText(targetAbsPath);
     // Idempotency: check if the #include directive already exists (line-anchored to avoid substring matches)

package/dist/src/core/wire-utils.js

@@ -160,7 +160,7 @@ export function tokenizeXhtml(lines) {
 }
 // ---------------------------------------------------------------------------
 // Legacy (line-based) helpers — shared by fallback implementations in
-// wire-targets.ts.  Extracted to reduce duplication and make the brace-
+// the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
 /**
@@ -179,24 +179,12 @@ export function tokenizeXhtml(lines) {
  *   found (or, under `requireBrace`, no brace follows the signature).
  */
 export function findMethodBraceIndex(lines, pattern, options) {
-    let methodLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (pattern.test(lines[i] ?? '')) {
-            methodLine = i;
-            break;
-        }
-    }
+    const methodLine = lines.findIndex((line) => pattern.test(line));
     if (methodLine === -1)
         return null;
-    let braceIndex = methodLine;
-    let braceFound = false;
-    for (let i = methodLine; i < lines.length; i++) {
-        if (lines[i]?.includes('{')) {
-            braceIndex = i;
-            braceFound = true;
-            break;
-        }
-    }
+    const braceOffset = lines.slice(methodLine).findIndex((line) => line.includes('{'));
+    const braceFound = braceOffset !== -1;
+    const braceIndex = braceFound ? methodLine + braceOffset : methodLine;
     if (!braceFound && options?.requireBrace) {
         return null;
     }

package/dist/src/core/xpcshell-appdir.js

@@ -64,8 +64,7 @@ export function parseAppdirFromToml(tomlText, key) {
     // comment further along the file is not mistaken for the directive.
     const escapedKey = escapeRegex(key);
     const keyPattern = new RegExp('^\\s*' + escapedKey + '\\s*=\\s*(.+?)\\s*(?:[#;].*)?$');
-    for (let i = 0; i < lines.length; i += 1) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         const sectionMatch = /^\s*\[([^\]]+)\]\s*$/.exec(line);
         if (sectionMatch) {
             sectionSeen = true;
@@ -290,8 +289,7 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
  * wins.
  */
 export function operatorAlreadySetAppPath(extraArgs) {
-    for (let i = 0; i < extraArgs.length; i += 1) {
-        const arg = extraArgs[i] ?? '';
+    for (const [i, arg] of extraArgs.entries()) {
         if (arg === '--app-path' && i + 1 < extraArgs.length)
             return true;
         if (arg.startsWith('--app-path='))

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

@@ -19,12 +19,45 @@ export declare abstract class FireForgeError extends Error {
      */
     get userMessage(): string;
 }
+/**
+ * Renders the trailing "To fix this:" block shared by every FireForge error
+ * that offers remedies.
+ *
+ * Numbering is derived from the array rather than written into each string.
+ * Several classes vary their advice by context (`FurnaceError` drops the
+ * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
+ * hand-numbered branches had to renumber every later step by hand — one
+ * conditional away from printing "2." twice.
+ *
+ * @param steps - The remedy lines, in order, without their numbers
+ * @returns The block, starting with the blank-line separator
+ */
+export declare function remedies(steps: readonly string[]): string;
 /**
  * General error for unexpected failures.
  */
 export declare class GeneralError extends FireForgeError {
     readonly code: 1;
 }
+/**
+ * A `fireforge test` preflight gate that refused before any harness ran.
+ *
+ * Exists to carry a `note`, not to change behaviour: it keeps
+ * {@link ExitCode.GENERAL_ERROR}, so `docs/exit-codes.md` and every CI
+ * consumer keying on the exit status are untouched. The note is a stable
+ * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
+ * additive `note=` key. Without it every preflight refusal reached an
+ * unattended reader as the single token `reason=preflight`, which covers
+ * everything from a missing build to a peer's packaging record — so the one
+ * line that survives a truncating pipe could not say WHICH gate fired.
+ */
+export declare class PreflightRefusalError extends GeneralError {
+    /** Stable refusal class, e.g. `stale-browser`. */
+    readonly note: string;
+    constructor(message: string, 
+    /** Stable refusal class, e.g. `stale-browser`. */
+    note: string);
+}
 /**
  * Raised when one of FireForge's own internal invariants did not hold —
  * the failure of a runtime assertion from `src/utils/assert.ts`.
@@ -92,14 +125,33 @@ export declare class ExecTimeoutError extends FireForgeError {
     /** Timeout that elapsed, in milliseconds. */
     readonly timeoutMs: number;
     readonly code: 1;
+    /** Standard output captured before the deadline fired (empty when the exec path does not capture). */
+    readonly stdout: string;
+    /** Standard error captured before the deadline fired (empty when the exec path does not capture). */
+    readonly stderr: string;
+    /** True when either captured stream was cut off at the exec layer's collector cap. */
+    readonly outputTruncated: boolean;
     constructor(
     /** Executable that was spawned (argv[0]). */
     command: string, 
     /** Arguments the executable was spawned with. */
     args: readonly string[], 
     /** Timeout that elapsed, in milliseconds. */
-    timeoutMs: number, cause?: unknown);
+    timeoutMs: number, cause?: unknown, output?: ExecTimeoutOutput);
     get userMessage(): string;
+    /**
+     * The last few lines the command printed before it was killed, so an
+     * operator can see what it was doing (a `git add -A` stuck on one path,
+     * a build step that hung) instead of a bare budget number. Prefers
+     * stderr; falls back to stdout when stderr is silent.
+     */
+    private outputTailForUser;
+}
+/** Output captured before an exec timeout fired; see {@link ExecTimeoutError}. */
+export interface ExecTimeoutOutput {
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
 }
 /**
  * Error thrown when a file-lock wait times out because another process holds

package/dist/src/errors/base.js

@@ -17,10 +17,11 @@ export class FireForgeError extends Error {
         if (cause !== undefined) {
             this.cause = cause;
         }
-        // Maintains proper stack trace in V8 environments
-        if (typeof Error.captureStackTrace === 'function') {
-            Error.captureStackTrace(this, this.constructor);
-        }
+        // Trims the constructor frames off the stack. `engines` pins Node >= 22,
+        // so the V8-only `captureStackTrace` is always present — the former
+        // `typeof === 'function'` guard was an unreachable branch that coverage
+        // could never close.
+        Error.captureStackTrace(this, this.constructor);
     }
     /**
      * User-friendly error message with context and suggested fixes.
@@ -30,12 +31,49 @@ export class FireForgeError extends Error {
         return this.message;
     }
 }
+/**
+ * Renders the trailing "To fix this:" block shared by every FireForge error
+ * that offers remedies.
+ *
+ * Numbering is derived from the array rather than written into each string.
+ * Several classes vary their advice by context (`FurnaceError` drops the
+ * validate step, `ChecksumMismatchError` adds a Developer Edition note), and
+ * hand-numbered branches had to renumber every later step by hand — one
+ * conditional away from printing "2." twice.
+ *
+ * @param steps - The remedy lines, in order, without their numbers
+ * @returns The block, starting with the blank-line separator
+ */
+export function remedies(steps) {
+    return `\n\nTo fix this:\n${steps.map((step, index) => `  ${index + 1}. ${step}`).join('\n')}`;
+}
 /**
  * General error for unexpected failures.
  */
 export class GeneralError extends FireForgeError {
     code = ExitCode.GENERAL_ERROR;
 }
+/**
+ * A `fireforge test` preflight gate that refused before any harness ran.
+ *
+ * Exists to carry a `note`, not to change behaviour: it keeps
+ * {@link ExitCode.GENERAL_ERROR}, so `docs/exit-codes.md` and every CI
+ * consumer keying on the exit status are untouched. The note is a stable
+ * kebab-case refusal class that the `FIREFORGE-VERDICT:` line reports as an
+ * additive `note=` key. Without it every preflight refusal reached an
+ * unattended reader as the single token `reason=preflight`, which covers
+ * everything from a missing build to a peer's packaging record — so the one
+ * line that survives a truncating pipe could not say WHICH gate fired.
+ */
+export class PreflightRefusalError extends GeneralError {
+    note;
+    constructor(message, 
+    /** Stable refusal class, e.g. `stale-browser`. */
+    note) {
+        super(message);
+        this.note = note;
+    }
+}
 /**
  * Raised when one of FireForge's own internal invariants did not hold —
  * the failure of a runtime assertion from `src/utils/assert.ts`.
@@ -102,11 +140,9 @@ export class InvalidArgumentError extends FireForgeError {
         this.argument = argument;
     }
     get userMessage() {
-        let msg = `Invalid Argument: ${this.message}`;
-        if (this.argument) {
-            msg += `\n\nArgument: ${this.argument}`;
-        }
-        return msg;
+        return this.argument
+            ? `Invalid Argument: ${this.message}\n\nArgument: ${this.argument}`
+            : `Invalid Argument: ${this.message}`;
     }
 }
 /**
@@ -123,24 +159,56 @@ export class ExecTimeoutError extends FireForgeError {
     args;
     timeoutMs;
     code = ExitCode.GENERAL_ERROR;
+    /** Standard output captured before the deadline fired (empty when the exec path does not capture). */
+    stdout;
+    /** Standard error captured before the deadline fired (empty when the exec path does not capture). */
+    stderr;
+    /** True when either captured stream was cut off at the exec layer's collector cap. */
+    outputTruncated;
     constructor(
     /** Executable that was spawned (argv[0]). */
     command, 
     /** Arguments the executable was spawned with. */
     args, 
     /** Timeout that elapsed, in milliseconds. */
-    timeoutMs, cause) {
+    timeoutMs, cause, output) {
         super(`Command timed out after ${Math.round(timeoutMs / 1000)}s: ${[command, ...args].join(' ')}`, cause);
         this.command = command;
         this.args = args;
         this.timeoutMs = timeoutMs;
+        this.stdout = output?.stdout ?? '';
+        this.stderr = output?.stderr ?? '';
+        this.outputTruncated = output?.truncated ?? false;
     }
     get userMessage() {
         return (`${this.message}\n\n` +
             'The command was killed because it exceeded its time budget, not because it failed on its own. ' +
-            'If the host is just slow or loaded, re-running may succeed.');
+            'If the host is just slow or loaded, re-running may succeed.' +
+            this.outputTailForUser());
+    }
+    /**
+     * The last few lines the command printed before it was killed, so an
+     * operator can see what it was doing (a `git add -A` stuck on one path,
+     * a build step that hung) instead of a bare budget number. Prefers
+     * stderr; falls back to stdout when stderr is silent.
+     */
+    outputTailForUser() {
+        const source = this.stderr.trim().length > 0 ? this.stderr : this.stdout;
+        const lines = source
+            .trimEnd()
+            .split(/\r?\n/)
+            .filter((line) => line.length > 0);
+        if (lines.length === 0)
+            return '';
+        const tail = lines.slice(-EXEC_TIMEOUT_TAIL_LINES);
+        const label = this.stderr.trim().length > 0 ? 'stderr' : 'stdout';
+        const omitted = lines.length > tail.length ? ` (last ${tail.length} of ${lines.length} lines)` : '';
+        const truncatedNote = this.outputTruncated ? ' [captured output was truncated]' : '';
+        return `\n\nOutput before the timeout (${label}${omitted})${truncatedNote}:\n${tail.map((line) => `  ${line}`).join('\n')}`;
     }
 }
+/** How many trailing output lines {@link ExecTimeoutError.userMessage} shows. */
+const EXEC_TIMEOUT_TAIL_LINES = 20;
 /**
  * Error thrown when a file-lock wait times out because another process holds
  * the lock.

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

@@ -9,6 +9,34 @@ export declare class BuildError extends FireForgeError {
     constructor(message: string, command?: string | undefined, cause?: Error);
     get userMessage(): string;
 }
+/**
+ * A test SUITE went red — assertions failed, or sharded runs did not all
+ * pass. Distinct from its {@link BuildError} parent only in what it TELLS
+ * the operator, deliberately not in its exit code: `docs/exit-codes.md`
+ * documents 5 as "a suite that FAILED", and consumers key CI on it.
+ *
+ * The parent's remedies are all build remedies — "check the build output",
+ * "fireforge bootstrap", "delete obj-* directories" — and none of them apply
+ * to a failing assertion. Worse, the first points at the wrong half of the
+ * log, which is exactly the half a `tail` keeps. Ground truth for a test red
+ * is the harness's own output, so the remedies here name the failing tests,
+ * the `FIREFORGE-VERDICT:` line, and the run log that survives a pipe.
+ *
+ * Note that `machineErrorCode` derives the `--json` error code from the class
+ * name, so this reports as `test-failure` rather than `build`.
+ */
+export declare class TestFailureError extends BuildError {
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    readonly failureBlocks?: string | undefined;
+    /** The run's complete raw log, when one was opened. */
+    readonly logPath?: string | undefined;
+    constructor(message: string, command?: string, 
+    /** Rendered TEST-UNEXPECTED blocks, when the verdict carried any. */
+    failureBlocks?: string | undefined, 
+    /** The run's complete raw log, when one was opened. */
+    logPath?: string | undefined);
+    get userMessage(): string;
+}
 /**
  * Error thrown when mach is not available.
  */