@hienlh/ppm 0.18.13 → 0.18.15

package/src/server/ws/chat.ts

@@ -10,11 +10,13 @@ import type { ChatWsClientMessage, SessionPhase } from "../../types/api.ts";
 // — a chat socket is not guaranteed to exist now that chat tabs mount lazily.
 import { broadcastGlobalEvent } from "./global.ts";
 import { bashOutputSpy } from "../../services/bash-output-spy.ts";
+import { nestedSubagentSpy } from "../../services/nested-subagent-spy.ts";
+import { resolveSessionDir } from "../../services/subagent-transcript-merger.ts";
 import { backgroundShellRegistry } from "../../services/background-shell-registry.ts";
 import { basename } from "node:path";
 import { configService } from "../../services/config.service.ts";
 import { formatTurnUsageLog } from "../../shared/turn-usage.ts";
-import { isTerminalAgentStatus } from "../../shared/background-agent-status.ts";
+import { isAsyncAgentLaunchAck, isTerminalAgentStatus } from "../../shared/background-agent-status.ts";
 import { cacheReleaseDelayMs, selectWarmIdleEvictions } from "../../services/subprocess-retention.ts";
 
 /** Resolve the SESSION's provider config — not the global default provider's.
@@ -47,10 +49,33 @@ function resolveSessionThinkingEnabled(sessionId: string): boolean {
 }
 
 const PING_INTERVAL_MS = 15_000; // 15s keepalive
-const CLEANUP_TIMEOUT_MS = 5 * 60_000; // 5min after Claude done + no FE
-/** How many clientless sessions may hold a live SDK subprocess at once. */
-const MAX_WARM_IDLE_SESSIONS = 5;
+/**
+ * When an abandoned session's entry is dropped.
+ *
+ * Deliberately *not* derived from the cache window. This timer also drops `activeSessions`
+ * — which carries up to MAX_TURN_EVENTS buffered events per session, tool results included —
+ * plus team watchers and the background-shell registry. Stretching it to the cache window
+ * held all of that for an hour to protect a subprocess it knows nothing about.
+ *
+ * It still must not preempt `scheduleSubprocessRelease`, so when that release is pending the
+ * timer reschedules itself instead of running. The two stay independent, and the long wait
+ * happens only for sessions that actually have a warm subprocess to protect.
+ */
+const CLEANUP_TIMEOUT_MS = 5 * 60_000;
+/**
+ * How many clientless sessions may hold a live SDK subprocess at once.
+ *
+ * This, not the retention window, is what bounds the memory: a longer window keeps these
+ * slots filled for longer but never adds a slot. At ~350MB per subprocess, 10 costs ~3.5GB.
+ */
+const MAX_WARM_IDLE_SESSIONS = 10;
 const MAX_TURN_EVENTS = 10_000; // memory safety cap
