@akanjs/devkit 2.4.1-rc.3 → 2.4.1-rc.5

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -68,7 +68,7 @@ describe("IncrementalBuilderHost", () => {
 
     host.start({ onRestartReady });
     spawns[0]?.options.ipc?.({ type: "builder-ready" });
-    expect(spawns[0]?.options.env?.AKAN_BUILDER_RECYCLED).toBeUndefined();
+    expect(spawns[0]?.options.env?.AKAN_BUILDER_ANNOUNCE_BOOT).toBeUndefined();
 
     const reason = "rss=1300MiB>=1200MiB after 3 build(s)";
     expect(host.recycle(reason)).toBe(true);
@@ -80,7 +80,7 @@ describe("IncrementalBuilderHost", () => {
     // A planned exit skips the crash backoff — the dev server has no file watcher until it is back.
     spawns[0]?.options.onExit?.();
     expect(spawns).toHaveLength(2);
-    expect(spawns[1]?.options.env?.AKAN_BUILDER_RECYCLED).toBe("1");
+    expect(spawns[1]?.options.env?.AKAN_BUILDER_ANNOUNCE_BOOT).toBe("1");
     spawns[1]?.options.ipc?.({ type: "builder-ready" });
     expect(onRestartReady).toHaveBeenCalledTimes(1);
     expect(host.status).toBe("ready");
@@ -90,11 +90,96 @@ describe("IncrementalBuilderHost", () => {
     expect(spawns).toHaveLength(2);
     await wait(1_050);
     expect(spawns).toHaveLength(3);
-    expect(spawns[2]?.options.env?.AKAN_BUILDER_RECYCLED).toBeUndefined();
+    expect(spawns[2]?.options.env?.AKAN_BUILDER_ANNOUNCE_BOOT).toBeUndefined();
 
     host.stop();
   });
 
+  test("fails the requests a departing builder never answered", async () => {
+    const spawns = mockSpawns();
+    const messages: unknown[] = [];
+    const host = new IncrementalBuilderHost({
+      app: { cwdPath: "/tmp/app" } as never,
+      entry: "/tmp/builder.ts",
+      env: {},
+      onMessage: (message) => messages.push(message),
+    });
+
+    host.start();
+    spawns[0]?.options.ipc?.({ type: "builder-ready" });
+    expect(host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] })).toBe(true);
+    expect(host.send({ type: "build-csr", id: 2, reason: "device webview" })).toBe(true);
+    // Answered before the exit, so this one must not be failed again afterwards.
+    expect(host.send({ type: "build-route", id: 3, routeId: "c", seeds: [], knownEntries: [] })).toBe(true);
+    spawns[0]?.options.ipc?.({ type: "build-route-res", id: 3, ok: true, data: { routeId: "c" } });
+    messages.length = 0;
+
+    host.recycle("rss=1300MiB>=1200MiB after 3 build(s)");
+    spawns[0]?.options.onExit?.();
+
+    // Nothing else answers these: the builder only refuses requests that arrive after it starts shutting
+    // down, and a kill or a truncated write sends nothing at all.
+    expect(messages).toEqual([
+      {
+        type: "build-route-res",
+        id: 1,
+        ok: false,
+        error: "builder exited to release bundler memory before answering; reload to retry",
+      },
+      {
+        type: "build-csr-res",
+        id: 2,
+        ok: false,
+        error: "builder exited to release bundler memory before answering; reload to retry",
+      },
+    ]);
+
+    // The replacement owes nothing, so its own exit stays quiet.
+    spawns[1]?.options.ipc?.({ type: "builder-ready" });
+    messages.length = 0;
+    spawns[1]?.options.onExit?.();
+    expect(messages).toEqual([]);
+    await wait(1_050);
+
+    host.stop();
+  });
+
+  test("names a crash rather than a recycle, and answers on stop too", async () => {
+    const spawns = mockSpawns();
+    const messages: unknown[] = [];
+    const host = new IncrementalBuilderHost({
+      app: { cwdPath: "/tmp/app" } as never,
+      entry: "/tmp/builder.ts",
+      env: {},
+      onMessage: (message) => messages.push(message),
+    });
+
+    host.start();
+    spawns[0]?.options.ipc?.({ type: "builder-ready" });
+    host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] });
+    messages.length = 0;
+    spawns[0]?.options.onExit?.();
+    expect(messages).toEqual([
+      {
+        type: "build-route-res",
+        id: 1,
+        ok: false,
+        error: "builder exited unexpectedly before answering; reload once it is back",
+      },
+    ]);
+
+    // `stop()` clears the process before its exit callback runs, so the callback bails on its identity
+    // check and cannot be the only place this happens.
+    await wait(1_050);
+    spawns[1]?.options.ipc?.({ type: "builder-ready" });
+    messages.length = 0;
+    expect(host.send({ type: "build-route", id: 2, routeId: "b", seeds: [], knownEntries: [] })).toBe(true);
+    host.stop();
+    expect(messages).toEqual([
+      { type: "build-route-res", id: 2, ok: false, error: "builder was stopped before answering" },
+    ]);
+  });
+
   test("only recycles a builder that is ready", () => {
     const spawns = mockSpawns();
     const host = new IncrementalBuilderHost({

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -27,6 +27,11 @@ interface IncrementalBuilderStartOptions {
   onExit?: () => void;
   onReady?: () => void;
   onRestartReady?: () => void;
+  /**
+   * Ask the builder to re-announce the artifact it boots with. Needed whenever a *previous* builder's
+   * artifact may still be live in a running backend — after an rss recycle, and after an idle wake.
+   */
+  announceBootState?: boolean;
 }
 
 export class IncrementalBuilderHost {
@@ -56,6 +61,17 @@ export class IncrementalBuilderHost {
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
   #manualStop = false;
+  /**
+   * Requests handed to the running builder that it has not answered yet, keyed by the backend's
+   * correlation id.
+   *
+   * Nothing else answers a request whose builder exits while holding it: the builder only refuses
+   * requests that arrive *after* it starts shutting down, a kill or crash sends nothing at all, and even
+   * a clean drain races its own `process.exit`. The builder exits routinely — it is recycled whenever its
+   * RSS passes the ceiling — so a page request that happened to be mid route-build left the backend's
+   * promise pending and the browser tab spinning with no error and nothing to retry.
+   */
+  readonly #inFlight = new Map<number, "build-route" | "build-csr">();
   #startOptions: IncrementalBuilderStartOptions = {};
   constructor({ app, entry, env, onMessage }: IncrementalBuilderHostOptions) {
     this.app = app;
@@ -66,28 +82,38 @@ export class IncrementalBuilderHost {
   get status() {
     return this.#status;
   }
+  /**
+   * The running builder's pid, so the host can read its RSS from the OS between builds. The builder
+   * only reports its own metrics at work-completion points, which is the *peak*; on a platform that
+   * returns bundler arenas to the OS while idle, that sample goes stale within seconds.
+   */
+  get pid(): number | null {
+    return this.#proc?.pid ?? null;
+  }
   start(options: IncrementalBuilderStartOptions = {}) {
     if (this.#proc) this.stop();
     this.#manualStop = false;
     this.#startOptions = options;
+    this.#spawnAfterRecycle = options.announceBootState ?? false;
     this.#spawn(false);
     return this;
   }
   #spawn(isRestart: boolean) {
     this.#status = isRestart ? "restarting" : "starting";
     this.ready = false;
-    // A recycled builder rebuilds every artifact, and the running backend still holds the previous
-    // one; the flag is what tells the replacement to re-announce what it booted with.
+    // A fresh builder rebuilds every artifact while the running backend still holds the previous one;
+    // the flag is what tells it to re-announce what it booted with.
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
     let proc!: Bun.Subprocess<"ignore", "inherit", "inherit">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
-      env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_RECYCLED: "1" } : {}) },
+      env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
       stdio: ["ignore", "inherit", "inherit"],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
         if (!msg || typeof msg !== "object") return;
+        if (msg.type === "build-route-res" || msg.type === "build-csr-res") this.#inFlight.delete(msg.id);
         if (builderMsgTypeSet.has(msg.type)) this.#onMessage(msg);
         if (msg.type === "builder-ready" && !this.ready) {
           this.ready = true;
@@ -105,6 +131,11 @@ export class IncrementalBuilderHost {
         const wasRecycle = this.#recycleRequested;
         this.#clearRecycle();
         this.ready = false;
+        this.#failInFlight(
+          wasRecycle
+            ? "builder exited to release bundler memory before answering; reload to retry"
+            : "builder exited unexpectedly before answering; reload once it is back",
+        );
         if (this.#manualStop || this.#status === "stopped") return;
         if (!wasReady) {
           this.#status = "stopped";
@@ -189,6 +220,7 @@ export class IncrementalBuilderHost {
     }
     try {
       this.#proc.send(message);
+      if (message.type === "build-route" || message.type === "build-csr") this.#inFlight.set(message.id, message.type);
       return true;
     } catch (error) {
       this.logger.warn(
@@ -197,9 +229,24 @@ export class IncrementalBuilderHost {
       return false;
     }
   }
+  /**
+   * Answer every request the departing builder still owed, as if it had failed them itself. `onExit`
+   * cannot do this alone: `stop()` clears `#proc` first, so the exit callback bails on its identity check.
+   */
+  #failInFlight(reason: string): void {
+    if (!this.#inFlight.size) return;
+    const lost = [...this.#inFlight];
+    this.#inFlight.clear();
+    this.logger.warn(`failing ${lost.length} unanswered builder request(s): ${reason}`);
+    for (const [id, type] of lost) {
+      if (type === "build-route") this.#onMessage({ type: "build-route-res", id, ok: false, error: reason });
+      else this.#onMessage({ type: "build-csr-res", id, ok: false, error: reason });
+    }
+  }
   stop() {
     this.#manualStop = true;
     this.#clearRecycle();
+    this.#failInFlight("builder was stopped before answering");
     if (this.#restartTimer) {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -12,14 +12,12 @@ import {
   GraphClientEntryDiscovery,
   HmrWatcher,
   RouteClientBuilder,
-  SsrBaseArtifactBuilder,
   WatchRootResolver,
 } from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
   BuilderCsrReq,
-  BuilderCsrRes,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
@@ -28,6 +26,7 @@ import type {
 } from "akanjs/server";
 import type { BuildBatchNeed, BuildBatchRequest, BuildBatchResult, OptimizedFonts } from "./buildBatchProtocol";
 import { BuildBatchRunner } from "./buildBatchRunner";
+import { BuilderChannel } from "./builderChannel";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
 interface IncrementalBuilderOptions {
@@ -53,6 +52,7 @@ class IncrementalBuilder {
   #changePlanner: DevChangePlanner;
   #generatedIndexSync: DevGeneratedIndexSync;
   #autoImportSync: AutoImportSync;
+  #watcher: HmrWatcher | null = null;
   #generation = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #workQueue: Promise<void> = Promise.resolve();
@@ -82,8 +82,14 @@ class IncrementalBuilder {
     return `${this.#app.cwdPath}/.akan/artifact`;
   }
 
-  async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
-    return this.#enqueueWork(`build-route:${msg.routeId}`, async () => this.#handleBuildRoute(msg));
+  /**
+   * 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".
+   */
+  async handleBuildRoute(msg: BuilderReq): Promise<void> {
+    await this.#enqueueWork(`build-route:${msg.routeId}`, async () =>
+      BuilderChannel.send(await this.#handleBuildRoute(msg)),
+    );
   }
 
   async #handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
@@ -125,7 +131,7 @@ class IncrementalBuilder {
     { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
   ): void {
     if (typeof generation !== "number") return;
-    process.send?.({
+    BuilderChannel.emit({
       type: "build-status",
       data: {
         generation,
@@ -163,7 +169,7 @@ class IncrementalBuilder {
    */
   #reportMetrics(): void {
     if (!this.#idle || this.#shuttingDown) return;
-    process.send?.({
+    BuilderChannel.emit({
       type: "builder-metrics",
       data: { rssBytes: process.memoryUsage.rss(), generation: this.#generation, workCount: this.#workCount },
     });
@@ -188,7 +194,14 @@ class IncrementalBuilder {
     }
     await this.#workQueue.catch(() => undefined);
     await this.#cssRebuildQueue.catch(() => undefined);
-    this.#logger.info(`drained in ${Date.now() - started}ms; exiting for recycle`);
+    // 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`.
+    const flushed = await BuilderChannel.drain();
+    this.#logger.info(
+      `drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`,
+    );
     process.exit(0);
   }
 
@@ -260,7 +273,8 @@ class IncrementalBuilder {
         await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(appDir, artifactDir, batch));
       },
     });
-    watcher.start();
+    await watcher.start();
+    this.#watcher = watcher;
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
 
@@ -276,6 +290,10 @@ class IncrementalBuilder {
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
     const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
+    //* 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.
+    await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
     const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
@@ -299,7 +317,7 @@ class IncrementalBuilder {
 
     if (hasSyncErrors) {
       this.#sendBuildStatus("barrel", { generation, ok: false, files, message: indexSync.errors.join("\n") });
-      process.send?.(event);
+      BuilderChannel.emit(event);
       return;
     }
     if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
@@ -335,7 +353,7 @@ class IncrementalBuilder {
       needs.push("css");
     }
 
-    process.send?.(event);
+    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
@@ -362,15 +380,18 @@ class IncrementalBuilder {
   }): Promise<BuildBatchResult> {
     const started = Date.now();
     const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) =>
-      process.send?.(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.
     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)
-        this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
+        if (need !== "base")
+          this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
     }
     if (needs.includes("css")) this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
     return result;
@@ -401,7 +422,7 @@ class IncrementalBuilder {
 
   async boot(): Promise<void> {
     if (this.#watch) await this.installWatcher();
-    process.send?.({ type: "builder-ready" });
+    BuilderChannel.emit({ type: "builder-ready" });
     this.#logger.verbose(`ready (watch=${this.#watch})`);
   }
 
@@ -429,7 +450,9 @@ class IncrementalBuilder {
   async announceBootState(): Promise<void> {
     const generation = ++this.#generation;
     const reason = "builder-recycle" as const;
-    process.send?.({
+    // 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.
+    await BuilderChannel.send({
       type: "pages-updated",
       data: {
         bundlePath: this.#artifact.pagesBundlePath,
@@ -448,7 +471,7 @@ class IncrementalBuilder {
         ]),
       ),
     );
-    process.send?.({
+    await BuilderChannel.send({
       type: "css-updated",
       data: { cssAssets, cssBase64ByUrl, generation, changedFiles: [], reason },
     });
@@ -460,8 +483,8 @@ class IncrementalBuilder {
    * 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.
    */
-  async handleBuildCsr(msg: BuilderCsrReq): Promise<BuilderCsrRes> {
-    return this.#enqueueWork("build-csr", async (): Promise<BuilderCsrRes> => {
+  async handleBuildCsr(msg: BuilderCsrReq): Promise<void> {
+    await this.#enqueueWork("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.
@@ -471,11 +494,12 @@ class IncrementalBuilder {
       const error = result.errors.csr;
       if (error) {
         this.#logger.error(`csr-build failed: ${error}`);
-        return { type: "build-csr-res", id: msg.id, ok: false, error };
+        await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: false, error });
+        return;
       }
       this.#csrActive = true;
       this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
-      return { type: "build-csr-res", id: msg.id, ok: true };
+      await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
 
@@ -487,10 +511,40 @@ class IncrementalBuilder {
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
 
-  static async #buildBootDeps(app: App): Promise<IncrementalBuilderBootDeps> {
-    const { artifact, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
+  /**
+   * 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.
+   */
+  static async #buildBootDeps(app: App, runner: BuildBatchRunner): Promise<IncrementalBuilderBootDeps> {
+    const result = await runner.run({
+      appName: app.name,
+      workspaceRoot: app.workspace.workspaceRoot,
+      repoName: app.workspace.repoName,
+      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.
+    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");
     const discovery = await GraphClientEntryDiscovery.create(app);
-    return { artifact, optimizedFonts, discovery };
+    return { artifact: result.artifact, optimizedFonts: result.optimizedFonts, discovery };
   }
 
   /**
@@ -522,18 +576,19 @@ class IncrementalBuilder {
     app: App,
     bootError: unknown,
     logger: Logger,
+    runner: BuildBatchRunner,
   ): 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;
     const sendFailure = (files: string[], message: string) => {
-      process.send?.({
+      BuilderChannel.emit({
         type: "build-status",
         data: { generation, phase: "pages", ok: false, files, message: `Boot build failed: ${message}` },
       });
     };
     sendFailure([], firstMessage);
-    process.send?.({ type: "builder-ready" });
+    BuilderChannel.emit({ type: "builder-ready" });
     return new Promise((resolve, reject) => {
       void (async () => {
         const roots = await new WatchRootResolver(app).resolve();
@@ -546,7 +601,7 @@ class IncrementalBuilder {
             try {
               // A broken akan.config.ts caches its import failure; re-import it before rebuilding.
               if (new Set(batch.kinds).has("config")) await app.getConfig({ refresh: true });
-              const deps = await IncrementalBuilder.#buildBootDeps(app);
+              const deps = await IncrementalBuilder.#buildBootDeps(app, runner);
               const builder = new IncrementalBuilder({ app, watch: true, initialGeneration: generation, ...deps });
               watcher.stop();
               logger.info(`boot build recovered generation=${generation}`);
@@ -558,7 +613,7 @@ class IncrementalBuilder {
             }
           },
         });
-        watcher.start();
+        await watcher.start();
         logger.warn(`[degraded] watching ${roots.length} roots for a fix`);
       })().catch(reject);
     });
@@ -589,39 +644,43 @@ class IncrementalBuilder {
       if (msg.type === "build-route") {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         if (!builder || builder.shuttingDown) {
-          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error });
+          BuilderChannel.emit({ type: "build-route-res", id: msg.id, ok: false, error });
           return;
         }
-        void builder.handleBuildRoute(msg).then((res) => process.send?.(res));
+        void builder.handleBuildRoute(msg);
         return;
       }
       if (msg.type === "build-csr") {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         if (!builder || builder.shuttingDown) {
-          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error });
+          BuilderChannel.emit({ type: "build-csr-res", id: msg.id, ok: false, error });
           return;
         }
-        void builder.handleBuildCsr(msg).then((res) => process.send?.(res));
+        void builder.handleBuildCsr(msg);
       }
     });
     // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
-    // as an orphaned watcher that keeps rebuilding for nobody.
+    // 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.
     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 });
     try {
-      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app)) });
+      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app, bootRunner)) });
     } catch (err) {
       if (!watch) throw err;
-      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger);
+      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger, bootRunner);
       builder = recovered.builder;
       recoveredFiles = recovered.changedFiles;
     }
     await builder.boot();
     if (recoveredFiles) await builder.announceRecoveredState(recoveredFiles);
-    else if (process.env.AKAN_BUILDER_RECYCLED === "1") await builder.announceBootState();
+    else if (process.env.AKAN_BUILDER_ANNOUNCE_BOOT === "1") await builder.announceBootState();
     await builder.rearmCsrFromEnv();
   }
 }