@hienlh/ppm 0.8.52 → 0.8.53

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.8.53] - 2026-03-25
+
+### Added
+- **Process supervisor**: Long-lived parent process manages server + tunnel children with auto-restart on crash (exponential backoff 1s→60s, resets after 5min stable)
+- **Tunnel resilience**: Auto-respawn cloudflared on death, extract new URL, sync to cloud immediately
+- **Server health watchdog**: GET /api/health every 30s, kills hung server after 3 consecutive failures
+- **Tunnel URL probe**: GET tunnelUrl/api/health every 2min, regenerates tunnel after 2 failures
+- **SIGUSR2 graceful restart**: `ppm restart` signals supervisor to restart server only (tunnel stays alive, no backoff)
+- **Count-based exception exit**: 3+ uncaught exceptions in 1 minute triggers exit for clean supervisor restart
+- **Integration tests**: 8 tests covering supervisor spawn, crash recovery, SIGUSR2 restart, backoff behavior
+
+### Changed
+- **Daemon mode**: `ppm start` now spawns supervisor process instead of server directly
+- **macOS autostart**: KeepAlive changed from conditional (SuccessfulExit=false) to unconditional
+- **Linux autostart**: Restart policy changed from `on-failure` to `always`
+- **`ppm stop`**: Kills supervisor PID first (cascades to children), 2s grace period
+- **`ppm status`**: Shows supervisor PID and alive status
+- **`ppm restart`**: Uses SIGUSR2 to supervisor for server-only restart
+
 ## [0.8.52] - 2026-03-25
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.52",
+  "version": "0.8.53",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/cli/commands/restart.ts

@@ -26,6 +26,45 @@ export async function restartServer(options: { config?: string }) {
     process.exit(1);
   }
 