+/**
+ * Share of the turn buffer nested-agent children may take. They are restored
+ * from disk on reload anyway; this only keeps a chatty grandchild from evicting
+ * the turn's own later events out of a reconnecting client's replay.
+ */
+const MAX_NESTED_TURN_EVENTS = 2_000;
 const BUFFERABLE_TYPES = new Set([
   "text", "thinking", "tool_use", "tool_result",
   "approval_request", "error", "done", "account_info", "account_retry",
@@ -91,8 +116,10 @@ interface SessionEntry {
   lastImplicitTeamProbe?: number;
   /** Compact indicator state — sticky until turn ends or boundary received, synced on reconnect */
   compactStatus?: "compacting" | null;
-  /** toolUseIds of Bash calls launched with run_in_background — spy is kept alive for these */
+  /** toolUseIds of Bash/Agent calls launched with run_in_background — their spy outlives the tool_result */
   backgroundToolUseIds?: Set<string>;
+  /** Nested-agent children buffered into turnEvents this turn (see MAX_NESTED_TURN_EVENTS) */
+  nestedBuffered?: number;
   /** When the last client left, for evicting the least recently used warm subprocess */
   idleSince?: number;
   /** When the last turn completed — the moment this session's prompt cache was last written */
@@ -116,7 +143,19 @@ function listWarmIdleSessions(): { sessionId: string; entry: SessionEntry; idleS
 /** Release a session's subprocess, if it still has one and nobody is using it. */
 function releaseSubprocess(sessionId: string, reason: string, note: string): void {
   const entry = activeSessions.get(sessionId);
-  if (!entry || entry.clients.size > 0 || entry.isStreamingActive) return;
+  if (!entry) return;
+  // Disarm before deciding anything: past this point the pending release is either being
+  // performed or is moot, and a timer left armed is not merely stale. startCleanupTimer
+  // reschedules itself while `cacheReleaseTimer` is set, so an entry evicted by
+  // enforceWarmIdleCap — which calls straight in here — would outlive its own subprocess by
+  // up to the full TTL, holding its turnEvents buffer, ping interval, team watchers and
+  // shell registry. That is the accumulation the 5-minute cleanup exists to stop, on the one
+  // path that only runs when memory is already tight. Clearing here covers every caller.
+  if (entry.cacheReleaseTimer) {
+    clearTimeout(entry.cacheReleaseTimer);
+    entry.cacheReleaseTimer = undefined;
+  }
+  if (entry.clients.size > 0 || entry.isStreamingActive) return;
   const provider = providerRegistry.get(entry.providerId);
   if (!provider?.hasStreamingSession?.(sessionId)) return;
   provider.abortQuery?.(sessionId, reason);
@@ -124,6 +163,30 @@ function releaseSubprocess(sessionId: string, reason: string, note: string): voi
   logSessionEvent(sessionId, "INFO", note);
 }
 
+/**
+ * Drop a session's live subprocess so its next turn is rebuilt from the transcript on disk.
+ *
+ * Routes that rewrite the JSONL need this. The subprocess holds the conversation in memory,
+ * so a rewrite it never learns about simply does not apply: the user strips an oversized
+ * image, sends again, and the same image is re-sent from memory and fails identically.
+ * `listRunningSessions()` does not cover it — that skips `phase === "idle"`, and a warm idle
+ * subprocess is exactly this case. Unlike `releaseSubprocess` it does not require the session
+ * to be clientless, because the tab being open is the normal way to reach the strip button.
+ */
+export function dropSubprocessForTranscriptRewrite(sessionId: string): void {
+  const entry = activeSessions.get(sessionId);
+  if (!entry) return;
+  const provider = providerRegistry.get(entry.providerId);
+  if (!provider?.hasStreamingSession?.(sessionId)) return;
+  provider.abortQuery?.(sessionId, "transcript_rewritten");
+  if (entry.cacheReleaseTimer) {
+    clearTimeout(entry.cacheReleaseTimer);
+    entry.cacheReleaseTimer = undefined;
+  }
+  console.log(`[chat] session=${sessionId} released subprocess (transcript_rewritten)`);
+  logSessionEvent(sessionId, "INFO", "Subprocess released: the transcript was rewritten, so the next turn is rebuilt from disk");
+}
+
 /** Tear down the longest-idle subprocesses once too many sessions are holding one. */
 function enforceWarmIdleCap(): void {
   const warmIdle = listWarmIdleSessions();
@@ -153,7 +216,10 @@ function scheduleSubprocessRelease(sessionId: string): void {
   if (!provider?.hasStreamingSession?.(sessionId)) return;
 
   const note = "Subprocess released: its prompt cache has expired, so keeping it warm saves nothing";
-  const delay = cacheReleaseDelayMs(entry.lastTurnEndedAt, Date.now());
+  // The window is the provider's to state: an API-key install's cache dies at five minutes,
+  // so holding the subprocess for an hour there guards nothing and costs ~350MB.
+  const ttlMs = provider.promptCacheTtlMs?.(sessionId);
+  const delay = cacheReleaseDelayMs(entry.lastTurnEndedAt, Date.now(), ttlMs);
   if (delay === 0) {
     releaseSubprocess(sessionId, "cache_expired", note);
     return;
@@ -271,6 +337,24 @@ function bufferAndBroadcast(sessionId: string, event: unknown): void {
   broadcast(sessionId, event);
 }
 
+/**
+ * Emit a nested-agent child read off disk. Buffered for reconnect replay only
+ * while its turn is still in flight and under the nested budget; a background
+ * agent that outlives the turn streams its children unbuffered, since the next
+ * turn's replay is not the place for them and reload restores them from disk.
+ */
+function emitNestedChild(sessionId: string, child: unknown): void {
+  const entry = activeSessions.get(sessionId);
+  if (!entry) return;
+  const inFlight = entry.isStreamingActive && entry.phase !== "idle";
+  if (inFlight && (entry.nestedBuffered ?? 0) < MAX_NESTED_TURN_EVENTS) {
+    entry.nestedBuffered = (entry.nestedBuffered ?? 0) + 1;
+    bufferAndBroadcast(sessionId, child);
+  } else {
+    broadcast(sessionId, child);
+  }
+}
+
 /** How often a session may stat ~/.claude/teams looking for an implicit team. */
 const IMPLICIT_TEAM_PROBE_INTERVAL_MS = 3_000;
 
@@ -367,6 +451,13 @@ function startCleanupTimer(sessionId: string): void {
   entry.cleanupTimer = setTimeout(() => {
     // Double-check: don't kill if streaming started while timer was pending
     if (entry.isStreamingActive) return;
+    // A pending release means the subprocess is still worth holding, and dropping the entry
+    // takes it with us. Come back after that timer rather than stretching this one.
+    if (entry.cacheReleaseTimer) {
+      entry.cleanupTimer = undefined;
+      startCleanupTimer(sessionId);
+      return;
+    }
     console.log(`[chat] session=${sessionId} cleanup: idle with no FE for ${CLEANUP_TIMEOUT_MS / 1000}s`);
     logSessionEvent(sessionId, "INFO", "Session cleaned up (idle, no FE reconnected)");
     // Backstop for the subprocess: scheduleSubprocessRelease normally gets there first,
@@ -405,6 +496,7 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
   entry.isStreamingActive = true;
   entry.pendingApprovalEvent = undefined;
   entry.turnEvents = [];
+  entry.nestedBuffered = 0;
   setPhase(sessionId, "connecting");
 
   let heartbeat: ReturnType<typeof setInterval> | undefined;
@@ -484,6 +576,9 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
           // the card can settle. Harmless for background bash tasks: no card matches them.
           if (sub === "task_notification" && taskToolUseId && isTerminalAgentStatus(taskStatus)) {
             broadcast(sessionId, { type: "subagent_status", toolUseId: taskToolUseId, status: taskStatus });
+            // The agent is done, so its nested workers are too — release the tail.
+            nestedSubagentSpy.stopSpy(taskToolUseId);
+            entry.backgroundToolUseIds?.delete(taskToolUseId);
           }
           if (taskId) {
             // Ensure the shell is registered even if the spy missed the file (fallback).
@@ -549,6 +644,18 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
           entry.pendingTeamCreate = ev.toolUseId;
           console.log(`[chat] session=${sessionId} TeamCreate tool_use detected, toolUseId=${ev.toolUseId}`);
         }
+        // A session-level Agent card: the SDK streams its agent's own steps, but
+        // nothing from agents that agent spawns in turn. Tail those nested
+        // transcripts from disk so the card keeps moving instead of freezing on
+        // the step that forked them. Claude-SDK-only — the layout is the CLI's.
+        if (providerId === "claude" && (ev.tool === "Agent" || ev.tool === "Task") && ev.toolUseId && !ev.parentToolUseId) {
+          const sessionDir = resolveSessionDir(sessionId, entry.projectPath);
+          if (sessionDir) {
+            nestedSubagentSpy.startSpy(sessionId, ev.toolUseId, sessionDir, (events) => {
+              for (const child of events) emitNestedChild(sessionId, child);
+            });
+          }
+        }
         // Start output spy for real-time streaming (Bash on Linux/macOS, PowerShell on Windows).
         // Claude-SDK-only: it tails the SDK's per-tool output file. Other providers
         // (codex/cursor) run commands in their own subprocess with no such file.
@@ -600,10 +707,18 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
       } else if (evType === "tool_result") {
         logSessionEvent(sessionId, "TOOL_RESULT", `error=${ev.isError ?? false} ${(ev.output ?? "").slice(0, 300)}`);
         console.log(`[chat] session=${sessionId} tool_result: toolUseId=${ev.toolUseId} pendingTeamCreate=${entry.pendingTeamCreate} output=${(ev.output ?? "").slice(0, 200)}`);
+        // A backgrounded Agent's tool_result is only a launch ack while the agent
+        // runs on — keep its nested spy until the terminal task_notification.
+        // Keyed off the ack text: `input.run_in_background` is optional and absent
+        // from most recorded calls (see background-agent-status.ts).
+        if (ev.toolUseId && !ev.parentToolUseId && isAsyncAgentLaunchAck(ev.output)) {
+          (entry.backgroundToolUseIds ??= new Set()).add(ev.toolUseId);
+        }
         // Stop bash output spy for this tool — EXCEPT background commands, whose
         // process keeps running after tool_result; keep tailing their .output.
         if (ev.toolUseId && !entry.backgroundToolUseIds?.has(ev.toolUseId)) {
           bashOutputSpy.stopSpy(ev.toolUseId);
+          nestedSubagentSpy.stopSpy(ev.toolUseId);
         }
         // Detect team creation from TeamCreate tool_result (legacy explicit teams)
         if (entry.pendingTeamCreate && entry.pendingTeamCreate === ev.toolUseId) {
@@ -689,6 +804,7 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
           console.log(`[chat] session_migrated: ${sessionId} → ${newId}`);
           // Stop spies tagged with old session ID before re-keying
           bashOutputSpy.stopAllForSession(sessionId);
+          nestedSubagentSpy.stopAllForSession(sessionId);
           backgroundShellRegistry.clearSession(sessionId);
           const oldEntry = activeSessions.get(sessionId);
           if (oldEntry) {
@@ -741,6 +857,9 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
     bufferAndBroadcast(sessionId, { type: "error", message: errMsg });
   } finally {
     if (heartbeat) clearInterval(heartbeat);
+    // Drain nested-agent tails while their turn buffer still exists, so the last
+    // records land in this turn's replay instead of the head of the next one.
+    nestedSubagentSpy.stopAllForSession(sessionId);
     entry.isStreamingActive = false;
     entry.turnEvents = [];
     // Force-clear compact status on stream teardown (error, close, etc.)

package/src/server/ws/remote-desktop.ts

@@ -0,0 +1,86 @@
+/**
+ * WS handler for `/ws/remote-desktop` — binary out = framed video access units (1-byte
+ * key/delta header + Annex-B bytes), text in = JSON control messages.
+ *
+ * The connection is *not* trusted just because the upgrade succeeded: the coarse PPM auth
+ * token already travels as `?token=` on every WS URL (`isWsUpgradeAuthorized`,
+ * `src/server/index.ts`) and proves nothing beyond "holds the one reusable app token", so a
+ * single-use short-TTL nonce (`POST /api/remote-desktop/session`) must be presented as the
+ * client's *first* message — `{type:"auth", nonce}` — before capture or input starts. Kept out
+ * of the query string (unlike the coarse token) so it never lands in proxy/tunnel access logs.
+ *
+ * Both the feature flag and `auth.enabled` are re-checked here even though
+ * `src/server/index.ts` already gated the upgrade on them — this handler must never depend on
+ * a single call site staying correct as fetch-time routing evolves, and must NOT reuse
+ * `isWsUpgradeAuthorized()`, which returns `true` unconditionally when PPM auth is disabled.
+ */
+import { configService } from "../../services/config.service.ts";
+import { isRemoteDesktopEnabled } from "../../services/remote-desktop/remote-desktop-flag.ts";
+import { consumeRemoteDesktopNonce } from "../../services/remote-desktop/remote-desktop-nonce.ts";
+import {
+  createRemoteDesktopSession,
+  registerRemoteDesktopExitSweep,
+  type RemoteDesktopSession,
+  type RemoteDesktopSocket,
+} from "../../services/remote-desktop/remote-desktop-session.ts";
+
+registerRemoteDesktopExitSweep();
+
+interface RemoteDesktopWs {
+  data: { type: "remote-desktop"; session?: RemoteDesktopSession; authenticated?: boolean };
+  send: (d: string | Uint8Array) => number;
+  getBufferedAmount?: () => number;
+  close: (code?: number, reason?: string) => void;
+}
+
+function guardOrClose(ws: RemoteDesktopWs): boolean {
+  if (!isRemoteDesktopEnabled()) { ws.close(1008, "remote desktop is disabled"); return false; }
+  if (!configService.get("auth").enabled) {
+    ws.close(1008, "remote desktop requires PPM authentication to be enabled");
+    return false;
+  }
+  return true;
+}
+
+async function authenticateFirstMessage(ws: RemoteDesktopWs, text: string): Promise<void> {
+  let parsed: Record<string, unknown>;
+  try { parsed = JSON.parse(text); } catch { ws.close(1008, "expected auth message"); return; }
+  const nonce = parsed.type === "auth" ? parsed.nonce : undefined;
+  if (typeof nonce !== "string" || !consumeRemoteDesktopNonce(nonce)) {
+    ws.close(1008, "invalid or expired session nonce");
+    return;
+  }
+  ws.data.authenticated = true;
+  try {
+    const socket: RemoteDesktopSocket = {
+      send: (d) => ws.send(d),
+      getBufferedAmount: ws.getBufferedAmount ? () => ws.getBufferedAmount!() : undefined,
+      close: (code, reason) => ws.close(code, reason),
+    };
+    ws.data.session = await createRemoteDesktopSession(socket);
+  } catch (e) {
+    console.error(`[remote-desktop] failed to start capture: ${(e as Error).message}`);
+    ws.send(JSON.stringify({ type: "error", message: (e as Error).message }));
+    ws.close(1011, "capture failed to start");
+  }
+}
+
+export const remoteDesktopWebSocket = {
+  open(ws: RemoteDesktopWs) {
+    guardOrClose(ws); // nothing else to do until the client's first (auth) message arrives
+  },
+
+  async message(ws: RemoteDesktopWs, msg: string | ArrayBuffer | Uint8Array) {
+    if (!guardOrClose(ws)) return;
+    const text = typeof msg === "string" ? msg : new TextDecoder().decode(msg as ArrayBuffer);
+    if (!ws.data.authenticated) {
+      await authenticateFirstMessage(ws, text);
+      return;
+    }
+    await ws.data.session?.handleClientMessage(text);
+  },
+
+  close(ws: RemoteDesktopWs) {
+    ws.data.session?.close();
+  },
+};

package/src/services/account.service.ts

@@ -131,21 +131,36 @@ class AccountService {
    * Returns the refreshed account with fresh tokens, or null if refresh failed.
    */
   async ensureFreshToken(id: string): Promise<AccountWithTokens | null> {
+    return (await this.ensureFreshTokenChecked(id)).account;
+  }
+
+  /**
+   * `ensureFreshToken`, keeping the reason it failed.
+   *
+   * `rejected` means the OAuth server turned the refresh token itself down (`invalid_grant`
+   * / `invalid_request`): nothing local recovers from that, only a fresh sign-in. Anything
+   * else — a network drop, a 429, a decrypt failure — is transient and worth retrying,
+   * which is a different sentence to put in front of a user. `ensureFreshToken` collapses
+   * the two because its callers are background loops with nobody to tell; the one caller
+   * that has a user in front of it (`PATCH /api/accounts/:id`) uses this.
+   */
+  async ensureFreshTokenChecked(id: string): Promise<{ account: AccountWithTokens | null; rejected: boolean }> {
     const acc = this.getWithTokens(id);
-    if (!acc) return null;
+    if (!acc) return { account: null, rejected: false };
     // Only OAuth tokens need refresh
-    if (!acc.accessToken.startsWith("sk-ant-oat")) return acc;
-    if (!acc.expiresAt) return acc;
+    if (!acc.accessToken.startsWith("sk-ant-oat")) return { account: acc, rejected: false };
+    if (!acc.expiresAt) return { account: acc, rejected: false };
     const nowS = Math.floor(Date.now() / 1000);
     const REFRESH_BUFFER_S = 3600; // 1 hour — refresh proactively before expiry
-    if (acc.expiresAt - nowS > REFRESH_BUFFER_S) return acc; // still fresh
+    if (acc.expiresAt - nowS > REFRESH_BUFFER_S) return { account: acc, rejected: false }; // still fresh
     try {
       console.log(`[accounts] Pre-flight refresh for ${acc.email ?? id} (expires in ${acc.expiresAt - nowS}s, buffer=${REFRESH_BUFFER_S}s)`);
       await this.refreshAccessToken(id, false, false, REFRESH_BUFFER_S);
-      return this.getWithTokens(id);
+      return { account: this.getWithTokens(id), rejected: false };
     } catch (e) {
-      console.error(`[accounts] Pre-flight refresh failed for ${id}: ${(e as Error).message ?? e}`);
-      return null;
+      const msg = (e as Error).message ?? String(e);
+      console.error(`[accounts] Pre-flight refresh failed for ${id}: ${msg}`);
+      return { account: null, rejected: /invalid_grant|invalid_request/.test(msg) };
     }
   }
 
@@ -183,6 +198,8 @@ class AccountService {
       }
       if (params.label) updateAccount(dup.id, { label: params.label });
       if (params.email) updateAccount(dup.id, { email: params.email });
+      // After the email lands, or the first re-add of a row that had none logs a UUID.
+      this.noteParkSurvivedReAdd(dup.id);
       return this.toAccount(getAccountById(dup.id)!);
     }
 
@@ -284,9 +301,18 @@ class AccountService {
     // Check for duplicate — update tokens on existing account
     const dup = this.findDuplicate(email, info.profileData);
     if (dup) {
-      updateAccount(dup.id, { access_token: encrypt(params.apiKey), status: "active", cooldown_until: null });
+      // Mirrors updateTokens(): a fresh token ends a cooldown, but a park is a decision
+      // about the rotation and pasting the token in again does not reverse it. This was the
+      // one door left that force-enabled, which is how the two paths disagreed.
+      const parked = getAccountById(dup.id)?.status === "disabled";
+      updateAccount(dup.id, {
+        access_token: encrypt(params.apiKey),
+        cooldown_until: null,
+        ...(parked ? {} : { status: "active" as const }),
+      });
       if (info.profileData) updateAccount(dup.id, { profile_json: JSON.stringify(info.profileData) });
       if (email) updateAccount(dup.id, { email });
+      this.noteParkSurvivedReAdd(dup.id);
       return this.toAccount(getAccountById(dup.id)!);
     }
 
@@ -326,15 +352,39 @@ class AccountService {
   }
 
   updateTokens(id: string, accessToken: string, refreshToken: string, expiresAt: number): void {
+    // A disabled account keeps that status. Usage polling refreshes parked accounts on
+    // purpose (a GET costs no quota), and export does the same before writing a backup;
+    // activating here put them back in the chat rotation behind the user's back, so the
+    // toggle looked like it had been forgotten — most visibly after a restart, which
+    // polls immediately. Cooldown still clears for everything else: a fresh token is
+    // precisely what ends a cooldown.
+    const parked = getAccountById(id)?.status === "disabled";
     updateAccount(id, {
       access_token: encrypt(accessToken),
       refresh_token: encrypt(refreshToken),
       expires_at: expiresAt,
-      status: "active",
+      // The cooldown clears either way — a fresh token is what ends one, and leaving the
+      // timestamp on a parked account would resurrect it the moment the park is lifted.
       cooldown_until: null,
+      ...(parked ? {} : { status: "active" as const }),
     });
   }
 
+  /**
+   * Both re-add doors land here once the new tokens are stored. Neither lifts a park —
+   * disabling is a decision about the rotation, and carrying credentials in does not reverse
+   * it — but landing tokens and then showing nothing is exactly what made the OAuth path look
+   * like a no-op. Saying so is the whole point; keeping it in one place is what stops the two
+   * doors from drifting apart again.
+   */
+  private noteParkSurvivedReAdd(id: string): void {
+    const row = getAccountById(id);
+    if (row?.status !== "disabled") return;
+    console.log(
+      `[accounts] Tokens updated for ${row.email ?? id} — account stays disabled; enable it in Settings`,
+    );
+  }
+
   setCooldown(id: string, untilMs: number): void {
     updateAccount(id, {
       status: "cooldown",
@@ -352,7 +402,11 @@ class AccountService {
       const acc = this.list().find((a) => a.id === id);
       const nowS = Math.floor(Date.now() / 1000);
       if (acc?.expiresAt && acc.expiresAt < nowS) {
-        throw new Error("Cannot re-enable expired temporary account. Please login again or import a fresh backup.");
+        // Signing in again refreshes the tokens but no longer re-enables anything, so the
+        // text says what actually happens: get a live token in, then flip it back on here.
+        throw new Error(
+          "Cannot re-enable expired temporary account. Sign in again or import a fresh backup to refresh its tokens, then enable it here.",
+        );
       }
     }
     updateAccount(id, { status: "active", cooldown_until: null });
@@ -552,9 +606,15 @@ class AccountService {
 
   /**
    * POST the refresh grant, retrying transient failures with backoff.
-   * A network blip (e.g. waking from sleep) must not cost a whole refresh cycle —
-   * Anthropic's refresh token dies shortly after the access token, so the retry
-   * window before it lapses for good is narrow.
+   * A network blip (e.g. waking from sleep) must not cost a whole refresh cycle: this
+   * runs at or past access-token expiry, so a dropped attempt leaves the account unable
+   * to serve a turn until the next sweep.
+   *
+   * It is *not* that the refresh token is about to lapse with it. Measured against a
+   * live install's history: 324 refreshes, zero `invalid_grant`, and one that succeeded
+   * after a 58-hour gap — 50 hours past the 8-hour access-token expiry. Refresh tokens
+   * outlive their access tokens by days, which is what makes freezing a parked account
+   * (see `startAutoRefresh`) safe rather than a slow way to kill it.
    */
   private async postRefreshGrant(refreshToken: string, label: string): Promise<Response> {
     const backoffMs = [2_000, 6_000];
@@ -664,7 +724,8 @@ class AccountService {
    * Export accounts backup.
    * @param includeRefreshToken - if true, includes refresh tokens (full transfer).
    *   Source keeps its refresh token; it will be auto-cleared if it becomes invalid.
-   *   Default false = temporary export (access-only, ~1h).
+   *   Default false = temporary export (access-only, ~1h — see `refreshBeforeExport`,
+   *   which freshens the access token first so the window starts at export time).
    */
   exportEncrypted(password: string, accountIds?: string[], includeRefreshToken = false): string {
     const rows = accountIds?.length
@@ -709,14 +770,25 @@ class AccountService {
           let accessToken = row.access_token;
           if (!looksEncrypted(accessToken)) accessToken = encrypt(accessToken);
           const refreshToken = looksEncrypted(row.refresh_token) ? row.refresh_token : encrypt(row.refresh_token);
+          // An account parked on THIS machine stays parked: the import carries tokens, not
+          // the local decision about who is in the rotation. A new account still takes the
+          // backup's status below, since there is no local decision to respect. An account
+          // the failed-refresh path disabled is recoverable in one click — the import gives
+          // it back a live refresh token, which is what setEnabled() checks for.
+          const parked = existing.status === "disabled";
           updateAccount(existing.id, {
             access_token: accessToken,
             refresh_token: refreshToken,
             expires_at: row.expires_at,
-            status: "active",
+            ...(parked ? {} : { status: "active" as const }),
           });
           imported++;
-          fullTransferIds.push(existing.id);
+          // The usage poller and export both refresh a parked account, because a token
+          // nothing ever refreshes eventually dies. This one is different: it is not
+          // keeping the token alive, it is claiming ownership of it — and claiming a token
+          // for an account this machine has taken out of the rotation buys nothing here
+          // while invalidating the machine still using it. Enabling the account claims it.
+          if (!parked) fullTransferIds.push(existing.id);
           console.log(`[accounts] Updated ${row.email ?? existing.id} tokens from import`);
         }
         continue; // skip if import doesn't have refresh token
@@ -726,6 +798,11 @@ class AccountService {
       let accessToken = row.access_token;
       if (!looksEncrypted(accessToken)) accessToken = encrypt(accessToken);
       const refreshToken = hasRefresh ? (looksEncrypted(row.refresh_token) ? row.refresh_token : encrypt(row.refresh_token)) : encrypt("");
+      // The column has no CHECK constraint and the blob is user-supplied, so anything
+      // outside the three real statuses lands as active. A stray value reads as *on* in
+      // the UI (`status !== "disabled"`) while never being selectable for a turn.
+      const importedStatus =
+        row.status === "disabled" || row.status === "cooldown" ? row.status : "active";
       insertAccount({
         id: row.id,
         label: row.label,
@@ -733,7 +810,7 @@ class AccountService {
         access_token: accessToken,
         refresh_token: refreshToken,
         expires_at: row.expires_at,
-        status: row.status ?? "active",
+        status: importedStatus,
         cooldown_until: row.cooldown_until,
         priority: row.priority ?? 0,
         total_requests: row.total_requests ?? 0,
@@ -741,7 +818,7 @@ class AccountService {
         profile_json: row.profile_json ?? null,
       });
       imported++;
-      if (hasRefresh) fullTransferIds.push(row.id);
+      if (hasRefresh && importedStatus !== "disabled") fullTransferIds.push(row.id);
     }
 
     // Immediately refresh full-transfer accounts to claim ownership
@@ -781,11 +858,17 @@ class AccountService {
       const accounts = this.list();
       const nowS = Math.floor(Date.now() / 1000);
       for (const acc of accounts) {
-        // Freeze disabled accounts: skip background refresh entirely.
-        // Refreshing rotates the OAuth refresh token; when the same account is
-        // shared across machines/processes the rotation races and one side gets
-        // invalid_grant, killing an account the user only meant to park. Leaving
-        // a disabled account untouched keeps its token intact until re-enabled.
+        // Skip disabled accounts: this timer exists to keep the chat rotation supplied and
+        // a parked account is not in it. Refreshing rotates the OAuth refresh token; when
+        // the same account is shared across machines the rotation races and one side gets
+        // invalid_grant, killing an account the user only meant to park.
+        //
+        // A preference, not a guarantee, and worth knowing before relying on it: the usage
+        // poller runs on the same 5-minute cadence with the same 1-hour buffer and does not
+        // skip parked accounts — deliberately, because a token nothing ever refreshes does
+        // eventually die. So while polling is on, a parked account's token still rotates
+        // here-or-there; this skip only declines to be the one that does it. Enabling the
+        // account proves the token either way (`PATCH /api/accounts/:id`).
         if (acc.status === "disabled") continue;
         if (!acc.expiresAt) continue;
         if (acc.expiresAt - nowS > REFRESH_BUFFER_S) continue;

package/src/services/db-backup/db-backup-paths.ts

@@ -0,0 +1,66 @@
+import { resolve, basename } from "node:path";
+import { homedir } from "node:os";
+import { getPpmDir, isIsolatedPpmHome } from "../ppm-dir.ts";
+
+/**
+ * Where database snapshots live, and how their filenames encode when and why
+ * they were taken.
+ *
+ * The directory deliberately sits OUTSIDE `~/.ppm` in production. A snapshot
+ * kept next to the database it protects dies with it: the whole point is to
+ * survive the case where something wipes or overwrites the PPM directory.
+ * Under an isolated `PPM_HOME` (tests) it goes back inside that temp dir, so a
+ * test run can never write snapshots into the user's real home.
+ *
+ * `homedir()` here is a deliberate exception to the getPpmDir()-only rule (see
+ * CLAUDE.md "PPM Directory"): the sibling location is the entire reason this
+ * directory survives a PPM-directory wipe, so it cannot be derived from
+ * `getPpmDir()` in production.
+ */
+export function getBackupsDir(): string {
+  return isIsolatedPpmHome()
+    ? resolve(getPpmDir(), "backups")
+    : resolve(homedir(), ".ppm-backups");
+}
+
+/** Why a snapshot was taken. Encoded in the filename so `ppm restore` can explain each candidate. */
+export type BackupReason = "hourly" | "premigrate" | "start" | "manual";
+
+export const BACKUP_REASONS: readonly BackupReason[] = ["hourly", "premigrate", "start", "manual"];
+
+/** `2026-09-06T15:46:00.000Z` → `20260906T154600Z` (filename-safe, still sorts chronologically). */
+export function formatBackupStamp(date: Date): string {
+  return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+
+/**
+ * Snapshot filename. `dbFile` is the SOURCE database's basename (`ppm.db`,
+ * `ppm.dev.db`), kept in the name so a dev-profile run never prunes or
+ * restores production snapshots.
+ */
+export function backupFileName(dbFile: string, date: Date, reason: BackupReason): string {
+  const stem = basename(dbFile).replace(/\.db$/, "");
+  return `${stem}-${formatBackupStamp(date)}-${reason}.db`;
+}
+
+export interface ParsedBackupName {
+  dbStem: string;
+  date: Date;
+  reason: BackupReason;
+}
+
+/**
+ * Inverse of `backupFileName`. Returns null for anything this module did not
+ * write — including `.partial` files from an interrupted snapshot, which must
+ * never be offered as a restore candidate.
+ */
+export function parseBackupName(name: string): ParsedBackupName | null {
+  const m = /^(.+)-(\d{8}T\d{6}Z)-([a-z]+)\.db$/.exec(name);
+  if (!m) return null;
+  const [, dbStem, stamp, reason] = m;
+  if (!BACKUP_REASONS.includes(reason as BackupReason)) return null;
+  const iso = `${stamp!.slice(0, 4)}-${stamp!.slice(4, 6)}-${stamp!.slice(6, 8)}T${stamp!.slice(9, 11)}:${stamp!.slice(11, 13)}:${stamp!.slice(13, 15)}Z`;
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return null;
+  return { dbStem: dbStem!, date, reason: reason as BackupReason };
+}