@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.25

package/incrementalBuilder/buildBatch.proc.ts

@@ -11,10 +11,12 @@ import {
   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";
 
@@ -32,10 +34,11 @@ class BuildBatch {
 
   async run(): Promise<BuildBatchResult> {
     if (this.#request.needs.includes("base")) await this.#buildBase();
-    // Order kept from the in-process build: csr before pages, 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;
   }
 
@@ -45,6 +48,12 @@ class BuildBatch {
     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",
@@ -102,7 +111,21 @@ class BuildBatch {
   }
 
   async #updateCsrRegistry(started: number): Promise<void> {
-    const update = await new CsrDevBundler(this.#app).update(this.#request.changedFiles);
+    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;
@@ -110,17 +133,48 @@ class BuildBatch {
     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)`,
     );
-    this.#emit({
-      type: "csr-updated",
-      data: {
-        generation: update.generation,
-        mode: "registry",
-        reload: update.reload,
-        reason: update.reason,
-        patchUrl: update.patchUrl,
-        changedIds: update.changedIds,
-      },
-    });
+  }
+
+  // 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.
@@ -129,8 +183,16 @@ class BuildBatch {
     try {
       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: {
@@ -138,12 +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) {
       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)}`),
+      );
     }
   }
 
@@ -213,7 +280,13 @@ 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,
@@ -221,8 +294,13 @@ class BuildBatch {
     const app = AppExecutor.from(workspace, request.appName);
     // 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);
   }
 }
 

package/incrementalBuilder/buildBatchProtocol.ts

@@ -1,10 +1,10 @@
 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: it always runs alone, before the builder can serve anything.
