@hienlh/ppm 0.9.0-beta.7 → 0.9.0-beta.9

package/docs/system-architecture.md

@@ -945,6 +945,157 @@ ppm db data <name> <table>   # Show table data (paginated)
 
 ---
 
+## MCP Server Management
+
+### Overview
+MCP (Model Context Protocol) servers extend Claude with custom tools and resources. PPM manages MCP server configurations via Settings UI, storing them in SQLite and passing them to the Claude Agent SDK.
+
+**Features:**
+- **Add/Edit/Delete** MCP servers via Settings UI
+- **Auto-import** from `~/.claude.json` on first access (convenience, no forced import)
+- **Three transport types:** stdio, HTTP, SSE
+- **Validation** on name and config before storage
+- **SDK integration:** Servers passed to `query()` as `mcpServers` object, tools auto-allowed via `mcp__*` wildcard
+
+### Storage Schema
+
+```sql
+CREATE TABLE mcp_servers (
+  name TEXT PRIMARY KEY,
+  transport TEXT NOT NULL DEFAULT 'stdio',  -- 'stdio' | 'http' | 'sse'
+  config TEXT NOT NULL,                     -- JSON: McpServerConfig
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+```
+
+**Config Format (JSON):**
+```json
+{
+  "type": "stdio",
+  "command": "path/to/server",
+  "args": ["--flag"],
+  "env": { "VAR": "value" }
+}
+```
+
+Or HTTP/SSE:
+```json
+{
+  "type": "http",
+  "url": "http://localhost:3000",
+  "headers": { "Authorization": "Bearer token" }
+}
+```
+
+### REST API
+
+**Endpoints** (`src/server/routes/mcp.ts`):
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| **GET** | `/api/settings/mcp` | List all servers; auto-import on first access |
+| **GET** | `/api/settings/mcp/:name` | Get single server config |
+| **POST** | `/api/settings/mcp` | Add new server (validates name + config) |
+| **PUT** | `/api/settings/mcp/:name` | Update existing server |
+| **DELETE** | `/api/settings/mcp/:name` | Remove server |
+| **GET** | `/api/settings/mcp/import/preview` | Preview servers in `~/.claude.json` |
+| **POST** | `/api/settings/mcp/import` | Bulk import from `~/.claude.json` |
+
+**Add Server Example:**
+```bash
+POST /api/settings/mcp
+Content-Type: application/json
+
+{
+  "name": "file-server",
+  "config": {
+    "type": "stdio",
+    "command": "/usr/local/bin/file-server",
+    "args": ["--port", "8000"]
+  }
+}
+```
+
+### Service Layer
+
+**McpConfigService** (`src/services/mcp-config.service.ts`):
+- `list()` — Record<name, McpServerConfig> (SDK-compatible format)
+- `listWithMeta()` — Array with metadata (for UI)
+- `get(name)` — Single server config
+- `set(name, config)` — Add or update (upsert)
+- `remove(name)` — Delete server
+- `exists(name)` — Check if name exists
+- `bulkImport(servers)` — Transactional import from `~/.claude.json`, skips existing/invalid
+
+**Validation:**
+- `validateMcpName(name)` — alphanumeric + hyphens/underscores, max 50 chars
+- `validateMcpConfig(config)` — type-specific checks (command for stdio, url for http/sse)
+
+### Frontend Integration
+
+**UI Components:**
+- `MCP Settings Section` (`src/web/components/settings/mcp-settings-section.tsx`) — Tab in Settings UI
+- `MCP Server Dialog` (`src/web/components/settings/mcp-server-dialog.tsx`) — Add/Edit modal
+- `API client` (`src/web/lib/api-mcp.ts`) — Fetch/mutate operations
+
+**Workflow:**
+1. User opens Settings → MCP tab
+2. **GET** `/api/settings/mcp` (auto-imports on first access)
+3. Display list with transport badge + actions (edit, delete)
+4. Click "Add" → Dialog with name + transport selector + config fields
+5. **POST** to `/api/settings/mcp` or **PUT** to update
+6. On success, list refreshes
+
+### SDK Integration
+
+**Claude Agent SDK Provider** (`src/providers/claude-agent-sdk.ts`):
+```typescript
+// Line ~574
+const mcpServers = mcpConfigService.list();
+const hasMcp = Object.keys(mcpServers).length > 0;
+
+// Line ~589: Pass to query() if servers exist
+const mcpTools = ["mcp__*"];
+const queryConfig = {
+  // ... other options
+  ...(hasMcp && { mcpServers }),
+  allowedTools: [...otherTools, ...mcpTools],
+};
+
+const query = new Query(messages, queryConfig);
+```
+
+**Tool Allow List:**
+- All MCP tools automatically allowed via wildcard `mcp__*`
+- MCP server connection failures don't block chat (logged as warning)
+
+### Import Flow
+
+**Auto-import on first access:**
+1. GET `/api/settings/mcp` called
+2. If table is empty, read `~/.claude.json`
+3. If `mcpServers` key exists, bulk import (validate + skip duplicates)
+4. Return populated list
+
+**Manual import:**
+1. GET `/api/settings/mcp/import/preview` — show what's available
+2. POST `/api/settings/mcp/import` — import validated servers
+3. Returns `{ imported: N, skipped: M }`
+
+### Error Handling
+
+| Scenario | Response |
+|----------|----------|
+| Invalid name (non-alphanumeric) | 400 Bad Request |
+| Invalid config (missing required fields) | 400 Bad Request |
+| Duplicate name | 409 Conflict |
+| Server not found (GET/:name, PUT/:name, DELETE/:name) | 404 Not Found |
+| `~/.claude.json` not found (import) | 404 Not Found |
+| Corrupt config JSON (recovery) | Log warning, skip entry, continue |
+
+---
+
 ## Deployment Architecture
 
 ### Single-Machine Deployment (Current)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.9.0-beta.7",
