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

package/frontendBuild/sourceMtimeIndex.ts

@@ -0,0 +1,326 @@
+import type { Dirent, Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { HmrChangeClassifier } from "./hmrChangeClassifier";
+
+interface TrackedFile {
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * A directory the index could not read, held with this mtime so every subsequent scan sees a mismatch
+ * and retries it. `NaN !== NaN`, which is exactly the "always stale" semantics wanted here.
+ */
+const UNREADABLE = Number.NaN;
+
+export interface SourceMtimeIndexOptions {
+  roots: string[];
+  classifier?: HmrChangeClassifier;
+}
+
+/**
+ * A snapshot of every interesting source file's mtime under the watch roots, so the watcher can answer
+ * "what actually changed" without trusting `fs.watch` event payloads.
+ *
+ * Bun 1.3.14's recursive `fs.watch` on macOS reports roughly **one path per ~200ms coalescing window**
+ * and discards every other path changed in that window. Measured on this repo: saving 5 files together
+ * reports 1; saving 20 reports 2; a single unrelated write landing first in the window hides a
+ * concurrent save entirely. Node 22 reports all 20 on the same tree, so this is a Bun defect rather
+ * than an FSEvents limitation (`local/optimize-resource/06-watcher-dropped-event.md`).
+ *
+ * Re-stating the tracked set costs ~15ms against ~1300 source files here, where a fresh walk costs
+ * ~70ms — the walk has to visit ~40k entries (`ios/`, `android/`, `public/`) to find those 1300. So
+ * changes are found by re-stating known files plus re-reading only the directories whose own mtime
+ * moved, which is what adding or removing an entry bumps.
+ */
+export class SourceMtimeIndex {
+  readonly #roots: string[];
+  readonly #classifier: HmrChangeClassifier;
+  readonly #files = new Map<string, TrackedFile>();
+  readonly #dirs = new Map<string, number>();
+  readonly #unreadable = new Map<string, string>();
+  #primed = false;
+  #queue: Promise<unknown> = Promise.resolve();
+
+  constructor({ roots, classifier }: SourceMtimeIndexOptions) {
+    this.#roots = SourceMtimeIndex.#pruneNestedRoots(roots);
+    this.#classifier = classifier ?? new HmrChangeClassifier();
+  }
+
+  get primed(): boolean {
+    return this.#primed;
+  }
+
+  get trackedFileCount(): number {
+    return this.#files.size;
+  }
+
+  /**
+   * Paths the index currently cannot read, as `{ path, code }`. Non-empty means change detection has a
+   * blind spot right now: anything edited underneath one of these is not reported until it recovers.
+   *
+   * Worth surfacing rather than swallowing, because the failure is silent by nature — a walk cannot tell
+   * how much it did not see. Each entry is retried on every scan and clears itself on success.
+   */
+  get coverageGaps(): { path: string; code: string }[] {
+    return [...this.#unreadable].map(([file, code]) => ({ path: file, code }));
+  }
+
+  /** Record the current state as the baseline. Reports nothing; call before the first `collectChanges`. */
+  async prime(): Promise<void> {
+    await this.#serialize(async () => {
+      this.#files.clear();
+      this.#dirs.clear();
+      this.#unreadable.clear();
+      await Promise.all(this.#roots.map((root) => this.#walk(root, null)));
+      this.#primed = true;
+    });
+  }
+
+  /**
+   * Absolute paths whose content changed (or which disappeared) since the last call, with the baseline
+   * advanced to match. Returns an empty list until primed, so a failed prime degrades to watcher events
+   * rather than reporting the entire tree as changed.
+   */
+  async collectChanges(): Promise<string[]> {
+    return this.#serialize(async () => {
+      if (!this.#primed) return [];
+      const changed = new Set<string>();
+      await this.#collectFileChanges(changed);
+      await this.#collectDirChanges(changed);
+      return [...changed];
+    });
+  }
+
+  /**
+   * Every scan runs to completion before the next begins.
+   *
+   * Overlapping scans corrupt each other rather than merely racing: one advances the baseline and prunes
+   * entries while the other is midway through a key snapshot it took earlier, so a path the first has
+   * already accounted for reads back as missing and is reported as a change that never happened. Observed
+   * directly — a file nothing had written was reported, which downstream is a wasted rebuild.
+   */
+  async #serialize<T>(work: () => Promise<T>): Promise<T> {
+    const run = this.#queue.then(work, work);
+    // Swallowed on the chain only; the caller still sees the rejection through `run`.
+    this.#queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /**
+   * Adopt writes the caller made itself — regenerated barrels, inserted imports — into the baseline so
+   * the next `collectChanges` does not report them as a user edit.
+   *
+   * Narrow race worth knowing: a user save of the same path landing between the caller's write and this
+   * call is baselined too, and therefore lost. It is sub-millisecond and no wider than the window the
+   * event-based watcher already had.
+   */
+  async absorb(paths: string[]): Promise<void> {
+    await this.#serialize(async () => {
+      if (!this.#primed) return;
+      await Promise.all(
+        paths.map(async (file) => {
+          const abs = path.resolve(file);
+          const stats = await stat(abs).catch(() => null);
+          if (!stats?.isFile()) {
+            this.#files.delete(abs);
+            return;
+          }
+          this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        }),
+      );
+    });
+  }
+
+  async #collectFileChanges(changed: Set<string>): Promise<void> {
+    await Promise.all(
+      [...this.#files.keys()].map(async (abs) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+        if (!stats) {
+          // Unreadable is not deleted. Dropping it here would both invent a change nobody made and stop
+          // tracking the file, so a later real edit would go unreported.
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+            return;
+          }
+          this.#files.delete(abs);
+          this.#unreadable.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        this.#unreadable.delete(abs);
+        if (!stats.isFile()) {
+          this.#files.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        const known = this.#files.get(abs);
+        if (known && known.mtimeMs === stats.mtimeMs && known.size === stats.size) return;
+        this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        changed.add(abs);
+      }),
+    );
+  }
+
+  /**
+   * A directory's own mtime moves when an entry is added or removed but not when a tracked file's
+   * content changes, so this finds creations and deletions the file pass cannot see.
+   */
+  async #collectDirChanges(changed: Set<string>): Promise<void> {
+    const moved: string[] = [];
+    const gone: string[] = [];
+    await Promise.all(
+      [...this.#dirs.entries()].map(async ([dir, mtimeMs]) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(dir);
+        if (!stats?.isDirectory()) {
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#markUnreadable(dir, err);
+            return;
+          }
+          gone.push(dir);
+          return;
+        }
+        // `UNREADABLE` is NaN, so a directory retained from a failed read always mismatches and is
+        // rewalked here — that retry is what lets a transient failure recover on its own.
+        if (stats.mtimeMs !== mtimeMs) moved.push(dir);
+      }),
+    );
+    for (const dir of gone) this.#forget(dir);
+    // Sequential: a moved directory can reveal a new subtree, and walking those in order keeps the
+    // number of concurrent `readdir` calls proportional to the change rather than to the tree.
+    for (const dir of moved) await this.#walk(dir, changed);
+  }
+
+  /**
+   * Re-read one directory, tracking entries that are new or changed. Recurses only into subdirectories
+   * that are new to the index; known ones are covered by their own mtime check in `#collectDirChanges`.
+   */
+  async #walk(dir: string, changed: Set<string> | null): Promise<void> {
+    const [listing, dirStat] = await Promise.all([SourceMtimeIndex.#readdirPath(dir), SourceMtimeIndex.#statPath(dir)]);
+    const entries = listing.entries;
+    const dirStats = dirStat.stats;
+    if (!entries || !dirStats?.isDirectory()) {
+      // A directory that cannot be read is not a directory that is gone. Forgetting it here is
+      // unrecoverable: nothing re-stats a dir the index has dropped, and the parent's own mtime does not
+      // move when a child merely becomes unreadable, so the whole subtree stays invisible for the life of
+      // the process. Measured: one `EACCES` at prime silently hid 2 of 3 files, permanently.
+      const err = listing.err ?? dirStat.err;
+      if (err && !SourceMtimeIndex.#isMissing(err)) {
+        this.#markUnreadable(dir, err);
+        return;
+      }
+      this.#forget(dir);
+      return;
+    }
+    const known = this.#dirs.has(dir);
+    this.#dirs.set(dir, dirStats.mtimeMs);
+    this.#unreadable.delete(dir);
+    const descend: string[] = [];
+    const present = new Set<string>();
+    let blind = false;
+    for (const entry of entries) {
+      if (SourceMtimeIndex.#skipDirent(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        descend.push(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (this.#classifier.classify(abs) === "ignore") continue;
+      present.add(abs);
+      const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+      if (!stats?.isFile()) {
+        // A file listed but not stat-able has no baseline, so an edit to it would compare against nothing.
+        // Leaving the directory stale is what brings it back; the file pass cannot, since it only revisits
+        // paths already tracked.
+        if (err && !SourceMtimeIndex.#isMissing(err)) {
+          this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+          blind = true;
+        }
+        continue;
+      }
+      this.#unreadable.delete(abs);
+      const previous = this.#files.get(abs);
+      if (previous && previous.mtimeMs === stats.mtimeMs && previous.size === stats.size) continue;
+      this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+      changed?.add(abs);
+    }
+    // Entries this directory used to hold and no longer does. Only worth scanning for a directory the
+    // index already knew, which during `prime` is none of them.
+    if (known) {
+      for (const abs of [...this.#files.keys()]) {
+        if (present.has(abs) || path.dirname(abs) !== dir) continue;
+        this.#files.delete(abs);
+        changed?.add(abs);
+      }
+    }
+    if (blind) this.#dirs.set(dir, UNREADABLE);
+    // Known subdirectories carry their own mtime check, so only unseen ones need walking. Concurrent
+    // because `prime` reaches every directory through here.
+    await Promise.all(descend.filter((sub) => !this.#dirs.has(sub)).map((sub) => this.#walk(sub, changed)));
+  }
+
+  /**
+   * Keep a directory the index could not read, flagged for retry on every scan, and keep whatever it
+   * already knows underneath it — those files stay tracked so a real edit is still caught the moment
+   * access returns.
+   */
+  #markUnreadable(dir: string, err: NodeJS.ErrnoException): void {
+    this.#dirs.set(dir, UNREADABLE);
+    this.#unreadable.set(dir, err.code ?? "EUNKNOWN");
+  }
+
+  /** Drop a directory and everything the index holds beneath it. */
+  #forget(dir: string): void {
+    const prefix = `${dir}${path.sep}`;
+    this.#dirs.delete(dir);
+    this.#unreadable.delete(dir);
+    for (const known of [...this.#dirs.keys()]) if (known.startsWith(prefix)) this.#dirs.delete(known);
+    // Otherwise a gap under a deleted directory is reported forever, since nothing revisits it to clear.
+    for (const known of [...this.#unreadable.keys()]) if (known.startsWith(prefix)) this.#unreadable.delete(known);
+  }
+
+  /** `null` stats with the errno kept, so callers can tell "not there" from "could not look". */
+  static async #statPath(abs: string): Promise<{ stats: Stats | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { stats: await stat(abs), err: null };
+    } catch (err) {
+      return { stats: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  static async #readdirPath(dir: string): Promise<{ entries: Dirent[] | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { entries: await readdir(dir, { withFileTypes: true }), err: null };
+    } catch (err) {
+      return { entries: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  /**
+   * Whether an errno means the path genuinely is not there, which is the only case where dropping it from
+   * the baseline is right. Everything else — `EACCES`, `EIO`, `EMFILE`, a stalled network mount — means the
+   * index failed to look, and treating that as a deletion both invents a change and blinds it to real ones.
+   */
+  static #isMissing(err: NodeJS.ErrnoException): boolean {
+    return err.code === "ENOENT" || err.code === "ENOTDIR";
+  }
+
+  /**
+   * Mirrors `HmrChangeClassifier`'s path rules for directory names — dotted names cover `.git` and
+   * `.akan`, which is where every build artifact lands. Symlinked entries are neither `isFile` nor
+   * `isDirectory` and so are skipped, matching `fs.watch`, which does not follow them either.
+   */
+  static #skipDirent(name: string): boolean {
+    return !name || name.startsWith(".") || name === "node_modules";
+  }
+
+  /** `WatchRootResolver` can return `apps/<app>/page` alongside `apps/`; walking both doubles the work. */
+  static #pruneNestedRoots(roots: string[]): string[] {
+    const resolved = [...new Set(roots.map((root) => path.resolve(root)))].sort();
+    return resolved.filter(
+      (root) => !resolved.some((other) => other !== root && root.startsWith(`${other}${path.sep}`)),
+    );
+  }
+}

package/incrementalBuilder/builderReply.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { BuilderReply } from "./builderReply";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+/**
+ * Run a child that answers a build request and exits immediately — the shape of the recycle drain
+ * finishing its last work item — and report whatever the parent actually received.
+ */
+const replyThenExit = async (
+  bytes: number,
+  { awaitFlush }: { awaitFlush: boolean },
+): Promise<{ id?: number } | null> => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "builder-reply-"));
+  tempDirs.push(dir);
+  const entry = path.join(dir, "child.ts");
+  const modulePath = JSON.stringify(path.join(import.meta.dir, "builderReply"));
+  const reply = awaitFlush ? "await BuilderReply.send(res as never);" : "process.send?.(res);";
+  await Bun.write(
+    entry,
+    [
+      `import { BuilderReply } from ${modulePath};`,
+      'const chunk = "x".repeat(200);',
+      "const moduleMap: Record<string, string> = {};",
+      `for (let i = 0; i * 210 < ${bytes}; i++) moduleMap["chunk-" + i] = chunk;`,
+      'const res = { type: "build-route-res", id: 7, ok: true, data: { ssrManifestDelta: moduleMap } };',
+      reply,
+      "process.exit(0);",
+    ].join("\n"),
+  );
+  let received: { id?: number } | null = null;
+  const proc = Bun.spawn(["bun", entry], {
+    stdio: ["ignore", "inherit", "inherit"],
+    serialization: "advanced",
+    ipc: (message) => {
+      received = message as { id?: number };
+    },
+  });
+  await proc.exited;
+  // Replies land before the exit callback, never after, but leave room for a straggler to prove it.
+  await Bun.sleep(50);
+  return received;
+};
+
+describe("BuilderReply.send", () => {
+  test("delivers a reply too large for the pipe buffer before the process exits", async () => {
+    expect(await replyThenExit(1_000_000, { awaitFlush: true })).toMatchObject({ id: 7 });
+    // A manifest delta is usually well past the buffer, but the small case must keep working too.
+    expect(await replyThenExit(0, { awaitFlush: true })).toMatchObject({ id: 7 });
+  });
+
+  test("without the flush wait the same reply is lost, which is why this class exists", async () => {
+    // A control, not a requirement: if a future bun flushes ipc writes on exit, this fails and says so.
+    expect(await replyThenExit(1_000_000, { awaitFlush: false })).toBeNull();
+  });
+
+  test("resolves instead of hanging when there is no ipc channel", async () => {
+    const send = process.send;
+    try {
+      (process as { send?: typeof process.send }).send = undefined;
+      await BuilderReply.send({ type: "build-csr-res", id: 1, ok: true });
+    } finally {
+      (process as { send?: typeof process.send }).send = send;
+    }
+  });
+});

package/incrementalBuilder/builderReply.ts

@@ -0,0 +1,30 @@
+import type { BuilderCsrRes, BuilderRes } from "akanjs/server";
+
+/**
+ * Sends a builder's answer to a backend request and reports when it has actually left the process.
+ *
+ * `process.exit` truncates an ipc write that has not flushed yet, and anything past the pipe buffer
+ * (~64KiB) needs the sender to stay alive to drain it — a `build-route-res` carrying a manifest delta is
+ * routinely larger than that. Measured on bun 1.3: a 100KB reply sent immediately before
+ * `process.exit(0)` was lost 20/20 times, and arrived 20/20 times when the exit waited for the flush
+ * callback. That made the recycle drain, which exists to release bundler memory, eat the answer of
+ * whatever route build it happened to be draining.
+ */
+export class BuilderReply {
+  /** Bound so a runtime that ever stops invoking the callback costs one late reply instead of wedging
+   * the shutdown drain until the host's kill watchdog fires. */
+  static readonly #flushTimeoutMs = 5_000;
+
+  static async send(res: BuilderRes | BuilderCsrRes): Promise<void> {
+    const send = process.send;
+    if (!send) return;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, BuilderReply.#flushTimeoutMs);
+      // A failed send has nothing to retry — the host answers the id itself when this process exits.
+      send.call(process, res, undefined, undefined, () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+}

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;