@hienlh/ppm 0.20.3 → 0.20.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.20.3",
+  "version": "0.20.4",
   "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-event-mapper.ts

@@ -168,6 +168,10 @@ export function mapCodexEvent(notif: Notif, sessionId: string): ChatEvent[] {
       return typeof p.delta === "string" ? [{ type: "text", content: p.delta }] : [];
 
     case "item/reasoning/textDelta":
+    // `summary` is what turn/start requests for PPM's Thinking switch. Recent
+    // app-server builds stream it under this method, while older builds used
+    // textDelta directly. Both are safe, user-visible reasoning summaries.
+    case "item/reasoning/summaryTextDelta":
       return typeof p.delta === "string" ? [{ type: "thinking", content: p.delta }] : [];
 
     case "item/started": {

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

@@ -411,10 +411,12 @@ export function getRolloutMessages(sessionsDir: string, threadId: string, reques
   } catch { return []; }
 }
 
-/** True when a path points at a codex rollout under ~/.codex/sessions. */
+/** True when a path points at a codex rollout in the ambient or a PPM account home. */
 export function isCodexRolloutPath(p: string): boolean {
   const n = normPath(p);
-  return n.endsWith(".jsonl") && n.includes(normPath(join(homedir(), ".codex", "sessions")));
+  const ambient = normPath(join(homedir(), ".codex", "sessions"));
+  const managed = normPath(join(homedir(), ".ppm", "codex-accounts"));
+  return n.endsWith(".jsonl") && (n.includes(ambient) || (n.includes(managed) && n.includes("/sessions/")));
 }
 
 /**

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

@@ -56,6 +56,10 @@ export interface TurnStartParams {
   approvalPolicy?: AskForApproval;
   sandboxPolicy?: unknown;
   model?: string;
+  /** Codex's per-turn reasoning depth (low through ultra, model dependent). */
+  effort?: string;
+  /** Controls whether Codex streams a safe reasoning summary to the client. */
+  summary?: "none" | "auto" | "concise" | "detailed";
 }
 
 // ── Decisions (approval responses) ──

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

@@ -10,7 +10,7 @@ import type {
   UsageInfo,
 } from "../provider.interface.ts";
 import { configService } from "../../services/config.service.ts";
-import { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount, getSessionCodexAccount, getSessionTitles } from "../../services/db.service.ts";
+import { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount, getSessionCodexAccount, getSessionTitles, insertTurnUsage } from "../../services/db.service.ts";
 import {
   resolveCodexAccountForSession,
   getCodexAccount,
@@ -29,6 +29,7 @@ import { join } from "node:path";
 import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS } from "./codex-jsonrpc-client.ts";
 import { permissionModeToCodex, type CodexPermission } from "./codex-permission-map.ts";
 import { mapCodexEvent, parseTokenUsage } from "./codex-event-mapper.ts";
+import { subagentCardId } from "./codex-subagent-thread.ts";
 import { decisionFor, isApprovalMethod, type ApprovalMethod } from "./codex-approval-decision.ts";
 import { parseModelList } from "./codex-model-parser.ts";
 import { getOrFetchUsage, registerUsageSource } from "../../services/provider-usage/usage-registry.ts";