-export type BuildBatchNeed = "base" | "pages" | "css" | "csr";
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr" | "ssr";
 
 // JSON only: the worker is spawned per batch and receives this in its argv.
 export interface BuildBatchRequest {
@@ -18,6 +18,7 @@ export interface BuildBatchRequest {
   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"];
@@ -29,7 +30,9 @@ export interface BuildBatchResult {
   optimizedFonts?: OptimizedFonts;
   artifact?: BaseBuildArtifact; // `base` batches only
   errors: Partial<Record<BuildBatchNeed, string>>;
-  crashed?: boolean; // died before reporting, so it streamed no build-status for these needs
+  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

@@ -31,4 +31,35 @@ describe("BuildBatchRunner", () => {
 
     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,7 +3,8 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
 import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
 
-// No pool on purpose: one worker at a time, exiting after its batch, returns the arenas `Bun.build` never frees.
+// 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 {
   #logger = new Logger("BuildBatchRunner");
@@ -38,8 +39,10 @@ export class BuildBatchRunner {
     const started = Date.now();
     const entry = await this.#resolveEntry();
     let result: BuildBatchResult | null = null;
+    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(request)], {
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(payload)], {
       cwd: this.#cwd,
       env: process.env,
       stdio: ["ignore", "inherit", "inherit"],
@@ -47,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;
@@ -64,10 +70,13 @@ export class BuildBatchRunner {
         }`
       : `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 };
   }
 }

package/incrementalBuilder/builderWorkQueue.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { type BatchJob, BuilderWorkQueue } from "./builderWorkQueue";
+
+const gate = () => {
+  const { promise: opened, resolve: open } = Promise.withResolvers<void>();
+  return { open, opened };
+};
+
+describe("BuilderWorkQueue", () => {
+  test("runs jobs one at a time, in the order they were queued", async () => {
+    const order: string[] = [];
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const first = gate();
+    const a = queue.enqueue("a", async () => {
+      await first.opened;
+      order.push("a");
+    });
+    const b = queue.enqueue("b", async () => {
+      order.push("b");
+      return 2;
+    });
+    expect(queue.size).toBe(2);
+    first.open();
+    await a;
+    expect(await b).toBe(2);
+    expect(order).toEqual(["a", "b"]);
+    expect(queue.size).toBe(0);
+  });
+
+  test("folds a batch queued behind another batch into it, for the newest generation", async () => {
+    const ran: BatchJob[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        ran.push(batch);
+        if (ran.length === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages", "css"], changedFiles: ["a.tsx"] });
+    const second = queue.enqueueBatch({
+      generation: 2,
+      needs: ["pages", "css"],
+      changedFiles: ["b.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+    const third = queue.enqueueBatch({ generation: 3, needs: ["csr", "pages"], changedFiles: ["a.tsx", "c.tsx"] });
+    expect(second).toBe(third);
+    running.open();
+    await Promise.all([first, second, third]);
+    expect(ran).toHaveLength(2);
+    expect(ran[1]).toEqual({
+      generation: 3,
+      needs: ["pages", "css", "csr"],
+      changedFiles: ["b.tsx", "a.tsx", "c.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+  });
+
+  test("keeps a batch queued after a task behind that task", async () => {
+    const order: string[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        order.push(`batch:${batch.generation}`);
+        if (batch.generation === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages"], changedFiles: [] });
+    const route = queue.enqueue("route", async () => {
+      order.push("route");
+    });
+    const second = queue.enqueueBatch({ generation: 2, needs: ["pages"], changedFiles: [] });
+    running.open();
+    await Promise.all([first, route, second]);
+    expect(order).toEqual(["batch:1", "route", "batch:2"]);
+  });
+
+  test("drains jobs queued while it waits, and survives a job that throws", async () => {
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const failing = queue.enqueue("fails", async () => {
+      throw new Error("boom");
+    });
+    let late = false;
+    void queue.enqueue("queues-more", async () => {
+      void queue.enqueue("late", async () => {
+        late = true;
+      });
+    });
+    await expect(failing).rejects.toThrow("boom");
+    await queue.drain();
+    expect(late).toBe(true);
+    expect(queue.size).toBe(0);
+  });
+});

package/incrementalBuilder/builderWorkQueue.ts

@@ -0,0 +1,126 @@
+import type { HmrTrace } from "akanjs/server";
+import type { BuildBatchNeed } from "./buildBatchProtocol";
+
+export interface DiscoveryJob {
+  files: string[];
+  refresh: boolean;
+  /** The newest batch these files came from: a route build that starts after has taken it in. */
+  generation: number;
+}
+
+export interface BatchJob {
+  generation: number;
+  needs: BuildBatchNeed[];
+  changedFiles: string[];
+  trace?: HmrTrace;
+  /** Code files whose client-entry discovery goes stale before this batch builds; `refresh` rebuilds it whole. */
+  discovery?: DiscoveryJob;
+}
+
+interface QueuedJob {
+  label: string;
+  batch: BatchJob | null;
+  run: () => Promise<void>;
+  settle: PromiseWithResolvers<void>;
+}
+
+export interface BuilderWorkQueueOptions {
+  runBatch: (batch: BatchJob) => Promise<void>;
+  onSettled?: (label: string, ms: number) => void;
+}
+
+//* The builder's slow lane: build-worker batches, route builds and full CSR builds run here one at a time, so a save's
+//* CSR patch never waits behind them. A batch queued behind another batch folds into it: a burst of saves builds pages
+//* and css once for the newest generation instead of once per save.
+export class BuilderWorkQueue {
+  readonly #runBatch: BuilderWorkQueueOptions["runBatch"];
+  readonly #onSettled: BuilderWorkQueueOptions["onSettled"];
+  readonly #pending: QueuedJob[] = [];
+  #running: QueuedJob | null = null;
+  #idle: Promise<void> = Promise.resolve();
+  #wakeIdle: (() => void) | null = null;
+
+  constructor({ runBatch, onSettled }: BuilderWorkQueueOptions) {
+    this.#runBatch = runBatch;
+    this.#onSettled = onSettled;
+  }
+
+  /** Jobs waiting or running. */
+  get size(): number {
+    return this.#pending.length + (this.#running ? 1 : 0);
+  }
+
+  enqueueBatch(batch: BatchJob): Promise<void> {
+    const tail = this.#pending.at(-1);
+    if (tail?.batch) {
+      tail.batch = BuilderWorkQueue.merge(tail.batch, batch);
+      return tail.settle.promise;
+    }
+    const job = this.#job("batch", batch, async () => undefined);
+    job.run = async () => await this.#runBatch(job.batch ?? batch);
+    return this.#push(job);
+  }
+
+  enqueue<T>(label: string, run: () => Promise<T>): Promise<T> {
+    let result: T | undefined;
+    const job = this.#job(label, null, async () => {
+      result = await run();
+    });
+    return this.#push(job).then(() => result as T);
+  }
+
+  /** Resolves once nothing is waiting or running, including jobs queued while it waits. */
+  async drain(): Promise<void> {
+    while (this.size > 0) await this.#idle;
+  }
+
+  static merge(into: BatchJob, next: BatchJob): BatchJob {
+    const discovery =
+      into.discovery || next.discovery
+        ? {
+            files: [...new Set([...(into.discovery?.files ?? []), ...(next.discovery?.files ?? [])])],
+            refresh: !!into.discovery?.refresh || !!next.discovery?.refresh,
+            generation: Math.max(into.discovery?.generation ?? 0, next.discovery?.generation ?? 0),
+          }
+        : undefined;
+    return {
+      generation: Math.max(into.generation, next.generation),
+      needs: [...new Set([...into.needs, ...next.needs])],
+      changedFiles: [...new Set([...into.changedFiles, ...next.changedFiles])],
+      trace: next.trace ?? into.trace,
+      ...(discovery ? { discovery } : {}),
+    };
+  }
+
+  #job(label: string, batch: BatchJob | null, run: () => Promise<void>): QueuedJob {
+    return { label, batch, run, settle: Promise.withResolvers<void>() };
+  }
+
+  #push(job: QueuedJob): Promise<void> {
+    if (this.size === 0)
+      this.#idle = new Promise<void>((resolve) => {
+        this.#wakeIdle = resolve;
+      });
+    this.#pending.push(job);
+    if (!this.#running) void this.#pump();
+    return job.settle.promise;
+  }
+
+  async #pump(): Promise<void> {
+    for (let job = this.#pending.shift(); job; job = this.#pending.shift()) {
+      this.#running = job;
+      const started = Date.now();
+      try {
+        await job.run();
+        job.settle.resolve();
+      } catch (error) {
+        job.settle.reject(error);
+      } finally {
+        this.#running = null;
+        this.#onSettled?.(job.label, Date.now() - started);
+      }
+    }
+    this.#wakeIdle?.();
+    this.#wakeIdle = null;
+  }
+}

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -196,7 +196,7 @@ describe("IncrementalBuilderHost.maxRssBytes", () => {
     withEnv(
       { AKAN_BUILDER_MAX_RSS_MB: undefined, AKAN_BUILDER_MAX_RSS: undefined, AKAN_MEMORY_LIMIT: undefined },
       () => {
-        expect(IncrementalBuilderHost.maxRssBytes()).toBe(1_200 * 1024 * 1024);
+        expect(IncrementalBuilderHost.maxRssBytes()).toBe(2_048 * 1024 * 1024);
       },
     );
   });

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,6 +1,8 @@
+import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
+import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
 import type { App } from "../commandDecorators";
 
@@ -12,8 +14,10 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "css-updated",
   "pages-updated",
   "csr-updated",
+  "ssr-updated",
   "build-status",
   "builder-metrics",
+  "boot-armed",
 ]);
 /** Prefer `"pipe"` under a TUI: a Bun child that inherits the terminal restores its spawn-time termios on exit. */
 export type DevStdioMode = "inherit" | "pipe";
@@ -45,8 +49,9 @@ export class IncrementalBuilderHost {
   static readonly #restartBaseDelayMs = 1_000;
   static readonly #restartMaxDelayMs = 30_000;
   static readonly #recycleDrainTimeoutMs = 30_000;
-  // A fresh boot is ~300-600MB; this leaves room for one full rebuild on top.
-  static readonly #devMaxRssBytes = 1_200 * 1024 * 1024;
+  // apps/akan's builder peaks near 950MB holding the SSR registry's patcher through a route build, and arming CSR adds
+  // a second patcher: this recycles only a builder grown well past both.
+  static readonly #devMaxRssBytes = 2_048 * 1024 * 1024;
   logger = new Logger("IncrementalBuilderHost");
   entry: string;
   env: Record<string, string>;
@@ -62,6 +67,7 @@ export class IncrementalBuilderHost {
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
+  #patcherOff: boolean = false;
   #manualStop = false;
   // Nothing else answers a request whose builder exits holding it: a crash or kill sends nothing, and a drain races
   // its own exit, so an unanswered page request would spin forever.
@@ -95,10 +101,16 @@ export class IncrementalBuilderHost {
     this.ready = false;
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
+    this.#checkPatchingMarker(isRestart && !afterRecycle);
     let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
-      env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
+      env: {
+        ...this.env,
+        AKAN_WATCH: "1",
+        ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}),
+        ...(this.#patcherOff ? { AKAN_DEV_CSR_PATCHER: "off" } : {}),
+      },
       stdio: ["ignore", this.#stdio, this.#stdio],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
@@ -152,6 +164,23 @@ export class IncrementalBuilderHost {
     }
     this.logger.verbose(`builder spawned pid=${proc.pid} entry=${this.entry}${isRestart ? " restart=1" : ""}`);
   }
+  //? The resident builder patches the dev CSR bundle in its own process, so a bundler crash there takes the file watcher
+  //? with it. A builder that died holding the marker hands every later CSR save to build workers for this session;
+  //? a marker any other exit left behind (Ctrl-C mid-patch) is cleared so it cannot turn the patcher off next session.
+  #checkPatchingMarker(afterCrash: boolean): void {
+    const markers = [CSR_DEV_DIRNAME, SSR_DEV_DIRNAME]
+      .map((dirName) => path.join(this.app.cwdPath, ".akan/artifact", dirName, CSR_DEV_PATCHING_MARKER))
+      .filter((marker) => fs.existsSync(marker));
+    if (markers.length === 0) return;
+    if (afterCrash && !this.#patcherOff) {
+      this.#patcherOff = true;
+      this.logger.warn(
+        "the builder died while patching a dev module registry; registry saves go to a build worker until the next config or metadata restart (AKAN_DEV_CSR_PATCHER=off)",
+      );
+    }
+    for (const marker of markers) fs.rmSync(marker, { force: true });
+  }
+
   async #drain(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
     if (!stream) return;
     const decoder = new TextDecoder();