@hienlh/ppm 0.17.28 → 0.17.29

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.17.29] - 2026-08-25
+
+### Fixed
+- **PPM said it had started but nothing answered** — `ppm start` printed the local address and a share link, yet neither localhost nor the link ever responded, and the status file kept insisting everything was running while every process it referred to was already dead. Two things went wrong in sequence, both on Windows. First, before starting the server, PPM briefly listens on the port itself to make sure it is free; starting the share tunnel at the same moment made Windows hand the tunnel a copy of that short-lived listening socket — a copy the tunnel never closes — so the port stayed occupied and the real server could never take it, timing out after ten seconds on every attempt. Second, the supervisor then went looking for whichever process was hogging the port so it could clear it out, and the answer came back as the supervisor itself — which it dutifully killed, taking the server, the tunnel and its own status reporting down with it. That is why the status file still said "running": nothing was left alive to correct it. The port check and the starting of child processes now take turns instead of overlapping, so the socket can no longer leak into a child; and if the port ever does show up as held by the supervisor itself, it restarts the tunnel — the only thing that can actually be holding the leaked copy — rather than killing itself.
+- **PPM's reserved memory could grow without limit on Windows** — the supervisor takes a periodic inventory of the helper processes the server has started, so that after a crash it knows exactly what to clean up. Each inventory launches a PowerShell and builds a list of every process on the machine, which is fine on its own — but on a busy machine one inventory could still be running when the next fired, and every simultaneous run permanently reserved a chunk of memory that was never returned to the system. Left long enough this ratcheted up to an observed 19GB of reserved memory against 1GB actually in use. Inventories now run one at a time — a tick that finds the previous one still running simply skips its turn — and a PowerShell that gets stuck is cut off after twenty seconds instead of lingering forever.
+
 ## [0.17.28] - 2026-08-21
 
 ### Added

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

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

@@ -282,4 +282,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.28 -->
+<!-- Generated from src/server/routes/ for PPM v0.17.29 -->

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.17.28",
-  "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
+  "version": "0.17.29",
+  "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "SEE LICENSE IN LICENSE",
   "module": "src/index.ts",

package/skills-lock.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "skills": {
+    "game-assets": {
+      "source": "Meowa-AI/meowa-skills",
+      "sourceType": "github",
+      "skillPath": "skills/game-assets/SKILL.md",
+      "computedHash": "b3ceb77a09475144f2a598da451ec57a4f4e3994711b62a8eeae60a25fd2d916"
+    }
+  }
+}

package/spike-memory-region-dump.ps1

