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

package/{index-77crfweb.js → index-n5y2gbf2.js}

@@ -4,17 +4,21 @@ import {
 } from "./index-76rn3g2c.js";
 import {
   LibraryScript
-} from "./index-pmm9e2jf.js";
+} from "./index-fh990y67.js";
 import {
   runner,
   script
-} from "./index-hdqztm58.js";
+} from "./index-qpz4csbs.js";
 import {
   AppExecutor,
   LibExecutor,
   PkgExecutor,
   WorkspaceExecutor
-} from "./index-a6sbyy0b.js";
+} from "./index-0t7pwff2.js";
+import {
+  HmrWatcher,
+  WatchRootResolver
+} from "./index-0fn1r7gg.js";
 import {
   __require
 } from "./index-r24hmh0q.js";
@@ -69,6 +73,7 @@ import { confirm } from "@inquirer/prompts";
 import { Logger as Logger5 } from "akanjs/common";
 
 // pkgs/@akanjs/devkit/akanApp/akanApp.host.ts
+import { stat } from "fs/promises";
 import path2 from "path";
 import { Logger as Logger3 } from "akanjs/common";
 
@@ -209,6 +214,7 @@ var createTunnel = async (service, { app, environment, port = service === "postg
 // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.host.ts
 import path from "path";
 import { Logger as Logger2 } from "akanjs/common";
+import { MemoryLimit } from "akanjs/server/memoryLimit";
 var builderMsgTypeSet = new Set([
   "build-route-res",
   "build-csr-res",
@@ -216,12 +222,15 @@ var builderMsgTypeSet = new Set([
   "invalidate",
   "css-updated",
   "pages-updated",
-  "build-status"
+  "build-status",
+  "builder-metrics"
 ]);
 
 class IncrementalBuilderHost {
   static #restartBaseDelayMs = 1000;
   static #restartMaxDelayMs = 30000;
+  static #recycleDrainTimeoutMs = 30000;
+  static #devMaxRssBytes = 1200 * 1024 * 1024;
   logger = new Logger2("IncrementalBuilderHost");
   entry;
   env;
@@ -232,7 +241,11 @@ class IncrementalBuilderHost {
   #status = "stopped";
   #restartAttempts = 0;
   #restartTimer = null;
+  #recycleTimer = null;
+  #recycleRequested = false;
+  #spawnAfterRecycle = false;
   #manualStop = false;
+  #inFlight = new Map;
   #startOptions = {};
   constructor({ app, entry, env, onMessage }) {
     this.app = app;
@@ -243,27 +256,35 @@ class IncrementalBuilderHost {
   get status() {
     return this.#status;
   }
+  get pid() {
+    return this.#proc?.pid ?? null;
+  }
   start(options = {}) {
     if (this.#proc)
       this.stop();
     this.#manualStop = false;
     this.#startOptions = options;
+    this.#spawnAfterRecycle = options.announceBootState ?? false;
     this.#spawn(false);
     return this;
   }
   #spawn(isRestart) {
     this.#status = isRestart ? "restarting" : "starting";
     this.ready = false;
+    const afterRecycle = this.#spawnAfterRecycle;
+    this.#spawnAfterRecycle = false;
     let proc;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
-      env: { ...this.env, AKAN_WATCH: "1" },
+      env: { ...this.env, AKAN_WATCH: "1", ...afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {} },
       stdio: ["ignore", "inherit", "inherit"],
       ipc: (msg) => {
         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) {
@@ -282,7 +303,10 @@ class IncrementalBuilderHost {
           return;
         this.#proc = null;
         const wasReady = this.ready;
+        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) {
@@ -290,6 +314,12 @@ class IncrementalBuilderHost {
           this.#startOptions.onExit?.();
           return;
         }
+        if (wasRecycle) {
+          this.logger.verbose("builder exited for a recycle; spawning its replacement now");
+          this.#spawnAfterRecycle = true;
+          this.#spawn(true);
+          return;
+        }
         this.#scheduleRestart();
       }
     });
@@ -311,6 +341,40 @@ class IncrementalBuilderHost {
       this.#spawn(true);
     }, delay);
   }
+  recycle(reason) {
+    if (!this.#proc || this.#status !== "ready" || this.#recycleRequested)
+      return false;
+    const proc = this.#proc;
+    if (!this.send({ type: "builder-shutdown", reason }))
+      return false;
+    this.#recycleRequested = true;
+    this.logger.info(`recycling builder pid=${proc.pid} (${reason})`);
+    this.#recycleTimer = setTimeout(() => {
+      this.#recycleTimer = null;
+      if (this.#proc !== proc)
+        return;
+      this.logger.warn(`builder pid=${proc.pid} did not exit within ${IncrementalBuilderHost.#recycleDrainTimeoutMs}ms of the recycle request; killing it`);
+      proc.kill();
+    }, IncrementalBuilderHost.#recycleDrainTimeoutMs);
+    return true;
+  }
+  #clearRecycle() {
+    this.#recycleRequested = false;
+    if (!this.#recycleTimer)
+      return;
+    clearTimeout(this.#recycleTimer);
+    this.#recycleTimer = null;
+  }
+  static maxRssBytes() {
+    if (process.env.AKAN_BUILDER_MAX_RSS_MB === "0")
+      return null;
+    return MemoryLimit.resolveMaxRssBytes({
+      megabytesEnv: "AKAN_BUILDER_MAX_RSS_MB",
+      bytesEnv: "AKAN_BUILDER_MAX_RSS",
+      limitFraction: 0.35,
+      fallbackBytes: IncrementalBuilderHost.#devMaxRssBytes
+    });
+  }
   send(message) {
     if (!this.#proc || this.#status !== "ready") {
       this.logger.warn(`incrementalBuilderHost is ${this.#status}; cannot send ${message.type}`);
@@ -318,14 +382,31 @@ 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(`failed to send ${message.type} to builder: ${error instanceof Error ? error.message : String(error)}`);
       return false;
     }
   }
+  #failInFlight(reason) {
+    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;
@@ -359,6 +440,13 @@ var BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
+var BUILDER_RSS_RECYCLE_QUIET_MS = 750;
+var BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30000;
+var BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT = 2;
+var BUILDER_RSS_SETTLE_MS = 20000;
+var BUILDER_RSS_HARD_MULTIPLE = 1.5;
+var DEV_IDLE_SUSPEND_MS = 300000;
+var DEV_IDLE_MIN_UPTIME_MS = 30000;
 var BUILDER_RECOVERY_BASE_DELAY_MS = 2000;
 var BUILDER_RECOVERY_MAX_DELAY_MS = 60000;
 var SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -446,6 +534,74 @@ var hasBuildFailureForGeneration = (statusByPhase, generation) => {
   }
   return false;
 };
+var decideBuilderRssRecycle = ({
+  rssBytes,
+  ceilingBytes,
+  buildFailed,
+  msSinceLastRecycle,
+  minIntervalMs = BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS
+}) => {
+  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";
+};
+var decideBuilderRssSettle = ({
+  rssBytes,
+  ceilingBytes,
+  hardMultiple = BUILDER_RSS_HARD_MULTIPLE
+}) => rssBytes >= ceilingBytes * hardMultiple ? "recycle-now" : "wait-and-recheck";
+var decideIdleSuspend = ({
+  enabled,
+  suspended,
+  builderReady,
+  backendReady,
+  buildFailed,
+  restartPending,
+  msSinceWake,
+  minUptimeMs = DEV_IDLE_MIN_UPTIME_MS
+}) => {
+  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";
+};
+var resolveIdleSuspendMs = (raw) => {
+  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);
+};
+var hasAnyBuildFailure = (statusByPhase) => [...statusByPhase.values()].some((status) => !status.ok);
+var shouldRefreshConfigOnIdleWake = (batch) => !!batch && batch.kinds.has("config");
+var shouldAbandonBuilderRssCeiling = (ineffectiveRecycles, limit = BUILDER_INEFFECTIVE_RSS_RECYCLE_LIMIT) => ineffectiveRecycles >= limit;
+var shouldRelayRecycledFrontendState = (current, next) => {
+  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;
+};
 var mergeDevPlans = (current, next) => {
   if (!current)
     return next;
@@ -484,6 +640,7 @@ class BackendImportGraph {
   #jsTranspiler = new Bun.Transpiler({ loader: "js" });
   #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
   #files = new Set;
+  #scanCache = new Map;
   #ready = false;
   #lastRefreshSucceeded = false;
   constructor(app, logger) {
@@ -525,11 +682,10 @@ class BackendImportGraph {
         continue;
       if (!this.#isWorkspaceSource(current, workspaceRoot))
         continue;
-      if (!await Bun.file(current).exists())
+      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 = path2.dirname(current);
       for (const imp of imports) {
         if (!GRAPH_IMPORT_KINDS.has(imp.kind) || !imp.path || NON_SOURCE_EXT_RE.test(imp.path))
@@ -540,8 +696,23 @@ class BackendImportGraph {
         queue.push(resolved);
       }
     }
+    for (const cached of this.#scanCache.keys())
+      if (!files.has(cached))
+        this.#scanCache.delete(cached);
     return files;
   }
+  async#importsOf(file) {
+    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() {
     const roots = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     const existing = [];
@@ -606,10 +777,24 @@ class AkanAppHost {
   #backendBuildStatusGeneration = 0;
   #backendStderrTail = [];
   #lastGoodFrontend = {};
+  #rssRecycleTimer = null;
+  #rssRecycleReason = null;
+  #lastRssRecycleAtMono = null;
+  #rssCeilingIneffective = 0;
+  #rssSettleToken = 0;
+  #rssRecycleOver = null;
+  #rssCeilingAbandoned = false;
   #buildStatusByPhase = new Map;
   #pendingBuildStatusReplay = [];
   #builderMessageQueue = Promise.resolve();
   #backendGraph;
+  #idleSuspendTimer = null;
+  #suspended = false;
+  #waking = false;
+  #wokeAtMono = null;
+  #idleWatcher = null;
+  #suspendedChanges = null;
+  #pendingBuilderMessages = [];
   constructor(app, { env, withInk = false }) {
     this.app = app;
     this.env = env;
@@ -628,9 +813,12 @@ 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;
@@ -895,24 +1083,284 @@ ${this.#backendStderrTail.join(`
     });
   }
   async#handleBuilderMessage(message) {
+    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);
   }
+  #shouldRelayRecycledState(message) {
+    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) {
+    if (this.#rssCeilingAbandoned)
+      return;
+    const ceilingBytes = IncrementalBuilderHost.maxRssBytes();
+    const asMib = (bytes) => 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 });
+  }
+  #armRssRecycle(reason, over) {
+    if (this.#rssRecycleReason !== reason)
+      this.logger.verbose(`[builder-recycle] armed (${reason}); replacing the builder once it stays quiet`);
+    this.#rssRecycleReason = reason;
+    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;
+      }
+      this.#recycleBuilderForRssWhenStillOver(pendingReason, pendingOver);
+    }, BUILDER_RSS_RECYCLE_QUIET_MS);
+  }
+  async#recycleBuilderForRssWhenStillOver(reason, { rssBytes, ceilingBytes }) {
+    const asMib = (bytes) => Math.round(bytes / 1024 / 1024);
+    if (decideBuilderRssSettle({ rssBytes, ceilingBytes }) === "recycle-now") {
+      this.#recycleBuilderForRss(reason);
+      return;
+    }
+    const pid = this.#builder?.pid;
+    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);
+    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`);
+  }
+  static async readProcessRssBytes(pid) {
+    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() {
+    this.#rssRecycleReason = null;
+    this.#rssRecycleOver = null;
+    this.#rssSettleToken += 1;
+    if (!this.#rssRecycleTimer)
+      return;
+    clearTimeout(this.#rssRecycleTimer);
+    this.#rssRecycleTimer = null;
+  }
+  static idleSuspendMs() {
+    return resolveIdleSuspendMs(process.env.AKAN_DEV_IDLE_SUSPEND_MS);
+  }
+  #markDevActivity() {
+    if (this.#suspended || this.#waking)
+      return;
+    this.#armIdleSuspend();
+  }
+  #armIdleSuspend() {
+    const idleMs = AkanAppHost.idleSuspendMs();
+    this.#cancelIdleSuspend();
+    if (idleMs === null)
+      return;
+    this.#idleSuspendTimer = setTimeout(() => {
+      this.#idleSuspendTimer = null;
+      this.#suspendWhenIdle(idleMs);
+    }, idleMs);
+  }
+  #cancelIdleSuspend() {
+    if (!this.#idleSuspendTimer)
+      return;
+    clearTimeout(this.#idleSuspendTimer);
+    this.#idleSuspendTimer = null;
+  }
+  async#suspendWhenIdle(idleMs) {
+    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;
+    }
+    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 \u2014 the next edit or route request brings it back`);
+  }
+  get #restartPending() {
+    return !!(this.#pendingRecycle || this.#restartTimer || this.#backendRecoveryTimer || this.#builderRecoveryTimer || this.#rssRecycleReason);
+  }
+  async#startIdleWatcher() {
+    try {
+      const roots = await new WatchRootResolver(this.app).resolve();
+      const watcher = new HmrWatcher({
+        roots,
+        logger: this.logger,
+        onBatch: (batch) => {
+          this.#recordSuspendedChange(batch);
+          this.#wakeFromIdle(`${batch.files.length} file(s) changed`);
+        }
+      });
+      await watcher.start();
+      this.#idleWatcher = watcher;
+      return true;
+    } catch (err) {
+      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() {
+    this.#idleWatcher?.stop();
+    this.#idleWatcher = null;
+  }
+  #recordSuspendedChange(batch) {
+    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])
+    };
+  }
+  async#wakeFromIdle(reason) {
+    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) {
+      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) {
+    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;
+    }
+    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() {
+    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) {
+    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) {
     this.#logDevPlan(message);
+    if (this.#rssRecycleReason)
+      this.#armRssRecycle(this.#rssRecycleReason);
     const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
     const pending = this.#pendingRecycle;
     if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || pending && message.kinds.includes("code")) {
@@ -1045,15 +1493,15 @@ ${this.#backendStderrTail.join(`
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
   }
-  #recordLastGood(message) {
+  #recordLastGood(message, { supersede = false } = {}) {
     if (message.type === "pages-updated") {
-      if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message))
+      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))
+    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}`);
@@ -1132,7 +1580,9 @@ ${this.#backendStderrTail.join(`
   #isBackendFile(file) {
     return this.#backendGraph.has(file);
   }
