@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.26

package/DEV_RUNTIME_KNOBS.md

@@ -22,7 +22,7 @@ crosses its ceiling is replaced when it is next idle — never mid-work.
 
 | process | explicit (MiB) | explicit (bytes) | share of the limit | fallback with no limit |
 |---|---|---|---|---|
-| incremental builder | `AKAN_BUILDER_MAX_RSS_MB` | `AKAN_BUILDER_MAX_RSS` | **0.35** | 1200MB (dev) |
+| incremental builder | `AKAN_BUILDER_MAX_RSS_MB` | `AKAN_BUILDER_MAX_RSS` | **0.35** | 2048MB (dev) |
 | RSC worker | `AKAN_RSC_WORKER_MAX_RSS_MB` | `AKAN_RSC_WORKER_MAX_RSS` | **0.55** | 768MB (dev), unbounded (production) |
 
 `AKAN_BUILDER_MAX_RSS_MB=0` leaves the builder unbounded, which is the escape hatch for an app whose
@@ -37,8 +37,10 @@ this repo's own `apps/akan`). None of those has a ceiling, and none is subtracte
 
 In practice this holds because the two ceilings are rarely at their limit simultaneously and the build
 worker exits. But if you are sizing a container to a hard number, size it against the *sum of observed
-peaks*, not against these fractions. Measured floors, for reference: builder 134-202MB at rest and
-~490MB after a route build, RSC worker ~142MB after boot, ~247MB per route build.
+peaks*, not against these fractions. Measured on `apps/minimal` (macOS, 2026-09-29), for reference: the
+builder ~120MB at rest after boot, ~540MB right after its first route build (the bundler hands most of it
+back after ~20s idle), ~250MB while it patches saves into the SSR registry; the RSC worker ~75MB after boot
+and ~110MB after route builds; the build worker ~900MB for the SSR registry's boot build.
 
 ## Recycling behaviour
 
@@ -65,10 +67,17 @@ which is the one case where replacing it again cannot help; it says that too, an
 
 | variable | default | what it does |
 |---|---|---|
-| `AKAN_DEV_CSR_REBUILD` | off | Rebuild the CSR artifact on every save. Armed automatically by the first `/__csr` or `?csr=true` request, which is what a mobile WebView session does — set it explicitly only to have it from boot. |
+| `AKAN_DEV_CSR_REBUILD` | off | Rebuild the CSR artifact on every save. Armed automatically by the first `/__csr` or `?csr=true` request, which is what a mobile WebView session does — set it explicitly only to have it from boot. Set at boot, its CSR build runs beside the SSR registry's: on apps/akan the builder and its workers peak at about 2.7GB instead of 1.3GB, and the next boot wave waits for both builds. |
+| `AKAN_DEV_CSR` | `registry` | How the dev CSR page is built. `registry` serves it as a module registry that patches the modules a save changed; `artifact` brings back the single-file bundle, which reloads on every save. |
+| `AKAN_DEV_CSR_PATCHER` | on | `off` sends every save of a dev module registry — the CSR page's, and the one SSR pages load their client code from (`.akan/artifact/ssr-dev`) — to a disposable build worker instead of patching it in the resident builder. The patcher keeps each registry in memory (on minimal the CSR one adds about 170MB to the builder's median RSS and 210MB to its peak, flat across saves) and hands whole-app builds to a worker: a first build, a new npm module, a bare import no file of its package resolved before, a config change, a signal or dictionary save (their metadata is inlined at build time), and a registry whose last whole build was cut short. A misspelled import fails in the builder, like a missing file. A builder that dies mid-patch turns it off until the dev server next replaces its builder and backend together (a config, signal or dictionary change). |
+| `AKAN_DEV_WATCH_DEBOUNCE_MS` | `30` | How long the file watcher collects changes before it hands a batch over. Every save waits this long before anything builds. A second write inside the window joins the same batch; one after it starts another batch, which reads the file's latest content, so a format-on-save costs a second build rather than a wrong one. |
 | `AKAN_BUILDER_RPC_TIMEOUT_MS` | `120000` | How long the backend waits for a builder answer. Generous on purpose: a cold CSR build of every page legitimately takes tens of seconds. |
 | `AKAN_SERVER_PAGES_SPLITTING` | off | Emit the server pages bundle as chunks instead of one file. Experimental — the memory/latency trade has not been measured on a real app. |
 
