@hienlh/ppm 0.9.0-beta.8 → 0.9.1

package/src/server/ws/extensions.ts

@@ -0,0 +1,175 @@
+/**
+ * WebSocket handler for extension UI bridge.
+ * Routes messages between browser clients and the extension host.
+ */
+import { contributionRegistry } from "../../services/contribution-registry.ts";
+import type { ExtServerMsg, ExtClientMsg } from "../../types/extension-messages.ts";
+
+type ExtWsSocket = {
+  data: { type: string };
+  send: (data: string) => void;
+};
+
+/** All connected extension WS clients */
+const clients = new Set<ExtWsSocket>();
+
+/** Pending request resolvers for quickpick/inputbox responses from browser */
+const pendingRequests = new Map<string, (value: unknown) => void>();
+
+// --- Public API for extension service to push UI updates ---
+
+/** Broadcast a message to all connected extension WS clients */
+export function broadcastExtMsg(msg: ExtServerMsg): void {
+  const data = JSON.stringify(msg);
+  for (const ws of clients) {
+    try { ws.send(data); } catch {}
+  }
+}
+
+/**
+ * Send a request to browser and wait for response (quickpick, inputbox, notification).
+ * The `trackingId` is the key used to match the response.
+ * Returns the resolved value or undefined on timeout.
+ */
+export function requestFromBrowser<T = unknown>(
+  msg: ExtServerMsg,
+  trackingId: string,
+  timeoutMs = 30_000,
+): Promise<T | undefined> {
+  broadcastExtMsg(msg);
+  return new Promise<T | undefined>((resolve) => {
+    const timer = setTimeout(() => {
+      pendingRequests.delete(trackingId);
+      resolve(undefined);
+    }, timeoutMs);
+    pendingRequests.set(trackingId, (value) => {
+      clearTimeout(timer);
+      resolve(value as T);
+    });
+  });
+}
+
+/** Get the number of connected extension WS clients */
+export function getExtClientCount(): number {
+  return clients.size;
+}
+
+// --- WS lifecycle handlers ---
+
+function handleOpen(ws: ExtWsSocket): void {
+  clients.add(ws);
+  console.log(`[ExtWS] Client connected (${clients.size} total)`);
+}
+
+async function handleMessage(ws: ExtWsSocket, raw: string | Buffer): Promise<void> {
+  let msg: ExtClientMsg;
+  try {
+    msg = JSON.parse(typeof raw === "string" ? raw : raw.toString()) as ExtClientMsg;
+  } catch {
+    return;
+  }
+
+  switch (msg.type) {
+    case "ready": {
+      // Send current contributions on connect
+      const contributions = contributionRegistry.getAll();
+      ws.send(JSON.stringify({ type: "contributions:update", contributions } satisfies ExtServerMsg));
+      break;
+    }
+
+    case "command:execute": {
+      try {
+        const { extensionService } = await import("../../services/extension.service.ts");
+        // Forward to extension host worker via RPC
+        if (extensionService["rpc"]) {
+          await extensionService["rpc"].sendRequest("ext:command:execute", msg.command, ...(msg.args ?? []));
+        }
+      } catch (e) {
+        console.error(`[ExtWS] command:execute error:`, e);
+      }
+      break;
+    }
+
+    case "tree:click": {
+      if (msg.command) {
+        try {
+          const { extensionService } = await import("../../services/extension.service.ts");
+          if (extensionService["rpc"]) {
+            await extensionService["rpc"].sendRequest("ext:command:execute", msg.command);
+          }
+        } catch (e) {
+          console.error(`[ExtWS] tree:click command error:`, e);
+        }
+      }
+      break;
+    }
+
+    case "quickpick:resolve": {
+      const resolver = pendingRequests.get(msg.requestId);
+      if (resolver) {
+        pendingRequests.delete(msg.requestId);
+        resolver(msg.selected);
+      }
+      break;
+    }
+
+    case "inputbox:resolve": {
+      const resolver = pendingRequests.get(msg.requestId);
+      if (resolver) {
+        pendingRequests.delete(msg.requestId);
+        resolver(msg.value);
+      }
+      break;
+    }
+
+    case "notification:action": {
+      const resolver = pendingRequests.get(msg.id);
+      if (resolver) {
+        pendingRequests.delete(msg.id);
+        resolver(msg.action);
+      }
+      break;
+    }
+
+    case "webview:message": {
+      try {
+        const { extensionService } = await import("../../services/extension.service.ts");
+        if (extensionService["rpc"]) {
+          await extensionService["rpc"].sendRequest("ext:webview:message", msg.panelId, msg.message);
+        }
+      } catch (e) {
+        console.error(`[ExtWS] webview:message error:`, e);
+      }
+      break;
+    }
+
+    case "tree:expand": {
+      try {
+        const { extensionService } = await import("../../services/extension.service.ts");
+        if (extensionService["rpc"]) {
+          const result = await extensionService["rpc"].sendRequest<{ ok: boolean; items?: unknown[] }>(
+            "ext:tree:expand", msg.viewId, msg.itemId,
+          );
+          if (result?.ok && result.items) {
+            // Send children back to the requesting client (parentId distinguishes child updates from root updates)
+            ws.send(JSON.stringify({ type: "tree:update", viewId: msg.viewId, items: result.items as import("../../types/extension-messages.ts").TreeItemMsg[], parentId: msg.itemId } satisfies ExtServerMsg));
+          }
+        }
+      } catch (e) {
+        console.error(`[ExtWS] tree:expand error:`, e);
+      }
+      break;
+    }
+  }
+}
+
+function handleClose(ws: ExtWsSocket): void {
+  clients.delete(ws);
+  console.log(`[ExtWS] Client disconnected (${clients.size} remaining)`);
+}
+
+export const extensionWebSocket = {
+  open: handleOpen,
+  message: handleMessage,
+  close: handleClose,
+};

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

