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

package/akanApp/akanApp.host.ts

@@ -1,9 +1,22 @@
+import { stat } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangePlan, DevChangeRole } from "akanjs/server";
+import type {
+  BuilderMessage,
+  BuilderMetrics,
+  BuildPhase,
+  ChangeBatch,
+  DevBuildStatus,
+  DevChangePlan,
+  DevChangeRole,
+} from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
+// Imported by module path, not through `../frontendBuild`: that barrel pulls in `typescript` and the
+// tailwind stack, which is exactly what a suspended dev host must not be holding.
+import { HmrWatcher } from "../frontendBuild/hmrWatcher";
+import { WatchRootResolver } from "../frontendBuild/watchRootResolver";
 import { IncrementalBuilderHost } from "../incrementalBuilder";
 
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
@@ -17,6 +30,25 @@ const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
+// Save-on-keystroke arrives as a burst of batches. Recycling mid-burst would drop the watcher events
+// still on their way to the builder, so an over-ceiling builder is replaced only once it goes quiet.
+const BUILDER_RSS_RECYCLE_QUIET_MS = 750;
+const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
+const BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT = 2;
+// Linux hands the bundler arenas back on its own after ~10-15s idle — measured at 46-59% of the
+// builder's peak (`local/optimize-resource/09-linux-retention-measurement.md`) — while macOS returns
+// none of it. The builder only reports RSS at work-completion points, so the sample a recycle is armed
+// from is the peak. Waiting out the purge and re-reading before committing is what stops the host
+// paying a cold boot build for memory the OS was about to return anyway. On macOS the re-read returns
+// the same value, so this only ever costs the delay.
+const BUILDER_RSS_SETTLE_MS = 20_000;
+// Far enough above the ceiling that no purge would rescue it; recycle without waiting.
+const BUILDER_RSS_HARD_MULTIPLE = 1.5;
+// A sandbox between user turns pays for a watcher that is watching nothing change. Suspending build
+// capacity after this long returns the builder's residency until the next edit or route request.
+const DEV_IDLE_SUSPEND_MS = 300_000;
+// A wake that immediately suspends again would flap around whatever woke it.
+const DEV_IDLE_MIN_UPTIME_MS = 30_000;
 // The builder is the file watcher: while it is down no edit can trigger a retry, so unlike the
 // backend the recovery loop never gives up — it only backs off.
 const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
@@ -177,6 +209,152 @@ export const hasBuildFailureForGeneration = (
   return false;
 };
 
