@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -1,19 +1,22 @@
+import { rm } from "node:fs/promises";
 import path from "node:path";
-// Module paths, never a barrel. The `@akanjs/devkit` root re-exports all 41 modules, which would drag
-// @trapezedev/project, the @langchain stack, ssh2, ink and the cloud stack in; and `frontendBuild`'s own
-// barrel reaches `cssCompiler`/`ssrBaseArtifactBuilder`, which pull tailwindcss + @tailwindcss/node
-// (~40MB) into a process that then holds them for the whole dev session. Phase 2 moved css compilation
-// into the batch worker, so this process has no use for them — `entryModuleGraph.test.ts` keeps it that way.
+// Module paths, never a barrel: the devkit and `frontendBuild` barrels would hold tailwindcss (~40MB), ssh2, ink
+// and the cloud stack for the whole dev session (`entryModuleGraph.test.ts` enforces it).
+import { ApplicationBuildReporter } from "@akanjs/devkit/applicationBuildReporter";
 import { CodegenLock } from "@akanjs/devkit/codegenLock";
 import type { App } from "@akanjs/devkit/commandDecorators";
 import { AppExecutor, type PageRoot, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import { AutoImportSync } from "@akanjs/devkit/frontendBuild/autoImportSync";
 import type { ClientEntryDiscovery } from "@akanjs/devkit/frontendBuild/clientBuildTypes";
 import { GraphClientEntryDiscovery } from "@akanjs/devkit/frontendBuild/clientEntryDiscovery";
+import { CsrDevBundler } from "@akanjs/devkit/frontendBuild/csrDevBundler";
+import { CsrDevPatcher } from "@akanjs/devkit/frontendBuild/csrDevPatcher";
 import { DevChangePlanner } from "@akanjs/devkit/frontendBuild/devChangePlanner";
 import { DevGeneratedIndexSync } from "@akanjs/devkit/frontendBuild/devGeneratedIndexSync";
 import { HmrWatcher } from "@akanjs/devkit/frontendBuild/hmrWatcher";
 import { RouteClientBuilder } from "@akanjs/devkit/frontendBuild/routeClientBuilder";
+import { ServerGraphFile } from "@akanjs/devkit/frontendBuild/serverGraphFile";
+import { SsrDevBundler } from "@akanjs/devkit/frontendBuild/ssrDevBundler";
 import { WatchRootResolver } from "@akanjs/devkit/frontendBuild/watchRootResolver";
 import { Logger } from "akanjs/common";
 import type {
@@ -25,10 +28,13 @@ import type {
   BuildPhase,
   BuildRouteResultPayload,
   ChangeBatch,
+  HmrTrace,
 } from "akanjs/server";
+import { CSR_DEV_PATCHING_MARKER } from "akanjs/server/hmr/csrDevManifest";
 import type { BuildBatchNeed, BuildBatchRequest, BuildBatchResult, OptimizedFonts } from "./buildBatchProtocol";
 import { BuildBatchRunner } from "./buildBatchRunner";
 import { BuilderChannel } from "./builderChannel";
+import { type BatchJob, BuilderWorkQueue, type DiscoveryJob } from "./builderWorkQueue";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
 interface IncrementalBuilderOptions {
@@ -41,6 +47,7 @@ interface IncrementalBuilderOptions {
 }
 
 type IncrementalBuilderBootDeps = Pick<IncrementalBuilderOptions, "artifact" | "optimizedFonts" | "discovery">;
+type BatchWork = Pick<BuildBatchRequest, "generation" | "needs" | "changedFiles" | "trace">;
 
 class IncrementalBuilder {
   #logger = new Logger("IncrementalBuilder");
@@ -56,8 +63,43 @@ class IncrementalBuilder {
   #autoImportSync: AutoImportSync;
   #watcher: HmrWatcher | null = null;
   #generation = 0;
+  #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
-  #workQueue: Promise<void> = Promise.resolve();
+  #csrBundler: CsrDevBundler;
+  /** Null when `AKAN_DEV_CSR_PATCHER=off`: every CSR save then goes to a build worker, as before the patcher. */
+  #patcher: CsrDevPatcher | null;
+  /** A worker's full CSR build (arming, re-arming) that a patch must not race for the csr-dev directory. */
+  #csrGate: Promise<void> = Promise.resolve();
+  #csrArming = false;
+  #csrArms = 0;
+  #crashRetryTimer: ReturnType<typeof setTimeout> | null = null;
+  readonly #crashRetryEntries = new Set<string>();
+  #csrWasActive = false;
+  #csrArmSucceeded = false;
+  /** Where SSR pages load their client code from in dev; route builds bundle only its server half. */
+  #ssrBundler: SsrDevBundler;
+  /** Null when `AKAN_DEV_CSR_PATCHER=off`: every registry save then goes to a build worker. */
+  #ssrPatcher: CsrDevPatcher | null;
+  //* Serializes everything that writes ssr-dev: a save's patch (fast lane), a route build adding the entries it names,
+  //* a queued worker batch with the ssr need, and the boot build. Never held while awaiting the slow lane.
+  #ssrLock: Promise<void> = Promise.resolve();
+  /** How often each reason sent a registry save to a build worker this session: the resident patcher's miss rate. */
+  readonly #delegations = new Map<string, number>();
+  /** The boot build of the SSR registry while it runs; it holds every entry the routes reach once it lands. */
+  #ssrArming: Promise<void> | null = null;
+  //* A registry build that failed on the user's code fails again until the code changes, so route builds do not retry
+  //* it; the next attempt that touches the registry (a save's patch, a worker batch) settles it. A worker that died
+  //* before reporting (an OOM kill) route builds do retry, at most every `#crashRetryMs`.
+  #ssrBroken = false;
+  #ssrCrashedAt: number | null = null;
+  static readonly #crashRetryMs = 10_000;
+  /** Arming and the route entries deferred behind it run beside both lanes; a recycle waits for them too. */
+  readonly #beside = new Set<Promise<void>>();
+  #barrelFailed = false;
+  //* Two lanes: a save's codegen and CSR patch in the fast one, which the watcher waits for; build workers, route
+  //* builds and discovery in the slow one, which folds queued batches. A save no longer waits behind pages and css.
+  #fastQueue: Promise<void> = Promise.resolve();
+  #workQueue: BuilderWorkQueue;
   #inFlight = 0;
   #workCount = 0;
   #shuttingDown = false;
@@ -71,6 +113,7 @@ class IncrementalBuilder {
     this.#optimizedFonts = options.optimizedFonts;
     this.#discovery = options.discovery;
     this.#generation = options.initialGeneration ?? 0;
+    this.#discoveredThrough = this.#generation;
     this.#batchRunner = new BuildBatchRunner({
       workspaceRoot: options.app.workspace.workspaceRoot,
       cwd: options.app.cwdPath,
@@ -78,34 +121,51 @@ class IncrementalBuilder {
     this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#autoImportSync = new AutoImportSync({ workspaceRoot: options.app.workspace.workspaceRoot });
+    this.#csrBundler = new CsrDevBundler(options.app);
+    this.#patcher =
+      process.env.AKAN_DEV_CSR_PATCHER === "off" ? null : new CsrDevPatcher(this.#csrBundler, { resident: true });
+    this.#ssrBundler = new SsrDevBundler(options.app, { discovery: () => this.#discovery });
+    this.#ssrPatcher =
+      process.env.AKAN_DEV_CSR_PATCHER === "off" ? null : new CsrDevPatcher(this.#ssrBundler, { resident: true });
+    this.#workQueue = new BuilderWorkQueue({
+      runBatch: async (batch) => await this.#runQueuedBatch(batch),
+      onSettled: (label, ms) => {
+        this.#workCount += 1;
+        this.#logger.verbose(`[work-queue] ${label} finished in ${ms}ms`);
+        this.#reportMetrics();
+      },
+    });
   }
 
   get #artifactDir() {
     return `${this.#app.cwdPath}/.akan/artifact`;
   }
 
-  /**
-   * Build a route and answer it. The reply is part of the work item on purpose: `shutdown` drains the
-   * work queue before exiting, so folding the flush in here is what makes "drained" mean "answered".
-   */
+  // The reply is part of the work item on purpose: `shutdown` drains the queue, so "drained" must mean "answered".
   async handleBuildRoute(msg: BuilderReq): Promise<void> {
-    await this.#enqueueWork(`build-route:${msg.routeId}`, async () =>
+    await this.#workQueue.enqueue(`build-route:${msg.routeId}`, async () =>
       BuilderChannel.send(await this.#handleBuildRoute(msg)),
     );
   }
 
   async #handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
+    const seenGeneration = this.#discoveredThrough;
     try {
       const delta = await new RouteClientBuilder({
         app: this.#app,
         routeId: msg.routeId,
         seeds: msg.seeds,
+        graphSeeds: msg.graphSeeds,
         artifact: this.#artifact,
         knownEntries: new Set<string>(msg.knownEntries),
         discovery: this.#discovery,
+        browser: "registry",
       }).build();
+      await this.#ensureSsrEntries(delta.registryEntries ?? []);
       this.#logger.verbose(`build-route ok routeId=${msg.routeId} newEntries=${delta.newEntries.length}`);
-      this.#sendBuildStatus("route", { generation: msg.generation, ok: true, files: msg.seeds });
+      //? The builder's generation, not the route cache's: the cache's does not move when a fixed file maps to no entry,
+      //? so the rebuild's ok would carry the failure's own number.
+      this.#sendBuildStatus("route", { generation: this.#generation, ok: true, files: msg.seeds, scope: msg.routeId });
       return {
         type: "build-route-res",
         id: msg.id,
@@ -119,56 +179,70 @@ class IncrementalBuilder {
           clientDepsByEntry: delta.clientDepsByEntry,
           routeId: msg.routeId,
           generation: msg.generation,
+          seenGeneration,
         } as BuildRouteResultPayload,
       };
     } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
+      const errMsg = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
-      this.#sendBuildStatus("route", { generation: msg.generation, ok: false, files: msg.seeds, message: errMsg });
+      this.#sendBuildStatus("route", {
+        generation: this.#generation,
+        ok: false,
+        files: msg.seeds,
+        message: errMsg,
+        scope: msg.routeId,
+      });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
     }
   }
   #sendBuildStatus(
     phase: BuildPhase,
-    { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
+    {
+      generation,
+      ok,
+      files,
+      message,
+      scope,
+    }: { generation?: number; ok: boolean; files?: string[]; message?: string; scope?: string },
   ): void {
     if (typeof generation !== "number") return;
     BuilderChannel.emit({
       type: "build-status",
-      data: {
-        generation,
-        phase,
-        ok,
-        files: files ?? [],
-        message,
-      },
+      data: { generation, phase, ok, files: files ?? [], message, ...(scope !== undefined ? { scope } : {}) },
     });
   }
-  async #enqueueWork<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  async #enqueueFast<T>(label: string, fn: () => Promise<T>): Promise<T> {
     const started = Date.now();
     this.#inFlight += 1;
-    const run = this.#workQueue.then(fn, fn);
-    this.#workQueue = run.then(() => undefined).catch(() => undefined);
+    const run = this.#fastQueue.then(fn, fn);
+    this.#fastQueue = run.then(() => undefined).catch(() => undefined);
     try {
       return await run;
     } finally {
       this.#inFlight -= 1;
       this.#workCount += 1;
-      this.#logger.verbose(`[work-queue] ${label} finished in ${Date.now() - started}ms`);
+      this.#logger.verbose(`[fast-queue] ${label} finished in ${Date.now() - started}ms`);
       this.#reportMetrics();
     }
   }
 
