@hienlh/ppm 0.17.5 → 0.17.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.17.6] - 2026-07-23
+
+### Fixed
+- **Tunnel no longer leaks orphaned cloudflared processes on regeneration** — `restartTunnel()` nulls the mutable global `tunnelChild` before spawning a fresh loop, but a concurrent `spawnTunnel` loop still awaited `tunnelChild.exited` on that global. When it was nulled mid-await the loop threw `TypeError: null is not an object (evaluating 'tunnelChild.exited')` and died **without reaping the cloudflared child it spawned** — leaving an orphaned process (PID 1) that retried forever. Over weeks dozens accumulated (observed 62 such crashes in one deployment). `spawnTunnel` now owns its child via a local reference for the whole loop and only touches the global while it still points at that child, so a regeneration can never crash the previous loop or orphan its process.
+- **Tunnel regeneration no longer trips Cloudflare's per-IP rate limit** — the resume-from-sleep detector regenerated the quick tunnel on *every* wall-clock gap >90s. A laptop that sleeps/wakes frequently rotated the tunnel hundreds of times/day (observed ~325 in 3 weeks), each spawning a new `cloudflared` → trycloudflare rate-limited the source IP and **no new tunnel could register** (`control stream encountered a failure while serving`, retrying forever). Regeneration is now throttled to at most once per 5 minutes; the existing tunnel probe still heals a genuinely-zombied URL, and cloudflared self-heals transient QUIC drops on its own.
+
 ## [0.17.5] - 2026-07-16
 
 ### Fixed

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

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

@@ -255,4 +255,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.5 -->
+<!-- Generated from src/server/routes/ for PPM v0.17.6 -->

package/package.json

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

package/src/services/supervisor.ts

@@ -56,6 +56,13 @@ let shuttingDown = false;
 // respawning, so restarts never leave two concurrent spawnTunnel loops racing
 // (the old leak that spawned dozens of orphaned cloudflared processes).
 let tunnelGeneration = 0;
+// Throttle tunnel regeneration. A quick-tunnel URL rotation spawns a NEW
+// cloudflared → trycloudflare rate-limits quick tunnels per source IP, so a
+// sleep/wake storm that regenerates hundreds of times gets the whole IP
+// throttled and NO new tunnel can register ("control stream encountered a
+// failure while serving"). Never rotate more than once per this window.
+let lastTunnelRegenAt = 0;
+const TUNNEL_REGEN_MIN_INTERVAL_MS = 300_000; // 5min
 
 // Module-level refs for softStop (needs access to respawn args)
 let _serverArgs: string[] = [];
@@ -167,6 +174,7 @@ async function ensureBindablePort(preferred: number, host: string): Promise<numb
  * is dead. Fire-and-forget: spawnTunnel's own loop owns liveness afterwards.
  */
 function restartTunnel(port: number) {
+  lastTunnelRegenAt = Date.now();
   if (tunnelChild) { try { tunnelChild.kill(); } catch {} tunnelChild = null; }
   if (adoptedTunnelPid) { try { process.kill(adoptedTunnelPid, "SIGTERM"); } catch {} adoptedTunnelPid = null; }
   tunnelUrl = null;
@@ -457,8 +465,16 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
       ]
     : [bin, "tunnel", "--url", `http://127.0.0.1:${port}`];
 