+  // Supervisor-aware restart: send SIGUSR2 → supervisor restarts server child
+  const supervisorPid = status.supervisorPid as number | undefined;
+  if (supervisorPid) {
+    try { process.kill(supervisorPid, 0); } catch {
+      console.log("Supervisor not running. Use 'ppm stop && ppm start' instead.");
+      process.exit(1);
+    }
+
+    const oldServerPid = status.pid as number | undefined;
+    console.log("\n  Restarting PPM server via supervisor...");
+    console.log("  If you're using PPM terminal, wait a few seconds for auto-reconnect.\n");
+
+    try { process.kill(supervisorPid, "SIGUSR2"); } catch (e) {
+      console.error(`  ✗  Failed to signal supervisor: ${e}`);
+      process.exit(1);
+    }
+
+    // Wait for new server PID to appear in status.json (up to 15s)
+    const start = Date.now();
+    while (Date.now() - start < 15_000) {
+      await Bun.sleep(500);
+      try {
+        const newStatus = JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+        const newPid = newStatus.pid as number | undefined;
+        if (newPid && newPid !== oldServerPid) {
+          // Verify it's alive
+          try { process.kill(newPid, 0); } catch { continue; }
+          console.log(`  ✓  Restart complete (new PID: ${newPid})`);
+          if (newStatus.shareUrl) console.log(`  ➜  Share:   ${newStatus.shareUrl}`);
+          process.exit(0);
+        }
+      } catch {}
+    }
+
+    console.error("  ⚠  Restart timed out. Check: ppm logs");
+    process.exit(1);
+  }
+
+  // Legacy path: no supervisor (pre-supervisor daemon)
   const serverPid = status.pid as number | undefined;
   if (!serverPid) {
     console.log("No server PID found. Use 'ppm stop && ppm start' instead.");

package/src/cli/commands/status.ts

@@ -13,6 +13,8 @@ interface DaemonStatus {
   shareUrl: string | null;
   tunnelPid: number | null;
   tunnelAlive: boolean;
+  supervisorPid: number | null;
+  supervisorAlive: boolean;
 }
 
 function isAlive(pid: number): boolean {
@@ -23,6 +25,7 @@ function getDaemonStatus(): DaemonStatus {
   const dead: DaemonStatus = {
     running: false, pid: null, port: null, host: null,
     shareUrl: null, tunnelPid: null, tunnelAlive: false,
+    supervisorPid: null, supervisorAlive: false,
   };
 
   if (existsSync(STATUS_FILE)) {
@@ -31,6 +34,8 @@ function getDaemonStatus(): DaemonStatus {
       const pid = data.pid as number;
       const tunnelPid = (data.tunnelPid as number) ?? null;
       const tunnelAlive = tunnelPid ? isAlive(tunnelPid) : false;
+      const supervisorPid = (data.supervisorPid as number) ?? null;
+      const supervisorAlive = supervisorPid ? isAlive(supervisorPid) : false;
       return {
         running: isAlive(pid),
         pid,
@@ -39,6 +44,8 @@ function getDaemonStatus(): DaemonStatus {
         shareUrl: data.shareUrl ?? null,
         tunnelPid,
         tunnelAlive,
+        supervisorPid,
+        supervisorAlive,
       };
     } catch { return dead; }
   }
@@ -151,6 +158,9 @@ export async function showStatus(options: { json?: boolean; all?: boolean }) {
   }
 
   console.log(`\n  PPM daemon status\n`);
+  if (status.supervisorPid) {
+    console.log(`  Supervisor: ${status.supervisorAlive ? "running" : "stopped"} (PID: ${status.supervisorPid})`);
+  }
   console.log(`  Server:  ${status.running ? "running" : "stopped"} (PID: ${status.pid})`);
   if (status.port) console.log(`  Local:   http://localhost:${status.port}/`);
   if (status.tunnelPid) {

package/src/cli/commands/stop.ts

@@ -54,53 +54,70 @@ export async function stopServer(options?: { all?: boolean }) {
   if (options?.all) {
     console.log("  Stopping all PPM and cloudflared processes...\n");
     const cfKilled = killAllByName("cloudflared");
-    // Kill bun processes listening on PPM ports (from status.json or common ports)
-    let serverKilled = 0;
+    let killed = 0;
     if (existsSync(STATUS_FILE)) {
       try {
         const data = JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
-        if (data.pid) { killPid(data.pid, "server"); serverKilled++; }
+        // Kill supervisor first (cascades to server + tunnel children)
+        if (data.supervisorPid) { killPid(data.supervisorPid, "supervisor"); killed++; }
+        if (data.pid) { killPid(data.pid, "server"); killed++; }
+        if (data.tunnelPid) { killPid(data.tunnelPid, "tunnel"); killed++; }
       } catch {}
     }
     if (existsSync(PID_FILE)) {
       try {
         const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
-        if (!isNaN(pid)) { killPid(pid, "server (pidfile)"); serverKilled++; }
+        if (!isNaN(pid)) { killPid(pid, "supervisor/server (pidfile)"); killed++; }
       } catch {}
     }
     cleanup();
-    console.log(`\n  Done. Killed ${cfKilled} cloudflared + ${serverKilled} server process(es).`);
+    console.log(`\n  Done. Killed ${cfKilled} cloudflared + ${killed} PPM process(es).`);
     return;
   }
 
-  let status: { pid?: number; tunnelPid?: number } | null = null;
+  let status: { pid?: number; tunnelPid?: number; supervisorPid?: number } | null = null;
 
   // Read status.json
   if (existsSync(STATUS_FILE)) {
     try { status = JSON.parse(readFileSync(STATUS_FILE, "utf-8")); } catch {}
   }
 
-  // Fallback to ppm.pid
+  // Fallback to ppm.pid (now stores supervisor PID)
   const pidFromFile = existsSync(PID_FILE)
     ? parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10)
     : NaN;
 
-  const serverPid = status?.pid ?? (isNaN(pidFromFile) ? null : pidFromFile);
+  const supervisorPid = status?.supervisorPid ?? null;
+  const serverPid = status?.pid ?? null;
   const tunnelPid = status?.tunnelPid ?? null;
+  const fallbackPid = isNaN(pidFromFile) ? null : pidFromFile;
 
-  if (!serverPid && !tunnelPid) {
+  if (!supervisorPid && !serverPid && !tunnelPid && !fallbackPid) {
     console.log("No PPM daemon running.");
     cleanup();
     return;
   }
 
-  // Kill server process
-  if (serverPid) killPid(serverPid, "server");
+  // Kill supervisor first — its SIGTERM handler kills server + tunnel children
+  if (supervisorPid) {
+    killPid(supervisorPid, "supervisor");
+    // Give supervisor 2s to gracefully kill children
+    await Bun.sleep(2000);
+  } else if (fallbackPid) {
+    // Legacy: ppm.pid might be server PID (pre-supervisor) or supervisor PID
+    killPid(fallbackPid, "supervisor/server (pidfile)");
+    await Bun.sleep(1000);
+  }
 
-  // Kill tunnel process (independent from server)
-  if (tunnelPid) killPid(tunnelPid, "tunnel");
+  // Kill remaining children if supervisor didn't clean them up
+  if (serverPid) {
+    try { process.kill(serverPid, 0); killPid(serverPid, "server"); } catch {}
+  }
+  if (tunnelPid) {
+    try { process.kill(tunnelPid, 0); killPid(tunnelPid, "tunnel"); } catch {}
+  }
 
-  // Windows fallback: kill orphan cloudflared processes spawned by PPM
+  // Windows fallback: kill orphan cloudflared processes
   if (process.platform === "win32") {
     try {
       Bun.spawnSync(["taskkill", "/F", "/IM", "cloudflared.exe"], { stdout: "ignore", stderr: "ignore" });

package/src/server/index.ts

@@ -53,12 +53,29 @@ async function setupLogFile() {
   console.error = (...args: unknown[]) => { origError(...args); writeLog("ERROR", args); };
   console.warn = (...args: unknown[]) => { origWarn(...args); writeLog("WARN", args); };
 
-  // Capture uncaught errors
+  // Capture uncaught errors — count-based exit for supervisor restart
+  let exceptionCount = 0;
+  let lastExceptionTime = 0;
+
+  const handleFatalError = (label: string, detail: string) => {
+    writeLog("FATAL", [`${label}: ${detail}`]);
+    const now = Date.now();
+    if (now - lastExceptionTime < 60_000) exceptionCount++;
+    else exceptionCount = 1;
+    lastExceptionTime = now;
+
+    // 3+ fatal errors in 1 minute → exit and let supervisor restart fresh
+    if (exceptionCount >= 3) {
+      writeLog("FATAL", ["Too many errors in 1 min, exiting for supervisor restart"]);
+      process.exit(1);
+    }
+  };
+
   process.on("uncaughtException", (err) => {
-    writeLog("FATAL", [`Uncaught exception: ${err.stack ?? err.message}`]);
+    handleFatalError("Uncaught exception", err.stack ?? err.message);
   });
   process.on("unhandledRejection", (reason) => {
-    writeLog("FATAL", [`Unhandled rejection: ${reason}`]);
+    handleFatalError("Unhandled rejection", String(reason));
   });
 }
 
@@ -168,110 +185,52 @@ export async function startServer(options: {
   if (isDaemon) {
     const { resolve } = await import("node:path");
     const { homedir } = await import("node:os");
-    const { writeFileSync, readFileSync, mkdirSync, existsSync } = await import("node:fs");
+    const { writeFileSync, readFileSync, mkdirSync, existsSync, openSync } = await import("node:fs");
+    const { isCompiledBinary } = await import("../services/autostart-generator.ts");
 
     const ppmDir = resolve(homedir(), ".ppm");
     if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
     const pidFile = resolve(ppmDir, "ppm.pid");
     const statusFile = resolve(ppmDir, "status.json");
 
-    // If --share, download cloudflared and start tunnel as independent process
-    let shareUrl: string | undefined;
-    let tunnelPid: number | undefined;
+    // Kill any leftover processes from previous run
+    if (existsSync(statusFile)) {
+      try {
+        const prev = JSON.parse(readFileSync(statusFile, "utf-8"));
+        if (prev.supervisorPid) { try { process.kill(prev.supervisorPid); } catch {} }
+        else if (prev.pid) { try { process.kill(prev.pid); } catch {} }
+        if (prev.tunnelPid) { try { process.kill(prev.tunnelPid); } catch {} }
+      } catch {}
+    }
+
+    // Pre-download cloudflared if --share (so supervisor doesn't need to)
     if (options.share) {
+      console.log("  Ensuring cloudflared is available...");
       const { ensureCloudflared } = await import("../services/cloudflared.service.ts");
-      const bin = await ensureCloudflared();
-
-      // Kill any leftover tunnel from previous run
-      if (existsSync(statusFile)) {
-        try {
-          const prev = JSON.parse(readFileSync(statusFile, "utf-8"));
-          if (prev.tunnelPid) {
-            try { process.kill(prev.tunnelPid); } catch { /* already dead */ }
-          }
-        } catch {}
-      }
-
-      // Spawn new tunnel if no existing one
-      if (!shareUrl) {
-        console.log("  Starting share tunnel...");
-        const { openSync: openFd, writeFileSync: writeFs } = await import("node:fs");
-        const tunnelLog = resolve(ppmDir, "tunnel.log");
-        // Truncate old log so we only match the new tunnel URL
-        writeFs(tunnelLog, "");
-
-        if (process.platform === "win32") {
-          // Windows: use PowerShell for detached tunnel process
-          const psCmd = [
-            `$p = Start-Process -PassThru -WindowStyle Hidden`,
-            `-FilePath '${bin.replace(/\\/g, "\\\\")}'`,
-            `-ArgumentList 'tunnel','--url','http://localhost:${port}'`,
-            `-RedirectStandardError '${tunnelLog.replace(/\\/g, "\\\\")}'`,
-            `; Write-Output $p.Id`,
-          ].join(" ");
-          const result = Bun.spawnSync({
-            cmd: ["powershell", "-NoProfile", "-Command", psCmd],
-            stdout: "pipe", stderr: "pipe",
-          });
-          tunnelPid = parseInt(result.stdout.toString().trim(), 10);
-          if (isNaN(tunnelPid)) tunnelPid = undefined;
-        } else {
-          const tfd = openFd(tunnelLog, "a");
-          const tunnelProc = Bun.spawn({
-            cmd: [bin, "tunnel", "--url", `http://localhost:${port}`],
-            stdio: ["ignore", "ignore", tfd],
-            env: process.env,
-          });
-          tunnelProc.unref();
-          tunnelPid = tunnelProc.pid;
-        }
-
-        // Parse URL from tunnel.log (poll stderr output)
-        const urlRegex = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
-        const pollStart = Date.now();
-        while (Date.now() - pollStart < 30_000) {
-          await Bun.sleep(500);
-          try {
-            const logContent = readFileSync(tunnelLog, "utf-8");
-            const match = logContent.match(urlRegex);
-            if (match) { shareUrl = match[0]; break; }
-          } catch {}
-        }
-        if (!shareUrl) console.warn("  ⚠  Tunnel started but URL not detected.");
-      }
+      await ensureCloudflared();
     }
 
-    // Write preliminary status.json so child process can read shareUrl on startup
-    // (child reads this before parent has a chance to write PID — fixes race condition)
-    writeFileSync(statusFile, JSON.stringify({
-      port, host,
-      shareUrl: shareUrl ?? null,
-      tunnelPid: tunnelPid ?? null,
-    }));
-
-    // Spawn server child process with log file
-    const { openSync } = await import("node:fs");
-    const { isCompiledBinary } = await import("../services/autostart-generator.ts");
+    // Spawn supervisor process (manages server + tunnel children)
     const isCompiledBin = isCompiledBinary();
     const logFile = resolve(ppmDir, "ppm.log");
     const logFd = openSync(logFile, "a");
-    const { resolve: resolvePath } = await import("node:path");
-    const script = resolvePath(import.meta.dir, "index.ts");
-    // Keep positional order: port, host, config, profile (empty strings kept as placeholders)
-    const args = ["__serve__", String(port), host, options.config ?? "", options.profile ?? ""];
-    // Windows PowerShell: strip trailing empty args to avoid ArgumentList validation error
-    while (args.length > 0 && args[args.length - 1] === "") args.pop();
+    const supervisorScript = resolve(import.meta.dir, "..", "services", "supervisor.ts");
 
-    let childPid: number;
+    const superviseArgs = [
+      "__supervise__", String(port), host,
+      options.config ?? "", options.profile ?? "",
+    ];
+    if (options.share) superviseArgs.push("--share");
+    // Strip trailing empty args (before --share flag)
+    while (superviseArgs.length > 1 && superviseArgs[superviseArgs.length - 1] === "") superviseArgs.pop();
+
+    let supervisorPid: number;
 
     if (process.platform === "win32") {
-      // Windows: Bun.spawn child may die when parent exits (same job object).
-      // Use PowerShell Start-Process to create a truly detached process.
       const bunExe = process.execPath.replace(/\\/g, "\\\\");
       const logEscaped = logFile.replace(/\\/g, "\\\\");
       const errLog = logFile.replace(/\.log$/, ".err.log").replace(/\\/g, "\\\\");
-      // Use "_" placeholder for empty args — PowerShell rejects empty strings in ArgumentList
-      const winArgs = isCompiledBin ? args : ["run", script, ...args];
+      const winArgs = isCompiledBin ? superviseArgs : ["run", supervisorScript, ...superviseArgs];
       const argStr = winArgs.map((a) => `'${a || "_"}'`).join(",");
       const psCmd = [
         `$p = Start-Process -PassThru -WindowStyle Hidden`,
@@ -283,48 +242,73 @@ export async function startServer(options: {
       ].join(" ");
       const result = Bun.spawnSync({
         cmd: ["powershell", "-NoProfile", "-Command", psCmd],
-        stdout: "pipe",
-        stderr: "pipe",
+        stdout: "pipe", stderr: "pipe",
       });
-      childPid = parseInt(result.stdout.toString().trim(), 10);
-      if (isNaN(childPid)) {
-        console.error("  ✗  Failed to start daemon on Windows.");
+      supervisorPid = parseInt(result.stdout.toString().trim(), 10);
+      if (isNaN(supervisorPid)) {
+        console.error("  ✗  Failed to start supervisor on Windows.");
         console.error(`     ${result.stderr.toString().trim()}`);
         console.error("     Try: ppm start -f (foreground mode)");
         process.exit(1);
       }
     } else {
-      // macOS/Linux: Bun.spawn + unref works fine
-      // Compiled binary: execPath IS the server, no "run script" needed
       const cmd = isCompiledBin
-        ? [process.execPath, ...args]
-        : [process.execPath, "run", script, ...args];
+        ? [process.execPath, ...superviseArgs]
+        : [process.execPath, "run", supervisorScript, ...superviseArgs];
       const child = Bun.spawn({
         cmd,
         stdio: ["ignore", logFd, logFd],
         env: process.env,
       });
       child.unref();
-      childPid = child.pid;
+      supervisorPid = child.pid;
     }
 
-    // Verify daemon is alive after brief startup
-    await Bun.sleep(500);
-    let alive = false;
-    try { process.kill(childPid, 0); alive = true; } catch {}
-    if (!alive) {
-      console.error("  ✗  Daemon exited immediately after start.");
+    // Wait for supervisor to start server child (poll status.json for pid)
+    const startWait = Date.now();
+    let serverPid: number | null = null;
+    while (Date.now() - startWait < 10_000) {
+      await Bun.sleep(500);
+      // Check supervisor is still alive
+      try { process.kill(supervisorPid, 0); } catch {
+        console.error("  ✗  Supervisor exited immediately after start.");
+        console.error("     Check logs: ppm logs");
+        console.error("     Or try: ppm start -f (foreground mode)");
+        process.exit(1);
+      }
+      // Check if server PID appeared in status.json
+      try {
+        const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+        if (data.pid && data.supervisorPid) {
+          serverPid = data.pid;
+          break;
+        }
+      } catch {}
+    }
+
+    if (!serverPid) {
+      console.error("  ✗  Server did not start within 10 seconds.");
       console.error("     Check logs: ppm logs");
-      console.error("     Or try: ppm start -f (foreground mode)");
+      try { process.kill(supervisorPid); } catch {}
       process.exit(1);
     }
 
-    // Update status file with child PID + server script path for restart
-    const status = { pid: childPid, port, host, shareUrl: shareUrl ?? null, tunnelPid: tunnelPid ?? null, serverScript: script };
-    writeFileSync(statusFile, JSON.stringify(status));
-    writeFileSync(pidFile, String(childPid));
+    // Read final status for share URL
+    let shareUrl: string | null = null;
+    if (options.share) {
+      // Give tunnel a bit more time to establish
+      const tunnelWait = Date.now();
+      while (Date.now() - tunnelWait < 35_000) {
+        await Bun.sleep(500);
+        try {
+          const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+          if (data.shareUrl) { shareUrl = data.shareUrl; break; }
+        } catch {}
+      }
+      if (!shareUrl) console.warn("  ⚠  Tunnel started but URL not detected yet. Check: ppm status");
+    }
 
-    console.log(`  Daemon started (PID: ${childPid})\n`);
+    console.log(`  Supervisor started (PID: ${supervisorPid}, server PID: ${serverPid})\n`);
     console.log(`  ➜  Local:   http://localhost:${port}/`);
     if (shareUrl) {
       console.log(`  ➜  Share:   ${shareUrl}`);

package/src/services/autostart-generator.ts

@@ -90,10 +90,7 @@ ${programArgs}
     <key>RunAtLoad</key>
     <true/>
     <key>KeepAlive</key>
-    <dict>
-        <key>SuccessfulExit</key>
-        <false/>
-    </dict>
+    <true/>
     <key>StandardOutPath</key>
     <string>${escapeXml(logPath)}</string>
     <key>StandardErrorPath</key>
@@ -133,7 +130,7 @@ Wants=network-online.target
 [Service]
 Type=simple
 ExecStart=${execStart}
-Restart=on-failure
+Restart=always
 RestartSec=5
 ${envPath}
 WorkingDirectory=${homedir()}/.ppm

package/src/services/supervisor.ts

@@ -0,0 +1,387 @@
+/**
+ * Supervisor process — long-lived parent that manages server child + tunnel child.
+ * Respawns children on crash with exponential backoff.
+ * Health-checks server (/api/health) and tunnel URL (public probe).
+ * Entry: __supervise__ <port> <host> [config] [profile] [--share]
+ */
+import type { Subprocess } from "bun";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync, openSync, appendFileSync,
+} from "node:fs";
+import { isCompiledBinary } from "./autostart-generator.ts";
+
+// ─── Constants ─────────────────────────────────────────────────────────
+const MAX_RESTARTS = 10;
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_MAX_MS = 60_000;
+const STABLE_WINDOW_MS = 300_000;       // 5min stable → reset restart counter
+const SERVER_HEALTH_INTERVAL_MS = 30_000;
+const SERVER_HEALTH_FAIL_THRESHOLD = 3;
+const TUNNEL_PROBE_INTERVAL_MS = 120_000;
+const TUNNEL_PROBE_FAIL_THRESHOLD = 2;
+const TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+const PPM_DIR = resolve(homedir(), ".ppm");
+const STATUS_FILE = resolve(PPM_DIR, "status.json");
+const PID_FILE = resolve(PPM_DIR, "ppm.pid");
+const LOG_FILE = resolve(PPM_DIR, "ppm.log");
+
+// ─── State ─────────────────────────────────────────────────────────────
+let serverChild: Subprocess | null = null;
+let tunnelChild: Subprocess | null = null;
+let tunnelUrl: string | null = null;
+let shuttingDown = false;
+
+let serverRestarts = 0;
+let lastServerCrash = 0;
+let tunnelRestarts = 0;
+let lastTunnelCrash = 0;
+
+let healthFailCount = 0;
+let tunnelFailCount = 0;
+let serverRestartRequested = false; // SIGUSR2 flag — skip backoff on next crash
+
+// Timers for cleanup
+let healthTimer: ReturnType<typeof setInterval> | null = null;
+let tunnelProbeTimer: ReturnType<typeof setInterval> | null = null;
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+// ─── Logging ───────────────────────────────────────────────────────────
+function log(level: string, msg: string) {
+  const ts = new Date().toISOString();
+  const line = `[${ts}] [${level}] [supervisor] ${msg}\n`;
+  try { appendFileSync(LOG_FILE, line); } catch {}
+  if (level === "ERROR" || level === "FATAL") {
+    process.stderr.write(line);
+  }
+}
+
+// ─── Status management ─────────────────────────────────────────────────
+function readStatus(): Record<string, unknown> {
+  try {
+    if (existsSync(STATUS_FILE)) return JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+  } catch {}
+  return {};
+}
+
+function updateStatus(patch: Record<string, unknown>) {
+  try {
+    const data = { ...readStatus(), ...patch };
+    writeFileSync(STATUS_FILE, JSON.stringify(data));
+  } catch {}
+}
+
+// ─── Backoff calc ──────────────────────────────────────────────────────
+function backoffDelay(restartCount: number): number {
+  return Math.min(BACKOFF_BASE_MS * 2 ** (restartCount - 1), BACKOFF_MAX_MS);
+}
+
+// ─── Server management ─────────────────────────────────────────────────
+export async function spawnServer(
+  serverArgs: string[],
+  logFd: number,
+): Promise<void> {
+  const cmd = isCompiledBinary()
+    ? [process.execPath, ...serverArgs]
+    : [process.execPath, "run", resolve(import.meta.dir, "..", "server", "index.ts"), ...serverArgs];
+
+  serverChild = Bun.spawn({
+    cmd,
+    stdio: ["ignore", logFd, logFd],
+    env: process.env,
+  });
+
+  const childPid = serverChild.pid;
+  updateStatus({ pid: childPid });
+  writeFileSync(PID_FILE, String(process.pid)); // supervisor PID for stop
+  log("INFO", `Server started (PID: ${childPid})`);
+
+  const exitCode = await serverChild.exited;
+  serverChild = null;
+
+  if (exitCode === 0 || shuttingDown) {
+    log("INFO", `Server exited cleanly (code ${exitCode})`);
+    return;
+  }
+
+  // SIGUSR2 restart — skip backoff, respawn immediately
+  if (serverRestartRequested) {
+    serverRestartRequested = false;
+    log("INFO", `Server restarting (SIGUSR2), no backoff`);
+    if (!shuttingDown) return spawnServer(serverArgs, logFd);
+    return;
+  }
+
+  // Crash — apply backoff
+  const now = Date.now();
+  if (now - lastServerCrash > STABLE_WINDOW_MS) serverRestarts = 0;
+  lastServerCrash = now;
+  serverRestarts++;
+
+  if (serverRestarts > MAX_RESTARTS) {
+    log("FATAL", `Server exceeded ${MAX_RESTARTS} restarts, giving up`);
+    shutdown();
+    return;
+  }
+
+  const delay = backoffDelay(serverRestarts);
+  log("WARN", `Server crashed (exit ${exitCode}), restarting in ${delay}ms (#${serverRestarts})`);
+  await Bun.sleep(delay);
+
+  if (!shuttingDown) return spawnServer(serverArgs, logFd);
+}
+
+// ─── Tunnel management ─────────────────────────────────────────────────
+async function extractUrlFromStderr(stderr: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stderr.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error("Tunnel URL timeout (30s)")), 30_000);
+
+    const read = async () => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const match = buffer.match(TUNNEL_URL_REGEX);
+          if (match) {
+            clearTimeout(timeout);
+            // Keep draining in background to avoid SIGPIPE
+            (async () => {
+              try { while (!(await reader.read()).done) {} } catch {}
+            })();
+            resolve(match[0]);
+            return;
+          }
+        }
+        clearTimeout(timeout);
+        reject(new Error("cloudflared exited without providing URL"));
+      } catch (err) {
+        clearTimeout(timeout);
+        reject(err);
+      }
+    };
+    read();
+  });
+}
+
+async function syncUrlToCloud(url: string) {
+  try {
+    const { sendHeartbeat, getCloudDevice } = await import("./cloud.service.ts");
+    if (getCloudDevice()) {
+      const ok = await sendHeartbeat(url);
+      if (ok) log("INFO", `Cloud synced: ${url}`);
+      else log("WARN", "Cloud sync failed (non-blocking)");
+    }
+  } catch {}
+}
+
+function startCloudHeartbeat(url: string) {
+  if (heartbeatTimer) clearInterval(heartbeatTimer);
+  heartbeatTimer = setInterval(() => {
+    if (tunnelUrl) syncUrlToCloud(tunnelUrl);
+  }, 5 * 60 * 1000);
+}
+
+export async function spawnTunnel(port: number): Promise<void> {
+  let bin: string;
+  try {
+    const { ensureCloudflared } = await import("./cloudflared.service.ts");
+    bin = await ensureCloudflared();
+  } catch (err) {
+    log("ERROR", `Failed to get cloudflared: ${err}`);
+    return;
+  }
+
+  tunnelChild = Bun.spawn(
+    [bin, "tunnel", "--url", `http://127.0.0.1:${port}`],
+    { stderr: "pipe", stdout: "ignore", stdin: "ignore" },
+  );
+
+  try {
+    tunnelUrl = await extractUrlFromStderr(tunnelChild.stderr as ReadableStream<Uint8Array>);
+  } catch (err) {
+    log("ERROR", `Tunnel URL extraction failed: ${err}`);
+    tunnelUrl = null;
+    try { tunnelChild.kill(); } catch {}
+    tunnelChild = null;
+
+    if (shuttingDown) return;
+    tunnelRestarts++;
+    const delay = backoffDelay(tunnelRestarts);
+    log("WARN", `Tunnel failed, retry in ${delay}ms (#${tunnelRestarts})`);
+    await Bun.sleep(delay);
+    return spawnTunnel(port);
+  }
+
+  updateStatus({ shareUrl: tunnelUrl, tunnelPid: tunnelChild.pid });
+  log("INFO", `Tunnel ready: ${tunnelUrl} (PID: ${tunnelChild.pid})`);
+
+  // Sync new URL to cloud immediately + start periodic heartbeat
+  await syncUrlToCloud(tunnelUrl);
+  startCloudHeartbeat(tunnelUrl);
+
+  const exitCode = await tunnelChild.exited;
+  tunnelChild = null;
+  const deadUrl = tunnelUrl;
+  tunnelUrl = null;
+
+  if (shuttingDown) return;
+
+  // Crash — apply backoff
+  const now = Date.now();
+  if (now - lastTunnelCrash > STABLE_WINDOW_MS) tunnelRestarts = 0;
+  lastTunnelCrash = now;
+  tunnelRestarts++;
+
+  if (tunnelRestarts > MAX_RESTARTS) {
+    log("ERROR", `Tunnel exceeded ${MAX_RESTARTS} restarts, disabling tunnel`);
+    updateStatus({ shareUrl: null, tunnelPid: null });
+    return;
+  }
+
+  const delay = backoffDelay(tunnelRestarts);
+  log("WARN", `Tunnel died (exit ${exitCode}, was ${deadUrl}), restart in ${delay}ms (#${tunnelRestarts})`);
+  await Bun.sleep(delay);
+
+  if (!shuttingDown) return spawnTunnel(port);
+}
+
+// ─── Health checks ─────────────────────────────────────────────────────
+function startServerHealthCheck(port: number) {
+  healthTimer = setInterval(async () => {
+    if (shuttingDown || !serverChild) return;
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) { healthFailCount = 0; return; }
+    } catch {}
+    healthFailCount++;
+    if (healthFailCount >= SERVER_HEALTH_FAIL_THRESHOLD && serverChild) {
+      log("WARN", `Server unresponsive (${healthFailCount} failures), killing`);
+      try { serverChild.kill(); } catch {}
+      healthFailCount = 0;
+      // spawnServer loop handles respawn via exited promise
+    }
+  }, SERVER_HEALTH_INTERVAL_MS);
+}
+
+function startTunnelProbe(port: number) {
+  tunnelProbeTimer = setInterval(async () => {
+    if (shuttingDown || !tunnelUrl || !tunnelChild) {
+      tunnelFailCount = 0;
+      return;
+    }
+    try {
+      const res = await fetch(`${tunnelUrl}/api/health`, {
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok) {
+        tunnelFailCount = 0;
+        tunnelRestarts = 0; // reset on success
+        return;
+      }
+    } catch {}
+    tunnelFailCount++;
+    if (tunnelFailCount >= TUNNEL_PROBE_FAIL_THRESHOLD && tunnelChild) {
+      log("WARN", `Tunnel URL dead (${tunnelFailCount} failures), regenerating`);
+      try { tunnelChild.kill(); } catch {}
+      tunnelFailCount = 0;
+      // spawnTunnel loop handles respawn via exited promise
+    }
+  }, TUNNEL_PROBE_INTERVAL_MS);
+}
+
+// ─── Shutdown ──────────────────────────────────────────────────────────
+export function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  log("INFO", "Supervisor shutting down");
+
+  if (healthTimer) clearInterval(healthTimer);
+  if (tunnelProbeTimer) clearInterval(tunnelProbeTimer);
+  if (heartbeatTimer) clearInterval(heartbeatTimer);
+
+  if (serverChild) { try { serverChild.kill(); } catch {} }
+  if (tunnelChild) { try { tunnelChild.kill(); } catch {} }
+}
+
+// ─── Main entry ────────────────────────────────────────────────────────
+export async function runSupervisor(opts: {
+  port: number;
+  host: string;
+  config?: string;
+  profile?: string;
+  share: boolean;
+}) {
+  if (!existsSync(PPM_DIR)) mkdirSync(PPM_DIR, { recursive: true });
+
+  const logFd = openSync(LOG_FILE, "a");
+  log("INFO", `Supervisor started (PID: ${process.pid}, port: ${opts.port}, share: ${opts.share})`);
+
+  // Write supervisor PID
+  writeFileSync(PID_FILE, String(process.pid));
+  updateStatus({ supervisorPid: process.pid, port: opts.port, host: opts.host });
+
+  // Build __serve__ args
+  const serverArgs = [
+    "__serve__", String(opts.port), opts.host,
+    opts.config ?? "", opts.profile ?? "",
+  ];
+  // Strip trailing empty args
+  while (serverArgs.length > 0 && serverArgs[serverArgs.length - 1] === "") serverArgs.pop();
+
+  // Signal handlers
+  process.on("SIGTERM", () => { shutdown(); process.exit(0); });
+  process.on("SIGINT", () => { shutdown(); process.exit(0); });
+
+  // SIGUSR2 = graceful server restart (tunnel stays alive)
+  process.on("SIGUSR2", () => {
+    log("INFO", "SIGUSR2 received, restarting server only");
+    if (serverChild) {
+      serverRestartRequested = true; // flag so spawnServer skips backoff
+      try { serverChild.kill(); } catch {}
+    }
+  });
+
+  // Start health checks
+  startServerHealthCheck(opts.port);
+
+  // Spawn server + tunnel in parallel
+  const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];
+
+  if (opts.share) {
+    startTunnelProbe(opts.port);
+    promises.push(spawnTunnel(opts.port));
+  }
+
+  await Promise.all(promises);
+
+  // If we get here, both loops exited (shutdown or max restarts)
+  log("INFO", "Supervisor exiting");
+  process.exit(shuttingDown ? 0 : 1);
+}
+
+// ─── CLI entry point ───────────────────────────────────────────────────
+if (process.argv.includes("__supervise__")) {
+  const idx = process.argv.indexOf("__supervise__");
+  const port = parseInt(process.argv[idx + 1] ?? "8080", 10);
+  const host = process.argv[idx + 2] ?? "0.0.0.0";
+  const config = process.argv[idx + 3] && process.argv[idx + 3] !== "_" ? process.argv[idx + 3] : undefined;
+  const profile = process.argv[idx + 4] && process.argv[idx + 4] !== "_" ? process.argv[idx + 4] : undefined;
+  const share = process.argv.includes("--share");
+
+  // Set DB profile for supervisor (needed to read config)
+  if (profile) {
+    const { setDbProfile } = await import("./db.service.ts");
+    setDbProfile(profile);
+  }
+
+  runSupervisor({ port, host, config, profile, share });
+}