akanjs 2.3.13 → 2.4.0-rc.1

package/client/csrTypes.ts

@@ -16,6 +16,20 @@ export type PageSafeAreaConfig =
       bottom?: boolean;
       android?: "auto" | "edge-to-edge" | "none";
     };
+/**
+ * Server-render strategy for the initial full-document SSR pass.
+ * - `"stream"` (default): flush the shell — including any `Loading` Suspense
+ *   fallback — as soon as it is ready, then stream the resolved page. Redirects
+ *   decided in the shell still become real HTTP redirects; redirects thrown
+ *   inside suspended content degrade to soft (client) redirects.
+ * - `"block"`: buffer the whole document until every Suspense boundary resolves
+ *   before sending a byte. The `Loading` fallback never reaches the browser, but
+ *   a non-redirect error thrown in slow content can still yield a clean error
+ *   page. Use only for routes that need that guarantee and do not care about SEO
+ *   or first-paint of the fallback.
+ */
+export type SsrRenderMode = "stream" | "block";
+
 /** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
   transition?: TransitionType;
@@ -26,6 +40,8 @@ export interface PageConfig {
   bottomInset?: number | boolean;
   gesture?: boolean;
   cache?: boolean;
+  /** Initial full-document SSR strategy. Defaults to `"stream"`. */
+  ssr?: SsrRenderMode;
   /**
    * Opt in to guarded RSC page suffix commits when the page does not require
    * head/metadata updates and the retained route chain head is invariant for
@@ -44,6 +60,7 @@ export interface CsrState {
   bottomInset: number;
   gesture: boolean;
   cache: boolean;
+  ssr: SsrRenderMode;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
 }
@@ -99,6 +116,9 @@ export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
   Loading?: LayoutLoadingRender | PageLoadingRender;
+  /** Loads the module and populates `Loading` without running `render`/`resolveHead`.
+   * Used by the patch (suffix) compose path, which never calls `resolveHead`. */
+  resolveLoading?: () => void | Promise<void>;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
   resolveNotFound?: () => PromiseOrObject<LayoutNotFoundRender | undefined>;
@@ -242,6 +262,7 @@ export const defaultPageState: PageState = {
   bottomInset: 0,
   gesture: true,
   cache: false,
+  ssr: "stream",
   topSafeAreaColor: "var(--color-base-100, Canvas)",
   bottomSafeAreaColor: "var(--color-base-100, Canvas)",
 };

package/client/frameConfig.ts

@@ -1,4 +1,4 @@
-import type { PageConfig, PageSafeAreaConfig, PageState, TransitionType } from "./csrTypes";
+import type { PageConfig, PageSafeAreaConfig, PageState, SsrRenderMode, TransitionType } from "./csrTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
 export type SafeAreaInsets = { top: number; bottom: number };
@@ -19,11 +19,13 @@ const pageConfigKeys = new Set<keyof PageConfig>([
   "bottomInset",
   "gesture",
   "cache",
+  "ssr",
   "rscPatchHeadSafe",
   "topSafeAreaColor",
   "bottomSafeAreaColor",
 ]);
 const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "stack", "scaleOut"]);
+const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -43,6 +45,9 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (pageConfig.transition !== undefined && !transitionTypes.has(pageConfig.transition)) {
     throw new Error(`[route-convention] unsupported pageConfig.transition "${pageConfig.transition}" in ${routeKey}`);
   }