@@ -9,6 +9,8 @@ const MAX_RETRY_CONFIG_KEY = "account_max_retry";
 const BACKOFF_BASE_MS = 1_000;
 const BACKOFF_MAX_MS = 30 * 60_000;
 const AUTH_BACKOFF_BASE_MS = 5 * 60_000; // 5min base for auth errors (longer than rate limits)
+/** Skip accounts whose 5-hour utilization >= this threshold (proactive avoidance) */
+const FIVE_HOUR_SKIP_THRESHOLD = 0.95;
 
 class AccountSelectorService {
   private cursor = 0;
@@ -74,18 +76,25 @@ class AccountSelectorService {
       return null;
     }
 
+    // Proactive: skip accounts whose 5-hour utilization >= 95%
+    const usable = active.filter((a) => {
+      const snap = getLatestSnapshotForAccount(a.id);
+      return !snap || (snap.five_hour_util ?? 0) < FIVE_HOUR_SKIP_THRESHOLD;
+    });
+    const candidates = usable.length > 0 ? usable : active; // fallback to all if every account is near limit
+
     let pickedId: string;
     const strategy = this.getStrategy();
     if (strategy === "lowest-usage") {
-      pickedId = this.pickLowestUsage(active);
+      pickedId = this.pickLowestUsage(candidates);
     } else if (strategy === "fill-first") {
-      const sorted = [...active].sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt);
+      const sorted = [...candidates].sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt);
       pickedId = sorted[0]!.id;
     } else {
       // Round-robin
-      this.cursor = this.cursor % active.length;
-      pickedId = active[this.cursor]!.id;
-      this.cursor = (this.cursor + 1) % active.length;
+      this.cursor = this.cursor % candidates.length;
+      pickedId = candidates[this.cursor]!.id;
+      this.cursor = (this.cursor + 1) % candidates.length;
     }
     this._lastPickedId = pickedId;
     const result = accountService.getWithTokens(pickedId);

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;
@@ -134,7 +139,7 @@ class AccountService {
       await this.refreshAccessToken(id, false);
       return this.getWithTokens(id);
     } catch (e) {
-      console.error(`[accounts] Pre-flight refresh failed for ${id}:`, e);
+      console.error(`[accounts] Pre-flight refresh failed for ${id}: ${(e as Error).message ?? e}`);
       return null;
     }
   }
