@hienlh/ppm 0.23.4 → 0.23.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.23.5] - 2026-09-27
+
+### Improved
+- New Codex chats reply about 2.5 s sooner, and starting one no longer freezes the whole server for a couple of seconds.
+- The Codex session list loads about 4x faster.
+
 ## [0.23.4] - 2026-09-27
 
 ### Improved

package/assets/skills/ppm/SKILL.md

@@ -71,4 +71,4 @@ This skill covers the `ppm` CLI, its HTTP API, and its config DB. It does **not*
 - Third-party extensions (inspect via `ppm ext list`).
 - The Claude Agent SDK internals (separate skill).
 
-<!-- Generated for PPM v0.23.4 at build time. Re-run `ppm export skill --install` to refresh. -->
+<!-- Generated for PPM v0.23.5 at build time. Re-run `ppm export skill --install` to refresh. -->

package/assets/skills/ppm/references/cli-reference.md

@@ -781,7 +781,7 @@ Show recent runs for a schedule
 Manage and inspect discovered skills & commands
 
 **Options:**
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.4"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm"`)
 
 **Usage:** `ppm skills [options] [command]`
 
@@ -791,7 +791,7 @@ List all discovered skills and commands
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.4"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm"`)
 
 ### `ppm skills search`
 
@@ -799,7 +799,7 @@ Fuzzy search skills and commands
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.4"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm"`)
 
 **Usage:** `ppm skills search [options] <query>`
 
@@ -809,7 +809,7 @@ Show detailed info for a specific skill
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.4"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm"`)
 
 **Usage:** `ppm skills info [options] <name>`
 

package/assets/skills/ppm/references/http-api.md

