@hienlh/ppm 0.9.52 → 0.9.53

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.9.53] - 2026-04-07
+
+### Added
+- **Supervisor Always Alive**: `ppm stop` now does a soft stop — kills server only, supervisor stays alive with Cloud WS + tunnel. Use `ppm stop --kill` or `ppm down` for full shutdown.
+- **`ppm down` command**: Alias for `ppm stop --kill` (full shutdown).
+- **`ppm stop --kill` flag**: Full shutdown that kills supervisor + server + tunnel.
+- **Stopped page**: When server is stopped, tunnel URL serves a minimal HTML status page + 503 on `/api/health`.
+- **Supervisor detection**: `ppm start` detects existing supervisor and resumes/upgrades instead of spawning a new one.
+- **Cloud WS commands**: `start` (resume from stopped), `shutdown` (full kill), `stop` (now soft stop).
+- **Exception handlers**: Supervisor catches `uncaughtException`/`unhandledRejection` — never crashes.
+- **Lockfile**: Prevents concurrent `ppm start` races (`~/.ppm/.start-lock`).
+- **Windows command file polling**: Supervisor polls command file every 1s on Windows (no SIGUSR2).
+
+### Changed
+- **BREAKING**: `ppm stop` default behavior changed from full shutdown to soft stop.
+- **Autostart**: Generates `__supervise__` instead of `__serve__`. Existing users must run `ppm autostart disable && ppm autostart enable` to regenerate.
+- **Supervisor modularized**: Split into `supervisor.ts` (orchestrator), `supervisor-state.ts` (state machine + IPC), `supervisor-stopped-page.ts` (stopped HTML server).
+
 ## [0.9.52] - 2026-04-07
 
 ### Added

package/docs/project-changelog.md

@@ -2,7 +2,37 @@
 
 All notable changes to PPM are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
 
-**Current Version:** v0.9.9
+**Current Version:** v0.9.10
+
+---
+
+## [0.9.11] — 2026-04-07
+
+### Added
+- **Supervisor Always Alive Feature** — Distinguish between soft stop (server shutdown) and full shutdown (supervisor shutdown)
+  - `ppm stop` now performs SOFT STOP: kills server only, supervisor remains alive with Cloud WS + tunnel connectivity
+  - `ppm stop --kill` or `ppm down` performs FULL SHUTDOWN: kills everything (old `ppm stop` behavior)
+  - Supervisor now has new `stopped` state (in addition to running, paused, upgrading)
+  - When stopped, minimal HTML page served on the port (503 status on /api/health)
+  - `ppm start` detects existing supervisor and handles resume/upgrade scenarios
+  - Autostart now uses `__supervise__` instead of `__serve__` for consistency
+  - Cloud WS has new commands: `start`, `shutdown` (stop is now soft stop, separate from shutdown)
+  - Supervisor has uncaughtException/unhandledRejection handlers (never crashes)
+  - Supervisor logic modularized into 3 files: supervisor.ts (orchestrator), supervisor-state.ts (state machine), supervisor-stopped-page.ts (503 page)
+
+### Technical Details
+- **Files Created:**
+  - `src/services/supervisor-state.ts` — State machine, IPC command file handling
+  - `src/services/supervisor-stopped-page.ts` — Minimal 503 HTML response
+  - Enhanced `src/services/supervisor.ts` — Orchestrator with stopped state support
+- **Files Modified:**
+  - `src/cli/commands/stop.ts` — Added --kill flag, soft stop default, ppm down alias
+  - `src/cli/commands/start.ts` — Resume detection for existing supervisor
+  - `src/cli/autostart-generator.ts` — Uses __supervise__ entry point
+  - Cloud WS endpoints updated with new commands
+- **Type Changes:** SupervisorState = "running" | "paused" | "stopped" | "upgrading"
+- **API Changes:** GET /api/health returns 503 when server stopped (supervisor still running)
+- **Breaking Changes:** None (backward compatible, graceful fallback)
 
 ---
 

package/docs/project-roadmap.md

@@ -38,12 +38,13 @@ PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-d
 
 **Theme:** Multi-device access + AI chat improvements. Solve the "I can't reach my PPM from my phone" problem.
 
