@hienlh/ppm 0.17.48 → 0.17.50

package/src/cli/commands/restart.ts

@@ -177,6 +177,12 @@ export async function restartServer(options: { force?: boolean }) {
   // terminal (and its process group) to receive SIGHUP.
   const params = JSON.stringify({
     serverPid, port, host, serverScript,
+    // The server's own loopback port, distinct from `port` (the PUBLIC port,
+    // owned by the edge forwarder). The worker must only ever reclaim this one:
+    // force-killing whatever listens on the public port would kill the edge,
+    // which is detached and legitimately still running even with no supervisor.
+    serverPort: (status.serverPort as number | undefined) ?? null,
+    serverPortFile: resolve(getPpmDir(), ".server-port"),
     statusFile: statusFile(),
     pidFile: pidFile(),
     restartingFlag: restartingFlag(),
@@ -210,16 +216,20 @@ async function main() {
   try { process.kill(P.serverPid); log("INFO", "Restart: killed old server PID " + P.serverPid); } catch {}
   await Bun.sleep(500);
 
-  // Force-kill any process still holding the port (handles orphan/zombie processes)
+  // Force-kill anything still holding the OLD SERVER's loopback port (orphaned
+  // grandchildren keep its inherited socket open). Never P.port: that is the
+  // public port and the edge forwarder is listening there — it is detached, so
+  // it is alive and correct even when no supervisor is.
   const killByPort = () => {
+    if (!P.serverPort) return;
     try {
       if (process.platform === "win32") {
-        const r = Bun.spawnSync(["cmd", "/c", "netstat -ano | findstr :" + P.port + " | findstr LISTENING"]);
+        const r = Bun.spawnSync(["cmd", "/c", "netstat -ano | findstr :" + P.serverPort + " | findstr LISTENING"]);
         const lines = r.stdout.toString().trim().split("\\n");
         const pids = new Set(lines.map((l: string) => l.trim().split(/\\s+/).pop()).filter(Boolean));
         for (const pid of pids) { try { process.kill(Number(pid)); } catch {} }
       } else {
-        const r = Bun.spawnSync(["lsof", "-t", "-i", ":" + P.port]);
+        const r = Bun.spawnSync(["lsof", "-t", "-i", ":" + P.serverPort]);
         const pids = r.stdout.toString().trim().split("\\n").filter(Boolean);
         for (const pid of pids) { try { process.kill(Number(pid)); } catch {} }
       }
@@ -227,28 +237,21 @@ async function main() {
   };
   killByPort();
 
-  // Wait for port to be free (up to 5s)
-  const start = Date.now();
-  while (Date.now() - start < 5000) {
-    const inUse: boolean = await new Promise((res) => {
-      const t = createServer()
-        .once("error", () => res(true))
-        .once("listening", () => { t.close(() => res(false)); })
-        .listen(P.port, P.host);
-    });
-    if (!inUse) break;
-    killByPort();
-    await Bun.sleep(200);
-  }
+  // No wait-for-free loop: the replacement server asks for port 0, so a wedged
+  // old port cannot block it. That loop existed only because the server used to
+  // need one specific port back.
+  try { unlinkSync(P.serverPortFile); } catch {}
 
   // Spawn new server — on Windows use PowerShell Start-Process for true detach
   // (Bun.spawn + unref on Windows keeps child in same job object → dies when worker exits)
   let childPid: number;
   // Compiled binary: execPath IS the server, no "run script" needed
   const isCompiled = !process.execPath.includes("bun");
+  // Port 0 / loopback, matching how the supervisor spawns it: the edge owns the
+  // public port and forwards to whatever the server ends up binding.
   const serverArgs = isCompiled
-    ? ["__serve__", String(P.port), P.host]
-    : ["run", P.serverScript, "__serve__", String(P.port), P.host];
+    ? ["__serve__", "0", "127.0.0.1"]
+    : ["run", P.serverScript, "__serve__", "0", "127.0.0.1"];
 
   if (process.platform === "win32") {
     const bunExe = process.execPath.replace(/\\\\/g, "\\\\\\\\");
@@ -293,16 +296,29 @@ async function main() {
   // Remove restarting flag
   try { unlinkSync(P.restartingFlag); } catch {}
 
-  // Health check (up to 10s)
+  // Health check (up to 10s). Probe the PUBLIC port first — that is the whole
+  // chain (edge → server) and what a user actually hits. Fall back to the
+  // server's own loopback port so a dead edge is reported as "server up, public
+  // access down" instead of a blanket restart failure.
   let ready = false;
+  let edgeUp = false;
+  const probe = async (p: number) => {
+    try {
+      const res = await fetch("http://127.0.0.1:" + p + "/api/health", { signal: AbortSignal.timeout(1000) });
+      return res.ok;
+    } catch { return false; }
+  };
   const hStart = Date.now();
   while (Date.now() - hStart < 10000) {
-    try {
-      const res = await fetch("http://127.0.0.1:" + P.port + "/api/health", { signal: AbortSignal.timeout(1000) });
-      if (res.ok) { ready = true; break; }
-    } catch {}
+    if (await probe(P.port)) { ready = true; edgeUp = true; break; }
+    let direct = 0;
+    try { direct = parseInt(readFileSync(P.serverPortFile, "utf-8").trim(), 10); } catch {}
+    if (direct > 0 && await probe(direct)) { ready = true; break; }
     await Bun.sleep(300);
   }
+  if (ready && !edgeUp) {
+    log("WARN", "Server is up but the public port is not being served — edge forwarder is down. Run 'ppm stop --kill' then 'ppm start'.");
+  }
 
   // Check tunnel
   let tunnelAlive = false;

package/src/cli/commands/stop.ts

@@ -81,6 +81,11 @@ export async function stopServer(options?: { all?: boolean; kill?: boolean }) {
         if (data.supervisorPid) { killPid(data.supervisorPid, "supervisor"); killed++; }
         if (data.pid) { killPid(data.pid, "server"); killed++; }
         if (data.tunnelPid) { killPid(data.tunnelPid, "tunnel"); killed++; }
+        // The edge forwarder is spawned detached so it survives an upgrade's
+        // self-replace — which means killing the supervisor does NOT take it
+        // down. Left running it keeps holding the public port and the next
+        // `ppm start` collides with it.
+        if (data.edgePid) { killPid(data.edgePid, "edge"); killed++; }
       } catch {}
     }
     if (existsSync(pidFile())) {

package/src/index.ts

@@ -179,9 +179,12 @@ export async function buildProgram(): Promise<Command> {
  * which would reject them as unknown commands. Source installs spawn the
  * `.ts` files directly and never reach this entry with a sentinel.
  */
-export function resolveEntryMode(argv: string[]): "supervise" | "serve" | "cli" {
+export function resolveEntryMode(
+  argv: string[],
+): "supervise" | "serve" | "edge" | "cli" {
   if (argv.includes("__supervise__")) return "supervise";
   if (argv.includes("__serve__")) return "serve";
+  if (argv.includes("__edge__")) return "edge";
   return "cli";
 }
 
@@ -193,6 +196,9 @@ if (import.meta.main) {
     case "serve":
       await import("./server/index.ts");
       break;
+    case "edge":
+      await import("./services/edge-forwarder.ts");
+      break;
     default: {
       const program = await buildProgram();
       program.parse();

package/src/providers/claude-agent-sdk.ts

@@ -23,7 +23,7 @@ import { getSessionProjectPath, setSessionMetadata, getSessionTitles, insertTurn
 import { buildTurnUsage, formatTurnUsageLog } from "../shared/turn-usage.ts";
 import { accountSelector } from "../services/account-selector.service.ts";
 import { accountService, type AccountWithTokens } from "../services/account.service.ts";
-import { parseSessionMessage, nestChildEvents } from "../services/jsonl-transcript-parser.ts";
+import { parseSessionMessage, nestChildEventsAcrossMessages } from "../services/jsonl-transcript-parser.ts";
 import { stringifyToolResultContent } from "../shared/tool-result-content.ts";
 import { isCompiledBinary } from "../services/autostart-generator.ts";
 import { resolveClaudeCliPath } from "../services/claude-cli-resolver.ts";
@@ -2080,11 +2080,10 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         merged.push(msg);
       }
 
-      // Nest child events under their parent Agent/Task tool_use's children array
-      for (const msg of merged) {
-        if (!msg.events) continue;
-        nestChildEvents(msg.events);
-      }
+      // Nest child events under their parent Agent/Task tool_use's children array.
+      // Cross-message: a backgrounded subagent's events land in later messages
+      // than the Agent tool_use that spawned it.
+      nestChildEventsAcrossMessages(merged);
 
       return merged.filter(
         (msg) => msg.content.trim().length > 0 || (msg.events && msg.events.length > 0),

package/src/server/index.ts

@@ -1,5 +1,7 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
+import { writeFileSync } from "node:fs";
+import { SERVER_PORT_FILE } from "../services/edge-target-resolver.ts";
 import { configService } from "../services/config.service.ts";
 import { VERSION } from "../version.ts";
 import { authMiddleware } from "./middleware/auth.ts";
@@ -940,5 +942,16 @@ if (process.argv.includes("__serve__")) {
     }, 200);
   }
 
-  console.log(`Server child ready on port ${port}`);
+  // Publish the port we actually bound. With `port: 0` the OS picks it, so this
+  // file is the only way anything else can find the server — the edge forwarder
+  // reads it to know where to send traffic, and the supervisor mirrors it into
+  // status.json. The server is the single writer; see edge-target-resolver.ts
+  // for why this is not status.json.
+  try {
+    writeFileSync(SERVER_PORT_FILE(), String(server.port));
+  } catch (e) {
+    console.error(`[serve] Failed to publish server port: ${e}`);
+  }
+
+  console.log(`Server child ready on port ${server.port}`);
 }

package/src/services/edge-forwarder.ts

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

package/src/services/edge-target-resolver.ts

@@ -0,0 +1,63 @@
+/**
+ * Resolves which loopback port the edge forwarder should send traffic to.
+ *
+ * Split out of `edge-forwarder.ts` so the forwarder file stays about piping
+ * bytes and this one stays about trusting (or not trusting) the port it is told.
+ *
+ * The source of truth is `~/.ppm/.server-port`, written by the server itself
+ * the moment it binds — NOT `status.json`. Two reasons:
+ *   1. `writeStatus` replaces status.json wholesale at supervisor startup, so a
+ *      supervisor restart would blank the target out from under a live edge.
+ *   2. The edge is deliberately detached and outlives the supervisor; it must
+ *      not depend on the supervisor being alive to know where the server is.
+ * The supervisor mirrors the value into `status.json.serverPort` for `ppm
+ * status`, but that copy is observability only.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "./ppm-dir.ts";
+
+/** File the server writes its bound port to. Single writer: the server. */
+export const SERVER_PORT_FILE = () => resolve(getPpmDir(), ".server-port");
+
+/** How long a resolved target port is trusted before re-reading from disk. */
+const TARGET_CACHE_MS = 1000;
+
+let cachedPort: number | null = null;
+let cachedAt = 0;
+
+/**
+ * Current server port, or null when it is absent/invalid.
+ *
+ * The value is validated rather than trusted: anything able to write the file
+ * would otherwise be able to redirect all tunnel traffic. Only a plausible port
+ * number is accepted, and callers must always dial loopback.
+ *
+ * Only successful reads are cached — caching a miss would stretch the
+ * forwarder's retry loop to one attempt per second during startup, which is
+ * exactly when the server is still coming up.
+ */
+export function resolveTargetPort(now: number = Date.now()): number | null {
+  if (cachedPort !== null && now - cachedAt < TARGET_CACHE_MS) return cachedPort;
+
+  let raw: number;
+  try {
+    const file = SERVER_PORT_FILE();
+    if (!existsSync(file)) return null;
+    raw = parseInt(readFileSync(file, "utf-8").trim(), 10);
+  } catch {
+    return null;
+  }
+
+  if (!Number.isInteger(raw) || raw <= 0 || raw > 65535) return null;
+
+  cachedPort = raw;
+  cachedAt = now;
+  return cachedPort;
+}
+
+/** Drop the memoized target port (tests, and after a known server restart). */
+export function _resetTargetCache(): void {
+  cachedPort = null;
+  cachedAt = 0;
+}

package/src/services/jsonl-transcript-parser.ts

@@ -154,6 +154,48 @@ export function nestChildEvents(events: ChatEvent[]): void {
   }
 }
 
+/**
+ * Nest child events across message boundaries. A backgrounded subagent keeps
+ * running after its turn ends, so its events land in later messages than the
+ * Agent/Task tool_use that spawned it. Collects parents globally, moves each
+ * child event into its parent's children array, and blanks out messages left
+ * with nothing but moved child content (callers filter empty messages).
+ * Mutates messages in-place.
+ */
+export function nestChildEventsAcrossMessages(messages: { content: string; events?: ChatEvent[] }[]): void {
+  const parentMap = new Map<string, ChatEvent & { type: "tool_use" }>();
+  for (const msg of messages) {
+    for (const ev of msg.events ?? []) {
+      if (ev.type === "tool_use" && (ev.tool === "Agent" || ev.tool === "Task") && ev.toolUseId) {
+        parentMap.set(ev.toolUseId, ev);
+      }
+    }
+  }
+  if (parentMap.size === 0) return;
+
+  for (const msg of messages) {
+    if (!msg.events?.length) continue;
+    const kept: ChatEvent[] = [];
+    let moved = 0;
+    for (const ev of msg.events) {
+      const pid = (ev as any).parentToolUseId as string | undefined;
+      const parent = pid ? parentMap.get(pid) : undefined;
+      if (parent && parent !== ev) {
+        if (!parent.children) parent.children = [];
+        parent.children.push(ev);
+        moved++;
+      } else {
+        kept.push(ev);
+      }
+    }
+    if (moved === 0) continue;
+    msg.events = kept.length > 0 ? kept : undefined;
+    // A message that was purely subagent output duplicates its (now nested)
+    // text via `content` — blank it so the empty-message filter drops it.
+    if (kept.length === 0) msg.content = "";
+  }
+}
+
 /**
  * Validate JSONL path — must be under ~/.claude/ (prevents arbitrary file reads).
  * Throws Error with descriptive message. Returns resolved realpath on success.
@@ -233,9 +275,9 @@ export async function parseJsonlTranscript(
     merged.push(msg);
   }
 
-  for (const msg of merged) {
-    if (msg.events) nestChildEvents(msg.events);
-  }
+  // Nest across messages: a backgrounded subagent's events land in later
+  // messages than the Agent tool_use that spawned it.
+  nestChildEventsAcrossMessages(merged);
 
   return merged.filter(
     (msg) => msg.content.trim().length > 0 || (msg.events && msg.events.length > 0),

package/src/services/supervisor-stopped-page.ts

@@ -1,10 +1,16 @@
 /**
  * Minimal HTTP server that serves a "stopped" page when the PPM server child is down.
- * Binds to the same port so the tunnel URL still works.
+ *
+ * It stands in for the server, so it binds an OS-assigned loopback port and
+ * publishes it to `.server-port` exactly as the real server does. The edge
+ * forwarder then routes the public port here and the tunnel URL keeps working —
+ * which is the whole point of the page. Binding the public port directly would
+ * collide with the edge, which owns it.
  */
-import { appendFileSync } from "node:fs";
+import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { getPpmDir } from "./ppm-dir.ts";
+import { SERVER_PORT_FILE } from "./edge-target-resolver.ts";
 
 function log(level: string, msg: string) {
   const ts = new Date().toISOString();
@@ -36,6 +42,11 @@ const STOPPED_HTML = `<!DOCTYPE html>
 
 let stoppedServer: ReturnType<typeof Bun.serve> | null = null;
 
+/**
+ * @param port  0 in normal operation — the edge finds this page via
+ *              `.server-port`, so it needs no fixed port of its own.
+ * @param host  loopback; the edge is the only public listener.
+ */
 export function startStoppedPage(port: number, host: string) {
   if (stoppedServer) return;
 
@@ -56,7 +67,13 @@ export function startStoppedPage(port: number, host: string) {
         });
       },
     });
-    log("INFO", `Stopped page serving on port ${port}`);
+    // Take over as the edge's target so the public URL shows this page.
+    try {
+      writeFileSync(SERVER_PORT_FILE(), String(stoppedServer.port));
+    } catch (e) {
+      log("WARN", `Failed to publish stopped-page port: ${e}`);
+    }
+    log("INFO", `Stopped page serving on ${host}:${stoppedServer.port}`);
   } catch (e) {
     log("WARN", `Failed to start stopped page: ${e}`);
   }