@@ -359,4 +359,4 @@ _Base URL: `http://localhost:8080` (default; override via `ppm config set port <
 - `ws://<host>/ws/terminal` — PTY terminal multiplexer
 - `ws://<host>/ws/extensions` — extension host channel
 
-<!-- Generated from src/server/routes/ for PPM v0.23.4 -->
+<!-- Generated from src/server/routes/ for PPM v0.23.5 -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.23.4",
+  "version": "0.23.5",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",

package/src/providers/codex-app-server/codex-history.ts

@@ -1,6 +1,6 @@
 import type { ChatMessage, ChatEvent, SessionInfo } from "../provider.interface.ts";
 import { stripSharedContext } from "../../shared/provider-context.ts";
-import { readdirSync, readFileSync, statSync, realpathSync } from "node:fs";
+import { closeSync, fstatSync, openSync, readdirSync, readFileSync, readSync, statSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { getPpmDir } from "../../services/ppm-dir.ts";
@@ -221,11 +221,46 @@ export function parseRolloutJsonl(
   return messages;
 }
 
-/** Read a rollout file's header (session_meta, plus its title when asked). */
-function readSessionMeta(file: string, opts?: { withTitle?: boolean }): RolloutHeader | null {
+/** First read of a rollout's head: `session_meta` carries the base instructions, measured at 22–27 KB. */
+const HEADER_FIRST_READ_BYTES = 32 * 1024;
+
+/**
+ * Read a rollout file's header (session_meta, plus its title when asked) from as little of
+ * the file as answers it.
+ *
+ * Reading whole files here is what froze the server: identifying one rollout among thousands
+ * read every transcript in full (1.8 GB, over a second of synchronous I/O) whenever no file
+ * name matched. The head is read in growing slices instead, and a slice's unterminated last
+ * line — possibly a split multi-byte character — is dropped by `completeLines`, so a partial
+ * read never parses a partial record.
+ */
+function readSessionMeta(
+  file: string,
+  opts?: { withTitle?: boolean; titleIf?: (header: RolloutHeader) => boolean },
+): RolloutHeader | null {
+  let fd: number | undefined;
   try {
-    return readRolloutHeader(readFileSync(file, "utf-8"), opts);
+    fd = openSync(file, "r");
+    const size = fstatSync(fd).size;
+    let buffer = Buffer.alloc(Math.min(size, HEADER_FIRST_READ_BYTES));
+    let filled = 0;
+    while (true) {
+      const read = readSync(fd, buffer, filled, buffer.length - filled, filled);
+      filled += read;
+      // A file that shrank under us reads short; stop rather than wait for bytes that are gone.
+      const eof = filled >= size || read === 0;
+      const header = readRolloutHeader(buffer.toString("utf-8", 0, filled), opts);
+      // A header the caller is about to discard needs no title: most rollouts in a shared
+      // tree belong to other projects, and a title can sit megabytes in, or nowhere at all.
+      const wanted = header && (!opts?.titleIf || opts.titleIf(header));
+      const complete = header && (!opts?.withTitle || !wanted || header.title || header.parentThreadId);
+      if (complete || eof) return header;
+      const grown = Buffer.alloc(Math.min(size, buffer.length * 4));
+      buffer.copy(grown, 0, 0, filled);
+      buffer = grown;
+    }
   } catch { /* unreadable file → excluded (fail-closed) */ }
+  finally { if (fd !== undefined) closeSync(fd); }
   return null;
 }
 
@@ -270,7 +305,10 @@ export function listCodexRollouts(
   const sessions: SessionInfo[] = [];
 
   for (const file of files) {
-    const meta = readSessionMeta(file, { withTitle: true });
+    const meta = readSessionMeta(file, {
+      withTitle: true,
+      titleIf: (h) => !!h.cwd && !h.parentThreadId && normPath(h.cwd) === target,
+    });
     if (!meta?.cwd) continue;            // fail-closed: no cwd → exclude
     if (normPath(meta.cwd) !== target) continue;
     if (meta.parentThreadId) continue;   // one step of another session, not a session

package/src/providers/codex-app-server/codex-provider.ts

@@ -887,8 +887,12 @@ export class CodexAppServerProvider implements AIProvider {
 
     // Only resume a rollout attributable to this project. An unknown/resumed ID
     // without one must not silently become a fresh thread with a different identity.
-    const found = locateRollout(sessionId, cwd);
-    if (!found && !this.unstartedSessions.has(sessionId)) throw missingRolloutError(sessionId);
+    // A session created here and never started has no rollout: codex names the thread with an
+    // id of its own, so no file can match this one. Looking anyway reads the head of every
+    // rollout on disk, synchronously, before the first turn can start.
+    const unstarted = this.unstartedSessions.has(sessionId);
+    const found = unstarted ? null : locateRollout(sessionId, cwd);
+    if (!found && !unstarted) throw missingRolloutError(sessionId);
 
     const client = new CodexJsonRpcClient();
     const channel = createEventChannel();
@@ -948,11 +952,13 @@ export class CodexAppServerProvider implements AIProvider {
       if (account) setSessionCodexAccount(threadId, account.id);
     }
     // Snapshot persisted history so live message ids continue the rollout-N
-    // numbering (empty for a brand-new thread; full prior transcript on resume).
-    live.history = fromCodexSessionsDirs(threadId, (d) => {
+    // numbering (empty for a brand-new thread; full prior transcript on resume). A new thread
+    // has nothing to snapshot, and its rollout may not be on disk yet — searching for it would
+    // fall back to reading the head of every other rollout.
+    live.history = found ? fromCodexSessionsDirs(threadId, (d) => {
       const msgs = getRolloutMessages(d, threadId, cwd);
       return msgs.length > 0 ? msgs : null;
-    }) ?? [];
+    }) ?? [] : [];
     return live;
   }
 

package/src/server/ws/chat.ts

@@ -131,6 +131,12 @@ interface SessionEntry {
   idleSince?: number;
   /** When the last turn completed — the moment this session's prompt cache was last written */
   lastTurnEndedAt?: number;
+  /**
+   * When the message that opened the current turn reached the server — what "time to first
+   * event" is measured from. The consumer loop outlives turns, so its own clock would count
+   * the idle gap before a follow-up as waiting on the provider.
+   */
+  turnRequestedAt?: { at: number; cold: boolean };
   /** Pending release of the subprocess once its prompt cache lapses */
   cacheReleaseTimer?: ReturnType<typeof setTimeout>;
 }
@@ -716,9 +722,13 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
       const isMetadataEvent = evType === "account_info" || evType === "account_retry" || evType === "streaming_status" || evType === "status_update";
       if (!firstEventReceived && !isMetadataEvent) {
         firstEventReceived = true;
-        const waitMs = Date.now() - startTime;
-        console.log(`[chat] session=${sessionId} first SDK event after ${waitMs}ms: type=${evType}`);
-        logSessionEvent(sessionId, "PERF", `First SDK event after ${waitMs}ms (type=${evType})`);
+        const requested = entry.turnRequestedAt;
+        entry.turnRequestedAt = undefined;
+        // A turn nobody sent over this socket (scheduler, remote trigger) has no receipt time.
+        const waitMs = Date.now() - (requested?.at ?? startTime);
+        const path = requested ? (requested.cold ? "cold" : "warm") : "unsent";
+        console.log(`[chat] session=${sessionId} first SDK event after ${waitMs}ms: type=${evType} path=${path}`);
+        logSessionEvent(sessionId, "PERF", `First SDK event after ${waitMs}ms (type=${evType}, ${path})`);
         if (heartbeat) clearInterval(heartbeat);
         const newPhase = evType === "thinking" ? "thinking" : "streaming";
         setPhase(sessionId, newPhase);
@@ -1197,6 +1207,8 @@ export const chatWebSocket = {
     }
 
     if (parsed.type === "message") {
+      // Taken before any awaited work below (slash rewrites, resume), which is part of the wait.
+      const messageReceivedAt = Date.now();
       // Images count as content: a message may carry only a picture, with nothing typed.
       const hasInlineImages = Array.isArray((parsed as { images?: unknown }).images)
         && ((parsed as { images: unknown[] }).images.length > 0);
@@ -1320,6 +1332,10 @@ export const chatWebSocket = {
 
       // Store user message for reconnect replay (turn_events includes only assistant events)
       entry.currentUserMessage = parsed.content;
+      // Only a message that opens a turn is timed; one typed mid-turn joins the running turn.
+      if (!entry.isStreamingActive || entry.phase === "idle") {
+        entry.turnRequestedAt = { at: messageReceivedAt, cold: !entry.isStreamingActive };
+      }
 
       if (!entry.isStreamingActive) {
         // First message or post-crash recovery: start persistent consumer
@@ -1467,6 +1483,9 @@ export const chatWebSocket = {
       broadcastBackgroundRegistry(sessionId);
       const provider = providerRegistry.get(providerId);
       const instruction = `Call the KillShell tool with task_id "${shellId}" to stop that background command, then reply with just "Stopped.".`;
+      if (!entry.isStreamingActive || entry.phase === "idle") {
+        entry.turnRequestedAt = { at: Date.now(), cold: !entry.isStreamingActive };
+      }
       if (!entry.isStreamingActive) {
         if (provider && "resumeSession" in provider) await (provider as any).resumeSession(sessionId);
         if (entry.projectPath && provider && "ensureProjectPath" in provider) {

package/src/services/edge-forwarder.ts

@@ -1,191 +1,191 @@
-/**
- * Edge forwarder — owns the public port and pipes raw TCP to the server's
- * current loopback port.
- *
- * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
- *
- * On Windows a child spawned with fd stdio inherits every inheritable handle,
- * including a listening socket. When such a descendant is orphaned it keeps the
- * socket open, so the port stays in LISTEN under a dead PID and can never be
- * rebound — a "zombie port". The server hits this constantly because it spawns
- * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
- *
- * The edge exists precisely because it spawns nothing, so its socket cannot be
- * inherited and its port cannot zombie. cloudflared can therefore stay pinned
- * to it forever and the public URL stops rotating. Adding any child-process
- * call to this file reintroduces the exact bug the edge was built to remove.
- *
- * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
- * untouched, and forwarded requests keep the headers cloudflared set.
- */
-import net from "node:net";
-import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
-
-/** Delay between attempts while waiting for the server to come back. */
-const CONNECT_RETRY_MS = 250;
-/**
- * How long a client connection waits for a reachable server before giving up.
- * During an upgrade the server is briefly absent; refusing instantly would
- * surface as a broken page rather than a slow one.
- */
-const CONNECT_WINDOW_MS = 5000;
-
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-
-/** Resolve once the socket is connected; reject on the first connect error. */
-function connectUpstream(port: number): Promise<net.Socket> {
-  return new Promise((resolvePromise, reject) => {
-    const upstream = net.connect({
-      port,
-      host: "127.0.0.1", // never taken from status.json — loopback only
-      allowHalfOpen: true,
-    });
-    const onError = (err: Error) => {
-      upstream.destroy();
-      reject(err);
-    };
-    upstream.once("error", onError);
-    upstream.once("connect", () => {
-      upstream.removeListener("error", onError);
-      resolvePromise(upstream);
-    });
-  });
-}
-
-/**
- * Largest amount of client data held while waiting for the server. Bounds the
- * memory a slow upload can pin during an upgrade window.
- */
-const MAX_PENDING_BYTES = 8 * 1024 * 1024;
-
-/**
- * Pipe one client connection to the server.
- *
- * Resolving the upstream is async, so the first bytes usually arrive before
- * there is anywhere to send them. They must be captured by a `data` listener
- * attached synchronously on this very tick and replayed once the upstream
- * exists.
- *
- * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
- * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
- * bring them back. A socket with no `data` listener drops them outright too.
- * Both variants silently swallowed the first request in testing.
- */
-async function handleConnection(
-  client: net.Socket,
-  connectWindowMs: number,
-): Promise<void> {
-  const pending: Buffer[] = [];
-  let pendingBytes = 0;
-  let clientEnded = false;
-  const onEarlyData = (chunk: Buffer) => {
-    pendingBytes += chunk.length;
-    if (pendingBytes > MAX_PENDING_BYTES) {
-      client.destroy();
-      return;
-    }
-    pending.push(chunk);
-  };
-  client.on("data", onEarlyData);
-  client.once("end", () => { clientEnded = true; });
-
-  let upstream: net.Socket | null = null;
-  let clientGone = false;
-
-  // A socket error with no listener is an unhandled 'error' event, which would
-  // take the whole edge process — and the public port — down with it.
-  const teardown = () => {
-    upstream?.destroy();
-    client.destroy();
-  };
-  client.on("error", teardown);
-  client.once("close", () => { clientGone = true; });
-
-  const deadline = Date.now() + connectWindowMs;
-  while (!clientGone && Date.now() < deadline) {
-    const port = resolveTargetPort();
-    if (port !== null) {
-      try {
-        upstream = await connectUpstream(port);
-        break;
-      } catch {
-        // Server not up yet (or moved mid-restart) — re-resolve and retry.
-        _resetTargetCache();
-      }
-    }
-    await sleep(CONNECT_RETRY_MS);
-  }
-
-  if (clientGone) return;
-  if (!upstream) {
-    client.destroy();
-    return;
-  }
-
-  upstream.on("error", teardown);
-
-  // Replay what arrived during the connect, then hand both directions to the
-  // stream machinery. Removing the listener and piping happen in the same tick,
-  // so no chunk can slip through the gap.
-  client.off("data", onEarlyData);
-  for (const chunk of pending) upstream.write(chunk);
-  pending.length = 0;
-
-  client.pipe(upstream);
-  upstream.pipe(client);
-
-  // The client may have half-closed while we were still connecting.
-  if (clientEnded) upstream.end();
-}
-
-export interface EdgeForwarderOptions {
-  publicPort: number;
-  host?: string;
-  /** How long a client waits for a reachable server. Defaults to 5s. */
-  connectWindowMs?: number;
-}
-
-/**
- * Bind the public port and start forwarding. Resolves once listening so the
- * caller can fail fast when the port is unavailable.
- */
-export function startEdgeForwarder(
-  opts: EdgeForwarderOptions,
-): Promise<net.Server> {
-  const host = opts.host ?? "0.0.0.0";
-  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
-  return new Promise((resolvePromise, reject) => {
-    // allowHalfOpen keeps the other direction alive when one side sends FIN —
-    // long-lived chat WS and SSE streams depend on it.
-    const server = net.createServer({ allowHalfOpen: true }, (client) => {
-      void handleConnection(client, connectWindowMs);
-    });
-    server.once("error", reject);
-    server.listen(opts.publicPort, host, () => {
-      server.removeListener("error", reject);
-      resolvePromise(server);
-    });
-  });
-}
-
-// ─── Process entry ─────────────────────────────────────────────────────
-// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
-// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
-if (process.argv.includes("__edge__")) {
-  const idx = process.argv.indexOf("__edge__");
-  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
-  const host = process.argv[idx + 2] ?? "0.0.0.0";
-
-  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
-    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
-    process.exit(2);
-  }
-
-  try {
-    await startEdgeForwarder({ publicPort, host });
-    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
-  } catch (err) {
-    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
-    process.exit(1);
-  }
-}
+/**
+ * Edge forwarder — owns the public port and pipes raw TCP to the server's
+ * current loopback port.
+ *
+ * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
+ *
+ * On Windows a child spawned with fd stdio inherits every inheritable handle,
+ * including a listening socket. When such a descendant is orphaned it keeps the
+ * socket open, so the port stays in LISTEN under a dead PID and can never be
+ * rebound — a "zombie port". The server hits this constantly because it spawns
+ * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
+ *
+ * The edge exists precisely because it spawns nothing, so its socket cannot be
+ * inherited and its port cannot zombie. cloudflared can therefore stay pinned
+ * to it forever and the public URL stops rotating. Adding any child-process
+ * call to this file reintroduces the exact bug the edge was built to remove.
+ *
+ * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
+ * untouched, and forwarded requests keep the headers cloudflared set.
+ */
+import net from "node:net";
+import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
+
+/** Delay between attempts while waiting for the server to come back. */
+const CONNECT_RETRY_MS = 250;
+/**
+ * How long a client connection waits for a reachable server before giving up.
+ * During an upgrade the server is briefly absent; refusing instantly would
+ * surface as a broken page rather than a slow one.
+ */
+const CONNECT_WINDOW_MS = 5000;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Resolve once the socket is connected; reject on the first connect error. */
+function connectUpstream(port: number): Promise<net.Socket> {
+  return new Promise((resolvePromise, reject) => {
+    const upstream = net.connect({
+      port,
+      host: "127.0.0.1", // never taken from status.json — loopback only
+      allowHalfOpen: true,
+    });
+    const onError = (err: Error) => {
+      upstream.destroy();
+      reject(err);
+    };
+    upstream.once("error", onError);
+    upstream.once("connect", () => {
+      upstream.removeListener("error", onError);
+      resolvePromise(upstream);
+    });
+  });
+}
+
+/**
+ * Largest amount of client data held while waiting for the server. Bounds the
+ * memory a slow upload can pin during an upgrade window.
+ */
+const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Pipe one client connection to the server.
+ *
+ * Resolving the upstream is async, so the first bytes usually arrive before
+ * there is anywhere to send them. They must be captured by a `data` listener
+ * attached synchronously on this very tick and replayed once the upstream
+ * exists.
+ *
+ * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
+ * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
+ * bring them back. A socket with no `data` listener drops them outright too.
+ * Both variants silently swallowed the first request in testing.
+ */
+async function handleConnection(
+  client: net.Socket,
+  connectWindowMs: number,
+): Promise<void> {
+  const pending: Buffer[] = [];
+  let pendingBytes = 0;
+  let clientEnded = false;
+  const onEarlyData = (chunk: Buffer) => {
+    pendingBytes += chunk.length;
+    if (pendingBytes > MAX_PENDING_BYTES) {
+      client.destroy();
+      return;
+    }
+    pending.push(chunk);
+  };
+  client.on("data", onEarlyData);
+  client.once("end", () => { clientEnded = true; });
+
+  let upstream: net.Socket | null = null;
+  let clientGone = false;
+
+  // A socket error with no listener is an unhandled 'error' event, which would
+  // take the whole edge process — and the public port — down with it.
+  const teardown = () => {
+    upstream?.destroy();
+    client.destroy();
+  };
+  client.on("error", teardown);
+  client.once("close", () => { clientGone = true; });
+
+  const deadline = Date.now() + connectWindowMs;
+  while (!clientGone && Date.now() < deadline) {
+    const port = resolveTargetPort();
+    if (port !== null) {
+      try {
+        upstream = await connectUpstream(port);
+        break;
+      } catch {
+        // Server not up yet (or moved mid-restart) — re-resolve and retry.
+        _resetTargetCache();
+      }
+    }
+    await sleep(CONNECT_RETRY_MS);
+  }
+
+  if (clientGone) return;
+  if (!upstream) {
+    client.destroy();
+    return;
+  }
+
+  upstream.on("error", teardown);
+
+  // Replay what arrived during the connect, then hand both directions to the
+  // stream machinery. Removing the listener and piping happen in the same tick,
+  // so no chunk can slip through the gap.
+  client.off("data", onEarlyData);
+  for (const chunk of pending) upstream.write(chunk);
+  pending.length = 0;
+
+  client.pipe(upstream);
+  upstream.pipe(client);
+
+  // The client may have half-closed while we were still connecting.
+  if (clientEnded) upstream.end();
+}
+
+export interface EdgeForwarderOptions {
+  publicPort: number;
+  host?: string;
+  /** How long a client waits for a reachable server. Defaults to 5s. */
+  connectWindowMs?: number;
+}
+
+/**
+ * Bind the public port and start forwarding. Resolves once listening so the
+ * caller can fail fast when the port is unavailable.
+ */
+export function startEdgeForwarder(
+  opts: EdgeForwarderOptions,
+): Promise<net.Server> {
+  const host = opts.host ?? "0.0.0.0";
+  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
+  return new Promise((resolvePromise, reject) => {
+    // allowHalfOpen keeps the other direction alive when one side sends FIN —
+    // long-lived chat WS and SSE streams depend on it.
+    const server = net.createServer({ allowHalfOpen: true }, (client) => {
+      void handleConnection(client, connectWindowMs);
+    });
+    server.once("error", reject);
+    server.listen(opts.publicPort, host, () => {
+      server.removeListener("error", reject);
+      resolvePromise(server);
+    });
+  });
+}
+
+// ─── Process entry ─────────────────────────────────────────────────────
+// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
+// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
+if (process.argv.includes("__edge__")) {
+  const idx = process.argv.indexOf("__edge__");
+  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
+  const host = process.argv[idx + 2] ?? "0.0.0.0";
+
+  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
+    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
+    process.exit(2);
+  }
+
+  try {
+    await startEdgeForwarder({ publicPort, host });
+    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
+  } catch (err) {
+    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
+    process.exit(1);
+  }
+}