-| Feature | Priority | Description |
-|---------|----------|-------------|
-| **PPM Cloud** | Critical | Separate cloud service for device registry + tunnel URL sync. Google OAuth login. CLI `ppm cloud link` syncs tunnel URL. Open cloud dashboard on any device → see machines → tap to connect. NO code/data through cloud — only URLs + metadata. |
-| **Auto-start** | High | PPM starts on boot. macOS launchd, Linux systemd, Windows Task Scheduler. CLI: `ppm autostart enable/disable`. Required for "always accessible" story. |
-| **Auto-upgrade** | High | Supervisor checks npm registry every 15min. UI banner shows when update available. One-click upgrade via API or CLI. Supervisor self-replaces after install (no OS autostart dependency). ✅ **Completed in v0.8.54** |
-| **AI Chat enhancements** | High | Tool allow/deny config per session. Chat modes (plan/code/ask). Model selector (opus/sonnet/haiku). Effort level. Max turns. System prompt customization. Better streaming UX (collapsible tool calls). |
+| Feature | Priority | Status | Description |
+|---------|----------|--------|-------------|
+| **PPM Cloud** | Critical | — | Separate cloud service for device registry + tunnel URL sync. Google OAuth login. CLI `ppm cloud link` syncs tunnel URL. Open cloud dashboard on any device → see machines → tap to connect. NO code/data through cloud — only URLs + metadata. |
+| **Auto-start** | High | — | PPM starts on boot. macOS launchd, Linux systemd, Windows Task Scheduler. CLI: `ppm autostart enable/disable`. Required for "always accessible" story. |
+| **Auto-upgrade** | High | ✅ Done | Supervisor checks npm registry every 15min. UI banner shows when update available. One-click upgrade via API or CLI. Supervisor self-replaces after install (no OS autostart dependency). **Completed in v0.8.54** |
+| **Supervisor Always Alive** | High | ✅ Done | Soft stop (server shutdown, supervisor stays) vs full shutdown. New `stopped` state. Cloud WS + tunnel stay active when stopped. `ppm start` resumes without supervisor restart. Modularized: supervisor.ts, supervisor-state.ts, supervisor-stopped-page.ts. **Completed in v0.9.11** |
+| **AI Chat enhancements** | High | — | Tool allow/deny config per session. Chat modes (plan/code/ask). Model selector (opus/sonnet/haiku). Effort level. Max turns. System prompt customization. Better streaming UX (collapsible tool calls). |
 
 **PPM Cloud — scope guard:**
 - Cloud is OPTIONAL convenience, never a dependency. PPM works 100% without it.

package/docs/system-architecture.md

@@ -1628,13 +1628,81 @@ $ ppm upgrade
   → Works in headless environments (no OS autostart dependency)
 
 $ ppm stop
-  → Reads ~/.ppm/status.json first (new format)
-  → Falls back to ppm.pid (compat)
-  → Sends SIGTERM to daemon
+  → SOFT STOP: kills server only, supervisor stays alive with Cloud WS + tunnel
+  → Supervisor transitions to "stopped" state
+  → Minimal HTML page served on port (503 status on /api/health)
+  → Tunnel and Cloud connectivity remain active
+  → `ppm start` resumes without restarting supervisor process
+
+$ ppm stop --kill OR ppm down
+  → FULL SHUTDOWN: kills everything (supervisor + server + tunnel)
+  → Supervisor transitions to "upgrading" then terminates
   → Cleans up status.json and ppm.pid