+export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
+
+/**
+ * Whether an over-ceiling builder should be replaced now.
+ *
+ * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
+ * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
+ * cases where a recycle cannot help are excluded: a generation whose build already failed (the
+ * replacement would hit the same compile error), and a recycle so soon after the last one that the
+ * ceiling is evidently unreachable for this app.
+ */
+export const decideBuilderRssRecycle = ({
+  rssBytes,
+  ceilingBytes,
+  buildFailed,
+  msSinceLastRecycle,
+  minIntervalMs = BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+}: {
+  rssBytes: number;
+  ceilingBytes: number | null;
+  buildFailed: boolean;
+  msSinceLastRecycle: number | null;
+  minIntervalMs?: number;
+}): BuilderRssRecycleDecision => {
+  if (!ceilingBytes) return "unbounded";
+  if (rssBytes < ceilingBytes) return "below-ceiling";
+  if (buildFailed) return "build-failed";
+  if (msSinceLastRecycle !== null && msSinceLastRecycle < minIntervalMs) return "too-soon";
+  return "recycle";
+};
+
+export type BuilderRssSettleDecision = "recycle-now" | "wait-and-recheck";
+
+/**
+ * Whether an armed recycle should wait out the allocator's purge window before committing. A builder
+ * far enough over the ceiling is not going to be rescued by a purge, so waiting there only delays a
+ * recycle that has to happen.
+ */
+export const decideBuilderRssSettle = ({
+  rssBytes,
+  ceilingBytes,
+  hardMultiple = BUILDER_RSS_HARD_MULTIPLE,
+}: {
+  rssBytes: number;
+  ceilingBytes: number;
+  hardMultiple?: number;
+}): BuilderRssSettleDecision => (rssBytes >= ceilingBytes * hardMultiple ? "recycle-now" : "wait-and-recheck");
+
+export type IdleSuspendDecision =
+  | "disabled"
+  | "already-suspended"
+  | "builder-not-ready"
+  | "backend-not-ready"
+  | "build-failed"
+  | "restart-pending"
+  | "too-soon"
+  | "suspend";
+
+/**
+ * Whether the dev host may drop its build capacity now. Every "no" here is a case where suspending
+ * would either lose work or produce a wake that immediately re-suspends:
+ *
+ * - a red build means the developer is mid-fix and about to save again, and a wake would boot straight
+ *   back into the same error via the degraded-boot path
+ * - a pending restart/recovery already has its own plan for the builder
+ * - `too-soon` keeps a wake from flapping around whatever triggered it
+ */
+export const decideIdleSuspend = ({
+  enabled,
+  suspended,
+  builderReady,
+  backendReady,
+  buildFailed,
+  restartPending,
+  msSinceWake,
+  minUptimeMs = DEV_IDLE_MIN_UPTIME_MS,
+}: {
+  enabled: boolean;
+  suspended: boolean;
+  builderReady: boolean;
+  backendReady: boolean;
+  buildFailed: boolean;
+  restartPending: boolean;
+  msSinceWake: number | null;
+  minUptimeMs?: number;
+}): IdleSuspendDecision => {
+  if (!enabled) return "disabled";
+  if (suspended) return "already-suspended";
+  if (!builderReady) return "builder-not-ready";
+  if (!backendReady) return "backend-not-ready";
+  if (buildFailed) return "build-failed";
+  if (restartPending) return "restart-pending";
+  if (msSinceWake !== null && msSinceWake < minUptimeMs) return "too-soon";
+  return "suspend";
+};
+
+/** `undefined` env means the default is on; any non-positive value turns idle suspend off. */
+export const resolveIdleSuspendMs = (raw: string | undefined): number | null => {
+  if (raw === undefined || raw === "") return DEV_IDLE_SUSPEND_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return Math.round(parsed);
+};
+
+/** Any red phase blocks a suspend, unlike the rss recycle which only cares about one generation. */
+export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
+  [...statusByPhase.values()].some((status) => !status.ok);
+
+/**
+ * A config change while suspended cannot be applied by restarting the builder alone — the dev host
+ * itself has to re-read the config, which is the same path an ordinary config save takes.
+ */
+export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
+  !!batch && batch.kinds.has("config");
+
+/**
+ * A builder whose fresh boot already exceeds the ceiling reports `too-soon` after every recycle and
+ * would be replaced forever without ever getting under it. After this many recycles bought no relief
+ * the host stops enforcing the ceiling and says so, rather than looping.
+ */
+export const shouldAbandonBuilderRssCeiling = (
+  ineffectiveRecycles: number,
+  limit = BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT,
+): boolean => ineffectiveRecycles >= limit;
+
+/**
+ * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
+ * already has. Both payload identities are content hashes — `pages-[hash].js` and
+ * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
+ * save that raced the recycle moves them, and that is the case worth pushing.
+ */
+export const shouldRelayRecycledFrontendState = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => {
+  if (!current || current.type !== next.type) return true;
+  if (current.type === "pages-updated" && next.type === "pages-updated")
+    return current.data.bundlePath !== next.data.bundlePath;
+  if (current.type === "css-updated" && next.type === "css-updated")
+    return JSON.stringify(current.data.cssAssets) !== JSON.stringify(next.data.cssAssets);
+  return true;
+};
+
 const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChangePlan | undefined => {
   if (!current) return next;
   if (!next) return current;
@@ -214,7 +392,7 @@ export const buildStatusReplaySequence = (
   latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
 ): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
 
-class BackendImportGraph {
+export class BackendImportGraph {
   readonly #app: App;
   readonly #logger: Logger;
   readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
@@ -222,6 +400,15 @@ class BackendImportGraph {
   readonly #jsTranspiler = new Bun.Transpiler({ loader: "js" });
   readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
   #files = new Set<string>();
+  /**
+   * `refresh()` runs on every server-side save and on every dev-host recycle, and re-reading plus
+   * re-parsing files that did not change is the whole cost of it. Keyed on (mtimeMs, size).
+   *
+   * Specifiers are cached, not resolved paths: creating a file can change what an *unchanged* importer's
+   * specifier resolves to, and `Bun.resolveSync` is cheap next to a read plus a transpiler scan. Only
+   * the scan result is retained — never the source text.
+   */
+  #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
   #ready = false;
   #lastRefreshSucceeded = false;
 
@@ -270,11 +457,10 @@ class BackendImportGraph {
       const current = path.resolve(queue.pop() as string);
       if (files.has(current)) continue;
       if (!this.#isWorkspaceSource(current, workspaceRoot)) continue;
-      if (!(await Bun.file(current).exists())) continue;
+      const imports = await this.#importsOf(current);
+      if (!imports) continue;
 
       files.add(current);
-      const source = await Bun.file(current).text();
-      const imports = this.#scanImports(current, source);
       const importerDir = path.dirname(current);
       for (const imp of imports) {
         if (!GRAPH_IMPORT_KINDS.has(imp.kind) || !imp.path || NON_SOURCE_EXT_RE.test(imp.path)) continue;
@@ -283,9 +469,23 @@ class BackendImportGraph {
         queue.push(resolved);
       }
     }
+    // Files that dropped out of the graph would otherwise be cached for the life of the dev session.
+    for (const cached of this.#scanCache.keys()) if (!files.has(cached)) this.#scanCache.delete(cached);
     return files;
   }
 
+  /** Null when the file is gone, which is the existence check the walk used to make separately. */
+  async #importsOf(file: string): Promise<Bun.Import[] | null> {
+    const stats = await stat(file).catch(() => null);
+    if (!stats?.isFile()) return null;
+    const mtimeMs = Math.round(stats.mtimeMs);
+    const cached = this.#scanCache.get(file);
+    if (cached && cached.mtimeMs === mtimeMs && cached.size === stats.size) return cached.specifiers;
+    const specifiers = this.#scanImports(file, await Bun.file(file).text());
+    this.#scanCache.set(file, { mtimeMs, size: stats.size, specifiers });
+    return specifiers;
+  }
+
   async #entrypoints(): Promise<string[]> {
     const roots = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     const existing: string[] = [];
@@ -344,10 +544,26 @@ export class AkanAppHost {
   #backendBuildStatusGeneration = 0;
   #backendStderrTail: string[] = [];
   #lastGoodFrontend: LastGoodFrontendState = {};
+  #rssRecycleTimer: ReturnType<typeof setTimeout> | null = null;
+  #rssRecycleReason: string | null = null;
+  #lastRssRecycleAtMono: number | null = null;
+  #rssCeilingIneffective = 0;
+  /** Invalidates an in-flight settle check when anything else moves the builder underneath it. */
+  #rssSettleToken = 0;
+  #rssRecycleOver: { rssBytes: number; ceilingBytes: number } | null = null;
+  #rssCeilingAbandoned = false;
   #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
   #pendingBuildStatusReplay: DevBuildStatus[] = [];
   #builderMessageQueue: Promise<void> = Promise.resolve();
   #backendGraph: BackendImportGraph;
+  #idleSuspendTimer: ReturnType<typeof setTimeout> | null = null;
+  #suspended: boolean = false;
+  #waking: boolean = false;
+  #wokeAtMono: number | null = null;
+  #idleWatcher: HmrWatcher | null = null;
+  #suspendedChanges: ChangeBatch | null = null;
+  /** Requests that arrived while suspended, answered by the builder that the wake brings up. */
+  #pendingBuilderMessages: BuilderMessage[] = [];
   constructor(
     private readonly app: App,
     { env, withInk = false }: { env: Record<string, string>; withInk?: boolean },
@@ -366,9 +582,12 @@ export class AkanAppHost {
     ]);
     Object.assign(this.env, { REDIS_HOST: redisHost });
     this.#startBackend();
+    this.#armIdleSuspend();
     return this;
   }
   async stop() {
+    this.#cancelIdleSuspend();
+    this.#stopIdleWatcher();
     if (this.#restartTimer) {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;
@@ -636,22 +855,345 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
+    this.#markDevActivity();
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
       this.#reviveBackendAfterGreenBuild(message.data);
       return;
     }
-    if (message.type === "pages-updated") this.#recordLastGood(message);
-    if (message.type === "css-updated") this.#recordLastGood(message);
+    if (message.type === "builder-metrics") {
+      this.#handleBuilderMetrics(message.data);
+      return;
+    }
+    if (message.type === "pages-updated" || message.type === "css-updated") {
+      const recycled = message.data.reason === "builder-recycle";
+      if (recycled && !this.#shouldRelayRecycledState(message)) return;
+      this.#recordLastGood(message, { supersede: recycled });
+    }
     if (message.type === "invalidate") {
       await this.#handleInvalidate(message);
       return;
     }
     this.#sendToBackend(message);
   }
+  /**
+   * A recycled builder re-announces the artifact it booted with, because the backend read
+   * `base-artifact.json` once and never re-reads it. Dropping the announcement when the hashes match
+   * is what keeps the common case — a recycle with no concurrent edit — invisible to browsers.
+   */
+  #shouldRelayRecycledState(
+    message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+  ): boolean {
+    const current = message.type === "pages-updated" ? this.#lastGoodFrontend.pages : this.#lastGoodFrontend.css;
+    if (shouldRelayRecycledFrontendState(current, message)) {
+      this.logger.verbose(`[builder-recycle] ${message.type} moved during the recycle; pushing it to the backend`);
+      return true;
+    }
+    this.logger.verbose(`[builder-recycle] ${message.type} unchanged after the recycle; backend left as is`);
+    return false;
+  }
+  #handleBuilderMetrics(metrics: BuilderMetrics): void {
+    if (this.#rssCeilingAbandoned) return;
+    const ceilingBytes = IncrementalBuilderHost.maxRssBytes();
+    const asMib = (bytes: number) => Math.round(bytes / 1024 / 1024);
+    const decision = decideBuilderRssRecycle({
+      rssBytes: metrics.rssBytes,
+      ceilingBytes,
+      buildFailed: hasBuildFailureForGeneration(this.#buildStatusByPhase, metrics.generation),
+      msSinceLastRecycle: this.#lastRssRecycleAtMono === null ? null : performance.now() - this.#lastRssRecycleAtMono,
+    });
+    if (decision === "below-ceiling") {
+      this.#rssCeilingIneffective = 0;
+      return;
+    }
+    if (decision === "unbounded") return;
+    if (decision === "build-failed") {
+      this.logger.verbose(
+        `[builder-recycle] deferred: generation=${metrics.generation} has a failing build, so a replacement would hit the same error`,
+      );
+      return;
+    }
+    if (decision === "too-soon") {
+      this.#rssCeilingIneffective += 1;
+      if (!shouldAbandonBuilderRssCeiling(this.#rssCeilingIneffective)) return;
+      this.#rssCeilingAbandoned = true;
+      this.logger.error(
+        `[builder-recycle] the builder is still at ${asMib(metrics.rssBytes)}MiB right after being recycled, so the ${asMib(ceilingBytes ?? 0)}MiB ceiling cannot be met for this app; no longer enforcing it this session. Raise AKAN_BUILDER_MAX_RSS_MB, or set it to 0 to leave the builder unbounded.`,
+      );
+      return;
+    }
+    this.#armRssRecycle(
+      `rss=${asMib(metrics.rssBytes)}MiB>=${asMib(ceilingBytes ?? 0)}MiB after ${metrics.workCount} build(s)`,
+      { rssBytes: metrics.rssBytes, ceilingBytes: ceilingBytes ?? 0 },
+    );
+  }
+  /** Waits for the builder to go quiet, so a recycle never lands in the middle of a burst of saves. */
+  #armRssRecycle(reason: string, over?: { rssBytes: number; ceilingBytes: number }): void {
+    if (this.#rssRecycleReason !== reason)
+      this.logger.verbose(`[builder-recycle] armed (${reason}); replacing the builder once it stays quiet`);
+    this.#rssRecycleReason = reason;
+    // Held in a field, not the closure: `#handleInvalidate` re-arms mid-burst with the reason alone, and
+    // losing the sample there would silently skip the settle check for exactly the bursty case.
+    if (over) this.#rssRecycleOver = over;
+    if (this.#rssRecycleTimer) clearTimeout(this.#rssRecycleTimer);
+    this.#rssRecycleTimer = setTimeout(() => {
+      this.#rssRecycleTimer = null;
+      const pendingReason = this.#rssRecycleReason;
+      const pendingOver = this.#rssRecycleOver;
+      this.#rssRecycleReason = null;
+      this.#rssRecycleOver = null;
+      if (!pendingReason) return;
+      if (!pendingOver) {
+        this.#recycleBuilderForRss(pendingReason);
+        return;
+      }
+      void this.#recycleBuilderForRssWhenStillOver(pendingReason, pendingOver);
+    }, BUILDER_RSS_RECYCLE_QUIET_MS);
+  }
+  /**
+   * Confirms the builder is *still* over the ceiling before replacing it. The armed sample was taken
+   * the instant the builder went idle, which is its peak; where the allocator returns arenas during
+   * idle, that number is stale within seconds and recycling on it is pure cost.
+   */
+  async #recycleBuilderForRssWhenStillOver(
+    reason: string,
+    { rssBytes, ceilingBytes }: { rssBytes: number; ceilingBytes: number },
+  ): Promise<void> {
+    const asMib = (bytes: number) => Math.round(bytes / 1024 / 1024);
+    if (decideBuilderRssSettle({ rssBytes, ceilingBytes }) === "recycle-now") {
+      this.#recycleBuilderForRss(reason);
+      return;
+    }
+    const pid = this.#builder?.pid;
+    // Without a readable pid there is nothing to re-check, so keep the original behaviour.
+    if (!pid) {
+      this.#recycleBuilderForRss(reason);
+      return;
+    }
+    this.#rssSettleToken += 1;
+    const token = this.#rssSettleToken;
+    this.logger.verbose(
+      `[builder-recycle] holding ${Math.round(BUILDER_RSS_SETTLE_MS / 1000)}s to see whether the allocator returns it (${reason})`,
+    );
+    await Bun.sleep(BUILDER_RSS_SETTLE_MS);
+    // Anything that touched the builder meanwhile — a new batch, a recycle, a suspend — invalidates this.
+    if (token !== this.#rssSettleToken || this.#builder?.pid !== pid || this.#suspended || this.#waking) {
+      this.logger.verbose("[builder-recycle] settle check abandoned; the builder moved on");
+      return;
+    }
+    const settledBytes = await AkanAppHost.readProcessRssBytes(pid);
+    if (settledBytes !== null && settledBytes < ceilingBytes) {
+      this.logger.info(
+        `[builder-recycle] skipped: the builder fell to ${asMib(settledBytes)}MiB (ceiling ${asMib(ceilingBytes)}MiB) on its own, so a recycle would have cost a boot build for nothing`,
+      );
+      return;
+    }
+    this.#recycleBuilderForRss(
+      settledBytes === null ? reason : `${reason}; still ${asMib(settledBytes)}MiB after settling`,
+    );
+  }
+  /**
+   * Another process's RSS, read from the OS rather than asked of the process. `/proc` where it exists,
+   * `ps` otherwise (macOS has no `/proc`). Null when it cannot be read, which callers treat as
+   * "no new information" rather than as zero.
+   */
+  static async readProcessRssBytes(pid: number): Promise<number | null> {
+    const status = await Bun.file(`/proc/${pid}/status`)
+      .text()
+      .catch(() => null);
+    const vmRssKb = status === null ? null : /VmRSS:\s+(\d+) kB/.exec(status)?.[1];
+    if (vmRssKb) return Number(vmRssKb) * 1024;
+    const psOutput = await Bun.$`ps -o rss= -p ${pid}`
+      .quiet()
+      .text()
+      .catch(() => "");
+    const rssKb = Number(psOutput.trim());
+    return Number.isFinite(rssKb) && rssKb > 0 ? rssKb * 1024 : null;
+  }
+  #cancelRssRecycle(): void {
+    this.#rssRecycleReason = null;
+    this.#rssRecycleOver = null;
+    // Also drops any settle check already waiting, which would otherwise recycle after the cancel.
+    this.#rssSettleToken += 1;
+    if (!this.#rssRecycleTimer) return;
+    clearTimeout(this.#rssRecycleTimer);
+    this.#rssRecycleTimer = null;
+  }
+  /**
+   * How long the dev server may sit unused before its build capacity is dropped. Set
+   * `AKAN_DEV_IDLE_SUSPEND_MS=0` to keep the builder resident for the whole session.
+   */
+  static idleSuspendMs(): number | null {
+    return resolveIdleSuspendMs(process.env.AKAN_DEV_IDLE_SUSPEND_MS);
+  }
+  /** Every builder message and every request for one counts as the dev server being in use. */
+  #markDevActivity(): void {
+    if (this.#suspended || this.#waking) return;
+    this.#armIdleSuspend();
+  }
+  #armIdleSuspend(): void {
+    const idleMs = AkanAppHost.idleSuspendMs();
+    this.#cancelIdleSuspend();
+    if (idleMs === null) return;
+    this.#idleSuspendTimer = setTimeout(() => {
+      this.#idleSuspendTimer = null;
+      void this.#suspendWhenIdle(idleMs);
+    }, idleMs);
+  }
+  #cancelIdleSuspend(): void {
+    if (!this.#idleSuspendTimer) return;
+    clearTimeout(this.#idleSuspendTimer);
+    this.#idleSuspendTimer = null;
+  }
+  async #suspendWhenIdle(idleMs: number): Promise<void> {
+    const decision = decideIdleSuspend({
+      enabled: true,
+      suspended: this.#suspended,
+      builderReady: this.#builder?.status === "ready",
+      backendReady: this.#backendReady,
+      buildFailed: hasAnyBuildFailure(this.#buildStatusByPhase),
+      restartPending: this.#restartPending,
+      msSinceWake: this.#wokeAtMono === null ? null : performance.now() - this.#wokeAtMono,
+    });
+    if (decision !== "suspend") {
+      this.logger.verbose(`[idle-suspend] skipped (${decision}); re-arming`);
+      this.#armIdleSuspend();
+      return;
+    }
+    // Watch before stopping, never after: an edit landing in the gap would be lost, and nothing
+    // would wake the dev server until the next one.
+    if (!(await this.#startIdleWatcher())) {
+      this.#armIdleSuspend();
+      return;
+    }
+    this.#suspended = true;
+    this.#stopBuilder();
+    this.logger.info(
+      `[idle-suspend] no build activity for ${Math.round(idleMs / 1000)}s; released the builder — the next edit or route request brings it back`,
+    );
+  }
+  get #restartPending(): boolean {
+    return !!(
+      this.#pendingRecycle ||
+      this.#restartTimer ||
+      this.#backendRecoveryTimer ||
+      this.#builderRecoveryTimer ||
+      this.#rssRecycleReason
+    );
+  }
+  async #startIdleWatcher(): Promise<boolean> {
+    try {
+      const roots = await new WatchRootResolver(this.app).resolve();
+      const watcher = new HmrWatcher({
+        roots,
+        logger: this.logger,
+        onBatch: (batch) => {
+          this.#recordSuspendedChange(batch);
+          void this.#wakeFromIdle(`${batch.files.length} file(s) changed`);
+        },
+      });
+      // Awaited so the mtime baseline exists before the first edit: `#recordSuspendedChange` replays this
+      // batch's file list to the woken builder, and a file missing from it is never rebuilt at all.
+      await watcher.start();
+      this.#idleWatcher = watcher;
+      return true;
+    } catch (err) {
+      // Better to keep paying for the builder than to suspend into a dev server that cannot notice edits.
+      this.logger.warn(
+        `[idle-suspend] could not install the idle watcher; staying awake: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      this.#stopIdleWatcher();
+      return false;
+    }
+  }
+  #stopIdleWatcher(): void {
+    this.#idleWatcher?.stop();
+    this.#idleWatcher = null;
+  }
+  #recordSuspendedChange(batch: ChangeBatch): void {
+    const current = this.#suspendedChanges;
+    if (!current) {
+      this.#suspendedChanges = { files: [...batch.files], kinds: new Set(batch.kinds) };
+      return;
+    }
+    this.#suspendedChanges = {
+      files: [...new Set([...current.files, ...batch.files])],
+      kinds: new Set([...current.kinds, ...batch.kinds]),
+    };
+  }
+  /**
+   * Bring build capacity back. Reuses the paths an ordinary change would take, so a change made while
+   * suspended lands the same way it would have while awake.
+   */
+  async #wakeFromIdle(reason: string): Promise<void> {
+    if (!this.#suspended || this.#waking) return;
+    this.#waking = true;
+    this.#cancelIdleSuspend();
+    this.#stopIdleWatcher();
+    const batch = this.#suspendedChanges;
+    this.#suspendedChanges = null;
+    const startedAtMono = performance.now();
+    this.logger.info(`[idle-suspend] waking (${reason})`);
+    try {
+      await this.#applyIdleWake(batch);
+      this.logger.info(`[idle-suspend] awake in ${Math.round(performance.now() - startedAtMono)}ms`);
+    } catch (err) {
+      // Never leave the dev server without a builder: fall back to the ordinary recovery loop, which
+      // keeps retrying, rather than sitting suspended with no watcher.
+      this.logger.error(
+        `[idle-suspend] wake failed; recovering the builder: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      this.#scheduleBuilderRecovery({ files: batch?.files ?? [] });
+    } finally {
+      this.#suspended = false;
+      this.#waking = false;
+      this.#wokeAtMono = performance.now();
+      this.#flushPendingBuilderMessages();
+      this.#armIdleSuspend();
+    }
+  }
+  async #applyIdleWake(batch: ChangeBatch | null): Promise<void> {
+    const files = batch?.files ?? [];
+    if (shouldRefreshConfigOnIdleWake(batch)) {
+      this.logger.verbose("[idle-suspend] config changed while suspended; restarting the dev host");
+      await this.#recycleDevChildren(
+        { type: "invalidate", kinds: [...(batch?.kinds ?? [])], files },
+        {
+          refreshConfig: true,
+        },
+      );
+      return;
+    }
+    // Refresh before deciding: a file created while suspended is not in the graph yet.
+    if (files.length > 0) await this.#backendGraph.refresh();
+    await this.#startBuilder({ announceBootState: true });
+    const backendFiles = files.filter((file) => this.#isBackendFile(file));
+    if (backendFiles.length === 0) return;
+    this.logger.verbose(`[idle-suspend] ${backendFiles.length} backend file(s) changed while suspended`);
+    this.#scheduleBackendRestart({ files: backendFiles, roles: [] });
+  }
+  #flushPendingBuilderMessages(): void {
+    const pending = this.#pendingBuilderMessages.splice(0);
+    if (pending.length === 0) return;
+    this.logger.verbose(`[idle-suspend] replaying ${pending.length} request(s) held during the wake`);
+    for (const message of pending) this.#sendToBuilder(message);
+  }
+  #recycleBuilderForRss(reason: string): void {
+    // A config or runtime-metadata change already replaces the builder along with the backend, and a
+    // pending backend restart is disruption enough on its own; either way, dropping the recycle here
+    // costs nothing — the next build re-reports an over-ceiling rss and arms it again.
+    if (this.#pendingRecycle || this.#restartTimer) {
+      this.logger.verbose(`[builder-recycle] skipped (${reason}); a dev restart is already pending`);
+      return;
+    }
+    if (!this.#builder?.recycle(reason)) return;
+    this.#lastRssRecycleAtMono = performance.now();
+  }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
     this.#logDevPlan(message);
+    // More batches are on the way, so push the recycle out until the dev server settles.
+    if (this.#rssRecycleReason) this.#armRssRecycle(this.#rssRecycleReason);
     // Config changes subsume builder restarts: the dev-host restart recycles builder and backend
     // AND re-runs the prepare step, so check it first when a batch carries both actions.
     const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
@@ -811,18 +1353,25 @@ export class AkanAppHost {
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
   }
+  /**
+   * `supersede` bypasses the generation check for a builder that just replaced another one. Its
+   * generation counter restarts at 0, so its announcement looks stale to `shouldReplaceLastGoodMessage`
+   * — and leaving the old payload cached would make the next backend restart replay an artifact the
+   * builder that produced it no longer serves.
+   */
   #recordLastGood(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+    { supersede = false }: { supersede?: boolean } = {},
   ): void {
     if (message.type === "pages-updated") {
-      if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
+      if (!supersede && !shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
       this.#lastGoodFrontend.pages = message;
       this.logger.verbose(
         `[last-good] pages generation=${message.data.generation ?? "(unknown)"} buildId=${message.data.buildId}`,
       );
       return;
     }
-    if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
+    if (!supersede && !shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
     this.#lastGoodFrontend.css = message;
     this.logger.verbose(
       `[last-good] css generation=${message.data.generation ?? "(unknown)"} assets=${Object.keys(message.data.cssAssets).length}`,
@@ -906,7 +1455,11 @@ export class AkanAppHost {
   #isBackendFile(file: string): boolean {
     return this.#backendGraph.has(file);
   }
-  async #startBuilder(): Promise<IncrementalBuilderHost> {
+  async #startBuilder({
+    announceBootState = false,
+  }: {
+    announceBootState?: boolean;
+  } = {}): Promise<IncrementalBuilderHost> {
     const startTime = Date.now();
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
@@ -915,7 +1468,7 @@ export class AkanAppHost {
         this.#enqueueBuilderMessage(msg);
       });
       try {
-        await this.#waitForBuilderReady(attempt);
+        await this.#waitForBuilderReady(attempt, { announceBootState });
         this.app.verbose(`[cli] base build ready in ${Date.now() - startTime}ms — starting backend`);
         return this.#builder;
       } catch (err) {
@@ -927,7 +1480,10 @@ export class AkanAppHost {
     }
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
-  #waitForBuilderReady(attempt: number): Promise<void> {
+  #waitForBuilderReady(
+    attempt: number,
+    { announceBootState = false }: { announceBootState?: boolean } = {},
+  ): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       if (!this.#builder) throw new Error("Builder Not Found");
       let settled = false;
@@ -941,6 +1497,7 @@ export class AkanAppHost {
         settle(() => reject(new Error("[cli] builder timed out before emitting builder-ready")));
       }, BUILDER_READY_TIMEOUT_MS);
       this.#builder.start({
+        announceBootState,
         onExit: () => {
           settle(() => reject(new Error(`[cli] builder exited before emitting builder-ready (attempt ${attempt})`)));
         },
@@ -955,6 +1512,14 @@ export class AkanAppHost {
     });
   }
   #sendToBuilder(message: BuilderMessage): void {
+    this.#markDevActivity();
+    if (this.#suspended || this.#waking) {
+      // A navigation must not fail just because the sandbox was idle — hold the request and let the
+      // builder the wake brings up answer it.
+      this.#pendingBuilderMessages.push(message);
+      void this.#wakeFromIdle(`${message.type} arrived while suspended`);
+      return;
+    }
     // The builder skips dev CSR artifacts until a `?csr=true` request needs one. Remember that this
     // session armed it and pass the flag through `env`, which is re-read on every builder spawn, so a
     // builder restart re-arms itself instead of silently breaking an in-progress mobile dev session.
@@ -985,6 +1550,7 @@ export class AkanAppHost {
     this.logger.warn("akanAppHost builder is not running");
   }
   #stopBuilder(): void {
+    this.#cancelRssRecycle();
     if (!this.#builder) return;
     this.#builder.stop();
     this.#builder = null;