@akanjs/devkit 2.4.0-rc.0 → 2.4.0-rc.2

package/akanApp/akanApp.host.test.ts

@@ -6,6 +6,8 @@ import {
   createBackendBuildStatus,
   isLegacyBackendFallbackFile,
   mergeBackendRestartReasons,
+  normalizeBackendReportedGeneration,
+  shouldAbandonBackendRecovery,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldReplaceLastGoodMessage,
@@ -209,3 +211,28 @@ describe("legacy backend graph fallback", () => {
     expect(isLegacyBackendFallbackFile(`${root}/apps/akan/page/_index.tsx`, root)).toBe(false);
   });
 });
+
+describe("backend recovery abandonment", () => {
+  test("keeps retrying below the attempt ceiling and abandons at it", () => {
+    expect(shouldAbandonBackendRecovery(0)).toBe(false);
+    expect(shouldAbandonBackendRecovery(4)).toBe(false);
+    expect(shouldAbandonBackendRecovery(5)).toBe(true);
+    expect(shouldAbandonBackendRecovery(9)).toBe(true);
+  });
+
+  test("honors a custom attempt ceiling", () => {
+    expect(shouldAbandonBackendRecovery(2, 3)).toBe(false);
+    expect(shouldAbandonBackendRecovery(3, 3)).toBe(true);
+  });
+});
+
+describe("normalizeBackendReportedGeneration", () => {
+  test("drops the gateway's unknown-generation sentinel", () => {
+    expect(normalizeBackendReportedGeneration(-1)).toBeUndefined();
+  });
+
+  test("keeps real generations including zero", () => {
+    expect(normalizeBackendReportedGeneration(0)).toBe(0);
+    expect(normalizeBackendReportedGeneration(7)).toBe(7);
+  });
+});

package/akanApp/akanApp.host.ts

@@ -8,9 +8,12 @@ import { IncrementalBuilderHost } from "../incrementalBuilder";
 
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route"]);
 const BACKEND_RESTART_DEBOUNCE_MS = 120;
-const BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
+// Must exceed the gateway's child-wait budget (AkanApp child shutdown, ~5s in dev) so the gateway
+// is never SIGKILLed while its replicas are still shutting down — that's what strands orphans.
+const BACKEND_GRACEFUL_TIMEOUT_MS = 8_000;
 const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
 const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
