@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -19,6 +19,20 @@ 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.
  */
@@ -26,7 +40,26 @@ export declare class GeneralError extends FireForgeError {
     readonly code: 1;
 }
 /**
- * Raised when one of FireForge's own internal invariants did not hold —
+ * 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`.
  *
  * Dedicated subclass (rather than raw GeneralError) because an invariant
@@ -35,12 +68,12 @@ export declare class GeneralError extends FireForgeError {
  * fix. That difference is worth carrying all the way to the exit status
  * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
  * instead of retrying it, and it is the one error class the CLI boundary
- * prints a stack trace for — the stack is the report.
+ * prints a stack trace for, since the stack is the report.
  *
  * Assertions exist so that a violated invariant stops the run at the
  * first inconsistency instead of continuing to write. In the mutating
  * paths that means the surrounding rollback journal restores the engine
- * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ * before this reaches the operator. See `docs/lifecycle-invariants.md`.
  */
 export declare class InternalInvariantError extends FireForgeError {
     readonly code: 11;
@@ -48,7 +81,7 @@ export declare class InternalInvariantError extends FireForgeError {
 }
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
- * cannot safely perform its mutation — e.g. because a block it expected
+ * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.
  *
@@ -80,9 +113,10 @@ export declare class InvalidArgumentError extends FireForgeError {
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
  * instead of Node's bare `AbortError: The operation was aborted`, which
- * carries no command name, no elapsed time, and no hint that a timeout —
- * not the command — was responsible. See {@link GitIndexingTimeoutError} in
- * errors/git.ts for the git-specific variant.
+ * carries no command name, no elapsed time, and no hint that a timeout
+ * (rather than the command) was responsible. See
+ * {@link GitIndexingTimeoutError} in errors/git.ts for the git-specific
+ * variant.
  */
 export declare class ExecTimeoutError extends FireForgeError {
     /** Executable that was spawned (argv[0]). */
@@ -92,14 +126,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. It prefers
+     * stderr and 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
@@ -108,12 +161,12 @@ export declare class ExecTimeoutError extends FireForgeError {
  * Dedicated subclass so the CLI boundary renders lock contention as the
  * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
  * is treated by `withErrorHandling` as an internal failure and printed with
- * a five-frame stack — a correct refusal that looks like a crash.
+ * a five-frame stack: a correct refusal that looks like a crash.
  *
  * Exit code 15, not 1: the run never started. A script that retries on
  * failure wants to re-queue this one, not treat it as a failure of the work
  * it asked for. Every lock in FireForge shares the class and therefore the
- * code — the fact is the same whichever lock was contended.
+ * code, because the fact is the same whichever lock was contended.
  */
 export declare class LockContentionError extends FireForgeError {
     readonly code: 15;
@@ -125,19 +178,19 @@ export declare class LockContentionError extends FireForgeError {
  *
  * Dedicated subclass for its exit code alone: as a `GeneralError` this
  * refusal exited 1 beside real test failures' 5, and a summary line reading
- * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
- * kind of fact. They are opposites — one suite failed, the other's result
- * was discarded — and only a distinct code makes "unknown, re-run"
+ * `FAIL, exit 1` next to `FAIL, exit 5` invites treating them as the same
+ * kind of fact. They are opposites (one suite failed, the other's result
+ * was discarded) and only a distinct code makes "unknown, re-run"
  * mechanically separable from "red".
  */
 export declare class InconclusiveVerdictError extends FireForgeError {
     readonly code: 14;
 }
 /**
- * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Error thrown when the user interrupts an interactive prompt: Esc or
  * Ctrl+C, i.e. `isCancel(...)`.
  *
- * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * Not for a prompt the operator answered "no" to: 130 is
  * 128+SIGINT, which claims an interrupt. A declined confirmation is a
  * successful run that chose not to proceed, and exits 0.
  */
@@ -156,7 +209,7 @@ export declare class ResolutionError extends FireForgeError {
  * without calling process.exit() from shared library code.
  *
  * The user-visible error message has already been logged by the time this
- * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ * is thrown. The entrypoint only needs to read `.exitCode` and terminate.
  */
 export declare class CommandError extends Error {
     readonly exitCode: ExitCode;

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,6 +31,22 @@ 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.
  */
@@ -37,7 +54,28 @@ export class GeneralError extends FireForgeError {
     code = ExitCode.GENERAL_ERROR;
 }
 /**
- * Raised when one of FireForge's own internal invariants did not hold —
+ * 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`.
  *
  * Dedicated subclass (rather than raw GeneralError) because an invariant
@@ -46,12 +84,12 @@ export class GeneralError extends FireForgeError {
  * fix. That difference is worth carrying all the way to the exit status
  * (see {@link ExitCode.INTERNAL_ERROR}) so a CI job can escalate it
  * instead of retrying it, and it is the one error class the CLI boundary
- * prints a stack trace for — the stack is the report.
+ * prints a stack trace for, since the stack is the report.
  *
  * Assertions exist so that a violated invariant stops the run at the
  * first inconsistency instead of continuing to write. In the mutating
  * paths that means the surrounding rollback journal restores the engine
- * before this reaches the operator; see `docs/lifecycle-invariants.md`.
+ * before this reaches the operator. See `docs/lifecycle-invariants.md`.
  */
 export class InternalInvariantError extends FireForgeError {
     code = ExitCode.INTERNAL_ERROR;
@@ -69,7 +107,7 @@ export class InternalInvariantError extends FireForgeError {
 }
 /**
  * Raised when a legacy regex/brace-depth fallback parser decides it
- * cannot safely perform its mutation — e.g. because a block it expected
+ * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.
  *
@@ -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}`;
     }
 }
 /**
@@ -114,33 +150,66 @@ export class InvalidArgumentError extends FireForgeError {
  *
  * Every `exec*` helper in `src/utils/process.ts` rejects with this type
  * instead of Node's bare `AbortError: The operation was aborted`, which
- * carries no command name, no elapsed time, and no hint that a timeout —
- * not the command — was responsible. See {@link GitIndexingTimeoutError} in
- * errors/git.ts for the git-specific variant.
+ * carries no command name, no elapsed time, and no hint that a timeout
+ * (rather than the command) was responsible. See
+ * {@link GitIndexingTimeoutError} in errors/git.ts for the git-specific
+ * variant.
  */
 export class ExecTimeoutError extends FireForgeError {
     command;
     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. It prefers
+     * stderr and 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.
@@ -148,12 +217,12 @@ export class ExecTimeoutError extends FireForgeError {
  * Dedicated subclass so the CLI boundary renders lock contention as the
  * one-line reason-first/remedy-second refusal it is. As a plain `Error` it
  * is treated by `withErrorHandling` as an internal failure and printed with
- * a five-frame stack — a correct refusal that looks like a crash.
+ * a five-frame stack: a correct refusal that looks like a crash.
  *
  * Exit code 15, not 1: the run never started. A script that retries on
  * failure wants to re-queue this one, not treat it as a failure of the work
  * it asked for. Every lock in FireForge shares the class and therefore the
- * code — the fact is the same whichever lock was contended.
+ * code, because the fact is the same whichever lock was contended.
  */
 export class LockContentionError extends FireForgeError {
     code = ExitCode.LOCK_TIMEOUT;
@@ -165,19 +234,19 @@ export class LockContentionError extends FireForgeError {
  *
  * Dedicated subclass for its exit code alone: as a `GeneralError` this
  * refusal exited 1 beside real test failures' 5, and a summary line reading
- * `FAIL — exit 1` next to `FAIL — exit 5` invites treating them as the same
- * kind of fact. They are opposites — one suite failed, the other's result
- * was discarded — and only a distinct code makes "unknown, re-run"
+ * `FAIL, exit 1` next to `FAIL, exit 5` invites treating them as the same
+ * kind of fact. They are opposites (one suite failed, the other's result
+ * was discarded) and only a distinct code makes "unknown, re-run"
  * mechanically separable from "red".
  */
 export class InconclusiveVerdictError extends FireForgeError {
     code = ExitCode.INCONCLUSIVE;
 }
 /**
- * Error thrown when the user INTERRUPTS an interactive prompt — Esc or
+ * Error thrown when the user interrupts an interactive prompt: Esc or
  * Ctrl+C, i.e. `isCancel(...)`.
  *
- * Not for a prompt the operator deliberately answered "no" to: 130 is
+ * Not for a prompt the operator answered "no" to: 130 is
  * 128+SIGINT, which claims an interrupt. A declined confirmation is a
  * successful run that chose not to proceed, and exits 0.
  */
@@ -198,7 +267,7 @@ export class ResolutionError extends FireForgeError {
  * without calling process.exit() from shared library code.
  *
  * The user-visible error message has already been logged by the time this
- * is thrown — the entrypoint only needs to read `.exitCode` and terminate.
+ * is thrown. The entrypoint only needs to read `.exitCode` and terminate.
  */
 export class CommandError extends Error {
     exitCode;

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

@@ -10,19 +10,19 @@ export declare class BuildError extends FireForgeError {
     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`
+ * 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, and 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
+ * 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
+ * `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 {

package/dist/src/errors/build.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { FireForgeError } from './base.js';
+import { FireForgeError, remedies } from './base.js';
 import { ExitCode } from './codes.js';
 /**
  * Error thrown when a build operation fails.
@@ -12,31 +12,29 @@ export class BuildError extends FireForgeError {
         this.command = command;
     }
     get userMessage() {
-        let msg = `Build Error: ${this.message}`;
-        if (this.command) {
-            msg += `\n\nCommand: ${this.command}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += '  1. Check the build output above for specific errors\n';
-        msg += '  2. Ensure all dependencies are installed with "fireforge bootstrap"\n';
-        msg += '  3. Try a clean build by deleting obj-* directories';
-        return msg;
+        return (`Build Error: ${this.message}` +
+            (this.command ? `\n\nCommand: ${this.command}` : '') +
+            remedies([
+                'Check the build output above for specific errors',
+                'Ensure all dependencies are installed with "fireforge bootstrap"',
+                'Try a clean build by deleting obj-* directories',
+            ]));
     }
 }
 /**
- * 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`
+ * 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, and 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
+ * 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
+ * `machineErrorCode` derives the `--json` error code from the class
  * name, so this reports as `test-failure` rather than `build`.
  */
 export class TestFailureError extends BuildError {
@@ -52,24 +50,18 @@ export class TestFailureError extends BuildError {
         this.logPath = logPath;
     }
     get userMessage() {
-        let msg = `Test Failure: ${this.message}`;
-        if (this.command) {
-            msg += `\n\nCommand: ${this.command}`;
-        }
-        if (this.failureBlocks) {
-            msg += `\n\n${this.failureBlocks}`;
-        }
-        msg += '\n\nTo fix this:\n';
-        msg += this.failureBlocks
-            ? '  1. Fix the failing assertions listed above, then re-run just those test paths\n'
-            : '  1. Find the TEST-UNEXPECTED-FAIL lines in the output above — they name what broke\n';
-        msg +=
-            '  2. Read the "FIREFORGE-VERDICT:" line for the run\'s ground truth (checks, unexpected)\n';
-        msg +=
-            this.logPath !== undefined
-                ? `  3. The complete raw output is at ${this.logPath} — it survives a piped/tailed terminal`
-                : '  3. Re-run without piping the output, so the failure lines are not cut off by "tail"';
-        return msg;
+        return (`Test Failure: ${this.message}` +
+            (this.command ? `\n\nCommand: ${this.command}` : '') +
+            (this.failureBlocks ? `\n\n${this.failureBlocks}` : '') +
+            remedies([
+                this.failureBlocks
+                    ? 'Fix the failing assertions listed above, then re-run just those test paths'
+                    : 'Find the TEST-UNEXPECTED-FAIL lines in the output above — they name what broke',
+                'Read the "FIREFORGE-VERDICT:" line for the run\'s ground truth (checks, unexpected)',
+                this.logPath !== undefined
+                    ? `The complete raw output is at ${this.logPath} — it survives a piped/tailed terminal`
+                    : 'Re-run without piping the output, so the failure lines are not cut off by "tail"',
+            ]));
     }
 }
 /**

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

@@ -26,7 +26,7 @@ export declare const ExitCode: {
     /** Patch conflict resolution error */
     readonly RESOLUTION_ERROR: 10;
     /**
-     * An internal invariant did not hold — a bug in FireForge itself, not a
+     * An internal invariant did not hold: a bug in FireForge itself, not a
      * user or environment failure. Distinct from GENERAL_ERROR because the
      * two call for opposite responses: a GENERAL_ERROR usually means the
      * operator must change something (fix a config, free a lock, retry), and
@@ -43,30 +43,30 @@ export declare const ExitCode: {
     readonly SMOKE_EXIT_FAILURE: 12;
     /**
      * `fireforge run --smoke-exit` saw the browser exit with a non-clean
-     * status before the smoke window elapsed — a launch-side failure that
-     * did NOT surface as a console error line (crash before console wiring,
-     * missing profile, etc.).
+     * status before the smoke window elapsed. This is a launch-side failure
+     * that did not surface as a console error line (crash before console
+     * wiring, missing profile, etc.).
      */
     readonly SMOKE_LAUNCH_FAILURE: 13;
     /**
-     * A `fireforge test` run produced a harness result that cannot be trusted
-     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
-     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
-     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * A `fireforge test` run produced a harness result that cannot be
+     * trusted: `engine/` moved (or became unprobeable) while the tests ran.
+     * Distinct from BUILD_ERROR because the two are opposites: a 5 is a suite
+     * that failed, a 14 is a suite whose result was thrown away. A consumer should
      * re-run a 14 (after settling the writers) and must not report it as red.
      */
     readonly INCONCLUSIVE: 14;
     /**
      * A lock wait expired: the run never started, because another FireForge
      * process held the lock for the whole budget. Distinct from GENERAL_ERROR
-     * because nothing about the request was wrong — a consumer should re-queue
+     * because nothing about the request was wrong. A consumer should re-queue
      * it, with a larger `--wait-lock` budget, rather than treat it as a
      * failure of the work it asked for.
      */
     readonly LOCK_TIMEOUT: 15;
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
-     * conventional "interrupted by the user" code — scripts and CI can tell
+     * conventional "interrupted by the user" code, so scripts and CI can tell
      * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
      */
     readonly USER_CANCELLED: 130;

package/dist/src/errors/codes.js

@@ -27,7 +27,7 @@ export const ExitCode = {
     /** Patch conflict resolution error */
     RESOLUTION_ERROR: 10,
     /**
-     * An internal invariant did not hold — a bug in FireForge itself, not a
+     * An internal invariant did not hold: a bug in FireForge itself, not a
      * user or environment failure. Distinct from GENERAL_ERROR because the
      * two call for opposite responses: a GENERAL_ERROR usually means the
      * operator must change something (fix a config, free a lock, retry), and
@@ -44,30 +44,30 @@ export const ExitCode = {
     SMOKE_EXIT_FAILURE: 12,
     /**
      * `fireforge run --smoke-exit` saw the browser exit with a non-clean
-     * status before the smoke window elapsed — a launch-side failure that
-     * did NOT surface as a console error line (crash before console wiring,
-     * missing profile, etc.).
+     * status before the smoke window elapsed. This is a launch-side failure
+     * that did not surface as a console error line (crash before console
+     * wiring, missing profile, etc.).
      */
     SMOKE_LAUNCH_FAILURE: 13,
     /**
-     * A `fireforge test` run produced a harness result that cannot be trusted
-     * — `engine/` moved (or became unprobeable) while the tests ran. Distinct
-     * from BUILD_ERROR because the two are opposites: a 5 is a suite that
-     * FAILED, a 14 is a suite whose result was THROWN AWAY. A consumer should
+     * A `fireforge test` run produced a harness result that cannot be
+     * trusted: `engine/` moved (or became unprobeable) while the tests ran.
+     * Distinct from BUILD_ERROR because the two are opposites: a 5 is a suite
+     * that failed, a 14 is a suite whose result was thrown away. A consumer should
      * re-run a 14 (after settling the writers) and must not report it as red.
      */
     INCONCLUSIVE: 14,
     /**
      * A lock wait expired: the run never started, because another FireForge
      * process held the lock for the whole budget. Distinct from GENERAL_ERROR
-     * because nothing about the request was wrong — a consumer should re-queue
+     * because nothing about the request was wrong. A consumer should re-queue
      * it, with a larger `--wait-lock` budget, rather than treat it as a
      * failure of the work it asked for.
      */
     LOCK_TIMEOUT: 15,
     /**
      * The user cancelled an interactive prompt. 130 = 128 + SIGINT, the
-     * conventional "interrupted by the user" code — scripts and CI can tell
+     * conventional "interrupted by the user" code, so scripts and CI can tell
      * a deliberate cancellation apart from a real failure (GENERAL_ERROR).
      */
     USER_CANCELLED: 130,

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

@@ -15,17 +15,3 @@ export declare class ConfigNotFoundError extends ConfigError {
     constructor(configPath: string);
     get userMessage(): string;
 }
-/**
- * Error thrown when a required field is missing from config.
- */
-export declare class MissingFieldError extends ConfigError {
-    constructor(field: string);
-}
-/**
- * Error thrown when a field has an invalid value.
- */
-export declare class InvalidFieldError extends ConfigError {
-    readonly expectedType: string;
-    readonly actualValue: unknown;
-    constructor(field: string, expectedType: string, actualValue: unknown);
-}