@@ -147,6 +148,8 @@ interface LiveSession {
   compactRequested?: boolean;
   /** Token counts from the most recent usage notification, attached to `done`. */
   lastUsage?: import("../../shared/turn-usage.ts").TurnUsage;
+  /** Spawned thread ids. Notifications from these threads belong inside their Agent card. */
+  subagentThreadIds: Set<string>;
   /** A turn is running on the thread. Codex accepts exactly one at a time: a
    *  second `turn/start` resolves with the ALREADY-RUNNING turn (same id,
    *  status `inProgress`) and silently discards the new input — no error, so
@@ -219,6 +222,21 @@ function createEventChannel(): EventChannel {
   };
 }
 
+/** The app-server puts the owner thread on every item notification.  An
+ * `agentThreadId` inside a SubAgentActivity is the newly spawned child, so it
+ * must never be used here: that would nest the launch card inside itself. */
+export function threadIdFromNotification(params: unknown): string | null {
+  if (!params || typeof params !== "object") return null;
+  const p = params as Record<string, unknown>;
+  const direct = p.threadId ?? p.thread_id;
+  if (typeof direct === "string" && direct) return direct;
+  const thread = p.thread;
+  if (thread && typeof thread === "object" && typeof (thread as Record<string, unknown>).id === "string") {
+    return (thread as Record<string, unknown>).id as string;
+  }
+  return null;
+}
+
 /**
  * Drop a model id that isn't a codex model. PPM's per-session model can fall back
  * to the global Claude default (e.g. `claude-opus-4-8`), which codex rejects
@@ -425,6 +443,7 @@ export class CodexAppServerProvider implements AIProvider {
     live.lastTurnInput = { message, opts };
     live.currentAssistant = "";
     live.currentEvents = [];
+    live.lastUsage = undefined;
     // Codex takes an image as a path, never as a payload, so the uploaded copy is what it
     // gets. Images lead: the text usually refers to them ("what is this?").
     const input: UserInput[] = [
@@ -432,10 +451,17 @@ export class CodexAppServerProvider implements AIProvider {
       { type: "text" as const, text: message, text_elements: [] },
     ];
     const turnModel = codexModel(opts?.model);
+    const turnEffort = opts?.effort ?? this.config?.effort;
+    const configuredThinking = this.config?.thinking_budget_tokens;
+    // Codex does not accept a token budget. Its equivalent is an effort level,
+    // while `summary` controls the safe thinking text the UI can show.
+    const thinkingEnabled = (opts?.thinkingBudget ?? configuredThinking ?? -1) !== 0;
     live.client.request("turn/start", {
       threadId: live.threadId,
       input,
       ...(turnModel ? { model: turnModel } : {}),
+      ...(turnEffort ? { effort: turnEffort } : {}),
+      summary: thinkingEnabled ? "detailed" : "none",
     }).then((res) => {
       // Backup for the `turn/started` notification, which is what normally names
       // the turn — an interrupt arriving in between has nothing to address.
@@ -678,7 +704,7 @@ export class CodexAppServerProvider implements AIProvider {
       client, threadId: null, cwd, channel, permission, model,
       pendingApprovals: new Map(), answeredCodexIds: new Set(),
       history: [], transcript: [], currentAssistant: "", currentEvents: [],
-      pendingTurns: [],
+      pendingTurns: [], subagentThreadIds: new Set(),
     };
     this.live.set(sessionId, live);
 
@@ -750,14 +776,26 @@ export class CodexAppServerProvider implements AIProvider {
       const usage = parseTokenUsage(notif.params, live.model);
       if (usage) live.lastUsage = usage;
     }
+    const notificationThreadId = threadIdFromNotification(notif.params);
+    const parentToolUseId = notificationThreadId && live.subagentThreadIds.has(notificationThreadId)
+      ? subagentCardId(notificationThreadId)
+      : undefined;
     const events = mapCodexEvent(notif, live.threadId ?? "");
     for (const ev of events) {
       // The counts arrive on their own notification just before the turn ends,
       // so `done` is where they become visible to a consumer.
-      if (ev.type === "done" && live.lastUsage) ev.usage = live.lastUsage;
-      live.channel.push(ev);
+      if (ev.type === "done" && live.lastUsage) {
+        ev.usage = live.lastUsage;
+        this.recordTurnUsage(live, live.lastUsage);
+      }
+      const nested = parentToolUseId ? { ...ev, parentToolUseId } as ChatEvent : ev;
+      live.channel.push(nested);
       // Accumulate tool calls into the turn so getMessages (live) keeps them.
-      if (ev.type === "tool_use" || ev.type === "tool_result") live.currentEvents.push(ev);
+      if (nested.type === "tool_use" || nested.type === "tool_result") live.currentEvents.push(nested);
+      if (nested.type === "tool_use" && nested.tool === "Agent" && typeof nested.toolUseId === "string"
+          && nested.toolUseId.startsWith("subagent-")) {
+        live.subagentThreadIds.add(nested.toolUseId.slice("subagent-".length));
+      }
     }
     if (notif.method === "turn/completed") {
       if (live.currentAssistant || live.currentEvents.length) {
@@ -798,6 +836,32 @@ export class CodexAppServerProvider implements AIProvider {
     }
   }
 
+  /** Persist Codex's per-turn token and prompt-cache split for the debug panel. */
+  private recordTurnUsage(live: LiveSession, usage: import("../../shared/turn-usage.ts").TurnUsage): void {
+    const accountId = live.threadId ? getSessionCodexAccount(live.threadId) ?? undefined : undefined;
+    const account = accountId ? getCodexAccount(accountId) : null;
+    try {
+      insertTurnUsage({
+        sessionId: live.threadId ?? "",
+        model: usage.model,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        cacheReadTokens: usage.cacheReadTokens,
+        cacheWriteTokens: usage.cacheWriteTokens,
+        contextWindow: usage.contextWindow,
+        costUsd: usage.costUsd,
+        // A cache miss alone does not prove a process restart: a first turn and
+        // an evicted prompt cache look the same on the wire. Keep this false
+        // until the provider has an explicit lifecycle reason to record.
+        coldStart: false,
+        ...(accountId ? { accountId } : {}),
+        ...(account?.label ? { accountLabel: account.label } : {}),
+      });
+    } catch (err) {
+      console.warn(`[usage] failed to persist codex usage: ${(err as Error).message}`);
+    }
+  }
+
   private handleServerRequest(live: LiveSession, req: ServerRequest): void {
     const method = req.method;
     if (isApprovalMethod(method)) {

package/src/server/routes/chat.ts

@@ -19,6 +19,8 @@ import { parseJsonlTranscript, validateJsonlPath } from "../../services/jsonl-tr
 import { aggregateTasks } from "../../services/task-status-aggregator.ts";
 import { MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
 import { auditTranscriptImagesFile, stripTranscriptImagesFile } from "../../services/transcript-images-file.ts";
+import { listCodexAccounts } from "../../services/codex-account.service.ts";
+import { findRolloutByThreadId } from "../../providers/codex-app-server/codex-history.ts";
 import { getSessionProjectPath, setSessionMetadata, setSessionTitle, getSessionTitle, getPinnedSessionIds, pinSession, unpinSession, deleteSessionMapping, deleteSessionMetadata, deleteSessionTitle, getAllUnread, clearSessionUnread, setSessionUnread } from "../../services/db.service.ts";
 import { setSessionTag, bulkSetSessionTag, getTagById, getSessionTags, getProjectDefaultTagId } from "../../services/tag.service.ts";
 import { recordBranch, resolveVersionGroup, resolveVersionMap, collapseTreesToHeads, hasChildren, deleteBranchesFor, getRootId } from "../../services/session-branch.service.ts";
@@ -469,8 +471,11 @@ chatRoutes.patch("/sessions/:id", async (c) => {
     const projectPath = c.get("projectPath");
     // Persist to PPM DB (authoritative source for user-set titles)
     setSessionTitle(id, title);
-    // Also persist to SDK so Claude Code CLI sees the custom title
-    await sdkRenameSession(id, title, { dir: projectPath });
+    // Codex owns its rollout title and has no Claude SDK session to rename.
+    // PPM's title table is the authoritative title for both providers.
+    if (getSessionProvider(id) !== "codex") {
+      await sdkRenameSession(id, title, { dir: projectPath });
+    }
     // Also update in-memory session
     const session = chatService.getSession(id);
     if (session) session.title = title;
@@ -763,9 +768,22 @@ chatRoutes.get("/sessions/:id/logs", (c) => {
  */
 function resolveSessionJsonlPath(sessionId: string): { jsonlPath: string; jsonlDir: string; projectPath: string; exists: boolean } {
   const homedir = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  const providerId = getSessionProvider(sessionId);
+  const storedProjectPath = getSessionProjectPath(sessionId) ?? "";
+  if (providerId === "codex") {
+    const dirs = [
+      ...listCodexAccounts().map((account) => join(account.home, "sessions")),
+      ...(homedir ? [resolve(homedir, ".codex", "sessions")] : []),
+    ];
+    for (const dir of dirs) {
+      const found = findRolloutByThreadId(dir, sessionId, storedProjectPath || undefined);
+      if (found) return { jsonlPath: found, jsonlDir: dir, projectPath: storedProjectPath, exists: true };
+    }
+    return { jsonlPath: "", jsonlDir: "", projectPath: storedProjectPath, exists: false };
+  }
   const provider = providerRegistry.get("claude") as any;
   const projectPath = provider?.activeSessions?.get(sessionId)?.projectPath
-    ?? getSessionProjectPath(sessionId)
+    ?? storedProjectPath
     ?? "";
   const projectsRoot = homedir ? resolve(homedir, ".claude", "projects") : "";
   // SDK encodes cwd by replacing path separators + drive colon with "-".
@@ -815,6 +833,7 @@ chatRoutes.get("/sessions/:id/debug", (c) => {
   return c.json(ok({
     ppmSessionId: sessionId,
     sdkSessionId: sessionId,
+    providerId: getSessionProvider(sessionId) ?? "claude",
     sessionId,
     jsonlPath: exists ? jsonlPath : null,
     jsonlDir,

package/src/server/ws/chat.ts

@@ -1286,10 +1286,15 @@ export const chatWebSocket = {
       } else {
         // Follow-up: push into existing generator via provider
         if (provider && "pushMessage" in provider && parsed.type === "message") {
+          const effort = getSessionEffort(sessionId) ?? undefined;
+          const thinkingBudget = getSessionThinking(sessionId);
           (provider as any).pushMessage(sessionId, parsed.content, {
             priority: parsed.priority ?? 'next',
             images: parsed.images,
             imagePaths: parsed.imagePaths,
+            ...(entry.model ? { model: entry.model } : {}),
+            ...(effort ? { effort } : {}),
+            ...(thinkingBudget != null ? { thinkingBudget } : {}),
           });
         }
         // Clear turn events for new turn display + transition phase

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);
+  }
+}