@hienlh/ppm 0.18.14 → 0.18.15

package/src/services/remote-desktop/remote-desktop-session.ts

@@ -0,0 +1,189 @@
+/**
+ * Owns one remote-desktop connection end to end: capture lifecycle, WS backpressure,
+ * heartbeat/TTL teardown, and forwarding input to the injector. "One active session per
+ * host" — a new connection evicts (and awaits) any previous one before starting its own
+ * capture so two `gdigrab` processes never contend for the same display.
+ */
+import { startCapture, type CaptureHandle } from "./remote-desktop-capture.ts";
+import { avc1CodecString } from "./avc1-codec-string.ts";
+import type { AccessUnit } from "./access-unit-assembler.ts";
+import { injectPointer, injectKey, injectWheel, releaseAllModifiers, isInputAvailable } from "./remote-desktop-input.ts";
+
+/** Minimal socket surface this module needs — matches Bun's `ServerWebSocket` shape closely
+ *  enough to be faked in a unit test without a real connection. */
+export interface RemoteDesktopSocket {
+  send(data: string | Uint8Array): number;
+  getBufferedAmount?(): number;
+  close(code?: number, reason?: string): void;
+}
+
+/** App-level heartbeat, independent of Bun's 960s socket `idleTimeout` — a dead tunnel or a
+ * sleeping laptop must not leave ffmpeg + input access live for minutes unattended. */
+const HEARTBEAT_INTERVAL_MS = 5_000;
+// 30s (6 missed 5s pings): tolerant of brief network jitter and of a client whose ping timer
+// is throttled while its tab is briefly backgrounded, without leaving an unattended session
+// (ffmpeg + input access) live for long. The client also re-pings the moment its tab is visible.
+const HEARTBEAT_TIMEOUT_MS = 30_000;
+/** Above this many buffered bytes, drop delta AUs until the next keyframe rather than
+ *  queueing forever — a slow WAN/tunnel link must degrade to "waits ~2s for a keyframe",
+ *  never to unbounded memory growth or an ever-growing latency queue. */
+const BACKPRESSURE_THRESHOLD_BYTES = 512 * 1024;
+
+export class RemoteDesktopSession {
+  private capture: CaptureHandle | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastPingAt = Date.now();
+  private droppingUntilKey = false;
+  private sentConfig = false;
+  private closed = false;
+  private readonly heldKeyCodes = new Set<string>();
+  private exitResolve: (() => void) | null = null;
+  /** Resolves once the underlying ffmpeg process has actually exited (not merely asked to). */
+  readonly exited: Promise<void>;
+
+  constructor(private readonly ws: RemoteDesktopSocket) {
+    this.exited = new Promise((resolve) => { this.exitResolve = resolve; });
+  }
+
+  async start(): Promise<void> {
+    this.capture = await startCapture({
+      onAccessUnit: (au) => this.handleAccessUnit(au),
+      // `reason` is only set when ffmpeg died on its own (crash, access denied, etc) — tell
+      // the client *why* before closing instead of leaving it to guess from a bare
+      // disconnect (this is exactly what happens today for e.g. gdigrab failing against a
+      // disconnected Windows session: "Failed to capture image (error 5)").
+      onExit: (_code, reason) => {
+        this.exitResolve?.();
+        if (!this.closed) {
+          if (reason) {
+            try { this.ws.send(JSON.stringify({ type: "error", message: `Capture failed: ${reason}` })); } catch { /* closing anyway */ }
+          }
+          this.close();
+        }
+      },
+    });
+    this.heartbeatTimer = setInterval(() => this.checkHeartbeat(), HEARTBEAT_INTERVAL_MS);
+  }
+
+  noteClientAlive(): void {
+    this.lastPingAt = Date.now();
+  }
+
+  async handleClientMessage(raw: string): Promise<void> {
+    let msg: Record<string, unknown>;
+    try { msg = JSON.parse(raw); } catch { return; }
+    if (msg.type === "ping") { this.noteClientAlive(); return; }
+    if (msg.type === "stop") { this.close(); return; }
+    if (!isInputAvailable()) return; // part 1b unsupported on this OS — silently ignore
+
+    if (msg.type === "pointer") {
+      const { xFrac, yFrac, button, down } = msg as { xFrac?: unknown; yFrac?: unknown; button?: unknown; down?: unknown };
+      if (typeof xFrac === "number" && typeof yFrac === "number") {
+        const btn = button === "left" || button === "right" ? button : null;
+        await injectPointer(xFrac, yFrac, btn, typeof down === "boolean" ? down : null);
+      }
+      return;
+    }
+    if (msg.type === "wheel") {
+      const { dy } = msg as { dy?: unknown };
+      if (typeof dy === "number" && Number.isFinite(dy)) await injectWheel(dy);
+      return;
+    }
+    if (msg.type === "key") {
+      const { code, down } = msg as { code?: unknown; down?: unknown };
+      if (typeof code === "string" && typeof down === "boolean") {
+        if (down) this.heldKeyCodes.add(code); else this.heldKeyCodes.delete(code);
+        await injectKey(code, down);
+      }
+      return;
+    }
+    if (msg.type === "releaseAll") {
+      await this.releaseHeldKeys();
+    }
+  }
+
+  /** Force a keyup for every key this session has tracked as held, then run the modifier
+   *  backstop too — `heldKeyCodes` covers whatever the client actually pressed (letters,
+   *  digits, etc, not just modifiers); `releaseAllModifiers()` is a second backstop for a
+   *  modifier that raced a disconnect before its keydown was ever tracked. Previously this
+   *  only ran the modifier backstop and *cleared* `heldKeyCodes` without releasing them,
+   *  so a held non-modifier key (e.g. a letter) stayed logically down on the host. */
+  private async releaseHeldKeys(): Promise<void> {
+    const codes = [...this.heldKeyCodes];
+    this.heldKeyCodes.clear();
+    await Promise.all(codes.map((code) => injectKey(code, false).catch(() => {})));
+    await releaseAllModifiers();
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.capture?.stop();
+    activeSessions.delete(this);
+    if (this.heldKeyCodes.size > 0) {
+      this.releaseHeldKeys().catch(() => {});
+    }
+    try { this.ws.close(); } catch { /* already closing */ }
+  }
+
+  private checkHeartbeat(): void {
+    if (Date.now() - this.lastPingAt > HEARTBEAT_TIMEOUT_MS) {
+      console.warn("[remote-desktop] heartbeat timeout — tearing down session");
+      this.close();
+    }
+  }
+
+  private handleAccessUnit(au: AccessUnit): void {
+    if (this.closed) return;
+    if (!this.sentConfig) {
+      const sps = this.capture?.cachedSps();
+      if (!sps) return; // nothing decodable yet — wait for the encoder's first SPS
+      const codec = avc1CodecString(sps);
+      if (!codec) return;
+      this.ws.send(JSON.stringify({ type: "config", codec }));
+      this.sentConfig = true;
+    }
+
+    const buffered = this.ws.getBufferedAmount?.() ?? 0;
+    if (buffered > BACKPRESSURE_THRESHOLD_BYTES && !au.isKey) {
+      this.droppingUntilKey = true;
+      return;
+    }
+    if (this.droppingUntilKey && !au.isKey) return;
+    if (au.isKey) this.droppingUntilKey = false;
+
+    const framed = new Uint8Array(1 + au.bytes.length);
+    framed[0] = au.isKey ? 1 : 0;
+    framed.set(au.bytes, 1);
+    this.ws.send(framed);
+  }
+}
+
+const activeSessions = new Set<RemoteDesktopSession>();
+
+/** Evict any previous session (awaiting its ffmpeg exit, capped so a wedged process can't
+ *  hang a reconnect) before starting the new one. */
+export async function createRemoteDesktopSession(ws: RemoteDesktopSocket): Promise<RemoteDesktopSession> {
+  for (const existing of [...activeSessions]) {
+    existing.close();
+    await Promise.race([existing.exited, Bun.sleep(2000)]);
+  }
+  const session = new RemoteDesktopSession(ws);
+  await session.start();
+  activeSessions.add(session);
+  return session;
+}
+
+/** Process-exit sweep so ffmpeg never outlives a server crash/exit — a clean WS close or an
+ *  idle heartbeat timeout is handled by the session itself; this covers everything else
+ *  (SIGINT/SIGTERM, uncaught crash unwind). */
+let sweepRegistered = false;
+export function registerRemoteDesktopExitSweep(): void {
+  if (sweepRegistered) return;
+  sweepRegistered = true;
+  const sweep = () => { for (const s of [...activeSessions]) s.close(); };
+  process.on("exit", sweep);
+  process.on("SIGINT", sweep);
+  process.on("SIGTERM", sweep);
+}

