@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/incrementalBuilder/buildBatch.proc.ts

@@ -1,33 +1,26 @@
 import path from "node:path";
+import { ApplicationBuildReporter } from "@akanjs/devkit/applicationBuildReporter";
+import { resolveSsrPageEntriesForApp } from "@akanjs/devkit/artifact/implicitRootLayout";
+import { computeRouteSeedIndex, saveRouteSeedIndex } from "@akanjs/devkit/artifact/routeSeedIndex";
 import type { App } from "@akanjs/devkit/commandDecorators";
-// Subpath imports only, and as few as possible: this process is spawned once per generation, so every
-// eager import is paid on every save. Measured on a 177-route app: `executors` 24ms, `frontendBuild`
-// ~110ms, app config 5ms.
+// Subpath imports only, as few as possible: spawned per generation, this process pays every import on every save.
 import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import {
   CsrArtifactBuilder,
+  CsrDevBundler,
   CssCompiler,
   FontOptimizer,
   PagesBundleBuilder,
+  ServerGraphFile,
   SsrBaseArtifactBuilder,
+  SsrDevBundler,
 } from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage, BuildPhase } from "akanjs/server";
+import type { BuilderMessage, BuildPhase, HmrTrace } from "akanjs/server";
+import { resolveDevCsrMode } from "akanjs/server/hmr/csrDevManifest";
 import type { BuildBatchRequest, BuildBatchResult, OptimizedFonts, PagesBatchCssAssets } from "./buildBatchProtocol";
 