+  // Own this cloudflared via a LOCAL ref for the whole loop. `tunnelChild` is a
+  // mutable global that a concurrent restartTunnel() nulls/reassigns; awaiting
+  // `tunnelChild.exited` on it would throw `TypeError: null is not an object`
+  // mid-flight, killing this loop WITHOUT reaping the child we spawned →
+  // orphaned cloudflared (PID 1). The local ref keeps our lifecycle
+  // self-contained; we only touch the global when it still points at us.
+  let child: Subprocess;
   try {
-    tunnelChild = Bun.spawn(tunnelCmd, { stderr: tunnelLogFd, stdout: "ignore", stdin: "ignore" });
+    child = Bun.spawn(tunnelCmd, { stderr: tunnelLogFd, stdout: "ignore", stdin: "ignore" });
+    tunnelChild = child; // publish so restartTunnel/killStaleTunnel can reach the live child
   } finally {
     // Close our handle; cloudflared keeps its own via dup2
     try { closeSync(tunnelLogFd); } catch {}
@@ -466,12 +482,12 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   if (underSystemd) log("INFO", "Tunnel spawned inside transient systemd-run scope (escapes ppm.service cgroup)");
 
   try {
-    tunnelUrl = await extractUrlFromLogFile(() => tunnelChild?.exitCode ?? null);
+    tunnelUrl = await extractUrlFromLogFile(() => child.exitCode);
   } catch (err) {
     log("ERROR", `Tunnel URL extraction failed: ${err}`);
     tunnelUrl = null;
-    try { tunnelChild.kill(); } catch {}
-    tunnelChild = null;
+    try { child.kill(); } catch {}
+    if (tunnelChild === child) tunnelChild = null;
 
     if (shuttingDown) return;
 
@@ -492,19 +508,19 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // A newer authoritative (re)start superseded us while we extracted the URL —
   // kill our child so it can't linger as an orphan, and bail.
   if (generation !== tunnelGeneration) {
-    try { tunnelChild.kill(); } catch {}
-    tunnelChild = null;
+    try { child.kill(); } catch {}
+    if (tunnelChild === child) tunnelChild = null;
     return;
   }
 
-  updateStatus({ shareUrl: tunnelUrl, tunnelPid: tunnelChild.pid, tunnelPort: port });
-  log("INFO", `Tunnel ready: ${tunnelUrl} (PID: ${tunnelChild.pid})`);
+  updateStatus({ shareUrl: tunnelUrl, tunnelPid: child.pid, tunnelPort: port });
+  log("INFO", `Tunnel ready: ${tunnelUrl} (PID: ${child.pid})`);
 
   // One-time sync of tunnel URL to cloud (WS handles periodic heartbeat)
   await syncUrlToCloud(tunnelUrl);
 
-  const exitCode = await tunnelChild.exited;
-  tunnelChild = null;
+  const exitCode = await child.exited;
+  if (tunnelChild === child) tunnelChild = null;
   const deadUrl = tunnelUrl;
   tunnelUrl = null;
 
@@ -527,7 +543,7 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // Never give up: cap the counter so backoff plateaus at BACKOFF_MAX_MS (no 10-min dark window).
   if (tunnelRestarts > MAX_RESTARTS) tunnelRestarts = MAX_RESTARTS;
   const delay = backoffDelay(tunnelRestarts) + Math.floor(Math.random() * 1000);
-  log("WARN", `Tunnel process exited (code=${exitCode}, signal=${tunnelChild === null ? "killed" : "self"}, url=${deadUrl}), restart in ${delay}ms (#${tunnelRestarts})`);
+  log("WARN", `Tunnel process exited (code=${exitCode}, url=${deadUrl}), restart in ${delay}ms (#${tunnelRestarts})`);
   await Bun.sleep(delay);
 
   if (generation !== tunnelGeneration) return; // superseded during backoff
@@ -1353,10 +1369,19 @@ export async function runSupervisor(opts: {
     tunnelFailCount = 0;
     // If paused solely from the post-resume failure cascade, resume the server.
     if (getState() === "paused") triggerResume();
-    // The old quick-tunnel session is almost certainly dead — force a fresh one
-    // at the server's live port (the URL rotates anyway, so follow the server).
+    // The old quick-tunnel session MAY be dead after resume, but cloudflared
+    // self-heals transient QUIC drops on its own. Only force a fresh tunnel if
+    // we haven't just rotated — otherwise a laptop that sleeps/wakes constantly
+    // regenerates hundreds of quick tunnels/day, tripping trycloudflare's
+    // per-IP rate limit so NO tunnel can register. The tunnel probe still
+    // regenerates a genuinely-zombied URL (edge dropped) within ~5min.
     if (getState() === "running" && (tunnelUrl || tunnelChild || adoptedTunnelPid)) {
-      restartTunnel(_opts.port);
+      const sinceRegen = now - lastTunnelRegenAt;
+      if (sinceRegen >= TUNNEL_REGEN_MIN_INTERVAL_MS) {
+        restartTunnel(_opts.port);
+      } else {
+        log("INFO", `Resume: tunnel regen skipped (last regen ${Math.round(sinceRegen / 1000)}s ago); probe will heal if truly dead`);
+      }
     }
   }, RESUME_TICK_MS);