@akanjs/devkit 3.0.0-beta.3 → 3.0.0-beta.31

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/README.ko.md

@@ -44,7 +44,7 @@ await runner.build();
 - Frontend build transform과 RSC/SSR artifact builder.
 - `@akanjs/cli`가 사용하는 command/script decorator.
 - AI prompt, guideline, code-generation 지원 utility.
-- Capacitor와 mobile release helper.
+- `@akanjs/native` 기반 네이티브 모바일 빌드(iOS, Android)와 스토어 release helper.
 
 ## 패키지 경계
 
@@ -58,7 +58,7 @@ await runner.build();
 
 - [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript
-- Optional peer는 Capacitor integration처럼 해당 기능을 사용할 때만 필요합니다.
+- `react`는 optional peer이며, 렌더링하는 기능에서만 필요합니다.
 
 ## 라이선스
 

package/README.md

@@ -43,7 +43,8 @@ await runner.build();
 - Frontend build transforms and RSC/SSR artifact builders.
 - Command/script decorators used by `@akanjs/cli`.
 - AI prompt, guideline, and code-generation support utilities.
-- Capacitor and mobile release helpers.
+- Native mobile builds on `@akanjs/native` (iOS, Android) and store release helpers.
+- The `akan code` agent engine, the tools it is given, and the shipped akan skills (`@akanjs/devkit/codeAgent`).
 
 ## Dev Server Sizing
 
@@ -62,7 +63,7 @@ defaults, the shares they derive from `AKAN_MEMORY_LIMIT`, and what a small cont
 
 - [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript
-- Optional peers are only needed for the features that use them, such as Capacitor integration.
+- `react` is an optional peer, needed only by the features that render.
 
 ## License
 

package/abstractDoc.test.ts

@@ -1,29 +1,20 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
 import { AppExecutor, WorkspaceExecutor } from "./executors";
+import { tempDirs, writeText } from "./testHelpers";
 
-const tempRoots: string[] = [];
+const makeTempRoot = tempDirs("akan-abstract-doc-");
 
 const makeApp = async (files: Record<string, string>) => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-abstract-doc-"));
-  tempRoots.push(root);
+  const root = await makeTempRoot();
   const appName = "abstractDemo";
-  for (const [filePath, content] of Object.entries(files)) {
-    const absolutePath = path.join(root, "apps", appName, filePath);
-    await mkdir(path.dirname(absolutePath), { recursive: true });
-    await writeFile(absolutePath, content);
-  }
+  for (const [filePath, content] of Object.entries(files))
+    await writeText(path.join(root, "apps", appName, filePath), content);
   const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "repo" });
   return AppExecutor.from(workspace, appName);
 };
 
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
-
 describe("AbstractDoc.kindOf", () => {
   test("reads the module kind off the sys-relative path", () => {
     expect(AbstractDoc.kindOf("lib/user/user.abstract.md")).toBe("domain");

package/abstractDoc.ts

@@ -1,14 +1,12 @@
+import path from "node:path";
 import type { SysExecutor } from "./executors";
 
 export type AbstractKind = "domain" | "service" | "scalar" | "other";
 
-/** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
 export class AbstractDoc {
   static readonly suffix = ".abstract.md";
-  /** `akan quality` warns above this and points at `akan compact`. */
+  /** `akan quality` warns above this. */
   static readonly maxLines = 300;
-  /** `akan compact` floor, and the line budget it compacts down to, so a compacted file is never a candidate again. */
-  static readonly compactMinLines = 40;
   // Abstracts only live in facet folders; globbing the sys root instead would walk node_modules.
   static readonly #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
 
@@ -18,7 +16,6 @@ export class AbstractDoc {
   static lineCountOf(content: string) {
     return content.split(/\r?\n/).length;
   }
-  /** Module kind read off the sys-relative path; anything outside a `lib/` module folder is "other". */
   static kindOf(filePath: string): AbstractKind {
     const [root, folder, ...rest] = filePath.split("/");
     if (root !== "lib" || !folder) return "other";
@@ -27,7 +24,9 @@ export class AbstractDoc {
     return folder.startsWith("_") ? "service" : "domain";
   }
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
-    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
+      .map((filePath) => filePath.split(path.sep).join("/"))
+      .sort();
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);
@@ -59,8 +58,7 @@ export class AbstractDoc {
   get lineCount() {
     return AbstractDoc.lineCountOf(this.content);
   }
-  // An AI editor answers in prose when it decides nothing needs changing, and that prose would silently
-  // replace the abstract — so a candidate must look like a markdown file and be shorter than what it replaces.
+  // An AI editor that decides nothing needs changing answers in prose, which must not replace the abstract.
   canReplaceWith(candidate: string) {
     const next = candidate.trim();
     if (!next.startsWith("#")) return false;

package/agentsIndex.test.ts

@@ -1,6 +1,4 @@
 import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
 import path from "node:path";
 import {
   AGENT_BLOCK_END,
@@ -14,6 +12,7 @@ import {
   upsertAgentBlock,
 } from "./agentsIndex";
 import type { RecipeInfo } from "./recipeScanner";
+import { tempDirs, writeText } from "./testHelpers";
 
 const button: RecipeInfo = {
   name: "buttonRecipe",
@@ -79,12 +78,10 @@ describe("upsertAgentBlock / extractAgentBlock", () => {
 });
 
 describe("collectScopeRecipeSources", () => {
+  const makeTempRoot = tempDirs("agents-index-");
   test("collects own + dependency lib recipes, never the framework's", async () => {
-    const root = await mkdtemp(path.join(tmpdir(), "agents-index-"));
-    const write = async (rel: string, content: string) => {
-      await mkdir(path.dirname(path.join(root, rel)), { recursive: true });
-      await writeFile(path.join(root, rel), content);
-    };
+    const root = await makeTempRoot();
+    const write = async (rel: string, content: string) => await writeText(path.join(root, rel), content);
     await write("apps/minimal/ui/Recipe/appCard.ts", `export const appCard = recipe(tv({ base: "x" }));`);
     await write("libs/shared/ui/Recipe/panel.ts", `export const panelRecipe = recipe(tv({ base: "y" }));`);
     await write("pkgs/akanjs/ui/recipe/buttonRecipe.ts", `export const buttonRecipe = recipe(tv({ base: "z" }));`);

package/agentsIndex.ts

@@ -1,31 +1,18 @@
 import type { RecipeInfo, RecipeSource } from "./recipeScanner";
 
-// recipeScanner 는 상단에서 typescript(~65MB)를 끌어온다. 이 모듈은 executors(CLI 엔트리 그래프)에
-// 상주하므로 스캔 스택은 첫 사용 시점에 지연 로드한다 — 정적 import 로 되돌리면 entryModuleGraph 테스트가 깨진다.
+// Lazy: recipeScanner loads `typescript` (~65MB) and this module sits in the CLI entry graph (entryModuleGraph test).
 let recipeScannerLoad: Promise<typeof import("./recipeScanner")> | null = null;
 const loadRecipeScanner = () => (recipeScannerLoad ??= import("./recipeScanner"));
 
-/**
- * agentsIndex — 스코프별 에이전트 색인의 단일 렌더러.
- *
- * 색인은 소유 경계로 쪼갠다: 루트 AGENTS.md 는 프레임워크(akanjs/ui) 레시피만 싣고, 각 앱/lib 은
- * 자기 스코프에서 import 가능한 레시피(own + 의존 lib)를 자기 AGENTS.md 에 싣는다. 항상 로드되는
- * 컨텍스트가 앱 수에 비례해 커지는 것과, import 불가능한 이웃 앱 레시피가 환상을 유발하는 것을 막는다.
- *
- * 신선도는 두 지점이 보장한다: `SysExecutor.scan(write)` 가 재생성하고(akan sync/build/start 가 전부
- * 지나가는 길목), `akan lint` 가 스캔 결과와 커밋된 블록을 비교해 stale 이면 실패시킨다.
- */
+//* Split by ownership (root: framework recipes; each app/lib: what it may import), so always-loaded context does not
+//* grow with the app count and no unimportable neighbour recipe is listed.
 
 export const AGENT_BLOCK_START = "<!-- akan:agent:start -->";
 export const AGENT_BLOCK_END = "<!-- akan:agent:end -->";
 
 const AGENT_VERSION_PREFIX = "<!-- akan:agent:version ";
 
-/**
- * The generating release, stamped into the workspace block. Nothing re-runs `akan agent install` on its own, so
- * without a stamp a workspace carrying conventions from four releases ago is indistinguishable from a current one —
- * `akan doctor` compares this against the installed devkit and says so.
- */
+/** Nothing re-runs `akan agent install` on its own, so `akan doctor` compares this stamp against the installed devkit. */
 export const stampBlockVersion = (block: string, version: string): string =>
   `${AGENT_VERSION_PREFIX}${version} -->\n\n${block}`;
 
@@ -36,7 +23,7 @@ export const extractBlockVersion = (content: string): string | null =>
 /** The running `@akanjs/devkit` version; null when its package.json is unreadable, which must not fail a doctor run. */
 export const readDevkitVersion = async (): Promise<string | null> => {
   const { readFile } = await import("node:fs/promises");
-  const { getDirname } = await import("./getDirname");
+  const { getDirname } = await import("./fileSys");
   try {
     const raw = await readFile(`${getDirname(import.meta.url)}/package.json`, "utf-8");
     return (JSON.parse(raw) as { version?: string }).version ?? null;
@@ -97,10 +84,7 @@ export const renderRecipeEntries = (recipes: RecipeInfo[]): string => {
     .join("\n\n");
 };
 
-/**
- * Every recipe source importable from the scope: its own `ui/Recipe/` plus each dependency lib's.
- * Framework recipes are excluded on purpose — they live in the root AGENTS.md, valid for every scope.
- */
+/** Own `ui/Recipe/` plus each dependency lib's; framework recipes live in the root AGENTS.md instead. */
 export const collectScopeRecipeSources = async (
   workspaceRoot: string,
   scope: AgentsIndexScope,

package/akanApp/BackendImportGraph.test.ts

@@ -1,34 +1,24 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
+import { realpath, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { App } from "../commandDecorators";
+import { tempDirs, writeText } from "../testHelpers";
 import { BackendImportGraph } from "./BackendImportGraph";
 import { filesChangedSince } from "./devHostPolicy";
 
 describe("BackendImportGraph", () => {
-  const tempRoots: string[] = [];
+  const makeTempRoot = tempDirs("akan-devkit-graph-");
 
   const makeGraph = async (files: Record<string, string>) => {
-    // Realpath, not the mkdtemp path: `Bun.resolveSync` returns real paths, and on macOS `/var/folders`
-    // is a symlink, so an unresolved root makes every resolved import look like it escapes the workspace.
-    const workspaceRoot = await realpath(await mkdtemp(path.join(os.tmpdir(), "akan-devkit-graph-")));
-    tempRoots.push(workspaceRoot);
+    // Realpath: `Bun.resolveSync` returns real paths, and macOS `/var/folders` is a symlink.
+    const workspaceRoot = await realpath(await makeTempRoot());
     const cwdPath = path.join(workspaceRoot, "apps/demo");
-    for (const [rel, source] of Object.entries(files)) {
-      const filePath = path.join(cwdPath, rel);
-      await mkdir(path.dirname(filePath), { recursive: true });
-      await writeFile(filePath, source);
-    }
+    for (const [rel, source] of Object.entries(files)) await writeText(path.join(cwdPath, rel), source);
     const app = { cwdPath, workspace: { workspaceRoot } } as unknown as App;
     return { graph: new BackendImportGraph(app, new Logger("test")), cwdPath };
   };
 
-  afterEach(async () => {
-    await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-  });
-
   test("walks the backend entrypoints' import graph", async () => {
     const { graph, cwdPath } = await makeGraph({
       "main.ts": 'import "./server";\n',
@@ -51,7 +41,6 @@ describe("BackendImportGraph", () => {
     await graph.refresh();
     expect(graph.has(path.join(cwdPath, "lib/added.ts"))).toBe(false);
 
-    // The scan cache is keyed on (mtimeMs, size), so the rewrite must invalidate it.
     await writeFile(path.join(cwdPath, "server.ts"), 'import "./lib/added";\nexport default 1;\n');
 
     await graph.refresh();
@@ -81,8 +70,7 @@ describe("BackendImportGraph", () => {
     await graph.refresh();
     const before = await graph.fingerprint();
 
-    // The builder is gone here, so no watcher event exists for this save — which is the whole reason
-    // the stamps are taken. `mtimeMs` has a coarse clock on Linux, so the size has to move too.
+    // `mtimeMs` has a coarse clock on Linux, so the size has to move too.
     await writeFile(path.join(cwdPath, "lib/handler.ts"), "export const handler = () => 'changed';\n");
 
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
@@ -96,11 +84,9 @@ describe("BackendImportGraph", () => {
     });
     await graph.refresh();
     const before = await graph.fingerprint();
-    // A recycle with no edit in it is the common case, and it must not cost a backend restart.
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([]);
 
     await rm(path.join(cwdPath, "lib/handler.ts"));
-    // Deleted counts as changed: the backend is still running what used to be there.
     expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
   });
 

package/akanApp/BackendImportGraph.ts

@@ -22,14 +22,7 @@ export 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.
-   */
+  // Specifiers, not resolved paths: a new file can change what an unchanged importer's specifier resolves to.
   #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
   #ready = false;
   #lastRefreshSucceeded = false;
@@ -51,17 +44,6 @@ export class BackendImportGraph {
     return this.#files.has(path.resolve(file));
   }
 
-  /**
-   * Stamp every file the backend runs, so a caller can ask later what moved.
-   *
-   * Taken when the builder goes away and compared when its replacement is up, because nothing watches
-   * the tree in between: the departing builder's watcher left with it, and the replacement's index
-   * primes from the disk it finds, so an edit that lands in the gap is *baseline* to it and is never
-   * reported at all. The client half of such an edit is rescued by the replacement's boot build; the
-   * backend half is a server left running code that no longer exists, with nothing on screen to say so.
-   *
-   * One `stat` per graph file, against a gap that costs a whole boot build anyway.
-   */
   async fingerprint(): Promise<SourceFingerprints> {
     const stamps = await Promise.all(
       [...this.#files].map(async (file) => {
@@ -117,7 +99,6 @@ export class BackendImportGraph {
     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;

package/akanApp/akanApp.host.test.ts

@@ -1,18 +1,71 @@
 import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { IncrementalBuilderHost } from "../incrementalBuilder";
+import { createTempApp, isolateEnv, tempRoots, writeText } from "../testHelpers";
 import { AkanAppHost } from "./akanApp.host";
+import type { DevHostEvent } from "./devHostPolicy";
 
 describe("readProcessRssBytes", () => {
   test("reads this process's own rss", async () => {
     const rssBytes = await AkanAppHost.readProcessRssBytes(process.pid);
     if (rssBytes === null) throw new Error("expected to read this process's own rss");
-    // Loose bounds on purpose: the point is that it read a real number from the OS, not which number.
     expect(rssBytes).toBeGreaterThan(1024 * 1024);
     expect(rssBytes).toBeLessThan(64 * 1024 * 1024 * 1024);
   });
 
-  // Null rather than 0, because callers must treat an unreadable pid as "no new information" — a 0
-  // would read as "settled below the ceiling" and cancel a recycle that should happen.
+  // A 0 would read as "settled below the ceiling" and cancel a recycle that should happen.
   test("returns null for a pid that does not exist", async () => {
     expect(await AkanAppHost.readProcessRssBytes(2_147_483_646)).toBeNull();
   });
 });
+
+describe("a gateway whose replica crash-loops", () => {
+  isolateEnv({ AKAN_PUBLIC_REPO_NAME: "repo", AKAN_PUBLIC_SERVE_DOMAIN: "localhost", AKAN_PUBLIC_ENV: "local" });
+  const track = tempRoots();
+  const crashLoop = "Backend replica 0/federation failed 3 consecutive boots; waiting for a code change to retry: boom";
+  const readyBuilder = {
+    status: "ready",
+    patcherOff: false,
+    start: ({ onReady }: { onReady?: () => void }) => onReady?.(),
+    send: () => true,
+    stop: () => undefined,
+  } as unknown as IncrementalBuilderHost;
+
+  test("fails the dev server at once, and leaves it running for the fix", async () => {
+    const { root, app } = track(await createTempApp("demo"));
+    await writeText(
+      path.join(root, "apps/demo/main.ts"),
+      [
+        `process.send?.({ type: "build-status", data: { generation: -1, phase: "backend", ok: false, files: [], message: ${JSON.stringify(crashLoop)} } });`,
+        "setInterval(() => undefined, 1_000);",
+        "",
+      ].join("\n"),
+    );
+    const create = IncrementalBuilderHost.create;
+    IncrementalBuilderHost.create = async () => readyBuilder;
+    const events: DevHostEvent[] = [];
+    const failed = Promise.withResolvers<void>();
+    const host = new AkanAppHost(app, {
+      env: { ...process.env } as Record<string, string>,
+      onDevEvent: (event) => {
+        events.push(event);
+        if ("state" in event && event.state === "failed") failed.resolve();
+      },
+    });
+    let beforeStop: DevHostEvent[] = [];
+    try {
+      await host.start();
+      await failed.promise;
+      await Bun.sleep(300);
+      beforeStop = [...events];
+    } finally {
+      await host.stop();
+      IncrementalBuilderHost.create = create;
+    }
+
+    expect(beforeStop).toEqual([
+      { app: "demo", state: "starting" },
+      { app: "demo", state: "failed", detail: crashLoop },
+    ]);
+  });
+});