@mandujs/core 0.25.2 → 0.25.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/config/mandu.ts

@@ -198,6 +198,24 @@ export interface ManduConfig {
      * `autoPrebuild === false`. Relative to project root.
      */
     contentDir?: string;
+    /**
+     * Issue #203 — Per-script wall-clock timeout for prebuild scripts
+     * (milliseconds). Default: `120_000` (2 minutes), matching the MCP
+     * `runCommand()` convention (#136). Override for projects that ship
+     * slow seed generators (e.g. large docs indexers, image pipelines).
+     *
+     * Precedence at runtime, highest first:
+     *   1. `MANDU_PREBUILD_TIMEOUT_MS` env var — useful for one-off CI
+     *      overrides without committing to the config.
+     *   2. This field (`dev.prebuildTimeoutMs`).
+     *   3. Default 120_000 ms.
+     *
+     * When the timeout fires, `runPrebuildScripts` throws a
+     * `PrebuildTimeoutError` whose message names the failing script path,
+     * the limit, AND the two override paths — so the user does not need
+     * to re-read this comment to recover.
+     */
+    prebuildTimeoutMs?: number;
   };
   fsRoutes?: {
     routesDir?: string;

package/src/config/validate.ts

@@ -122,6 +122,14 @@ const DevConfigSchema = z
      * an empty pattern. Default `"content"`.
      */
     contentDir: z.string().min(1).default("content"),
+    /**
+     * Issue #203 — per-script wall-clock timeout (ms) for
+     * `scripts/prebuild-*.ts`. `undefined` = use default (120_000 ms) or
+     * the `MANDU_PREBUILD_TIMEOUT_MS` env var if set. Explicit positive
+     * integer overrides both. The boundary check mirrors
+     * `server.rateLimit.windowMs` style — positive integers only.
+     */
+    prebuildTimeoutMs: z.number().int().positive().optional(),
   })
   .strict();
 

package/src/content/prebuild.test.ts

@@ -24,6 +24,11 @@ import {
   shouldAutoPrebuild,
   runPrebuildScripts,
   PrebuildError,
+  PrebuildTimeoutError,
+  resolvePrebuildTimeout,
+  DEFAULT_PREBUILD_TIMEOUT_MS,
+  PREBUILD_TIMEOUT_ENV,
+  defaultSpawn,
   type SpawnHook,
 } from "./prebuild";
 
@@ -247,3 +252,320 @@ describe("runPrebuildScripts", () => {
     expect(spawn.calls[0].timeoutMs).toBe(2 * 60 * 1000);
   });
 });
