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

package/akanApp/akanApp.host.ts

@@ -1,9 +1,11 @@
+import { stat } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type {
   BuilderMessage,
   BuilderMetrics,
   BuildPhase,
+  ChangeBatch,
   DevBuildStatus,
   DevChangePlan,
   DevChangeRole,
@@ -11,6 +13,10 @@ import type {
 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"]);
@@ -29,6 +35,20 @@ const BUILDER_START_MAX_ATTEMPTS = 3;
 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;
@@ -220,6 +240,90 @@ export const decideBuilderRssRecycle = ({
   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
@@ -288,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" });
@@ -296,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;
 
@@ -344,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;
@@ -357,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[] = [];
@@ -422,11 +548,22 @@ export class AkanAppHost {
   #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 },
@@ -445,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;
@@ -715,6 +855,7 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
+    this.#markDevActivity();
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
@@ -784,27 +925,260 @@ export class AkanAppHost {
     }
     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): void {
+  #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;
-      if (pendingReason) this.#recycleBuilderForRss(pendingReason);
+      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
@@ -1081,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;
@@ -1090,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) {
@@ -1102,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;
@@ -1116,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})`)));
         },
@@ -1130,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.

package/executors.test.ts

@@ -271,6 +271,66 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  describe("getDevPort", () => {
+    const makeWorkspaceWithApps = async (names: string[]) => {
+      const root = await makeTempRoot();
+      process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+      process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+      process.env.AKAN_PUBLIC_ENV = "local";
+      process.env.PORT_OFFSET = "0";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      for (const name of names) {
+        await mkdir(path.join(root, "apps", name), { recursive: true });
+        await writeFile(path.join(root, "apps", name, "akan.config.ts"), "export default {};\n");
+      }
+      // `AppExecutor.from` memoises by name, so each test needs names no other test has used.
+      return new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+    };
+
+    test("derives the port from the app's position in the sorted apps listing", async () => {
+      const workspace = await makeWorkspaceWithApps(["port-a", "port-b"]);
+
+      expect(await AppExecutor.from(workspace, "port-a").getDevPort()).toBe(8282);
+      expect(await AppExecutor.from(workspace, "port-b").getDevPort()).toBe(8283);
+    });
+
+    test("moves when another app appears before it, which is why pinning exists", async () => {
+      const workspace = await makeWorkspaceWithApps(["drift-b"]);
+      const app = AppExecutor.from(workspace, "drift-b");
+      expect(await app.getDevPort()).toBe(8282);
+
+      // Sorts ahead of `drift-b`, so the same app now answers with a different port — and a dev host
+      // recomputes this on every restart.
+      await mkdir(path.join(workspace.workspaceRoot, "apps/drift-a"), { recursive: true });
+      await writeFile(path.join(workspace.workspaceRoot, "apps/drift-a/akan.config.ts"), "export default {};\n");
+
+      expect(await app.getDevPort()).toBe(8283);
+    });
+
+    test("AKAN_DEV_PORT pins it, and survives an app appearing before it", async () => {
+      const workspace = await makeWorkspaceWithApps(["pin-b"]);
+      const app = AppExecutor.from(workspace, "pin-b");
+      process.env.AKAN_DEV_PORT = "12345";
+
+      expect(await app.getDevPort()).toBe(12345);
+
+      await mkdir(path.join(workspace.workspaceRoot, "apps/pin-a"), { recursive: true });
+      await writeFile(path.join(workspace.workspaceRoot, "apps/pin-a/akan.config.ts"), "export default {};\n");
+
+      expect(await app.getDevPort()).toBe(12345);
+    });
+
+    test("ignores an unusable AKAN_DEV_PORT rather than binding a nonsense port", async () => {
+      const workspace = await makeWorkspaceWithApps(["bad-a"]);
+      const app = AppExecutor.from(workspace, "bad-a");
+
+      for (const value of ["0", "-1", "nope", "", "70000", "8282.5"]) {
+        process.env.AKAN_DEV_PORT = value;
+        expect(await app.getDevPort()).toBe(8282);
+      }
+    });
+  });
+
   test("accepts metadata route exports during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";

package/executors.ts

@@ -1256,7 +1256,18 @@ export class AppExecutor extends SysExecutor {
   getEnv() {
     return WorkspaceExecutor.getBaseDevEnv().env;
   }
+  /**
+   * This app's dev port, derived from its position in the sorted `apps/` listing so several apps can run
+   * at once without colliding.
+   *
+   * `AKAN_DEV_PORT` pins it instead, because the derived value *moves*: the index shifts whenever any other
+   * app directory appears or disappears, and a dev host recomputes this on every restart. So a session that
+   * adds an app relands its dev server on a different port, and anything that reserved a port relative to
+   * the old one is left pointing at nothing.
+   */
   async getDevPort() {
+    const pinned = Number(process.env.AKAN_DEV_PORT);
+    if (Number.isInteger(pinned) && pinned > 0 && pinned <= 65_535) return pinned;
     const basePort = 8282;
     const appNames = (await this.workspace.getApps()).sort((a, b) => a.localeCompare(b));
     const appIndex = Math.max(appNames.indexOf(this.name), 0);