+const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
@@ -39,6 +42,17 @@ export const shouldRestartBackendByDevPlan = (
 export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-builder") ?? false;
 
+/**
+ * A backend that keeps dying isn't going to heal by retrying the same code; after this many
+ * consecutive attempts the host idles and the next server-side edit triggers a fresh restart.
+ */
+export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
+  attempts >= maxAttempts;
+
+/** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
+export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
+  generation >= 0 ? generation : undefined;
+
 export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 
@@ -339,6 +353,18 @@ export class AkanAppHost {
           this.#replayBuilderState();
           return;
         }
+        if (msg.type === "build-status") {
+          // The gateway reports replica boot failures (crash loops, port conflicts) this way so
+          // they reach the build-status log and the HMR overlay like any other build failure.
+          const status = this.#recordBackendBuildStatus({
+            generation: normalizeBackendReportedGeneration(msg.data.generation),
+            ok: msg.data.ok,
+            files: msg.data.files,
+            message: msg.data.message,
+          });
+          this.#sendOrQueueBuildStatus(status);
+          return;
+        }
         if (backendMsgTypeSet.has(msg.type)) this.#sendToBuilder(msg);
       },
       serialization: "advanced",
@@ -504,6 +530,17 @@ export class AkanAppHost {
   }
   #scheduleBackendRecovery(reason: string) {
     if (this.#backendRecoveryTimer || this.#backend) return;
+    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.logger.error(`[backend-recovery] ${message}`);
+      if (this.#backendStderrTail.length > 0) {
+        this.logger.error(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
+      }
+      const abandonedStatus = this.#recordBackendBuildStatus({ ok: false, files: [], message });
+      this.#sendOrQueueBuildStatus(abandonedStatus);
+      return;
+    }
     this.#setBackendLifecycleState("recovering", reason);
     const attempt = this.#backendRecoveryAttempts;
     const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
@@ -550,16 +587,23 @@ export class AkanAppHost {
     this.#sendToBackend(message);
   }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
-    if (shouldRestartBuilderByDevPlan(message)) {
+    this.#logDevPlan(message);
+    // Config changes subsume builder restarts: the dev-host restart recycles builder and backend
+    // AND re-runs the prepare step, so check it first when a batch carries both actions.
+    if (shouldRestartDevHostByDevPlan(message)) {
       try {
-        await this.#restartDevChildren(message);
+        await this.#restartDevHost(message);
       } catch (err) {
-        this.#recordDevHostRestartFailure(message, err);
+        this.#recordDevHostRestartFailure(message, err, "Config");
       }
       return;
     }
-    if (shouldRestartDevHostByDevPlan(message)) {
-      this.#recordDevHostRestartRequired(message);
+    if (shouldRestartBuilderByDevPlan(message)) {
+      try {
+        await this.#restartDevChildren(message);
+      } catch (err) {
+        this.#recordDevHostRestartFailure(message, err, "Runtime metadata");
+      }
       return;
     }
     if (await this.#shouldRestartBackend(message)) {
@@ -573,6 +617,27 @@ export class AkanAppHost {
     this.logger.warn(
       `[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`,
     );
+    await this.#recycleDevChildren(message);
+  }
+  /**
+   * Controlled dev-host restart for config changes (akan.config.ts, tsconfig, package.json):
+   * re-runs the prepare step so env and codegen reflect the new config, then recycles the builder
+   * and backend. The config module is re-imported with a cache-busting query; modules it imports
+   * keep their cached instances, so a change inside an imported plugin file still needs a manual
+   * `akan start` restart.
+   */
+  async #restartDevHost(message: Extract<BuilderMessage, { type: "invalidate" }>): 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 });
+  }
+  async #recycleDevChildren(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    { refreshConfig = false }: { refreshConfig?: boolean } = {},
+  ): Promise<void> {
+    const generation = message.devPlan?.generation ?? message.generation;
     if (this.#restartTimer) {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;
@@ -587,6 +652,13 @@ export class AkanAppHost {
     this.#pendingBuildStatusReplay = [];
     await this.#stopBackend();
     this.#stopBuilder();
+    if (refreshConfig) {
+      await this.app.getConfig({ refresh: true });
+      // Merge instead of replace: start() enriched this.env with values prepare doesn't produce
+      // (e.g. REDIS_HOST from the tunnel), and the spawned children must keep seeing them.
+      const { env } = await this.app.prepareCommand("start");
+      Object.assign(this.env, env);
+    }
     await this.#backendGraph.refresh();
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
@@ -608,34 +680,20 @@ export class AkanAppHost {
       `[last-good] css generation=${message.data.generation ?? "(unknown)"} assets=${Object.keys(message.data.cssAssets).length}`,
     );
   }
-  #recordDevHostRestartRequired(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
-    const generation = message.devPlan?.generation ?? message.generation;
-    const detail = `generation=${generation ?? "(unknown)"} files=${message.files.length}`;
-    this.logger.warn(
-      `[dev-host] config change requires a manual restart until controlled dev-host restart is implemented (${detail})`,
-    );
-    if (typeof generation === "number") {
-      const status: DevBuildStatus = {
-        generation,
-        phase: "scan",
-        ok: false,
-        files: message.files,
-        message: "Config change requires restarting `akan start` to apply.",
-      };
-      this.#recordBuildStatus(status);
-      this.#sendOrQueueBuildStatus(status);
-    }
-  }
-  #recordDevHostRestartFailure(message: Extract<BuilderMessage, { type: "invalidate" }>, err: unknown): void {
+  #recordDevHostRestartFailure(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    err: unknown,
+    kind: "Config" | "Runtime metadata",
+  ): void {
     const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
     const detail = err instanceof Error ? err.message : String(err);
-    this.logger.warn(`[dev-host] runtime metadata restart failed generation=${generation}: ${detail}`);
+    this.logger.warn(`[dev-host] ${kind.toLowerCase()} restart failed generation=${generation}: ${detail}`);
     const status: DevBuildStatus = {
       generation,
       phase: "scan",
       ok: false,
       files: message.files,
-      message: `Runtime metadata change requires restarting \`akan start\` to apply: ${detail}`,
+      message: `${kind} change requires restarting \`akan start\` to apply: ${detail}`,
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
@@ -666,13 +724,18 @@ export class AkanAppHost {
       this.#sendToBackend({ type: "build-status", data: status });
     }
   }
+  /** One log line per planned generation, regardless of which action branch handles it. */
+  #logDevPlan(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
+    if (!message.devPlan) return;
+    const { generation, roles, actions, reasonByFile } = message.devPlan;
+    this.logger.verbose(
+      `[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`,
+    );
+  }
+
   async #shouldRestartBackend(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<boolean> {
     if (message.kinds.length === 1 && message.kinds[0] === "css") return false;
     if (message.devPlan) {
-      const { generation, roles, actions, reasonByFile } = message.devPlan;
-      this.logger.verbose(
-        `[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`,
-      );
       const shouldRestart = shouldRestartBackendByDevPlan(message) ?? false;
       if (shouldRestart && message.kinds.includes("code")) await this.#backendGraph.refresh();
       return shouldRestart;

package/akanConfig/akanConfig.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PackageJson } from "../types";
@@ -344,3 +345,26 @@ describe("AkanLibConfig", () => {
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);
   });
 });