-/**
- * One generation of frontend build work, in a process that exits when it is done.
- *
- * This exists for one reason: `Bun.build` retains native bundler arenas that the process never returns
- * to the OS — `Bun.gc(true)` reclaims nothing and the JS heap stays flat while RSS climbs ~250MB per
- * save. Exit is the only mechanism that gives that memory back, so the work that scales per save lives
- * here rather than in the long-lived watcher.
- *
- * Nothing is cached here, by design. That costs less than it appears to: `CssCompiler` rebuilds its
- * tailwind compilers on every `compileCss` call, and the watcher always asked for `refresh: true`, so
- * there was no warm state to lose. What genuinely had to be preserved travels in the request — the
- * validated page keys and the previous font optimization.
- */
+// `Bun.build` keeps native bundler arenas that `Bun.gc(true)` cannot reclaim; only exiting returns them.
 class BuildBatch {
   #logger = new Logger("BuildBatch");
   #request: BuildBatchRequest;
@@ -40,33 +33,27 @@ class BuildBatch {
   }
 
   async run(): Promise<BuildBatchResult> {
-    // `base` arrives alone, from a builder that cannot serve anything until it finishes.
     if (this.#request.needs.includes("base")) await this.#buildBase();
-    // Ordered the way the watcher used to run them: csr before pages so a csr failure cannot delay the
-    // pages bundle the browser is waiting on, and css last because it depends on the rebuilt client.
     if (this.#request.needs.includes("csr")) await this.#buildCsr();
-    if (this.#request.needs.includes("pages")) await this.#buildPages();
+    if (this.#request.needs.includes("ssr")) await this.#buildSsrRegistry();
+    // Css before pages: it scans the sources and reads nothing pages produces, so a class edit need not wait for pages.
     if (this.#request.needs.includes("css")) await this.#buildCss();
+    if (this.#request.needs.includes("pages")) await this.#buildPages();
     return this.#result;
   }
 
-  /**
-   * Broadcast as soon as a need finishes rather than when the batch does. The browser is waiting on the
-   * pages bundle; making it wait for the css compile behind it would add latency the in-process version
-   * never had, and it would move every artifact write into the window right before the watcher reports
-   * the generation complete — which is where a save issued immediately afterwards gets dropped by Bun's
-   * recursive `fs.watch` (`local/optimize-resource/06-watcher-dropped-event.md`).
-   *
-   * A bare `process.send` is safe here, unlike in the watcher, for one reason: this process ends by
-   * returning from `main`, and a natural exit flushes a pending ipc write (measured: 1MB delivered
-   * 20/20). It is `process.exit` that discards one — so adding an explicit exit to this file, at the end
-   * of `main` or anywhere after an emit, would silently start dropping `css-updated` payloads. Route
-   * sends through `BuilderChannel` if that ever becomes necessary.
-   */
+  // A bare `process.send` is safe only because this process exits by returning from `main`, which flushes ipc;
+  // an explicit `process.exit` after an emit would silently drop payloads (route through BuilderChannel then).
   #emit(message: BuilderMessage): void {
     process.send?.(message);
   }
 
+  #sentTrace(): HmrTrace | undefined {
+    if (!this.#request.trace) return undefined;
+    const now = Date.now();
+    return { ...this.#request.trace, patchAt: now, sentAt: now };
+  }
+
   #emitStatus(phase: BuildPhase, message?: string): void {
     this.#emit({
       type: "build-status",
@@ -80,11 +67,15 @@ class BuildBatch {
     });
   }
 
-  /**
-   * The boot build. Streams nothing: a builder is not serving yet, so there is no phase board to update
-   * and no browser to reload — the watcher learns the outcome from the batch result, and a failure there
-   * is what puts it into degraded watch mode.
-   */
+  // `Bun.build` rejects with an AggregateError whose own message is only "Bundle failed"; the reasons are nested.
+  #fail(need: keyof BuildBatchResult["errors"], label: string, err: unknown): void {
+    const message = ApplicationBuildReporter.formatError(err, this.#request.workspaceRoot);
+    this.#logger.error(`${label} failed: ${message}`);
+    this.#result.errors[need] = message;
+    if (need !== "base") this.#emitStatus(need, message);
+  }
+
+  // Streams nothing: the builder is not serving yet, so the watcher reads the outcome from the batch result.
   async #buildBase(): Promise<void> {
     const started = Date.now();
     try {
@@ -93,30 +84,115 @@ class BuildBatch {
       this.#result.optimizedFonts = optimizedFonts;
       this.#logger.verbose(`base-artifact ok buildId=${artifact.pagesBundleBuildId} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`base-artifact failed: ${message}`);
-      this.#result.errors.base = message;
+      this.#fail("base", "base-artifact", err);
     }
   }
 
   async #buildCsr(): Promise<void> {
     const started = Date.now();
     try {
-      await new CsrArtifactBuilder(this.#app).build();
-      this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
+      if (resolveDevCsrMode() === "registry") await this.#updateCsrRegistry(started);
+      else await this.#rebuildCsrArtifact(started);
       this.#emitStatus("csr");
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`csr-rebundle failed: ${message}`);
-      this.#result.errors.csr = message;
-      this.#emitStatus("csr", message);
+      this.#fail("csr", "csr-rebundle", err);
+    }
+  }
+
+  async #rebuildCsrArtifact(started: number): Promise<void> {
+    await new CsrArtifactBuilder(this.#app).build();
+    this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
+    // A CSR tab takes none of the SSR refresh messages, so a rebuilt artifact reaches it only as this reload.
+    if (this.#request.changedFiles.length === 0) return;
+    this.#emit({
+      type: "csr-updated",
+      data: { generation: Date.now(), mode: "artifact", reload: true, reason: "the CSR artifact was rebuilt" },
+    });
+  }
+
+  async #updateCsrRegistry(started: number): Promise<void> {
+    const update = await new CsrDevBundler(this.#app).update(this.#request.changedFiles, {
+      announce: (announced) =>
+        this.#emit({
+          type: "csr-updated",
+          data: {
+            generation: announced.generation,
+            mode: "registry",
+            reload: announced.reload,
+            reason: announced.reason,
+            patchUrl: announced.patchUrl,
+            changedIds: announced.changedIds,
+            trace: this.#sentTrace(),
+          },
+        }),
+    });
+    if (!update) {
+      this.#logger.verbose(`csr-dev unchanged (${Date.now() - started}ms)`);
+      return;
+    }
+    this.#logger.verbose(
+      `csr-dev generation=${update.generation} ${update.reload ? `reload (${update.reason})` : `patch modules=${update.changedIds.length}`} graph=${update.moduleCount} (${Date.now() - started}ms)`,
+    );
+  }
+
+  // Takes every entry the routes reach as a root, so a route build naming any of them finds it in the registry.
+  async #buildSsrRegistry(): Promise<void> {
+    const started = Date.now();
+    try {
+      const bundler = new SsrDevBundler(this.#app);
+      //? Runs before pages, so the graph is the last build's, as in the resident builder: a save it holds still waits.
+      const hold = await ServerGraphFile.touches(
+        await ServerGraphFile.read(this.#request.artifactDir),
+        this.#request.changedFiles,
+        (file) => ServerGraphFile.clientExportsOf(file),
+      );
+      const update = await bundler.update(this.#request.changedFiles, {
+        roots: await bundler.clientEntries(),
+        announce: (announced) =>
+          this.#emit({
+            type: "ssr-updated",
+            data: {
+              generation: announced.generation,
+              reload: announced.reload,
+              reason: announced.reason,
+              patchUrl: announced.patchUrl,
+              changedIds: announced.changedIds,
+              trace: this.#sentTrace(),
+              ...(announced.epoch !== undefined ? { epoch: announced.epoch } : {}),
+              ...(announced.first ? { first: true } : {}),
+              ...(hold && this.#request.changedFiles.length > 0
+                ? { hold, batchGeneration: this.#request.generation }
+                : {}),
+            },
+          }),
+      });
+      this.#emitStatus("ssr");
+      this.#logger.verbose(
+        update
+          ? `ssr-dev generation=${update.generation} ${update.reload ? `reload (${update.reason})` : `patch modules=${update.changedIds.length}`} graph=${update.moduleCount} (${Date.now() - started}ms)`
+          : `ssr-dev unchanged (${Date.now() - started}ms)`,
+      );
+    } catch (err) {
+      this.#fail("ssr", "ssr-dev", err);
     }
   }
 
