akanjs 2.4.0-rc.0 → 2.4.0-rc.2

package/base/baseEnv.ts

@@ -104,7 +104,11 @@ export const getEnv = (): ClientEnv => {
   const clientHost =
     process.env.AKAN_PUBLIC_CLIENT_HOST ??
     (operationMode === "local" || side === "server" ? "localhost" : window.location.hostname);
-  const clientPort = parseInt(process.env.AKAN_PUBLIC_CLIENT_PORT ?? (operationMode === "local" ? "8282" : "443"));
+  const clientPort =
+    side === "server"
+      ? parseInt(process.env.AKAN_PUBLIC_CLIENT_PORT ?? (operationMode === "local" ? "8282" : "443"))
+      : parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"));
+
   const clientHttpProtocol =
     side === "client"
       ? (window.location.protocol as "http:" | "https:")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.0-rc.0",
+  "version": "2.4.0-rc.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

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;
@@ -103,10 +112,13 @@ export class AkanApp {
     this.#serverPath = AkanApp.#resolveServerPath(resolvedOptions.serverPath ?? serverPath);
     this.#artifactDir = path.resolve(path.dirname(this.#serverPath), ".akan", "artifact");
     this.#replica = AkanApp.#parseReplicaConfig(resolvedOptions.replica);
-    this.#runtimeDir =
-      (resolvedOptions.runtimeDir ?? process.env.AKAN_RUNTIME_DIR ?? process.env.NODE_ENV === "production")
-        ? path.resolve(process.cwd(), "runtime")
-        : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime");
+    this.#runtimeDir = path.resolve(
+      resolvedOptions.runtimeDir ??
+        process.env.AKAN_RUNTIME_DIR ??
+        (process.env.NODE_ENV === "production"
+          ? path.resolve(process.cwd(), "runtime")
+          : path.resolve(process.cwd(), "local", "apps", process.env.AKAN_PUBLIC_APP_NAME ?? "unknown", "runtime")),
+    );
     this.#port = Number(resolvedOptions.port ?? process.env.PORT ?? 8282);
     this.#wsBasePort = Number(resolvedOptions.wsBasePort ?? process.env.AKAN_WS_BASE_PORT ?? this.#port + 10_000);
     this.#openapi = resolvedOptions.openapi;
@@ -149,15 +161,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,11 +235,12 @@ 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();
-    }
+
+    const stragglers = [...this.#children.values()].filter((child) => !child.proc.killed);
+    for (const child of stragglers) child.proc.kill("SIGKILL");
+    await Promise.all(stragglers.map((child) => child.proc.exited.catch(() => undefined)));
     this.#children.clear();
     await this.#stopFileLogging();
     this.#resolveStopped?.();
@@ -213,6 +257,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 +317,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 +333,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 +403,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 +456,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 +556,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 +612,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 +626,7 @@ export class AkanApp {
         lastExitCode: child.lastExitCode,
         lastRestartAt: child.lastRestartAt,
         lastRestartReason: child.lastRestartReason,
+        lastErrorMessage: child.lastErrorMessage,
       })),
     };
   }