package/src/services/remote-desktop/remote-desktop-vk-map.ts

@@ -0,0 +1,41 @@
+/**
+ * `KeyboardEvent.code` (physical key, layout-independent) → Win32 virtual-key code.
+ * Only `code` is accepted from the client — `key` depends on the browser's active layout
+ * and would map wrong the moment host and client disagree on layout.
+ */
+const CODE_TO_VK: Record<string, number> = {
+  Backspace: 0x08, Tab: 0x09, Enter: 0x0d, ShiftLeft: 0xa0, ShiftRight: 0xa1,
+  ControlLeft: 0xa2, ControlRight: 0xa3, AltLeft: 0xa4, AltRight: 0xa5,
+  Pause: 0x13, CapsLock: 0x14, Escape: 0x1b, Space: 0x20,
+  PageUp: 0x21, PageDown: 0x22, End: 0x23, Home: 0x24,
+  ArrowLeft: 0x25, ArrowUp: 0x26, ArrowRight: 0x27, ArrowDown: 0x28,
+  Insert: 0x2d, Delete: 0x2e,
+  Digit0: 0x30, Digit1: 0x31, Digit2: 0x32, Digit3: 0x33, Digit4: 0x34,
+  Digit5: 0x35, Digit6: 0x36, Digit7: 0x37, Digit8: 0x38, Digit9: 0x39,
+  KeyA: 0x41, KeyB: 0x42, KeyC: 0x43, KeyD: 0x44, KeyE: 0x45, KeyF: 0x46,
+  KeyG: 0x47, KeyH: 0x48, KeyI: 0x49, KeyJ: 0x4a, KeyK: 0x4b, KeyL: 0x4c,
+  KeyM: 0x4d, KeyN: 0x4e, KeyO: 0x4f, KeyP: 0x50, KeyQ: 0x51, KeyR: 0x52,
+  KeyS: 0x53, KeyT: 0x54, KeyU: 0x55, KeyV: 0x56, KeyW: 0x57, KeyX: 0x58,
+  KeyY: 0x59, KeyZ: 0x5a,
+  MetaLeft: 0x5b, MetaRight: 0x5c, ContextMenu: 0x5d,
+  Numpad0: 0x60, Numpad1: 0x61, Numpad2: 0x62, Numpad3: 0x63, Numpad4: 0x64,
+  Numpad5: 0x65, Numpad6: 0x66, Numpad7: 0x67, Numpad8: 0x68, Numpad9: 0x69,
+  NumpadMultiply: 0x6a, NumpadAdd: 0x6b, NumpadSubtract: 0x6d,
+  NumpadDecimal: 0x6e, NumpadDivide: 0x6f,
+  F1: 0x70, F2: 0x71, F3: 0x72, F4: 0x73, F5: 0x74, F6: 0x75,
+  F7: 0x76, F8: 0x77, F9: 0x78, F10: 0x79, F11: 0x7a, F12: 0x7b,
+  NumLock: 0x90, ScrollLock: 0x91,
+  Semicolon: 0xba, Equal: 0xbb, Comma: 0xbc, Minus: 0xbd, Period: 0xbe,
+  Slash: 0xbf, Backquote: 0xc0, BracketLeft: 0xdb, Backslash: 0xdc,
+  BracketRight: 0xdd, Quote: 0xde,
+};
+
+/** All modifier VK codes — used to force-release stuck modifiers on teardown (a lost keyup
+ *  otherwise leaves e.g. Shift logically held on the host after the WS drops). */
+export const MODIFIER_VK_CODES = [0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0x5b, 0x5c] as const;
+
+/** Resolve a `KeyboardEvent.code` to its VK; null for anything unmapped (IME composition,
+ *  unusual layouts) rather than guessing and injecting the wrong key. */
+export function codeToVk(code: string): number | null {
+  return CODE_TO_VK[code] ?? null;
+}