+  if (pageConfig.ssr !== undefined && !ssrRenderModes.has(pageConfig.ssr)) {
+    throw new Error(`[route-convention] unsupported pageConfig.ssr "${pageConfig.ssr}" in ${routeKey}`);
+  }
   if (pageConfig.topInset !== undefined && !isValidInsetValue(pageConfig.topInset)) {
     throw new Error(
       `[route-convention] pageConfig.topInset in ${routeKey} must be a boolean or non-negative px number.`,
@@ -141,6 +146,7 @@ export function resolvePageState({
         ? false
         : (config.gesture ?? false),
     cache: config.cache ?? false,
+    ssr: config.ssr ?? "stream",
     topSafeAreaColor: config.topSafeAreaColor ?? "var(--color-base-100, Canvas)",
     bottomSafeAreaColor: config.bottomSafeAreaColor ?? "var(--color-base-100, Canvas)",
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.3.13",
+  "version": "2.4.0-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -195,6 +195,7 @@
     "bullmq": "^5.76.10",
     "capacitor-plugin-safe-area": "^5.0.0",
     "chance": "^1.1.13",
+    "cordova-plugin-purchase": "^13.16.0",
     "croner": "^10.0.1",
     "daisyui": "5.5.23",
     "firebase": "^12.13.0",
@@ -279,6 +280,9 @@
     "chance": {
       "optional": true
     },
+    "cordova-plugin-purchase": {
+      "optional": true
+    },
     "croner": {
       "optional": true
     },

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0001.log

@@ -0,0 +1,4 @@
+[AkanApp] 39364 - 07/21/2026, 04:19:57 AM    INFO  AkanApp gateway is running on port http://localhost:32283 +499ms
+[AkanApp] 39364 - 07/21/2026, 04:19:57 AM VERBOSE  All 1 child process(es) are ready +512ms
+[AkanApp] 39364 - 07/21/2026, 04:19:57 AM   ERROR  Child 0/federation failed (exit:1); restarting in 1000ms (attempt 1) +565ms
+[AkanApp] 39364 - 07/21/2026, 04:19:58 AM VERBOSE  All 1 child process(es) are ready +1582ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0002.log

@@ -0,0 +1,5 @@
+[AkanApp] 39364 - 07/21/2026, 04:19:58 AM    INFO  AkanApp gateway is running on port http://localhost:30883 +1587ms
+[AkanApp] 39364 - 07/21/2026, 04:19:58 AM VERBOSE  All 1 child process(es) are ready +1599ms
+[AkanApp] 39364 - 07/21/2026, 04:19:58 AM   ERROR  Child 0/federation upstream is unreachable (/Users/kangminseon/github3/leading-flight-guidance/pkgs/akanjs/runtime/akan-child-39364-mru5abmz-0.sock); restarting +1740ms
+[AkanApp] 39364 - 07/21/2026, 04:19:58 AM   ERROR  Child 0/federation failed (upstream-open-failed); restarting in 1000ms (attempt 1) +1740ms
+[AkanApp] 39364 - 07/21/2026, 04:19:59 AM VERBOSE  All 1 child process(es) are ready +2760ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0003.log

@@ -0,0 +1,7 @@
+[AkanApp] 39364 - 07/21/2026, 04:19:59 AM    INFO  AkanApp gateway is running on port http://localhost:24583 +2773ms
+[AkanApp] 39364 - 07/21/2026, 04:19:59 AM   ERROR  intentional-boot-failure +2783ms
+[AkanApp] 39364 - 07/21/2026, 04:19:59 AM   ERROR  Child 0/federation failed (child-error); restarting in 1000ms (attempt 1) +2783ms
+[AkanApp] 39364 - 07/21/2026, 04:20:00 AM   ERROR  intentional-boot-failure +3799ms
+[AkanApp] 39364 - 07/21/2026, 04:20:00 AM   ERROR  Child 0/federation failed (child-error); restarting in 2000ms (attempt 2) +3799ms
+[AkanApp] 39364 - 07/21/2026, 04:20:02 AM   ERROR  intentional-boot-failure +5817ms
+[AkanApp] 39364 - 07/21/2026, 04:20:02 AM   ERROR  [child-crash-loop] Backend replica 0/federation failed 3 consecutive boots; waiting for a code change to retry: intentional-boot-failure +5817ms

package/runtime/logs/serverGet-local-local-2026-07-21-gateway-0004.log

@@ -0,0 +1,2 @@
+[AkanApp] 39364 - 07/21/2026, 04:20:03 AM    INFO  AkanApp gateway is running on port http://localhost:24132 +7360ms
+[AkanApp] 39364 - 07/21/2026, 04:20:03 AM VERBOSE  All 1 child process(es) are ready +7373ms

package/server/akanApp.ts

@@ -1,10 +1,11 @@
-import { mkdir, rm } from "node:fs/promises";
+import { mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { AkanChildRole, AkanChildStatus, AkanIpcMessage, AkanMetricsReport, AkanUpstream } from "akanjs/service";
 import { isTraceEnabled } from "akanjs/signal";
 import { makeAkanChildProxyHeaders } from "./akanAppHeaders";
 import type { BuilderMessage, BuilderReq, BuilderRes } from "./artifact";
+import { isPortInUseError } from "./lifecycle/portInUse";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 
@@ -16,9 +17,11 @@ interface ChildState {
   status: AkanChildStatus;
   pid?: number;
   upstream?: AkanUpstream;
+  wsUpstream?: Extract<AkanUpstream, { type: "tcp" }>;
   healthPath?: string;
   metrics: AkanMetricsReport;
-  lastPongAt?: number;
+  /** Monotonic (`performance.now()`) so sleep/wake wall-clock jumps cannot fake a health timeout. */
+  lastPongAtMono?: number;
   restartAttempts: number;
   restartCount: number;
   restartTimer: Timer | null;
@@ -26,6 +29,7 @@ interface ChildState {
   lastExitCode?: number | null;
   lastRestartAt?: number;
   lastRestartReason?: string;
+  lastErrorMessage?: string;
 }
 
 interface GatewayWsData {
@@ -62,8 +66,13 @@ export class AkanApp {
   static readonly #childRestartBaseDelayMs = 1_000;
   static readonly #childRestartMaxDelayMs = 30_000;
   static readonly #childRestartGraceMs = 5_000;
+  /** In dev, stop restarting a replica that never boots after this many consecutive failures. */
+  static readonly #devMaxChildBootFailures = 3;
 
   readonly logger = new Logger("AkanApp");
+  /** Hosted by `akan start`: crash loops should yield to the dev host, which restarts on file edits. */
+  readonly #devHosted = process.env.AKAN_COMMAND_TYPE === "start";
+  readonly #healthTimeoutMs = AkanApp.#parseHealthTimeoutMs();
   readonly #serverPath: string;
   readonly #artifactDir: string;
   readonly #replica: AkanReplicaConfig;
@@ -149,15 +158,46 @@ export class AkanApp {
     return Bun.main.endsWith(".js") ? "production" : "development";
   }
 
+  /**
+   * Dev builds and first-touch transpiles can stall a child's event loop well past the production
+   * pong budget, so `akan start` runs with a wider timeout to avoid restarting healthy replicas.
+   */
+  static #parseHealthTimeoutMs() {
+    const configured = Number(process.env.AKAN_HEALTH_TIMEOUT_MS);
+    if (Number.isFinite(configured) && configured > 0) return configured;
+    return process.env.AKAN_COMMAND_TYPE === "start" ? 15_000 : 5_000;
+  }
+
+  /**
+   * Must exceed the child's own shutdown timeout (see `AkanServer.#defaultShutdownTimeoutMs`) so
+   * children always get to exit on their own before this gateway stops waiting.
+   */
+  static #childShutdownWaitMs() {
+    const configured = Number(process.env.AKAN_CHILD_SHUTDOWN_WAIT_MS);
+    if (Number.isFinite(configured) && configured > 0) return configured;
+    return process.env.AKAN_COMMAND_TYPE === "start" ? 5_000 : 30_000;
+  }
+
   async start() {
     await this.#prepareRuntimeDir();
     this.#startFileLogging();
     for (let idx = 0; idx < this.#replica.total; idx++) this.#spawn(idx);
-    this.#listen();
+    try {
+      this.#listen();
+    } catch (error) {
+      if (isPortInUseError(error)) {
+        const message = `Port ${this.#port} is already in use — another \`akan start\` or an orphaned gateway may still be running (try: lsof -ti :${this.#port}).`;
+        this.logger.error(message);
+        this.#reportBackendBuildStatus({ ok: false, message });
+      }
+      await this.stop("listen-failed");
+      throw error;
+    }
     this.#snapshotTimer = setInterval(() => this.#requestRoomSnapshots(), 30_000);
     this.#healthTimer = setInterval(() => this.#checkHealth(), 2_000);
     this.#startMetricsReporting();
     process.on("message", (message) => this.#handleHostMessage(message as BuilderMessage));
+    process.on("disconnect", () => this.#handleHostDisconnect());
     process.on("SIGINT", () => this.#handleShutdownSignal("SIGINT"));
     process.on("SIGTERM", () => this.#handleShutdownSignal("SIGTERM"));
     await new Promise<void>((resolve) => {
@@ -192,7 +232,7 @@ export class AkanApp {
     }
     await Promise.race([
       Promise.all([...this.#children.values()].map((child) => child.proc.exited.catch(() => undefined))),
-      new Promise((resolve) => setTimeout(resolve, 30_000)),
+      new Promise((resolve) => setTimeout(resolve, AkanApp.#childShutdownWaitMs())),
     ]);
     for (const child of this.#children.values()) {
       if (!child.proc.killed) child.proc.kill();
@@ -213,6 +253,18 @@ export class AkanApp {
     });
   }
 
+  /**
+   * The IPC channel closes when the dev host dies (including SIGKILL). Exiting takes the children
+   * down too, so a dead host never strands a gateway tree that would block the next `akan start`.
+   */
+  #handleHostDisconnect() {
+    if (this.#stopping) return;
+    this.logger.warn("Host IPC channel closed; shutting down gateway and children");
+    this.#exitAfterStop = true;
+    setTimeout(() => process.exit(1), AkanApp.#childShutdownWaitMs() + 5_000);
+    void this.stop("ipc-disconnect").catch(() => process.exit(1));
+  }
+
   #spawn(idx: number) {
     const role = this.#getRole(idx);
     const upstream = this.#getChildUpstream(idx, role);
@@ -261,6 +313,7 @@ export class AkanApp {
   #handleChildExit(idx: number, proc: Bun.Subprocess<"ignore", "pipe", "pipe">, code: number | null) {
     const child = this.#children.get(idx);
     if (!child || child.proc !== proc) return;
+    if (child.status === "crashed") return;
     child.status = "exited";
     child.lastExitCode = code;
     this.#invalidateFederationChildCache();
@@ -276,11 +329,16 @@ export class AkanApp {
       child.lastRestartReason = reason;
       return;
     }
+    if (this.#devHosted && child.restartAttempts >= AkanApp.#devMaxChildBootFailures - 1 && !child.ready) {
+      this.#markChildCrashed(child, reason);
+      return;
+    }
 
     child.restartPending = true;
     child.ready = false;
     child.status = reason === "health-timeout" || reason === "upstream-open-failed" ? "unhealthy" : "exited";
     child.upstream = undefined;
+    child.wsUpstream = undefined;
     child.healthPath = undefined;
     this.#invalidateFederationChildCache();
     child.lastRestartReason = reason;
@@ -341,6 +399,41 @@ export class AkanApp {
     this.#spawn(idx);
   }
 
+  /**
+   * Dev-only terminal state: the same broken code fails every boot, so retrying is pure churn.
+   * The dev host replaces this whole gateway on the next server-side edit, which clears the state.
+   */
+  #markChildCrashed(child: ChildState, reason: string) {
+    
+    if (child.status === "crashed") return;
+    child.ready = false;
+    child.status = "crashed";
+    child.restartPending = false;
+    child.upstream = undefined;
+    child.wsUpstream = undefined;
+    child.healthPath = undefined;
+    child.lastRestartReason = reason;
+    this.#invalidateFederationChildCache();
+    this.#removeChildRooms(child.idx);
+    const attempts = child.restartAttempts + 1;
+    const detail = child.lastErrorMessage ?? reason;
+    const message = `Backend replica ${child.idx}/${child.role} failed ${attempts} consecutive boots; waiting for a code change to retry: ${detail}`;
+    this.logger.error(`[child-crash-loop] ${message}`);
+    this.#reportBackendBuildStatus({ ok: false, message });
+  }
+
+  /** Forwards a backend-phase build status to the dev host so failures reach the HMR overlay. */
+  #reportBackendBuildStatus({ ok, message }: { ok: boolean; message: string }) {
+    process.send?.({
+      type: "build-status",
+      data: { generation: -1, phase: "backend", ok, files: [], message },
+    } satisfies BuilderMessage);
+  }
+
+  #isChildUnavailable(child: ChildState): boolean {
+    return child.proc.killed || child.status === "exited" || child.status === "crashed";
+  }
+
   async #stopChildForRestart(child: ChildState, proc: Bun.Subprocess<"ignore", "pipe", "pipe">, reason: string) {
     if (reason.startsWith("exit:") || proc.killed) return;
     if (!proc.killed) {
@@ -359,9 +452,13 @@ export class AkanApp {
 
   async #prepareRuntimeDir() {
     await mkdir(this.#runtimeDir, { recursive: true });
-    for (let idx = 0; idx < this.#replica.total; idx++) {
-      await this.#removeChildSocket(idx, this.#getRole(idx));
-    }
+
+    const entries = await readdir(this.#runtimeDir).catch(() => []);
+    await Promise.all(
+      entries
+        .filter((name) => /^akan-child-.*\.sock$/.test(name))
+        .map((name) => rm(path.join(this.#runtimeDir, name), { force: true }).catch(() => undefined)),
+    );
   }
 
   async #removeChildSocket(idx: number, role: AkanChildRole) {
@@ -455,11 +552,9 @@ export class AkanApp {
 
   #upgradeWebSocket(req: Request, server: Bun.Server<GatewayWsData>): Response | undefined {
     const child = this.#pickFederationChild();
-    if (!child?.upstream || !child.upstream || !this.#getChildUpstream(child.idx, child.role).ws) {
-      return new Response("No websocket upstream is ready", { status: 503 });
-    }
-    const upstream = this.#getChildUpstream(child.idx, child.role).ws;
-    if (!upstream) return new Response("No websocket upstream is ready", { status: 503 });
+
+    const upstream = child?.upstream ? (child.wsUpstream ?? this.#getChildUpstream(child.idx, child.role).ws) : null;
+    if (!child || !upstream) return new Response("No websocket upstream is ready", { status: 503 });
     const url = new URL(req.url);
     const upstreamWs = new WebSocket(`ws://${upstream.host}:${upstream.port}${url.pathname}${url.search}`, {
       headers: this.#makeProxyHeaders(req, child.idx),
@@ -513,6 +608,7 @@ export class AkanApp {
   #getHealthStatus() {
     return {
       status: this.#stopping ? "stopping" : "running",
+      pid: process.pid,
       children: [...this.#children.values()].map((child) => ({
         idx: child.idx,
         role: child.role,
@@ -526,6 +622,7 @@ export class AkanApp {
         lastExitCode: child.lastExitCode,
         lastRestartAt: child.lastRestartAt,
         lastRestartReason: child.lastRestartReason,
+        lastErrorMessage: child.lastErrorMessage,
       })),
     };
   }
@@ -709,8 +806,7 @@ export class AkanApp {
           (child.role === "federation" || child.role === "all") &&
           child.ready &&
           child.status !== "unhealthy" &&
-          child.status !== "exited" &&
-          !child.proc.killed,
+          !this.#isChildUnavailable(child),
       );
     this.#federationChildCache = candidates;
     if (candidates.length === 0) return null;
@@ -767,6 +863,7 @@ export class AkanApp {
         return;
       case "error":
         this.logger.error(message.message);
+        if (child) child.lastErrorMessage = message.message;
         if (child && proc) void this.#scheduleChildRestart(child, proc, "child-error");
         return;
       case "build-route":
@@ -798,13 +895,19 @@ export class AkanApp {
     child.status = "ready";
     child.pid = message.pid;
     child.upstream = message.upstream;
+    child.wsUpstream = message.wsUpstream;
     child.healthPath = message.healthPath;
-    child.lastPongAt = Date.now();
+    child.lastPongAtMono = performance.now();
     child.restartAttempts = 0;
     child.restartPending = false;
+    child.lastErrorMessage = undefined;
     this.#invalidateFederationChildCache();
-    if ([...this.#children.values()].every((item) => item.ready)) {
+    
+    const trafficChildren = [...this.#children.values()].filter((item) => item.role !== "batch");
+    if (child.role !== "batch" && trafficChildren.every((item) => item.ready)) {
       process.send?.({ type: "backend-ready", pid: process.pid } satisfies AkanIpcMessage);
+    }
+    if ([...this.#children.values()].every((item) => item.ready)) {
       this.logger.verbose(`All ${this.#children.size} child process(es) are ready`);
     }
   }
@@ -813,7 +916,7 @@ export class AkanApp {
     const child = this.#children.get(idx);
     if (!child) return;
     child.status = "healthy";
-    child.lastPongAt = Date.now();
+    child.lastPongAtMono = performance.now();
     this.#invalidateFederationChildCache();
   }
 
@@ -828,7 +931,7 @@ export class AkanApp {
     for (const childIdx of targets) {
       if (childIdx === originIdx) continue;
       const child = this.#children.get(childIdx);
-      if (!child || child.proc.killed || child.status === "exited") continue;
+      if (!child || this.#isChildUnavailable(child)) continue;
       if (
         !this.#sendToChild(child, {
           type: "pubsub.deliver",
@@ -935,31 +1038,30 @@ export class AkanApp {
 
   #requestRoomSnapshots() {
     for (const child of this.#children.values()) {
-      if (child.proc.killed || child.status === "exited") continue;
+      if (this.#isChildUnavailable(child)) continue;
       this.#sendToChild(child, { type: "pubsub.snapshot.request" } satisfies AkanIpcMessage);
     }
   }
 
   #checkHealth() {
-    const now = Date.now();
+    const nowMono = performance.now();
     for (const child of this.#children.values()) {
-      if (child.proc.killed || child.status === "exited") continue;
-      if (child.lastPongAt && now - child.lastPongAt > 5_000) {
+      if (this.#isChildUnavailable(child)) continue;
+      if (child.lastPongAtMono && nowMono - child.lastPongAtMono > this.#healthTimeoutMs) {
         child.status = "unhealthy";
         this.#invalidateFederationChildCache();
         void this.#scheduleChildRestart(child, child.proc, "health-timeout");
-        return;
+        continue;
       }
       const sent = this.#sendToChild(child, {
         type: "health.ping",
         nonce: crypto.randomUUID(),
-        sentAt: now,
+        sentAt: Date.now(),
       } satisfies AkanIpcMessage);
       if (!sent) {
         child.status = "unhealthy";
         this.#invalidateFederationChildCache();
         void this.#scheduleChildRestart(child, child.proc, "health-send-failed");
-        return;
       }
     }
   }
@@ -1000,7 +1102,7 @@ export class AkanApp {
   }
 
   #sendToChild(child: ChildState, message: AkanIpcMessage | BuilderMessage): boolean {
-    if (child.proc.killed || child.status === "exited") return false;
+    if (this.#isChildUnavailable(child)) return false;
     try {
       child.proc.send(message);
       return true;

package/server/akanServer.ts

@@ -16,6 +16,7 @@ import type { AkanLib, AkanLibProps } from "./akanLib";
 import type { BuilderRpc } from "./artifact";
 import { DiLifecycle } from "./di/diLifecycle";
 import type { HmrWsData, HmrWsHub } from "./hmr/wsHub";
+import { isPortInUseError } from "./lifecycle/portInUse";
 import { ShutdownManager } from "./lifecycle/shutdownManager";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
@@ -74,7 +75,7 @@ export class AkanServer {
   websocketPrefix = "/ws";
   openapi = AkanServer.#isOpenApiEnvEnabled();
   serverMode: "federation" | "batch" | "all";
-  shutdownTimeoutMs = 30_000;
+  shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
   #di: DiLifecycle;
   #localPublish: ((roomId: string, data: object | object[]) => void) | null = null;
@@ -257,10 +258,10 @@ export class AkanServer {
       websocket: websocketHandlers,
     } as Parameters<typeof Bun.serve>[0]);
     if (unix && process.env.AKAN_CHILD_WS_PORT) {
-      const wsPort = Number(process.env.AKAN_CHILD_WS_PORT);
-      this.#wsServer = Bun.serve({
+      const preferredWsPort = Number(process.env.AKAN_CHILD_WS_PORT);
+      const wsServeOptions = (port: number) => ({
         idleTimeout: 0,
-        port: wsPort,
+        port,
         routes: ApiRouter.buildRoutes({
           prefix: this.prefix,
           websocketPrefix: this.websocketPrefix,
@@ -268,12 +269,20 @@ export class AkanServer {
           builtinRoutes,
           routeOptions,
           renderEnvRoutes,
-          upgradeAppWs: (req, data) => this.#wsServer?.upgrade(req, { data }) ?? false,
+          upgradeAppWs: (req: Request, data: { createdAt: number }) => this.#wsServer?.upgrade(req, { data }) ?? false,
           webProxyRunner,
         }),
         websocket: websocketHandlers,
       });
-      this.logger.verbose(`${this.name} websocket fallback is serving on port ${wsPort}`);
+      try {
+        this.#wsServer = Bun.serve(wsServeOptions(preferredWsPort));
+      } catch (error) {
+        if (!isPortInUseError(error)) throw error;
+
+        this.logger.warn(`ws port ${preferredWsPort} is in use; falling back to an ephemeral port`);
+        this.#wsServer = Bun.serve(wsServeOptions(0));
+      }
+      this.logger.verbose(`${this.name} websocket fallback is serving on port ${this.#wsServer.port}`);
     }
 
     const server = this.#server;
@@ -300,12 +309,14 @@ export class AkanServer {
     this.#startMetricsReporting();
     this.#di.registerSchedule(this.serverMode);
     this.logger.verbose(`🚀 ${this.name} is running on ${unix ? `unix://${unix}` : `port ${port}`}`);
+    const wsPort = this.#wsServer?.port;
     process.send?.({
       type: "ready",
       pid: process.pid,
       replicaIdx: Number(process.env.AKAN_REPLICA_IDX ?? 0),
       role: this.serverMode,
       upstream: unix ? { type: "unix", socketPath: unix } : { type: "tcp", host: "127.0.0.1", port: Number(port) },
+      wsUpstream: typeof wsPort === "number" ? { type: "tcp", host: "127.0.0.1", port: wsPort } : undefined,
       healthPath: "/_akan/app/child-health",
     } satisfies AkanIpcMessage);
     await this.#di.runSchedulerInit();
@@ -324,7 +335,7 @@ export class AkanServer {
       if (!isNoListenCommand) {
         this.#startMetricsReporting();
         this.#di.registerSchedule(this.serverMode);
-        process.on("message", (message) => this.#handleIpcMessage(message as AkanIpcMessage));
+        this.#registerParentIpc();
         process.send?.({
           type: "ready",
           pid: process.pid,
@@ -336,7 +347,7 @@ export class AkanServer {
       }
       return this;
     }
-    process.on("message", (message) => this.#handleIpcMessage(message as AkanIpcMessage));
+    this.#registerParentIpc();
     return this.listen();
   }
   async stop() {
@@ -368,6 +379,23 @@ export class AkanServer {
     }
   }
 
+  #registerParentIpc() {
+    process.on("message", (message) => this.#handleIpcMessage(message as AkanIpcMessage));
+    process.on("disconnect", () => this.#handleParentDisconnect());
+  }
+
+  /**
+   * The IPC channel closes when the parent gateway dies (including SIGKILL). Exiting here keeps a
+   * killed dev/gateway run from stranding replicas that would hold ports and break the next boot.
+   */
+  #handleParentDisconnect() {
+    this.logger.warn("Parent IPC channel closed; shutting down to avoid an orphaned replica");
+    setTimeout(() => process.exit(1), this.shutdownTimeoutMs + 1_000);
+    void this.stop()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  }
+
   #handleIpcMessage(message: AkanIpcMessage) {
     if (!message || typeof message !== "object") return;
     if (message.type === "pubsub.deliver") this.#localPublish?.(message.roomId, message.data as object | object[]);
@@ -461,6 +489,16 @@ export class AkanServer {
     );
   }
 
+  /**
+   * Shutdown must finish inside the gateway's child-wait budget or the layer above SIGKILLs this
+   * process and strands its resources; dev (`akan start`) keeps it short so edit-restarts stay snappy.
+   */
+  static #defaultShutdownTimeoutMs() {
+    const configured = Number(process.env.AKAN_SHUTDOWN_TIMEOUT_MS);
+    if (Number.isFinite(configured) && configured > 0) return configured;
+    return process.env.AKAN_COMMAND_TYPE === "start" ? 3_000 : 30_000;
+  }
+
   async #withShutdownTimeout<T>(promise: Promise<T>) {
     let timeout: Timer | null = null;
     try {

package/server/lifecycle/portInUse.ts

@@ -0,0 +1,11 @@
+/**
+ * Detects "address already in use" listen failures across the shapes Bun throws them in
+ * (`code: "EADDRINUSE"` on newer versions, message-only on older ones).
+ */
+export const isPortInUseError = (error: unknown): boolean => {
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as { code?: unknown; message?: unknown };
+  if (candidate.code === "EADDRINUSE") return true;
+  const message = String(candidate.message ?? "");
+  return message.includes("EADDRINUSE") || message.toLowerCase().includes("in use");
+};