-  → Graceful shutdown (close WS, cleanup PTY, stop tunnel)
+  → Graceful cleanup (close WS, cleanup PTY, stop tunnel)
 ```
 
+### Supervisor Architecture (v0.9.11+)
+
+The supervisor is a long-lived parent process that manages server + tunnel children with resilience and state management.
+
+**Architecture:**
+```
+Supervisor Process (parent)
+  ├── Server Child (Hono HTTP server)
+  │   ├── Health checks every 30s (/api/health)
+  │   ├── Auto-restart on crash (exponential backoff, max 10 restarts)
+  │   └── If in "stopped" state, serves minimal 503 page instead of restarting
+  │
+  ├── Tunnel Child (Cloudflare Quick Tunnel, if --share)
+  │   ├── URL probe every 2min
+  │   ├── Auto-reconnect on failure
+  │   └── URL persisted to status.json
+  │
+  ├── State Machine: "running" | "paused" | "stopped" | "upgrading"
+  │   ├── running — Server spawned, tunnel optional, serving requests
+  │   ├── paused — Supervisor paused (resume via signal)
+  │   ├── stopped — Server stopped (soft stop), tunnel alive, Cloud WS active
+  │   └── upgrading — Self-replace in progress
+  │
+  ├── Upgrade Check (every 15min)
+  │   └── npm registry poll → availableVersion written to status.json
+  │
+  ├── Stopped Page Server
+  │   ├── Lightweight HTTP handler on same port as server
+  │   ├── Returns 503 on /api/health
+  │   └── Tunnels Cloud WS calls through to PPM Cloud
+  │
+  └── Error Resilience
+      ├── uncaughtException → log + exit gracefully
+      ├── unhandledRejection → log + continue
+      └── Signal handlers: SIGTERM (full shutdown), SIGUSR1 (self-replace), SIGUSR2 (restart skip backoff)
+```
+
+**Soft Stop vs Full Shutdown:**
+| Command | Server | Supervisor | Tunnel | Use Case |
+|---------|--------|------------|--------|----------|
+| `ppm stop` | Killed | Stays alive | Stays alive | Restart later with `ppm start` |
+| `ppm stop --kill` | Killed | Killed | Killed | Full cleanup, exit |
+| `ppm down` | Killed | Killed | Killed | Full cleanup, exit |
+
+**State Persistence:**
+- Status file: `~/.ppm/status.json` — PID, port, host, shareUrl, supervisorPid, availableVersion, state
+- Lock file: `~/.ppm/.start-lock` — Prevent concurrent starts
+- Command file: `~/.ppm/.supervisor-cmd` — IPC for soft_stop, resume, self_replace
+
+**Stopped Page Implementation:**
+- Minimal HTTP server on same port as main server
+- Serves `503 Service Unavailable` on /api/health
+- Proxies Cloud WS calls to PPM Cloud (if tunnel configured)
+- Allows `ppm start` to resume without supervisor restart
+
+**Files (Modular Design):**
+- `src/services/supervisor.ts` — Main orchestrator (spawn, health checks, upgrade checks)
+- `src/services/supervisor-state.ts` — State machine, IPC command handling, signal routing
+- `src/services/supervisor-stopped-page.ts` — Minimal 503 page + Cloud WS proxy
+
+---
+
 ### Future: Multi-Machine (Not in v2)
 Would require:
 - Central state server (Redis/Postgres)

package/package.json

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

package/src/cli/commands/restart.ts

@@ -42,6 +42,35 @@ export async function restartServer(options: { config?: string; force?: boolean
       process.exit(1);
     }
 
+    // Stopped state: treat restart as resume (send resume command)
+    if (state === "stopped") {
+      console.log("\n  Server is stopped. Resuming via supervisor...\n");
+      const cmdFile = resolve(PPM_DIR, ".supervisor-cmd");
+      writeFileSync(cmdFile, JSON.stringify({ action: "resume" }));
+      // Signal supervisor (Windows: polling picks up command file)
+      if (process.platform !== "win32") {
+        try { process.kill(supervisorPid, "SIGUSR2"); } catch (e) {
+          console.error(`  ✗  Failed to signal supervisor: ${e}`);
+          process.exit(1);
+        }
+      }
+      // Wait for state to change back to running
+      const rStart = Date.now();
+      while (Date.now() - rStart < 15_000) {
+        await Bun.sleep(500);
+        try {
+          const newStatus = JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+          if (newStatus.state === "running" && newStatus.pid) {
+            console.log(`  ✓  Server resumed (PID: ${newStatus.pid})`);
+            if (newStatus.shareUrl) console.log(`  ➜  Share:   ${newStatus.shareUrl}`);
+            process.exit(0);
+          }
+        } catch {}
+      }
+      console.error("  ⚠  Resume timed out. Check: ppm logs");
+      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/stop.ts

@@ -1,10 +1,11 @@
 import { resolve } from "node:path";
 import { homedir } from "node:os";
-import { readFileSync, unlinkSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
 
 const PPM_DIR = process.env.PPM_HOME || resolve(homedir(), ".ppm");
 const PID_FILE = resolve(PPM_DIR, "ppm.pid");
 const STATUS_FILE = resolve(PPM_DIR, "status.json");
+const CMD_FILE = resolve(PPM_DIR, ".supervisor-cmd");
 
 function killPid(pid: number, label: string): boolean {
   try {
@@ -51,7 +52,7 @@ function killAllByName(name: string): number {
   return killed;
 }
 
-export async function stopServer(options?: { all?: boolean }) {
+export async function stopServer(options?: { all?: boolean; kill?: boolean }) {
   if (options?.all) {
     console.log("  Stopping all PPM and cloudflared processes...\n");
     const cfKilled = killAllByName("cloudflared");
@@ -76,14 +77,76 @@ export async function stopServer(options?: { all?: boolean }) {
     return;
   }
 
+  // Full shutdown: --kill flag or `ppm down`
+  if (options?.kill) {
+    return hardStop();
+  }
+
+  // Default: soft stop — kill server only, supervisor stays alive
+  return softStopCmd();
+}
+
+/** Soft stop: write command file + signal supervisor → kills server only */
+async function softStopCmd() {
+  let status: Record<string, unknown> | null = null;
+  if (existsSync(STATUS_FILE)) {
+    try { status = JSON.parse(readFileSync(STATUS_FILE, "utf-8")); } catch {}
+  }
+
+  const supervisorPid = (status?.supervisorPid as number) ?? null;
+
+  if (!supervisorPid) {
+    // No supervisor — fall back to hard stop (legacy)
+    return hardStop();
+  }
+
+  // Check if supervisor is alive
+  try { process.kill(supervisorPid, 0); } catch {
+    console.log("Supervisor not running. Cleaning up.");
+    cleanup();
+    return;
+  }
+
+  // Already stopped?
+  if ((status?.state as string) === "stopped") {
+    console.log("PPM server is already stopped. Supervisor still alive.");
+    console.log("Use 'ppm stop --kill' or 'ppm down' to fully shut down.");
+    return;
+  }
+
+  // Write soft stop command file + signal supervisor (Windows: polling picks it up)
+  writeFileSync(CMD_FILE, JSON.stringify({ action: "soft_stop" }));
+  if (process.platform !== "win32") {
+    try { process.kill(supervisorPid, "SIGUSR2"); } catch (e) {
+      console.error(`  Failed to signal supervisor: ${e}`);
+      return;
+    }
+  }
+
+  // Wait for state to change to "stopped" in status.json
+  const start = Date.now();
+  while (Date.now() - start < 5000) {
+    await Bun.sleep(500);
+    try {
+      const data = JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+      if (data.state === "stopped") {
+        console.log("PPM server stopped. Supervisor still alive (Cloud WS + tunnel).");
+        console.log("Use 'ppm start' to restart or 'ppm stop --kill' to fully shut down.");
+        return;
+      }
+    } catch {}
+  }
+  console.log("PPM server stop requested.");
+}
+
+/** Hard stop: SIGTERM supervisor → everything dies (current behavior) */
+async function hardStop() {
   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 (now stores supervisor PID)
   const pidFromFile = existsSync(PID_FILE)
     ? parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10)
     : NaN;
@@ -102,10 +165,8 @@ export async function stopServer(options?: { all?: boolean }) {
   // 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);
   }

package/src/index.ts

@@ -39,13 +39,22 @@ program
 
 program
   .command("stop")
-  .description("Stop the PPM daemon")
+  .description("Stop the PPM server (supervisor stays alive)")
   .option("-a, --all", "Kill all PPM and cloudflared processes (including untracked)")
+  .option("--kill", "Full shutdown (kills supervisor too)")
   .action(async (options) => {
     const { stopServer } = await import("./cli/commands/stop.ts");
     await stopServer(options);
   });
 
+program
+  .command("down")
+  .description("Fully shut down PPM (supervisor + server + tunnel)")
+  .action(async () => {
+    const { stopServer } = await import("./cli/commands/stop.ts");
+    await stopServer({ kill: true });
+  });
+
 program
   .command("restart")
   .description("Restart the server (keeps tunnel alive)")

package/src/server/index.ts

@@ -169,6 +169,49 @@ app.route("/api/cloud", cloudRoutes);
 // Static files / SPA fallback (non-API routes)
 app.route("/", staticRoutes);
 
+// ─── Helpers for supervisor detection ───────────────────────────────────
+async function waitForNewSupervisor(statusFile: string, oldPid: number) {
+  const { readFileSync } = await import("node:fs");
+  const start = Date.now();
+  while (Date.now() - start < 30_000) {
+    await Bun.sleep(1000);
+    try {
+      const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+      if (data.supervisorPid && data.supervisorPid !== oldPid && data.state === "running") {
+        console.log(`  Upgrade complete (new PID: ${data.supervisorPid})`);
+        process.exit(0);
+      }
+    } catch {}
+  }
+  console.error("  Upgrade timed out (30s). Check: ppm logs");
+  process.exit(1);
+}
+
+async function waitForServerReady(statusFile: string, port: number) {
+  const { readFileSync } = await import("node:fs");
+  const start = Date.now();
+  while (Date.now() - start < 10_000) {
+    await Bun.sleep(500);
+    try {
+      const data = JSON.parse(readFileSync(statusFile, "utf-8"));
+      if (data.state === "running" && data.pid) {
+        // Verify server is responding
+        try {
+          const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(2000),
+          });
+          if (res.ok) {
+            console.log(`  Server is ready (PID: ${data.pid}).`);
+            process.exit(0);
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  console.log("  Resume signal sent. Check: ppm status");
+  process.exit(0);
+}
+
 export async function startServer(options: {
   port?: string;
   share?: boolean;
@@ -189,36 +232,105 @@ export async function startServer(options: {
   const { bootstrapProviders } = await import("../providers/registry.ts");
   await bootstrapProviders();
 
-  // 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 { resolve } = await import("node:path");
     const { homedir } = await import("node:os");
     const { writeFileSync, readFileSync, mkdirSync, existsSync, openSync } = await import("node:fs");
     const { isCompiledBinary } = await import("../services/autostart-generator.ts");
+    const { writeCmd, acquireLock, releaseLock } = await import("../services/supervisor-state.ts");
 
     const ppmDir = process.env.PPM_HOME || resolve(homedir(), ".ppm");
     if (!existsSync(ppmDir)) mkdirSync(ppmDir, { recursive: true });
     const pidFile = resolve(ppmDir, "ppm.pid");
     const statusFile = resolve(ppmDir, "status.json");
 
-    // Kill any leftover processes from previous run
+    // Prevent concurrent ppm start races
+    if (!acquireLock()) {
+      console.log("\n  Another 'ppm start' is already in progress. Exiting.\n");
+      process.exit(1);
+    }
+    // Release lock on exit (normal or error)
+    process.on("exit", releaseLock);
+
+    // ── Check for existing supervisor ──────────────────────────────────
+    if (existsSync(statusFile)) {
+      try {
+        const status = JSON.parse(readFileSync(statusFile, "utf-8"));
+        const supervisorPid = status.supervisorPid as number;
+
+        if (supervisorPid) {
+          try {
+            process.kill(supervisorPid, 0); // throws if dead
+
+            // Supervisor is alive — handle based on state
+            const state = status.state as string;
+            const runningVersion = status.serverVersion as string;
+
+            if (state === "stopped") {
+              console.log("  Supervisor is alive (stopped state). Resuming server...");
+              if (runningVersion !== VERSION) {
+                console.log(`  Upgrading: ${runningVersion} -> ${VERSION}`);
+                process.kill(supervisorPid, "SIGUSR1");
+                await waitForNewSupervisor(statusFile, supervisorPid);
+              } else {
+                writeCmd("resume");
+                process.kill(supervisorPid, "SIGUSR2");
+                await waitForServerReady(statusFile, port);
+              }
+              return;
+            }
+
+            if (state === "running") {
+              if (runningVersion !== VERSION) {
+                console.log(`  Supervisor running (v${runningVersion}). Upgrading to v${VERSION}...`);
+                process.kill(supervisorPid, "SIGUSR1");
+                await waitForNewSupervisor(statusFile, supervisorPid);
+              } else {
+                console.log(`\n  PPM is already running (PID: ${supervisorPid}).`);
+                console.log(`  Use 'ppm restart' to reload or 'ppm stop' first.\n`);
+                process.exit(0);
+              }
+              return;
+            }
+
+            if (state === "paused") {
+              console.log("  Supervisor is paused (max restarts). Sending resume...");
+              writeCmd("resume");
+              process.kill(supervisorPid, "SIGUSR2");
+              await waitForServerReady(statusFile, port);
+              return;
+            }
+
+            if (state === "upgrading") {
+              console.log("  Supervisor is currently upgrading. Please wait...");
+              process.exit(0);
+            }
+          } catch {
+            // Supervisor PID is dead, continue with fresh start
+          }
+        }
+      } catch {}
+    }
+
+    // ── Check port availability ────────────────────────────────────────
+    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);
+    }
+
+    // Kill any leftover processes from previous run (stale status.json)
     if (existsSync(statusFile)) {
       try {
         const prev = JSON.parse(readFileSync(statusFile, "utf-8"));

package/src/services/autostart-generator.ts

@@ -39,24 +39,26 @@ export function resolveBunPath(): string {
   throw new Error("Could not resolve bun binary. Install Bun or add it to PATH.");
 }
 
-/** Build the command array for the PPM server process */
+/** Build the command array for the PPM supervisor process */
 export function buildExecCommand(config: AutoStartConfig): string[] {
   if (isCompiledBinary()) {
-    // Compiled binary: just run self with __serve__ args
-    const args = [process.execPath, "__serve__", String(config.port), config.host];
+    // Compiled binary: just run self with __supervise__ args
+    const args = [process.execPath, "__supervise__", String(config.port), config.host];
     if (config.configPath) args.push(config.configPath);
     if (config.profile) args.push(config.profile);
+    if (config.share) args.push("--share");
     return args;
   }
 
-  // Bun runtime: bun run <script> __serve__ <port> <host> [config] [profile]
+  // Bun runtime: bun run <script> __supervise__ <port> <host> [config] [profile]
   const bunPath = resolveBunPath();
-  const scriptPath = resolve(import.meta.dir, "..", "server", "index.ts");
-  const args = [bunPath, "run", scriptPath, "__serve__", String(config.port), config.host];
+  const scriptPath = resolve(import.meta.dir, "supervisor.ts");
+  const args = [bunPath, "run", scriptPath, "__supervise__", String(config.port), config.host];
   if (config.configPath) args.push(config.configPath);
   else args.push(""); // placeholder
   if (config.profile) args.push(config.profile);
   else args.push(""); // placeholder
+  if (config.share) args.push("--share");
   return args;
 }
 

package/src/services/supervisor-state.ts

@@ -0,0 +1,100 @@
+/**
+ * Supervisor state machine — state transitions, IPC command file, signal handling.
+ * Extracted from supervisor.ts to keep the orchestrator lean.
+ */
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import {
+  readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, openSync, closeSync,
+} from "node:fs";
+import { constants } from "node:fs";
+
+const PPM_DIR = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"));
+export const CMD_FILE = resolve(PPM_DIR, ".supervisor-cmd");
+export const STATUS_FILE = resolve(PPM_DIR, "status.json");
+export const PID_FILE = resolve(PPM_DIR, "ppm.pid");
+export const LOCK_FILE = resolve(PPM_DIR, ".start-lock");
+
+// ─── State ─────────────────────────────────────────────────────────────
+export type SupervisorState = "running" | "paused" | "stopped" | "upgrading";
+
+let _state: SupervisorState = "running";
+let _resumeResolve: (() => void) | null = null;
+
+export function getState(): SupervisorState { return _state; }
+
+export function setState(s: SupervisorState) { _state = s; }
+
+export function waitForResume(): Promise<void> {
+  return new Promise((res) => { _resumeResolve = res; });
+}
+
+export function triggerResume(): void {
+  if (_resumeResolve) {
+    _resumeResolve();
+    _resumeResolve = null;
+  }
+}
+
+// ─── Status file helpers ───────────────────────────────────────────────
+export function readStatus(): Record<string, unknown> {
+  try {
+    if (existsSync(STATUS_FILE)) return JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+  } catch {}
+  return {};
+}
+
+export function updateStatus(patch: Record<string, unknown>) {
+  try {
+    const data = { ...readStatus(), ...patch };
+    writeFileSync(STATUS_FILE, JSON.stringify(data));
+  } catch {}
+}
+
+// ─── Command file protocol ─────────────────────────────────────────────
+export type CmdAction = "soft_stop" | "resume";
+
+/** Atomically claim + read command file (rename to .claimed, read, delete) */
+export function readAndDeleteCmd(): { action: CmdAction } | null {
+  const claimed = CMD_FILE + ".claimed";
+  try {
+    renameSync(CMD_FILE, claimed); // atomic claim — second caller gets ENOENT
+    const cmd = JSON.parse(readFileSync(claimed, "utf-8"));
+    unlinkSync(claimed);
+    return cmd;
+  } catch {
+    // No command file or already claimed by another handler
+    try { unlinkSync(claimed); } catch {}
+    return null;
+  }
+}
+
+export function writeCmd(action: CmdAction) {
+  writeFileSync(CMD_FILE, JSON.stringify({ action }));
+}
+
+// ─── Lockfile ──────────────────────────────────────────────────────────
+export function acquireLock(): boolean {
+  try {
+    // Try exclusive create — fails if file already exists (atomic)
+    const fd = openSync(LOCK_FILE, "wx");
+    writeFileSync(fd, String(process.pid));
+    closeSync(fd);
+    return true;
+  } catch {
+    // File exists — check if holding process is alive
+    try {
+      const pid = parseInt(readFileSync(LOCK_FILE, "utf-8").trim(), 10);
+      if (!isNaN(pid)) {
+        try { process.kill(pid, 0); return false; } catch {} // stale lock
+      }
+      // Stale lock — overwrite
+      writeFileSync(LOCK_FILE, String(process.pid));
+      return true;
+    } catch { return false; }
+  }
+}
+
+export function releaseLock() {
+  try { unlinkSync(LOCK_FILE); } catch {}
+}

package/src/services/supervisor-stopped-page.ts

@@ -0,0 +1,73 @@
+/**
+ * Minimal HTTP server that serves a "stopped" page when the PPM server child is down.
+ * Binds to the same port so the tunnel URL still works.
+ */
+import { appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+const LOG_FILE = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"), "ppm.log");
+
+function log(level: string, msg: string) {
+  const ts = new Date().toISOString();
+  try { appendFileSync(LOG_FILE, `[${ts}] [${level}] [stopped-page] ${msg}\n`); } catch {}
+}
+
+const STOPPED_HTML = `<!DOCTYPE html>
+<html><head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>PPM - Stopped</title>
+  <style>
+    body { font-family: system-ui; display: flex; justify-content: center;
+           align-items: center; min-height: 100vh; margin: 0;
+           background: #1a1a2e; color: #e0e0e0; }
+    .card { text-align: center; padding: 2rem; }
+    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+    p { color: #888; font-size: 0.9rem; }
+    .dot { display: inline-block; width: 10px; height: 10px;
+           border-radius: 50%; background: #f59e0b; margin-right: 8px; }
+  </style>
+</head><body>
+  <div class="card">
+    <h1><span class="dot"></span>PPM Server Stopped</h1>
+    <p>The server is stopped but the supervisor is still running.</p>
+    <p>Use <code>ppm start</code> or Cloud dashboard to restart.</p>
+  </div>
+</body></html>`;
+
+let stoppedServer: ReturnType<typeof Bun.serve> | null = null;
+
+export function startStoppedPage(port: number, host: string) {
+  if (stoppedServer) return;
+
+  try {
+    stoppedServer = Bun.serve({
+      port,
+      hostname: host,
+      fetch(req) {
+        const url = new URL(req.url);
+        if (url.pathname === "/api/health") {
+          return new Response(JSON.stringify({ status: "stopped" }), {
+            status: 503,
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+        return new Response(STOPPED_HTML, {
+          headers: { "Content-Type": "text/html" },
+        });
+      },
+    });
+    log("INFO", `Stopped page serving on port ${port}`);
+  } catch (e) {
+    log("WARN", `Failed to start stopped page: ${e}`);
+  }
+}
+
+export function stopStoppedPage() {
+  if (stoppedServer) {
+    stoppedServer.stop();
+    stoppedServer = null;
+    log("INFO", "Stopped page server shut down");
+  }
+}

package/src/services/supervisor.ts

@@ -12,6 +12,13 @@ import {
   unlinkSync,
 } from "node:fs";
 import { isCompiledBinary } from "./autostart-generator.ts";
+import {
+  type SupervisorState,
+  getState, setState, waitForResume, triggerResume,
+  readAndDeleteCmd, readStatus, updateStatus,
+  STATUS_FILE, PID_FILE,
+} from "./supervisor-state.ts";
+import { startStoppedPage, stopStoppedPage } from "./supervisor-stopped-page.ts";
 
 // ─── Constants ─────────────────────────────────────────────────────────
 const MAX_RESTARTS = 10;
@@ -28,8 +35,6 @@ const UPGRADE_SKIP_INITIAL_MS = 300_000;    // 5min delay before first check
 const SELF_REPLACE_TIMEOUT_MS = 30_000;     // 30s to wait for new supervisor
 
 const PPM_DIR = resolve(process.env.PPM_HOME || 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");
 const RESTARTING_FLAG = resolve(PPM_DIR, ".restarting");
 
@@ -40,23 +45,10 @@ let tunnelUrl: string | null = null;
 let adoptedTunnelPid: number | null = null; // PID of tunnel kept alive across upgrade
 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;
-  }
-}
+// Module-level refs for softStop (needs access to respawn args)
+let _serverArgs: string[] = [];
+let _logFd: number = -1;
+let _opts: { port: number; host: string; share: boolean } = { port: 8080, host: "0.0.0.0", share: false };
 
 let serverRestarts = 0;
 let lastServerCrash = 0;
@@ -87,21 +79,6 @@ function log(level: string, msg: string) {
   }
 }
 
-// ─── 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);
@@ -130,6 +107,12 @@ export async function spawnServer(
   const exitCode = await serverChild.exited;
   serverChild = null;
 
+  // Don't respawn if in stopped state (soft stop)
+  if (getState() === "stopped") {
+    log("INFO", "Server exited, supervisor in stopped state — not respawning");
+    return;
+  }
+
   if (exitCode === 0 && shuttingDown) {
     log("INFO", `Server exited cleanly (code ${exitCode})`);
     return;
@@ -158,7 +141,7 @@ export async function spawnServer(
   if (serverRestarts > MAX_RESTARTS) {
     log("WARN", `Server exceeded ${MAX_RESTARTS} restarts, pausing`);
     notifyStateChange("running", "paused", "max_restarts_exceeded");
-    supervisorState = "paused";
+    setState("paused");
     updateStatus({
       state: "paused",
       pid: null,
@@ -170,7 +153,7 @@ export async function spawnServer(
     await waitForResume();
     // Resumed — reset and respawn
     notifyStateChange("paused", "running", "user_resume");
-    supervisorState = "running";
+    setState("running");
     serverRestarts = 0;
     updateStatus({ state: "running", pausedAt: null, pauseReason: null });
     log("INFO", "Resuming server after pause");
@@ -301,7 +284,7 @@ export async function spawnTunnel(port: number): Promise<void> {
 // ─── Health checks ─────────────────────────────────────────────────────
 function startServerHealthCheck(port: number) {
   healthTimer = setInterval(async () => {
-    if (shuttingDown || !serverChild) return;
+    if (shuttingDown || !serverChild || getState() === "stopped") return;
     try {
       const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
         signal: AbortSignal.timeout(5000),
@@ -322,6 +305,8 @@ function startTunnelProbe(port: number) {
   tunnelProbeTimer = setInterval(async () => {
     if (shuttingDown || !tunnelUrl) { tunnelFailCount = 0; return; }
     if (!tunnelChild && !adoptedTunnelPid) { tunnelFailCount = 0; return; }
+    // Don't probe when server is intentionally stopped (stopped page serves 503)
+    if (getState() === "stopped") { tunnelFailCount = 0; return; }
 
     // Check if adopted tunnel process is still alive
     if (adoptedTunnelPid && !tunnelChild) {
@@ -421,8 +406,8 @@ 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";
+    notifyStateChange(getState(), "upgrading", "self_replace");
+    setState("upgrading");
     updateStatus({ state: "upgrading" });
 
     // Set restarting flag so server child's stopTunnel() skips killing the tunnel
@@ -470,7 +455,7 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     try { unlinkSync(RESTARTING_FLAG); } catch {}
     shuttingDown = false;
     notifyStateChange("upgrading", "running", "upgrade_failed");
-    supervisorState = "running";
+    setState("running");
     updateStatus({ state: "running" });
     return { success: false, error: "New supervisor failed to start within 30s" };
   } catch (e) {
@@ -478,7 +463,7 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
     try { unlinkSync(RESTARTING_FLAG); } catch {}
     shuttingDown = false;
     notifyStateChange("upgrading", "running", "upgrade_failed");
-    supervisorState = "running";
+    setState("running");
     updateStatus({ state: "running" });
     return { success: false, error: (e as Error).message };
   }
@@ -524,7 +509,7 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
         return {
           type: "heartbeat" as const,
           tunnelUrl,
-          state: supervisorState,
+          state: getState(),
           // Use server-reported version (source of truth) with supervisor fallback
           appVersion: (status.serverVersion as string) || VERSION,
           availableVersion: (status.availableVersion as string) || null,
@@ -560,12 +545,21 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
       });
 
       switch (cmd.action) {
+        case "start":
+          if (getState() === "stopped") {
+            triggerResume();
+            sendResult(true, undefined, { state: "running" });
+          } else {
+            sendResult(false, `Server already in ${getState()} state`);
+          }
+          break;
+
         case "restart":
           if (serverChild) {
             serverRestartRequested = true;
             try { serverChild.kill(); } catch {}
             sendResult(true);
-          } else if (supervisorState === "paused") {
+          } else if (getState() === "paused" || getState() === "stopped") {
             triggerResume();
             sendResult(true);
           } else {
@@ -574,17 +568,25 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
           break;
 
         case "resume":
-          if (supervisorState === "paused") {
+          if (getState() === "paused" || getState() === "stopped") {
             triggerResume();
             sendResult(true);
           } else {
-            sendResult(false, "Not in paused state");
+            sendResult(false, `Not in paused/stopped state (current: ${getState()})`);
           }
           break;
 
         case "stop":
+          if (getState() === "stopped") {
+            sendResult(false, "Already stopped");
+          } else {
+            sendResult(true);
+            softStop();
+          }
+          break;
+
+        case "shutdown":
           sendResult(true);
-          // Delay exit to allow WS buffer to flush
           setTimeout(() => {
             shutdown();
             process.exit(0);
@@ -593,10 +595,13 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
 
         case "status":
           sendResult(true, undefined, {
-            state: supervisorState,
+            state: getState(),
             serverPid: serverChild?.pid ?? null,
             tunnelUrl,
             serverRestarts,
+            stoppedAt: getState() === "stopped"
+              ? readStatus().stoppedAt
+              : null,
           });
           break;
 
@@ -609,6 +614,47 @@ async function connectCloud(opts: { port: number }, serverArgs: string[], logFd:
   }
 }
 
+// ─── Soft stop (server only, supervisor stays alive) ──────────────────
+let _softStopRunning = false;
+export async function softStop() {
+  if (getState() === "stopped" || _softStopRunning) return;
+  _softStopRunning = true;
+
+  log("INFO", "Soft stop: killing server, supervisor stays alive");
+  notifyStateChange(getState(), "stopped", "user_stop");
+  setState("stopped");
+
+  // Kill server child
+  if (serverChild) {
+    try { serverChild.kill(); } catch {}
+    serverChild = null;
+  }
+
+  // Stop health checks (no server to check)
+  if (healthTimer) { clearInterval(healthTimer); healthTimer = null; }
+
+  // Keep: tunnel, Cloud WS, upgrade checks, tunnel probe
+  updateStatus({ state: "stopped", pid: null, stoppedAt: new Date().toISOString() });
+
+  // Start stopped page on the server port so tunnel URL still works
+  await Bun.sleep(500); // brief wait for port release
+  startStoppedPage(_opts.port, _opts.host);
+
+  // Wait for resume signal
+  await waitForResume();
+
+  // Resumed — restart server
+  stopStoppedPage();
+  await Bun.sleep(200); // brief wait for port release
+  notifyStateChange("stopped", "running", "user_start");
+  setState("running");
+  updateStatus({ state: "running", stoppedAt: null });
+  startServerHealthCheck(_opts.port);
+  log("INFO", "Resuming server from stopped state");
+  _softStopRunning = false;
+  spawnServer(_serverArgs, _logFd);
+}
+
 // ─── Shutdown ──────────────────────────────────────────────────────────
 export function shutdown() {
   if (shuttingDown) return;
@@ -653,6 +699,14 @@ export async function runSupervisor(opts: {
   const logFd = openSync(LOG_FILE, "a");
   log("INFO", `Supervisor started (PID: ${process.pid}, port: ${opts.port}, share: ${opts.share})`);
 
+  // Global exception handlers — supervisor must never crash
+  process.on("uncaughtException", (err) => {
+    log("ERROR", `Uncaught exception: ${err.stack || err.message}`);
+  });
+  process.on("unhandledRejection", (reason) => {
+    log("ERROR", `Unhandled rejection: ${reason}`);
+  });
+
   // Write supervisor PID + clear stale availableVersion from previous run
   writeFileSync(PID_FILE, String(process.pid));
   updateStatus({
@@ -668,17 +722,45 @@ export async function runSupervisor(opts: {
   // Strip trailing empty args
   while (serverArgs.length > 0 && serverArgs[serverArgs.length - 1] === "") serverArgs.pop();
 
+  // Save module-level refs for softStop()
+  _serverArgs = serverArgs;
+  _logFd = logFd;
+  _opts = { port: opts.port, host: opts.host, share: opts.share };
+
   // Signal handlers
   process.on("SIGTERM", () => { shutdown(); process.exit(0); });
   process.on("SIGINT", () => { shutdown(); process.exit(0); });
 
-  // SIGUSR2 = graceful server restart (tunnel stays alive) or resume from paused
+  // SIGUSR2 = command file dispatch OR graceful server restart
   process.on("SIGUSR2", () => {
-    if (supervisorState === "paused") {
+    // Check for command file first (soft_stop, resume)
+    const cmd = readAndDeleteCmd();
+    if (cmd) {
+      if (cmd.action === "soft_stop") {
+        log("INFO", "SIGUSR2: soft_stop command received");
+        softStop();
+        return;
+      }
+      if (cmd.action === "resume") {
+        log("INFO", "SIGUSR2: resume command received");
+        if (getState() === "stopped" || getState() === "paused") {
+          triggerResume();
+        }
+        return;
+      }
+    }
+
+    // Default: restart server (existing behavior)
+    if (getState() === "paused") {
       log("INFO", "SIGUSR2 received while paused, resuming server");
       triggerResume();
       return;
     }
+    if (getState() === "stopped") {
+      log("INFO", "SIGUSR2 received while stopped, resuming server");
+      triggerResume();
+      return;
+    }
     log("INFO", "SIGUSR2 received, restarting server only");
     if (serverChild) {
       serverRestartRequested = true; // flag so spawnServer skips backoff
@@ -707,6 +789,18 @@ export async function runSupervisor(opts: {
     upgradeCheckTimer = setInterval(checkAvailableVersion, UPGRADE_CHECK_INTERVAL_MS);
   }, UPGRADE_SKIP_INITIAL_MS);
 
+  // Windows: poll command file since SIGUSR2 is not available
+  if (process.platform === "win32") {
+    setInterval(() => {
+      const cmd = readAndDeleteCmd();
+      if (!cmd) return;
+      if (cmd.action === "soft_stop") { softStop(); }
+      else if (cmd.action === "resume") {
+        if (getState() === "stopped" || getState() === "paused") triggerResume();
+      }
+    }, 1000);
+  }
+
   // Connect to Cloud via WebSocket (if device is linked)
   connectCloud(opts, serverArgs, logFd);
 
@@ -725,7 +819,7 @@ export async function runSupervisor(opts: {
   await Promise.all(promises);
 
   // If upgrading, selfReplace handles process.exit — wait for it
-  if (supervisorState === "upgrading") {
+  if (getState() === "upgrading") {
     log("INFO", "Server loop exited during upgrade, waiting for selfReplace to finish");
     await new Promise(() => {}); // selfReplace will call process.exit()
   }