-  /** No queued work and no debounced css rebuild, so nothing is lost if the process exits now. */
   get #idle(): boolean {
-    return this.#inFlight === 0 && this.#cssRebuildTimer === null;
+    return this.#inFlight === 0 && this.#workQueue.size === 0 && this.#cssRebuildTimer === null;
   }
 
-  /**
-   * Reported only when the builder is idle. The host's only lever against the bundler arenas
-   * `Bun.build` retains is to recycle this process, and a recycle decided while work is queued would
-   * either truncate that work or race the shutdown drain — so a busy builder simply says nothing.
-   */
+  // Callers catch their own errors: the promise handed in never rejects.
+  #runBeside(work: Promise<void>): Promise<void> {
+    this.#inFlight += 1;
+    const tracked: Promise<void> = work.finally(() => {
+      this.#inFlight -= 1;
+      this.#beside.delete(tracked);
+      this.#reportMetrics();
+    });
+    this.#beside.add(tracked);
+    return tracked;
+  }
+
+  // Idle only: the host recycles on these metrics, and a recycle decided mid-work would truncate it or race the drain.
   #reportMetrics(): void {
     if (!this.#idle || this.#shuttingDown) return;
     BuilderChannel.emit({
@@ -177,34 +251,31 @@ class IncrementalBuilder {
     });
   }
 
-  /**
-   * Finish queued work, then exit so the OS reclaims the bundler arenas. The host restarts a
-   * replacement; build requests that arrive during the drain are refused with the same retry error
-   * the backend already handles for any other builder restart.
-   */
+  // Exits so the OS reclaims the bundler arenas; the host spawns the replacement.
   async shutdown(reason: string): Promise<void> {
     if (this.#shuttingDown) return;
     this.#shuttingDown = true;
     const started = Date.now();
     this.#logger.debug(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
-    // Stopped before the drain, or a save landing mid-drain would enqueue a batch behind the queue tail
-    // this method already awaited — and `process.exit(0)` would cut that batch off partway through
-    // writing its artifacts. The replacement rebuilds every artifact from its boot build anyway, so the
-    // batch is not lost; a half-written one would be.
+    // Before the drain: a save landing mid-drain would queue behind the awaited tail and `process.exit` would cut
+    // its artifacts off half-written; the replacement's boot build redoes that work anyway.
     this.#watcher?.stop();
     if (this.#cssRebuildTimer) {
-      // Only reachable if a css batch landed between the idle report and this request: the fresh
-      // boot build recompiles css from scratch anyway, so dropping the debounce loses nothing.
+      // Only if css landed after the idle report; the replacement's boot build recompiles css, so nothing is lost.
       clearTimeout(this.#cssRebuildTimer);
       this.#cssRebuildTimer = null;
       this.#pendingCssRebuild = null;
     }
-    await this.#workQueue.catch(() => undefined);
+    // The fast lane first: a save it is still handling may queue a batch in the slow one.
+    await this.#fastQueue.catch(() => undefined);
+    await this.#workQueue.drain();
     await this.#cssRebuildQueue.catch(() => undefined);
-    // Drained queues do not mean the host has the results. The events those work items produced are the
-    // largest messages this process sends, and `process.exit` discards an ipc write that has not
-    // flushed — a `css-updated` relayed milliseconds before this line would be dropped with no error
-    // anywhere, leaving the backend serving the previous bundle. See `BuilderChannel`.
+    while (this.#beside.size > 0) await Promise.all([...this.#beside]);
+    if (this.#delegations.size > 0)
+      this.#logger.verbose(
+        `registry saves handed to build workers this session: ${[...this.#delegations].map(([reason, count]) => `${reason}=${count}`).join(", ")}`,
+      );
+    // Drained queues are not delivered results: `process.exit` drops unflushed ipc writes (a relayed `css-updated`).
     const flushed = await BuilderChannel.drain();
     this.#logger.debug(
       `drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`,
@@ -215,8 +286,7 @@ class IncrementalBuilder {
   get shuttingDown(): boolean {
     return this.#shuttingDown;
   }
-  //* Watch events name the file's real path, so synced lib pages are matched by `realDir` while their
-  //* page key still carries the app-relative `(libs)/(<lib>)` prefix.
+  //* Watch events carry real paths: synced lib pages match by `realDir`, their keys keep the `(libs)/(<lib>)` prefix.
   static #matchPageRoot(roots: PageRoot[], abs: string): PageRoot | null {
     for (const root of roots) {
       const absRoot = path.resolve(root.realDir);
@@ -244,7 +314,6 @@ class IncrementalBuilder {
     }
     return false;
   }
-  /** Debounced css-only rebuild; the compile itself runs in a disposable worker like every other build. */
   scheduleCssRebuild({ generation, changedFiles }: { generation?: number; changedFiles?: string[] }) {
     this.#pendingCssRebuild = { generation, changedFiles };
     if (this.#cssRebuildTimer) clearTimeout(this.#cssRebuildTimer);
@@ -279,13 +348,12 @@ class IncrementalBuilder {
     }, 150);
   }
   async installWatcher() {
-    const artifactDir = this.#artifactDir;
     const roots = await new WatchRootResolver(this.#app).resolve();
     const watcher = new HmrWatcher({
       roots,
       logger: this.#logger,
       onBatch: async (batch: ChangeBatch) => {
-        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(artifactDir, batch));
+        await this.#enqueueFast("hmr-batch", async () => this.#handleWatchBatch(batch));
       },
     });
     await watcher.start();
@@ -293,13 +361,12 @@ class IncrementalBuilder {
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
 
-  async #handleWatchBatch(artifactDir: string, batch: ChangeBatch) {
+  async #handleWatchBatch(batch: ChangeBatch) {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
-    //* Insert framework imports that are used but omitted (e.g. `Int` in *.constant.ts, `fetch` in
-    //* *.store.ts) before regenerating barrels. Edits land on files already in this batch, so they
-    //* rebuild in this same generation; the write is idempotent so it does not re-trigger the watcher.
+    const trace = { ...batch.trace, batchAt: Date.now() };
+    //* Auto-import edits touch only this batch's files, so they rebuild in this same generation.
     const [autoImport, indexSync] = await CodegenLock.run(
       this.#app.workspace.workspaceRoot,
       `hmr-batch:${this.#app.name}`,
@@ -311,9 +378,7 @@ class IncrementalBuilder {
     for (const error of autoImport.errors) this.#logger.error(error);
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
-    //* Both passes above write source files, and this generation's build consumes what they wrote. Hand
-    //* them to the watcher so its verification scan does not read them back as a user edit and spend a
-    //* second generation rebuilding identical content.
+    //* Absorbed so the watcher's verification scan does not replay these writes as a user edit next generation.
     await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
     const { files, kinds, expandedBatch, devPlan, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
@@ -326,24 +391,26 @@ class IncrementalBuilder {
     );
     for (const error of indexSync.errors) this.#logger.error(error);
 
-    if (kinds.includes("code")) {
-      const started = Date.now();
-      if (kinds.includes("config")) this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
-      else this.#discovery.invalidate?.(files);
-      this.#logger.verbose(
-        `client-entry-discovery ${kinds.includes("config") ? "refreshed" : "invalidated"} (${Date.now() - started}ms)`,
-      );
-    }
+    // Invalidated in the slow lane, under the route builds that read it; a registry check reading it beside them caches
+    // nothing a walk began before the invalidation (the discovery's epoch).
+    const discovery = kinds.includes("code") ? { files, refresh: kinds.includes("config"), generation } : undefined;
 
     if (hasSyncErrors) {
+      this.#barrelFailed = true;
       this.#sendBuildStatus("barrel", { generation, ok: false, files, message: indexSync.errors.join("\n") });
       BuilderChannel.emit(event);
+      if (discovery)
+        void this.#workQueue
+          .enqueue("discovery", async () => await this.#refreshDiscovery(discovery))
+          .catch(this.#slowLaneFailed("discovery"));
       return;
     }
-    if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
+    // After a failure too, where nothing changed on disk: the host re-sends a phase still failing to every new tab.
+    if (indexSync.changedFiles.length > 0 || this.#barrelFailed)
+      this.#sendBuildStatus("barrel", { generation, ok: true, files });
+    this.#barrelFailed = false;
 
-    // Server-only generations (e.g. a .service.ts or srvkit edit) must not rebuild or refresh the
-    // client: a fresh pages buildId would broadcast rsc-refresh to browsers for no visible change.
+    // Server-only generations skip the client: a fresh pages buildId would rsc-refresh browsers for no visible change.
     const rebuildClient = devPlan.actions.includes("rebuild-client");
     if (kinds.includes("code") && !rebuildClient) {
       this.#logger.verbose(`client rebuild skipped; devPlan actions=${devPlan.actions.join(",") || "(none)"}`);
@@ -358,75 +425,392 @@ class IncrementalBuilder {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
 
-    const needs: BuildBatchNeed[] = [];
+    BuilderChannel.emit(event);
+
     if (kinds.includes("code") && rebuildClient) {
-      if (this.#shouldRebuildCsr()) needs.push("csr");
-      else
+      // Css rides the pages batch rather than its own debounce: the slow lane folds a burst of saves into one batch.
+      const needs: BuildBatchNeed[] = ["pages", "css"];
+      if (!this.#csrActive)
         this.#logger.verbose(
           `csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`,
         );
-      needs.push("pages");
-      // Server-only code edits cannot introduce class names the CSS scanner would pick up; only a
-      // client rebuild or a direct stylesheet edit can change the compiled CSS. Folded into this
-      // generation's batch rather than debounced separately: the work queue already serializes
-      // generations, so by the time a second batch runs the 150ms debounce would have fired anyway,
-      // and a second worker spawn per save costs more than the coalescing ever saved.
-      needs.push("css");
+      //? One after the other, since two compiles side by side slow both. CSR goes first unless its build is being armed:
+      //? a CSR patch then waits behind #csrGate, which SSR tabs must not.
+      const patchCsr = async () => (this.#csrActive ? await this.#patchCsr(generation, files, trace) : false);
+      const patchSsr = async () => await this.#patchSsr(generation, files, trace);
+      let csrToWorker: boolean;
+      let ssrToWorker: boolean;
+      if (this.#csrArming) {
+        ssrToWorker = await patchSsr();
+        csrToWorker = await patchCsr();
+      } else {
+        csrToWorker = await patchCsr();
+        ssrToWorker = await patchSsr();
+      }
+      if (csrToWorker) needs.unshift("csr");
+      if (ssrToWorker) needs.unshift("ssr");
+      const batch: BatchJob = { generation, needs, changedFiles: files, trace, ...(discovery ? { discovery } : {}) };
+      // A worker's registry build rewrites the directory its patcher reads, so the next save waits for it.
+      if (needs.includes("csr") || needs.includes("ssr")) await this.#workQueue.enqueueBatch(batch);
+      else void this.#workQueue.enqueueBatch(batch).catch(this.#slowLaneFailed("batch"));
+      return;
     }
-
-    BuilderChannel.emit(event);
-
-    if (needs.length > 0) await this.#runBatch({ generation, needs, changedFiles: files });
-    // A css-only batch keeps its debounce: those arrive in bursts while a stylesheet is edited, and
-    // without a pages build in front of them there is nothing else to space them out.
-    else if (kinds.includes("css")) {
+    if (discovery)
+      void this.#workQueue
+        .enqueue("discovery", async () => await this.#refreshDiscovery(discovery))
+        .catch(this.#slowLaneFailed("discovery"));
+    // Css-only batches keep the debounce: they arrive in bursts while a stylesheet is edited.
+    if (kinds.includes("css")) {
       this.scheduleCssRebuild({ generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }
 
-  /**
-   * Run one generation of build work in a process that exits afterwards. The worker streams the
-   * messages the backend and the HMR overlay consume, which this relays untouched, so the sequence a
-   * browser observes is the same one the in-process build produced.
-   */
-  async #runBatch({
-    generation,
-    needs,
-    changedFiles,
-  }: {
-    generation: number;
-    needs: BuildBatchNeed[];
-    changedFiles: string[];
-  }): Promise<BuildBatchResult> {
+  // True when the save has to go to a build worker: the patcher handed it back, or threw (the worker reports why).
+  async #patchCsr(generation: number, files: string[], trace: HmrTrace): Promise<boolean> {
+    const patcher = this.#patcher;
+    if (!patcher) return true;
+    await this.#csrGate;
+    // The arming build this save waited for failed: CSR is off again, and the next request arms it anew.
+    if (!this.#csrActive) return false;
     const started = Date.now();
-    const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) =>
-      BuilderChannel.emit(msg),
+    const marker = path.join(this.#csrBundler.outDir, CSR_DEV_PATCHING_MARKER);
+    await Bun.write(marker, String(process.pid));
+    try {
+      const result = await patcher.update(files, {
+        announce: (update) => {
+          const now = Date.now();
+          BuilderChannel.emit({
+            type: "csr-updated",
+            data: {
+              generation: update.generation,
+              mode: "registry",
+              reload: update.reload,
+              reason: update.reason,
+              patchUrl: update.patchUrl,
+              changedIds: update.changedIds,
+              trace: { ...trace, patchAt: now, sentAt: now },
+            },
+          });
+        },
+      });
+      if (result.kind === "delegate") {
+        this.#logger.verbose(
+          `csr-patch handed to a build worker (${this.#countDelegation("csr", result.reason)}): ${result.reason}`,
+        );
+        return true;
+      }
+      this.#sendBuildStatus("csr", { generation, ok: true, files });
+      this.#logger.verbose(
+        result.kind === "unchanged"
+          ? `csr-patch unchanged (${Date.now() - started}ms)`
+          : `csr-patch generation=${result.update.generation} ${result.update.reload ? `reload (${result.update.reason})` : `patch modules=${result.update.changedIds.length}`} (${Date.now() - started}ms)`,
+      );
+      return false;
+    } catch (err) {
+      const message = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+      if (IncrementalBuilder.#isCompileError(err)) {
+        this.#sendBuildStatus("csr", { generation, ok: false, files, message });
+        return false;
+      }
+      this.#logger.verbose(`csr-patch threw; a build worker takes this save: ${message}`);
+      patcher.forget();
+      return true;
+    } finally {
+      await rm(marker, { force: true });
+    }
+  }
+
+  // True when the save has to go to a build worker, as for CSR.
+  async #patchSsr(generation: number, files: string[], trace: HmrTrace): Promise<boolean> {
+    const patcher = this.#ssrPatcher;
+    if (!patcher) return true;
+    const hold = await ServerGraphFile.touches(await ServerGraphFile.read(this.#artifactDir), files, (file) =>
+      ServerGraphFile.clientExportsOf(file),
+    );
+    //? Ahead of this save's own discovery job in the slow lane: which client entries a page still names decides which
+    //? pending roots this patch keeps.
+    this.#discovery.invalidate?.(files);
+    return await this.#withSsrLock(
+      async () => await this.#runSsrPatcher(patcher, files, { trace, hold, batchGeneration: generation }),
+    );
+  }
+
+  //* Adds the entries a route build names to the registry, since the tab requires them by id. A registry that cannot
+  //* take them fails no route build: the page answers, and its tab waits for the registry while the overlay says why.
+  async #ensureSsrEntries(entries: string[], { crashRetry = false }: { crashRetry?: boolean } = {}): Promise<void> {
+    if (entries.length === 0) return;
+    //? The boot build takes every entry the routes reach, so the first page answers now and its tab waits for the
+    //? registry (boot.json) instead; whatever that build missed is added right after it lands.
+    const arming = this.#ssrArming;
+    if (arming) {
+      void this.#runBeside(
+        arming
+          .then(async () => await this.#ensureSsrEntries(entries, { crashRetry }))
+          .catch(this.#slowLaneFailed("ssr-ensure")),
+      );
+      return;
+    }
+    await this.#withSsrLock(async () => {
+      const patcher = this.#ssrPatcher;
+      // The builder's generation, not the request's: its build-status joins the saves' `ssr` ones.
+      const generation = this.#generation;
+      if (
+        patcher &&
+        !(await this.#runSsrPatcher(patcher, [], { roots: entries, onlyRoots: true, batchGeneration: generation }))
+      )
+        return;
+      //? Read, not compiled: with the patcher off, the save's own worker batch already built every entry.
+      if (!patcher && (await this.#ssrBundler.holds(entries))) return;
+      //? Not retried per route build: the save that fixes the error rebuilds it, where each route build retrying held
+      //? the SSR lock that save's patch waits on.
+      if (this.#ssrBroken) return;
+      if (this.#ssrCrashedAt !== null && Date.now() - this.#ssrCrashedAt < IncrementalBuilder.#crashRetryMs) {
+        //? Handed over just now with nothing run for them: the retry must find them to hand over again.
+        patcher?.releaseHandedOver();
+        this.#retryAfterCrash(this.#ssrCrashedAt, entries);
+        return;
+      }
+      await this.#runSsrWorker(generation).catch((err: unknown) => {
+        this.#logger.error(
+          `ssr-registry could not take a route's entries; the save that fixes it rebuilds it: ${ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot)}`,
+        );
+      });
+      //? A worker that died took these entries with it and left them pending nowhere: they are tried once more after the
+      //? crash window, but a retry that crashes again waits for the next route build or save.
+      if (this.#ssrCrashedAt !== null && !crashRetry) this.#retryAfterCrash(this.#ssrCrashedAt, entries);
+    });
+  }
+
+  //? Once the crash window closes, for the entries skipped in it: later route builds may name none (the first one
+  //? announced every entry to the route cache), so without this a tab could wait on boot.json until the next save.
+  #retryAfterCrash(crashedAt: number, entries: string[]): void {
+    for (const entry of entries) this.#crashRetryEntries.add(entry);
+    if (this.#crashRetryTimer) return;
+    const timer = setTimeout(
+      () => {
+        this.#crashRetryTimer = null;
+        const retried = [...this.#crashRetryEntries];
+        this.#crashRetryEntries.clear();
+        if (this.shuttingDown || retried.length === 0) return;
+        void this.#runBeside(this.#ensureSsrEntries(retried, { crashRetry: true })).catch(
+          this.#slowLaneFailed("ssr-crash-retry"),
+        );
+      },
+      Math.max(0, crashedAt + IncrementalBuilder.#crashRetryMs - Date.now()),
+    );
+    timer.unref?.();
+    this.#crashRetryTimer = timer;
+  }
+
+  //* The boot build of the SSR registry runs beside the slow lane, holding only the SSR lock: the first page's route
+  //* build bundles meanwhile instead of queueing behind it (on apps/akan it cost the first page about a second).
+  async armSsrRegistry(): Promise<void> {
+    //? `AKAN_DEV_SSR_ARM_DELAY_MS` is a test hook: an E2E has a tab reconnect before the boot build has run.
+    const delayMs = Number(process.env.AKAN_DEV_SSR_ARM_DELAY_MS);
+    if (Number.isInteger(delayMs) && delayMs > 0) await Bun.sleep(delayMs);
+    const arm = async () =>
+      await this.#withSsrLock(async () => {
+        const generation = this.#generation;
+        if (this.#ssrPatcher && !(await this.#runSsrPatcher(this.#ssrPatcher, [], { batchGeneration: generation })))
+          return;
+        await this.#runSsrWorker(generation);
+      }).catch((err: unknown) => {
+        this.#logger.error(
+          `ssr-registry boot build failed; the next save retries it: ${ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot)}`,
+        );
+      });
+    const arming = this.#runBeside(
+      (async () => {
+        await arm();
+        //? A boot build whose worker was killed (a small container's OOM) is tried once more before `boot-armed` lets
+        //? the next app boot: retried after that, the two biggest workers of a boot would run side by side.
+        const crashedAt = this.#ssrCrashedAt;
+        if (crashedAt === null) return;
+        while (!this.shuttingDown && Date.now() < crashedAt + IncrementalBuilder.#crashRetryMs) await Bun.sleep(250);
+        if (!this.shuttingDown) await arm();
+      })(),
+    );
+    this.#ssrArming = arming;
+    await arming;
+    this.#ssrArming = null;
+  }
+
+  //? A save the user broke fails the same way in a worker, so it is reported here and the patcher keeps its state: the
+  //? modules it could not compile stay pending in the graph and the fixing save compiles them.
+  static #isCompileError(error: unknown): boolean {
+    return error instanceof AggregateError;
+  }
+
+  // Voided so the fast lane need not wait; unhandled, a rejection would exit the builder and drop the watcher with it.
+  #slowLaneFailed(label: string) {
+    return (error: unknown) =>
+      this.#logger.error(
+        `${label} failed in the slow lane: ${ApplicationBuildReporter.formatError(error, this.#app.workspace.workspaceRoot)}`,
+      );
+  }
+
+  // A reason's own detail (which import) follows its first colon, so saves of one kind count together.
+  #countDelegation(registry: "csr" | "ssr", reason: string): string {
+    const key = `${registry}:${reason.split(":")[0]}`;
+    const count = (this.#delegations.get(key) ?? 0) + 1;
+    this.#delegations.set(key, count);
+    return `#${count} for this reason`;
+  }
+
+  async #withSsrLock<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.#ssrLock.then(fn, fn);
+    this.#ssrLock = run.then(
+      () => undefined,
+      () => undefined,
     );
+    return await run;
+  }
+
+  // Runs the worker directly, under the SSR lock its callers hold: queueing it could wait on a batch that waits on them.
+  async #runSsrWorker(generation: number): Promise<void> {
+    let result: BuildBatchResult;
+    try {
+      result = await this.#runBatch({ generation, needs: ["ssr"], changedFiles: [] });
+    } finally {
+      this.#ssrPatcher?.forget();
+    }
+    this.#noteSsrWorker(result);
+    if (result.errors.ssr) throw new Error(result.errors.ssr);
+  }
+
+  #noteSsrWorker(result: BuildBatchResult): void {
+    const crashed = !!result.crashed && (result.crashedNeeds ?? ["ssr"]).includes("ssr");
+    this.#ssrBroken = !!result.errors.ssr && !crashed;
+    this.#ssrCrashedAt = crashed ? Date.now() : null;
+  }
+
+  async #runSsrPatcher(
+    patcher: CsrDevPatcher,
+    files: string[],
+    {
+      roots,
+      onlyRoots,
+      trace,
+      hold,
+      batchGeneration,
+    }: { roots?: string[]; onlyRoots?: boolean; trace?: HmrTrace; hold?: boolean; batchGeneration?: number } = {},
+  ): Promise<boolean> {
+    const started = Date.now();
+    const marker = path.join(this.#ssrBundler.outDir, CSR_DEV_PATCHING_MARKER);
+    await Bun.write(marker, String(process.pid));
+    try {
+      const result = await patcher.update(files, {
+        roots,
+        onlyRoots,
+        announce: (update) => {
+          const now = Date.now();
+          BuilderChannel.emit({
+            type: "ssr-updated",
+            data: {
+              generation: update.generation,
+              reload: update.reload,
+              reason: update.reason,
+              patchUrl: update.patchUrl,
+              changedIds: update.changedIds,
+              ...(trace ? { trace: { ...trace, patchAt: now, sentAt: now } } : {}),
+              ...(hold ? { hold } : {}),
+              ...(batchGeneration !== undefined ? { batchGeneration } : {}),
+              ...(update.epoch !== undefined ? { epoch: update.epoch } : {}),
+              ...(update.first ? { first: true } : {}),
+            },
+          });
+        },
+      });
+      if (result.kind === "delegate") {
+        this.#logger.verbose(
+          `ssr-patch handed to a build worker (${this.#countDelegation("ssr", result.reason)}): ${result.reason}`,
+        );
+        return true;
+      }
+      //? A route build's check reports only a failure: it compiles the roots the registry lacks and nothing else, so
+      //? its ok, of the builder's current generation, would read as the fix of a save that broke something else.
+      if (!onlyRoots) {
+        this.#ssrBroken = false;
+        this.#ssrCrashedAt = null;
+        this.#sendBuildStatus("ssr", { generation: batchGeneration, ok: true, files });
+      }
+      this.#logger.verbose(
+        result.kind === "unchanged"
+          ? `ssr-patch unchanged (${Date.now() - started}ms)`
+          : `ssr-patch generation=${result.update.generation} ${result.update.reload ? `reload (${result.update.reason})` : `patch modules=${result.update.changedIds.length}`} (${Date.now() - started}ms)`,
+      );
+      return false;
+    } catch (err) {
+      const message = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+      if (IncrementalBuilder.#isCompileError(err)) {
+        this.#sendBuildStatus("ssr", { generation: batchGeneration, ok: false, files, message });
+        return false;
+      }
+      this.#logger.verbose(`ssr-patch threw; a build worker takes it: ${message}`);
+      patcher.forget();
+      return true;
+    } finally {
+      await rm(marker, { force: true });
+    }
+  }
+
+  async #runQueuedBatch({ discovery, ...work }: BatchJob): Promise<void> {
+    if (discovery) await this.#refreshDiscovery(discovery);
+    //? The slow lane runs in order, so every batch up to this one has had its discovery job.
+    this.#discoveredThrough = Math.max(this.#discoveredThrough, work.generation);
+    // A worker writing ssr-dev must not overlap the boot build, which no longer runs in this lane.
+    //? Forgotten inside the lock: a route build's check waiting on it would patch the old state over the worker's.
+    try {
+      if (work.needs.includes("ssr"))
+        await this.#withSsrLock(async () => {
+          try {
+            this.#noteSsrWorker(await this.#runBatch(work));
+          } finally {
+            this.#ssrPatcher?.forget();
+          }
+        });
+      else await this.#runBatch(work);
+    } finally {
+      if (work.needs.includes("csr")) this.#patcher?.forget();
+    }
+  }
+
+  async #refreshDiscovery({ files, refresh, generation }: DiscoveryJob): Promise<void> {
+    const started = Date.now();
+    if (refresh) this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
+    else this.#discovery.invalidate?.(files);
+    this.#discoveredThrough = Math.max(this.#discoveredThrough, generation);
+    this.#logger.verbose(`client-entry-discovery ${refresh ? "refreshed" : "invalidated"} (${Date.now() - started}ms)`);
+  }
+
+  async #runBatch(work: BatchWork): Promise<BuildBatchResult> {
+    const { generation, needs, changedFiles } = work;
+    const started = Date.now();
+    const result = await this.#batchRunner.run(await this.#batchRequest(work), (msg) => BuilderChannel.emit(msg));
     if (result.optimizedFonts) this.#optimizedFonts = result.optimizedFonts;
     if (result.cssAssets) this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
-    // A worker that died before reporting streamed no build-status of its own, so report one per need
-    // it was given: the generation must go red rather than look like it silently succeeded.
+    // A need the worker died before reporting goes red here instead of looking silently successful.
     if (result.crashed) {
-      // `base` is excluded because it is not a `BuildPhase`: a boot build has no phase board to fail, and
-      // it never travels through here — `#buildBootDeps` runs it and throws into the degraded-boot path.
-      for (const need of needs)
+      const crashedNeeds = result.crashedNeeds ?? needs;
+      //? A worker that died wrote no failure for the roots handed to it: they must not wait on one that never comes.
+      if (crashedNeeds.includes("csr")) this.#patcher?.releaseHandedOver();
+      if (crashedNeeds.includes("ssr")) this.#ssrPatcher?.releaseHandedOver();
+      // `base` is not a `BuildPhase` and never comes through here: `#buildBootDeps` throws into the degraded boot.
+      for (const need of crashedNeeds)
         if (need !== "base")
-          this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
+          this.#sendBuildStatus(need, {
+            generation,
+            ok: false,
+            files: changedFiles,
+            message: `${result.errors[need] ?? "the build worker crashed"}; the next save builds it again`,
+          });
     }
     if (needs.includes("css")) this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
     return result;
   }
 
-  async #batchRequest({
-    generation,
-    needs,
-    changedFiles,
-  }: {
-    generation: number;
-    needs: BuildBatchNeed[];
-    changedFiles: string[];
-  }): Promise<BuildBatchRequest> {
+  async #batchRequest({ generation, needs, changedFiles, trace }: BatchWork): Promise<BuildBatchRequest> {
     return {
       appName: this.#app.name,
       workspaceRoot: this.#app.workspace.workspaceRoot,
@@ -438,6 +822,7 @@ class IncrementalBuilder {
       optimizedFonts: this.#optimizedFonts,
       cssAssets: this.#artifact.cssAssets ?? null,
       artifactDir: path.resolve(this.#artifactDir),
+      ...(trace ? { trace } : {}),
     };
   }
 
@@ -447,32 +832,20 @@ class IncrementalBuilder {
     this.#logger.verbose(`ready (watch=${this.#watch})`);
   }
 
-  /**
-   * After a degraded boot recovers, the backend is still serving the last-good bundle; push a
-   * fresh pages/css state so connected browsers pick up the fixed code without another edit.
-   */
+  // The backend still serves the last-good bundle after a degraded boot; push fresh pages/css without another edit.
   async announceRecoveredState(changedFiles: string[]): Promise<void> {
     const generation = ++this.#generation;
-    await this.#enqueueWork("boot-recovered", async () => {
+    await this.#workQueue.enqueue("boot-recovered", async () => {
       await this.#runBatch({ generation, needs: ["pages", "css"], changedFiles });
     });
   }
 