package/src/services/subagent-transcript-merger.ts

@@ -5,11 +5,13 @@
  * session JSONL (no isSidechain lines, no parent_tool_use_id). Instead each
  * agent gets its own transcript at:
  *   ~/.claude/projects/<slug>/<sessionId>/subagents/agent-<id>.jsonl
- * with a sibling agent-<id>.meta.json carrying the spawning Agent tool_use id.
+ * with a sibling agent-<id>.meta.json carrying the spawning Agent tool_use id
+ * (session-spawned agents) or the spawning agent's id (nested agents).
  *
  * Without merging these, a reloaded session shows bare Agent cards and the
- * live-streamed children are lost. This module reads the meta files, parses
- * each agent transcript, and attaches its events as the card's children.
+ * live-streamed children are lost. This module groups the transcripts under
+ * their session-level card, parses each one, and attaches the events — every
+ * nesting level flattened into one time-ordered list — as the card's children.
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
@@ -17,18 +19,20 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ChatEvent } from "../types/chat.ts";
 import { parseSessionMessage } from "./jsonl-transcript-parser.ts";
+import { groupSubagentsByCard } from "./team-member-activity/subagent-transcript-index.ts";
 
 /**
  * Locate the per-session directory (…/projects/<slug>/<sessionId>) that holds
- * subagents/. The SDK encodes the cwd by replacing separators + drive colon
- * with "-"; when that drifts (drive-letter case), fall back to scanning
- * project dirs for the session's main JSONL.
+ * subagents/. The SDK encodes the cwd by replacing separators, drive colon
+ * and dots with "-" (`…\ppm\.claude\worktrees\x` → `…-ppm--claude-worktrees-x`);
+ * when that drifts (drive-letter case), fall back to scanning project dirs for
+ * the session's main JSONL.
  */
 export function resolveSessionDir(sessionId: string, projectPath: string | null | undefined): string | null {
   const home = homedir();
   const projectsRoot = join(home, ".claude", "projects");
   if (projectPath) {
-    const encoded = projectPath.replace(/[/\\:]/g, "-");
+    const encoded = projectPath.replace(/[/\\:.]/g, "-");
     const dir = join(projectsRoot, encoded);
     if (existsSync(join(dir, `${sessionId}.jsonl`))) return join(dir, sessionId);
   }
@@ -53,92 +57,105 @@ interface MessageLike {
 const MAX_CHILDREN_PER_AGENT = 2000;
 const MAX_CHILD_OUTPUT_CHARS = 50_000;
 
-/** Map of Agent-card toolUseId → agent transcript path, from subagents/*.meta.json */
-function indexAgentTranscripts(subagentsDir: string): Map<string, string> {
-  const map = new Map<string, string>();
-  let entries: string[];
-  try {
-    entries = readdirSync(subagentsDir);
-  } catch {
-    return map;
-  }
-  for (const name of entries) {
-    if (!name.endsWith(".meta.json")) continue;
-    try {
-      const meta = JSON.parse(readFileSync(join(subagentsDir, name), "utf8"));
-      const toolUseId = meta?.toolUseId as string | undefined;
-      if (!toolUseId) continue;
-      const transcript = join(subagentsDir, name.replace(/\.meta\.json$/, ".jsonl"));
-      if (existsSync(transcript)) map.set(toolUseId, transcript);
-    } catch {
-      /* unreadable meta — skip this agent */
-    }
-  }
-  return map;
+/** One child event plus the transcript record time it came from (epoch ms). */
+export interface TimedChatEvent {
+  ts: number;
+  ev: ChatEvent;
 }
 
-/** Parse one agent transcript into a flat children event list (stream order). */
-export function parseAgentTranscript(filePath: string): ChatEvent[] {
-  const children: ChatEvent[] = [];
+/**
+ * Incremental parser for one agent transcript. Feed it JSONL lines in file
+ * order (whole file at once, or a live tail's new lines) and it returns the
+ * child events those lines carry, keeping the skip/limit state across calls.
+ */
+export function createAgentTranscriptLineParser() {
+  let isFirstUser = true;
+  let emitted = 0;
+  let lastTs = 0;
+  return {
+    feed(line: string): TimedChatEvent[] {
+      const out: TimedChatEvent[] = [];
+      const trimmed = line.trim();
+      if (!trimmed || emitted >= MAX_CHILDREN_PER_AGENT) return out;
+      let entry: any;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        return out;
+      }
+      if (entry.type !== "user" && entry.type !== "assistant") return out;
+      if (!entry.message) return out;
+      // The first user record is the agent's spawn prompt — the live stream
+      // never showed it as a child, so skip it to match the streaming view.
+      if (entry.type === "user" && isFirstUser) {
+        isFirstUser = false;
+        const content = entry.message?.content;
+        const hasToolResult = Array.isArray(content) && content.some((b: any) => b?.type === "tool_result");
+        if (!hasToolResult) return out;
+      }
+      // Records without a timestamp inherit the previous one so file order holds.
+      const parsedTs = typeof entry.timestamp === "string" ? Date.parse(entry.timestamp) : NaN;
+      if (!Number.isNaN(parsedTs)) lastTs = parsedTs;
+      const parsed = parseSessionMessage(entry);
+      for (const ev of parsed.events ?? []) {
+        if (emitted >= MAX_CHILDREN_PER_AGENT) break;
+        // Keep single events from ballooning the history payload (agent files
+        // can carry multi-MB tool outputs the live stream also showed in full,
+        // but 24 agents × full outputs breaks mobile reloads).
+        if (ev.type === "tool_result" && typeof ev.output === "string" && ev.output.length > MAX_CHILD_OUTPUT_CHARS) {
+          ev.output = ev.output.slice(0, MAX_CHILD_OUTPUT_CHARS) + "\n… [truncated]";
+        }
+        out.push({ ts: lastTs, ev });
+        emitted++;
+      }
+      return out;
+    },
+  };
+}
+
+/** Parse one whole agent transcript into timed child events (file order). */
+export function parseAgentTranscriptTimed(filePath: string): TimedChatEvent[] {
   let text: string;
   try {
     text = readFileSync(filePath, "utf8");
   } catch {
-    return children;
-  }
-  let isFirstUser = true;
-  for (const line of text.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let entry: any;
-    try {
-      entry = JSON.parse(trimmed);
-    } catch {
-      continue;
-    }
-    if (entry.type !== "user" && entry.type !== "assistant") continue;
-    if (!entry.message) continue;
-    if (children.length >= MAX_CHILDREN_PER_AGENT) break;
-    // The first user record is the agent's spawn prompt — the live stream
-    // never showed it as a child, so skip it to match the streaming view.
-    if (entry.type === "user" && isFirstUser) {
-      isFirstUser = false;
-      const content = entry.message?.content;
-      const hasToolResult = Array.isArray(content) && content.some((b: any) => b?.type === "tool_result");
-      if (!hasToolResult) continue;
-    }
-    const parsed = parseSessionMessage(entry);
-    for (const ev of parsed.events ?? []) {
-      // Keep single events from ballooning the history payload (agent files
-      // can carry multi-MB tool outputs the live stream also showed in full,
-      // but 24 agents × full outputs breaks mobile reloads).
-      if (ev.type === "tool_result" && typeof ev.output === "string" && ev.output.length > MAX_CHILD_OUTPUT_CHARS) {
-        ev.output = ev.output.slice(0, MAX_CHILD_OUTPUT_CHARS) + "\n… [truncated]";
-      }
-      children.push(ev);
-    }
+    return [];
   }
-  return children;
+  const parser = createAgentTranscriptLineParser();
+  const out: TimedChatEvent[] = [];
+  for (const line of text.split("\n")) out.push(...parser.feed(line));
+  return out;
+}
+
+/** Parse one agent transcript into a flat children event list (stream order). */
+export function parseAgentTranscript(filePath: string): ChatEvent[] {
+  return parseAgentTranscriptTimed(filePath).map((t) => t.ev);
 }
 
 /**
  * Attach subagent transcript events as children of their Agent/Task cards.
  * `sessionDir` is the per-session directory next to the main JSONL
- * (…/projects/<slug>/<sessionId>). Existing children are replaced — the disk
- * transcript is the complete record, while live-collected children may be a
- * partial overlap. Mutates messages in-place.
+ * (…/projects/<slug>/<sessionId>). A card's group — the agent it spawned plus
+ * any agents that one spawned in turn — is merged into one list ordered by
+ * record time, so a nested worker's steps read where they happened rather
+ * than after the parent agent's conclusion. Existing children are replaced —
+ * the disk transcripts are the complete record, while live-collected children
+ * may be a partial overlap. Mutates messages in-place.
  */
 export function mergeSubagentChildren(sessionDir: string, messages: MessageLike[]): void {
-  const index = indexAgentTranscripts(join(sessionDir, "subagents"));
-  if (index.size === 0) return;
+  const groups = groupSubagentsByCard(join(sessionDir, "subagents"));
+  if (groups.size === 0) return;
 
   for (const msg of messages) {
     for (const ev of msg.events ?? []) {
       if (ev.type !== "tool_use" || (ev.tool !== "Agent" && ev.tool !== "Task") || !ev.toolUseId) continue;
-      const transcript = index.get(ev.toolUseId);
-      if (!transcript) continue;
-      const children = parseAgentTranscript(transcript);
-      if (children.length > 0) ev.children = children;
+      const group = groups.get(ev.toolUseId);
+      if (!group) continue;
+      const timed: TimedChatEvent[] = [];
+      for (const agent of group) timed.push(...parseAgentTranscriptTimed(agent.transcriptPath));
+      // Stable sort: same-timestamp events keep transcript order.
+      timed.sort((a, b) => a.ts - b.ts);
+      if (timed.length > 0) ev.children = timed.map((t) => t.ev);
     }
   }
 }

package/src/services/subprocess-retention.ts

@@ -13,13 +13,36 @@
  */
 
 /**
- * Anthropic's default prompt-cache lifetime. A prefix not re-sent within this window has to
- * be written to the cache again, so a subprocess older than this is worth nothing.
+ * Anthropic's prompt-cache lifetime, per auth mode. From the SDK's own typings: "1 hour on a
+ * Claude subscription within its usage limits, 5 minutes on an API key, Bedrock, Vertex or
+ * Foundry."
  *
- * Named here rather than inlined because the retention window is *derived* from it — the two
- * were previously equal by coincidence, which read as if the teardown delay were arbitrary.
+ * Both are named here because the retention window is *derived* from whichever applies — the
+ * delay was previously equal to the TTL by coincidence, which read as arbitrary.
+ *
+ * Which one a session gets is not a constant: PPM supports settings `api_key` and a custom
+ * `base_url` as first-class options, and "within its usage limits" excludes exactly the
+ * accounts the rotation exists for. Holding a subprocess for an hour on an API-key install
+ * guards a cache that died at minute five, at ~350MB a session. The provider decides; these
+ * are the two values it picks between.
+ */
+export const SUBSCRIPTION_PROMPT_CACHE_TTL_MS = 60 * 60_000;
+export const API_KEY_PROMPT_CACHE_TTL_MS = 5 * 60_000;
+
+/** The longer of the two — what a timer that must outlast any cache window has to clear. */
+export const PROMPT_CACHE_TTL_MS = SUBSCRIPTION_PROMPT_CACHE_TTL_MS;
+
+/**
+ * What a provider that does not state a window gets.
+ *
+ * The short one, deliberately. `promptCacheTtlMs` is optional on the provider interface, so
+ * "no opinion" and "an hour" would otherwise be the same answer — and the providers without
+ * an opinion are exactly the ones with no Anthropic prompt cache to protect. Codex reaches
+ * this path today: it implements `hasStreamingSession` but not `promptCacheTtlMs`, so an
+ * hour here would hold ~350MB per abandoned session guarding a cache it never had. A
+ * provider that benefits from the long window says so.
  */
-export const PROMPT_CACHE_TTL_MS = 5 * 60_000;
+const UNDECLARED_PROMPT_CACHE_TTL_MS = API_KEY_PROMPT_CACHE_TTL_MS;
 
 /**
  * Milliseconds until a session's prompt cache lapses.
@@ -31,7 +54,7 @@ export const PROMPT_CACHE_TTL_MS = 5 * 60_000;
 export function cacheReleaseDelayMs(
   lastTurnEndedAt: number | undefined,
   now: number,
-  ttlMs: number = PROMPT_CACHE_TTL_MS,
+  ttlMs: number = UNDECLARED_PROMPT_CACHE_TTL_MS,
 ): number {
   // No completed turn means nothing has been cached, so there is nothing to protect.
   if (lastTurnEndedAt == null) return 0;

package/src/services/supervisor.ts

@@ -52,6 +52,9 @@ const TUNNEL_URL_REGEX = /https:\/\/(?!api\.)[a-z0-9-]+\.trycloudflare\.com/;
 const NAMED_TUNNEL_READY_REGEX = /Registered tunnel connection/;
 const UPGRADE_CHECK_INTERVAL_MS = 900_000;  // 15min
 const UPGRADE_SKIP_INITIAL_MS = 300_000;    // 5min delay before first check
+const DB_BACKUP_INTERVAL_MS = 3_600_000;    // 1h — the recovery-point target
+const DB_BACKUP_START_DELAY_MS = 30_000;    // let the server settle before the first snapshot
+const DB_BACKUP_STALE_WARN_MS = 21_600_000; // 6h — snapshots stopped happening
 const SELF_REPLACE_TIMEOUT_MS = 30_000;     // 30s to wait for new supervisor
 const EDGE_PROBE_INTERVAL_MS = 10_000;      // the public port is dark while the edge is down — check often
 const SERVER_PORT_MIRROR_TIMEOUT_MS = 30_000; // how long to wait for the server to publish its port
@@ -127,6 +130,7 @@ let healthTimer: ReturnType<typeof setInterval> | null = null;
 let tunnelProbeTimer: ReturnType<typeof setInterval> | null = null;
 let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 let upgradeCheckTimer: ReturnType<typeof setInterval> | null = null;
+let dbBackupTimer: ReturnType<typeof setInterval> | null = null;
 let upgradeDelayTimer: ReturnType<typeof setTimeout> | null = null;
 let cloudMonitorTimer: ReturnType<typeof setInterval> | null = null;
 let descendantSnapshotTimer: ReturnType<typeof setInterval> | null = null; // win32 only
@@ -936,6 +940,41 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   return retryTunnelAfterFailure(generation);
 }
 
+// ─── Config-database snapshots ─────────────────────────────────────────
+let dbBackupDelayTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Take one verified snapshot of the config database, then report whether
+ * snapshots are keeping up.
+ *
+ * Failures are logged and swallowed: a backup problem must never take the
+ * server down. The staleness warning exists because a silently-failing backup
+ * is worse than no backup — it is the state where recovery is believed to be
+ * available and is not.
+ */
+async function runDbBackupTick(reason: "hourly" | "start"): Promise<void> {
+  if (shuttingDown) return;
+  try {
+    const { backupDb } = await import("./db-backup/db-backup.service.ts");
+    const result = await backupDb(reason);
+    const mb = (result.bytes / 1_048_576).toFixed(1);
+    const prunedNote = result.pruned.length ? `, pruned ${result.pruned.length}` : "";
+    log("INFO", `DB snapshot (${reason}): ${result.path} ${mb}MB in ${result.ms}ms${prunedNote}`);
+  } catch (e: any) {
+    log("ERROR", `DB snapshot (${reason}) failed: ${e?.message ?? e}`);
+  }
+
+  try {
+    const { newestBackupAgeMs } = await import("./db-backup/db-backup.service.ts");
+    const age = await newestBackupAgeMs();
+    if (age === null) {
+      log("WARN", "DB snapshot: no backups exist yet — the database is currently unrecoverable");
+    } else if (age > DB_BACKUP_STALE_WARN_MS) {
+      log("WARN", `DB snapshot: newest backup is ${Math.round(age / 3_600_000)}h old — recovery point is degraded`);
+    }
+  } catch { /* staleness reporting is advisory only */ }
+}
+
 // ─── Health checks ─────────────────────────────────────────────────────
 function startServerHealthCheck() {
   healthTimer = setInterval(async () => {
@@ -1314,6 +1353,8 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (upgradeCheckTimer) clearInterval(upgradeCheckTimer);
       if (upgradeDelayTimer) clearTimeout(upgradeDelayTimer);
+      if (dbBackupTimer) clearInterval(dbBackupTimer);
+      if (dbBackupDelayTimer) clearTimeout(dbBackupDelayTimer);
       if (cloudMonitorTimer) clearInterval(cloudMonitorTimer);
       // Disconnect Cloud WS so new supervisor can reconnect cleanly
       try { const { disconnect } = await import("./cloud-ws.service.ts"); disconnect(); } catch {}
@@ -1398,6 +1439,8 @@ async function selfReplace(): Promise<{ success: boolean; error?: string }> {
           if (heartbeatTimer) clearInterval(heartbeatTimer);
           if (upgradeCheckTimer) clearInterval(upgradeCheckTimer);
           if (upgradeDelayTimer) clearTimeout(upgradeDelayTimer);
+          if (dbBackupTimer) clearInterval(dbBackupTimer);
+          if (dbBackupDelayTimer) clearTimeout(dbBackupDelayTimer);
           process.exit(0);
         }
       } catch {}
@@ -1680,6 +1723,8 @@ export function shutdown() {
   if (heartbeatTimer) clearInterval(heartbeatTimer);
   if (upgradeCheckTimer) clearInterval(upgradeCheckTimer);
   if (upgradeDelayTimer) clearTimeout(upgradeDelayTimer);
+  if (dbBackupTimer) clearInterval(dbBackupTimer);
+  if (dbBackupDelayTimer) clearTimeout(dbBackupDelayTimer);
   if (cloudMonitorTimer) clearInterval(cloudMonitorTimer);
   if (descendantSnapshotTimer) clearInterval(descendantSnapshotTimer);
 
@@ -1962,6 +2007,19 @@ export async function runSupervisor(opts: {
     }
   }, RESUME_TICK_MS);
 
+  // Snapshot the config database on a schedule. The supervisor is the only
+  // always-on process, so this is the one place a periodic snapshot survives
+  // both server restarts and crash-backoff windows.
+  //
+  // The start-up snapshot is not redundant with the hourly one: a machine that
+  // is only powered on for short sessions, or a supervisor that sat paused
+  // after exhausting its restart budget, would otherwise take no snapshot at
+  // all for as long as that lasted.
+  dbBackupDelayTimer = setTimeout(() => {
+    void runDbBackupTick("start");
+    dbBackupTimer = setInterval(() => void runDbBackupTick("hourly"), DB_BACKUP_INTERVAL_MS);
+  }, DB_BACKUP_START_DELAY_MS);
+
   // Start upgrade check timer (5min initial delay, then every 15min)
   upgradeDelayTimer = setTimeout(() => {
     checkAvailableVersion();