@@ -0,0 +1,69 @@
+# Enumerate committed memory regions of a process via VirtualQueryEx.
+# Reveals allocation shape: many small regions (per-iteration leak) vs few huge (allocator arena).
+param([int]$ProcessId)
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public class MemProbe {
+  [StructLayout(LayoutKind.Sequential)]
+  public struct MEMORY_BASIC_INFORMATION {
+    public IntPtr BaseAddress;
+    public IntPtr AllocationBase;
+    public uint AllocationProtect;
+    public uint Alignment1;
+    public IntPtr RegionSize;
+    public uint State;
+    public uint Protect;
+    public uint Type;
+    public uint Alignment2;
+  }
+  [DllImport("kernel32.dll", SetLastError=true)]
+  public static extern IntPtr OpenProcess(uint access, bool inherit, int pid);
+  [DllImport("kernel32.dll", SetLastError=true)]
+  public static extern int VirtualQueryEx(IntPtr h, IntPtr addr, out MEMORY_BASIC_INFORMATION mbi, int len);
+  [DllImport("kernel32.dll")]
+  public static extern bool CloseHandle(IntPtr h);
+}
+"@
+
+$h = [MemProbe]::OpenProcess(0x0400 -bor 0x0010, $false, $ProcessId)
+if ($h -eq [IntPtr]::Zero) { Write-Error "OpenProcess failed: $([ComponentModel.Win32Exception]::new([Runtime.InteropServices.Marshal]::GetLastWin32Error()).Message)"; exit 1 }
+
+$size = [Runtime.InteropServices.Marshal]::SizeOf([type][MemProbe+MEMORY_BASIC_INFORMATION])
+$addr = [IntPtr]::Zero
+$regions = New-Object System.Collections.ArrayList
+$max = [Int64]0x7FFFFFFFFFFF
+
+while ([Int64]$addr -lt $max) {
+  $mbi = New-Object MemProbe+MEMORY_BASIC_INFORMATION
+  if ([MemProbe]::VirtualQueryEx($h, $addr, [ref]$mbi, $size) -eq 0) { break }
+  $rs = [Int64]$mbi.RegionSize
+  if ($rs -le 0) { break }
+  # MEM_COMMIT=0x1000, MEM_PRIVATE=0x20000
+  if ($mbi.State -eq 0x1000 -and $mbi.Type -eq 0x20000) {
+    [void]$regions.Add([pscustomobject]@{ Base=$mbi.BaseAddress; Size=$rs; Protect=$mbi.Protect })
+  }
+  $addr = [IntPtr]([Int64]$addr + $rs)
+}
+[void][MemProbe]::CloseHandle($h)
+
+$total = ($regions | Measure-Object -Property Size -Sum).Sum
+"PID $ProcessId : committed-private regions = $($regions.Count), total = $([math]::Round($total/1GB,2)) GB"
+""
+"--- by protection flag ---"
+$regions | Group-Object Protect | Sort-Object { ($_.Group | Measure-Object Size -Sum).Sum } -Descending |
+  Select-Object @{n='Protect';e={'0x{0:X}' -f [int]$_.Name}}, Count,
+                @{n='TotalGB';e={[math]::Round((($_.Group|Measure-Object Size -Sum).Sum)/1GB,2)}} |
+  Format-Table -AutoSize
+
+"--- by region size bucket ---"
+$regions | Group-Object { [math]::Pow(2,[math]::Floor([math]::Log($_.Size,2))) } |
+  Sort-Object { ($_.Group | Measure-Object Size -Sum).Sum } -Descending |
+  Select-Object -First 12 @{n='BucketMB';e={[math]::Round([double]$_.Name/1MB,3)}}, Count,
+                @{n='TotalGB';e={[math]::Round((($_.Group|Measure-Object Size -Sum).Sum)/1GB,2)}} |
+  Format-Table -AutoSize
+
+"--- top 10 single regions ---"
+$regions | Sort-Object Size -Descending | Select-Object -First 10 @{n='Base';e={'0x{0:X}' -f [Int64]$_.Base}},
+  @{n='MB';e={[math]::Round($_.Size/1MB,1)}}, @{n='Protect';e={'0x{0:X}' -f [int]$_.Protect}} | Format-Table -AutoSize

package/src/services/supervisor.ts

@@ -109,6 +109,22 @@ function backoffDelay(restartCount: number): number {
   return Math.min(BACKOFF_BASE_MS * 2 ** (restartCount - 1), BACKOFF_MAX_MS);
 }
 
+// ─── Probe/spawn gate ──────────────────────────────────────────────────
+// On Windows, spawning a child with fd stdio turns on handle inheritance for
+// the whole process, so EVERY inheritable handle — including a port-probe
+// listener that happens to be open at that instant — is duplicated into the
+// child. The child (cloudflared, server) never closes the copy, the kernel
+// keeps the port in LISTEN, and the server child can never bind: startup
+// crash-loops with "port still in use" while netstat blames the supervisor.
+// Serialize all bind probes and all child spawns through this gate so a probe
+// socket is never open across a CreateProcess. Never nest gated calls.
+let probeSpawnGate: Promise<unknown> = Promise.resolve();
+function withProbeSpawnGate<T>(fn: () => Promise<T> | T): Promise<T> {
+  const run = probeSpawnGate.then(fn);
+  probeSpawnGate = run.catch(() => {});
+  return run;
+}
+
 // ─── Port recovery ─────────────────────────────────────────────────────
 // The probe socket really listens, so clients retrying against the port (browser
 // tabs, extension/chat WebSockets after a server restart) can connect to it. An