-  /**
-   * Re-announce the state this builder just booted with, after the host recycled the previous one.
-   *
-   * The backend reads `base-artifact.json` once at boot and never re-reads it, so a pages or css hash
-   * that moved while the builder was being replaced would otherwise leave it pointing at the previous
-   * artifact until the next save. Announced from the boot artifact rather than by rebuilding: the
-   * bundles are already on disk, and spending another ~200MB of bundler arena in a process that was
-   * just recycled to reclaim memory would defeat the purpose. The host suppresses the announcement
-   * when the hashes match, which is the common case, so a clean recycle never reloads a browser.
-   */
+  // The backend reads base-artifact.json once, at its boot. Re-announced from disk rather than rebuilt (this process
+  // was recycled to free bundler memory); the host drops it when hashes match, so a clean recycle reloads nothing.
   async announceBootState(): Promise<void> {
     const generation = ++this.#generation;
     const reason = "builder-recycle" as const;
-    // Awaited rather than emitted: this runs during a recycle, so the host may ask this builder to shut
-    // down at any moment, and "announced boot state" must mean the announcement left the process.
+    // Awaited, not emitted: the host may shut this builder down any moment, so "announced" must mean flushed.
     await BuilderChannel.send({
       type: "pages-updated",
       data: {
@@ -499,51 +872,64 @@ class IncrementalBuilder {
     this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
 
-  /**
-   * Build the dev CSR artifact because a request asked for it, and keep it in sync from now on. The
-   * dev server only serves CSR through the opt-in `/__csr` and `?csr=true` routes — mobile local dev
-   * points a device WebView at the latter — so nothing needs the artifact until one of them is hit.
-   */
+  // On demand: dev serves CSR only via the opt-in `/__csr` and `?csr=true` routes; once built, it rebuilds every save.
   async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
-    await this.#enqueueWork("build-csr", async (): Promise<void> => {
+    //? Armed now, not when the build lands: a save handled meanwhile then patches CSR behind #csrGate instead of skipping.
+    this.#beginCsrArm();
+    this.#csrActive = true;
+    const armed = this.#workQueue.enqueue("build-csr", async (): Promise<void> => {
       const started = Date.now();
-      // Messages are not relayed: an on-demand CSR build is a request/response, and the phase board
-      // never carried a csr status for it before. The error travels in the response below.
-      const result = await this.#batchRunner.run(
-        await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }),
-      );
-      const error = result.errors.csr;
+      let error: string | undefined;
+      try {
+        // Not relayed: an on-demand CSR build is request/response, and its error travels in the response.
+        const result = await this.#batchRunner.run(
+          await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }),
+        );
+        error = result.errors.csr;
+      } catch (err) {
+        error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
+      }
       if (error) {
         this.#logger.error(`csr-build failed: ${error}`);
         await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: false, error });
         return;
       }
