@hienlh/ppm 0.17.49 → 0.17.51

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.17.49 at build time. Re-run `ppm export skill --install` to refresh. -->
+<!-- Generated for PPM v0.17.51 at build time. Re-run `ppm export skill --install` to refresh. -->

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

@@ -288,4 +288,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.17.49 -->
+<!-- Generated from src/server/routes/ for PPM v0.17.51 -->

package/docs/lessons-learned.md

@@ -153,3 +153,134 @@ the handle count low also keeps `fs.inotify.max_user_instances` (default 128) ou
 
 Raising the sysctl limit is not a fix — each watch pins ~1KB of kernel memory, so a 2M ceiling
 reserves ~2GB to paper over waste.
+
+---
+
+## Public tunnel URL stability
+
+### Why the public URL used to rotate on every upgrade
+
+**Problem**: a quick trycloudflare tunnel dies with its `cloudflared` process and the URL cannot be
+recovered. The supervisor kept that process alive across a self-replace upgrade, but a tunnel is
+pinned to one *origin port*. When the server could not rebind that port it moved to a nearby one,
+the supervisor re-pointed the tunnel, and the URL changed. The port moved because of a zombie port.
+
+**Zombie port**: on Windows a child spawned with fd stdio inherits every inheritable handle,
+including a listening socket. The server spawns chat/tool/MCP subprocesses constantly; when one is
+orphaned it keeps the server's socket open, so the port stays in LISTEN under a dead PID and can
+never be rebound. Three different debris shapes caused this within two weeks — `nohup` coreutils,
+a `bun run dev:web` tree, and orphaned `mcp-remote` MCP-connector processes. Whitelisting each new
+shape was a losing game.
+
+**Fix**: the server no longer needs a stable port. A dedicated **edge forwarder** owns the public
+port and pipes raw TCP to whatever loopback port the server happened to bind, so `cloudflared`
+stays pinned to the edge forever.
+
+What makes it work: **the edge spawns no child processes**, so its socket can never be inherited
+and its port can never zombie. A test enforces that invariant (`supervisor-resilience.test.ts` →
+"the edge forwarder never spawns a child process"). Any subprocess call added to
+`src/services/edge-forwarder.ts` reintroduces the original bug.
+
+**Files**: `src/services/edge-forwarder.ts`, `src/services/edge-target-resolver.ts`,
+`src/services/supervisor.ts`
+
+### Bun drops socket data that arrives while a socket is paused
+
+Forwarding means resolving the upstream first, so the client's first bytes usually arrive before
+there is anywhere to send them. The obvious guard — `socket.pause()` until `.pipe()` is wired —
+silently loses them on Bun 1.3.13. So does leaving the socket with no `data` listener. Both
+variants swallowed the first HTTP request and the connection simply hung.
+
+A standalone repro compared four variants (`pause`→`pipe`, `pause`→`pipe`→`resume`, no pause, and
+buffering). Only buffering worked: attach a `data` listener synchronously on the connection tick,
+buffer the chunks (bounded — an unbounded buffer is a memory DoS during an upgrade window), then
+replay them into the upstream and pipe. Removing the listener and piping must happen in the same
+tick so no chunk slips through the gap.
+
+### `_opts.port` in the supervisor means the PUBLIC port, not the server's
+
+After the edge took over the public port, three call sites still read that value as the server's,
+and none of them failed a test:
+
+- the **server health probe** — a dead edge looks like a dead server, so the supervisor would kill
+  a healthy one every third cycle;
+- the **pre-self-replace port wait**, which tree-kills whatever holds the port — that is the edge,
+  during an upgrade, which is exactly the URL rotation being fixed;
+- the **stopped page**, which bound the public port directly and collided with the edge.
+
+The health probe now reads the server's own `.server-port`, the self-replace wait is skipped when
+an edge is running, and the stopped page binds loopback and publishes itself so the edge routes to
+it. **When you change what a widely-read variable means, audit every reader — tests will not find
+these.**
+
+### Adoption must come before any bind probe
+
+`ensureBindablePort` treats a live PPM process holding the port as debris and tree-kills it, so
+probing the public port before adopting the edge kills the healthy edge it was about to adopt.
+Adopt first; probe only when there is nothing to adopt.
+
+Related: `findPortListenerPid` needs `netstat` on Windows and `lsof` on POSIX, and returns `0` when
+the tool is missing. Treating "cannot tell" as "does not match" refused every adoption on such a
+box and spawned a duplicate edge that then could not bind.
+
+---
+
+## Process enumeration must not depend on `ps`
+
+**Problem**: `collectProcessTree` and `isPpmProcess` shelled out to `ps`, which ships in `procps` —
+a package slim Debian images leave out, including the one PPM's own suite runs in. Both functions
+swallow the spawn error and return "no descendants" / "not a PPM process", so a missing binary
+**silently disables orphan reaping** rather than failing loudly. Two tests had been timing out for
+weeks and were written off as environmental.
+
+**Fix**: read `/proc` directly on Linux (`/proc/<pid>/stat` for the pid→ppid map,
+`/proc/<pid>/cmdline` for argv) and keep `ps` only as the macOS path. No subprocess, no hidden
+dependency, and much faster — the two tests went from 5s timeouts to ~100ms.
+
+Parsing note: `/proc/<pid>/stat` is `pid (comm) state ppid …` and `comm` may contain spaces **and
+parentheses**, so anchor on the last `)` instead of splitting the line naively.
+
+All call sites now go through `src/services/proc-table-linux.ts`, which reads the table once per
+call and derives what each caller used to ask `ps` for:
+
+| `ps` column | `/proc` source |
+|---|---|
+| `pid`, `ppid` | `/proc/<pid>/stat` fields 1 and 4 |
+| `%cpu` | `(utime+stime)/HZ / elapsed` — fields 14, 15, 22 plus `/proc/uptime` |
+| `rss` | field 24 (pages) × page size |
+| `etimes` | `uptime − starttime/HZ` |
+| `lstart` | `btime` from `/proc/stat` + `starttime/HZ` |
+| `args` | `/proc/<pid>/cmdline` (NUL-separated) |
+| `comm` | `/proc/<pid>/comm` |
+
+`HZ` is assumed to be 100 — `sysconf(_SC_CLK_TCK)` is unreachable from JS, and every mainstream
+Linux ships 100. A wrong value would skew a CPU percentage, nothing more.
+
+## Bun on Linux cannot re-watch a deleted-and-recreated directory
+
+**Problem**: `WatchTree` releases a watcher when a directory disappears and re-covers it when it
+comes back. On Bun 1.3.13 + Linux the new watcher is silent forever: Bun keys its `fs.watch`
+registry by the literal path string and reuses the dead inotify watch. Closing the old handle
+first, or waiting seconds before re-watching, makes no difference.
+
+**Evidence** (`spike-bun-recursive-watch-probe.mjs`): plain recursive and non-recursive watches
+both deliver; both go silent for a recreated directory. On **Windows** (bun 1.3.10) every case
+delivers, so the defect is Linux-only.
+
+**No clean workaround.** A trailing separator is a different key and works exactly once; `//` and
+`///` normalise to the same key, so a rotating-spelling scheme fails from the second cycle.
+
+**The poisoning does not spread**, and that is what made a fix affordable: a directory Bun has
+never watched works normally even inside a recreated parent
+(`spike-bun-watch-poison-scope-probe.mjs`). So only paths that were actually re-attached are dead.
+
+**Fix**: `WatchTree` remembers every path it has handed to `fs.watch`. Re-attaching one of them
+means that directory was deleted and recreated, so on Linux it hands the directory to
+`RecreatedDirPoller` (readdir + mtime diff, 1s interval, hard cap of 64 directories) and covers the
+subtree non-recursively so each child gets a watcher on a path the runtime still honours. Windows
+and macOS never construct the poller.
+
+`WatchTreeStats.polledDirs` reports how many directories are on the degraded path, and the cap
+being hit sets `truncated` — so a churn storm shows up in stats instead of silently growing the
+poll set. Given this watcher once reached ~360k inotify watches, refusing to grow without limit
+matters more than perfect coverage.

