@hienlh/ppm 0.8.71 → 0.8.73

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.8.73] - 2026-04-01
+
+### Fixed
+- **Cloud WS reconnect loop**: Stale WebSocket closure handlers from replaced connections no longer reset module state — prevents infinite reconnect cycle after upgrade/restart
+
+## [0.8.72] - 2026-03-31
+
+### Added
+- **Supervisor state machine**: States `running → paused → upgrading` with promise-based wait/resume. Supervisor pauses after 10 consecutive crashes, resumes via `ppm restart --force` or SIGUSR2
+- **Cloud WebSocket client**: Persistent WS connection from supervisor to PPM Cloud replacing HTTP heartbeat — auto-reconnect with exponential backoff + jitter, 60s heartbeat, 50-message offline queue
+- **Remote commands via Cloud**: Supervisor handles restart/stop/upgrade/resume/status commands received from Cloud WS
+- **`ppm restart --force`**: Resume a paused supervisor (crashed too many times)
+- **Status CLI state display**: `ppm status` shows paused/upgrading state with reason, timestamp, and last crash error
+
+### Changed
+- **Foreground mode removed**: `ppm start` no longer accepts `-f`/`--foreground` — always runs as supervised daemon
+- **Heartbeat via WS**: Cloud heartbeat migrated from HTTP polling (5min) to WebSocket (60s), includes `appVersion`, `serverPid`, `uptime`
+
+### Fixed
+- **Upgrade failure recovery**: `selfReplace` failure now correctly resets state from "upgrading" back to "running" and notifies Cloud
+
 ## [0.8.71] - 2026-03-31
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.8.71",
+  "version": "0.8.73",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",
@@ -11,7 +11,7 @@
   },
   "scripts": {
     "dev": "concurrently \"bun run dev:server\" \"bun run dev:web\"",
-    "dev:server": "bun run --hot src/index.ts start --profile dev -f",
+    "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",
     "build:web": "bun run vite build --config vite.config.ts",
     "build": "bun run build:web && bun build src/index.ts --compile --outfile dist/ppm",

package/src/cli/commands/restart.ts

@@ -9,7 +9,7 @@ const RESTARTING_FLAG = resolve(PPM_DIR, ".restarting");
 const RESTART_RESULT = resolve(PPM_DIR, ".restart-result");
 
 /** Restart only the server process, keeping the tunnel alive */
-export async function restartServer(options: { config?: string }) {
+export async function restartServer(options: { config?: string; force?: boolean }) {
   // Ignore SIGHUP so this process survives when PPM terminal dies
   process.on("SIGHUP", () => {});
 
@@ -34,6 +34,14 @@ export async function restartServer(options: { config?: string }) {
       process.exit(1);
     }
 
+    // Check if supervisor is paused — require --force to resume
+    const state = status.state as string | undefined;
+    if (state === "paused" && !options.force) {
+      console.log("\n  Server is paused (crashed too many times).");
+      console.log("  Use 'ppm restart --force' to resume.\n");
+      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");

package/src/cli/commands/status.ts

@@ -15,6 +15,10 @@ interface DaemonStatus {
   tunnelAlive: boolean;
   supervisorPid: number | null;
   supervisorAlive: boolean;
+  state: string | null;
+  pausedAt: string | null;
+  pauseReason: string | null;
+  lastCrashError: string | null;
 }
 
 function isAlive(pid: number): boolean {
@@ -26,6 +30,7 @@ function getDaemonStatus(): DaemonStatus {
     running: false, pid: null, port: null, host: null,
     shareUrl: null, tunnelPid: null, tunnelAlive: false,
     supervisorPid: null, supervisorAlive: false,
+    state: null, pausedAt: null, pauseReason: null, lastCrashError: null,
   };
 
   if (existsSync(STATUS_FILE)) {
@@ -46,6 +51,10 @@ function getDaemonStatus(): DaemonStatus {
         tunnelAlive,
         supervisorPid,
         supervisorAlive,
+        state: (data.state as string) ?? null,
+        pausedAt: (data.pausedAt as string) ?? null,
+        pauseReason: (data.pauseReason as string) ?? null,
+        lastCrashError: (data.lastCrashError as string) ?? null,
       };
     } catch { return dead; }
   }
@@ -161,6 +170,16 @@ export async function showStatus(options: { json?: boolean; all?: boolean }) {
   if (status.supervisorPid) {
     console.log(`  Supervisor: ${status.supervisorAlive ? "running" : "stopped"} (PID: ${status.supervisorPid})`);
   }
+  // Show state info
+  const state = status.state ?? (status.running ? "running" : "stopped");
+  if (state === "paused") {
+    console.log(`  State:   PAUSED — ${status.pauseReason ?? "unknown reason"}`);
+    if (status.pausedAt) console.log(`  Paused:  ${status.pausedAt}`);
+    if (status.lastCrashError) console.log(`  Error:   ${status.lastCrashError}`);
+    console.log(`\n  Resume:  ppm restart --force`);
+  } else if (state === "upgrading") {
+    console.log(`  State:   UPGRADING`);
+  }
   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/index.ts

@@ -16,8 +16,6 @@ program
   .command("start")
   .description("Start the PPM server (background by default)")
   .option("-p, --port <port>", "Port to listen on")
-  .option("-f, --foreground", "Run in foreground (default: background daemon)")
-  .option("-d, --daemon", "Run as background daemon (default, kept for compat)")
   .option("-s, --share", "Share via public URL (Cloudflare tunnel)")
   .option("-c, --config <path>", "Path to config file (YAML import into DB)")
   .option("--profile <name>", "DB profile name (e.g. 'dev' → ppm.dev.db)")
@@ -51,6 +49,7 @@ program
   .command("restart")
   .description("Restart the server (keeps tunnel alive)")
   .option("-c, --config <path>", "Path to config file")
+  .option("--force", "Force resume from paused state")
   .action(async (options) => {
     const { restartServer } = await import("./cli/commands/restart.ts");
     await restartServer(options);

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

@@ -13,7 +13,7 @@ import type {
 } from "./provider.interface.ts";
 import { configService } from "../services/config.service.ts";
 import { updateFromSdkEvent } from "../services/claude-usage.service.ts";
-import { getSessionMapping, setSessionMapping, getSessionTitles } from "../services/db.service.ts";
+import { getSessionMapping, setSessionMapping, getSessionTitles, getSessionTitle } from "../services/db.service.ts";
 import { accountSelector } from "../services/account-selector.service.ts";
 import { accountService } from "../services/account.service.ts";
 import { resolve } from "node:path";
@@ -176,10 +176,11 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         (s) => s.sessionId === sessionId || s.sessionId === mappedSdkId,
       );
       if (found) {
+        const dbTitle = getSessionTitle(found.sessionId);
         const meta: Session = {
           id: sessionId,
           providerId: this.id,
-          title: found.customTitle ?? found.summary ?? "Resumed Chat",
+          title: dbTitle ?? found.customTitle ?? found.summary ?? "Resumed Chat",
           createdAt: new Date(found.lastModified).toISOString(),
         };
         this.activeSessions.set(sessionId, meta);

package/src/server/index.ts

@@ -160,8 +160,6 @@ app.route("/", staticRoutes);
 
 export async function startServer(options: {
   port?: string;
-  foreground?: boolean;
-  daemon?: boolean; // compat, ignored (daemon is now default)
   share?: boolean;
   config?: string;
   profile?: string;
@@ -171,36 +169,27 @@ export async function startServer(options: {
   const port = parseInt(options.port ?? String(configService.get("port")), 10);
   const host = configService.get("host");
 
-  // Setup log file (both foreground and daemon modes)
   await setupLogFile();
 
-  // Check if port is already in use before starting.
-  // Skip in hot-reload mode — Bun.serve() replaces the previous server on the same port,
-  // but a net.createServer() probe would see it as "in use" and exit prematurely.
-  // globalThis persists across bun --hot reloads, so we use a flag set after first start.
-  const isHotReload = !!(globalThis as any).__PPM_SERVER_STARTED__;
-  if (!isHotReload) {
-    const portInUse = await new Promise<boolean>((resolve) => {
-      const net = require("node:net") as typeof import("node:net");
-      const tester = net.createServer()
-        .once("error", (err: NodeJS.ErrnoException) => {
-          resolve(err.code === "EADDRINUSE");
-        })
-        .once("listening", () => {
-          tester.close(() => resolve(false));
-        })
-        .listen(port, host);
-    });
-    if (portInUse) {
-      console.error(`\n  ✗  Port ${port} is already in use.`);
-      console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
-      process.exit(1);
-    }
+  // Check if port is already in use before spawning supervisor
+  const portInUse = await new Promise<boolean>((resolve) => {
+    const net = require("node:net") as typeof import("node:net");
+    const tester = net.createServer()
+      .once("error", (err: NodeJS.ErrnoException) => {
+        resolve(err.code === "EADDRINUSE");
+      })
+      .once("listening", () => {
+        tester.close(() => resolve(false));
+      })
+      .listen(port, host);
+  });
+  if (portInUse) {
+    console.error(`\n  ✗  Port ${port} is already in use.`);
+    console.error(`     Run 'ppm stop' first or use a different port with --port.\n`);
+    process.exit(1);
   }
 
-  const isDaemon = !options.foreground;
-
-  if (isDaemon) {
+  {
     const { resolve } = await import("node:path");
     const { homedir } = await import("node:os");
     const { writeFileSync, readFileSync, mkdirSync, existsSync, openSync } = await import("node:fs");
@@ -266,7 +255,6 @@ export async function startServer(options: {
       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 {
@@ -291,7 +279,6 @@ export async function startServer(options: {
       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
@@ -347,130 +334,6 @@ export async function startServer(options: {
 
     process.exit(0);
   }
-
-  // Foreground mode — with WebSocket support
-  const server = Bun.serve({
-    port,
-    hostname: host,
-    fetch(req, server) {
-      const url = new URL(req.url);
-
-      // WebSocket upgrade: /ws/project/:projectName/terminal/:id
-      if (url.pathname.startsWith("/ws/project/")) {
-        const parts = url.pathname.split("/");
-        const projectName = parts[3] ?? "";
-        const wsType = parts[4] ?? "";
-        const id = parts[5] ?? "";
-
-        if (wsType === "terminal") {
-          const upgraded = server.upgrade(req, {
-            data: { type: "terminal", id, projectName },
-          });
-          if (upgraded) return undefined;
-          return new Response("WebSocket upgrade failed", { status: 400 });
-        }
-
-        if (wsType === "chat") {
-          const sessionId = id;
-          const upgraded = server.upgrade(req, {
-            data: { type: "chat", sessionId, projectName },
-          });
-          if (upgraded) return undefined;
-          return new Response("WebSocket upgrade failed", { status: 400 });
-        }
-      }
-
-      return app.fetch(req, server);
-    },
-    websocket: {
-      idleTimeout: 960,
-      sendPong: true,
-      perMessageDeflate: false, // Disable compression — Cloudflare tunnels can mangle compressed frames
-      open(ws: any) {
-        if (ws.data?.type === "health") {
-          ws.send(JSON.stringify({ type: "health", status: "ok" }));
-        } else if (ws.data?.type === "chat") chatWebSocket.open(ws);
-        else terminalWebSocket.open(ws);
-      },
-      message(ws: any, msg: any) {
-        if (ws.data?.type === "health") {
-          // Respond to ping with pong
-          ws.send(JSON.stringify({ type: "health", status: "ok" }));
-        } else if (ws.data?.type === "chat") chatWebSocket.message(ws, msg);
-        else terminalWebSocket.message(ws, msg);
-      },
-      close(ws: any) {
-        if (ws.data?.type === "health") return;
-        if (ws.data?.type === "chat") chatWebSocket.close(ws);
-        else terminalWebSocket.close(ws);
-      },
-    } as Parameters<typeof Bun.serve>[0] extends { websocket?: infer W } ? W : never,
-  });
-
-  // Mark server as started — survives bun --hot reloads (globalThis persists)
-  (globalThis as any).__PPM_SERVER_STARTED__ = true;
-
-  // Start background usage polling
-  import("../services/claude-usage.service.ts").then(({ startUsagePolling }) => startUsagePolling()).catch(() => {});
-
-  // Start background account token refresh
-  import("../services/account.service.ts").then(({ accountService }) => accountService.startAutoRefresh()).catch(() => {});
-
-  console.log(`\n  PPM ready\n`);
-  console.log(`  ➜  Local:   http://localhost:${server.port}/`);
-
-  const { networkInterfaces } = await import("node:os");
-  const nets = networkInterfaces();
-  for (const name of Object.keys(nets)) {
-    for (const net of nets[name] ?? []) {
-      if (net.family === "IPv4" && !net.internal) {
-        console.log(`  ➜  Network: http://${net.address}:${server.port}/`);
-      }
-    }
-  }
-
-  // Share tunnel in foreground mode
-  if (options.share) {
-    try {
-      const { tunnelService } = await import("../services/tunnel.service.ts");
-      console.log("\n  Starting share tunnel...");
-      const shareUrl = await tunnelService.startTunnel(server.port!);
-      console.log(`  ➜  Share:   ${shareUrl}`);
-      if (!configService.get("auth").enabled) {
-        console.log(`\n  ⚠  Warning: auth is disabled — your IDE is publicly accessible!`);
-        console.log(`     Enable auth: run 'ppm config set auth.enabled true' or restart without --share.`);
-      }
-      const qr = await import("qrcode-terminal");
-      console.log();
-      qr.generate(shareUrl, { small: true });
-    } catch (err: unknown) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.error(`  ✗  Share failed: ${msg}`);
-    }
-  }
-
-  console.log(`\n  Auth: ${configService.get("auth").enabled ? "enabled" : "disabled"}`);
-  if (configService.get("auth").enabled) {
-    console.log(`  Token: ${configService.get("auth").token}`);
-  }
-  console.log();
-
-  // Graceful shutdown — stop server + tunnel + preview tunnels + DB on exit
-  const shutdown = () => {
-    try { server.stop(true); } catch {}
-    try {
-      import("../services/tunnel.service.ts").then(({ tunnelService }) => tunnelService.stopTunnel()).catch(() => {});
-    } catch {}
-    try {
-      import("./routes/browser-preview.ts").then(({ stopAllPreviewTunnels }) => stopAllPreviewTunnels()).catch(() => {});
-    } catch {}
-    try {
-      import("../services/db.service.ts").then(({ closeDb }) => closeDb()).catch(() => {});
-    } catch {}
-  };
-  process.on("SIGINT", () => { shutdown(); process.exit(0); });
-  process.on("SIGTERM", () => { shutdown(); process.exit(0); });
-  process.on("exit", shutdown);
 }
 
 // Internal entry point for daemon child process

package/src/services/cloud-ws.service.ts

@@ -0,0 +1,214 @@
+/**
+ * Cloud WebSocket client — persistent connection from supervisor to PPM Cloud.
+ * Auto-reconnects with exponential backoff + jitter. Queues messages when disconnected.
+ */
+import { appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+// ─── Types (must match Cloud's ws-types.ts) ─────────
+interface WsMessage {
+  type: string;
+  id?: string;
+  timestamp: string;
+}
+
+interface HeartbeatMsg extends WsMessage {
+  type: "heartbeat";
+  tunnelUrl: string | null;
+  state: string;
+  appVersion: string;
+  serverPid: number | null;
+  uptime: number;
+}
+
+interface StateChangeMsg extends WsMessage {
+  type: "state_change";
+  from: string;
+  to: string;
+  reason: string;
+}
+
+interface CommandResultMsg extends WsMessage {
+  type: "command_result";
+  id: string;
+  success: boolean;
+  error?: string;
+  data?: Record<string, unknown>;
+}
+
+type OutboundMsg = HeartbeatMsg | StateChangeMsg | CommandResultMsg;
+
+interface CommandMsg extends WsMessage {
+  type: "command";
+  id: string;
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+type CommandHandler = (cmd: CommandMsg) => void;
+
+// ─── Constants ──────────────────────────────────────
+const BACKOFF_STEPS = [1000, 2000, 4000, 8000, 15000, 30000, 60000];
+const MAX_QUEUE_SIZE = 50;
+const HEARTBEAT_INTERVAL_MS = 60_000; // 60s via WS
+
+// ─── State ──────────────────────────────────────────
+let ws: WebSocket | null = null;
+let connected = false;
+let reconnecting = false;
+let reconnectAttempt = 0;
+let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+let commandHandler: CommandHandler | null = null;
+let outboundQueue: OutboundMsg[] = [];
+let wsUrl = "";
+let shouldConnect = false;
+
+// Credentials for first-message auth
+let deviceId = "";
+let secretKey = "";
+
+// For heartbeat payload
+let getHeartbeatData: (() => HeartbeatMsg) | null = null;
+
+// ─── Public API ─────────────────────────────────────
+
+export function connect(opts: {
+  cloudUrl: string;
+  deviceId: string;
+  secretKey: string;
+  heartbeatFn: () => HeartbeatMsg;
+}): void {
+  // No secret_key in URL — auth via first message after connect
+  wsUrl = `${opts.cloudUrl.replace(/^http/, "ws")}/ws/device`;
+  deviceId = opts.deviceId;
+  secretKey = opts.secretKey;
+  getHeartbeatData = opts.heartbeatFn;
+  shouldConnect = true;
+  reconnectAttempt = 0;
+  doConnect();
+}
+
+export function disconnect(): void {
+  shouldConnect = false;
+  if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+  if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+  if (ws) {
+    try { ws.close(1000, "shutdown"); } catch {}
+    ws = null;
+  }
+  connected = false;
+  outboundQueue = [];
+}
+
+export function send(msg: OutboundMsg): void {
+  if (connected && ws?.readyState === WebSocket.OPEN) {
+    ws.send(JSON.stringify(msg));
+  } else {
+    outboundQueue.push(msg);
+    if (outboundQueue.length > MAX_QUEUE_SIZE) outboundQueue.shift();
+  }
+}
+
+export function onCommand(handler: CommandHandler): void {
+  commandHandler = handler;
+}
+
+export function isConnected(): boolean {
+  return connected;
+}
+
+// ─── Internal ───────────────────────────────────────
+
+function doConnect(): void {
+  if (!shouldConnect || reconnecting) return;
+  reconnecting = true;
+
+  // Capture local ref — if a reconnect replaces `ws` before this socket's
+  // handlers fire, stale handlers must not reset module-level state.
+  let sock: WebSocket;
+  try {
+    sock = new WebSocket(wsUrl);
+    ws = sock;
+  } catch {
+    reconnecting = false;
+    scheduleReconnect("constructor");
+    return;
+  }
+
+  sock.onopen = () => {
+    if (ws !== sock) return; // stale — newer connection replaced us
+    reconnecting = false;
+    log("INFO", "Cloud WS connected, sending auth");
+
+    sock.send(JSON.stringify({
+      type: "auth",
+      deviceId,
+      secretKey,
+      timestamp: new Date().toISOString(),
+      version: 1,
+    }));
+
+    connected = true;
+    reconnectAttempt = 0;
+
+    // Flush queued messages
+    while (outboundQueue.length > 0 && connected) {
+      const msg = outboundQueue.shift()!;
+      sock.send(JSON.stringify(msg));
+    }
+
+    // Send immediate heartbeat
+    if (getHeartbeatData) send(getHeartbeatData());
+
+    // Start periodic heartbeat
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    heartbeatTimer = setInterval(() => {
+      if (getHeartbeatData && connected) send(getHeartbeatData());
+    }, HEARTBEAT_INTERVAL_MS);
+  };
+
+  sock.onmessage = (event) => {
+    try {
+      const msg = JSON.parse(String(event.data)) as CommandMsg;
+      if (msg.type === "command" && commandHandler) {
+        commandHandler(msg);
+      }
+    } catch {} // ignore malformed
+  };
+
+  sock.onclose = (event) => {
+    if (ws !== sock) return; // stale — ignore close from replaced connection
+    log("WARN", `Cloud WS closed: code=${event.code} reason=${event.reason || ""}`);
+    connected = false;
+    reconnecting = false;
+    ws = null;
+    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+    if (shouldConnect) scheduleReconnect("onclose");
+  };
+
+  sock.onerror = (event) => {
+    log("ERROR", `Cloud WS error: ${String(event)}`);
+  };
+}
+
+function scheduleReconnect(source = "unknown"): void {
+  if (!shouldConnect || reconnectTimer) return;
+  const base = BACKOFF_STEPS[Math.min(reconnectAttempt, BACKOFF_STEPS.length - 1)]!;
+  // Add ±30% jitter to prevent thundering herd after Cloud deploy
+  const jitter = base * (0.7 + Math.random() * 0.6);
+  const delay = Math.round(jitter);
+  reconnectAttempt++;
+  log("WARN", `Cloud WS reconnect in ${delay}ms (attempt #${reconnectAttempt}) src=${source}`);
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    doConnect();
+  }, delay);
+}
+
+function log(level: string, msg: string): void {
+  const ts = new Date().toISOString();
+  const logFile = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"), "ppm.log");
+  try { appendFileSync(logFile, `[${ts}] [${level}] [cloud-ws] ${msg}\n`); } catch {}
+}

package/src/services/supervisor.ts

@@ -37,6 +37,24 @@ let tunnelChild: Subprocess | null = null;
 let tunnelUrl: string | null = null;
 let shuttingDown = false;
 
+type SupervisorState = "running" | "paused" | "upgrading";
+let supervisorState: SupervisorState = "running";
+
+let resumeResolve: (() => void) | null = null;
+
+function waitForResume(): Promise<void> {
+  return new Promise((resolve) => {
+    resumeResolve = resolve;
+  });
+}
+
+function triggerResume(): void {
+  if (resumeResolve) {
+    resumeResolve();
+    resumeResolve = null;
+  }
+}
+
 let serverRestarts = 0;
 let lastServerCrash = 0;
 let tunnelRestarts = 0;
@@ -129,8 +147,25 @@ export async function spawnServer(
   serverRestarts++;
 
   if (serverRestarts > MAX_RESTARTS) {
-    log("FATAL", `Server exceeded ${MAX_RESTARTS} restarts, giving up`);
-    shutdown();
+    log("WARN", `Server exceeded ${MAX_RESTARTS} restarts, pausing`);
+    notifyStateChange("running", "paused", "max_restarts_exceeded");
+    supervisorState = "paused";
+    updateStatus({
+      state: "paused",
+      pid: null,
+      pausedAt: new Date().toISOString(),
+      pauseReason: "max_restarts",
+      lastCrashError: `exit ${exitCode}`,
+    });
+    // Wait for resume signal — supervisor stays alive
+    await waitForResume();
+    // Resumed — reset and respawn
+    notifyStateChange("paused", "running", "user_resume");
+    supervisorState = "running";
+    serverRestarts = 0;
+    updateStatus({ state: "running", pausedAt: null, pauseReason: null });
+    log("INFO", "Resuming server after pause");
+    if (!shuttingDown) return spawnServer(serverArgs, logFd);
     return;
   }
 
@@ -189,12 +224,7 @@ async function syncUrlToCloud(url: string) {
   } catch {}
 }
 
-function startCloudHeartbeat(url: string) {
-  if (heartbeatTimer) clearInterval(heartbeatTimer);
-  heartbeatTimer = setInterval(() => {
-    if (tunnelUrl) syncUrlToCloud(tunnelUrl);
-  }, 5 * 60 * 1000);
-}
+// HTTP heartbeat removed — WS is the sole heartbeat mechanism (Phase 4)
 
 export async function spawnTunnel(port: number): Promise<void> {
   let bin: string;
@@ -230,9 +260,8 @@ export async function spawnTunnel(port: number): Promise<void> {
   updateStatus({ shareUrl: tunnelUrl, tunnelPid: tunnelChild.pid });
   log("INFO", `Tunnel ready: ${tunnelUrl} (PID: ${tunnelChild.pid})`);
 
-  // Sync new URL to cloud immediately + start periodic heartbeat
+  // One-time sync of tunnel URL to cloud (WS handles periodic heartbeat)
   await syncUrlToCloud(tunnelUrl);
-  startCloudHeartbeat(tunnelUrl);
 
   const exitCode = await tunnelChild.exited;
   tunnelChild = null;
@@ -330,6 +359,9 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
   try {
     // Prevent spawnServer crash-restart loop from respawning killed children
     shuttingDown = true;
+    notifyStateChange(supervisorState, "upgrading", "self_replace");
+    supervisorState = "upgrading";
+    updateStatus({ state: "upgrading" });
 
     // Kill server + tunnel children FIRST to free the port for the new supervisor
     log("INFO", "Stopping server and tunnel before spawning new supervisor");
@@ -372,20 +404,158 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     log("ERROR", "Self-replace timeout: new supervisor did not start");
     try { child.kill(); } catch {}
     shuttingDown = false;
+    notifyStateChange("upgrading", "running", "upgrade_failed");
+    supervisorState = "running";
+    updateStatus({ state: "running" });
     return { success: false, error: "New supervisor failed to start within 30s" };
   } catch (e) {
     log("ERROR", `Self-replace error: ${e}`);
     shuttingDown = false;
+    notifyStateChange("upgrading", "running", "upgrade_failed");
+    supervisorState = "running";
+    updateStatus({ state: "running" });
     return { success: false, error: (e as Error).message };
   }
 }
 
+// ─── Cloud WS integration ─────────────────────────────────────────────
+
+/** Notify Cloud of supervisor state change via WS */
+async function notifyStateChange(from: string, to: string, reason: string) {
+  try {
+    const { send, isConnected } = await import("./cloud-ws.service.ts");
+    if (isConnected()) {
+      send({
+        type: "state_change",
+        from,
+        to,
+        reason,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  } catch {}
+}
+
+/** Connect supervisor to Cloud via WebSocket (if device is linked) */
+async function connectCloud(opts: { port: number }, serverArgs: string[], logFd: number) {
+  try {
+    const { getCloudDevice } = await import("./cloud.service.ts");
+    const device = getCloudDevice();
+    if (!device) return; // not linked to cloud
+
+    const { connect, onCommand } = await import("./cloud-ws.service.ts");
+    const { VERSION } = await import("../version.ts");
+    const startTime = Date.now();
+
+    connect({
+      cloudUrl: device.cloud_url,
+      deviceId: device.device_id,
+      secretKey: device.secret_key,
+      heartbeatFn: () => ({
+        type: "heartbeat" as const,
+        tunnelUrl,
+        state: supervisorState,
+        appVersion: VERSION,
+        serverPid: serverChild?.pid ?? null,
+        uptime: Math.floor((Date.now() - startTime) / 1000),
+        timestamp: new Date().toISOString(),
+      }),
+    });
+
+    // Handle commands from Cloud
+    onCommand(async (cmd) => {
+      const { send } = await import("./cloud-ws.service.ts");
+      const sendResult = (success: boolean, error?: string, data?: Record<string, unknown>) => {
+        send({
+          type: "command_result",
+          id: cmd.id,
+          success,
+          error,
+          data,
+          timestamp: new Date().toISOString(),
+        });
+      };
+
+      log("INFO", `Cloud command received: ${cmd.action}`);
+
+      switch (cmd.action) {
+        case "restart":
+          if (serverChild) {
+            serverRestartRequested = true;
+            try { serverChild.kill(); } catch {}
+            sendResult(true);
+          } else if (supervisorState === "paused") {
+            triggerResume();
+            sendResult(true);
+          } else {
+            sendResult(false, "No server child to restart");
+          }
+          break;
+
+        case "resume":
+          if (supervisorState === "paused") {
+            triggerResume();
+            sendResult(true);
+          } else {
+            sendResult(false, "Not in paused state");
+          }
+          break;
+
+        case "stop":
+          sendResult(true);
+          // Delay exit to allow WS buffer to flush
+          setTimeout(() => {
+            shutdown();
+            process.exit(0);
+          }, 500);
+          break;
+
+        case "upgrade":
+          // Send result BEFORE selfReplace (which exits on success)
+          sendResult(true, undefined, { status: "upgrading" });
+          await new Promise(r => setTimeout(r, 300));
+          const result = await selfReplace();
+          // Only reaches here on failure — selfReplace exits on success
+          if (!result.success) {
+            sendResult(false, result.error);
+            if (!serverChild && !shuttingDown) {
+              spawnServer(serverArgs, logFd);
+            }
+          }
+          break;
+
+        case "status":
+          sendResult(true, undefined, {
+            state: supervisorState,
+            serverPid: serverChild?.pid ?? null,
+            tunnelUrl,
+            serverRestarts,
+          });
+          break;
+
+        default:
+          sendResult(false, `Unknown action: ${cmd.action}`);
+      }
+    });
+  } catch (e) {
+    log("WARN", `Cloud WS setup failed: ${e}`);
+  }
+}
+
 // ─── Shutdown ──────────────────────────────────────────────────────────
 export function shutdown() {
   if (shuttingDown) return;
   shuttingDown = true;
   log("INFO", "Supervisor shutting down");
 
+  // Unblock if paused
+  triggerResume();
+
+  // Disconnect Cloud WS
+  import("./cloud-ws.service.ts")
+    .then(({ disconnect }) => disconnect())
+    .catch(() => {});
+
   if (healthTimer) clearInterval(healthTimer);
   if (tunnelProbeTimer) clearInterval(tunnelProbeTimer);
   if (heartbeatTimer) clearInterval(heartbeatTimer);
@@ -414,7 +584,10 @@ export async function runSupervisor(opts: {
 
   // Write supervisor PID + clear stale availableVersion from previous run
   writeFileSync(PID_FILE, String(process.pid));
-  updateStatus({ supervisorPid: process.pid, port: opts.port, host: opts.host, availableVersion: null });
+  updateStatus({
+    supervisorPid: process.pid, port: opts.port, host: opts.host, availableVersion: null,
+    state: "running", pausedAt: null, pauseReason: null, lastCrashError: null,
+  });
 
   // Build __serve__ args
   const serverArgs = [
@@ -428,8 +601,13 @@ export async function runSupervisor(opts: {
   process.on("SIGTERM", () => { shutdown(); process.exit(0); });
   process.on("SIGINT", () => { shutdown(); process.exit(0); });
 
-  // SIGUSR2 = graceful server restart (tunnel stays alive)
+  // SIGUSR2 = graceful server restart (tunnel stays alive) or resume from paused
   process.on("SIGUSR2", () => {
+    if (supervisorState === "paused") {
+      log("INFO", "SIGUSR2 received while paused, resuming server");
+      triggerResume();
+      return;
+    }
     log("INFO", "SIGUSR2 received, restarting server only");
     if (serverChild) {
       serverRestartRequested = true; // flag so spawnServer skips backoff
@@ -458,6 +636,9 @@ export async function runSupervisor(opts: {
     upgradeCheckTimer = setInterval(checkAvailableVersion, UPGRADE_CHECK_INTERVAL_MS);
   }, UPGRADE_SKIP_INITIAL_MS);
 
+  // Connect to Cloud via WebSocket (if device is linked)
+  connectCloud(opts, serverArgs, logFd);
+
   // Spawn server + tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];