-      this.#csrActive = true;
+      this.#csrArmSucceeded = true;
+      this.#patcher?.forget();
       this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
       await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
+    this.#csrGate = this.#armingCsr(armed);
+    await armed;
+  }
+
+  //? Settled by the last of the arming builds in flight, not by each: two requests that both fail would otherwise leave
+  //? CSR on (the second saw the first's optimistic flag as where it started), and the first to finish would let saves
+  //? patch CSR first while the second still builds.
+  #beginCsrArm(): void {
+    if (this.#csrArms === 0) {
+      this.#csrWasActive = this.#csrActive;
+      this.#csrArmSucceeded = false;
+    }
+    this.#csrArms += 1;
+    this.#csrArming = true;
   }
 
-  #shouldRebuildCsr() {
-    return this.#csrActive;
+  #armingCsr(armed: Promise<void>): Promise<void> {
+    const settle = () => {
+      this.#csrArms -= 1;
+      if (this.#csrArms > 0) return;
+      this.#csrArming = false;
+      this.#csrActive = this.#csrWasActive || this.#csrArmSucceeded;
+    };
+    return armed.then(settle, settle);
   }
 
   static #csrArmedByEnv() {
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
 
-  /**
-   * Build the boot artifact in a process that exits afterwards, and keep only the serializable result.
-   *
-   * This runs in a worker for the same reason every other build does, and it was the largest single
-   * holdout: measured on `apps/akan`, `SsrBaseArtifactBuilder.build()` retains **+1143 MB** that
-   * `Bun.gc(true)` cannot touch, which is 65 % of the builder's post-boot RSS. Nothing was lost by
-   * moving it — the builder only ever kept `artifact` and `optimizedFonts`, both plain data, and the
-   * artifact is written to `base-artifact.json` regardless.
-   *
-   * `GraphClientEntryDiscovery.create` stays here because route builds need it live, and it costs
-   * nothing to keep: measured at **0 ms and 0 MB**, because it builds its graph lazily on first use.
-   */
+  // Discovery stays in-process because route builds need it live; it is free at boot, building its graph lazily.
   static async #buildBootDeps(app: App, runner: BuildBatchRunner): Promise<IncrementalBuilderBootDeps> {
     const result = await runner.run({
       appName: app.name,
@@ -552,15 +938,12 @@ class IncrementalBuilder {
       generation: 0,
       needs: ["base"],
       changedFiles: [],
-      // Discovered by the worker: at boot the watcher has no validated keys to seed, and the boot build
-      // globs them itself anyway.
       pageKeys: null,
       optimizedFonts: null,
       cssAssets: null,
       artifactDir: path.resolve(`${app.cwdPath}/.akan/artifact`),
     });
-    // A failed boot build has to throw, not degrade quietly: `main` catches this to enter the degraded
-    // watch mode that keeps the dev server alive until the error is fixed.
+    // Throws rather than degrading quietly: `main` catches it to enter degraded watch mode.
     if (result.errors.base) throw new Error(result.errors.base);
     if (!result.artifact || !result.optimizedFonts)
       throw new Error("boot build reported success without an artifact; the build worker likely died");
@@ -568,40 +951,43 @@ class IncrementalBuilder {
     return { artifact: result.artifact, optimizedFonts: result.optimizedFonts, discovery };
   }
 
-  /**
-   * A session that already armed dev CSR keeps it armed across builder restarts through the env flag,
-   * so the artifact has to be rebuilt for the replacement. Queued after `builder-ready` and run in a
-   * disposable worker rather than inline: a full minified browser-target build of every page costs
-   * ~350MB of bundler arena that an inline build would never give back, and nothing serves CSR until a
-   * `/__csr` or `?csr=true` request arrives anyway.
-   */
+  // The env flag carries an armed CSR session across builder restarts, so the replacement rebuilds it after ready.
   async rearmCsrFromEnv(): Promise<void> {
     if (!IncrementalBuilder.#csrArmedByEnv()) return;
+    this.#beginCsrArm();
     this.#csrActive = true;
-    await this.#enqueueWork("build-csr-rearm", async () => {
+    //? The env keeps CSR armed whatever this build does, as it did before the builder restarted.
+    this.#csrArmSucceeded = true;
+    const rearmed = this.#workQueue.enqueue("build-csr-rearm", async () => {
+      //? Relayed, unlike an on-demand build: a rebuild for a metadata save must reach the CSR tabs as their reload.
       const result = await this.#batchRunner.run(
         await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }),
+        (msg) => BuilderChannel.emit(msg),
       );