package/docs/system-architecture.md

@@ -2075,12 +2075,22 @@ The supervisor is a long-lived parent process that manages server + tunnel child
 **Architecture:**
 ```
 Supervisor Process (parent)
-  ├── Server Child (Hono HTTP server)
-  │   ├── Health checks every 30s (/api/health)
+  ├── Edge Forwarder (detached; owns the PUBLIC port)
+  │   ├── Raw TCP pipe → server's loopback port (no HTTP parsing, so WS/SSE pass through)
+  │   ├── Target read per connection from ~/.ppm/.server-port
+  │   ├── SPAWNS NO CHILDREN — that is why its socket can never be inherited
+  │   │   and its port can never zombie; cloudflared stays pinned to it forever
+  │   ├── Liveness probe every 10s → respawn
+  │   └── Adopted by PID across a self-replace upgrade (adopt BEFORE any bind probe)
+  │
+  ├── Server Child (Hono HTTP server, 127.0.0.1:0 — OS-assigned)
+  │   ├── Publishes its bound port to ~/.ppm/.server-port (single writer)
+  │   ├── Health checks every 30s against that port, never the public one
   │   ├── Auto-restart on crash (exponential backoff, max 10 restarts)
   │   └── If in "stopped" state, serves minimal 503 page instead of restarting
   │
   ├── Tunnel Child (Cloudflare Quick Tunnel, always enabled)
+  │   ├── Origin is the EDGE port, so a server port move cannot rotate the URL
   │   ├── URL probe every 2min
   │   ├── Auto-reconnect on failure
   │   └── URL persisted to status.json
@@ -2095,7 +2105,8 @@ Supervisor Process (parent)
   │   └── npm registry poll → availableVersion written to status.json
   │
   ├── Stopped Page Server
-  │   ├── Lightweight HTTP handler on same port as server
+  │   ├── Lightweight HTTP handler on a loopback port, published to .server-port
+  │   │   so the edge routes the public URL to it (it stands in for the server)
   │   ├── Returns 503 on /api/health
   │   └── Tunnels Cloud WS calls through to PPM Cloud
   │

package/package.json

@@ -1,106 +1,106 @@
-{
-  "name": "@hienlh/ppm",
-  "version": "0.17.49",
-  "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
-  "author": "hienlh",
-  "license": "SEE LICENSE IN LICENSE",
-  "module": "src/index.ts",
-  "type": "module",
-  "workspaces": [
-    "packages/*"
-  ],
-  "bin": {
-    "ppm": "src/index.ts"
-  },
-  "scripts": {
-    "dev": "concurrently \"bun run dev:server\" \"bun run dev:web\"",
-    "dev:server": "bun run --hot src/server/index.ts __serve__ 8081 0.0.0.0 dev",
-    "dev:web": "bun run vite --config vite.config.ts",
-    "tunnel": "cloudflared tunnel --url http://localhost:5173",
-    "dev:tunnel": "concurrently \"bun run dev:server\" \"bun run dev:web\" \"bun run tunnel\"",
-    "build:web": "bun run vite build --config vite.config.ts",
-    "build": "bun run build:web && bun build src/index.ts --compile --outfile dist/ppm",
-    "start": "bun run src/index.ts start",
-    "typecheck": "bunx tsc --noEmit",
-    "test:docker": "docker compose -f docker-compose.test.yml up --build --renew-anon-volumes --abort-on-container-exit --exit-code-from test",
-    "generate:bot": "bun scripts/generate-bot-coordinator.ts --update",
-    "generate:skill": "bun scripts/generate-ppm-skill.ts",
-    "prepublishOnly": "bun run generate:skill && bun run build:web"
-  },
-  "devDependencies": {
-    "@tailwindcss/vite": "^4.2.1",
-    "@types/archiver": "^7.0.0",
-    "@types/bun": "latest",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
-    "concurrently": "^9.2.1",
-    "esbuild": "^0.27.4",
-    "tailwindcss": "^4.2.1",
-    "vite": "^8.0.0",
-    "vite-plugin-pwa": "^1.2.0",
-    "workbox-precaching": "^7.4.0"
-  },
-  "peerDependencies": {
-    "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.251",
-    "@codemirror/lang-sql": "^6.10.0",
-    "@glideapps/glide-data-grid": "^6.0.3",
-    "@inquirer/prompts": "^8.3.0",
-    "@monaco-editor/react": "^4.7.0",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@skitee3000/bun-pty": "^0.3.3",
-    "@tanstack/react-table": "^8.21.3",
-    "@tanstack/react-virtual": "^3.14.5",
-    "@types/diff": "^8.0.0",
-    "@uiw/react-codemirror": "^4.25.8",
-    "@use-gesture/react": "^10.3.1",
-    "@xterm/addon-fit": "0.12.0-beta.285",
-    "@xterm/addon-web-links": "0.13.0-beta.285",
-    "@xterm/addon-webgl": "0.20.0-beta.284",
-    "@xterm/xterm": "6.1.0-beta.285",
-    "archiver": "^7.0.1",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "commander": "^14.0.3",
-    "croner": "^9",
-    "diff": "^9.0.0",
-    "diff2html": "^3.4.56",
-    "highlight.js": "^11.11.1",
-    "hono": "^4.12.8",
-    "ignore": "^7.0.5",
-    "js-yaml": "^4.1.1",
-    "katex": "^0.16.45",
-    "lucide-react": "^0.577.0",
-    "mammoth": "^1.12.0",
-    "mermaid": "^11.13.0",
-    "monaco-editor": "0.55.1",
-    "next-themes": "^0.4.6",
-    "postgres": "^3.4.8",
-    "qrcode-terminal": "^0.12.0",
-    "qrcode.react": "^4.2.0",
-    "radix-ui": "^1.4.3",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-markdown": "^10.1.0",
-    "react-resizable-panels": "^4.7.3",
-    "rehype-highlight": "^7.0.2",
-    "rehype-katex": "^7.0.1",
-    "rehype-raw": "^7.0.0",
-    "remark-breaks": "^4.0.0",
-    "remark-gfm": "^4.0.1",
-    "remark-math": "^6.0.0",
-    "shiki": "^4.3.1",
-    "simple-git": "^3.33.0",
-    "sonner": "^2.0.7",
-    "tailwind-merge": "^3.5.0",
-    "unzipit": "^2.0.3",
-    "use-stick-to-bottom": "^1.1.6",
-    "vite-plugin-monaco-editor": "^1.1.0",
-    "zustand": "^5.0.11"
-  }
-}
+{
+  "name": "@hienlh/ppm",
+  "version": "0.17.51",
+  "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
+  "author": "hienlh",
+  "license": "SEE LICENSE IN LICENSE",
+  "module": "src/index.ts",
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "bin": {
+    "ppm": "src/index.ts"
+  },
+  "scripts": {
+    "dev": "concurrently \"bun run dev:server\" \"bun run dev:web\"",
+    "dev:server": "bun run --hot src/server/index.ts __serve__ 8081 0.0.0.0 dev",
+    "dev:web": "bun run vite --config vite.config.ts",
+    "tunnel": "cloudflared tunnel --url http://localhost:5173",
+    "dev:tunnel": "concurrently \"bun run dev:server\" \"bun run dev:web\" \"bun run tunnel\"",
+    "build:web": "bun run vite build --config vite.config.ts",
+    "build": "bun run build:web && bun build src/index.ts --compile --outfile dist/ppm",
+    "start": "bun run src/index.ts start",
+    "typecheck": "bunx tsc --noEmit",
+    "test:docker": "docker compose -f docker-compose.test.yml up --build --renew-anon-volumes --abort-on-container-exit --exit-code-from test",
+    "generate:bot": "bun scripts/generate-bot-coordinator.ts --update",
+    "generate:skill": "bun scripts/generate-ppm-skill.ts",
+    "prepublishOnly": "bun run generate:skill && bun run build:web"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.1",
+    "@types/archiver": "^7.0.0",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "concurrently": "^9.2.1",
+    "esbuild": "^0.27.4",
+    "tailwindcss": "^4.2.1",
+    "vite": "^8.0.0",
+    "vite-plugin-pwa": "^1.2.0",
+    "workbox-precaching": "^7.4.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.251",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@glideapps/glide-data-grid": "^6.0.3",
+    "@inquirer/prompts": "^8.3.0",
+    "@monaco-editor/react": "^4.7.0",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@skitee3000/bun-pty": "^0.3.3",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.14.5",
+    "@types/diff": "^8.0.0",
+    "@uiw/react-codemirror": "^4.25.8",
+    "@use-gesture/react": "^10.3.1",
+    "@xterm/addon-fit": "0.12.0-beta.285",
+    "@xterm/addon-web-links": "0.13.0-beta.285",
+    "@xterm/addon-webgl": "0.20.0-beta.284",
+    "@xterm/xterm": "6.1.0-beta.285",
+    "archiver": "^7.0.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "commander": "^14.0.3",
+    "croner": "^9",
+    "diff": "^9.0.0",
+    "diff2html": "^3.4.56",
+    "highlight.js": "^11.11.1",
+    "hono": "^4.12.8",
+    "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "katex": "^0.16.45",
+    "lucide-react": "^0.577.0",
+    "mammoth": "^1.12.0",
+    "mermaid": "^11.13.0",
+    "monaco-editor": "0.55.1",
+    "next-themes": "^0.4.6",
+    "postgres": "^3.4.8",
+    "qrcode-terminal": "^0.12.0",
+    "qrcode.react": "^4.2.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-resizable-panels": "^4.7.3",
+    "rehype-highlight": "^7.0.2",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
+    "remark-breaks": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.3.1",
+    "simple-git": "^3.33.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "unzipit": "^2.0.3",
+    "use-stick-to-bottom": "^1.1.6",
+    "vite-plugin-monaco-editor": "^1.1.0",
+    "zustand": "^5.0.11"
+  }
+}

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/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}`);
 }