+  // Rewritten with the bundle: the backend rereads it on `pages-updated` to pick up added, moved or deleted routes.
   async #buildPages(): Promise<void> {
     const started = Date.now();
     try {
-      const next = await new PagesBundleBuilder(this.#app).build();
+      const pageEntries = await resolveSsrPageEntriesForApp(this.#app, await this.#app.getPageKeys());
+      const seedIndex = computeRouteSeedIndex(pageEntries);
+      const previousGraph = await ServerGraphFile.read(this.#request.artifactDir);
+      const next = await new PagesBundleBuilder(this.#app, "start", pageEntries).build();
+      await saveRouteSeedIndex(this.#request.artifactDir, seedIndex);
+      const nextGraph = await ServerGraphFile.read(this.#request.artifactDir);
+      const serverTouched = await ServerGraphFile.touches(
+        previousGraph,
+        [...this.#request.changedFiles, ...(previousGraph?.carried ?? [])],
+        (file) => nextGraph?.clientExports[file] ?? null,
+        nextGraph,
+      );
       this.#emit({
         type: "pages-updated",
         data: {
@@ -124,15 +200,17 @@ class BuildBatch {
           buildId: next.buildId,
           generation: this.#request.generation,
           changedFiles: this.#request.changedFiles,
+          trace: this.#sentTrace(),
+          serverTouched,
         },
       });
       this.#emitStatus("pages");
       this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`pages-rebundle failed: ${message}`);
-      this.#result.errors.pages = message;
-      this.#emitStatus("pages", message);
+      this.#fail("pages", "pages-rebundle", err);
+      await ServerGraphFile.carry(this.#request.artifactDir, this.#request.changedFiles).catch((carryError: unknown) =>
+        this.#logger.warn(`server graph carry failed; the next save may skip its RSC refresh: ${String(carryError)}`),
+      );
     }
   }
 
@@ -174,14 +252,10 @@ class BuildBatch {
       });
       this.#logger.verbose(`css-compile ok assets=${Object.keys(cssAssets).length} (${Date.now() - started}ms)`);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      this.#logger.error(`css-rebuild failed: ${message}`);
-      this.#result.errors.css = message;
-      this.#emitStatus("css", message);
+      this.#fail("css", "css-rebuild", err);
     }
   }
 
-  /** Fonts are expensive and rarely change, so the previous result is reused unless this batch touched it. */
   async #optimizeFonts(): Promise<OptimizedFonts> {
     const previous = this.#request.optimizedFonts;
     if (previous && !BuildBatch.#shouldReoptimizeFonts(previous, this.#request.changedFiles)) {
@@ -196,7 +270,6 @@ class BuildBatch {
   }
 
   static #shouldReoptimizeFonts(previous: OptimizedFonts, changedFiles: string[]): boolean {
-    if (changedFiles.length === 0) return false;
     return changedFiles.some((file) => {
       const normalized = path.resolve(file);
       if (/\.(woff2?|ttf|otf)$/i.test(normalized)) return true;
@@ -207,21 +280,32 @@ class BuildBatch {
   static async main(): Promise<void> {
     const raw = process.argv[2];
     if (!raw) throw new Error("[build-batch] missing request argument");
-    const request = JSON.parse(raw) as BuildBatchRequest;
+    const parsed = JSON.parse(raw) as BuildBatchRequest;
+    const request = parsed.trace
+      ? {
+          ...parsed,
+          trace: { ...parsed.trace, workerStartAt: Math.round(performance.timeOrigin), workerAt: Date.now() },
+        }
+      : parsed;
     const workspace = WorkspaceExecutor.fromRoot({
       workspaceRoot: request.workspaceRoot,
       repoName: request.repoName,
     });
     const app = AppExecutor.from(workspace, request.appName);
-    // Seeded rather than rediscovered: the watcher already globbed and validated every route source,
-    // and repeating that here would be the single largest cost of spawning this process.
+    // Seeded, not rediscovered: route discovery would be the largest cost of spawning this process.
     if (request.pageKeys) app.setPageKeys(request.pageKeys);
+    //? Exits with the builder that spawned it (a kill, a crash, a restart for a metadata save): left running, it would
+    //? write a registry its replacement is rebuilding. Removed before returning, since the listener keeps Bun's IPC open.
+    const orphaned = () => process.exit(1);
+    process.on("disconnect", orphaned);
     const result = await new BuildBatch(request, app).run();
     process.send?.({ type: "build-batch-result", data: result });
+    process.off("disconnect", orphaned);
   }
 }
 
-void BuildBatch.main().catch((err) => {
+// Awaited, not voided: on Windows Bun exits during a missing file's `Bun.file` read unless an entry await is pending.
+await BuildBatch.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });

package/incrementalBuilder/buildBatchProtocol.ts

@@ -1,25 +1,12 @@
 import type { FontOptimizer } from "@akanjs/devkit/frontendBuild";
-import type { BaseBuildArtifact, CssPayload, PagesBundlePayload } from "akanjs/server";
+import type { BaseBuildArtifact, CssPayload, HmrTrace, PagesBundlePayload } from "akanjs/server";
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-/**
- * `base` is the boot build (`SsrBaseArtifactBuilder`) and is never batched with the others: it is what a
- * builder runs before it can serve anything, where the rest are per-save work. It earns its place here
- * for the same reason as the others — measured on `apps/akan`, it retains **+1143 MB** of bundler arena
- * that only a process exit returns, which was 65 % of the builder's whole idle footprint.
- */
-export type BuildBatchNeed = "base" | "pages" | "css" | "csr";
+// `base` is the boot build: it always runs alone, before the builder can serve anything.
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr";
 
-/**
- * One generation of build work, handed to a process that exits when it is done.
- *
- * Everything here is JSON: the worker is spawned per batch, so state that the long-lived watcher
- * caches for the session has to travel by value. Two fields exist purely to keep behaviour identical
- * to the in-process version — `pageKeys` because rediscovering them costs ~220ms on a 177-route app
- * (route-export validation), and `optimizedFonts` because fonts are only re-optimized when a font file
- * actually changed.
- */
+// JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {
   appName: string;
   workspaceRoot: string;
@@ -27,37 +14,25 @@ export interface BuildBatchRequest {
   generation: number;
   needs: BuildBatchNeed[];
   changedFiles: string[];
-  /** Page keys the watcher already validated, or null to make the worker discover them itself. */
-  pageKeys: string[] | null;
-  /** Previous font optimization, reused unless this batch touched one of its files. */
-  optimizedFonts: OptimizedFonts | null;
-  /** Previous css assets, so an unchanged compile skips the broadcast instead of busting hashes. */
-  cssAssets: PagesBatchCssAssets | null;
-  /** Absolute artifact directory; the worker writes css assets under it. */
+  pageKeys: string[] | null; // null: the worker discovers them itself
+  optimizedFonts: OptimizedFonts | null; // reused unless this batch touched one of its files
+  cssAssets: PagesBatchCssAssets | null; // an unchanged compile skips the broadcast instead of busting hashes
   artifactDir: string;
+  trace?: HmrTrace;
 }
 
 export type PagesBatchCssAssets = CssPayload["cssAssets"];
 
-/**
- * What the watcher folds back into its own state once the worker is done.
- *
- * Deliberately small: the payloads browsers are waiting on are *streamed* as each need finishes
- * (`pages-updated`, `css-updated`, `build-status`, relayed straight through), so a page reload is not
- * held back by a css compile that has not started yet. Only state the next batch needs travels here.
- */
+// Browser payloads stream as each need finishes; only state the next batch needs travels back here.
 export interface BuildBatchResult {
   generation: number;
   cssAssets?: PagesBatchCssAssets;
   optimizedFonts?: OptimizedFonts;
-  /**
-   * Present only for a `base` batch. The same object the worker wrote to `base-artifact.json`, returned
-   * here so the watcher does not have to read its own boot build back off disk.
-   */
-  artifact?: BaseBuildArtifact;
+  artifact?: BaseBuildArtifact; // `base` batches only
   errors: Partial<Record<BuildBatchNeed, string>>;
-  /** The worker died before reporting, so it streamed no `build-status` of its own for these needs. */
-  crashed?: boolean;
+  crashed?: boolean; // died before reporting its result
+  /** Of a crashed batch, the needs it died before reporting: the others streamed their build-status first. */
+  crashedNeeds?: BuildBatchNeed[];
 }
 
 export type BuildBatchMessage = { type: "build-batch-result"; data: BuildBatchResult };

package/incrementalBuilder/buildBatchRunner.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { createTempApp, tempRoots, writeText } from "../testHelpers";
+import { BuildBatchRunner } from "./buildBatchRunner";
+
+const track = tempRoots();
+
+describe("BuildBatchRunner", () => {
+  test("reports a boot build the bundler refuses with where each reason sits in the workspace", async () => {
+    // Inside the checkout so `akanjs/server` resolves to its source: from the OS temp dir Bun auto-installs npm's 2.x.
+    const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(path.join(appDir, "env/env.client.ts"), "export const env = {} as const;\n");
+    await writeText(
+      path.join(appDir, "page/_index.tsx"),
+      'import { gone } from "./not-there";\nexport default gone;\n',
+    );
+
+    const result = await new BuildBatchRunner({ workspaceRoot: root, cwd: appDir }).run({
+      appName: "demo",
+      workspaceRoot: root,
+      repoName: "repo",
+      generation: 0,
+      needs: ["base"],
+      changedFiles: [],
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.join(appDir, ".akan/artifact"),
+    });
+
+    expect(result.errors.base).toContain('"./not-there" (apps/demo/page/_index.tsx:1:22)');
+  }, 30_000);
+
+  test("a worker that dies mid-batch keeps what each need reported, and fails only the needs it never reached", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+const status = (phase, message) =>
+  process.send({ type: "build-status", data: { generation, phase, ok: !message, files: [], message } });
+status("ssr");
+status("css", "css broke");
+setTimeout(() => process.exit(1), 50);
+`,
+    );
+    const result = await new BuildBatchRunner({ workspaceRoot: root, cwd: appDir }).run({
+      appName: "demo",
+      workspaceRoot: root,
+      repoName: "repo",
+      generation: 7,
+      needs: ["ssr", "css", "pages"],
+      changedFiles: [],
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.join(appDir, ".akan/artifact"),
+    });
+    expect(result).toMatchObject({ crashed: true, crashedNeeds: ["pages"] });
+    expect(result.errors.ssr).toBeUndefined();
+    expect(result.errors.css).toBe("css broke");
+    expect(result.errors.pages).toContain("exited with code 1");
+  }, 30_000);
+});

package/incrementalBuilder/buildBatchRunner.ts

@@ -3,25 +3,10 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
 import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
 
-/**
- * Runs one `BuildBatchRequest` in a fresh process and resolves with what it produced.
- *
- * The watcher serializes every batch through its own work queue, so this deliberately has no pool: one
- * worker exists at a time, and it exits before the next one starts. That is the whole point — the
- * bundler arenas `Bun.build` never frees go back to the OS with the process.
- *
- * A worker that dies without reporting is not fatal. Every need it was given comes back as an error, the
- * watcher reports a red build-status for that generation, and the last-good artifact keeps serving —
- * the same contract a failed in-process build had. It must never take the watcher down with it: the
- * watcher is the dev server's file watcher, so nothing would notice the fix.
- */
+// No pool on purpose: a worker exiting after its batch returns the arenas `Bun.build` never frees. The callers order
+// their own work (the slow lane, the css queue, the SSR registry's boot build beside them), so a few can overlap.
+// A worker that dies without reporting must not take the watcher down; its needs come back as errors.
 export class BuildBatchRunner {
-  static readonly #entryCandidates = (workspaceRoot: string) => [
-    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
-    path.join(import.meta.dir, "buildBatch.proc.js"),
-    path.join(import.meta.dir, "buildBatch.proc.ts"),
-  ];
   #logger = new Logger("BuildBatchRunner");
   #entry: string | null = null;
   #workspaceRoot: string;
@@ -33,7 +18,12 @@ export class BuildBatchRunner {
 
   async #resolveEntry(): Promise<string> {
     if (this.#entry) return this.#entry;
-    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    const candidates = [
+      path.join(this.#workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(this.#workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      path.join(import.meta.dir, "buildBatch.proc.js"),
+      path.join(import.meta.dir, "buildBatch.proc.ts"),
+    ];
     for (const candidate of candidates) {
       if (!(await Bun.file(candidate).exists())) continue;
       this.#entry = candidate;
@@ -42,11 +32,6 @@ export class BuildBatchRunner {
     throw new Error(`[build-batch] worker entry not found; looked in: ${candidates.join(", ")}`);
   }
 
-  /**
-   * `onMessage` receives everything the worker streams as it goes — `pages-updated`, `css-updated`,
-   * `build-status` — so the watcher can relay each one the moment it is produced instead of holding a
-   * page reload until the whole batch is done.
-   */
   async run(
     request: BuildBatchRequest,
     onMessage: (message: BuilderMessage) => void = () => undefined,
@@ -54,9 +39,10 @@ export class BuildBatchRunner {
     const started = Date.now();
     const entry = await this.#resolveEntry();
     let result: BuildBatchResult | null = null;
-    // The request travels in argv rather than over IPC so the worker can start on its first tick
-    // instead of waiting for a handshake it would have to synchronize against.
-    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+    const reported = new Map<string, string | undefined>();
+    const payload = request.trace ? { ...request, trace: { ...request.trace, spawnAt: Date.now() } } : request;
+    // argv rather than IPC, so the worker starts on its first tick instead of waiting for a handshake.
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(payload)], {
       cwd: this.#cwd,
       env: process.env,
       stdio: ["ignore", "inherit", "inherit"],
@@ -64,7 +50,10 @@ export class BuildBatchRunner {
       ipc: (message: BuildBatchMessage | BuilderMessage) => {
         if (!message || typeof message !== "object") return;
         if (message.type === "build-batch-result") result = message.data;
-        else onMessage(message);
+        else {
+          if (message.type === "build-status") reported.set(message.data.phase, message.data.message);
+          onMessage(message);
+        }
       },
     });
     const exitCode = await proc.exited;
@@ -74,21 +63,20 @@ export class BuildBatchRunner {
       );
       return result;
     }
-    // A worker the kernel OOM-killed exits with code `null` and `SIGKILL`, which without the signal
-    // reads exactly like an ordinary crash — and the two have opposite fixes: one is a build error to
-    // find, the other is a memory limit to raise. The peak here is the largest transient in the tree
-    // (a boot build measured 548MB on a tenant app, 1.1GB on apps/akan), so on a small sandbox this is
-    // the process the kernel reaches for first.
+    // An OOM kill (code null, SIGKILL) reads like a crash without the signal, and needs the opposite fix.
     const message = proc.signalCode
       ? `build worker was killed by ${proc.signalCode} before reporting a result${
           proc.signalCode === "SIGKILL" ? " — most often the kernel OOM killer; check the sandbox's memory limit" : ""
         }`
       : `build worker exited with code ${exitCode} before reporting a result`;
     this.#logger.error(`[build-batch] generation=${request.generation} ${message}`);
-    return {
-      generation: request.generation,
-      errors: Object.fromEntries(request.needs.map((need) => [need, message])),
-      crashed: true,
-    };
+    //? A need that reported before the crash keeps what it reported: a worker killed during pages built ssr and css.
+    const crashedNeeds = request.needs.filter((need) => !reported.has(need));
+    const failed = request.needs.flatMap((need) => {
+      if (!reported.has(need)) return [[need, message] as const];
+      const error = reported.get(need);
+      return error ? [[need, error] as const] : [];
+    });
+    return { generation: request.generation, errors: Object.fromEntries(failed), crashed: true, crashedNeeds };
   }
 }