+Two more are read by the dev server for its end-to-end tests only; never set them. `AKAN_DEV_SSR_ARM_DELAY_MS`
+holds the SSR registry's boot build back, and `AKAN_CSR_DEV_APP_WRITE_DELAY_MS` holds a registry's `app.js`
+back after a patch is announced.
+
 ## Observability
 
 | variable | default | what it does |
@@ -80,31 +89,36 @@ which is the one case where replacing it again cannot help; it says that too, an
 ## Several apps at once
 
 `akan start a,b` runs one dev host per app under a supervisor, so **every number above multiplies by the number
-of apps** — there is no shared builder and no shared RSC worker. Measured on this repo, right after both apps
+of apps** — there is no shared builder and no shared RSC worker. Measured on this repo 8 seconds after both apps
 finished booting:
 
 | process | akan | minimal |
 |---|---|---|
-| dev host | 101MB | 94MB |
-| incremental builder | 596MB | 532MB |
-| backend | 35MB | 38MB |
-| RSC worker | 190MB | 81MB |
-
-Plus ~51MB for the supervisor itself: **~1.7GB for two apps at their peak.** The builders are almost all of
-that, and they are also the part that goes away — `AKAN_DEV_IDLE_SUSPEND_MS` releases each one independently, so
-a session where you are editing one app settles to roughly one builder plus ~190MB per idle app. **Multi-app is
-sized against idle suspend being on**; setting it to `0` keeps every builder resident for the whole session.
+| dev host | 279MB | 196MB |
+| incremental builder | 182MB | 114MB |
+| backend (gateway and replica) | 123MB | 130MB |
+| RSC worker | 162MB | 75MB |
+
+Plus ~75MB for the supervisor itself: **~1.3GB for two apps at rest.** The peak is the boot, not the rest: the
+build workers — the base build, then the SSR registry's — take a whole akan dev host to ~1.9GB and minimal's to
+~1.4GB, and booted one after the other the two peaked at 2.2GB. The builders are also the part that goes away —
+`AKAN_DEV_IDLE_SUSPEND_MS` releases each one independently, so a session where you are editing one app keeps one
+builder, and every idle app keeps only its dev host, backend and RSC worker. **Multi-app is sized against idle
+suspend being on**; setting it to `0` keeps every builder resident for the whole session.
 
 Two things bound the peak rather than the floor:
 
-- **`--concurrency` (default: what the machine allows).** Apps boot in waves, and the next wave starts only
-  once the previous one reports ready. A cold boot build is the builder's peak, so booting `n` apps at once
-  means `n` overlapping peaks — which is what OOM-kills a container that would have been fine with them
-  staggered. Unset, the wave is `min(apps, half the memory budget / 900MB per app, cores / 4)`, never below
-  one, and the session prints which — so a laptop boots its apps together and a 1.2GB container still
-  staggers them. The memory budget is the smaller of the host's RAM and `AKAN_MEMORY_LIMIT` / the cgroup
-  limit; `os.freemem()` is not consulted, because it counts free pages rather than reclaimable ones and
-  reports ~0.3GB on an idle 48GB laptop.
+- **`--concurrency` (default: what the machine allows).** Apps boot in waves. The next wave starts once each
+  app of the previous one serves and its builder's boot builds have settled — the SSR registry's, and CSR's when
+  `AKAN_DEV_CSR_REBUILD=1` arms it — since those workers are the largest processes of a boot. An app that never
+  reports them starts the next wave 30 seconds after it serves. It shows as ready, and `--open` opens it, as
+  soon as it serves. Booting `n` apps at once means `n` overlapping peaks — which is what OOM-kills a container
+  that would have been fine with them staggered. Unset, the wave is
+  `min(apps, half the memory budget / 1.8GB per app, cores / 4)`, never below one, and the session prints
+  which — so a laptop boots its apps together and a small container boots them one at a time. The 1.8GB is
+  apps/akan's boot peak across all its processes (measured 1.73–1.9GB). The memory budget is the smaller of
+  the host's RAM and `AKAN_MEMORY_LIMIT` / the cgroup limit; `os.freemem()` is not consulted, because it counts
+  free pages rather than reclaimable ones and reports ~0.3GB on an idle 48GB laptop.
 - **`AKAN_MEMORY_LIMIT` is per process, not per session.** Each dev host derives its builder and RSC-worker
   ceilings from it independently, so a limit sized for one app does not become a budget for four. Divide it
   yourself, or leave it unset on a laptop. The one place it is read as a session ceiling is the boot wave