+      this.#patcher?.forget();
       if (result.errors.csr) this.#logger.error(`csr-rearm failed: ${result.errors.csr}`);
       else this.#logger.verbose("csr-rearm ok; this session had CSR armed before the builder restarted");
     });
+    this.#csrGate = this.#armingCsr(rearmed);
+    await rearmed.catch((err: unknown) =>
+      this.#logger.error(
+        `csr-rearm failed: ${ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot)}`,
+      ),
+    );
   }
 
-  /**
-   * A compile error in the boot build must not kill the builder: the builder is the dev server's
-   * file watcher, so exiting here leaves nothing to notice the fix. Report the failure, emit
-   * builder-ready so the host keeps the backend serving the last-good artifact, then retry the
-   * boot build on every file change until it succeeds.
-   */
+  // A boot compile error must not kill the builder, the dev server's only file watcher: report it, emit builder-ready
+  // so the backend keeps the last-good artifact, and retry the boot build on every change.
   static #recoverBoot(
     app: App,
     bootError: unknown,
     logger: Logger,
     runner: BuildBatchRunner,
+    initialGeneration: number,
   ): Promise<{ builder: IncrementalBuilder; changedFiles: string[] }> {
     const firstMessage = bootError instanceof Error ? bootError.message : String(bootError);
     logger.error(`boot build failed; entering degraded watch mode until the error is fixed: ${firstMessage}`);
-    let generation = 0;
+    let generation = initialGeneration;
     const sendFailure = (files: string[], message: string) => {
       BuilderChannel.emit({
         type: "build-status",
@@ -610,6 +996,8 @@ class IncrementalBuilder {
     };
     sendFailure([], firstMessage);
     BuilderChannel.emit({ type: "builder-ready" });
+    // Nothing builds until a save fixes the boot, so the next app's boot need not wait for this one.
+    BuilderChannel.emit({ type: "boot-armed" });
     return new Promise((resolve, reject) => {
       void (async () => {
         const roots = await new WatchRootResolver(app).resolve();
@@ -648,8 +1036,7 @@ class IncrementalBuilder {
     const app = AppExecutor.from(workspace, appName);
     const watch = process.env.AKAN_WATCH !== "0";
     let builder: IncrementalBuilder | null = null;
-    // Registered before the boot build so backend requests get an error response (instead of hanging
-    // the backend) while the builder is still booting or recovering from a failed build.
+    // Registered before the boot build so a request during boot or recovery gets an error instead of hanging.
     const bootingError = "builder is recovering from a failed boot build; retry after the build error is fixed";
     const recyclingError = "builder is recycling to release bundler memory; retry after it restarts";
     process.on("message", (msg: BuilderMessage) => {
@@ -662,51 +1049,52 @@ class IncrementalBuilder {
         void builder.shutdown(msg.reason);
         return;
       }
-      if (msg.type === "build-route") {
+      if (msg.type !== "build-route" && msg.type !== "build-csr") return;
+      if (!builder || builder.shuttingDown) {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-route-res", id: msg.id, ok: false, error });
-          return;
-        }
-        void builder.handleBuildRoute(msg);
+        BuilderChannel.emit({ type: `${msg.type}-res`, id: msg.id, ok: false, error });
         return;
       }
-      if (msg.type === "build-csr") {
-        const error = builder?.shuttingDown ? recyclingError : bootingError;
-        if (!builder || builder.shuttingDown) {
-          BuilderChannel.emit({ type: "build-csr-res", id: msg.id, ok: false, error });
-          return;
-        }
-        void builder.handleBuildCsr(msg);
-      }
+      const handled = msg.type === "build-route" ? builder.handleBuildRoute(msg) : builder.handleBuildCsr(msg);
+      // Unhandled, a rejection (an ipc write that failed) would exit the builder and drop the watcher with it.
+      void handled.catch((err: unknown) =>
+        logger.error(`${msg.type} failed: ${err instanceof Error ? err.message : String(err)}`),
+      );
     });
-    // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
-    // as an orphaned watcher that keeps rebuilding for nobody. Nothing is drained here on purpose —
-    // there is no longer anyone on the other end to flush to.
+    // Closes when the host dies (even by SIGKILL): nothing left to drain, and an orphan would rebuild for nobody.
     process.on("disconnect", () => {
       logger.warn("host IPC channel closed; exiting builder");
       process.exit(0);
     });
     let recoveredFiles: string[] | null = null;
-    // Owned by `main` rather than the instance: the boot build has to run before an instance exists, and
-    // a degraded boot re-runs it once per file change until it succeeds.
     const bootRunner = new BuildBatchRunner({ workspaceRoot, cwd: app.cwdPath });
+    const initialGeneration = IncrementalBuilder.#initialGeneration();
     try {
-      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app, bootRunner)) });
+      const deps = await IncrementalBuilder.#buildBootDeps(app, bootRunner);
+      builder = new IncrementalBuilder({ app, watch, initialGeneration, ...deps });
     } catch (err) {
       if (!watch) throw err;
-      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger, bootRunner);
+      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger, bootRunner, initialGeneration);
       builder = recovered.builder;
       recoveredFiles = recovered.changedFiles;
     }
     await builder.boot();
     if (recoveredFiles) await builder.announceRecoveredState(recoveredFiles);
     else if (process.env.AKAN_BUILDER_ANNOUNCE_BOOT === "1") await builder.announceBootState();
-    await builder.rearmCsrFromEnv();
+    await Promise.all([builder.rearmCsrFromEnv(), builder.armSsrRegistry()]);
+    BuilderChannel.emit({ type: "boot-armed" });
+  }
+
+  //? A replacement builder continues past the host's last generation: from 0, the save fixing an error read older than
+  //? the failure the tabs hold, and from that generation itself its arming builds' ok did not read as the fix either.
+  static #initialGeneration(): number {
+    const generation = Number(process.env.AKAN_BUILDER_INITIAL_GENERATION);
+    return Number.isInteger(generation) && generation > 0 ? generation + 1 : 0;
   }
 }
 
-void IncrementalBuilder.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 IncrementalBuilder.main().catch((err) => {
   console.error(err);
   process.exit(1);
 });