@@ -116,7 +132,9 @@ function backoffDelay(restartCount: number): number {
 // before it ever spawned — supervisor alive, tunnel alive, nothing serving.
 // Hence: drop incoming connections, and never let the probe outlive the timeout.
 function isPortBindable(port: number, host: string): Promise<boolean> {
-  return new Promise((resolve) => {
+  // Gated: the probe listener must never be open while a child is spawned,
+  // or the child inherits the socket handle and wedges the port (see gate).
+  return withProbeSpawnGate(() => new Promise<boolean>((resolve) => {
     const net = require("node:net") as typeof import("node:net");
     let settled = false;
     const finish = (bindable: boolean) => {
@@ -135,7 +153,7 @@ function isPortBindable(port: number, host: string): Promise<boolean> {
     tester.once("error", () => finish(false));
     tester.once("listening", () => tester.close(() => finish(true)));
     tester.listen(port, host);
-  });
+  }));
 }
 
 /**
@@ -157,7 +175,17 @@ async function ensureBindablePort(preferred: number, host: string): Promise<numb
     if (holderPid > 0) {
       let alive = false;
       try { process.kill(holderPid, 0); alive = true; } catch {}
-      if (alive && isPpmProcess(holderPid)) {
+      if (holderPid === process.pid) {
+        // The LISTEN entry is our own leaked probe socket, kept open by a
+        // child that inherited the handle at spawn time. killProcessTree here
+        // would kill THIS supervisor (and everything under it) — the exact
+        // "starts then dies, status.json says running" failure. Bounce the
+        // tunnel instead: cloudflared is the detached child holding the
+        // inherited handle, and replacing it releases the port.
+        log("WARN", `Port ${preferred} LISTEN owned by this supervisor — leaked probe handle inherited by a child; bouncing tunnel to release it`);
+        restartTunnel(preferred);
+        await Bun.sleep(1500);
+      } else if (alive && isPpmProcess(holderPid)) {
         log("WARN", `Port ${preferred} held by stale PPM process (PID ${holderPid}) — reclaiming`);
         killProcessTree(holderPid);
         await Bun.sleep(800);
@@ -278,7 +306,8 @@ export async function spawnServer(
     ? [process.execPath, ...serverArgs]
     : [process.execPath, "run", resolve(import.meta.dir, "..", "server", "index.ts"), ...serverArgs];
 
-  serverChild = Bun.spawn({
+  // Gated: never spawn while a port probe is open (see gate).
+  serverChild = await withProbeSpawnGate(() => Bun.spawn({
     cmd,
     stdio: ["ignore", logFd, logFd],
     env: process.env,
@@ -286,7 +315,7 @@ export async function spawnServer(
     // supervisor is spawned consoleless (detached), so without this its console
     // children — and the Claude SDK grandchildren they spawn — pop blank windows.
     windowsHide: true,
-  });
+  }));
 
   const childPid = serverChild.pid;
   updateStatus({ pid: childPid });
@@ -427,11 +456,13 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // when the supervisor itself was started consoleless by the upgrade path.
   if (process.platform === "win32") {
     const { spawn: nodeSpawn } = require("node:child_process") as typeof import("node:child_process");
-    const proc = nodeSpawn(bin, quickArgs, {
+    // Gated: fd stdio enables handle inheritance — spawning while a port
+    // probe is open would hand cloudflared the listener handle (see gate).
+    const proc = await withProbeSpawnGate(() => nodeSpawn(bin, quickArgs, {
       detached: true,
       windowsHide: true,
       stdio: ["ignore", "ignore", tunnelLogFd] as ["ignore", "ignore", number],
-    });
+    }));
     proc.unref();
     try { closeSync(tunnelLogFd); } catch {}  // child keeps its own fd
     const pid = proc.pid ?? null;
@@ -497,7 +528,8 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // self-contained; we only touch the global when it still points at us.
   let child: Subprocess;
   try {
-    child = Bun.spawn(tunnelCmd, { stderr: tunnelLogFd, stdout: "ignore", stdin: "ignore" });
+    child = await withProbeSpawnGate(() =>
+      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
@@ -840,13 +872,7 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     const portFreeStart = Date.now();
     const portTimeout = process.platform === "win32" ? 3_000 : 10_000;
     while (Date.now() - portFreeStart < portTimeout) {
-      const inUse = await new Promise<boolean>((resolve) => {
-        const net = require("node:net") as typeof import("node:net");
-        const tester = net.createServer()
-          .once("error", (e: NodeJS.ErrnoException) => resolve(e.code === "EADDRINUSE"))
-          .once("listening", () => tester.close(() => resolve(false)))
-          .listen(_opts.port, _opts.host);
-      });
+      const inUse = !(await isPortBindable(_opts.port, _opts.host));
       if (!inUse) break;
       log("DEBUG", `Port ${_opts.port} still in use, waiting...`);
       await Bun.sleep(200);
@@ -858,13 +884,7 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     // supervisor can never bind. Resolve the real holder via netstat and
     // tree-kill it so the handoff doesn't dead-end on a zombie port.
     if (process.platform === "win32") {
-      const stillInUse = await new Promise<boolean>((resolve) => {
-        const net = require("node:net") as typeof import("node:net");
-        const tester = net.createServer()
-          .once("error", (e: NodeJS.ErrnoException) => resolve(e.code === "EADDRINUSE"))
-          .once("listening", () => tester.close(() => resolve(false)))
-          .listen(_opts.port, _opts.host);
-      });
+      const stillInUse = !(await isPortBindable(_opts.port, _opts.host));
       if (stillInUse) {
         const holderPid = findPortListenerPid(_opts.port);
         if (holderPid > 0) {
@@ -884,12 +904,13 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     // launchd/systemd tears the replacement down along with our process group
     // the moment we exit — it dies seconds after adopting the tunnel.
     const { spawn: nodeSpawn } = require("node:child_process") as typeof import("node:child_process");
-    const proc = nodeSpawn(cmd[0]!, cmd.slice(1), {
+    // Gated: never spawn while a port probe is open (see gate).
+    const proc = await withProbeSpawnGate(() => nodeSpawn(cmd[0]!, cmd.slice(1), {
       detached: true,
       stdio: ["ignore", newLogFd, newLogFd] as any,
       env: process.env as NodeJS.ProcessEnv,
       windowsHide: true,
-    });
+    }));
     const killNewChild = () => { try { if (proc.pid) process.kill(proc.pid); } catch {} };
     proc.unref();
     try { closeSync(newLogFd); } catch {} // child inherited fd, parent can close

package/src/services/windows-process-tree.ts

@@ -79,14 +79,24 @@ const trackedFile = () => resolve(getPpmDir(), "tracked-descendants.json");
 const PS_LIST_CMD =
   'Get-CimInstance Win32_Process | ForEach-Object { "$($_.ProcessId)|$($_.ParentProcessId)|$($_.CreationDate.Ticks)" }';
 
+// Shorter than the caller's 30s poll, so a wedged PowerShell can never outlive
+// the interval that spawned it and stack up behind the in-flight guard.
+const LIST_TIMEOUT_MS = 20_000;
+
 async function listProcesses(): Promise<Map<number, { ppid: number; ticks: string }>> {
   const map = new Map<number, { ppid: number; ticks: string }>();
   const proc = Bun.spawn(
     ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", PS_LIST_CMD],
     { stdout: "pipe", stderr: "ignore", stdin: "ignore", windowsHide: true },
   );
-  const out = await new Response(proc.stdout).text();
-  await proc.exited;
+  const killTimer = setTimeout(() => { try { proc.kill(); } catch {} }, LIST_TIMEOUT_MS);
+  let out: string;
+  try {
+    out = await new Response(proc.stdout).text();
+    await proc.exited;
+  } finally {
+    clearTimeout(killTimer);
+  }
   for (const line of out.split("\n")) {
     const [pidStr, ppidStr, ticks] = line.trim().split("|");
     const pid = parseInt(pidStr ?? "", 10);
@@ -136,8 +146,17 @@ export function killProcessTree(pid: number): void {
  * matching creation time) are kept even if they have since orphaned out of
  * the tree — that is exactly the case the reaper exists for.
  */
+let snapshotInFlight = false;
+
 export async function snapshotServerDescendants(rootPid: number): Promise<void> {
   if (process.platform !== "win32") return;
+  // The supervisor fires this from a timer without awaiting. Every concurrent
+  // call spawns a PowerShell and builds a full process map, which costs a 32MiB
+  // allocator segment that is never returned to the OS — so overlapping calls
+  // ratchet the process commit charge up permanently (observed: 19GB committed
+  // against 1GB resident). One at a time; a skipped tick is harmless.
+  if (snapshotInFlight) return;
+  snapshotInFlight = true;
   try {
     const procs = await listProcesses();
 
@@ -166,7 +185,9 @@ export async function snapshotServerDescendants(rootPid: number): Promise<void>
     }
 
     writeFileSync(trackedFile(), JSON.stringify([...tracked.values()]));
-  } catch {}
+  } catch {} finally {
+    snapshotInFlight = false;
+  }
 }
 
 /**