@@ -113,18 +127,22 @@ Two things bound the peak rather than the floor:
 
 ## Sizing a small sandbox
 
-A worked example, for a 1.2GB container:
+A worked example, for a 1.2GB container running an app the size of `apps/minimal` (apps/akan's boot alone
+peaks near 1.8GB):
 
 ```bash
 AKAN_MEMORY_LIMIT=1200mb          # builder gets ~420MB, rsc worker ~660MB
 AKAN_DEV_IDLE_SUSPEND_MS=300000   # release the builder after 5 idle minutes
 ```
 
-Two things to expect at that size. The builder crosses 420MB during ordinary work — one route build
-costs ~247MB on top of its floor — so it is replaced roughly once per 30s while you keep building, each
+Two things to expect at that size. The builder crosses 420MB during ordinary work — its first route
+build alone takes it to ~540MB — so it is replaced roughly once per 30s while you keep building, each
 replacement costing a boot build that requests wait through rather than fail. And the build worker's
 peak is not covered by any of these ceilings; if the kernel OOM-kills it, the dev server survives with a
-red build for that generation and the log names the signal.
+red build for that generation and the log names the signal. On a boot whose `.akan` was cleared, the SSR
+registry's first build is such a worker, peaking near 900MB on `apps/minimal`: a killed one leaves no
+registry, and every later save retries that same whole build, so a container that cannot fit it once
+cannot fit it at all.
 
 Raising `AKAN_BUILDER_MAX_RSS_MB` above the derived share trades memory for fewer boot builds. Setting
 it to `0` trades the bound away entirely, which on a container this size means the kernel decides

package/akanApp/akanApp.host.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage, BuilderMetrics, BuildPhase, ChangeBatch, DevBuildStatus } from "akanjs/server";
 import type { App } from "../commandDecorators";
@@ -9,6 +10,7 @@ import { WatchRootResolver } from "../frontendBuild/watchRootResolver";
 import { type DevStdioMode, IncrementalBuilderHost } from "../incrementalBuilder";
 import { BuilderRequestRouter } from "../incrementalBuilder/builderRequestRouter";
 import { BackendImportGraph } from "./BackendImportGraph";
