@hienlh/ppm 0.9.51 → 0.9.53

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+- **Full `ppm bot` CLI**: All 13 Telegram commands now have CLI equivalents — `project switch/list/current`, `session new/list/resume/stop`, `memory save/list/forget`, `status`, `version`, `restart`, `help`. AI can invoke any command via Bash tool from natural language (e.g. "chuyển sang project ppm" → `ppm bot project switch ppm`).
+- **Auto-detect chat ID**: `resolveChatId()` auto-detects single approved paired Telegram chat. Falls back to `--chat <id>` when multiple chats exist.
+- **System prompt with natural language mapping**: AI receives full CLI reference + Vietnamese/English intent examples, executes commands directly instead of describing actions.
+
 ## [0.9.51] - 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.51",
+  "version": "0.9.53",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",

package/src/cli/commands/bot-cmd.ts

@@ -11,17 +11,44 @@ const C = {
 };
 
 /**
- * `ppm bot memory` CLI — allows AI (via Bash tool) to save/list/forget
- * cross-project memories in the _global scope of clawbot_memories table.
+ * Resolve the Telegram chatId for CLI operations.
+ * Auto-detects if exactly 1 approved paired chat exists.
+ * Otherwise requires --chat flag.
+ */
+export async function resolveChatId(chatOpt?: string): Promise<string> {
+  if (chatOpt) return chatOpt;
+
+  const { getApprovedPairedChats } = await import("../../services/db.service.ts");
+  const approved = getApprovedPairedChats();
+
+  if (approved.length === 0) {
+    throw new Error("No paired Telegram chats. Pair a device in PPM Settings first.");
+  }
+  if (approved.length > 1) {
+    const ids = approved.map((c) => `  ${c.telegram_chat_id} (${c.display_name || "unknown"})`).join("\n");
+    throw new Error(`Multiple paired chats found. Use --chat <id> to specify:\n${ids}`);
+  }
+  return approved[0]!.telegram_chat_id;
+}
+
+/**
+ * `ppm bot` CLI — allows AI (via Bash tool) to manage PPMBot sessions,
+ * projects, memories, and server operations through natural language.
  *
- * Usage from AI:
- *   ppm bot memory save "User prefers Vietnamese" --category preference
- *   ppm bot memory list
- *   ppm bot memory forget "Vietnamese"
+ * All session/project commands auto-detect the paired Telegram chat.
  */
 export function registerBotCommands(program: Command): void {
   const bot = program.command("bot").description("PPMBot utilities");
 
+  registerMemoryCommands(bot);
+  registerProjectCommands(bot);
+  registerSessionCommands(bot);
+  registerMiscCommands(bot);
+}
+
+// ── Memory ──────────────────────────────────────────────────────────
+
+function registerMemoryCommands(bot: Command): void {
   const mem = bot.command("memory").description("Manage cross-project memories");
 
   mem
@@ -94,3 +121,349 @@ export function registerBotCommands(program: Command): void {
       }
     });
 }