-  async#startBuilder() {
+  async#startBuilder({
+    announceBootState = false
+  } = {}) {
     const startTime = Date.now();
     this.app.verbose(`[cli] waiting for builder to complete initial base build\u2026`);
     let lastError;
@@ -1141,7 +1591,7 @@ ${this.#backendStderrTail.join(`
         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 \u2014 starting backend`);
         return this.#builder;
       } catch (err) {
@@ -1154,7 +1604,7 @@ ${this.#backendStderrTail.join(`
     }
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
-  #waitForBuilderReady(attempt) {
+  #waitForBuilderReady(attempt, { announceBootState = false } = {}) {
     return new Promise((resolve, reject) => {
       if (!this.#builder)
         throw new Error("Builder Not Found");
@@ -1170,6 +1620,7 @@ ${this.#backendStderrTail.join(`
         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})`)));
         },
@@ -1184,6 +1635,12 @@ ${this.#backendStderrTail.join(`
     });
   }
   #sendToBuilder(message) {
+    this.#markDevActivity();
+    if (this.#suspended || this.#waking) {
+      this.#pendingBuilderMessages.push(message);
+      this.#wakeFromIdle(`${message.type} arrived while suspended`);
+      return;
+    }
     if (message.type === "build-csr" && this.env.AKAN_DEV_CSR_REBUILD !== "1") {
       Object.assign(this.env, { AKAN_DEV_CSR_REBUILD: "1" });
       this.logger.verbose(`[csr] armed dev CSR rebuilds (${message.reason})`);
@@ -1212,6 +1669,7 @@ ${this.#backendStderrTail.join(`
     this.logger.warn("akanAppHost builder is not running");
   }
   #stopBuilder() {
+    this.#cancelRssRecycle();
     if (!this.#builder)
       return;
     this.#builder.stop();
@@ -1259,9 +1717,9 @@ function openBrowser(url) {
 }
 
 // pkgs/@akanjs/cli/application/application.runner.ts
-var loadBuildRunner = async () => (await import("./applicationBuildRunner-yz144508.js")).ApplicationBuildRunner;
+var loadBuildRunner = async () => (await import("./applicationBuildRunner-5w8j9yp7.js")).ApplicationBuildRunner;
 var loadReleasePackager = async () => (await import("./applicationReleasePackager-brvth6rs.js")).ApplicationReleasePackager;
-var loadCapacitorApp = async () => (await import("./capacitorApp-y0h6cgft.js")).CapacitorApp;
+var loadCapacitorApp = async () => (await import("./capacitorApp-wnxzrppx.js")).CapacitorApp;
 var loadPrompts = async () => await import("@inquirer/prompts");
 
 class ApplicationRunner extends runner("application") {