@@ -560,7 +661,7 @@ export class AkanApp {
   async #proxyHttp(req: Request): Promise<Response> {
     const child = this.#pickFederationChild();
     if (!child?.upstream || child.upstream.type !== "unix") {
-      return new Response("No healthy federation child is ready", { status: 503 });
+      return this.#respondWithCrashPage(req) ?? new Response("No healthy federation child is ready", { status: 503 });
     }
     const url = new URL(req.url);
     const upstreamUrl = `http://akan-child${url.pathname}${url.search}`;
@@ -600,6 +701,70 @@ export class AkanApp {
     return candidate.code === "FailedToOpenSocket" || String(candidate.message ?? "").includes("FailedToOpenSocket");
   }
 
+  /**
+   * Dev-only: every traffic replica is in the crashed terminal state, so a bare 503 would hide the
+   * boot error from the browser. Surface it, and reload once a fixed gateway takes over the port.
+   */
+  #respondWithCrashPage(req: Request): Response | null {
+    if (!this.#devHosted) return null;
+    const trafficChildren = [...this.#children.values()].filter((child) => child.role !== "batch");
+    if (trafficChildren.length === 0) return null;
+    if (!trafficChildren.every((child) => child.status === "crashed")) return null;
+    const detail =
+      trafficChildren.map((child) => child.lastErrorMessage ?? child.lastRestartReason).find(Boolean) ??
+      "unknown boot error";
+    const message = `Backend failed to start after ${AkanApp.#devMaxChildBootFailures} boot attempts: ${detail}`;
+    if (!req.headers.get("accept")?.includes("text/html")) {
+      return new Response(message, { status: 503, headers: { "cache-control": "no-store" } });
+    }
+    const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<title>Backend failed to start</title>
+<style>
+  body { margin: 0; padding: 48px 24px; background: #111827; color: #e5e7eb; font-family: ui-sans-serif, system-ui, sans-serif; }
+  main { max-width: 720px; margin: 0 auto; }
+  h1 { font-size: 20px; color: #f87171; }
+  pre { padding: 16px; border-radius: 8px; background: #1f2937; color: #fca5a5; white-space: pre-wrap; word-break: break-word; }
+  p { color: #9ca3af; font-size: 14px; }
+</style>
+</head>
+<body>
+<main>
+<h1>Backend failed to start</h1>
+<pre>${AkanApp.#escapeHtml(detail)}</pre>
+<p>The dev server stopped retrying after ${AkanApp.#devMaxChildBootFailures} failed boots. Fix the error and save &mdash; this page reloads automatically.</p>
+</main>
+<script>
+  const poll = async () => {
+    try {
+      const res = await fetch(location.href, { cache: "no-store" });
+      if (res.ok) { location.reload(); return; }
+    } catch {}
+    setTimeout(poll, 1000);
+  };
+  setTimeout(poll, 1000);
+</script>
+</body>
+</html>`;
+    return new Response(html, {
+      status: 503,
+      headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" },
+    });
+  }
+
+  static #escapeHtml(text: string) {
+    const replacements: Record<string, string> = {
+      "&": "&amp;",
+      "<": "&lt;",
+      ">": "&gt;",
+      '"': "&quot;",
+      "'": "&#39;",
+    };
+    return text.replace(/[&<>"']/g, (ch) => replacements[ch] ?? ch);
+  }
+
   /**
    * Gateway-observed upstream round-trip time. The pure proxy overhead is this value
    * minus the child handler time captured in the per-request trace.
@@ -709,8 +874,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 +931,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 +963,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 +984,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 +999,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 +1106,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 +1170,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");
+};

package/server/rscWorker.tsx

@@ -216,6 +216,11 @@ export class RscRenderer {
     }
     this.#send = process.send.bind(process) as (message: unknown) => void;
     process.on("message", (msg: InMsg) => this.#handleMessage(msg));
+
+    process.on("disconnect", () => {
+      this.#logger.warn("parent IPC channel closed; exiting rsc worker");
+      process.exit(0);
+    });
     this.#logger.verbose(`constructed (pid=${process.pid})`);
   }
 

package/service/ipcTypes.ts

@@ -1,6 +1,6 @@
 export type AkanChildRole = "all" | "federation" | "batch";
 
-export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited";
+export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited" | "crashed";
 
 export type AkanUpstream = { type: "unix"; socketPath: string } | { type: "tcp"; host: string; port: number };
 
@@ -110,6 +110,8 @@ export type AkanIpcMessage =
       replicaIdx: number;
       role: AkanChildRole;
       upstream?: AkanUpstream;
+      /** Actual websocket upstream the child bound; may differ from the preferred port when it was in use. */
+      wsUpstream?: Extract<AkanUpstream, { type: "tcp" }>;
       healthPath?: string;
     }
   | { type: "backend-ready"; pid: number }

package/types/server/lifecycle/portInUse.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 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 declare const isPortInUseError: (error: unknown) => boolean;

package/types/service/ipcTypes.d.ts

@@ -1,5 +1,5 @@
 export type AkanChildRole = "all" | "federation" | "batch";
-export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited";
+export type AkanChildStatus = "starting" | "ready" | "healthy" | "draining" | "unhealthy" | "exited" | "crashed";
 export type AkanUpstream = {
     type: "unix";
     socketPath: string;
@@ -122,6 +122,10 @@ export type AkanIpcMessage = {
     replicaIdx: number;
     role: AkanChildRole;
     upstream?: AkanUpstream;
+    /** Actual websocket upstream the child bound; may differ from the preferred port when it was in use. */
+    wsUpstream?: Extract<AkanUpstream, {
+        type: "tcp";
+    }>;
     healthPath?: string;
 } | {
     type: "backend-ready";