+import { DevBootLatch } from "./devBootLatch";
 import {
   type BackendLifecycleState,
   type BackendRestartReason,
@@ -34,6 +36,7 @@ import {
   type SourceFingerprints,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
+  shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -88,8 +91,11 @@ export class AkanAppHost {
   readonly env: Record<string, string>;
   readonly #onDevEvent: ((event: DevHostEvent) => void) | null;
   #lastDevState: DevHostState | null = null;
+  readonly #bootLatch = new DevBootLatch(() => this.#onDevEvent?.({ app: this.app.name, booted: true }));
   #backend: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #builder: IncrementalBuilderHost | null = null;
+  //? Outlives the builder host, which idle wake and recovery replace; a config or metadata restart clears it.
+  #patcherOff = false;
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
@@ -98,7 +104,16 @@ export class AkanAppHost {
   #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
-  #pendingRecycle: { message: Extract<BuilderMessage, { type: "invalidate" }>; refreshConfig: boolean } | null = null;
+  #pendingRecycle: {
+    message: Extract<BuilderMessage, { type: "invalidate" }>;
+    refreshConfig: boolean;
+    failed?: boolean;
+    failedGeneration?: number;
+  } | null = null;
+  //? A restart that failed after its change applied (the builder or backend did not come up): the builder's return is
+  //? its recovery, reported past the failure's generation so the scan overlay clears.
+  #restartFailedAfterApply: number | null = null;
+  #stopping = false;
   #builderRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
   #builderRecoveryAttempts = 0;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
@@ -126,6 +141,7 @@ export class AkanAppHost {
   #builderGapStamp: Promise<SourceFingerprints | null> | null = null;
   #pendingBuilderMessages: BuilderMessage[] = [];
   readonly #builderRequests = new BuilderRequestRouter();
+  #builderGeneration = 0;
   constructor(
     private readonly app: App,
     {
@@ -143,6 +159,7 @@ export class AkanAppHost {
     if (!this.#onDevEvent || state === this.#lastDevState) return;
     this.#lastDevState = state;
     this.#onDevEvent({ app: this.app.name, state, ...(detail ? { detail } : {}) });
+    if (state === "ready") this.#bootLatch.ready();
   }
   async start() {
     if (this.#backend) await this.#stopBackend();
@@ -158,6 +175,9 @@ export class AkanAppHost {
     return this;
   }
   async stop() {
+    //? Nothing reapplies once it stops: a pages ok received meanwhile would bring children back after it.
+    this.#stopping = true;
+    this.#pendingRecycle = null;
     this.#cancelIdleSuspend();
     this.#stopIdleWatcher();
     this.#clearRestartTimers();
@@ -202,6 +222,7 @@ export class AkanAppHost {
           this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
           this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
+          this.#forgetRouteBuildStatus();
           this.#replayBuilderState();
           return;
         }
@@ -424,17 +445,25 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
+    if (this.#stopping) return;
     this.#markDevActivity();
+    this.#trackBuilderGeneration(message);
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
       this.#reviveBackendAfterGreenBuild(message.data);
+      await this.#resumeFailedRecycle(message.data);
       return;
     }
     if (message.type === "builder-metrics") {
       this.#handleBuilderMetrics(message.data);
       return;
     }
+    if (message.type === "boot-armed") {
+      this.logger.verbose("[builder] boot builds settled");
+      this.#bootLatch.armed();
+      return;
+    }
     if (message.type === "pages-updated" || message.type === "css-updated") {
       const recycled = message.data.reason === "builder-recycle";
       if (recycled && !this.#shouldRelayRecycledState(message)) return;
@@ -455,6 +484,20 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  // In `env`, which every builder spawn re-reads: a replacement (recycled, crashed, restarted) continues from here.
+  #trackBuilderGeneration(message: BuilderMessage): void {
+    const generation = AkanAppHost.#builderGenerationOf(message);
+    if (generation === undefined || generation <= this.#builderGeneration) return;
+    this.#builderGeneration = generation;
+    Object.assign(this.env, { AKAN_BUILDER_INITIAL_GENERATION: String(generation) });
+  }
+  // Not `csr-updated` / `ssr-updated`: their generation is the registry's.
+  static #builderGenerationOf(message: BuilderMessage): number | undefined {
+    if (message.type === "invalidate") return message.generation;
+    if (message.type === "build-status" || message.type === "builder-metrics") return message.data.generation;
+    if (message.type === "pages-updated" || message.type === "css-updated") return message.data.generation;
+    return undefined;
+  }
   // The backend reads `base-artifact.json` once, so a recycled builder re-announces it; unchanged hashes are dropped.
   #shouldRelayRecycledState(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
@@ -752,12 +795,8 @@ export class AkanAppHost {
       this.logger.verbose("[idle-suspend] config changed while suspended; restarting the dev host");
       // Replaces the backend too, and a baseline kept past its own gap costs a restart at the next one.
       this.#discardBuilderGap("config change replaces the backend anyway");
-      await this.#recycleDevChildren(
-        { type: "invalidate", kinds: [...(batch?.kinds ?? [])], files },
-        {
-          refreshConfig: true,
-        },
-      );
+      //? Through the same path as a save's: a failure is reported and stays pending, as one would be awake.
+      await this.#applyRecycle({ type: "invalidate", kinds: [...(batch?.kinds ?? [])], files }, true);
       return;
     }
     // Refresh before deciding: a file created while suspended is not in the graph yet.
@@ -863,7 +902,8 @@ export class AkanAppHost {
     const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
     const pending = this.#pendingRecycle;
     // A deferred recycle resumes on the next code batch; a css-only batch cannot heal a compile error.
-    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || (pending && message.kinds.includes("code"))) {
+    const resumes = !!pending && message.kinds.includes("code") && this.#touchesFailedRecycle(message.files);
+    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || resumes) {
       const refreshConfig = wantsDevHostRestart || (pending?.refreshConfig ?? false);
       const merged = pending ? mergeInvalidateMessages(pending.message, message) : message;
       const generation = message.devPlan?.generation ?? message.generation;
@@ -871,14 +911,7 @@ export class AkanAppHost {
         this.#deferRecycle(merged, { refreshConfig, generation });
         return;
       }
-      this.#pendingRecycle = null;
-      try {
-        if (refreshConfig) await this.#restartDevHost(merged);
-        else await this.#restartDevChildren(merged);
-      } catch (err) {
-        this.#recordDevHostRestartFailure(merged, err, refreshConfig ? "Config" : "Runtime metadata");
-        this.#resurrectDevChildren(merged);
-      }
+      await this.#applyRecycle(merged, refreshConfig);
       return;
     }
     if (await this.#shouldRestartBackend(message)) {
@@ -887,6 +920,38 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  async #applyRecycle(message: Extract<BuilderMessage, { type: "invalidate" }>, refreshConfig: boolean): Promise<void> {
+    if (this.#stopping) return;
+    this.#pendingRecycle = null;
+    const progress = { applied: !refreshConfig };
+    try {
+      if (refreshConfig) await this.#restartDevHost(message, progress);
+      else await this.#restartDevChildren(message);
+    } catch (err) {
+      const kind = refreshConfig ? "Config" : "Runtime metadata";
+      const generation = this.#recordDevHostRestartFailure(message, err, kind, { applied: progress.applied });
+      //? Kept only when the change itself did not apply: a builder that booted degraded (a broken akan.config.ts)
+      //? takes the fixing save itself and sends no invalidate, so without this the old config would keep running.
+      if (progress.applied) this.#restartFailedAfterApply = generation;
+      else this.#pendingRecycle = { message, refreshConfig, failed: true, failedGeneration: generation };
+      this.#resurrectDevChildren(message);
+    }
+  }
+  //? The first green pages build after a failed restart that touches its change is the fix: the change applies then. A
+  //? cause no save fixes (an env value) waits for the next change of those files, not for every green save.
+  async #resumeFailedRecycle(status: DevBuildStatus): Promise<void> {
+    const pending = this.#pendingRecycle;
+    if (!pending?.failed || !status.ok || status.phase !== "pages" || !this.#touchesFailedRecycle(status.files)) return;
+    //? Newer than the failure: the batch that carried the change reports its own pages ok while the restart runs.
+    if (status.generation <= (pending.failedGeneration ?? -1)) return;
+    await this.#applyRecycle(pending.message, pending.refreshConfig);
+  }
+  #touchesFailedRecycle(files: string[]): boolean {
+    const pending = this.#pendingRecycle;
+    if (!pending?.failed) return true;
+    const changed = new Set(pending.message.files);
+    return files.some((file) => changed.has(file));
+  }
   #deferRecycle(
     message: Extract<BuilderMessage, { type: "invalidate" }>,
     { refreshConfig, generation }: { refreshConfig: boolean; generation?: number },
@@ -937,8 +1002,13 @@ export class AkanAppHost {
     this.#builderRecoveryAttempts = 0;
     this.logger.info("[builder-recovery] builder recovered");
     void this.#restartBackendForGapChanges();
+    const failedAfterApply = this.#restartFailedAfterApply;
+    this.#restartFailedAfterApply = null;
     const status: DevBuildStatus = {
-      generation: reason.generation ?? this.#nextBackendBuildStatusGeneration(),
+      generation:
+        failedAfterApply !== null
+          ? this.#nextBackendBuildStatusGeneration(failedAfterApply + 1)
+          : (reason.generation ?? this.#nextBackendBuildStatusGeneration()),
       phase: "scan",
       ok: true,
       files: reason.files,
@@ -965,16 +1035,19 @@ export class AkanAppHost {
   }
   // The config is re-imported with a cache-busting query, but modules it imports stay cached: a change inside an
   // imported plugin file still needs a manual `akan start` restart.
-  async #restartDevHost(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
+  async #restartDevHost(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    progress?: { applied: boolean },
+  ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.logger.warn(
       `[dev-host] config change detected; restarting dev host generation=${generation ?? "(unknown)"} files=${message.files.length}`,
     );
-    await this.#recycleDevChildren(message, { refreshConfig: true });
+    await this.#recycleDevChildren(message, { refreshConfig: true, progress });
   }
   async #recycleDevChildren(
     message: Extract<BuilderMessage, { type: "invalidate" }>,
-    { refreshConfig = false }: { refreshConfig?: boolean } = {},
+    { refreshConfig = false, progress }: { refreshConfig?: boolean; progress?: { applied: boolean } } = {},
   ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.#clearRestartTimers();
@@ -985,17 +1058,19 @@ export class AkanAppHost {
     this.#pendingBuildStatusReplay = [];
     await this.#stopBackend();
     this.#stopBuilder();
+    this.#patcherOff = false;
     if (refreshConfig) {
       await this.app.getConfig({ refresh: true });
       // Merge, not replace: `start()` added values prepare does not produce (REDIS_HOST from the tunnel).
       const { env } = await this.app.prepareCommand("start");
       Object.assign(this.env, env);
+      if (progress) progress.applied = true;
     }
     await this.#backendGraph.refresh();
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
   }
-  // `supersede`: a replacement builder's generation restarts at 0, so its announcement would look stale.
+  // `supersede`: a recycled builder's re-announcement is what is on disk now, whatever generation it carries.
   #recordLastGood(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
     { supersede = false }: { supersede?: boolean } = {},
@@ -1018,22 +1093,29 @@ export class AkanAppHost {
     message: Extract<BuilderMessage, { type: "invalidate" }>,
     err: unknown,
     kind: "Config" | "Runtime metadata",
-  ): void {
+    { applied }: { applied: boolean },
+  ): number {
     const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
     const detail = err instanceof Error ? err.message : String(err);
     this.logger.warn(`[dev-host] ${kind.toLowerCase()} restart failed generation=${generation}: ${detail}`);
+    const names = message.files.slice(0, 3).map((file) => path.basename(file));
+    const saved = names.length > 0 ? names.join(", ") : "the changed file";
     const status: DevBuildStatus = {
       generation,
       phase: "scan",
       ok: false,
       files: message.files,
-      message: `${kind} change failed to apply; recovering the dev server automatically: ${detail}`,
+      message: applied
+        ? `${kind} change applied, but the dev server failed to restart: ${detail}. It is recovering on its own.`
+        : `${kind} change failed to apply: ${detail}. The dev server keeps running on the previous ${kind.toLowerCase()}; once it is fixed, save ${saved} again or restart the dev server to apply it.`,
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
+    return generation;
   }
   #recordBuildStatus(status: DevBuildStatus): void {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
+    if (shouldKeepBuildFailure(this.#buildStatusByPhase, status)) return;
     this.#buildStatusByPhase.set(status.phase, status);
     const label = `[build-status] generation=${status.generation} phase=${status.phase} ok=${status.ok} files=${status.files.length}`;
     if (status.ok) this.logger.verbose(`${label}${recovered ? " recovered=1" : ""}`);
@@ -1049,6 +1131,12 @@ export class AkanAppHost {
     }
     this.#sendToBackend({ type: "build-status", data: status });
   }
+  //? A route status belongs to the route cache of the backend that asked for the build: a new backend builds its routes
+  //? again, and reports each one itself.
+  #forgetRouteBuildStatus(): void {
+    this.#buildStatusByPhase.delete("route");
+    this.#pendingBuildStatusReplay = this.#pendingBuildStatusReplay.filter((status) => status.phase !== "route");
+  }
   #replayBuilderState(): void {
     if (!this.#backendReady) return;
     if (this.#lastGoodFrontend.css) this.#sendToBackend(this.#lastGoodFrontend.css);
@@ -1106,6 +1194,7 @@ export class AkanAppHost {
         {
           stdio: this.stdio,
           onOutput: (kind, text) => void (kind === "stderr" ? process.stderr : process.stdout).write(text),
+          patcherOff: this.#patcherOff,
         },
       );
       try {
@@ -1193,6 +1282,7 @@ export class AkanAppHost {
   #stopBuilder(): void {
     this.#cancelRssRecycle();
     if (!this.#builder) return;
+    if (this.#builder.patcherOff) this.#patcherOff = true;
     this.#builder.stop();
     this.#builder = null;
   }

package/akanApp/devBootLatch.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { DevBootLatch } from "./devBootLatch";
+
+const latch = (waitMs = 60_000) => {
+  const booted: number[] = [];
+  return { booted, latch: new DevBootLatch(() => booted.push(Date.now()), { waitMs }) };
+};
+
+describe("DevBootLatch", () => {
+  test("opens once the app serves and its boot builds have settled, in either order", () => {
+    const readyFirst = latch();
+    readyFirst.latch.ready();
+    expect(readyFirst.booted).toHaveLength(0);
+    readyFirst.latch.armed();
+    expect(readyFirst.booted).toHaveLength(1);
+
+    const armedFirst = latch();
+    armedFirst.latch.armed();
+    expect(armedFirst.booted).toHaveLength(0);
+    armedFirst.latch.ready();
+    expect(armedFirst.booted).toHaveLength(1);
+  });
+
+  test("opens once per session, however often the app restarts or the builder re-arms", () => {
+    const { booted, latch: boot } = latch();
+    boot.armed();
+    boot.ready();
+    boot.ready();
+    boot.armed();
+    expect(booted).toHaveLength(1);
+  });
+
+  test("opens after its wait past ready when the builder never reports", async () => {
+    const { booted, latch: boot } = latch(20);
+    boot.ready();
+    await Bun.sleep(60);
+    expect(booted).toHaveLength(1);
+  });
+});

package/akanApp/devBootLatch.ts

@@ -0,0 +1,39 @@
+//* An app's boot is over for the supervisor once it serves and its builder's boot builds have settled (the SSR
+//* registry's, and CSR's when the env arms it): those workers are a boot's largest processes, so the next boot wave
+//* starts here, while the browser opens on the ready that comes first.
+export class DevBootLatch {
+  readonly #onBooted: () => void;
+  readonly #waitMs: number;
+  #ready = false;
+  #armed = false;
+  #booted = false;
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** `waitMs` bounds the wait past ready: a builder that never reports (killed mid-boot) must not stall the waves. */
+  constructor(onBooted: () => void, { waitMs = 30_000 }: { waitMs?: number } = {}) {
+    this.#onBooted = onBooted;
+    this.#waitMs = waitMs;
+  }
+
+  ready(): void {
+    this.#ready = true;
+    if (!this.#armed && !this.#timer) {
+      this.#timer = setTimeout(() => this.armed(), this.#waitMs);
+      this.#timer.unref?.();
+    }
+    this.#release();
+  }
+
+  armed(): void {
+    this.#armed = true;
+    this.#release();
+  }
+
+  #release(): void {
+    if (this.#booted || !this.#ready || !this.#armed) return;
+    this.#booted = true;
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.#onBooted();
+  }
+}

package/akanApp/devHostPolicy.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeAction } from "akanjs/server";
+//? The source itself, not the package: the published akanjs exports no such subpath, and tests are not bundled.
+import { DevBuildRecovery } from "../../../akanjs/server/artifact/devBuildRecovery";
 import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
@@ -17,6 +19,7 @@ import {
   resolveIdleSuspendMs,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
+  shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -281,8 +284,9 @@ describe("dev idle suspend", () => {
     expect(resolveIdleSuspendMs("1500")).toBe(1_500);
   });
 
-  test("blocks a suspend on a failure in any phase, not just the newest generation", () => {
+  test("blocks a suspend on a failure in any phase but a route's, not just the newest generation", () => {
     expect(hasAnyBuildFailure(new Map())).toBe(false);
+    expect(hasAnyBuildFailure(new Map([["route", status("route", 1, false)]]))).toBe(false);
     expect(hasAnyBuildFailure(new Map([["scan", status("scan", 1, true)]]))).toBe(false);
     expect(
       hasAnyBuildFailure(
@@ -355,6 +359,67 @@ describe("build status helpers", () => {
     expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("pages", 12, true))).toBe(true);
   });
 
+  test("an ok of the failure's own generation neither recovers nor replaces it, except a backend's", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
+      ["ssr", status("ssr", 7, false)],
+      ["backend", status("backend", 7, false)],
+    ]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("ssr", 7, true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 7, true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 8, true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 7, false))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("backend", 7, true))).toBe(true);
+  });
+
+  test("the same route built again recovers at the failure's generation or later, and another route's ok never does", () => {
+    const routeA = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/a" });
+    const routeB = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/b" });
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", routeA(false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, routeB(true))).toBe(true);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true, 5))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true, 5))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true, 3))).toBe(true);
+  });
+
+  test("judges recovery as the backend does (akanjs DevBuildRecovery), case for case", () => {
+    const at = (phase: BuildPhase, generation: number, ok: boolean, scope?: string): DevBuildStatus => ({
+      ...status(phase, generation, ok),
+      ...(scope ? { scope } : {}),
+    });
+    const cases: [DevBuildStatus | undefined, DevBuildStatus][] = [];
+    for (const phase of ["backend", "route", "scan", "pages", "ssr"] as BuildPhase[])
+      for (const [previousOk, ok] of [
+        [false, true],
+        [true, true],
+        [false, false],
+      ])
+        for (const generation of [3, 4, 5])
+          for (const [previousScope, scope] of [
+            [undefined, undefined],
+            ["/a", "/a"],
+            ["/a", "/b"],
+          ])
+            cases.push([at(phase, 4, previousOk, previousScope), at(phase, generation, ok, scope)]);
+    cases.push([undefined, at("pages", 4, true)]);
+    for (const [previous, next] of cases) {
+      const previousByPhase = new Map<BuildPhase, DevBuildStatus>(previous ? [[previous.phase, previous]] : []);
+      expect([previous, next, shouldMarkBuildPhaseRecovered(previousByPhase, next)]).toEqual([
+        previous,
+        next,
+        DevBuildRecovery.recovers(previous, next),
+      ]);
+    }
+  });
+
+  test("a builder that came back clears no config change still on hold, or one that failed to apply", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["scan", status("scan", 42, false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 42, true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 43, true))).toBe(true);
+  });
+
   test("creates backend build-status payloads for lifecycle test hooks", () => {
     expect(
       createBackendBuildStatus({
@@ -440,6 +505,11 @@ describe("hasBuildFailureForGeneration", () => {
     expect(hasBuildFailureForGeneration(statusByPhase, 4)).toBe(false);
   });
 
+  test("leaves a route's failure out: nothing a replacement builder boots builds a route", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", status("route", 42, false)]]);
+    expect(hasBuildFailureForGeneration(statusByPhase, 42)).toBe(false);
+  });
+
   test("treats unknown generations and green boards as healthy", () => {
     const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["csr", status("csr", 3, false)]]);
     expect(hasBuildFailureForGeneration(statusByPhase, undefined)).toBe(false);