+  "version": "0.9.0-beta.9",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",
@@ -45,6 +45,7 @@
     "@radix-ui/react-switch": "^1.2.6",
     "@skitee3000/bun-pty": "^0.3.3",
     "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.23",
     "@uiw/react-codemirror": "^4.25.8",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",

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

@@ -13,8 +13,9 @@ import type {
   ModelOption,
 } from "./provider.interface.ts";
 import { configService } from "../services/config.service.ts";
+import { mcpConfigService } from "../services/mcp-config.service.ts";
 import { updateFromSdkEvent } from "../services/claude-usage.service.ts";
-import { getSessionMapping, setSessionMapping } from "../services/db.service.ts";
+import { getSessionMapping, setSessionMapping, getSessionTitles } 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";
@@ -281,10 +282,13 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   async listSessionsByDir(dir?: string): Promise<SessionInfo[]> {
     try {
       const sdkSessions = await sdkListSessions({ dir, limit: 50 });
+      // Overlay DB titles (user-set) over SDK titles
+      const ids = sdkSessions.map((s) => s.sessionId);
+      const dbTitles = getSessionTitles(ids);
       return sdkSessions.map((s) => ({
         id: s.sessionId,
         providerId: this.id,
-        title: s.customTitle ?? s.summary ?? s.firstPrompt ?? "Chat",
+        title: dbTitles[s.sessionId] ?? s.customTitle ?? s.summary ?? s.firstPrompt ?? "Chat",
         createdAt: new Date(s.lastModified).toISOString(),
         updatedAt: new Date(s.lastModified).toISOString(),
       }));
@@ -430,9 +434,10 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     // go through the permission evaluation chain → canUseTool callback.
     const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch", "ToolSearch"];
     const writeTools = ["Write", "Edit", "Bash", "Agent", "Skill", "TodoWrite", "AskUserQuestion"];
+    const mcpTools = ["mcp__*"];
     const allowedTools = isBypass
-      ? [...readOnlyTools, ...writeTools]
-      : readOnlyTools;
+      ? [...readOnlyTools, ...writeTools, ...mcpTools]
+      : [...readOnlyTools, ...mcpTools];
 
     /**
      * Approval events to yield from the generator.
@@ -568,6 +573,10 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
       console.log(`[sdk] query: session=${sessionId} sdkId=${sdkId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform} accountMode=${!!account} permissionMode=${permissionMode} isBypass=${isBypass}`);
 
+      // Read MCP servers from PPM DB (fresh per query — user may add/remove between chats)
+      const mcpServers = mcpConfigService.list();
+      const hasMcp = Object.keys(mcpServers).length > 0;
+
       const queryOptions: Record<string, any> = {
         // On Windows, child_process.spawn("bun") fails with ENOENT — force node
         ...(process.platform === "win32" && { executable: "node" }),
@@ -580,6 +589,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         env: queryEnv,
         settings: { permissions: { allow: [], deny: [] } },
         allowedTools,
+        ...(hasMcp && { mcpServers }),
         permissionMode,
         allowDangerouslySkipPermissions: isBypass,
         ...(providerConfig.model && { model: providerConfig.model }),
@@ -925,7 +935,16 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           }
 
           // Surface non-success subtypes as errors so FE can display them
+          // But suppress abort errors — user-initiated cancel is not a real error
           if (subtype && subtype !== "success") {
+            const errorsArr0 = Array.isArray(result.errors) ? result.errors : [];
+            const abortDetail = errorsArr0.join(" ") + " " + (typeof result.error === "string" ? result.error : "");
+            if (subtype === "error_during_execution" && /abort|request was aborted/i.test(abortDetail)) {
+              console.log(`[sdk] session=${sessionId} suppressing abort error (user-initiated cancel)`);
+              resultSubtype = subtype;
+              resultNumTurns = result.num_turns as number | undefined;
+              break;
+            }
             // SDK error results use `errors: string[]` array (not singular `error`)
             const errorsArr = Array.isArray(result.errors) ? result.errors : [];
             const sdkDetail = errorsArr.length > 0
@@ -1050,20 +1069,23 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   }
 
 
-  /** Interrupt the current turn — session stays alive for the next message */
+  /** Abort and fully teardown the streaming session — user must resume to continue */
   abortQuery(sessionId: string): void {
     const ss = this.streamingSessions.get(sessionId);
-    if (ss && typeof ss.query.interrupt === "function") {
-      ss.query.interrupt().catch(() => {});
-      console.log(`[sdk] abortQuery: interrupted session=${sessionId}`);
+    if (ss) {
+      // Signal generator to end, then close the query (kills bun subprocess)
+      ss.controller.done();
+      ss.query.close();
+      this.streamingSessions.delete(sessionId);
+      this.activeQueries.delete(sessionId);
+      console.log(`[sdk] abortQuery: closed streaming session=${sessionId}`);
       return;
     }
-    // Fallback: close query entirely and clean up streaming session
+    // Non-streaming fallback
     const q = this.activeQueries.get(sessionId);
     if (q) {
       q.close();
       this.activeQueries.delete(sessionId);
-      this.streamingSessions.delete(sessionId);
     }
   }
 

package/src/server/index.ts

@@ -14,6 +14,7 @@ import { databaseRoutes } from "./routes/database.ts";
 import { fsBrowseRoutes } from "./routes/fs-browse.ts";
 import { accountsRoutes } from "./routes/accounts.ts";
 import { proxyRoutes } from "./routes/proxy.ts";
+import { mcpRoutes } from "./routes/mcp.ts";
 import { browserPreviewRoutes } from "./routes/browser-preview.ts";
 import { initAdapters } from "../services/database/init-adapters.ts";
 import { terminalWebSocket } from "./ws/terminal.ts";
@@ -22,6 +23,10 @@ import { ok, err } from "../types/api.ts";
 
 /** Tee console.log/error to ~/.ppm/ppm.log while preserving terminal output */
 async function setupLogFile() {
+  // Guard: prevent re-wrapping console on hot-reload (bun --hot re-executes the module)
+  if ((globalThis as any).__PPM_LOG_SETUP__) return;
+  (globalThis as any).__PPM_LOG_SETUP__ = true;
+
   const { resolve } = await import("node:path");
   const { homedir } = await import("node:os");
   const { appendFileSync, mkdirSync, existsSync } = await import("node:fs");
@@ -135,6 +140,7 @@ app.route("/api/fs", fsBrowseRoutes);
 
 // API routes
 app.route("/api/settings", settingsRoutes);
+app.route("/api/settings/mcp", mcpRoutes);
 app.route("/api/tunnel", tunnelRoutes);
 app.route("/api/push", pushRoutes);
 app.route("/api/projects", projectRoutes);

package/src/server/routes/chat.ts

@@ -8,7 +8,7 @@ import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sd
 import { listSlashItems } from "../../services/slash-items.service.ts";
 import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.service.ts";
 import { getSessionLog } from "../../services/session-log.service.ts";
-import { getSessionMapping } from "../../services/db.service.ts";
+import { getSessionMapping, setSessionTitle } from "../../services/db.service.ts";
 import { ok, err } from "../../types/api.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
@@ -133,7 +133,9 @@ chatRoutes.patch("/sessions/:id", async (c) => {
     // Resolve PPM UUID → SDK session ID if mapped
     const sdkId = getSessionMapping(id) ?? id;
     const projectPath = c.get("projectPath");
-    // Persist to SDK so Claude Code CLI also sees the custom title
+    // Persist to PPM DB (authoritative source for user-set titles)
+    setSessionTitle(sdkId, title);
+    // Also persist to SDK so Claude Code CLI sees the custom title
     await sdkRenameSession(sdkId, title, { dir: projectPath });
     // Also update in-memory session
     const session = chatService.getSession(id);

package/src/server/routes/mcp.ts

@@ -0,0 +1,84 @@
+import { Hono } from "hono";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mcpConfigService } from "../../services/mcp-config.service";
+import { validateMcpName, validateMcpConfig, type McpServerConfig } from "../../types/mcp";
+import { ok, err } from "../../types/api";
+
+export const mcpRoutes = new Hono();
+
+const CLAUDE_CONFIG = join(homedir(), ".claude.json");
+
+function readClaudeMcpServers(): Record<string, unknown> | null {
+  if (!existsSync(CLAUDE_CONFIG)) return null;
+  try {
+    const data = JSON.parse(readFileSync(CLAUDE_CONFIG, "utf-8"));
+    return data.mcpServers ?? null;
+  } catch { return null; }
+}
+
+// GET / — list all (auto-imports from ~/.claude.json on first access if table empty)
+mcpRoutes.get("/", (c) => {
+  let servers = mcpConfigService.listWithMeta();
+  if (servers.length === 0) {
+    const claudeServers = readClaudeMcpServers();
+    if (claudeServers && Object.keys(claudeServers).length > 0) {
+      mcpConfigService.bulkImport(claudeServers as Record<string, McpServerConfig>);
+      servers = mcpConfigService.listWithMeta();
+    }
+  }
+  return c.json(ok(servers));
+});
+
+// GET /import/preview — show what would be imported
+mcpRoutes.get("/import/preview", (c) => {
+  const servers = readClaudeMcpServers();
+  if (!servers) return c.json(ok({ available: false, servers: {} }));
+  return c.json(ok({ available: true, servers }));
+});
+
+// POST /import — import from ~/.claude.json
+mcpRoutes.post("/import", (c) => {
+  const servers = readClaudeMcpServers();
+  if (!servers) return c.json(err("~/.claude.json not found or has no mcpServers"), 404);
+  const result = mcpConfigService.bulkImport(servers as Record<string, McpServerConfig>);
+  return c.json(ok(result));
+});
+
+// GET /:name — single server
+mcpRoutes.get("/:name", (c) => {
+  const config = mcpConfigService.get(c.req.param("name"));
+  if (!config) return c.json(err("Server not found"), 404);
+  return c.json(ok(config));
+});
+
+// POST / — add new server
+mcpRoutes.post("/", async (c) => {
+  const { name, config } = await c.req.json();
+  const nameErr = validateMcpName(name);
+  if (nameErr) return c.json(err(nameErr), 400);
+  const configErrs = validateMcpConfig(config);
+  if (configErrs.length) return c.json(err(configErrs.join("; ")), 400);
+  if (mcpConfigService.exists(name)) return c.json(err("Server already exists"), 409);
+  mcpConfigService.set(name, config);
+  return c.json(ok({ name }), 201);
+});
+
+// PUT /:name — update server config
+mcpRoutes.put("/:name", async (c) => {
+  const name = c.req.param("name");
+  if (!mcpConfigService.exists(name)) return c.json(err("Server not found"), 404);
+  const config = await c.req.json();
+  const configErrs = validateMcpConfig(config);
+  if (configErrs.length) return c.json(err(configErrs.join("; ")), 400);
+  mcpConfigService.set(name, config);
+  return c.json(ok({ name }));
+});
+
+// DELETE /:name — remove server
+mcpRoutes.delete("/:name", (c) => {
+  const removed = mcpConfigService.remove(c.req.param("name"));
+  if (!removed) return c.json(err("Server not found"), 404);
+  return c.json(ok(true));
+});

package/src/server/ws/chat.ts

@@ -3,6 +3,7 @@ import { providerRegistry } from "../../providers/registry.ts";
 import { resolveProjectPath } from "../helpers/resolve-project.ts";
 import { logSessionEvent } from "../../services/session-log.service.ts";
 import { listSessions as sdkListSessions } from "@anthropic-ai/claude-agent-sdk";
+import { getSessionTitle } from "../../services/db.service.ts";
 import type { ChatWsClientMessage, SessionPhase } from "../../types/api.ts";
 
 const PING_INTERVAL_MS = 15_000; // 15s keepalive
@@ -118,11 +119,12 @@ function clearClientPing(entry: SessionEntry, ws: ChatWsSocket): void {
   }
 }
 
-/** Start cleanup timer — only called when Claude is done AND no FE connected */
-function startCleanupTimer(sessionId: string): void {
+/** Start cleanup timer — called when no FE connected. Urgent mode (30s) for orphaned streaming sessions. */
+function startCleanupTimer(sessionId: string, urgent = false): void {
   const entry = activeSessions.get(sessionId);
   if (!entry) return;
   if (entry.cleanupTimer) clearTimeout(entry.cleanupTimer);
+  const delay = urgent ? 30_000 : CLEANUP_TIMEOUT_MS;
   entry.cleanupTimer = setTimeout(() => {
     console.log(`[chat] session=${sessionId} cleanup: no FE reconnected within timeout`);
     logSessionEvent(sessionId, "INFO", "Session cleaned up (no FE reconnected)");
@@ -134,7 +136,7 @@ function startCleanupTimer(sessionId: string): void {
     for (const interval of entry.pingIntervals.values()) clearInterval(interval);
     entry.pingIntervals.clear();
     activeSessions.delete(sessionId);
-  }, CLEANUP_TIMEOUT_MS);
+  }, delay);
 }
 
 /**
@@ -259,10 +261,11 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
         logSessionEvent(sessionId, "DONE", `subtype=${ev.resultSubtype ?? "none"} turns=${ev.numTurns ?? "?"} ctx=${ev.contextWindowPct ?? "?"}%`);
         if (ev.contextWindowPct != null) lastContextWindowPct = ev.contextWindowPct;
 
-        // Fire-and-forget: title + notification
+        // Fire-and-forget: fetch updated session title (DB title takes priority) + notification
         sdkListSessions({ dir: entry.projectPath, limit: 50 }).then((sessions) => {
           const found = sessions.find((s) => s.sessionId === sessionId || s.sessionId === ev.sessionId);
-          const title = found?.customTitle ?? found?.summary;
+          const dbTitle = getSessionTitle(found?.sessionId ?? sessionId);
+          const title = dbTitle ?? found?.customTitle ?? found?.summary;
           if (title) {
             broadcast(sessionId, { type: "title_updated", title });
             const session = chatService.getSession(sessionId);
@@ -386,11 +389,12 @@ export const chatWebSocket = {
       existing.clients.add(ws);
       setupClientPing(existing, ws);
 
-      // Async: resolve title from SDK if in-memory title is generic
+      // Async: resolve title from SDK if in-memory title is generic (DB title takes priority)
       if (!session?.title || session.title === "Chat" || session.title === "Resumed Chat") {
         sdkListSessions({ dir: projectPath, limit: 50 }).then((sessions) => {
           const found = sessions.find((s) => s.sessionId === sessionId);
-          const title = found?.customTitle ?? found?.summary;
+          const dbTitle = getSessionTitle(found?.sessionId ?? sessionId);
+          const title = dbTitle ?? found?.customTitle ?? found?.summary;
           if (title) {
             broadcast(sessionId, { type: "title_updated", title });
             if (session) session.title = title;
@@ -423,11 +427,12 @@ export const chatWebSocket = {
       sessionTitle: session?.title || null,
     }));
 
-    // Async: resolve title from SDK if in-memory title is generic
+    // Async: resolve title from SDK if in-memory title is generic (DB title takes priority)
     if (!session?.title || session.title === "Chat" || session.title === "Resumed Chat") {
       sdkListSessions({ dir: projectPath, limit: 50 }).then((sessions) => {
         const found = sessions.find((s) => s.sessionId === sessionId);
-        const title = found?.customTitle ?? found?.summary;
+        const dbTitle = getSessionTitle(found?.sessionId ?? sessionId);
+        const title = dbTitle ?? found?.customTitle ?? found?.summary;
         if (title) {
           broadcast(sessionId, { type: "title_updated", title });
           if (session) session.title = title;
@@ -564,7 +569,7 @@ export const chatWebSocket = {
         console.log(`[chat] session=${sessionId} follow-up pushed to generator`);
       }
     } else if (parsed.type === "cancel") {
-      // Interrupt current turn — session stays alive for next message
+      // Fully teardown streaming session — user must resume to continue
       const provider = providerRegistry.get(providerId);
       provider?.abortQuery?.(sessionId);
     } else if (parsed.type === "approval_response") {
@@ -589,8 +594,9 @@ export const chatWebSocket = {
     evictClient(entry, ws);
     console.log(`[chat] session=${sessionId} FE disconnected (phase=${entry.phase}, clients=${entry.clients.size})`);
 
-    if (entry.clients.size === 0 && !entry.isStreamingActive) {
-      startCleanupTimer(sessionId);
+    if (entry.clients.size === 0) {
+      // Use shorter timeout if streaming is still active (orphaned session — no FE to consume events)
+      startCleanupTimer(sessionId, entry.isStreamingActive);
     }
   },
 };

package/src/services/account-selector.service.ts

@@ -57,8 +57,14 @@ class AccountSelectorService {
     // Clear expired cooldowns
     for (const acc of allAccounts) {
       if (acc.status === "cooldown" && acc.cooldownUntil && acc.cooldownUntil <= now) {
-        accountService.setEnabled(acc.id);
-        this.retryCounts.delete(acc.id);
+        try {
+          accountService.setEnabled(acc.id);
+          this.retryCounts.delete(acc.id);
+        } catch {
+          // Account expired or cannot be re-enabled — disable it
+          accountService.setDisabled(acc.id);
+          this.retryCounts.delete(acc.id);
+        }
       }
     }
 

package/src/services/account.service.ts

@@ -69,9 +69,14 @@ const OAUTH_TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
 const OAUTH_SCOPE = "org:create_api_key user:profile user:inference";
 const OAUTH_PLATFORM_REDIRECT = "https://platform.claude.com/oauth/code/callback";
 
+// Survive Bun --hot reloads: persist timer ref across module re-evaluations
+const ACCT_HOT_KEY = "__PPM_ACCT_REFRESH__" as const;
+const acctHotState = ((globalThis as any)[ACCT_HOT_KEY] ??= {
+  refreshTimer: null as ReturnType<typeof setInterval> | null,
+}) as { refreshTimer: ReturnType<typeof setInterval> | null };
+
 class AccountService {
   private pendingStates = new Map<string, { verifier: string; createdAt: number }>();
-  private refreshTimer: ReturnType<typeof setInterval> | null = null;
 
   private toAccount(row: AccountRow): Account {
     let profileData: OAuthProfileData | null = null;
@@ -689,7 +694,7 @@ class AccountService {
   // ---------------------------------------------------------------------------
 
   startAutoRefresh(): void {
-    if (this.refreshTimer) return;
+    if (acctHotState.refreshTimer) return;
     const CHECK_INTERVAL_MS = 5 * 60_000;
     const REFRESH_BUFFER_S = 5 * 60;
 
@@ -729,20 +734,20 @@ class AccountService {
     // Run immediately on startup, then every 5 minutes
     refreshExpiring().catch(() => {});
     cleanupExpiredTemporary();
-    this.refreshTimer = setInterval(() => {
+    acctHotState.refreshTimer = setInterval(() => {
       refreshExpiring().catch(() => {});
       cleanupExpiredTemporary();
     }, CHECK_INTERVAL_MS);
 
-    if (typeof this.refreshTimer === "object" && this.refreshTimer !== null && "unref" in this.refreshTimer) {
-      (this.refreshTimer as NodeJS.Timeout).unref();
+    if (typeof acctHotState.refreshTimer === "object" && acctHotState.refreshTimer !== null && "unref" in acctHotState.refreshTimer) {
+      (acctHotState.refreshTimer as NodeJS.Timeout).unref();
     }
   }
 
   stopAutoRefresh(): void {
-    if (this.refreshTimer) {
-      clearInterval(this.refreshTimer);
-      this.refreshTimer = null;
+    if (acctHotState.refreshTimer) {
+      clearInterval(acctHotState.refreshTimer);
+      acctHotState.refreshTimer = null;
     }
   }
 }