@@ -618,13 +623,13 @@ class AccountService {
       if (!row.id || !row.access_token) continue;
       const hasRefresh = !!row.refresh_token && row.refresh_token !== "";
 
-      // Duplicate handling: if existing account has no refresh token but import does, upgrade it
+      // Duplicate handling: update existing account tokens from import
       const existingById = getAccountById(row.id);
       const existingByEmail = row.email ? this.list().find((a) => a.email === row.email) : null;
       const existing = existingById ?? (existingByEmail ? getAccountById(existingByEmail.id) : null);
       if (existing) {
-        if (hasRefresh && !this.hasRefreshToken(existing.id)) {
-          // Upgrade: import has refresh token, existing doesn't → update tokens
+        if (hasRefresh) {
+          // Always update tokens when import has refresh token (handles expired/invalid tokens too)
           let accessToken = row.access_token;
           if (!looksEncrypted(accessToken)) accessToken = encrypt(accessToken);
           const refreshToken = looksEncrypted(row.refresh_token) ? row.refresh_token : encrypt(row.refresh_token);
@@ -636,9 +641,9 @@ class AccountService {
           });
           imported++;
           fullTransferIds.push(existing.id);
-          console.log(`[accounts] Upgraded ${row.email ?? existing.id} with refresh token from import`);
+          console.log(`[accounts] Updated ${row.email ?? existing.id} tokens from import`);
         }
-        continue; // skip if existing already has refresh token or import doesn't
+        continue; // skip if import doesn't have refresh token
       }
 
       // New account — insert
@@ -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;
 
@@ -704,7 +709,7 @@ class AccountService {
         try {
           await this.refreshAccessToken(acc.id, false);
         } catch (e) {
-          console.error(`[accounts] Auto-refresh failed for ${acc.id}:`, e);
+          console.error(`[accounts] Auto-refresh failed for ${acc.id}: ${(e as Error).message ?? e}`);
         }
       }
     };
@@ -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;
     }
   }
 }

package/src/services/claude-usage.service.ts

@@ -47,15 +47,20 @@ const POLL_INTERVAL = 300_000; // 5min
 const ACCOUNT_STAGGER_MS = 1_000; // 1s between accounts
 
 let inMemoryCostUsd = 0;
-let pollTimer: ReturnType<typeof setInterval> | null = null;
+
+// Survive Bun --hot reloads: module-level vars reset on reload, globalThis persists.
+// Without this, each hot-reload creates a NEW polling timer without clearing the old one,
+// leading to N concurrent timers after N reloads (observed: 221 timers → 38k 429 errors/day).
+const HOT_KEY = "__PPM_USAGE_POLL__" as const;
+const hotState = ((globalThis as any)[HOT_KEY] ??= {
+  pollTimer: null as ReturnType<typeof setTimeout> | null,
+  inflightPoll: null as Promise<void> | null,
+}) as { pollTimer: ReturnType<typeof setTimeout> | null; inflightPoll: Promise<void> | null };
 
 // Per-token cooldown map: token prefix → earliest allowed fetch time
 const tokenCooldowns = new Map<string, number>();
 const MIN_COOLDOWN_MS = 60_000; // floor: at least 60s cooldown on 429
 
-// Dedup: if a poll is already in-flight, reuse the same promise
-let inflightPoll: Promise<void> | null = null;
-
 // Legacy: Keychain token cache for users without accounts in DB
 let tokenCache: { token: string; timestamp: number } | null = null;
 const TOKEN_TTL = 300_000;