+
+describe("AkanAppConfig.importConfigModule", () => {
+  test("busting the import cache re-evaluates an edited config module", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-bust-"));
+    try {
+      const configPath = path.join(root, "akan.config.ts");
+      fs.writeFileSync(configPath, "export default { basePaths: ['first'] };\n");
+      const first = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root);
+      expect(first.basePaths).toEqual(["first"]);
+
+      fs.writeFileSync(configPath, "export default { basePaths: ['second'] };\n");
+      const stale = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root);
+      expect(stale.basePaths).toEqual(["first"]);
+
+      const busted = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root, {
+        bustImportCache: true,
+      });
+      expect(busted.basePaths).toEqual(["second"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/akanConfig/akanConfig.ts

@@ -339,9 +339,26 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       command,
     };
   }
-  static async from(app: App) {
+  static #importGeneration = 0;
+  /**
+   * Bun caches dynamic imports by path, so a plain re-import after the user edits the config file
+   * returns the stale module. `bustImportCache` appends a fresh query string to force re-evaluation
+   * of the config module itself; modules it imports keep their cached instances.
+   */
+  static async importConfigModule<T = unknown>(
+    cwdPath: string,
+    { bustImportCache = false }: { bustImportCache?: boolean } = {},
+  ): Promise<T> {
+    const configPath = `${cwdPath}/akan.config.ts`;
+    const importPath = bustImportCache
+      ? `${configPath}?akanConfigGeneration=${++AkanAppConfig.#importGeneration}`
+      : configPath;
+    return (await import(importPath).then((mod: { default: T }) => mod.default)) as T;
+  }
+
+  static async from(app: App, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
     const [configImp, baseDevEnv, libs, rootPackageJson] = await Promise.all([
-      import(`${app.cwdPath}/akan.config.ts`).then((mod) => mod.default),
+      AkanAppConfig.importConfigModule(app.cwdPath, { bustImportCache }),
       WorkspaceExecutor.getBaseDevEnv(path.join(app.workspace.workspaceRoot, ".env")),
       app.workspace.getLibs(),
       app.workspace.getPackageJson(),

package/executors.ts

@@ -1463,7 +1463,9 @@ export class AppExecutor extends SysExecutor {
   #akanConfig: AkanAppConfig | null = null;
   override async getConfig({ refresh }: { refresh?: boolean } = {}) {
     if (this.#akanConfig && !refresh) return this.#akanConfig;
-    this.#akanConfig = await AkanAppConfig.from(this);
+    // A refresh means the config file may have been edited; bust the import cache so the fresh
+    // module is evaluated instead of Bun's cached instance.
+    this.#akanConfig = await AkanAppConfig.from(this, { bustImportCache: refresh });
     return this.#akanConfig;
   }
 

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -308,15 +308,22 @@ class IncrementalBuilder {
     }
     if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
 
-    if (kinds.includes("code") && (await this.batchMayChangePageKeys(appDir, expandedBatch))) {
+    // Server-only generations (e.g. a .service.ts or srvkit edit) must not rebuild or refresh the
+    // client: a fresh pages buildId would broadcast rsc-refresh to browsers for no visible change.
+    const rebuildClient = devPlan.actions.includes("rebuild-client");
+    if (kinds.includes("code") && !rebuildClient) {
+      this.#logger.verbose(`client rebuild skipped; devPlan actions=${devPlan.actions.join(",") || "(none)"}`);
+    }
+
+    if (kinds.includes("code") && rebuildClient && (await this.batchMayChangePageKeys(appDir, expandedBatch))) {
       const started = Date.now();
       await this.#app.getPageKeys({ refresh: true });
       this.#logger.verbose(`pageKeys updated, app pageKeys are refreshed (${Date.now() - started}ms)`);
-    } else if (kinds.includes("code") && this.batchTouchesPagesTree(appDir, expandedBatch)) {
+    } else if (kinds.includes("code") && rebuildClient && this.batchTouchesPagesTree(appDir, expandedBatch)) {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
 
-    if (kinds.includes("code") && this.#shouldRebuildCsr()) {
+    if (kinds.includes("code") && rebuildClient && this.#shouldRebuildCsr()) {
       try {
         const started = Date.now();
         await new CsrArtifactBuilder(this.#app).build();
@@ -327,13 +334,13 @@ class IncrementalBuilder {
         this.#logger.error(`csr-rebundle failed: ${message}`);
         this.#sendBuildStatus("csr", { generation, ok: false, files, message });
       }
-    } else if (kinds.includes("code")) {
+    } else if (kinds.includes("code") && rebuildClient) {
       this.#logger.verbose(`csr-rebundle skipped; set AKAN_DEV_CSR_REBUILD=1 to enable per-save CSR rebuilds`);
     }
 
     process.send?.(event);
 
-    if (kinds.includes("code")) {
+    if (kinds.includes("code") && rebuildClient) {
       try {
         const started = Date.now();
         const next = await new PagesBundleBuilder(this.#app).build();
@@ -349,7 +356,9 @@ class IncrementalBuilder {
         this.#sendBuildStatus("pages", { generation, ok: false, files, message });
       }
     }
-    if (kinds.includes("code") || kinds.includes("css")) {
+    // Server-only code edits cannot introduce class names the CSS scanner would pick up; only a
+    // client rebuild or a direct stylesheet edit can change the compiled CSS.
+    if (kinds.includes("css") || (kinds.includes("code") && rebuildClient)) {
       this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
@@ -368,6 +377,12 @@ class IncrementalBuilder {
           return;
       }
     });
+    // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
+    // as an orphaned watcher that keeps rebuilding for nobody.
+    process.on("disconnect", () => {
+      this.#logger.warn("host IPC channel closed; exiting builder");
+      process.exit(0);
+    });
     if (this.#watch) await this.installWatcher();
     process.send?.({ type: "builder-ready" });
     this.#logger.verbose(`ready (watch=${this.#watch})`);

package/integration/devStability.integration.test.ts

@@ -45,6 +45,50 @@ const waitForFileIncludes = async (filePath: string, text: string, timeoutMs = 5
   return null;
 };
 
+interface GatewayHealth {
+  status: string;
+  pid?: number;
+  children: Array<{ idx: number; role: string; status: string; ready: boolean; pid?: number }>;
+}
+
+const fetchGatewayHealth = async (port: number): Promise<GatewayHealth | null> => {
+  const res = await fetch(`http://127.0.0.1:${port}/_akan/app/health`).catch(() => null);
+  if (!res?.ok) return null;
+  return (await res.json()) as GatewayHealth;
+};
+
+const waitForGatewayHealth = async (
+  port: number,
+  predicate: (health: GatewayHealth) => boolean,
+  timeoutMs = 60_000,
+): Promise<GatewayHealth> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const health = await fetchGatewayHealth(port);
+    if (health && predicate(health)) return health;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error(`Timed out waiting for gateway health on port ${port}`);
+};
+
+const isProcessAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const waitForProcessesGone = async (pids: number[], timeoutMs = 15_000): Promise<boolean> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    if (pids.every((pid) => !isProcessAlive(pid))) return true;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return false;
+};
+
 afterEach(async () => {
   await Promise.all(harnesses.splice(0).map((harness) => harness.cleanup()));
 });
@@ -159,6 +203,32 @@ export const dictionary = serviceDictionary(["en", "ko"])
     hmr?.close();
   });
 
+  integrationTest("config edits restart the dev host and keep serving", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const initialHtml = await harness.tryWaitForHttpText("initial-shared-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      return;
+    }
+    const mark = host.markLog();
+
+    await harness.writeFile(
+      "akan.config.ts",
+      `import type { AppConfig } from "akanjs";
+
+const config: AppConfig = { externalLibs: [] };
+export default config;
+`,
+    );
+
+    await host.waitForLogSince(mark, /\[dev-plan\].*actions=.*restart-dev-host/);
+    await host.waitForLogSince(mark, /\[dev-host\] config change detected; restarting dev host/);
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    await harness.waitForHttpText("initial-shared-marker");
+    expect(host.proc.killed).toBe(false);
+  });
+
   integrationTest("client build failure reports error and recovers after fix", async () => {
     const harness = await createHarness();
     const host = await harness.startHost();
@@ -205,16 +275,20 @@ export const dictionary = serviceDictionary(["en", "ko"])
   integrationTest("barrel add/delete includes generated indexes in watch generation", async () => {
     const harness = await createHarness();
     const sync = new DevGeneratedIndexSync({ workspaceRoot: harness.workspaceRoot });
-    const facets = ["common", "ui"] as const;
-
-    for (const facet of facets) {
-      const exportName = `${facet}TmpExample`;
+    // `common` barrels export camelCase names; `ui` barrels export PascalCase component names. Each facet's
+    // fixture file must follow its own casing convention or the barrel deliberately skips it.
+    const facets = [
+      { facet: "common", moduleName: "tmpExample", fileName: "tmpExample.ts", exportName: "commonTmpExample" },
+      { facet: "ui", moduleName: "TmpExample", fileName: "TmpExample.tsx", exportName: "TmpExample" },
+    ] as const;
+
+    for (const { facet, moduleName, fileName, exportName } of facets) {
       const indexPath = `${facet}/index.ts`;
-      const absChangedFile = `${harness.appDir}/${facet}/tmpExample.ts`;
+      const absChangedFile = `${harness.appDir}/${facet}/${fileName}`;
       const absIndexPath = `${harness.appDir}/${indexPath}`;
 
       await harness.writeFile(
-        `${facet}/tmpExample.ts`,
+        `${facet}/${fileName}`,
         `export const ${exportName} = "added-${facet}-example";
 `,
       );
@@ -222,21 +296,105 @@ export const dictionary = serviceDictionary(["en", "ko"])
       const added = await sync.syncForBatch([absChangedFile]);
       expect(added.errors).toEqual([]);
       expect(added.changedFiles).toContain(absIndexPath);
-      const addedIndex = await waitForFileIncludes(absIndexPath, "tmpExample");
+      const addedIndex = await waitForFileIncludes(absIndexPath, moduleName);
       expect(addedIndex).not.toBeNull();
-      expect(addedIndex ?? "").toContain("tmpExample");
+      expect(addedIndex ?? "").toContain(moduleName);
 
-      await harness.removeFile(`${facet}/tmpExample.ts`);
+      await harness.removeFile(`${facet}/${fileName}`);
       const removed = await sync.syncForBatch([absChangedFile]);
       expect(removed.errors).toEqual([]);
       expect(removed.changedFiles).toContain(absIndexPath);
-      const deletedIndex = await waitForFileIncludes(absIndexPath, "tmpExample", 1_000);
-      if (deletedIndex) throw new Error(`${indexPath} still contains tmpExample after delete`);
+      const deletedIndex = await waitForFileIncludes(absIndexPath, moduleName, 1_000);
+      if (deletedIndex) throw new Error(`${indexPath} still contains ${moduleName} after delete`);
       const finalIndex = await Bun.file(absIndexPath).text();
       expect(finalIndex).toBeString();
     }
   });
 
+  integrationTest("backend boot failure stops the crash loop, surfaces build-status, and recovers on fix", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const failureMark = host.markLog();
+
+    // The service file is part of the generated server graph (`akan start` regenerates server.ts
+    // from lib/), so a module-level throw here breaks every replica boot.
+    await harness.writeFile(
+      "lib/_fixture/fixture.service.ts",
+      `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+
+throw new Error("intentional-backend-boot-crash");
+`,
+    );
+
+    // The gateway abandons the replica after three failed boots instead of retrying forever...
+    await host.waitForLogSince(failureMark, /\[child-crash-loop\].*failed 3 consecutive boots/);
+    // ...and the failure reaches the dev host's build-status pipeline (HMR overlay path).
+    await host.waitForLogSince(failureMark, /\[build-status\].*phase=backend.*ok=false/);
+    expect(host.proc.killed).toBe(false);
+
+    const recoveryMark = host.markLog();
+    await harness.writeFile(
+      "lib/_fixture/fixture.service.ts",
+      `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+`,
+    );
+
+    await host.waitForLogSince(recoveryMark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    expect(host.proc.killed).toBe(false);
+  });
+
+  integrationTest("SIGKILL'd gateway leaves no orphaned replicas and the host recovers", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const port = await harness.resolvePort();
+
+    const healthy = await waitForGatewayHealth(
+      port,
+      (health) =>
+        typeof health.pid === "number" &&
+        health.children.length > 0 &&
+        health.children.every((child) => child.ready && typeof child.pid === "number"),
+    );
+    const gatewayPid = healthy.pid as number;
+    const childPids = healthy.children.map((child) => child.pid as number);
+    const mark = host.markLog();
+
+    process.kill(gatewayPid, "SIGKILL");
+
+    // Children must notice the closed IPC channel and exit instead of orphaning (they would
+    // otherwise keep holding their ws ports and break every subsequent boot).
+    expect(await waitForProcessesGone(childPids)).toBe(true);
+
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    const recovered = await waitForGatewayHealth(
+      port,
+      (health) => typeof health.pid === "number" && health.pid !== gatewayPid && health.children.some((c) => c.ready),
+    );
+    expect(recovered.pid).not.toBe(gatewayPid);
+    expect(host.proc.killed).toBe(false);
+  });
+
+  integrationTest("occupied preferred ws port falls back to an ephemeral port and stays bootable", async () => {
+    const harness = await createHarness();
+    const port = await harness.resolvePort();
+    // The gateway assigns child 0 the deterministic ws port `port + 10_000`; occupy it up front
+    // the way an orphaned replica from a killed run would.
+    const blocker = Bun.serve({ port: port + 10_000, fetch: () => new Response("occupied") });
+    try {
+      const host = await harness.startHost();
+      await host.waitForLog(/falling back to an ephemeral port/);
+      const health = await waitForGatewayHealth(port, (h) => h.children.some((child) => child.ready));
+      expect(health.children.some((child) => child.ready)).toBe(true);
+      expect(host.proc.killed).toBe(false);
+    } finally {
+      blocker.stop(true);
+    }
+  });
+
   integrationTest("route and css phase-5 scope remains smoke-level in this harness", async () => {
     const manualSmoke = [
       "route add/delete should be covered by a later browser-driven test",

package/integration/devStabilityHarness.ts

@@ -259,6 +259,9 @@ export const dictionary = serviceDictionary(["en", "ko"])
       env: {
         ...process.env,
         AKAN_VERBOSE: "1",
+        // The dev-plan/hmr assertions match verbose-level Logger lines; without this the log
+        // stream only carries info/warn/error and those waits time out with empty tails.
+        AKAN_PUBLIC_LOG_LEVEL: "verbose",
         NODE_NO_WARNINGS: "1",
         PORT_OFFSET: String(this.portOffset),
       },
@@ -422,9 +425,21 @@ export const dictionary = serviceDictionary(["en", "ko"])
   }
 
   async resolvePort(): Promise<number> {
-    const apps = await readdir(path.join(this.workspaceRoot, "apps")).catch(() => []);
-    const appIndex = Math.max([...new Set([...apps, this.appName])].sort().indexOf(this.appName), 0);
-    return 8282 + appIndex + this.portOffset;
+    // Mirror the CLI's `getDevPort()` exactly (apps = directories containing akan.config.ts,
+    // locale-sorted): counting stray entries like .DS_Store would put us one port off the gateway.
+    const appsDir = path.join(this.workspaceRoot, "apps");
+    const entries = await readdir(appsDir, { withFileTypes: true }).catch(() => []);
+    const checked = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) =>
+          (await Bun.file(path.join(appsDir, entry.name, "akan.config.ts")).exists()) ? entry.name : null,
+        ),
+    );
+    const apps = [...new Set([...checked.filter((name): name is string => name !== null), this.appName])].sort((a, b) =>
+      a.localeCompare(b),
+    );
+    return 8282 + Math.max(apps.indexOf(this.appName), 0) + this.portOffset;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.0-rc.0",
+  "version": "2.4.0-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -32,7 +32,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.0-rc.0",
+    "akanjs": "2.4.0-rc.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/scanInfo.ts

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { rm } from "node:fs/promises";
+import path from "node:path";
 import type {
   AppConfigResult,
   AppScanResult,
@@ -71,6 +71,7 @@ const appRootAllowedDirs = new Set([
   "srvkit",
   "webkit",
   "common",
+  "secrets",
 ]);
 const libRootAllowedFiles = new Set([
   "cnst.ts",