+
+// ── Project ─────────────────────────────────────────────────────────
+
+function registerProjectCommands(bot: Command): void {
+  const proj = bot.command("project").description("Manage bot project context");
+
+  proj
+    .command("list")
+    .description("List available projects")
+    .option("--json", "Output as JSON")
+    .action(async (opts: { json?: boolean }) => {
+      try {
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+        const projects = sessions.getProjectNames();
+
+        if (opts.json) {
+          console.log(JSON.stringify(projects));
+          return;
+        }
+
+        if (projects.length === 0) {
+          console.log(`${C.dim}No projects configured.${C.reset}`);
+          return;
+        }
+
+        // Show current project if possible
+        let current = "";
+        try {
+          const chatId = await resolveChatId();
+          const active = sessions.getActiveSession(chatId);
+          current = active?.projectName ?? "";
+        } catch { /* no chat — skip marker */ }
+
+        for (const name of projects) {
+          const marker = name === current ? ` ${C.green}✓${C.reset}` : "";
+          console.log(`  ${name}${marker}`);
+        }
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  proj
+    .command("switch <name>")
+    .description("Switch to a different project")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .action(async (name: string, opts: { chat?: string }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+        const session = await sessions.switchProject(chatId, name);
+        console.log(`${C.green}✓${C.reset} Switched to ${C.bold}${session.projectName}${C.reset}`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  proj
+    .command("current")
+    .description("Show current project")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .action(async (opts: { chat?: string }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+        const active = sessions.getActiveSession(chatId);
+
+        // Fallback: check DB for active session
+        if (!active) {
+          const { getActivePPMBotSession } = await import("../../services/db.service.ts");
+          const { configService } = await import("../../services/config.service.ts");
+          const projects = (configService.get("projects") as any[]) ?? [];
+          for (const p of projects) {
+            const dbSession = getActivePPMBotSession(chatId, p.name);
+            if (dbSession) {
+              console.log(dbSession.project_name);
+              return;
+            }
+          }
+          console.log(`${C.dim}No active project. Use: ppm bot project switch <name>${C.reset}`);
+          return;
+        }
+        console.log(active.projectName);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+}
+
+// ── Session ─────────────────────────────────────────────────────────
+
+function registerSessionCommands(bot: Command): void {
+  const sess = bot.command("session").description("Manage chat sessions");
+
+  sess
+    .command("new")
+    .description("Start a fresh session (current project)")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .action(async (opts: { chat?: string }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+
+        // Get current project before closing
+        const active = sessions.getActiveSession(chatId);
+        const projectName = active?.projectName;
+        await sessions.closeSession(chatId);
+        const session = await sessions.getOrCreateSession(chatId, projectName ?? undefined);
+        console.log(`${C.green}✓${C.reset} New session for ${C.bold}${session.projectName}${C.reset} (${session.sessionId.slice(0, 8)})`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  sess
+    .command("list")
+    .description("List recent sessions")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .option("-l, --limit <n>", "Max results", "20")
+    .option("--json", "Output as JSON")
+    .action(async (opts: { chat?: string; limit: string; json?: boolean }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { getRecentPPMBotSessions, getSessionTitles, getPinnedSessionIds } = await import("../../services/db.service.ts");
+        const allSessions = getRecentPPMBotSessions(chatId, Number(opts.limit) || 20);
+
+        if (allSessions.length === 0) {
+          console.log(`${C.dim}No sessions found.${C.reset}`);
+          return;
+        }
+
+        const titles = getSessionTitles(allSessions.map((s) => s.session_id));
+        const pinnedIds = getPinnedSessionIds();
+
+        // Sort: pinned first, then by last_message_at desc
+        const sorted = [...allSessions].sort((a, b) => {
+          const aPin = pinnedIds.has(a.session_id) ? 1 : 0;
+          const bPin = pinnedIds.has(b.session_id) ? 1 : 0;
+          if (aPin !== bPin) return bPin - aPin;
+          return b.last_message_at - a.last_message_at;
+        });
+
+        if (opts.json) {
+          const jsonData = sorted.map((s, i) => ({
+            index: i + 1,
+            sessionId: s.session_id,
+            project: s.project_name,
+            title: titles[s.session_id]?.replace(/^\[PPM\]\s*/, "") || "",
+            pinned: pinnedIds.has(s.session_id),
+            active: !!s.is_active,
+            lastMessage: new Date(s.last_message_at * 1000).toISOString(),
+          }));
+          console.log(JSON.stringify(jsonData, null, 2));
+          return;
+        }
+
+        for (const [i, s] of sorted.entries()) {
+          const pin = pinnedIds.has(s.session_id) ? "📌 " : "   ";
+          const activeDot = s.is_active ? ` ${C.green}⬤${C.reset}` : "";
+          const rawTitle = titles[s.session_id]?.replace(/^\[PPM\]\s*/, "") || "";
+          const title = rawTitle ? rawTitle.slice(0, 50) : `${C.dim}untitled${C.reset}`;
+          const sid = s.session_id.slice(0, 8);
+          const date = new Date(s.last_message_at * 1000).toLocaleString(undefined, {
+            month: "short", day: "numeric", hour: "2-digit", minute: "2-digit",
+          });
+
+          console.log(`${pin}${i + 1}. ${title}${activeDot}`);
+          console.log(`      ${C.dim}${sid} · ${s.project_name} · ${date}${C.reset}`);
+        }
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  sess
+    .command("resume <target>")
+    .description("Resume a session by index number or session ID prefix")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .action(async (target: string, opts: { chat?: string }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+
+        const index = parseInt(target, 10);
+        const isIndex = !isNaN(index) && index >= 1 && String(index) === target.trim();
+
+        const session = isIndex
+          ? await sessions.resumeSessionById(chatId, index)
+          : await sessions.resumeSessionByIdPrefix(chatId, target.trim());
+
+        if (!session) {
+          console.log(`${C.yellow}Session not found: ${target}${C.reset}`);
+          process.exit(1);
+        }
+        console.log(`${C.green}✓${C.reset} Resumed session ${C.dim}${session.sessionId.slice(0, 8)}${C.reset} (${C.bold}${session.projectName}${C.reset})`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  sess
+    .command("stop")
+    .description("End the current session")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .action(async (opts: { chat?: string }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+        await sessions.closeSession(chatId);
+        console.log(`${C.green}✓${C.reset} Session ended`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+}
+
+// ── Misc: status, version, restart, help ────────────────────────────
+
+function registerMiscCommands(bot: Command): void {
+  bot
+    .command("status")
+    .description("Show current project and session info")
+    .option("--chat <id>", "Telegram chat ID (auto-detected if single)")
+    .option("--json", "Output as JSON")
+    .action(async (opts: { chat?: string; json?: boolean }) => {
+      try {
+        const chatId = await resolveChatId(opts.chat);
+        const { PPMBotSessionManager } = await import("../../services/ppmbot/ppmbot-session.ts");
+        const sessions = new PPMBotSessionManager();
+        const active = sessions.getActiveSession(chatId);
+
+        // Fallback: check DB for any active session
+        let project = active?.projectName ?? "";
+        let provider = active?.providerId ?? "";
+        let sessionId = active?.sessionId ?? "";
+
+        if (!active) {
+          const { getRecentPPMBotSessions } = await import("../../services/db.service.ts");
+          const recent = getRecentPPMBotSessions(chatId, 1);
+          if (recent.length > 0 && recent[0]!.is_active) {
+            project = recent[0]!.project_name;
+            provider = recent[0]!.provider_id;
+            sessionId = recent[0]!.session_id;
+          }
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify({ chatId, project, provider, sessionId }));
+          return;
+        }
+
+        if (!project) {
+          console.log(`${C.dim}No active session. Use: ppm bot project switch <name>${C.reset}`);
+          return;
+        }
+
+        console.log(`Project:  ${C.bold}${project}${C.reset}`);
+        console.log(`Provider: ${provider}`);
+        console.log(`Session:  ${C.dim}${sessionId.slice(0, 12)}…${C.reset}`);
+        console.log(`Chat:     ${chatId}`);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  bot
+    .command("version")
+    .description("Show PPM version")
+    .action(async () => {
+      try {
+        const { VERSION } = await import("../../version.ts");
+        console.log(`PPM v${VERSION}`);
+      } catch {
+        console.log("PPM version unknown");
+      }
+    });
+
+  bot
+    .command("restart")
+    .description("Restart the PPM server")
+    .action(async () => {
+      try {
+        const { join } = await import("node:path");
+        const { writeFileSync } = await import("node:fs");
+        const { homedir } = await import("node:os");
+        const { getApprovedPairedChats } = await import("../../services/db.service.ts");
+
+        const approvedChats = getApprovedPairedChats();
+        const chatIds = approvedChats.map((c) => c.telegram_chat_id);
+
+        const markerPath = join(homedir(), ".ppm", "restart-notify.json");
+        writeFileSync(markerPath, JSON.stringify({ chatIds, ts: Date.now() }));
+
+        console.log(`${C.green}✓${C.reset} Restart signal sent (exit code 42)`);
+        process.exit(42);
+      } catch (e) {
+        console.error(`${C.red}✗${C.reset} ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+      }
+    });
+
+  bot
+    .command("help")
+    .description("Show all bot CLI commands")
+    .action(() => {
+      console.log(`${C.bold}PPMBot CLI Commands${C.reset}
+
+${C.cyan}Project:${C.reset}
+  ppm bot project list             List available projects
+  ppm bot project switch <name>    Switch to a project
+  ppm bot project current          Show current project
+
+${C.cyan}Session:${C.reset}
+  ppm bot session new              Start fresh session
+  ppm bot session list             List recent sessions
+  ppm bot session resume <n|id>    Resume a session
+  ppm bot session stop             End current session
+
+${C.cyan}Memory (cross-project):${C.reset}
+  ppm bot memory save "<text>"     Save a memory (-c category)
+  ppm bot memory list              List saved memories
+  ppm bot memory forget "<topic>"  Delete matching memories
+
+${C.cyan}Server:${C.reset}
+  ppm bot status                   Current project/session info
+  ppm bot version                  Show PPM version
+  ppm bot restart                  Restart PPM server
+
+${C.dim}Session/project commands auto-detect your Telegram chat.
+Use --chat <id> if multiple chats are paired.${C.reset}`);
+    });
+}

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");