@@ -248,13 +253,13 @@ async function pollOnceInternal(): Promise<void> {
 
 /** Deduped: concurrent callers share a single in-flight fetch */
 async function pollOnce(): Promise<void> {
-  if (inflightPoll) return inflightPoll;
+  if (hotState.inflightPoll) return hotState.inflightPoll;
   const thisPoll = pollOnceInternal().finally(() => {
     // Only clear if still the current poll — prevents a stale .finally() from
     // clearing a newer poll after timeout handler force-nulled inflightPoll.
-    if (inflightPoll === thisPoll) inflightPoll = null;
+    if (hotState.inflightPoll === thisPoll) hotState.inflightPoll = null;
   });
-  inflightPoll = thisPoll;
+  hotState.inflightPoll = thisPoll;
   return thisPoll;
 }
 
@@ -268,28 +273,28 @@ export function getUsageForAccount(accountId: string): ClaudeUsage {
   return row ? snapshotToUsage(row) : {};
 }
 
-/** Get usage for all accounts (excludes expired temporary accounts) */
+/** Get usage for all accounts */
 export function getAllAccountUsages(): AccountUsageEntry[] {
-  const nowS = Math.floor(Date.now() / 1000);
-  const accounts = accountService.list().filter(acc => {
-    // Exclude expired accounts without refresh token (temporary/invalid)
-    if (!accountService.hasRefreshToken(acc.id) && acc.expiresAt && acc.expiresAt < nowS) return false;
-    return true;
-  });
+  const accounts = accountService.list();
   const snapshots = getAllLatestSnapshots();
   const snapshotMap = new Map(snapshots.map(s => [s.account_id, s]));
-  return accounts.map(acc => {
+  const nowS = Math.floor(Date.now() / 1000);
+  const result: AccountUsageEntry[] = [];
+  for (const acc of accounts) {
     const withTokens = accountService.getWithTokens(acc.id);
+    // Skip expired accounts without refresh token (temporary/disposable)
+    if (acc.expiresAt && acc.expiresAt < nowS && !withTokens?.refreshToken) continue;
     const isOAuth = withTokens?.accessToken.startsWith("sk-ant-oat") ?? false;
     const row = snapshotMap.get(acc.id);
-    return {
+    result.push({
       accountId: acc.id,
       accountLabel: acc.label,
       accountStatus: acc.status,
       isOAuth,
       usage: row ? snapshotToUsage(row) : {},
-    };
-  });
+    });
+  }
+  return result;
 }
 
 /** Get cached usage for active account (used by chat header) */
@@ -314,10 +319,10 @@ export function getCachedUsage(): ClaudeUsage & { activeAccountId?: string; acti
 }
 
 export function startUsagePolling(): void {
-  if (pollTimer) return;
+  if (hotState.pollTimer) return;
   const POLL_TIMEOUT = 60_000; // max 60s per poll iteration
   const scheduleNext = () => {
-    pollTimer = setTimeout(async () => {
+    hotState.pollTimer = setTimeout(async () => {
       const timeout = new Promise<"timeout">(r => setTimeout(() => r("timeout"), POLL_TIMEOUT));
       const result = await Promise.race([
         pollOnce().then(() => "done" as const),
@@ -325,7 +330,7 @@ export function startUsagePolling(): void {
       ]).catch(() => "error" as const);
       // If the poll timed out, force-clear inflightPoll so next scheduled poll
       // starts a fresh fetch instead of reusing the stale hanging promise.
-      if (result === "timeout") inflightPoll = null;
+      if (result === "timeout") hotState.inflightPoll = null;
       scheduleNext();
     }, POLL_INTERVAL);
   };
@@ -333,7 +338,7 @@ export function startUsagePolling(): void {
 }
 
 export function stopUsagePolling(): void {
-  if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
+  if (hotState.pollTimer) { clearTimeout(hotState.pollTimer); hotState.pollTimer = null; }
 }
 
 export function updateFromSdkEvent(_rateLimitType?: string, _utilization?: number, costUsd?: number): void {
@@ -348,8 +353,8 @@ export async function refreshUsageNow(): Promise<ClaudeUsage & { activeAccountId
 /** @internal Test-only: reset module-level state between tests */
 export function _resetForTesting(): void {
   inMemoryCostUsd = 0;
-  if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; }
+  if (hotState.pollTimer) { clearTimeout(hotState.pollTimer); hotState.pollTimer = null; }
   tokenCooldowns.clear();
-  inflightPoll = null;
+  hotState.inflightPoll = null;
   tokenCache = null;
 }

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

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