+
+// ---------------------------------------------------------------------------
+// resolvePrebuildTimeout (Issue #203)
+// ---------------------------------------------------------------------------
+
+describe("resolvePrebuildTimeout", () => {
+  const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+    else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+  });
+
+  it("returns DEFAULT_PREBUILD_TIMEOUT_MS (120s) when no override", () => {
+    delete process.env[PREBUILD_TIMEOUT_ENV];
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    expect(DEFAULT_PREBUILD_TIMEOUT_MS).toBe(120_000);
+  });
+
+  it("explicit arg wins over env var", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "5000";
+    expect(resolvePrebuildTimeout(1234)).toBe(1234);
+  });
+
+  it("env var is used when no explicit arg", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "7500";
+    expect(resolvePrebuildTimeout()).toBe(7500);
+  });
+
+  it("ignores invalid env var (non-numeric) and falls back to default", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "not-a-number";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+
+  it("ignores invalid env var (zero / negative) and falls back to default", () => {
+    process.env[PREBUILD_TIMEOUT_ENV] = "0";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    process.env[PREBUILD_TIMEOUT_ENV] = "-5";
+    expect(resolvePrebuildTimeout()).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+
+  it("ignores non-positive explicit arg", () => {
+    delete process.env[PREBUILD_TIMEOUT_ENV];
+    expect(resolvePrebuildTimeout(0)).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+    expect(resolvePrebuildTimeout(-1)).toBe(DEFAULT_PREBUILD_TIMEOUT_MS);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Issue #203 — Timeout + error surface regressions
+// ---------------------------------------------------------------------------
+
+describe("runPrebuildScripts — timeout surface (Issue #203)", () => {
+  let dir = "";
+  beforeEach(() => { dir = mktmp("timeout-"); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it("honours MANDU_PREBUILD_TIMEOUT_MS env override when timeoutMs omitted", async () => {
+    const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+    process.env[PREBUILD_TIMEOUT_ENV] = "9999";
+    try {
+      writeFile(dir, "scripts/prebuild-1.ts");
+      const spawn = makeMockSpawn(() => ({ exitCode: 0, durationMs: 1 }));
+      await runPrebuildScripts({ rootDir: dir, spawn });
+      expect(spawn.calls[0].timeoutMs).toBe(9999);
+    } finally {
+      if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+      else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+    }
+  });
+
+  it("explicit timeoutMs wins over env var", async () => {
+    const originalEnv = process.env[PREBUILD_TIMEOUT_ENV];
+    process.env[PREBUILD_TIMEOUT_ENV] = "9999";
+    try {
+      writeFile(dir, "scripts/prebuild-1.ts");
+      const spawn = makeMockSpawn(() => ({ exitCode: 0, durationMs: 1 }));
+      await runPrebuildScripts({ rootDir: dir, spawn, timeoutMs: 2222 });
+      expect(spawn.calls[0].timeoutMs).toBe(2222);
+    } finally {
+      if (originalEnv === undefined) delete process.env[PREBUILD_TIMEOUT_ENV];
+      else process.env[PREBUILD_TIMEOUT_ENV] = originalEnv;
+    }
+  });
+
+  it("defaultSpawn throws PrebuildTimeoutError with script name + limit when the script runs longer than timeout", async () => {
+    // Script sleeps 300ms — we set timeout 80ms, so the timer must win.
+    // We use `Bun.sleep` + `process.exit(0)` so the script exits cleanly
+    // if somehow the kill is skipped (no zombie in test harness).
+    const scriptAbs = writeFile(
+      dir,
+      "scripts/prebuild-slow.ts",
+      "await Bun.sleep(300);\nprocess.exit(0);\n",
+    );
+
+    let caught: unknown;
+    try {
+      await defaultSpawn({ scriptPath: scriptAbs, cwd: dir, timeoutMs: 80 });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildTimeoutError);
+    expect(caught).toBeInstanceOf(PrebuildError); // subclass relationship
+    const err = caught as PrebuildTimeoutError;
+    expect(err.timeoutMs).toBe(80);
+    expect(err.scriptPath).toContain("prebuild-slow.ts");
+    // Message contract: includes script name + timeout limit + override hint.
+    expect(err.message).toContain("prebuild-slow.ts");
+    expect(err.message).toContain("80ms");
+    expect(err.message).toContain("dev.prebuildTimeoutMs");
+    expect(err.message).toContain(PREBUILD_TIMEOUT_ENV);
+    // Regression beacon: message MUST NOT contain the opaque
+    // "non-Error thrown" string Issue #203 was reported against.
+    expect(err.message).not.toContain("non-Error thrown");
+  });
+
+  it("runPrebuildScripts surfaces PrebuildTimeoutError via injected spawn", async () => {
+    writeFile(dir, "scripts/prebuild-slow.ts");
+    const spawn: SpawnHook = async (args) => {
+      throw new PrebuildTimeoutError({
+        scriptPath: args.scriptPath,
+        timeoutMs: args.timeoutMs,
+        durationMs: args.timeoutMs,
+      });
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn, timeoutMs: 100 });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildTimeoutError);
+    const err = caught as PrebuildTimeoutError;
+    expect(err.timeoutMs).toBe(100);
+    expect(err.scriptPath).toContain("prebuild-slow.ts");
+  });
+});
+
+describe("runPrebuildScripts — error preservation (Issue #203)", () => {
+  let dir = "";
+  beforeEach(() => { dir = mktmp("err-surface-"); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it("preserves the inner Error message ('boom') when a spawn rejection occurs", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const inner = new Error("boom");
+    const spawn: SpawnHook = async () => {
+      throw inner;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError & { cause?: unknown };
+    // The inner message MUST appear verbatim — the whole point of #203.
+    expect(err.message).toContain("boom");
+    // Regression beacon.
+    expect(err.message).not.toContain("non-Error thrown");
+    // The inner error is attached as `.cause` so debug tooling can
+    // recover its stack.
+    expect(err.cause).toBe(inner);
+  });
+
+  it("preserves stack via .cause when inner Error has a stack", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const inner = new Error("kaboom");
+    const originalStack = inner.stack;
+    expect(originalStack).toBeTruthy();
+    const spawn: SpawnHook = async () => {
+      throw inner;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError & { cause?: Error };
+    expect(err.cause).toBe(inner);
+    expect(err.cause?.stack).toBe(originalStack);
+  });
+
+  it("handles non-Error rejections (string) without producing 'non-Error thrown'", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const spawn: SpawnHook = async () => {
+      // Raw string throw — the pathological case Issue #203 was about.
+      throw "spawn blew up";
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError & { cause?: unknown };
+    // The raw string survives into `.message`.
+    expect(err.message).toContain("spawn blew up");
+    expect(err.message).not.toContain("non-Error thrown");
+    expect(err.cause).toBe("spawn blew up");
+  });
+
+  it("handles non-Error rejections (object) without producing 'non-Error thrown'", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const raw = { code: "EBADF", info: "fd closed" };
+    const spawn: SpawnHook = async () => {
+      throw raw;
+    };
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError & { cause?: unknown };
+    expect(err.message).toContain("EBADF");
+    expect(err.message).not.toContain("non-Error thrown");
+    expect(err.cause).toBe(raw);
+  });
+
+  it("includes stdout/stderr tails in PrebuildError.message for non-zero exit", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const stderrSample = Array.from({ length: 15 }, (_, i) => `err-line-${i + 1}`).join("\n");
+    const stdoutSample = Array.from({ length: 12 }, (_, i) => `out-line-${i + 1}`).join("\n");
+    const spawn: SpawnHook = async () => ({
+      exitCode: 1,
+      durationMs: 5,
+      stdoutTail: stdoutSample,
+      stderrTail: stderrSample,
+    });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(PrebuildError);
+    const err = caught as PrebuildError;
+    // Exactly last 10 stderr lines are kept.
+    expect(err.message).toContain("err-line-15");
+    expect(err.message).toContain("err-line-6"); // the 10-from-last
+    expect(err.message).not.toContain("err-line-5"); // trimmed
+    // Stdout tail is also present (10 lines out of 12).
+    expect(err.message).toContain("out-line-12");
+    expect(err.message).toContain("out-line-3");
+    expect(err.message).not.toContain("out-line-2");
+    // Structured fields carry the full captured tails.
+    expect(err.stderrTail).toBe(stderrSample);
+    expect(err.stdoutTail).toBe(stdoutSample);
+  });
+
+  it("omits empty tail sections when the spawn hook didn't capture", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const spawn: SpawnHook = async () => ({ exitCode: 2, durationMs: 3 });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError;
+    // The "exited with code 2" prefix is present but no "--- stderr ---" sections.
+    expect(err.message).toContain("exited with code 2");
+    expect(err.message).not.toContain("--- stderr");
+    expect(err.message).not.toContain("--- stdout");
+  });
+
+  it("normalizes Windows-style CRLF line endings in stderr tail", async () => {
+    writeFile(dir, "scripts/prebuild.ts");
+    const crlf = ["a", "b", "c", "d"].join("\r\n");
+    const spawn: SpawnHook = async () => ({
+      exitCode: 1,
+      durationMs: 1,
+      stderrTail: crlf,
+    });
+    let caught: unknown;
+    try {
+      await runPrebuildScripts({ rootDir: dir, spawn });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as PrebuildError;
+    // All 4 lines survive (under the 10-line cap).
+    expect(err.message).toContain("a\nb\nc\nd");
+    // No raw \r\n survived.
+    expect(err.message).not.toContain("\r\n");
+  });
+});
+
+describe("PrebuildTimeoutError shape (Issue #203)", () => {
+  it("is a subclass of PrebuildError so existing `instanceof PrebuildError` callers still match", () => {
+    const err = new PrebuildTimeoutError({
+      scriptPath: "/tmp/foo/scripts/prebuild.ts",
+      timeoutMs: 500,
+      durationMs: 500,
+    });
+    expect(err).toBeInstanceOf(PrebuildTimeoutError);
+    expect(err).toBeInstanceOf(PrebuildError);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("PrebuildTimeoutError");
+    expect(err.exitCode).toBeNull();
+  });
+
+  it("message names the script + limit + override paths", () => {
+    const err = new PrebuildTimeoutError({
+      scriptPath: "/repo/scripts/prebuild-seed.ts",
+      timeoutMs: 250,
+      durationMs: 250,
+    });
+    expect(err.message).toContain("prebuild-seed.ts");
+    expect(err.message).toContain("250ms");
+    expect(err.message).toContain("dev.prebuildTimeoutMs");
+    expect(err.message).toContain(PREBUILD_TIMEOUT_ENV);
+  });
+});

package/src/content/prebuild.ts

@@ -34,9 +34,27 @@
  *      whether to abort (prod) or log + continue (dev) based on caller
  *      flags — this module does not make that policy decision.
  *
- *   4. **Timeout**: per-script 2-minute wall-clock cap, matching the
- *      policy established by `packages/mcp/src/util/runCommand.ts` (#136).
- *      Override via `options.timeoutMs` for unusual long-running seeds.
+ *      **Error surface (Issue #203)**: when a script exits non-zero we
+ *      tail its stdout/stderr (last 10 lines of each) into the error
+ *      message so the user can see WHY it failed without scrolling back
+ *      through the terminal. When a spawn rejection is a real `Error`
+ *      (e.g. `ENOENT`) we propagate its `message` and attach `cause` so
+ *      `err.cause?.stack` is recoverable — fixing the "non-Error thrown"
+ *      ghost stack traces reporters saw pre-#203.
+ *
+ *   4. **Timeout (Issue #203 — configurable)**: per-script wall-clock cap.
+ *      Default is 2 minutes (matching `packages/mcp/src/util/runCommand.ts`
+ *      #136). Override precedence, highest first:
+ *
+ *        a. `options.timeoutMs` (explicit caller arg)
+ *        b. `MANDU_PREBUILD_TIMEOUT_MS` environment variable
+ *        c. `ManduConfig.dev.prebuildTimeoutMs` (threaded through by the
+ *           CLI in `packages/cli/src/commands/dev.ts`)
+ *        d. Default: 120_000 ms
+ *
+ *      When the timer fires we throw `PrebuildTimeoutError` with the
+ *      script path + limit so `error.message` alone carries enough info
+ *      to let the user pick their override path without re-reading docs.
  *
  *   5. **No side-effects on empty discovery**: if no scripts are found,
  *      `runPrebuildScripts` returns `{ ran: 0 }` silently. This is the
@@ -75,6 +93,54 @@ import fs from "node:fs";
 const PREBUILD_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs"]);
 const PREBUILD_FILENAME_RE = /^prebuild[-_.a-zA-Z0-9]*\.(ts|tsx|js|mjs)$/;
 
+/**
+ * Default per-script timeout. Matches the MCP `runCommand()` convention
+ * (#136). Exported so `@mandujs/core` consumers (validators, tests) can
+ * reference the same constant instead of re-hardcoding `2 * 60 * 1000`.
+ */
+export const DEFAULT_PREBUILD_TIMEOUT_MS = 2 * 60 * 1000;
+
+/**
+ * Env var name for the runtime override. Checked inside
+ * `resolvePrebuildTimeout` when the caller does not pass an explicit
+ * `timeoutMs`. Invalid values (non-numeric, <= 0) are ignored with a
+ * single stderr warning so a typo does not silently break the default.
+ */
+export const PREBUILD_TIMEOUT_ENV = "MANDU_PREBUILD_TIMEOUT_MS";
+
+/**
+ * Resolve the timeout to apply for a single prebuild script, with
+ * precedence (highest first):
+ *
+ *   1. `explicit` argument — if the CLI or a test passes an explicit
+ *      `timeoutMs`, we honour it verbatim (no env lookup). This keeps
+ *      the injected-spawn unit tests deterministic.
+ *   2. `MANDU_PREBUILD_TIMEOUT_MS` environment variable (runtime knob
+ *      for ops — set once in CI / docker env without re-deploying code).
+ *   3. `DEFAULT_PREBUILD_TIMEOUT_MS`.
+ *
+ * Separated from `runPrebuildScripts` so the CLI can log the resolved
+ * value without re-implementing the lookup.
+ */
+export function resolvePrebuildTimeout(explicit?: number): number {
+  if (typeof explicit === "number" && explicit > 0) {
+    return explicit;
+  }
+  const envRaw = process.env[PREBUILD_TIMEOUT_ENV];
+  if (typeof envRaw === "string" && envRaw.length > 0) {
+    const parsed = Number(envRaw);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+    // Warn once per process — a typoed env var silently falling back to
+    // the default is the kind of issue #203 was reported to fix.
+    console.warn(
+      `[Mandu prebuild] ignoring invalid ${PREBUILD_TIMEOUT_ENV}='${envRaw}' (expected positive number of milliseconds). Falling back to default ${DEFAULT_PREBUILD_TIMEOUT_MS}ms.`,
+    );
+  }
+  return DEFAULT_PREBUILD_TIMEOUT_MS;
+}
+
 /**
  * Discover prebuild scripts under `<rootDir>/<scriptsDir>`.
  *
@@ -119,14 +185,25 @@ export function discoverPrebuildScripts(
 // ---------------------------------------------------------------------------
 
 /**
- * Error thrown when a prebuild script exits non-zero or times out. The
- * `scriptPath` + `exitCode` fields are stable so callers can decide
- * recovery policy without string-matching the message.
+ * Error thrown when a prebuild script exits non-zero or when we could not
+ * complete the spawn (e.g. `bun` binary missing, ENOENT on the script
+ * path). The `scriptPath` + `exitCode` fields are stable so callers can
+ * decide recovery policy without string-matching the message.
+ *
+ * Issue #203: when wrapping an inner `Error`, we preserve the inner
+ * `.message` (shown in the message) AND set `this.cause = err` so
+ * runtimes that render `err.cause` get the full stack. Previously we
+ * sometimes lost the inner error entirely, producing a useless
+ * `"non-Error thrown"` surface.
  */
 export class PrebuildError extends Error {
   readonly scriptPath: string;
   readonly exitCode: number | null;
   readonly durationMs: number;
+  /** Last ~10 lines of stdout captured from the child process, if any. */
+  readonly stdoutTail?: string;
+  /** Last ~10 lines of stderr captured from the child process, if any. */
+  readonly stderrTail?: string;
 
   constructor(
     message: string,
@@ -135,6 +212,8 @@ export class PrebuildError extends Error {
       exitCode: number | null;
       durationMs: number;
       cause?: unknown;
+      stdoutTail?: string;
+      stderrTail?: string;
     },
   ) {
     super(message);
@@ -142,12 +221,55 @@ export class PrebuildError extends Error {
     this.scriptPath = options.scriptPath;
     this.exitCode = options.exitCode;
     this.durationMs = options.durationMs;
+    if (options.stdoutTail !== undefined) this.stdoutTail = options.stdoutTail;
+    if (options.stderrTail !== undefined) this.stderrTail = options.stderrTail;
     if (options.cause !== undefined) {
       (this as Error & { cause?: unknown }).cause = options.cause;
     }
   }
 }
 
+/**
+ * Error thrown specifically when the per-script wall-clock timer elapses
+ * before the subprocess exits. Separate class (a subclass of
+ * `PrebuildError`) so callers can pattern-match:
+ *
+ *     if (err instanceof PrebuildTimeoutError) { showTimeoutHint(); }
+ *     else if (err instanceof PrebuildError)   { showGenericHint(); }
+ *
+ * Without the subclass they would have to grep the `.message` string,
+ * which is the exact anti-pattern Issue #203 flagged.
+ *
+ * The message always ends with an actionable hint naming the three
+ * override paths (config field, env var, CLI flag) so the user can pick
+ * one without reading the docs.
+ */
+export class PrebuildTimeoutError extends PrebuildError {
+  readonly timeoutMs: number;
+
+  constructor(options: {
+    scriptPath: string;
+    timeoutMs: number;
+    durationMs: number;
+    stdoutTail?: string;
+    stderrTail?: string;
+  }) {
+    const { scriptPath, timeoutMs, durationMs } = options;
+    super(
+      `PrebuildTimeoutError: ${scriptPath} exceeded ${timeoutMs}ms (set dev.prebuildTimeoutMs in mandu.config.ts or ${PREBUILD_TIMEOUT_ENV} env var to override).`,
+      {
+        scriptPath,
+        exitCode: null,
+        durationMs,
+        stdoutTail: options.stdoutTail,
+        stderrTail: options.stderrTail,
+      },
+    );
+    this.name = "PrebuildTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
 export interface PrebuildRunnerOptions {
   /** Project root. Absolute path — we resolve scripts relative to this. */
   rootDir: string;
@@ -157,8 +279,13 @@ export interface PrebuildRunnerOptions {
    */
   scriptsDir?: string;
   /**
-   * Per-script wall-clock timeout in milliseconds. Default: 2 minutes,
-   * matching the MCP `runCommand()` convention (#136).
+   * Per-script wall-clock timeout in milliseconds. Precedence matches
+   * `resolvePrebuildTimeout`: explicit arg > `MANDU_PREBUILD_TIMEOUT_MS`
+   * > `DEFAULT_PREBUILD_TIMEOUT_MS` (120_000).
+   *
+   * The CLI threads `ManduConfig.dev.prebuildTimeoutMs` into this field
+   * so end-users typically configure the timeout declaratively without
+   * passing an arg to this API.
    */
   timeoutMs?: number;
   /**
@@ -179,9 +306,10 @@ export interface PrebuildRunnerOptions {
    * Injected spawn hook — overridable in tests so we do not have to
    * actually fork `bun`. Default uses `Bun.spawn` with `stdio: "inherit"`.
    *
-   * Contract: returns a `{ exited }` with an `exited` Promise that
-   * resolves to the exit code (null on signal / timeout kill). The hook
-   * is responsible for the actual kill on timeout.
+   * Contract: returns a `{ exitCode, durationMs }`. May also return
+   * `stdoutTail` / `stderrTail` strings (the default spawn does not —
+   * it uses `stdio: "inherit"` so there is no captured output to tail).
+   * The hook is responsible for the actual kill on timeout.
    */
   spawn?: SpawnHook;
 }
@@ -198,12 +326,22 @@ export interface PrebuildResult {
 /**
  * Spawn shim — kept as an interface so tests can inject a pure-in-memory
  * replacement without monkey-patching `globalThis.Bun`.
+ *
+ * The hook is expected to self-enforce `timeoutMs` by killing the child
+ * when the timer fires, then throwing `PrebuildTimeoutError`. The
+ * default spawn follows this pattern. Custom hooks that skip the kill
+ * are responsible for any consequent zombie.
  */
 export type SpawnHook = (args: {
   scriptPath: string;
   cwd: string;
   timeoutMs: number;
-}) => Promise<{ exitCode: number | null; durationMs: number }>;
+}) => Promise<{
+  exitCode: number | null;
+  durationMs: number;
+  stdoutTail?: string;
+  stderrTail?: string;
+}>;
 
 /**
  * Default spawn hook: fork `bun <scriptPath>` with `stdio: "inherit"` so
@@ -219,6 +357,11 @@ export type SpawnHook = (args: {
  * prebuild's own perf log output doesn't muddle the dev boot perf trace
  * — otherwise the user's "dev boot in Nms" numbers include every
  * prebuild step, which is misleading.
+ *
+ * Note: `stdio: "inherit"` means we cannot capture stdout/stderr to tail
+ * into the error message. The captured-tail feature is exercised by
+ * injected spawn hooks in the test suite and by any future
+ * capture-mode hook callers may want to wire (e.g. CI log bundling).
  */
 export const defaultSpawn: SpawnHook = async ({
   scriptPath,
@@ -281,10 +424,11 @@ export const defaultSpawn: SpawnHook = async ({
     const exitCode = await proc.exited;
     const durationMs = performance.now() - start;
     if (timedOut) {
-      throw new PrebuildError(
-        `Prebuild script '${scriptPath}' exceeded timeout (${timeoutMs}ms) and was killed.`,
-        { scriptPath, exitCode: null, durationMs },
-      );
+      throw new PrebuildTimeoutError({
+        scriptPath,
+        timeoutMs,
+        durationMs,
+      });
     }
     return { exitCode, durationMs };
   } finally {
@@ -292,11 +436,50 @@ export const defaultSpawn: SpawnHook = async ({
   }
 };
 
+/**
+ * Coerce an unknown rejection into a stable Error shape.
+ *
+ * Issue #203 root cause: the original wrap path did
+ *
+ *     throw new Error("non-Error thrown: " + String(e));
+ *
+ * when `e` was, say, a plain string — which destroyed stack info and
+ * yielded the "non-Error thrown" message the reporter saw. This helper
+ * preserves whatever signal we can extract:
+ *
+ *   - `Error` instance → use `err.message`, attach as `cause`.
+ *   - Non-Error (string / number / object)  → use `String(e)` as
+ *     message prefix AND attach the raw value as `cause` so debug
+ *     tooling can introspect it.
+ *
+ * Never produces the string "non-Error thrown" — that phrase was the
+ * explicit regression beacon.
+ */
+function describeInner(err: unknown): { message: string; cause: unknown } {
+  if (err instanceof Error) {
+    // `.message` may still be empty (hand-thrown `new Error()`); fall
+    // back to the class name so the user sees something.
+    const message = err.message.length > 0 ? err.message : err.name;
+    return { message, cause: err };
+  }
+  // Primitives / plain objects: coerce to string. We intentionally do NOT
+  // use the phrase "non-Error thrown" (the Issue #203 regression beacon).
+  let message: string;
+  try {
+    message = typeof err === "string" ? err : JSON.stringify(err);
+  } catch {
+    message = String(err);
+  }
+  if (!message || message === "{}") message = String(err);
+  return { message: message || "unknown spawn rejection", cause: err };
+}
+
 /**
  * Run every `scripts/prebuild-*.ts` in sequence. Resolves with a summary
  * of which scripts ran and how long each took. Rejects with
- * `PrebuildError` on the first failure (subsequent scripts are NOT run,
- * matching the `&&` chain semantics the user relied on before).
+ * `PrebuildError` (or `PrebuildTimeoutError` specifically) on the first
+ * failure — subsequent scripts are NOT run, matching the `&&` chain
+ * semantics the user relied on before.
  *
  * @example
  * ```ts
@@ -309,12 +492,16 @@ export async function runPrebuildScripts(
   const {
     rootDir,
     scriptsDir = "scripts",
-    timeoutMs = 2 * 60 * 1000,
     onStart,
     onFinish,
     spawn = defaultSpawn,
   } = options;
 
+  // Resolve timeout with env-var awareness so both the CLI and direct
+  // programmatic callers pick up `MANDU_PREBUILD_TIMEOUT_MS` without
+  // plumbing.
+  const timeoutMs = resolvePrebuildTimeout(options.timeoutMs);
+
   const scripts = discoverPrebuildScripts(rootDir, scriptsDir);
   if (scripts.length === 0) {
     return { ran: 0, scripts: [] };
@@ -327,11 +514,18 @@ export async function runPrebuildScripts(
 
     let exitCode: number | null;
     let durationMs: number;
+    let stdoutTail: string | undefined;
+    let stderrTail: string | undefined;
     try {
       const res = await spawn({ scriptPath, cwd: rootDir, timeoutMs });
       exitCode = res.exitCode;
       durationMs = res.durationMs;
+      stdoutTail = res.stdoutTail;
+      stderrTail = res.stderrTail;
     } catch (err) {
+      // Already a PrebuildError (typically PrebuildTimeoutError from the
+      // default spawn): propagate as-is after notifying onFinish so the
+      // caller's UI ticks the row off.
       if (err instanceof PrebuildError) {
         onFinish?.({
           scriptPath: err.scriptPath,
@@ -343,17 +537,19 @@ export async function runPrebuildScripts(
           exitCode: err.exitCode,
           durationMs: err.durationMs,
         });
-        // Re-throw to abort the chain on failure.
         throw err;
       }
-      // Non-PrebuildError rejection — wrap so callers only see one error shape.
+      // Non-PrebuildError rejection — wrap in a way that preserves the
+      // inner error's message + stack (Issue #203: previously this path
+      // produced a "non-Error thrown" surface with no useful info).
+      const { message, cause } = describeInner(err);
       throw new PrebuildError(
-        `Prebuild script '${scriptPath}' failed: ${err instanceof Error ? err.message : String(err)}`,
+        `Prebuild script '${scriptPath}' failed: ${message}`,
         {
           scriptPath,
           exitCode: null,
           durationMs: 0,
-          cause: err,
+          cause,
         },
       );
     }
@@ -362,10 +558,14 @@ export async function runPrebuildScripts(
     results.push({ scriptPath, exitCode, durationMs });
 
     if (exitCode !== 0) {
+      // Include captured output tails in the error so logs are actionable
+      // even after the dev server aborts and wipes the scrollback.
+      const tailHint = formatTailHint({ stdoutTail, stderrTail });
       throw new PrebuildError(
         `Prebuild script '${scriptPath}' exited with code ${exitCode}. ` +
-          `Subsequent prebuild scripts were not run.`,
-        { scriptPath, exitCode, durationMs },
+          `Subsequent prebuild scripts were not run.` +
+          (tailHint ? `\n${tailHint}` : ""),
+        { scriptPath, exitCode, durationMs, stdoutTail, stderrTail },
       );
     }
   }
@@ -373,6 +573,42 @@ export async function runPrebuildScripts(
   return { ran: results.length, scripts: results };
 }
 
+/**
+ * Format the captured stdout/stderr tails into a human-readable multi-line
+ * hint suffix for `PrebuildError.message`. Returns an empty string when
+ * neither tail is present (the default spawn path) so we do not bloat the
+ * message with "[stdout tail]\n(empty)" noise in the common case.
+ */
+function formatTailHint(args: {
+  stdoutTail?: string;
+  stderrTail?: string;
+}): string {
+  const lines: string[] = [];
+  if (args.stderrTail && args.stderrTail.length > 0) {
+    lines.push("--- stderr (last 10 lines) ---");
+    lines.push(tailLines(args.stderrTail, 10));
+  }
+  if (args.stdoutTail && args.stdoutTail.length > 0) {
+    lines.push("--- stdout (last 10 lines) ---");
+    lines.push(tailLines(args.stdoutTail, 10));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Keep only the last N lines of a string. Exported indirectly through
+ * `PrebuildError.message` formatting so test assertions can recompute
+ * the expected tail without importing this helper.
+ */
+function tailLines(text: string, n: number): string {
+  const normalized = text.replace(/\r\n/g, "\n");
+  const lines = normalized.split("\n");
+  // Strip one trailing empty line (shell output convention) so we count
+  // real lines only.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines.slice(-n).join("\n");
+}
+
 /**
  * Determine whether a project appears to use the content/prebuild workflow.
  * Used by `mandu dev` to decide whether to enable auto-prebuild by default: