diff --git a/apps/ade-cli/pnpm-workspace.yaml b/apps/ade-cli/pnpm-workspace.yaml
index 9b5c7213c..738168dd3 100644
--- a/apps/ade-cli/pnpm-workspace.yaml
+++ b/apps/ade-cli/pnpm-workspace.yaml
@@ -1,5 +1,5 @@
 allowBuilds:
-  esbuild: set this to true or false
-  node-pty: set this to true or false
-  opencode-ai: set this to true or false
-  sqlite3: set this to true or false
+  esbuild: true
+  node-pty: true
+  opencode-ai: true
+  sqlite3: true
diff --git a/apps/desktop/src/main/main.ts b/apps/desktop/src/main/main.ts
index fb29e0dba..7cd4c770c 100644
--- a/apps/desktop/src/main/main.ts
+++ b/apps/desktop/src/main/main.ts
@@ -1749,6 +1749,7 @@ app.whenReady().then(async () => {
     currentVersion: app.getVersion(),
     globalStatePath,
     updaterCacheDir: app.isPackaged ? resolveAutoUpdaterCacheDir() : undefined,
+    autoCheckEnabled: app.isPackaged,
   });
 
   const initContextForProjectRoot = async ({
diff --git a/apps/desktop/src/main/services/appControl/appControlLaunchCommand.test.ts b/apps/desktop/src/main/services/appControl/appControlLaunchCommand.test.ts
new file mode 100644
index 000000000..5f5579a38
--- /dev/null
+++ b/apps/desktop/src/main/services/appControl/appControlLaunchCommand.test.ts
@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  commandForwardsAppControlDebug,
+  commandLooksLikeDirectElectronLaunch,
+  commandLooksLikePackageScriptLaunch,
+  insertDebugFlagsIntoDirectElectronCommand,
+  rewritePackageScriptElectronLaunch,
+} from "./appControlLaunchCommand";
+
+const DEBUG_FLAGS = ["--remote-debugging-port=9222"];
+
+describe("appControlLaunchCommand", () => {
+  it("detects direct Electron launches and injects debug flags after electron", () => {
+    expect(commandLooksLikeDirectElectronLaunch("FOO=bar npx electron .")).toBe(true);
+
+    expect(insertDebugFlagsIntoDirectElectronCommand("FOO=bar npx electron .", DEBUG_FLAGS))
+      .toBe("FOO=bar npx electron --remote-debugging-port=9222 .");
+  });
+
+  it("detects package script launches and rewrites direct Electron scripts", () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ade-app-control-launch-"));
+    try {
+      fs.writeFileSync(path.join(projectRoot, "package.json"), JSON.stringify({
+        scripts: {
+          dev: "electron .",
+        },
+      }), "utf8");
+
+      expect(commandLooksLikePackageScriptLaunch("npm run dev")).toBe(true);
+      expect(rewritePackageScriptElectronLaunch("npm run dev", DEBUG_FLAGS, projectRoot))
+        .toBe(`PATH=${path.join(projectRoot, "node_modules", ".bin")}:$PATH electron --remote-debugging-port=9222 .`);
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("does not rewrite scripts that already forward App Control flags", () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ade-app-control-launch-"));
+    try {
+      fs.writeFileSync(path.join(projectRoot, "package.json"), JSON.stringify({
+        scripts: {
+          dev: "electron . {ADE_APP_CONTROL_DEBUG_FLAGS}",
+        },
+      }), "utf8");
+
+      expect(commandForwardsAppControlDebug("electron . {ADE_APP_CONTROL_DEBUG_FLAGS}")).toBe(true);
+      expect(rewritePackageScriptElectronLaunch("npm run dev", DEBUG_FLAGS, projectRoot)).toBeNull();
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("resolves the last cd segment before reading package.json", () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ade-app-control-launch-"));
+    const appDir = path.join(projectRoot, "apps", "desktop");
+    try {
+      fs.mkdirSync(appDir, { recursive: true });
+      fs.writeFileSync(path.join(appDir, "package.json"), JSON.stringify({
+        scripts: {
+          dev: "electron .",
+        },
+      }), "utf8");
+
+      expect(rewritePackageScriptElectronLaunch("cd apps/desktop && npm run dev", DEBUG_FLAGS, projectRoot))
+        .toBe(`cd apps/desktop && PATH=${path.join(appDir, "node_modules", ".bin")}:$PATH electron --remote-debugging-port=9222 .`);
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/apps/desktop/src/main/services/appControl/appControlLaunchCommand.ts b/apps/desktop/src/main/services/appControl/appControlLaunchCommand.ts
new file mode 100644
index 000000000..efcd667ab
--- /dev/null
+++ b/apps/desktop/src/main/services/appControl/appControlLaunchCommand.ts
@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export function commandForwardsAppControlDebug(command: string): boolean {
+  return /\{ADE_APP_CONTROL_DEBUG_FLAGS\}|\bADE_APP_CONTROL_(?:DEBUG_FLAGS|CDP_PORT|REMOTE_DEBUGGING_PORT)\b|--remote-debugging-port\b/.test(command);
+}
+
+export function commandLooksLikePackageScriptLaunch(command: string): boolean {
+  return /(?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?[A-Za-z0-9:_./-]+)\s*$/.test(command.trim());
+}
+
+export function commandLooksLikeDirectElectronLaunch(command: string): boolean {
+  return /(?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:npx\s+)?electron(?:\s+[^;&|]*)?\s*$/.test(command.trim());
+}
+
+export function unquoteShellValue(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+    || (trimmed.startsWith("\"") && trimmed.endsWith("\""))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+export function insertDebugFlagsIntoDirectElectronCommand(command: string, debugFlags: string[]): string {
+  const flags = debugFlags.map(shellQuote).join(" ");
+  return command.replace(
+    /((?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:npx\s+)?electron)(?=\s|$)/,
+    `$1 ${flags}`,
+  );
+}
+
+function prependEnvToShellSegments(script: string, envPrefix: string): string {
+  const trimmedEnv = envPrefix.trim();
+  if (!trimmedEnv) return script;
+  return script
+    .split(/(\s*&&\s*)/)
+    .map((segment) => {
+      if (/^\s*&&\s*$/.test(segment)) return segment;
+      const trimmed = segment.trim();
+      return trimmed ? `${trimmedEnv} ${trimmed}` : segment;
+    })
+    .join("");
+}
+
+export function rewritePackageScriptElectronLaunch(command: string, debugFlags: string[], fallbackCwd: string): string | null {
+  const match = command.trim().match(/^(?<prefix>.*?)(?<env>(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*)(?<manager>npm|pnpm|yarn|bun)\s+(?:run\s+)?(?<script>[A-Za-z0-9:_./-]+)\s*$/);
+  const groups = match?.groups;
+  if (!groups) return null;
+  const prefix = groups.prefix ?? "";
+  const envPrefix = groups.env?.trim() ?? "";
+  const scriptName = groups.script;
+  if (!scriptName) return null;
+
+  let packageDir = fallbackCwd;
+  const cdMatches = Array.from(prefix.matchAll(/(?:^|[;&|]\s*)cd\s+((?:"[^"]+"|'[^']+'|[^\s;&|]+))\s*&&/g));
+  const lastCd = cdMatches.at(-1);
+  if (lastCd?.[1]) packageDir = path.resolve(fallbackCwd, unquoteShellValue(lastCd[1]));
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8")) as {
+      scripts?: Record<string, unknown>;
+    };
+    const script = packageJson.scripts?.[scriptName];
+    if (typeof script !== "string") return null;
+    if (commandForwardsAppControlDebug(script) || !/\belectron(?:\s|$)/.test(script)) return null;
+    const rewrittenScript = insertDebugFlagsIntoDirectElectronCommand(script, debugFlags);
+    if (rewrittenScript === script) return null;
+    const packageBinPath = path.join(packageDir, "node_modules", ".bin");
+    const expandedEnvPrefix = [`PATH=${shellQuote(packageBinPath)}:$PATH`, envPrefix].filter(Boolean).join(" ");
+    return `${prefix}${prependEnvToShellSegments(rewrittenScript, expandedEnvPrefix)}`;
+  } catch {
+    return null;
+  }
+}
diff --git a/apps/desktop/src/main/services/appControl/appControlService.ts b/apps/desktop/src/main/services/appControl/appControlService.ts
index a528b8459..18091549f 100644
--- a/apps/desktop/src/main/services/appControl/appControlService.ts
+++ b/apps/desktop/src/main/services/appControl/appControlService.ts
@@ -30,6 +30,16 @@ import type {
 } from "../../../shared/types";
 import type { Logger } from "../logging/logger";
 import type { createPtyService } from "../pty/ptyService";
+import { imageDimensions } from "../shared/imageDimensions";
+import {
+  commandForwardsAppControlDebug,
+  commandLooksLikeDirectElectronLaunch,
+  commandLooksLikePackageScriptLaunch,
+  insertDebugFlagsIntoDirectElectronCommand,
+  rewritePackageScriptElectronLaunch,
+  shellQuote,
+  unquoteShellValue,
+} from "./appControlLaunchCommand";
 
 const CDP_POLL_MS = 500;
 const CDP_HEALTH_POLL_MS = 2_000;
@@ -159,86 +169,6 @@ function roundFrame(frame: AppControlFrame): AppControlFrame {
   };
 }
 
-function shellQuote(value: string): string {
-  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-
-function commandForwardsAppControlDebug(command: string): boolean {
-  return /\{ADE_APP_CONTROL_DEBUG_FLAGS\}|\bADE_APP_CONTROL_(?:DEBUG_FLAGS|CDP_PORT|REMOTE_DEBUGGING_PORT)\b|--remote-debugging-port\b/.test(command);
-}
-
-function commandLooksLikePackageScriptLaunch(command: string): boolean {
-  return /(?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?[A-Za-z0-9:_./-]+)\s*$/.test(command.trim());
-}
-
-function commandLooksLikeDirectElectronLaunch(command: string): boolean {
-  return /(?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:npx\s+)?electron(?:\s+[^;&|]*)?\s*$/.test(command.trim());
-}
-
-function unquoteShellValue(value: string): string {
-  const trimmed = value.trim();
-  if (
-    (trimmed.startsWith("'") && trimmed.endsWith("'"))
-    || (trimmed.startsWith("\"") && trimmed.endsWith("\""))
-  ) {
-    return trimmed.slice(1, -1);
-  }
-  return trimmed;
-}
-
-function insertDebugFlagsIntoDirectElectronCommand(command: string, debugFlags: string[]): string {
-  const flags = debugFlags.map(shellQuote).join(" ");
-  return command.replace(
-    /((?:^|[;&|]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*(?:npx\s+)?electron)(?=\s|$)/,
-    `$1 ${flags}`,
-  );
-}
-
-function prependEnvToShellSegments(script: string, envPrefix: string): string {
-  const trimmedEnv = envPrefix.trim();
-  if (!trimmedEnv) return script;
-  return script
-    .split(/(\s*&&\s*)/)
-    .map((segment) => {
-      if (/^\s*&&\s*$/.test(segment)) return segment;
-      const trimmed = segment.trim();
-      return trimmed ? `${trimmedEnv} ${trimmed}` : segment;
-    })
-    .join("");
-}
-
-function rewritePackageScriptElectronLaunch(command: string, debugFlags: string[], fallbackCwd: string): string | null {
-  const match = command.trim().match(/^(?<prefix>.*?)(?<env>(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s;&|]+)\s+)*)(?<manager>npm|pnpm|yarn|bun)\s+(?:run\s+)?(?<script>[A-Za-z0-9:_./-]+)\s*$/);
-  const groups = match?.groups;
-  if (!groups) return null;
-  const prefix = groups.prefix ?? "";
-  const envPrefix = groups.env?.trim() ?? "";
-  const scriptName = groups.script;
-  if (!scriptName) return null;
-
-  let packageDir = fallbackCwd;
-  const cdMatches = Array.from(prefix.matchAll(/(?:^|[;&|]\s*)cd\s+((?:"[^"]+"|'[^']+'|[^\s;&|]+))\s*&&/g));
-  const lastCd = cdMatches.at(-1);
-  if (lastCd?.[1]) packageDir = path.resolve(fallbackCwd, unquoteShellValue(lastCd[1]));
-
-  try {
-    const packageJson = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf8")) as {
-      scripts?: Record<string, unknown>;
-    };
-    const script = packageJson.scripts?.[scriptName];
-    if (typeof script !== "string") return null;
-    if (commandForwardsAppControlDebug(script) || !/\belectron(?:\s|$)/.test(script)) return null;
-    const rewrittenScript = insertDebugFlagsIntoDirectElectronCommand(script, debugFlags);
-    if (rewrittenScript === script) return null;
-    const packageBinPath = path.join(packageDir, "node_modules", ".bin");
-    const expandedEnvPrefix = [`PATH=${shellQuote(packageBinPath)}:$PATH`, envPrefix].filter(Boolean).join(" ");
-    return `${prefix}${prependEnvToShellSegments(rewrittenScript, expandedEnvPrefix)}`;
-  } catch {
-    return null;
-  }
-}
-
 function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -449,48 +379,6 @@ class CdpClient {
   }
 }
 
-function pngDimensions(buffer: Buffer): { width: number; height: number } | null {
-  if (buffer.length < 24) return null;
-  if (buffer.toString("ascii", 1, 4) !== "PNG") return null;
-  return {
-    width: buffer.readUInt32BE(16),
-    height: buffer.readUInt32BE(20),
-  };
-}
-
-function jpegDimensions(buffer: Buffer): { width: number; height: number } | null {
-  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
-  let offset = 2;
-  while (offset + 9 < buffer.length) {
-    if (buffer[offset] !== 0xff) {
-      offset += 1;
-      continue;
-    }
-    const marker = buffer[offset + 1];
-    offset += 2;
-    if (marker === 0xd9 || marker === 0xda) break;
-    if (offset + 2 > buffer.length) return null;
-    const segmentLength = buffer.readUInt16BE(offset);
-    if (segmentLength < 2 || offset + segmentLength > buffer.length) return null;
-    const isStartOfFrame =
-      marker >= 0xc0
-      && marker <= 0xcf
-      && ![0xc4, 0xc8, 0xcc].includes(marker);
-    if (isStartOfFrame && segmentLength >= 7) {
-      return {
-        height: buffer.readUInt16BE(offset + 3),
-        width: buffer.readUInt16BE(offset + 5),
-      };
-    }
-    offset += segmentLength;
-  }
-  return null;
-}
-
-function imageDimensions(buffer: Buffer): { width: number; height: number } | null {
-  return pngDimensions(buffer) ?? jpegDimensions(buffer);
-}
-
 function cdpDomSnapshotScript(maxElements: number): string {
   return `(() => {
     const roleFor = (el) => {
diff --git a/apps/desktop/src/main/services/automations/automationService.test.ts b/apps/desktop/src/main/services/automations/automationService.test.ts
index 8440a0b94..6114348bc 100644
--- a/apps/desktop/src/main/services/automations/automationService.test.ts
+++ b/apps/desktop/src/main/services/automations/automationService.test.ts
@@ -1189,6 +1189,9 @@ describe("automationService integration", () => {
       getLaneWorktreePath: () => projectRoot,
       getLaneBaseAndBranch: () => ({ baseRef: "main", branchRef: "main", worktreePath: projectRoot })
     } as any;
+    const budgetCapService = {
+      checkBudget: vi.fn(() => ({ allowed: false, reason: "Budget exceeded" })),
+    };
 
     const service = createAutomationService({
       db: db as any,
@@ -1200,13 +1203,17 @@ describe("automationService integration", () => {
       agentChatService: {
         createSession,
       } as any,
-      budgetCapService: {
-        checkBudget: vi.fn(() => ({ allowed: false, reason: "Budget exceeded" })),
-      } as any,
+      budgetCapService: budgetCapService as any,
     });
 
     try {
       await expect(service.triggerManually({ id: "agent-budget" })).rejects.toThrow("Budget exceeded");
+      expect(budgetCapService.checkBudget).toHaveBeenCalledWith(
+        "automation-rule",
+        "agent-budget",
+        expect.any(String),
+        { runScopeId: expect.any(String) },
+      );
       expect(createSession).not.toHaveBeenCalled();
     } finally {
       fs.rmSync(projectRoot, { recursive: true, force: true });
@@ -1502,7 +1509,9 @@ describe("automationService integration", () => {
 
     try {
       await expect(service.triggerManually({ id: "agent-budget-provider" })).rejects.toThrow("Budget exceeded");
-      expect(checkBudget).toHaveBeenCalledWith("automation-rule", "agent-budget-provider", "codex");
+      expect(checkBudget).toHaveBeenCalledWith("automation-rule", "agent-budget-provider", "codex", {
+        runScopeId: expect.any(String),
+      });
       expect(createSession).not.toHaveBeenCalled();
     } finally {
       fs.rmSync(projectRoot, { recursive: true, force: true });
diff --git a/apps/desktop/src/main/services/automations/automationService.ts b/apps/desktop/src/main/services/automations/automationService.ts
index aa75c28d5..d2fe903bb 100644
--- a/apps/desktop/src/main/services/automations/automationService.ts
+++ b/apps/desktop/src/main/services/automations/automationService.ts
@@ -2097,15 +2097,6 @@ export function createAutomationService({
 
     const { modelId, modelDescriptor, providerGroup, budgetProvider } = resolveAutomationModelDescriptor(args.rule);
     const resolvedChat = resolveChatProviderForDescriptor(modelDescriptor);
-    const budgetCheck = budgetCapServiceRef?.checkBudget(
-      AUTOMATION_SCOPE as Parameters<NonNullable<typeof budgetCapServiceRef>["checkBudget"]>[0],
-      args.rule.id,
-      budgetProvider,
-    );
-    if (budgetCheck && !budgetCheck.allowed) {
-      throw new Error(budgetCheck.reason ?? "Budget cap blocked automation run.");
-    }
-
     const confidence = computeConfidence(args.rule);
     const existingRunRow = args.existingRunId ? loadRunRow(args.existingRunId) : null;
     const run = existingRunRow
@@ -2118,6 +2109,20 @@ export function createAutomationService({
           summary: args.rule.prompt?.trim() || `${args.rule.name} agent session dispatched`,
           ingressEventId: args.trigger.ingressEventId ?? null,
         });
+    // New runs start at zero; the `usd-per-run` preflight catches resumed runs
+    // with existing usage while in-flight enforcement uses records for this run id.
+    const budgetCheck = budgetCapServiceRef?.checkBudget(
+      AUTOMATION_SCOPE as Parameters<NonNullable<typeof budgetCapServiceRef>["checkBudget"]>[0],
+      args.rule.id,
+      budgetProvider,
+      { runScopeId: run.id },
+    );
+    if (budgetCheck && !budgetCheck.allowed) {
+      const message = budgetCheck.reason ?? "Budget cap blocked automation run.";
+      updateRun(run.id, { ended_at: nowIso(), status: "failed", error_message: message });
+      emit({ type: "runs-updated", automationId: args.rule.id, runId: run.id });
+      throw new Error(message);
+    }
 
     let laneId: string | null;
     try {
diff --git a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.test.ts b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.test.ts
new file mode 100644
index 000000000..6839cb484
--- /dev/null
+++ b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { isAllowedNavigationUrl, normalizeBrowserUrl } from "./builtInBrowserNavigation";
+
+describe("builtInBrowserNavigation", () => {
+  it("normalizes plain domains to https URLs", () => {
+    expect(normalizeBrowserUrl("example.com/path")).toBe("https://example.com/path");
+    expect(normalizeBrowserUrl("example.com:3000/path")).toBe("https://example.com:3000/path");
+  });
+
+  it("normalizes localhost-like URLs to http", () => {
+    expect(normalizeBrowserUrl("localhost:5173/work")).toBe("http://localhost:5173/work");
+    expect(normalizeBrowserUrl("127.0.0.1:3000")).toBe("http://127.0.0.1:3000/");
+  });
+
+  it("allows only http, https, and about:blank navigation", () => {
+    expect(isAllowedNavigationUrl("https://example.com")).toBe(true);
+    expect(isAllowedNavigationUrl("http://localhost:5173")).toBe(true);
+    expect(isAllowedNavigationUrl("about:blank")).toBe(true);
+    expect(isAllowedNavigationUrl("file:///tmp/test.html")).toBe(false);
+    expect(isAllowedNavigationUrl("about:config")).toBe(false);
+  });
+
+  it("rejects unsupported normalized protocols", () => {
+    expect(() => normalizeBrowserUrl("file:///tmp/test.html")).toThrow("Unsupported browser URL protocol");
+    expect(() => normalizeBrowserUrl("about:config")).toThrow("Only about:blank");
+  });
+});
diff --git a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.ts b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.ts
new file mode 100644
index 000000000..aa50b9fdb
--- /dev/null
+++ b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserNavigation.ts
@@ -0,0 +1,35 @@
+export function normalizeBrowserUrl(rawUrl: string): string {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) throw new Error("Browser URL is required.");
+
+  const localhostLike = /^(localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::|\/|$)/i.test(trimmed);
+  const hasScheme = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(trimmed) || /^about:/i.test(trimmed);
+  let candidate: string;
+  if (localhostLike) {
+    candidate = `http://${trimmed}`;
+  } else if (hasScheme) {
+    candidate = trimmed;
+  } else {
+    candidate = `https://${trimmed}`;
+  }
+
+  const parsed = new URL(candidate);
+  if (parsed.protocol === "about:") {
+    if (parsed.href === "about:blank") return parsed.href;
+    throw new Error("Only about:blank browser navigation is supported.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Unsupported browser URL protocol: ${parsed.protocol}`);
+  }
+  return parsed.href;
+}
+
+export function isAllowedNavigationUrl(rawUrl: string): boolean {
+  try {
+    const parsed = new URL(rawUrl);
+    if (parsed.protocol === "about:") return parsed.href.startsWith("about:blank");
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
diff --git a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.test.ts b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.test.ts
new file mode 100644
index 000000000..94006515e
--- /dev/null
+++ b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import {
+  shouldAllowGoogleAuthPermissionCheck,
+  shouldAllowGoogleAuthPermissionRequest,
+} from "./builtInBrowserPermissions";
+
+describe("builtInBrowserPermissions", () => {
+  it("allows Google auth storage permission checks from known Google account surfaces", () => {
+    expect(shouldAllowGoogleAuthPermissionCheck("storage-access", "https://accounts.google.com", {
+      requestingUrl: "https://example.com",
+      embeddingOrigin: "",
+      securityOrigin: "",
+    } as Electron.PermissionCheckHandlerHandlerDetails)).toBe(true);
+    expect(shouldAllowGoogleAuthPermissionCheck("usb", "https://example.com", {
+      requestingUrl: "https://accounts.google.com/signin",
+      embeddingOrigin: "",
+      securityOrigin: "",
+    } as Electron.PermissionCheckHandlerHandlerDetails)).toBe(true);
+  });
+
+  it("denies unsupported permission checks and non-Google origins", () => {
+    expect(shouldAllowGoogleAuthPermissionCheck("geolocation", "https://accounts.google.com", {
+      requestingUrl: "https://accounts.google.com",
+      embeddingOrigin: "",
+      securityOrigin: "",
+    } as Electron.PermissionCheckHandlerHandlerDetails)).toBe(false);
+    expect(shouldAllowGoogleAuthPermissionCheck("storage-access", "https://example.com", {
+      requestingUrl: "https://example.com",
+      embeddingOrigin: "",
+      securityOrigin: "",
+    } as Electron.PermissionCheckHandlerHandlerDetails)).toBe(false);
+  });
+
+  it("allows only Google auth storage permission requests", () => {
+    expect(shouldAllowGoogleAuthPermissionRequest("storage-access", {
+      requestingUrl: "https://accounts.google.com/signin",
+    })).toBe(true);
+    expect(shouldAllowGoogleAuthPermissionRequest("notifications", {
+      requestingUrl: "https://accounts.google.com/signin",
+    })).toBe(false);
+    expect(shouldAllowGoogleAuthPermissionRequest("storage-access", {
+      requestingUrl: "https://example.com",
+    })).toBe(false);
+  });
+});
diff --git a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.ts b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.ts
new file mode 100644
index 000000000..2132832c4
--- /dev/null
+++ b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserPermissions.ts
@@ -0,0 +1,56 @@
+import { isRecord } from "../shared/utils";
+
+const GOOGLE_AUTH_PERMISSION_CHECK_ALLOWLIST = new Set([
+  "hid",
+  "serial",
+  "storage-access",
+  "top-level-storage-access",
+  "usb",
+]);
+const GOOGLE_AUTH_PERMISSION_REQUEST_ALLOWLIST = new Set([
+  "storage-access",
+  "top-level-storage-access",
+]);
+
+export function shouldAllowGoogleAuthPermissionCheck(
+  permission: string,
+  requestingOrigin: string,
+  details: Electron.PermissionCheckHandlerHandlerDetails,
+): boolean {
+  if (!GOOGLE_AUTH_PERMISSION_CHECK_ALLOWLIST.has(permission)) return false;
+  return (
+    isGoogleAccountsSurface(requestingOrigin)
+    || isGoogleAccountsSurface(details.requestingUrl)
+    || isGoogleAccountsSurface(details.embeddingOrigin)
+    || isGoogleAccountsSurface(details.securityOrigin)
+  );
+}
+
+export function shouldAllowGoogleAuthPermissionRequest(permission: string, details: unknown): boolean {
+  if (!GOOGLE_AUTH_PERMISSION_REQUEST_ALLOWLIST.has(permission)) return false;
+  if (!isRecord(details)) return false;
+  return (
+    isGoogleAccountsSurface(details.requestingUrl)
+    || isGoogleAccountsSurface(details.requestingOrigin)
+  );
+}
+
+function isGoogleAccountsSurface(value: unknown): boolean {
+  const text = stringOrNull(value);
+  if (!text) return false;
+  try {
+    const parsed = new URL(text);
+    return parsed.protocol === "https:" && (
+      parsed.hostname === "accounts.google.com"
+      || parsed.hostname.endsWith(".accounts.google.com")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function stringOrNull(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length ? trimmed : null;
+}
diff --git a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts
index 24f5f79b5..e1d4a7292 100644
--- a/apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts
+++ b/apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts
@@ -19,24 +19,19 @@ import type {
   BuiltInBrowserTabArgs,
 } from "../../../shared/types";
 import type { Logger } from "../logging/logger";
+import { isRecord } from "../shared/utils";
 import { BUILT_IN_BROWSER_PARTITION } from "./builtInBrowserConstants";
+import { isAllowedNavigationUrl, normalizeBrowserUrl } from "./builtInBrowserNavigation";
+import {
+  shouldAllowGoogleAuthPermissionCheck,
+  shouldAllowGoogleAuthPermissionRequest,
+} from "./builtInBrowserPermissions";
 
 const BROWSER_PARTITION = BUILT_IN_BROWSER_PARTITION;
 const SCREENSHOT_TIMEOUT_MS = 3_000;
 const ELEMENT_SCREENSHOT_TIMEOUT_MS = 2_000;
 const DEBUGGER_TIMEOUT_MS = 3_000;
 const MAX_BROWSER_TABS = 10;
-const GOOGLE_AUTH_PERMISSION_CHECK_ALLOWLIST = new Set([
-  "hid",
-  "serial",
-  "storage-access",
-  "top-level-storage-access",
-  "usb",
-]);
-const GOOGLE_AUTH_PERMISSION_REQUEST_ALLOWLIST = new Set([
-  "storage-access",
-  "top-level-storage-access",
-]);
 
 type DebuggerMessageListener = (
   event: Electron.Event,
@@ -1292,52 +1287,11 @@ function createBuiltInBrowserWindowService(args: {
 
 export type BuiltInBrowserService = ReturnType<typeof createBuiltInBrowserService>;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function emptyToNull(value: string): string | null {
   const trimmed = value.trim();
   return trimmed.length ? trimmed : null;
 }
 
-function shouldAllowGoogleAuthPermissionCheck(
-  permission: string,
-  requestingOrigin: string,
-  details: Electron.PermissionCheckHandlerHandlerDetails,
-): boolean {
-  if (!GOOGLE_AUTH_PERMISSION_CHECK_ALLOWLIST.has(permission)) return false;
-  return (
-    isGoogleAccountsSurface(requestingOrigin)
-    || isGoogleAccountsSurface(details.requestingUrl)
-    || isGoogleAccountsSurface(details.embeddingOrigin)
-    || isGoogleAccountsSurface(details.securityOrigin)
-  );
-}
-
-function shouldAllowGoogleAuthPermissionRequest(permission: string, details: unknown): boolean {
-  if (!GOOGLE_AUTH_PERMISSION_REQUEST_ALLOWLIST.has(permission)) return false;
-  if (!isRecord(details)) return false;
-  return (
-    isGoogleAccountsSurface(details.requestingUrl)
-    || isGoogleAccountsSurface(details.requestingOrigin)
-  );
-}
-
-function isGoogleAccountsSurface(value: unknown): boolean {
-  const text = stringOrNull(value);
-  if (!text) return false;
-  try {
-    const parsed = new URL(text);
-    return parsed.protocol === "https:" && (
-      parsed.hostname === "accounts.google.com"
-      || parsed.hostname.endsWith(".accounts.google.com")
-    );
-  } catch {
-    return false;
-  }
-}
-
 function tabStatus(tab: BrowserTabState): BuiltInBrowserTab {
   const wc = tab.webContents;
   return {
@@ -1355,42 +1309,6 @@ function normalizeDimension(value: number): number {
   return Math.max(0, Math.round(value));
 }
 
-function normalizeBrowserUrl(rawUrl: string): string {
-  const trimmed = rawUrl.trim();
-  if (!trimmed) throw new Error("Browser URL is required.");
-
-  const localhostLike = /^(localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::|\/|$)/i.test(trimmed);
-  const hasScheme = /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(trimmed);
-  let candidate: string;
-  if (localhostLike) {
-    candidate = `http://${trimmed}`;
-  } else if (hasScheme) {
-    candidate = trimmed;
-  } else {
-    candidate = `https://${trimmed}`;
-  }
-
-  const parsed = new URL(candidate);
-  if (parsed.protocol === "about:") {
-    if (parsed.href === "about:blank") return parsed.href;
-    throw new Error("Only about:blank browser navigation is supported.");
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`Unsupported browser URL protocol: ${parsed.protocol}`);
-  }
-  return parsed.href;
-}
-
-function isAllowedNavigationUrl(rawUrl: string): boolean {
-  try {
-    const parsed = new URL(rawUrl);
-    if (parsed.protocol === "about:") return parsed.href.startsWith("about:blank");
-    return parsed.protocol === "http:" || parsed.protocol === "https:";
-  } catch {
-    return false;
-  }
-}
-
 function toElectronRect(frame: BuiltInBrowserFrame): Electron.Rectangle {
   return {
     x: Math.max(0, Math.round(frame.x)),
diff --git a/apps/desktop/src/main/services/ios/iosSimulatorService.ts b/apps/desktop/src/main/services/ios/iosSimulatorService.ts
index a6a1a2cdd..d8ce1c5aa 100644
--- a/apps/desktop/src/main/services/ios/iosSimulatorService.ts
+++ b/apps/desktop/src/main/services/ios/iosSimulatorService.ts
@@ -47,6 +47,8 @@ import type {
 import { IOS_SIMULATOR_OWNED_BY_OTHER_SESSION_CODE } from "../../../shared/types/iosSimulator";
 import { commandExists } from "../ai/utils";
 import type { Logger } from "../logging/logger";
+import { pngDimensions } from "../shared/imageDimensions";
+import { isRecord } from "../shared/utils";
 
 const execFile = promisify(execFileCallback);
 
@@ -1081,15 +1083,6 @@ async function waitForTcpPort(host: string, port: number, timeoutMs: number): Pr
   throw new Error(`Timed out waiting for ${host}:${port}.`);
 }
 
-function pngDimensions(buffer: Buffer): { width: number | null; height: number | null } {
-  if (buffer.length < 24) return { width: null, height: null };
-  if (buffer.toString("ascii", 1, 4) !== "PNG") return { width: null, height: null };
-  return {
-    width: buffer.readUInt32BE(16),
-    height: buffer.readUInt32BE(20),
-  };
-}
-
 function normalizeLaunchMode(mode: unknown): "snapshot" | "live" {
   if (mode == null) return "snapshot";
   if (mode === "snapshot" || mode === "live") return mode;
@@ -1144,10 +1137,6 @@ function normalizeFrame(value: Partial<IosInspectableElement["frame"]> | undefin
   return { x, y, width, height };
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
 function readString(record: Record<string, unknown>, keys: string[]): string | null {
   for (const key of keys) {
     const value = record[key];
@@ -2536,7 +2525,7 @@ export function createIosSimulatorService(args: CreateIosSimulatorServiceArgs) {
         };
       }
       const buffer = await fs.promises.readFile(previewSnapshotPath);
-      const dimensions = pngDimensions(buffer);
+      const dimensions = pngDimensions(buffer) ?? { width: null, height: null };
       return {
         ok: true,
         target,
@@ -2931,7 +2920,7 @@ export function createIosSimulatorService(args: CreateIosSimulatorServiceArgs) {
     try {
       await run("xcrun", ["simctl", "io", device.udid, "screenshot", "--type=png", tmpPath], { timeoutMs: 30_000 });
       const buffer = await fs.promises.readFile(tmpPath);
-      const dimensions = pngDimensions(buffer);
+      const dimensions = pngDimensions(buffer) ?? { width: null, height: null };
       return {
         deviceUdid: device.udid,
         dataUrl: `data:image/png;base64,${buffer.toString("base64")}`,
diff --git a/apps/desktop/src/main/services/ipc/registerIpc.ts b/apps/desktop/src/main/services/ipc/registerIpc.ts
index d4e642917..932d1f0ee 100644
--- a/apps/desktop/src/main/services/ipc/registerIpc.ts
+++ b/apps/desktop/src/main/services/ipc/registerIpc.ts
@@ -500,6 +500,7 @@ import type {
   GetAdeUsageStatsArgs,
   UsageSnapshot,
   BudgetCheckResult,
+  BudgetCheckArgs,
   BudgetCapScope,
   BudgetCapProvider,
   BudgetCapConfig,
@@ -4581,13 +4582,15 @@ export function registerIpc({
     IPC.usageCheckBudget,
     async (
       _event,
-      arg: { scope: BudgetCapScope; scopeId?: string; provider: BudgetCapProvider }
+      arg: BudgetCheckArgs
     ): Promise<BudgetCheckResult> => {
       const ctx = getCtx();
       if (!ctx.budgetCapService) {
         return { allowed: true, warnings: [] };
       }
-      return ctx.budgetCapService.checkBudget(arg.scope, arg.scopeId ?? "all", arg.provider);
+      return ctx.budgetCapService.checkBudget(arg.scope, arg.scopeId ?? "all", arg.provider, {
+        runScopeId: arg.runScopeId,
+      });
     }
   );
 
diff --git a/apps/desktop/src/main/services/macosVm/macosVmRecovery.ts b/apps/desktop/src/main/services/macosVm/macosVmRecovery.ts
index 4fb98f14c..9da3e407f 100644
--- a/apps/desktop/src/main/services/macosVm/macosVmRecovery.ts
+++ b/apps/desktop/src/main/services/macosVm/macosVmRecovery.ts
@@ -66,17 +66,22 @@ function writeRecords(storePath: string, records: MacosVmRecord[]): void {
   writeJsonFile(storePath, { version: 1, records });
 }
 
-function vncCredentialKey(laneId: string, vmName: string): string {
-  return `${laneId}:${vmName}`;
+function vncCredentialKeys(laneId: string, vmName: string): string[] {
+  return [JSON.stringify([laneId, vmName]), `${laneId}:${vmName}`];
 }
 
 function clearVncCredential(vncStorePath: string, record: MacosVmRecord): void {
   const parsed = readJsonFile(vncStorePath);
   if (!isRecord(parsed) || !isRecord(parsed.credentials)) return;
-  const key = vncCredentialKey(record.laneId, record.name);
-  if (!Object.prototype.hasOwnProperty.call(parsed.credentials, key)) return;
-  delete parsed.credentials[key];
-  writeJsonFile(vncStorePath, { ...parsed, version: 1, credentials: parsed.credentials }, 0o600);
+  const credentials = parsed.credentials;
+  const keys = vncCredentialKeys(record.laneId, record.name);
+  const removed = keys.some((key) => {
+    if (!Object.prototype.hasOwnProperty.call(credentials, key)) return false;
+    delete credentials[key];
+    return true;
+  });
+  if (!removed) return;
+  writeJsonFile(vncStorePath, { ...parsed, version: 1, credentials }, 0o600);
 }
 
 function clearGlobalLease(leasePath: string, args: MacosVmDeleteArgs, record: MacosVmRecord | null): boolean {
diff --git a/apps/desktop/src/main/services/macosVm/macosVmService.ts b/apps/desktop/src/main/services/macosVm/macosVmService.ts
index 34c1ec6e4..c1edadbe9 100644
--- a/apps/desktop/src/main/services/macosVm/macosVmService.ts
+++ b/apps/desktop/src/main/services/macosVm/macosVmService.ts
@@ -65,6 +65,17 @@ import {
   type BootstrapRunner,
   type RuntimeBootstrapPhase,
 } from "./runtimeBootstrap";
+import {
+  generateVncPassword,
+  readGlobalLeaseFile,
+  readStoreFile,
+  readVncCredentialStore,
+  vncCredentialKey,
+  writeGlobalLeaseFile,
+  writeStoreFile,
+  writeVncCredentialStore,
+} from "./macosVmStores";
+import { isRecord } from "../shared/utils";
 
 const APPLE_VIRTUALIZATION_DOCS = "https://developer.apple.com/documentation/virtualization";
 const APPLE_SHARED_DIRECTORIES_DOCS = "https://developer.apple.com/documentation/virtualization/vzvirtiofilesystemdeviceconfiguration";
@@ -192,26 +203,6 @@ type CreateMacosVmServiceArgs = {
     | null;
 };
 
-type VmStoreFile = {
-  version: 1;
-  records: MacosVmRecord[];
-};
-
-type VmGlobalLeaseFile = {
-  version: 1;
-  lease: MacosVmGlobalLease | null;
-};
-
-type VncCredentialStoreFile = {
-  version: 1;
-  credentials: Record<string, {
-    laneId: string;
-    vmName: string;
-    password: string;
-    updatedAt: string;
-  }>;
-};
-
 type ExternalVmInfo = {
   name: string;
   state: MacosVmLifecycleState;
@@ -230,10 +221,6 @@ function delay(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function normalizeLifecycleState(value: unknown): MacosVmLifecycleState {
   const normalized = typeof value === "string" ? value.trim().toLowerCase().replace(/[\s-]+/g, "_") : "";
   if (normalized === "created" || normalized === "not_created") return "not_created";
@@ -622,90 +609,6 @@ function guestReadinessForRecord(
   };
 }
 
-function readStoreFile(storePath: string): VmStoreFile {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VmStoreFile>;
-    const records = Array.isArray(parsed.records)
-      ? parsed.records.filter((record): record is MacosVmRecord => isRecord(record) && typeof record.id === "string")
-      : [];
-    return { version: 1, records };
-  } catch {
-    return { version: 1, records: [] };
-  }
-}
-
-function writeStoreFile(storePath: string, store: VmStoreFile): void {
-  fs.mkdirSync(path.dirname(storePath), { recursive: true });
-  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
-  fs.renameSync(tmpPath, storePath);
-}
-
-function parseGlobalLease(value: unknown): MacosVmGlobalLease | null {
-  if (!isRecord(value)) return null;
-  const projectRoot = asString(value.projectRoot);
-  const laneId = asString(value.laneId);
-  const vmId = asString(value.vmId);
-  const vmName = asString(value.vmName);
-  if (!projectRoot || !laneId || !vmId || !vmName) return null;
-  return {
-    projectRoot,
-    laneId,
-    laneName: asString(value.laneName) ?? laneId,
-    vmId,
-    vmName,
-    updatedAt: asString(value.updatedAt) ?? nowIso(),
-  };
-}
-
-function readGlobalLeaseFile(storePath: string): VmGlobalLeaseFile {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VmGlobalLeaseFile>;
-    return { version: 1, lease: parseGlobalLease(parsed.lease) };
-  } catch {
-    return { version: 1, lease: null };
-  }
-}
-
-function writeGlobalLeaseFile(storePath: string, store: VmGlobalLeaseFile): void {
-  fs.mkdirSync(path.dirname(storePath), { recursive: true });
-  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
-  fs.renameSync(tmpPath, storePath);
-}
-
-function readVncCredentialStore(storePath: string): VncCredentialStoreFile {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VncCredentialStoreFile>;
-    return {
-      version: 1,
-      credentials: isRecord(parsed.credentials) ? parsed.credentials as VncCredentialStoreFile["credentials"] : {},
-    };
-  } catch {
-    return { version: 1, credentials: {} };
-  }
-}
-
-function writeVncCredentialStore(storePath: string, store: VncCredentialStoreFile): void {
-  fs.mkdirSync(path.dirname(storePath), { recursive: true, mode: 0o700 });
-  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-  fs.renameSync(tmpPath, storePath);
-  try {
-    fs.chmodSync(storePath, 0o600);
-  } catch {
-    // Best effort. The file lives under .ade/secrets and is excluded from VM shares.
-  }
-}
-
-function vncCredentialKey(laneId: string, vmName: string): string {
-  return `${laneId}:${vmName}`;
-}
-
-function generateVncPassword(): string {
-  return randomBytes(6).toString("base64url").slice(0, 8);
-}
-
 function parseDisplaySize(display: string | null | undefined): { width: number; height: number } {
   const match = /^(\d{3,5})x(\d{3,5})$/i.exec(display ?? "");
   if (!match) return { width: 1024, height: 768 };
diff --git a/apps/desktop/src/main/services/macosVm/macosVmStores.test.ts b/apps/desktop/src/main/services/macosVm/macosVmStores.test.ts
new file mode 100644
index 000000000..e86c11ce8
--- /dev/null
+++ b/apps/desktop/src/main/services/macosVm/macosVmStores.test.ts
@@ -0,0 +1,124 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { MacosVmRecord } from "../../../shared/types";
+import {
+  generateVncPassword,
+  parseGlobalLease,
+  readGlobalLeaseFile,
+  readStoreFile,
+  readVncCredentialStore,
+  vncCredentialKey,
+  writeGlobalLeaseFile,
+  writeStoreFile,
+  writeVncCredentialStore,
+} from "./macosVmStores";
+
+describe("macosVmStores", () => {
+  it("round-trips VM records and drops malformed records", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ade-vm-store-"));
+    try {
+      const storePath = path.join(dir, "records.json");
+      writeStoreFile(storePath, {
+        version: 1,
+        records: [{ id: "record-1" } as MacosVmRecord],
+      });
+
+      expect(readStoreFile(storePath).records.map((record) => record.id)).toEqual(["record-1"]);
+
+      fs.writeFileSync(storePath, JSON.stringify({ version: 1, records: [{ nope: true }, { id: "record-2" }] }));
+      expect(readStoreFile(storePath).records.map((record) => record.id)).toEqual(["record-2"]);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("normalizes global lease files", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ade-vm-lease-"));
+    try {
+      const storePath = path.join(dir, "lease.json");
+      const lease = parseGlobalLease({
+        projectRoot: "/repo",
+        laneId: "lane-1",
+        vmId: "vm-1",
+        vmName: "ADE Lane",
+        updatedAt: "2026-05-31T00:00:00.000Z",
+      });
+      expect(lease).toMatchObject({ laneName: "lane-1", vmId: "vm-1" });
+
+      writeGlobalLeaseFile(storePath, { version: 1, lease });
+      expect(readGlobalLeaseFile(storePath).lease).toEqual(lease);
+
+      fs.writeFileSync(storePath, JSON.stringify({ version: 1, lease: { laneId: "missing-required" } }));
+      expect(readGlobalLeaseFile(storePath).lease).toBeNull();
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("round-trips VNC credentials under stable keys", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ade-vm-vnc-"));
+    try {
+      const storePath = path.join(dir, "vnc.json");
+      const key = vncCredentialKey("lane-1", "vm-1");
+      writeVncCredentialStore(storePath, {
+        version: 1,
+        credentials: {
+          [key]: {
+            laneId: "lane-1",
+            vmName: "vm-1",
+            password: "secret",
+            updatedAt: "2026-05-31T00:00:00.000Z",
+          },
+        },
+      });
+
+      expect(readVncCredentialStore(storePath).credentials[key]?.password).toBe("secret");
+
+      const validKey = vncCredentialKey("lane-2", "vm-2");
+      fs.writeFileSync(storePath, JSON.stringify({
+        version: 1,
+        credentials: {
+          "malformed-1": { laneId: "lane-2" },
+          [validKey]: {
+            laneId: "lane-2",
+            vmName: "vm-2",
+            password: "valid",
+            updatedAt: "2026-05-31T00:00:00.000Z",
+          },
+        },
+      }));
+
+      const filtered = readVncCredentialStore(storePath);
+      expect(filtered.credentials["malformed-1"]).toBeUndefined();
+      expect(filtered.credentials[validKey]?.password).toBe("valid");
+
+      fs.writeFileSync(storePath, JSON.stringify({
+        version: 1,
+        credentials: {
+          "lane-3:vm-3": {
+            laneId: "lane-3",
+            vmName: "vm-3",
+            password: "legacy",
+            updatedAt: "2026-05-31T00:00:00.000Z",
+          },
+        },
+      }));
+      expect(readVncCredentialStore(storePath).credentials[vncCredentialKey("lane-3", "vm-3")]?.password).toBe("legacy");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("uses collision-free VNC credential keys", () => {
+    expect(vncCredentialKey("foo:bar", "baz")).not.toBe(vncCredentialKey("foo", "bar:baz"));
+  });
+
+  it("generates 8-character base64url passwords", () => {
+    const password = generateVncPassword();
+
+    expect(password).toHaveLength(8);
+    expect(password).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+});
diff --git a/apps/desktop/src/main/services/macosVm/macosVmStores.ts b/apps/desktop/src/main/services/macosVm/macosVmStores.ts
new file mode 100644
index 000000000..fea8f4102
--- /dev/null
+++ b/apps/desktop/src/main/services/macosVm/macosVmStores.ts
@@ -0,0 +1,139 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { MacosVmGlobalLease, MacosVmRecord } from "../../../shared/types";
+import { isRecord } from "../shared/utils";
+
+export type VmStoreFile = {
+  version: 1;
+  records: MacosVmRecord[];
+};
+
+export type VmGlobalLeaseFile = {
+  version: 1;
+  lease: MacosVmGlobalLease | null;
+};
+
+export type VncCredentialStoreFile = {
+  version: 1;
+  credentials: Record<string, {
+    laneId: string;
+    vmName: string;
+    password: string;
+    updatedAt: string;
+  }>;
+};
+
+type VncCredential = VncCredentialStoreFile["credentials"][string];
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function readStoreFile(storePath: string): VmStoreFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VmStoreFile>;
+    return {
+      version: 1,
+      records: Array.isArray(parsed.records)
+        ? parsed.records.filter((record): record is MacosVmRecord => isRecord(record) && typeof record.id === "string")
+        : [],
+    };
+  } catch {
+    return { version: 1, records: [] };
+  }
+}
+
+export function writeStoreFile(storePath: string, store: VmStoreFile): void {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true });
+  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  fs.renameSync(tmpPath, storePath);
+}
+
+export function parseGlobalLease(value: unknown): MacosVmGlobalLease | null {
+  if (!isRecord(value)) return null;
+  const projectRoot = asString(value.projectRoot);
+  const laneId = asString(value.laneId);
+  const vmId = asString(value.vmId);
+  const vmName = asString(value.vmName);
+  if (!projectRoot || !laneId || !vmId || !vmName) return null;
+  return {
+    projectRoot,
+    laneId,
+    laneName: asString(value.laneName) ?? laneId,
+    vmId,
+    vmName,
+    updatedAt: asString(value.updatedAt) ?? nowIso(),
+  };
+}
+
+export function readGlobalLeaseFile(storePath: string): VmGlobalLeaseFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VmGlobalLeaseFile>;
+    return { version: 1, lease: parseGlobalLease(parsed.lease) };
+  } catch {
+    return { version: 1, lease: null };
+  }
+}
+
+export function writeGlobalLeaseFile(storePath: string, store: VmGlobalLeaseFile): void {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true });
+  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  fs.renameSync(tmpPath, storePath);
+}
+
+export function readVncCredentialStore(storePath: string): VncCredentialStoreFile {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<VncCredentialStoreFile>;
+    const credentials: VncCredentialStoreFile["credentials"] = {};
+    if (isRecord(parsed.credentials)) {
+      for (const value of Object.values(parsed.credentials)) {
+        const credential = parseVncCredential(value);
+        if (!credential) continue;
+        credentials[vncCredentialKey(credential.laneId, credential.vmName)] = credential;
+      }
+    }
+    return {
+      version: 1,
+      credentials,
+    };
+  } catch {
+    return { version: 1, credentials: {} };
+  }
+}
+
+export function writeVncCredentialStore(storePath: string, store: VncCredentialStoreFile): void {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true, mode: 0o700 });
+  const tmpPath = `${storePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmpPath, `${JSON.stringify(store, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  fs.renameSync(tmpPath, storePath);
+  try {
+    fs.chmodSync(storePath, 0o600);
+  } catch {
+    // Best effort. The file lives under .ade/secrets and is excluded from VM shares.
+  }
+}
+
+export function vncCredentialKey(laneId: string, vmName: string): string {
+  return JSON.stringify([laneId, vmName]);
+}
+
+export function generateVncPassword(): string {
+  return randomBytes(6).toString("base64url").slice(0, 8);
+}
+
+function parseVncCredential(value: unknown): VncCredential | null {
+  if (!isRecord(value)) return null;
+  const laneId = asString(value.laneId);
+  const vmName = asString(value.vmName);
+  const password = asString(value.password);
+  const updatedAt = asString(value.updatedAt);
+  if (!laneId || !vmName || !password || !updatedAt) return null;
+  return { laneId, vmName, password, updatedAt };
+}
diff --git a/apps/desktop/src/main/services/onboarding/onboardingService.test.ts b/apps/desktop/src/main/services/onboarding/onboardingService.test.ts
index 5b9f12ecd..4ce2215e1 100644
--- a/apps/desktop/src/main/services/onboarding/onboardingService.test.ts
+++ b/apps/desktop/src/main/services/onboarding/onboardingService.test.ts
@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createOnboardingService } from "./onboardingService";
+import { buildSuggestedConfig } from "./onboardingSuggestedConfig";
 import type { AdeDb } from "../state/kvDb";
 import type { ProjectConfigFile } from "../../../shared/types";
 
@@ -89,6 +90,22 @@ describe("onboardingService integration", () => {
       fs.rmSync(projectRoot, { recursive: true, force: true });
     }
   });
+
+  it("preserves quoted CI command arguments in suggested tests", () => {
+    const suggested = buildSuggestedConfig({
+      projectRoot: "/tmp/ade-onboarding-ci",
+      indicators: [],
+      suggestedWorkflowCommands: ["npm test -- --grep \"a b\""],
+    });
+
+    expect(suggested.testSuites?.find((suite) => suite.id === "ci-1")?.command).toEqual([
+      "npm",
+      "test",
+      "--",
+      "--grep",
+      "a b",
+    ]);
+  });
 });
 
 describe("onboardingService tour progress", () => {
diff --git a/apps/desktop/src/main/services/onboarding/onboardingService.ts b/apps/desktop/src/main/services/onboarding/onboardingService.ts
index 80d7ab20c..35d7bd932 100644
--- a/apps/desktop/src/main/services/onboarding/onboardingService.ts
+++ b/apps/desktop/src/main/services/onboarding/onboardingService.ts
@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import YAML from "yaml";
 import type { AdeDb } from "../state/kvDb";
 import type { Logger } from "../logging/logger";
 import type { createLaneService } from "../lanes/laneService";
@@ -19,7 +18,8 @@ import type {
   ProjectConfigFile
 } from "../../../shared/types";
 import { runGit, runGitOrThrow } from "../git/git";
-import { dirExists, fileExists, nowIso, safeReadText } from "../shared/utils";
+import { dirExists, fileExists, nowIso } from "../shared/utils";
+import { buildSuggestedConfig, parseGithubWorkflowRuns } from "./onboardingSuggestedConfig";
 
 const STATUS_KEY = "onboarding:status";
 const TOUR_PROGRESS_KEY = "onboarding:tourProgress";
@@ -196,172 +196,6 @@ function normalizeTourProgress(raw: unknown): OnboardingTourProgress {
   };
 }
 
-function uniqueById<T extends { id: string }>(items: T[]): T[] {
-  const out: T[] = [];
-  const seen = new Set<string>();
-  for (const item of items) {
-    const id = item.id.trim();
-    if (!id) continue;
-    if (seen.has(id)) continue;
-    seen.add(id);
-    out.push(item);
-  }
-  return out;
-}
-
-function parseGithubWorkflowRuns(absPath: string): string[] {
-  const raw = safeReadText(absPath, 220_000);
-  if (!raw.trim()) return [];
-  try {
-    const parsed = YAML.parse(raw) as any;
-    const jobs = parsed?.jobs;
-    if (!jobs || typeof jobs !== "object") return [];
-    const commands: string[] = [];
-    for (const job of Object.values(jobs)) {
-      const steps = (job as any)?.steps;
-      if (!Array.isArray(steps)) continue;
-      for (const step of steps) {
-        const runRaw = (step as any)?.run;
-        const run = typeof runRaw === "string" ? runRaw.trim() : "";
-        if (!run) continue;
-        // Keep it light: capture only single-line commands; multi-line gets noisy.
-        const first = run.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
-        if (first) commands.push(first);
-      }
-    }
-    return commands;
-  } catch {
-    return [];
-  }
-}
-
-function guessNodePackageManager(projectRoot: string): "npm" | "yarn" | "pnpm" {
-  if (fileExists(path.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
-  if (fileExists(path.join(projectRoot, "yarn.lock"))) return "yarn";
-  return "npm";
-}
-
-function buildSuggestedConfig(args: {
-  projectRoot: string;
-  indicators: OnboardingDetectionIndicator[];
-  suggestedWorkflowCommands: string[];
-}): ProjectConfigFile {
-  const out: ProjectConfigFile = {
-    version: 1,
-    processes: [],
-    stackButtons: [],
-    testSuites: [],
-    laneOverlayPolicies: [],
-    automations: []
-  };
-
-  const addProcess = (id: string, name: string, command: string[], cwd = ".") => {
-    out.processes!.push({ id, name, command, cwd });
-  };
-  const addTest = (id: string, name: string, command: string[], cwd = ".", tags: any[] = ["custom"]) => {
-    out.testSuites!.push({ id, name, command, cwd, tags });
-  };
-  const addStack = (id: string, name: string, processIds: string[]) => {
-    out.stackButtons!.push({ id, name, processIds, startOrder: "parallel" });
-  };
-
-  const has = (type: string) => args.indicators.some((ind) => ind.type === type);
-
-  if (has("node")) {
-    const pm = guessNodePackageManager(args.projectRoot);
-    if (pm === "pnpm") {
-      addProcess("install", "Install dependencies", ["pnpm", "install"]);
-      addTest("unit", "Unit tests", ["pnpm", "test"], ".", ["unit"]);
-      addProcess("build", "Build", ["pnpm", "build"]);
-    } else if (pm === "yarn") {
-      addProcess("install", "Install dependencies", ["yarn", "install", "--frozen-lockfile"]);
-      addTest("unit", "Unit tests", ["yarn", "test"], ".", ["unit"]);
-      addProcess("build", "Build", ["yarn", "build"]);
-    } else {
-      addProcess("install", "Install dependencies", ["npm", "install"]);
-      addTest("unit", "Unit tests", ["npm", "test"], ".", ["unit"]);
-      addProcess("build", "Build", ["npm", "run", "build"]);
-    }
-  }
-
-  if (has("make")) {
-    addProcess("make", "Make", ["make"]);
-    addTest("make-test", "Make test", ["make", "test"], ".", ["custom"]);
-  }
-
-  if (has("docker")) {
-    addProcess("docker-up", "Docker compose up", ["docker", "compose", "up"], ".");
-    addStack("dev", "Dev", ["docker-up"]);
-  }
-
-  if (has("rust")) {
-    addProcess("cargo-build", "Cargo build", ["cargo", "build"]);
-    addTest("cargo-test", "Cargo test", ["cargo", "test"], ".", ["unit"]);
-  }
-
-  if (has("go")) {
-    addProcess("go-build", "Go build", ["go", "build", "./..."]);
-    addTest("go-test", "Go test", ["go", "test", "./..."], ".", ["unit"]);
-  }
-
-  if (has("python")) {
-    addProcess("py-install", "Install (editable)", ["python", "-m", "pip", "install", "-e", "."]);
-    addTest("pytest", "Pytest", ["pytest"], ".", ["unit"]);
-  }
-
-  // CI-derived commands: keep only a few obvious ones to avoid spamming config.
-  const ciCandidates = args.suggestedWorkflowCommands
-    .map((cmd) => cmd.trim())
-    .filter(Boolean)
-    .filter((cmd) =>
-      /(npm|pnpm|yarn)\s+(test|run\s+test|lint|run\s+lint)|go\s+test|cargo\s+test|pytest|make\s+test/i.test(cmd)
-    )
-    .slice(0, 6);
-  for (const [idx, cmd] of ciCandidates.entries()) {
-    const id = `ci-${idx + 1}`;
-    addTest(id, `CI: ${cmd}`, cmd.split(/\s+/), ".", ["custom"]);
-  }
-
-  out.processes = uniqueById(out.processes ?? []);
-  out.testSuites = uniqueById(out.testSuites ?? []);
-  out.stackButtons = uniqueById(out.stackButtons ?? []);
-
-  out.automations = [
-    {
-      id: "session-end-local",
-      name: "Session end: predict conflicts",
-      enabled: true,
-      trigger: { type: "session-end" },
-      actions: [
-        { type: "predict-conflicts" }
-      ]
-    }
-  ];
-
-  out.providers = {
-    contextTools: {
-      generators: {
-        codex: {
-          command: ["codex", "exec", "-"]
-        },
-        claude: {
-          command: ["claude", "--print"]
-        }
-      },
-      conflictResolvers: {
-        codex: {
-          command: ["codex", "exec", "-"]
-        },
-        claude: {
-          command: ["claude", "--print"]
-        }
-      }
-    }
-  };
-
-  return out;
-}
-
 export function createOnboardingService(args: {
   db: AdeDb;
   logger: Logger;
diff --git a/apps/desktop/src/main/services/onboarding/onboardingSuggestedConfig.ts b/apps/desktop/src/main/services/onboarding/onboardingSuggestedConfig.ts
new file mode 100644
index 000000000..4f3b3b64d
--- /dev/null
+++ b/apps/desktop/src/main/services/onboarding/onboardingSuggestedConfig.ts
@@ -0,0 +1,214 @@
+import path from "node:path";
+import YAML from "yaml";
+import type {
+  OnboardingDetectionIndicator,
+  ProjectConfigFile,
+  TestSuiteTag,
+} from "../../../shared/types";
+import { fileExists, safeReadText } from "../shared/utils";
+
+function uniqueById<T extends { id: string }>(items: T[]): T[] {
+  const out: T[] = [];
+  const seen = new Set<string>();
+  for (const item of items) {
+    const id = item.id.trim();
+    if (!id) continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(item);
+  }
+  return out;
+}
+
+export function parseGithubWorkflowRuns(absPath: string): string[] {
+  const raw = safeReadText(absPath, 220_000);
+  if (!raw.trim()) return [];
+  try {
+    const parsed = YAML.parse(raw) as { jobs?: Record<string, { steps?: Array<{ run?: unknown }> }> } | null;
+    const jobs = parsed?.jobs;
+    if (!jobs || typeof jobs !== "object") return [];
+    const commands: string[] = [];
+    for (const job of Object.values(jobs)) {
+      const steps = job?.steps;
+      if (!Array.isArray(steps)) continue;
+      for (const step of steps) {
+        const run = typeof step.run === "string" ? step.run.trim() : "";
+        if (!run) continue;
+        const first = run.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)[0];
+        if (first) commands.push(first);
+      }
+    }
+    return commands;
+  } catch {
+    return [];
+  }
+}
+
+function guessNodePackageManager(projectRoot: string): "npm" | "yarn" | "pnpm" {
+  if (fileExists(path.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (fileExists(path.join(projectRoot, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+export function splitShellCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "\"" | "'" | null = null;
+  let escaped = false;
+
+  for (const char of command.trim()) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === "\"" || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (escaped) current += "\\";
+  if (current) tokens.push(current);
+  return tokens.length > 0 ? tokens : [command.trim()];
+}
+
+export function buildSuggestedConfig(args: {
+  projectRoot: string;
+  indicators: OnboardingDetectionIndicator[];
+  suggestedWorkflowCommands: string[];
+}): ProjectConfigFile {
+  const out: ProjectConfigFile = {
+    version: 1,
+    processes: [],
+    stackButtons: [],
+    testSuites: [],
+    laneOverlayPolicies: [],
+    automations: []
+  };
+
+  const addProcess = (id: string, name: string, command: string[], cwd = ".") => {
+    out.processes!.push({ id, name, command, cwd });
+  };
+  const addTest = (id: string, name: string, command: string[], cwd = ".", tags: TestSuiteTag[] = ["custom"]) => {
+    out.testSuites!.push({ id, name, command, cwd, tags });
+  };
+  const addStack = (id: string, name: string, processIds: string[]) => {
+    out.stackButtons!.push({ id, name, processIds, startOrder: "parallel" });
+  };
+
+  const has = (type: string) => args.indicators.some((ind) => ind.type === type);
+
+  if (has("node")) {
+    const pm = guessNodePackageManager(args.projectRoot);
+    if (pm === "pnpm") {
+      addProcess("install", "Install dependencies", ["pnpm", "install"]);
+      addTest("unit", "Unit tests", ["pnpm", "test"], ".", ["unit"]);
+      addProcess("build", "Build", ["pnpm", "build"]);
+    } else if (pm === "yarn") {
+      addProcess("install", "Install dependencies", ["yarn", "install", "--frozen-lockfile"]);
+      addTest("unit", "Unit tests", ["yarn", "test"], ".", ["unit"]);
+      addProcess("build", "Build", ["yarn", "build"]);
+    } else {
+      addProcess("install", "Install dependencies", ["npm", "install"]);
+      addTest("unit", "Unit tests", ["npm", "test"], ".", ["unit"]);
+      addProcess("build", "Build", ["npm", "run", "build"]);
+    }
+  }
+
+  if (has("make")) {
+    addProcess("make", "Make", ["make"]);
+    addTest("make-test", "Make test", ["make", "test"], ".", ["custom"]);
+  }
+
+  if (has("docker")) {
+    addProcess("docker-up", "Docker compose up", ["docker", "compose", "up"], ".");
+    addStack("dev", "Dev", ["docker-up"]);
+  }
+
+  if (has("rust")) {
+    addProcess("cargo-build", "Cargo build", ["cargo", "build"]);
+    addTest("cargo-test", "Cargo test", ["cargo", "test"], ".", ["unit"]);
+  }
+
+  if (has("go")) {
+    addProcess("go-build", "Go build", ["go", "build", "./..."]);
+    addTest("go-test", "Go test", ["go", "test", "./..."], ".", ["unit"]);
+  }
+
+  if (has("python")) {
+    addProcess("py-install", "Install (editable)", ["python", "-m", "pip", "install", "-e", "."]);
+    addTest("pytest", "Pytest", ["pytest"], ".", ["unit"]);
+  }
+
+  const ciCandidates = args.suggestedWorkflowCommands
+    .map((cmd) => cmd.trim())
+    .filter(Boolean)
+    .filter((cmd) =>
+      /(npm|pnpm|yarn)\s+(test|run\s+test|lint|run\s+lint)|go\s+test|cargo\s+test|pytest|make\s+test/i.test(cmd)
+    )
+    .slice(0, 6);
+  for (const [idx, cmd] of ciCandidates.entries()) {
+    const id = `ci-${idx + 1}`;
+    addTest(id, `CI: ${cmd}`, splitShellCommand(cmd), ".", ["custom"]);
+  }
+
+  out.processes = uniqueById(out.processes ?? []);
+  out.testSuites = uniqueById(out.testSuites ?? []);
+  out.stackButtons = uniqueById(out.stackButtons ?? []);
+
+  out.automations = [
+    {
+      id: "session-end-local",
+      name: "Session end: predict conflicts",
+      enabled: true,
+      trigger: { type: "session-end" },
+      actions: [
+        { type: "predict-conflicts" }
+      ]
+    }
+  ];
+
+  out.providers = {
+    contextTools: {
+      generators: {
+        codex: {
+          command: ["codex", "exec", "-"]
+        },
+        claude: {
+          command: ["claude", "--print"]
+        }
+      },
+      conflictResolvers: {
+        codex: {
+          command: ["codex", "exec", "-"]
+        },
+        claude: {
+          command: ["claude", "--print"]
+        }
+      }
+    }
+  };
+
+  return out;
+}
diff --git a/apps/desktop/src/main/services/shared/imageDimensions.test.ts b/apps/desktop/src/main/services/shared/imageDimensions.test.ts
new file mode 100644
index 000000000..18fa22a0a
--- /dev/null
+++ b/apps/desktop/src/main/services/shared/imageDimensions.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { imageDimensions, jpegDimensions, pngDimensions } from "./imageDimensions";
+
+function makePng(width: number, height: number): Buffer {
+  const buffer = Buffer.alloc(24);
+  buffer.write("\x89PNG\r\n\x1a\n", 0, "binary");
+  buffer.writeUInt32BE(width, 16);
+  buffer.writeUInt32BE(height, 20);
+  return buffer;
+}
+
+function makeJpeg(width: number, height: number): Buffer {
+  const buffer = Buffer.alloc(21);
+  buffer[0] = 0xff;
+  buffer[1] = 0xd8;
+  buffer[2] = 0xff;
+  buffer[3] = 0xc0;
+  buffer.writeUInt16BE(17, 4);
+  buffer[6] = 8;
+  buffer.writeUInt16BE(height, 7);
+  buffer.writeUInt16BE(width, 9);
+  return buffer;
+}
+
+describe("imageDimensions", () => {
+  it("reads PNG dimensions", () => {
+    const buffer = makePng(1200, 800);
+
+    expect(pngDimensions(buffer)).toEqual({ width: 1200, height: 800 });
+    expect(imageDimensions(buffer)).toEqual({ width: 1200, height: 800 });
+  });
+
+  it("rejects incomplete PNG signatures", () => {
+    const buffer = makePng(1200, 800);
+    buffer[0] = 0x00;
+
+    expect(pngDimensions(buffer)).toBeNull();
+  });
+
+  it("reads JPEG dimensions", () => {
+    const buffer = makeJpeg(640, 480);
+
+    expect(jpegDimensions(buffer)).toEqual({ width: 640, height: 480 });
+    expect(imageDimensions(buffer)).toEqual({ width: 640, height: 480 });
+  });
+
+  it("returns null for unknown image data", () => {
+    expect(imageDimensions(Buffer.from("not an image"))).toBeNull();
+  });
+});
diff --git a/apps/desktop/src/main/services/shared/imageDimensions.ts b/apps/desktop/src/main/services/shared/imageDimensions.ts
new file mode 100644
index 000000000..bb14f2eda
--- /dev/null
+++ b/apps/desktop/src/main/services/shared/imageDimensions.ts
@@ -0,0 +1,47 @@
+export type ImageDimensions = {
+  width: number;
+  height: number;
+};
+
+export function pngDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 24) return null;
+  const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!buffer.subarray(0, pngSignature.length).equals(pngSignature)) return null;
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+  };
+}
+
+export function jpegDimensions(buffer: Buffer): ImageDimensions | null {
+  if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
+  let offset = 2;
+  while (offset + 9 < buffer.length) {
+    if (buffer[offset] !== 0xff) {
+      offset += 1;
+      continue;
+    }
+    const marker = buffer[offset + 1];
+    offset += 2;
+    if (marker === 0xd9 || marker === 0xda) break;
+    if (offset + 2 > buffer.length) return null;
+    const segmentLength = buffer.readUInt16BE(offset);
+    if (segmentLength < 2 || offset + segmentLength > buffer.length) return null;
+    const isStartOfFrame =
+      marker >= 0xc0
+      && marker <= 0xcf
+      && ![0xc4, 0xc8, 0xcc].includes(marker);
+    if (isStartOfFrame && segmentLength >= 7) {
+      return {
+        height: buffer.readUInt16BE(offset + 3),
+        width: buffer.readUInt16BE(offset + 5),
+      };
+    }
+    offset += segmentLength;
+  }
+  return null;
+}
+
+export function imageDimensions(buffer: Buffer): ImageDimensions | null {
+  return pngDimensions(buffer) ?? jpegDimensions(buffer);
+}
diff --git a/apps/desktop/src/main/services/updates/autoUpdateService.test.ts b/apps/desktop/src/main/services/updates/autoUpdateService.test.ts
index 557881828..7754f3037 100644
--- a/apps/desktop/src/main/services/updates/autoUpdateService.test.ts
+++ b/apps/desktop/src/main/services/updates/autoUpdateService.test.ts
@@ -54,9 +54,29 @@ function expectCacheEmpty(updaterCacheDir: string): void {
 
 describe("createAutoUpdateService", () => {
   afterEach(() => {
+    vi.useRealTimers();
     vi.restoreAllMocks();
   });
 
+  it("does not schedule startup or periodic update checks when automatic checks are disabled", () => {
+    vi.useFakeTimers();
+    const updater = new FakeAutoUpdater();
+    const service = createAutoUpdateService({
+      logger: makeLogger(),
+      currentVersion: "1.2.2",
+      globalStatePath: makeStatePath(),
+      startupDelayMs: 5_000,
+      periodicCheckMs: 30 * 60_000,
+      autoCheckEnabled: false,
+      updater,
+    });
+
+    vi.advanceTimersByTime(60 * 60_000);
+
+    expect(updater.checkForUpdates).not.toHaveBeenCalled();
+    service.dispose();
+  });
+
   it("converts a pending install into a post-install notice on matching relaunch", () => {
     const globalStatePath = makeStatePath();
     const updaterCacheDir = makeUpdaterCacheDir();
diff --git a/apps/desktop/src/main/services/updates/autoUpdateService.ts b/apps/desktop/src/main/services/updates/autoUpdateService.ts
index 0c0ab37ff..091f86ec7 100644
--- a/apps/desktop/src/main/services/updates/autoUpdateService.ts
+++ b/apps/desktop/src/main/services/updates/autoUpdateService.ts
@@ -27,6 +27,7 @@ type CreateAutoUpdateServiceArgs = {
   startupDelayMs?: number;
   periodicCheckMs?: number;
   updaterCacheDir?: string;
+  autoCheckEnabled?: boolean;
 };
 
 type UpdateCheckResultLike = {
@@ -253,6 +254,7 @@ export function createAutoUpdateService({
   startupDelayMs = 5_000,
   periodicCheckMs = 30 * 60 * 1_000,
   updaterCacheDir,
+  autoCheckEnabled = true,
 }: CreateAutoUpdateServiceArgs) {
   updater.logger = null;
   updater.autoDownload = true;
@@ -564,8 +566,8 @@ export function createAutoUpdateService({
     });
   }
 
-  const startupTimer = setTimeout(checkForUpdates, startupDelayMs);
-  const periodicTimer = setInterval(checkForUpdates, periodicCheckMs);
+  const startupTimer = autoCheckEnabled ? setTimeout(checkForUpdates, startupDelayMs) : null;
+  const periodicTimer = autoCheckEnabled ? setInterval(checkForUpdates, periodicCheckMs) : null;
 
   return {
     checkForUpdates,
@@ -636,8 +638,8 @@ export function createAutoUpdateService({
       return quitAndInstallPromise;
     },
     dispose() {
-      clearTimeout(startupTimer);
-      clearInterval(periodicTimer);
+      if (startupTimer) clearTimeout(startupTimer);
+      if (periodicTimer) clearInterval(periodicTimer);
       listeners.clear();
       updater.removeListener("checking-for-update", onCheckingForUpdate);
       updater.removeListener("update-available", onUpdateAvailable);
diff --git a/apps/desktop/src/main/services/usage/budgetCapService.test.ts b/apps/desktop/src/main/services/usage/budgetCapService.test.ts
index ce606e62d..9c3b936b2 100644
--- a/apps/desktop/src/main/services/usage/budgetCapService.test.ts
+++ b/apps/desktop/src/main/services/usage/budgetCapService.test.ts
@@ -2,12 +2,10 @@ import { beforeAll, describe, expect, it } from "vitest";
 import path from "node:path";
 import { createRequire } from "node:module";
 import initSqlJs from "sql.js";
-import type { Database, SqlJsStatic } from "sql.js";
+import type { SqlJsStatic } from "sql.js";
 import { createBudgetCapService } from "./budgetCapService";
 import type {
   BudgetCapConfig,
-  BudgetCapScope,
-  BudgetCapProvider,
   UsageSnapshot
 } from "../../../shared/types/usage";
 
@@ -280,7 +278,7 @@ describe("budgetCapService", () => {
       expect(result.warnings[0]).toContain("exceeds cap of 90%");
     });
 
-    it("blocks when usd-per-run cap is exceeded", () => {
+    it("does not count previous rule usage against a new usd-per-run cap check", () => {
       const { db } = createInMemoryDb();
       const svc = createBudgetCapService({
         db,
@@ -297,6 +295,26 @@ describe("budgetCapService", () => {
       svc.recordUsage("automation-rule", "rule-1", { tokensUsed: 50000, costUsd: 0.50, provider: "claude" });
 
       const result = svc.checkBudget("automation-rule", "rule-1", "any");
+      expect(result.allowed).toBe(true);
+      expect(result.remainingUsd).toBeCloseTo(1.0);
+    });
+
+    it("blocks when the active run's usd-per-run cap is exceeded", () => {
+      const { db } = createInMemoryDb();
+      const svc = createBudgetCapService({
+        db,
+        logger: createLogger(),
+        projectConfigService: createMockConfigService({
+          budgetCaps: [
+            { scope: "automation-rule", capType: "usd-per-run", provider: "any", limit: 1.0, action: "block" }
+          ]
+        })
+      });
+
+      svc.recordUsage("automation-rule", "run-1", { tokensUsed: 50000, costUsd: 0.60, provider: "claude" });
+      svc.recordUsage("automation-rule", "run-1", { tokensUsed: 50000, costUsd: 0.50, provider: "claude" });
+
+      const result = svc.checkBudget("automation-rule", "rule-1", "any", { runScopeId: "run-1" });
       expect(result.allowed).toBe(false);
       expect(result.reason).toContain("exceeds cap of $1.00");
       expect(result.remainingUsd).toBe(0);
@@ -314,9 +332,9 @@ describe("budgetCapService", () => {
         })
       });
 
-      svc.recordUsage("automation-rule", "rule-1", { tokensUsed: 10000, costUsd: 0.50, provider: "claude" });
+      svc.recordUsage("automation-rule", "run-1", { tokensUsed: 10000, costUsd: 0.50, provider: "claude" });
 
-      const result = svc.checkBudget("automation-rule", "rule-1", "any");
+      const result = svc.checkBudget("automation-rule", "rule-1", "any", { runScopeId: "run-1" });
       expect(result.allowed).toBe(true);
       expect(result.remainingUsd).toBeCloseTo(4.5);
     });
@@ -449,14 +467,14 @@ describe("budgetCapService", () => {
         })
       });
 
-      svc.recordUsage("automation-rule", "rule-X", { tokensUsed: 100000, costUsd: 5.0, provider: "claude" });
+      svc.recordUsage("automation-rule", "run-X", { tokensUsed: 100000, costUsd: 5.0, provider: "claude" });
 
       // rule-X should be blocked
-      const blockedResult = svc.checkBudget("automation-rule", "rule-X", "any");
+      const blockedResult = svc.checkBudget("automation-rule", "rule-X", "any", { runScopeId: "run-X" });
       expect(blockedResult.allowed).toBe(false);
 
       // rule-Y should pass (different scopeId)
-      const passResult = svc.checkBudget("automation-rule", "rule-Y", "any");
+      const passResult = svc.checkBudget("automation-rule", "rule-Y", "any", { runScopeId: "run-X" });
       expect(passResult.allowed).toBe(true);
     });
   });
diff --git a/apps/desktop/src/main/services/usage/budgetCapService.ts b/apps/desktop/src/main/services/usage/budgetCapService.ts
index db3714c49..b1ad9f84f 100644
--- a/apps/desktop/src/main/services/usage/budgetCapService.ts
+++ b/apps/desktop/src/main/services/usage/budgetCapService.ts
@@ -7,6 +7,7 @@ import type {
   BudgetCapAction,
   BudgetCapType,
   BudgetCheckResult,
+  BudgetCheckContext,
   BudgetCapConfig,
   BudgetPreset,
   UsageSnapshot
@@ -192,7 +193,8 @@ export function createBudgetCapService({
     cap: CapConfigRaw,
     weekKey: string,
     scope: BudgetCapScope,
-    scopeId: string
+    scopeId: string,
+    context: BudgetCheckContext = {}
   ): { exceeded: boolean; message: string; remainingPercent?: number; remainingUsd?: number } {
     const { capType, limit, provider } = cap;
 
@@ -216,7 +218,18 @@ export function createBudgetCapService({
     }
 
     if (capType === "usd-per-run") {
-      const cumulative = getCumulativeUsage(scope, scopeId, provider, weekKey);
+      const runScopeId = typeof context.runScopeId === "string" && context.runScopeId.trim().length > 0
+        ? context.runScopeId.trim()
+        : null;
+      if (!runScopeId) {
+        logger.warn("budgetCap.runScopeMissing", { scope, scopeId, provider });
+        return {
+          exceeded: false,
+          message: "Run cost unavailable without an active run scope",
+          remainingUsd: limit,
+        };
+      }
+      const cumulative = getCumulativeUsage(scope, runScopeId, provider, weekKey);
       const remaining = Math.max(0, limit - cumulative.total_cost);
 
       if (cumulative.total_cost >= limit) {
@@ -264,7 +277,8 @@ export function createBudgetCapService({
     checkBudget(
       scope: BudgetCapScope,
       scopeId: string,
-      provider: BudgetCapProvider
+      provider: BudgetCapProvider,
+      context: BudgetCheckContext = {}
     ): BudgetCheckResult {
       const config = readConfig();
       const weekKey = currentWeekKey();
@@ -310,7 +324,7 @@ export function createBudgetCapService({
         const providerMatch = cap.provider === "any" || cap.provider === provider || provider === "any";
         if (!providerMatch) continue;
 
-        const result = evaluateCap(cap, weekKey, scope, scopeId);
+        const result = evaluateCap(cap, weekKey, scope, scopeId, context);
 
         if (result.remainingPercent != null) {
           minRemainingPercent =
diff --git a/apps/desktop/src/main/services/usage/ledgers/localUsageLedgers.ts b/apps/desktop/src/main/services/usage/ledgers/localUsageLedgers.ts
new file mode 100644
index 000000000..f8eaa57df
--- /dev/null
+++ b/apps/desktop/src/main/services/usage/ledgers/localUsageLedgers.ts
@@ -0,0 +1,1427 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline";
+import type { SqlValue } from "../../state/kvDb";
+import { isRecord, safeJsonParse } from "../../shared/utils";
+
+const LOCAL_COST_SCAN_MAX_FILES = 5_000;
+const LOCAL_COST_SCAN_MAX_FILE_BYTES = 768 * 1024 * 1024;
+const LOCAL_COST_SCAN_MAX_ENTRIES = 1_000_000;
+const LOCAL_COST_SCAN_ALL_DAYS = 3650;
+const LOCAL_SQLITE_SCAN_MAX_ROWS = 250_000;
+const LOCAL_CURSOR_SQLITE_RECENT_ROWS = 250_000;
+const CURSOR_CHARS_PER_TOKEN = 4;
+
+type UsageSqliteStatement = {
+  all: (...params: SqlValue[]) => Record<string, unknown>[];
+};
+type UsageSqliteDatabase = {
+  prepare: (sql: string) => UsageSqliteStatement;
+  exec?: (sql: string) => void;
+  close: () => void;
+};
+type UsageSqliteConstructor = new (dbPath: string, options?: { readOnly?: boolean }) => UsageSqliteDatabase;
+type RecentFileCandidate = { path: string; mtimeMs: number };
+
+const requireForUsageSqlite = createRequire(path.join(process.cwd(), "ade-runtime.cjs"));
+let usageSqliteConstructor: UsageSqliteConstructor | null | undefined;
+
+function toFiniteNumber(value: unknown): number {
+  const numberValue = Number(value ?? 0);
+  return Number.isFinite(numberValue) ? numberValue : 0;
+}
+
+function toNonNegativeInt(value: unknown): number {
+  return Math.max(0, Math.floor(toFiniteNumber(value)));
+}
+
+function normalizeUsageLabel(value: unknown, fallback: string): string {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text.length > 0 ? text : fallback;
+}
+
+export interface TokenEntry {
+  messageId: string;
+  model: string;
+  originator?: string;
+  inputTokens: number;
+  billableInputTokens?: number;
+  outputTokens: number;
+  billableOutputTokens?: number;
+  cachedTokens: number;
+  billableCachedTokens?: number;
+  cacheWriteTokens?: number;
+  oneHourCacheWriteTokens?: number;
+  webSearchRequests?: number;
+  costOverrideUsd?: number;
+  timestamp: number;
+}
+
+export function optionalNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function numberFromRecord(record: Record<string, unknown> | undefined, ...keys: string[]): number {
+  if (!record) return 0;
+  for (const key of keys) {
+    const value = optionalNumber(record[key]);
+    if (value != null) return value;
+  }
+  return 0;
+}
+
+function timestampMsFromValue(value: unknown): number {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const ms = Date.parse(value);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return Date.now();
+}
+
+function timestampMsFromUnixish(value: unknown): number {
+  const numeric = optionalNumber(value);
+  if (numeric != null) return numeric < 1_000_000_000_000 ? numeric * 1_000 : numeric;
+  return timestampMsFromValue(value);
+}
+
+function estimateTokensFromText(value: string): number {
+  if (!value) return 0;
+  return Math.ceil(value.length / CURSOR_CHARS_PER_TOKEN);
+}
+
+function newestCandidatePaths(files: RecentFileCandidate[]): string[] {
+  return files
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, LOCAL_COST_SCAN_MAX_FILES)
+    .map((file) => file.path);
+}
+
+function textFromSqliteValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
+  if (value == null) return "";
+  return String(value);
+}
+
+function loadUsageSqliteConstructor(): UsageSqliteConstructor | null {
+  if (usageSqliteConstructor !== undefined) return usageSqliteConstructor;
+  try {
+    const sqlite = requireForUsageSqlite("node:sqlite") as { DatabaseSync?: UsageSqliteConstructor };
+    usageSqliteConstructor = sqlite.DatabaseSync ?? null;
+  } catch {
+    usageSqliteConstructor = null;
+  }
+  return usageSqliteConstructor;
+}
+
+function openReadonlyUsageDatabase(dbPath: string): UsageSqliteDatabase | null {
+  if (!fs.existsSync(dbPath)) return null;
+  const DatabaseSync = loadUsageSqliteConstructor();
+  if (!DatabaseSync) return null;
+  try {
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+      db.exec?.("PRAGMA busy_timeout = 1000");
+    } catch {
+      // Best-effort only; read-only scans should still work without it.
+    }
+    return db;
+  } catch {
+    return null;
+  }
+}
+
+function usageSqliteAll<T extends Record<string, unknown>>(
+  db: UsageSqliteDatabase,
+  sql: string,
+  params: SqlValue[] = [],
+): T[] {
+  return db.prepare(sql).all(...params) as T[];
+}
+
+function claudeCacheCreationTokens(usage: Record<string, unknown>): { total: number; oneHour: number } {
+  const legacyTotal = numberFromRecord(usage, "cache_creation_input_tokens");
+  const cacheCreation = isRecord(usage.cache_creation) ? usage.cache_creation : undefined;
+  const fiveMinute = numberFromRecord(cacheCreation, "ephemeral_5m_input_tokens");
+  const oneHour = numberFromRecord(cacheCreation, "ephemeral_1h_input_tokens");
+  const splitTotal = fiveMinute + oneHour;
+  if (splitTotal === 0) return { total: legacyTotal, oneHour: 0 };
+  const total = Math.max(legacyTotal, splitTotal);
+  return { total, oneHour: Math.min(oneHour, total) };
+}
+
+function expandUsageHome(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
+  return value;
+}
+
+function dedupeResolvedPaths(paths: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const rawPath of paths) {
+    const resolved = path.resolve(expandUsageHome(rawPath));
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+function getClaudeConfigDirs(): string[] {
+  const multi = process.env.CLAUDE_CONFIG_DIRS;
+  if (multi?.trim()) {
+    const dirs = multi
+      .split(path.delimiter)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (dirs.length > 0) return dedupeResolvedPaths(dirs);
+  }
+
+  const single = process.env.CLAUDE_CONFIG_DIR;
+  if (single?.trim()) return dedupeResolvedPaths([single]);
+
+  return [path.join(os.homedir(), ".claude")];
+}
+
+function getClaudeDesktopSessionsDir(): string {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "Claude", "local-agent-mode-sessions");
+  }
+  if (process.platform === "win32") {
+    return path.join(os.homedir(), "AppData", "Roaming", "Claude", "local-agent-mode-sessions");
+  }
+  return path.join(os.homedir(), ".config", "Claude", "local-agent-mode-sessions");
+}
+
+async function addClaudeProjectsFromProjectsDir(projectsDir: string, seen: Set<string>, out: string[]): Promise<void> {
+  let entries: fs.Dirent[];
+  try {
+    entries = await fs.promises.readdir(projectsDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const projectDir = path.join(projectsDir, entry.name);
+    const resolved = path.resolve(projectDir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(projectDir);
+  }
+}
+
+async function findClaudeDesktopProjectDirs(base: string): Promise<string[]> {
+  const results: string[] = [];
+  async function walk(dir: string, depth: number): Promise<void> {
+    if (depth > 8) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    await Promise.all(entries.map(async (entry) => {
+      if (!entry.isDirectory() || entry.name === "node_modules" || entry.name === ".git") return;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.name === "projects") {
+        await addClaudeProjectsFromProjectsDir(fullPath, new Set(results.map((value) => path.resolve(value))), results);
+        return;
+      }
+      await walk(fullPath, depth + 1);
+    }));
+  }
+
+  await walk(base, 0);
+  return dedupeResolvedPaths(results);
+}
+
+export async function discoverClaudeProjectDirs(): Promise<string[]> {
+  const seen = new Set<string>();
+  const projectDirs: string[] = [];
+
+  for (const claudeDir of getClaudeConfigDirs()) {
+    await addClaudeProjectsFromProjectsDir(path.join(claudeDir, "projects"), seen, projectDirs);
+  }
+
+  for (const desktopProjectDir of await findClaudeDesktopProjectDirs(getClaudeDesktopSessionsDir())) {
+    const resolved = path.resolve(desktopProjectDir);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    projectDirs.push(desktopProjectDir);
+  }
+
+  return projectDirs;
+}
+
+export async function scanClaudeLogs(projectDirsOverride?: string[]): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seenMessageIds = new Set<string>();
+  const projectDirs = projectDirsOverride ?? await discoverClaudeProjectDirs();
+  if (projectDirs.length === 0) return [];
+
+  const jsonlFiles = await findClaudeJsonlFilesInProjectDirs(projectDirs, LOCAL_COST_SCAN_ALL_DAYS);
+
+  for (const filePath of jsonlFiles) {
+    try {
+      const firstTimestampByMessageId = new Map<string, number>();
+      const lastEntryByMessageId = new Map<string, TokenEntry>();
+      const messageOrder: string[] = [];
+
+      for await (const line of readJsonlLines(filePath)) {
+        if (!line.trim()) continue;
+        const record = safeJsonParse<Record<string, unknown>>(line, {});
+        if (record.type !== "assistant") continue;
+
+        const message = record.message as Record<string, unknown> | undefined;
+        if (!message) continue;
+
+        const usage = message.usage as Record<string, unknown> | undefined;
+        if (!usage) continue;
+
+        const messageId = typeof message.id === "string" ? message.id : "";
+        const requestId = typeof record.requestId === "string" ? record.requestId : "";
+        const dedupeKey = messageId || `claude:${record.timestamp ?? ""}:${requestId}`;
+        const timestamp = typeof record.timestamp === "number" ? record.timestamp :
+          typeof record.timestamp === "string" ? new Date(record.timestamp).getTime() : Date.now();
+
+        const model = typeof message.model === "string" ? message.model :
+                      typeof record.model === "string" ? record.model : "unknown";
+        const cacheCreation = claudeCacheCreationTokens(usage);
+        const webSearchRequests = isRecord(usage.server_tool_use)
+          ? numberFromRecord(usage.server_tool_use, "web_search_requests")
+          : 0;
+
+        if (!firstTimestampByMessageId.has(dedupeKey)) {
+          firstTimestampByMessageId.set(dedupeKey, timestamp);
+          messageOrder.push(dedupeKey);
+        }
+
+        lastEntryByMessageId.set(dedupeKey, {
+          messageId: dedupeKey,
+          model,
+          inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : 0,
+          outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : 0,
+          cachedTokens: typeof usage.cache_read_input_tokens === "number"
+            ? usage.cache_read_input_tokens
+            : typeof usage.cached_tokens === "number" ? usage.cached_tokens : 0,
+          cacheWriteTokens: cacheCreation.total,
+          oneHourCacheWriteTokens: cacheCreation.oneHour,
+          webSearchRequests,
+          timestamp,
+        });
+      }
+
+      for (const dedupeKey of messageOrder) {
+        if (seenMessageIds.has(dedupeKey)) continue;
+        const entry = lastEntryByMessageId.get(dedupeKey);
+        if (!entry) continue;
+        seenMessageIds.add(dedupeKey);
+        entry.timestamp = firstTimestampByMessageId.get(dedupeKey) ?? entry.timestamp;
+        entries.push(entry);
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return entries;
+}
+
+export async function scanCodexLogs(): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  const sessionsDir = path.join(codexHome, "sessions");
+
+  try {
+    await fs.promises.access(sessionsDir);
+  } catch {
+    return entries;
+  }
+
+  const jsonlFiles = await findJsonlFiles(sessionsDir, LOCAL_COST_SCAN_ALL_DAYS);
+
+  for (const filePath of jsonlFiles) {
+    try {
+      if (!await isSupportedCodexUsageSession(filePath)) continue;
+      let sessionId = path.basename(filePath, ".jsonl");
+      let sessionModel = "codex";
+      let sessionOriginator = "";
+      let previousTotals: { input: number; cached: number; output: number; reasoning: number; total: number } | null = null;
+
+      for await (const line of readJsonlLines(filePath)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const mayContainUsage =
+          trimmed.includes("\"token_count\"") ||
+          trimmed.includes("\"session_meta\"") ||
+          trimmed.includes("\"turn_context\"") ||
+          trimmed.includes("\"input_tokens\"") ||
+          trimmed.includes("\"prompt_tokens\"") ||
+          trimmed.includes("\"token_count\"");
+        if (!mayContainUsage) continue;
+        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
+
+        const payload = isRecord(record.payload) ? record.payload : undefined;
+        if (record.type === "session_meta" && payload) {
+          const payloadSessionId = typeof payload.id === "string"
+            ? payload.id
+            : typeof payload.session_id === "string"
+              ? payload.session_id
+              : null;
+          if (payloadSessionId) sessionId = payloadSessionId;
+          if (typeof payload.model === "string" && payload.model.trim()) sessionModel = payload.model;
+          if (typeof payload.originator === "string" && payload.originator.trim()) sessionOriginator = payload.originator;
+          continue;
+        }
+
+        if (record.type === "turn_context" && payload) {
+          if (typeof payload.model === "string" && payload.model.trim()) sessionModel = payload.model;
+          continue;
+        }
+
+        if (record.type === "event_msg" && payload?.type === "token_count") {
+          const info = isRecord(payload.info) ? payload.info : undefined;
+          if (!info) continue;
+
+          const totalUsage = isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
+          const lastUsage = isRecord(info.last_token_usage) ? info.last_token_usage : undefined;
+          const cumulativeTotal = numberFromRecord(totalUsage, "total_tokens");
+          if (previousTotals && cumulativeTotal > 0 && cumulativeTotal === previousTotals.total) continue;
+
+          let rawInputTokens = 0;
+          let cachedTokens = 0;
+          let outputTokens = 0;
+          let reasoningTokens = 0;
+
+          if (lastUsage) {
+            rawInputTokens = numberFromRecord(lastUsage, "input_tokens");
+            cachedTokens = numberFromRecord(lastUsage, "cached_input_tokens", "cache_read_input_tokens");
+            outputTokens = numberFromRecord(lastUsage, "output_tokens");
+            reasoningTokens = numberFromRecord(lastUsage, "reasoning_output_tokens");
+          } else if (totalUsage) {
+            rawInputTokens = numberFromRecord(totalUsage, "input_tokens") - (previousTotals?.input ?? 0);
+            cachedTokens = numberFromRecord(totalUsage, "cached_input_tokens", "cache_read_input_tokens") - (previousTotals?.cached ?? 0);
+            outputTokens = numberFromRecord(totalUsage, "output_tokens") - (previousTotals?.output ?? 0);
+            reasoningTokens = numberFromRecord(totalUsage, "reasoning_output_tokens") - (previousTotals?.reasoning ?? 0);
+          }
+
+          if (totalUsage) {
+            previousTotals = {
+              input: numberFromRecord(totalUsage, "input_tokens"),
+              cached: numberFromRecord(totalUsage, "cached_input_tokens", "cache_read_input_tokens"),
+              output: numberFromRecord(totalUsage, "output_tokens"),
+              reasoning: numberFromRecord(totalUsage, "reasoning_output_tokens"),
+              total: cumulativeTotal,
+            };
+          }
+
+          rawInputTokens = Math.max(0, rawInputTokens);
+          cachedTokens = Math.max(0, cachedTokens);
+          outputTokens = Math.max(0, outputTokens) + Math.max(0, reasoningTokens);
+          const billableInputTokens = Math.max(0, rawInputTokens - cachedTokens);
+          const inputTokens = Math.max(0, rawInputTokens);
+          if (inputTokens + outputTokens + cachedTokens === 0) continue;
+
+          const timestamp = timestampMsFromValue(record.timestamp);
+          const model = typeof payload.model === "string" && payload.model.trim()
+            ? payload.model
+            : sessionModel;
+          const dedupeKey = `${sessionId}:${record.timestamp ?? timestamp}:${cumulativeTotal || entries.length}`;
+          if (seen.has(dedupeKey)) continue;
+          seen.add(dedupeKey);
+
+          entries.push({
+            messageId: dedupeKey,
+            model,
+            originator: sessionOriginator,
+            inputTokens,
+            billableInputTokens,
+            outputTokens,
+            cachedTokens,
+            billableCachedTokens: cachedTokens,
+            cacheWriteTokens: 0,
+            timestamp,
+          });
+          if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+          continue;
+        }
+
+        // Codex uses event_msg format
+        const eventType = typeof record.type === "string" ? record.type :
+                          typeof record.event_type === "string" ? record.event_type : "";
+
+        if (!eventType.includes("token") && !eventType.includes("usage") && !eventType.includes("msg")) {
+          // Also check for direct usage fields
+          if (typeof record.input_tokens !== "number" && typeof record.token_count !== "number") continue;
+        }
+
+        const requestId = typeof record.requestId === "string" ? record.requestId :
+                          typeof record.request_id === "string" ? record.request_id :
+                          typeof record.id === "string" ? record.id : "";
+        const messageId = typeof record.message_id === "string" ? record.message_id : "";
+        const dedupeKey = `${messageId}:${requestId}`;
+        if (dedupeKey !== ":" && seen.has(dedupeKey)) continue;
+        if (dedupeKey !== ":") seen.add(dedupeKey);
+
+        const model = typeof record.model === "string" ? record.model : "codex";
+
+        const inputTokens = typeof record.input_tokens === "number" ? record.input_tokens :
+                            typeof record.prompt_tokens === "number" ? record.prompt_tokens : 0;
+        const outputTokens = typeof record.output_tokens === "number" ? record.output_tokens :
+                             typeof record.completion_tokens === "number" ? record.completion_tokens : 0;
+        const tokenCount = typeof record.token_count === "number" ? record.token_count : 0;
+
+        if (inputTokens === 0 && outputTokens === 0 && tokenCount === 0) continue;
+
+        entries.push({
+          messageId: dedupeKey,
+          model,
+          originator: sessionOriginator,
+          inputTokens: inputTokens || Math.floor(tokenCount * 0.4),
+          outputTokens: outputTokens || Math.ceil(tokenCount * 0.6),
+          cachedTokens: typeof record.cached_tokens === "number" ? record.cached_tokens : 0,
+          billableCachedTokens: typeof record.cached_tokens === "number" ? record.cached_tokens : 0,
+          cacheWriteTokens: 0,
+          timestamp: typeof record.timestamp === "number" ? record.timestamp :
+                     typeof record.timestamp === "string" ? new Date(record.timestamp).getTime() : Date.now(),
+        });
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  return entries;
+}
+
+function defaultOpenClawAgentRoots(): string[] {
+  return [
+    path.join(os.homedir(), ".openclaw", "agents"),
+    path.join(os.homedir(), ".clawdbot", "agents"),
+    path.join(os.homedir(), ".moltbot", "agents"),
+    path.join(os.homedir(), ".moldbot", "agents"),
+  ];
+}
+
+export async function scanOpenClawLogs(agentRoots = defaultOpenClawAgentRoots()): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+
+  const jsonlFiles: string[] = [];
+  for (const root of agentRoots) {
+    jsonlFiles.push(...await findJsonlFiles(root, LOCAL_COST_SCAN_ALL_DAYS));
+  }
+
+  for (const filePath of jsonlFiles.slice(0, LOCAL_COST_SCAN_MAX_FILES)) {
+    try {
+      let sessionId = path.basename(filePath, ".jsonl");
+      let currentModel = "openclaw-auto";
+      let sessionTimestamp = "";
+
+      for await (const line of readJsonlLines(filePath)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
+        const type = normalizeUsageLabel(record.type, "");
+
+        if (type === "session") {
+          if (typeof record.id === "string" && record.id.trim()) sessionId = record.id;
+          if (typeof record.timestamp === "string") sessionTimestamp = record.timestamp;
+          continue;
+        }
+
+        if (type === "model_change") {
+          if (typeof record.modelId === "string" && record.modelId.trim()) currentModel = record.modelId;
+          continue;
+        }
+
+        if (type === "custom" && record.customType === "model-snapshot" && isRecord(record.data)) {
+          if (typeof record.data.modelId === "string" && record.data.modelId.trim()) {
+            currentModel = record.data.modelId;
+          }
+          continue;
+        }
+
+        if (type !== "message" || !isRecord(record.message)) continue;
+        const message = record.message;
+        if (message.role !== "assistant" || !isRecord(message.usage)) continue;
+
+        const usage = message.usage;
+        const inputTokens = numberFromRecord(usage, "input");
+        const outputTokens = numberFromRecord(usage, "output");
+        const cachedTokens = numberFromRecord(usage, "cacheRead");
+        const cacheWriteTokens = numberFromRecord(usage, "cacheWrite");
+        if (inputTokens + outputTokens + cachedTokens + cacheWriteTokens === 0) continue;
+
+        const timestamp = timestampMsFromValue(record.timestamp ?? sessionTimestamp);
+        const cost = isRecord(usage.cost) ? optionalNumber(usage.cost.total) : null;
+        const model = typeof message.model === "string" && message.model.trim()
+          ? message.model
+          : currentModel;
+        const dedupeKey = `openclaw:${sessionId}:${typeof record.id === "string" && record.id ? record.id : `${record.timestamp ?? timestamp}:${entries.length}`}`;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
+
+        entries.push({
+          messageId: dedupeKey,
+          model,
+          inputTokens,
+          outputTokens,
+          cachedTokens,
+          billableCachedTokens: cachedTokens,
+          cacheWriteTokens,
+          costOverrideUsd: cost != null && cost > 0 ? cost : undefined,
+          timestamp,
+        });
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable or malformed session files.
+    }
+  }
+
+  return entries;
+}
+
+function defaultDroidSessionsDir(): string {
+  return path.join(process.env.FACTORY_DIR ?? path.join(os.homedir(), ".factory"), "sessions");
+}
+
+function stripDroidModelPrefix(raw: string): string {
+  return raw
+    .replace(/^custom:/, "")
+    .replace(/\[.*?\]/g, "")
+    .replace(/-\d+$/, "")
+    .replace(/-+$/, "")
+    .replace(/^-/, "");
+}
+
+export async function scanDroidLogs(sessionsDir = defaultDroidSessionsDir()): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const jsonlFiles = await findJsonlFiles(sessionsDir, LOCAL_COST_SCAN_ALL_DAYS);
+
+  for (const filePath of jsonlFiles) {
+    try {
+      const settings = safeJsonParse<Record<string, unknown>>(
+        await fs.promises.readFile(filePath.replace(/\.jsonl$/, ".settings.json"), "utf8").catch(() => "{}"),
+        {},
+      );
+      const tokenUsage = isRecord(settings.tokenUsage) ? settings.tokenUsage : null;
+      if (!tokenUsage) continue;
+
+      let sessionId = path.basename(filePath, ".jsonl");
+      const model = typeof settings.model === "string" && settings.model.trim()
+        ? stripDroidModelPrefix(settings.model)
+        : "droid-auto";
+      const assistantCalls: Array<{ id: string; timestamp: number }> = [];
+
+      for await (const line of readJsonlLines(filePath)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
+        if (record.type === "session_start" && typeof record.id === "string" && record.id.trim()) {
+          sessionId = record.id;
+          continue;
+        }
+        if (record.type !== "message" || !isRecord(record.message)) continue;
+        const message = record.message;
+        if (message.role !== "assistant") continue;
+        const content = Array.isArray(message.content) ? message.content : [];
+        const hasAssistantActivity = content.some((block) => (
+          isRecord(block) &&
+          ((block.type === "text" && typeof block.text === "string" && block.text.trim()) || block.type === "tool_use")
+        ));
+        if (!hasAssistantActivity) continue;
+        assistantCalls.push({
+          id: typeof record.id === "string" && record.id ? record.id : `msg-${assistantCalls.length}`,
+          timestamp: timestampMsFromValue(record.timestamp),
+        });
+      }
+
+      if (assistantCalls.length === 0) continue;
+      const totalInput = numberFromRecord(tokenUsage, "inputTokens");
+      const totalOutput = numberFromRecord(tokenUsage, "outputTokens");
+      const totalCacheWrite = numberFromRecord(tokenUsage, "cacheCreationTokens");
+      const totalCacheRead = numberFromRecord(tokenUsage, "cacheReadTokens");
+      const totalThinking = numberFromRecord(tokenUsage, "thinkingTokens");
+      if (totalInput + totalOutput + totalCacheWrite + totalCacheRead + totalThinking === 0) continue;
+
+      const inputPerCall = Math.floor(totalInput / assistantCalls.length);
+      const outputPerCall = Math.floor(totalOutput / assistantCalls.length);
+      const cacheWritePerCall = Math.floor(totalCacheWrite / assistantCalls.length);
+      const cacheReadPerCall = Math.floor(totalCacheRead / assistantCalls.length);
+      const thinkingPerCall = Math.floor(totalThinking / assistantCalls.length);
+
+      for (let i = 0; i < assistantCalls.length; i++) {
+        const call = assistantCalls[i]!;
+        const isLast = i === assistantCalls.length - 1;
+        const dedupeKey = `droid:${sessionId}:${call.id}`;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
+        entries.push({
+          messageId: dedupeKey,
+          model,
+          inputTokens: isLast ? totalInput - inputPerCall * i : inputPerCall,
+          outputTokens: (isLast ? totalOutput - outputPerCall * i : outputPerCall) +
+            (isLast ? totalThinking - thinkingPerCall * i : thinkingPerCall),
+          cachedTokens: isLast ? totalCacheRead - cacheReadPerCall * i : cacheReadPerCall,
+          billableCachedTokens: isLast ? totalCacheRead - cacheReadPerCall * i : cacheReadPerCall,
+          cacheWriteTokens: isLast ? totalCacheWrite - cacheWritePerCall * i : cacheWritePerCall,
+          timestamp: call.timestamp,
+        });
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable or malformed Droid sessions.
+    }
+  }
+
+  return entries;
+}
+
+function defaultCopilotSessionStateDir(): string {
+  return path.join(os.homedir(), ".copilot", "session-state");
+}
+
+function defaultVSCodeWorkspaceStorageDirs(): string[] {
+  if (process.platform === "darwin") {
+    return [
+      path.join(os.homedir(), "Library", "Application Support", "Code", "User", "workspaceStorage"),
+      path.join(os.homedir(), "Library", "Application Support", "Code - Insiders", "User", "workspaceStorage"),
+    ];
+  }
+  if (process.platform === "win32") {
+    return [
+      path.join(os.homedir(), "AppData", "Roaming", "Code", "User", "workspaceStorage"),
+      path.join(os.homedir(), "AppData", "Roaming", "Code - Insiders", "User", "workspaceStorage"),
+    ];
+  }
+  return [
+    path.join(os.homedir(), ".config", "Code", "User", "workspaceStorage"),
+    path.join(os.homedir(), ".config", "Code - Insiders", "User", "workspaceStorage"),
+    path.join(os.homedir(), ".vscode-server", "data", "User", "workspaceStorage"),
+  ];
+}
+
+function inferCopilotModelFromToolCalls(events: Record<string, unknown>[]): string {
+  const modelCounts = new Map<string, number>();
+  const bump = (model: string, weight: number) => {
+    if (!model.trim()) return;
+    modelCounts.set(model, (modelCounts.get(model) ?? 0) + weight);
+  };
+
+  for (const event of events) {
+    const data = isRecord(event.data) ? event.data : {};
+    if (typeof data.model === "string" && data.model.trim()) bump(data.model, 100);
+    if (event.type !== "assistant.message") continue;
+    const toolRequests = Array.isArray(data.toolRequests) ? data.toolRequests : [];
+    for (const tool of toolRequests) {
+      if (!isRecord(tool) || typeof tool.toolCallId !== "string") continue;
+      const toolCallId = tool.toolCallId;
+      if (toolCallId.startsWith("call_")) bump("copilot-openai-auto", 1);
+      if (toolCallId.startsWith("toolu_") || toolCallId.startsWith("tooluse_")) bump("copilot-anthropic-auto", 1);
+    }
+  }
+
+  return [...modelCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "copilot-auto";
+}
+
+export function parseCopilotEvents(raw: string, sourcePath: string): TokenEntry[] {
+  const entries: TokenEntry[] = [];
+  const records = raw
+    .split(/\r?\n/)
+    .filter((line) => line.trim())
+    .map((line) => safeJsonParse<Record<string, unknown>>(line, {}))
+    .filter((record) => isRecord(record));
+  const first = records[0];
+  const isTranscript = first?.type === "session.start" && isRecord(first.data) && first.data.producer === "copilot-agent";
+  const sessionId = path.basename(sourcePath, ".jsonl").length === 36
+    ? path.basename(sourcePath, ".jsonl")
+    : path.basename(path.dirname(sourcePath));
+  let currentModel = "";
+  let pendingUserMessage = "";
+
+  if (isTranscript) {
+    const inferredModel = inferCopilotModelFromToolCalls(records);
+    for (const record of records) {
+      const data = isRecord(record.data) ? record.data : {};
+      if (record.type === "user.message") {
+        pendingUserMessage = typeof data.content === "string" ? data.content.slice(0, 500) : "";
+        continue;
+      }
+      if (record.type !== "assistant.message") continue;
+      const messageId = typeof data.messageId === "string" && data.messageId ? data.messageId : `${record.timestamp ?? entries.length}`;
+      const content = typeof data.content === "string" ? data.content : "";
+      const reasoning = typeof data.reasoningText === "string" ? data.reasoningText : "";
+      const toolRequests = Array.isArray(data.toolRequests) ? data.toolRequests : [];
+      if (!content && !reasoning && toolRequests.length === 0) continue;
+      let outputTokens = numberFromRecord(data, "outputTokens");
+      let reasoningTokens = 0;
+      if (outputTokens === 0) {
+        outputTokens = estimateTokensFromText(content);
+        reasoningTokens = estimateTokensFromText(reasoning);
+      }
+      entries.push({
+        messageId: `copilot:${sessionId}:${messageId}`,
+        model: typeof data.model === "string" && data.model.trim() ? data.model : inferredModel,
+        inputTokens: estimateTokensFromText(pendingUserMessage),
+        outputTokens,
+        billableOutputTokens: outputTokens + reasoningTokens,
+        cachedTokens: 0,
+        cacheWriteTokens: 0,
+        timestamp: timestampMsFromValue(record.timestamp),
+      });
+      pendingUserMessage = "";
+    }
+    return entries;
+  }
+
+  for (const record of records) {
+    const data = isRecord(record.data) ? record.data : {};
+    if (typeof data.model === "string" && data.model.trim()) currentModel = data.model;
+    if (record.type === "session.model_change") {
+      if (typeof data.newModel === "string" && data.newModel.trim()) currentModel = data.newModel;
+      continue;
+    }
+    if (record.type === "user.message") {
+      pendingUserMessage = typeof data.content === "string" ? data.content : "";
+      continue;
+    }
+    if (record.type !== "assistant.message") continue;
+    const outputTokens = numberFromRecord(data, "outputTokens");
+    if (outputTokens === 0 || !currentModel) continue;
+    const messageId = typeof data.messageId === "string" && data.messageId ? data.messageId : `${record.timestamp ?? entries.length}`;
+    entries.push({
+      messageId: `copilot:${sessionId}:${messageId}`,
+      model: currentModel,
+      inputTokens: estimateTokensFromText(pendingUserMessage),
+      outputTokens,
+      cachedTokens: 0,
+      cacheWriteTokens: 0,
+      timestamp: timestampMsFromValue(record.timestamp),
+    });
+    pendingUserMessage = "";
+  }
+
+  return entries;
+}
+
+async function discoverCopilotTranscriptFiles(
+  sessionStateDir = defaultCopilotSessionStateDir(),
+  workspaceStorageDirs = defaultVSCodeWorkspaceStorageDirs(),
+): Promise<string[]> {
+  const files: RecentFileCandidate[] = [];
+  try {
+    const sessionDirs = await fs.promises.readdir(sessionStateDir);
+    await Promise.all(sessionDirs.map(async (sessionId) => {
+      const eventsPath = path.join(sessionStateDir, sessionId, "events.jsonl");
+      const stat = await fs.promises.stat(eventsPath).catch(() => null);
+      if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
+        files.push({ path: eventsPath, mtimeMs: stat.mtimeMs });
+      }
+    }));
+  } catch {
+    // Missing Copilot legacy state is expected for users who never used it.
+  }
+
+  await Promise.all(workspaceStorageDirs.map(async (workspaceStorageDir) => {
+    let workspaceDirs: string[];
+    try {
+      workspaceDirs = await fs.promises.readdir(workspaceStorageDir);
+    } catch {
+      return;
+    }
+    await Promise.all(workspaceDirs.map(async (workspaceDir) => {
+      const transcriptsDir = path.join(workspaceStorageDir, workspaceDir, "GitHub.copilot-chat", "transcripts");
+      let transcriptFiles: string[];
+      try {
+        transcriptFiles = await fs.promises.readdir(transcriptsDir);
+      } catch {
+        return;
+      }
+      await Promise.all(transcriptFiles
+        .filter((file) => file.endsWith(".jsonl"))
+        .map(async (file) => {
+          const filePath = path.join(transcriptsDir, file);
+          const stat = await fs.promises.stat(filePath).catch(() => null);
+          if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
+            files.push({ path: filePath, mtimeMs: stat.mtimeMs });
+          }
+        }));
+    }));
+  }));
+
+  return newestCandidatePaths(files);
+}
+
+export async function scanCopilotLogs(
+  sessionStateDir = defaultCopilotSessionStateDir(),
+  workspaceStorageDirs = defaultVSCodeWorkspaceStorageDirs(),
+): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const files = await discoverCopilotTranscriptFiles(sessionStateDir, workspaceStorageDirs);
+  for (const filePath of files) {
+    try {
+      const raw = await fs.promises.readFile(filePath, "utf8");
+      for (const entry of parseCopilotEvents(raw, filePath)) {
+        if (entry.inputTokens + entry.outputTokens + entry.cachedTokens + toNonNegativeInt(entry.cacheWriteTokens) === 0) continue;
+        if (seen.has(entry.messageId)) continue;
+        seen.add(entry.messageId);
+        entries.push(entry);
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable Copilot logs.
+    }
+  }
+  return entries;
+}
+
+function defaultGeminiTmpDir(): string {
+  return path.join(os.homedir(), ".gemini", "tmp");
+}
+
+function parseGeminiSession(raw: string): { sessionId: string; startTime: string; messages: Record<string, unknown>[] } | null {
+  const parsed = safeJsonParse<Record<string, unknown>>(raw, {});
+  if (isRecord(parsed) && typeof parsed.sessionId === "string" && Array.isArray(parsed.messages)) {
+    return {
+      sessionId: parsed.sessionId,
+      startTime: typeof parsed.startTime === "string" ? parsed.startTime : "",
+      messages: parsed.messages.filter((message): message is Record<string, unknown> => isRecord(message)),
+    };
+  }
+
+  let sessionId = "";
+  let startTime = "";
+  const messages: Record<string, unknown>[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const record = safeJsonParse<Record<string, unknown>>(line, {});
+    if (record.$set !== undefined) continue;
+    if (!sessionId && typeof record.sessionId === "string" && typeof record.startTime === "string") {
+      sessionId = record.sessionId;
+      startTime = record.startTime;
+      continue;
+    }
+    if (typeof record.id === "string" && typeof record.type === "string") {
+      messages.push(record);
+    }
+  }
+  return sessionId ? { sessionId, startTime, messages } : null;
+}
+
+export function parseGeminiEntries(raw: string, sourcePath: string): TokenEntry[] {
+  const session = parseGeminiSession(raw);
+  if (!session) return [];
+  const entries: TokenEntry[] = [];
+  let ordinal = 0;
+
+  for (const message of session.messages) {
+    if (message.type === "user") continue;
+    if (message.type !== "gemini" || !isRecord(message.tokens)) continue;
+    const model = typeof message.model === "string" && message.model.trim() ? message.model : "gemini-auto";
+    const tokens = message.tokens;
+    const totalInput = numberFromRecord(tokens, "input");
+    const totalOutput = numberFromRecord(tokens, "output");
+    const totalCached = numberFromRecord(tokens, "cached");
+    const totalThoughts = numberFromRecord(tokens, "thoughts");
+    if (totalInput + totalOutput + totalCached + totalThoughts === 0) continue;
+    const freshInput = Math.max(0, totalInput - totalCached);
+    const timestamp = timestampMsFromValue(message.timestamp ?? session.startTime);
+    if (timestamp < 1_000_000_000_000) continue;
+    const messageId = typeof message.id === "string" && message.id ? message.id : `${path.basename(sourcePath)}:${ordinal}`;
+    ordinal += 1;
+    entries.push({
+      messageId: `gemini:${session.sessionId}:${messageId}`,
+      model,
+      inputTokens: freshInput,
+      outputTokens: totalOutput + totalThoughts,
+      cachedTokens: totalCached,
+      billableCachedTokens: totalCached,
+      cacheWriteTokens: 0,
+      timestamp,
+    });
+  }
+  return entries;
+}
+
+async function discoverGeminiSessionFiles(tmpDir = defaultGeminiTmpDir()): Promise<string[]> {
+  const files: RecentFileCandidate[] = [];
+  let projectDirs: fs.Dirent[];
+  try {
+    projectDirs = await fs.promises.readdir(tmpDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  await Promise.all(projectDirs
+    .filter((entry) => entry.isDirectory())
+    .map(async (projectDir) => {
+      const chatsDir = path.join(tmpDir, projectDir.name, "chats");
+      let chatFiles: string[];
+      try {
+        chatFiles = await fs.promises.readdir(chatsDir);
+      } catch {
+        return;
+      }
+      await Promise.all(chatFiles
+        .filter((file) => file.startsWith("session-") && (file.endsWith(".json") || file.endsWith(".jsonl")))
+        .map(async (file) => {
+          const filePath = path.join(chatsDir, file);
+          const stat = await fs.promises.stat(filePath).catch(() => null);
+          if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
+            files.push({ path: filePath, mtimeMs: stat.mtimeMs });
+          }
+        }));
+    }));
+
+  return newestCandidatePaths(files);
+}
+
+export async function scanGeminiLogs(tmpDir = defaultGeminiTmpDir()): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const files = await discoverGeminiSessionFiles(tmpDir);
+  for (const filePath of files) {
+    try {
+      const raw = await fs.promises.readFile(filePath, "utf8");
+      for (const entry of parseGeminiEntries(raw, filePath)) {
+        if (seen.has(entry.messageId)) continue;
+        seen.add(entry.messageId);
+        entries.push(entry);
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable Gemini logs.
+    }
+  }
+  return entries;
+}
+
+function defaultOpenCodeDataDir(): string {
+  return path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share"), "opencode");
+}
+
+export async function scanOpenCodeLogs(dataDir = defaultOpenCodeDataDir()): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  let dbFiles: string[] = [];
+  try {
+    dbFiles = (await fs.promises.readdir(dataDir))
+      .filter((name) => name.startsWith("opencode") && name.endsWith(".db"))
+      .map((name) => path.join(dataDir, name));
+  } catch {
+    return entries;
+  }
+
+  const sinceMs = 0;
+  for (const dbPath of dbFiles) {
+    const db = openReadonlyUsageDatabase(dbPath);
+    if (!db) continue;
+    try {
+      const rows = usageSqliteAll<{ id: string; sessionId: string; timeCreated: number; data: string }>(
+        db,
+        `
+          select id, session_id as sessionId, time_created as timeCreated, cast(data as blob) as data
+          from message
+          where time_created >= ?
+          order by time_created desc, id desc
+          limit ?
+        `,
+        [sinceMs, LOCAL_SQLITE_SCAN_MAX_ROWS],
+      );
+      for (const row of rows) {
+        const data = safeJsonParse<Record<string, unknown>>(textFromSqliteValue(row.data), {});
+        if (data.role !== "assistant") continue;
+        const tokens = isRecord(data.tokens) ? data.tokens : {};
+        const cache = isRecord(tokens.cache) ? tokens.cache : {};
+        const inputTokens = numberFromRecord(tokens, "input");
+        const outputTokens = numberFromRecord(tokens, "output") + numberFromRecord(tokens, "reasoning");
+        const cachedTokens = numberFromRecord(cache, "read");
+        const cacheWriteTokens = numberFromRecord(cache, "write");
+        const cost = optionalNumber(data.cost);
+        if (inputTokens + outputTokens + cachedTokens + cacheWriteTokens === 0 && !(cost && cost > 0)) continue;
+
+        const sessionId = typeof row.sessionId === "string" && row.sessionId ? row.sessionId : "unknown";
+        const dedupeKey = `opencode:${sessionId}:${row.id}`;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
+        entries.push({
+          messageId: dedupeKey,
+          model: typeof data.modelID === "string" && data.modelID.trim() ? data.modelID : "opencode-auto",
+          inputTokens,
+          outputTokens,
+          cachedTokens,
+          billableCachedTokens: cachedTokens,
+          cacheWriteTokens,
+          costOverrideUsd: cost != null && cost > 0 ? cost : undefined,
+          timestamp: timestampMsFromUnixish(row.timeCreated),
+        });
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unrecognized OpenCode DB schemas.
+    } finally {
+      db.close();
+    }
+  }
+
+  return entries;
+}
+
+function defaultCursorDbPath(): string {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+  }
+  if (process.platform === "win32") {
+    return path.join(os.homedir(), "AppData", "Roaming", "Cursor", "User", "globalStorage", "state.vscdb");
+  }
+  return path.join(os.homedir(), ".config", "Cursor", "User", "globalStorage", "state.vscdb");
+}
+
+export async function scanCursorLogs(dbPath = defaultCursorDbPath()): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const db = openReadonlyUsageDatabase(dbPath);
+  if (!db) return entries;
+
+  try {
+    const cursorRows = usageSqliteAll<{
+      key: string;
+      value: string | Uint8Array | null;
+    }>(
+      db,
+      `
+        select
+          key,
+          cast(value as blob) as value
+        from cursorDiskKV
+        order by rowid desc
+        limit ?
+      `,
+      [LOCAL_CURSOR_SQLITE_RECENT_ROWS],
+    );
+
+    for (const row of cursorRows) {
+      if (!row.key.startsWith("bubbleId:")) continue;
+      const value = safeJsonParse<Record<string, unknown>>(textFromSqliteValue(row.value), {});
+      const createdAt = typeof value.createdAt === "string" ? value.createdAt : "";
+      if (!createdAt) continue;
+      const tokenCount = isRecord(value.tokenCount) ? value.tokenCount : {};
+      let inputTokens = numberFromRecord(tokenCount, "inputTokens");
+      let outputTokens = numberFromRecord(tokenCount, "outputTokens");
+      if (inputTokens + outputTokens === 0) {
+        const estimated = typeof value.text === "string" ? estimateTokensFromText(value.text) : 0;
+        if (value.type === 1) inputTokens = estimated;
+        else outputTokens = estimated;
+      }
+      if (inputTokens + outputTokens === 0) continue;
+      const dedupeKey = `cursor:bubble:${row.key}`;
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      const modelInfo = isRecord(value.modelInfo) ? value.modelInfo : {};
+      const rawModel = typeof modelInfo.modelName === "string" ? modelInfo.modelName.trim() : "";
+      const model = rawModel && rawModel !== "default"
+        ? rawModel
+        : "cursor-auto";
+      entries.push({
+        messageId: dedupeKey,
+        model,
+        inputTokens,
+        outputTokens,
+        cachedTokens: 0,
+        cacheWriteTokens: 0,
+        timestamp: timestampMsFromValue(createdAt),
+      });
+      if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+    }
+
+    // Cursor's bubble rows contain the real token counts surfaced by Cursor's
+    // UI. The agentKv rows are text blobs that require estimation and have
+    // proven noisy in parity checks, so ADE leaves them out and relies on the
+    // separate Cursor Agent transcript scanner for cursor-agent sessions.
+  } catch {
+    return entries;
+  } finally {
+    db.close();
+  }
+
+  return entries;
+}
+
+function extractCursorAgentUserQuery(text: string): string {
+  const matches = Array.from(text.matchAll(/<user_query>([\s\S]*?)<\/user_query>/g))
+    .map((match) => (match[1] ?? "").trim())
+    .filter(Boolean);
+  return (matches.length > 0 ? matches.join(" ") : text).replace(/\s+/g, " ").trim().slice(0, 500);
+}
+
+function parseCursorAgentJsonlTranscript(raw: string): Array<{ inputText: string; outputText: string; reasoningText: string }> {
+  const turns: Array<{ inputText: string; outputText: string; reasoningText: string }> = [];
+  let currentUser = "";
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const record = safeJsonParse<Record<string, unknown>>(line, {});
+    if (record.role === "user" && isRecord(record.message)) {
+      const content = Array.isArray(record.message.content) ? record.message.content : [];
+      const text = content
+        .map((block) => isRecord(block) && typeof block.text === "string" ? block.text : "")
+        .filter(Boolean)
+        .join(" ");
+      currentUser = extractCursorAgentUserQuery(text);
+      continue;
+    }
+    if (record.role === "assistant" && currentUser && isRecord(record.message)) {
+      const content = Array.isArray(record.message.content) ? record.message.content : [];
+      const outputText = content
+        .map((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" ? block.text : "")
+        .filter(Boolean)
+        .join("\n");
+      turns.push({ inputText: currentUser, outputText, reasoningText: "" });
+      currentUser = "";
+    }
+  }
+  return turns;
+}
+
+function parseCursorAgentTextTranscript(raw: string): Array<{ inputText: string; outputText: string; reasoningText: string }> {
+  const turns: Array<{ inputText: string; outputText: string; reasoningText: string }> = [];
+  const pendingUsers: string[] = [];
+  let active: "none" | "user" | "assistant" = "none";
+  let userLines: string[] = [];
+  let assistantLines: string[] = [];
+
+  const flushUser = () => {
+    if (userLines.length === 0) return;
+    const inputText = extractCursorAgentUserQuery(userLines.join("\n"));
+    if (inputText) pendingUsers.push(inputText);
+    userLines = [];
+  };
+
+  const flushAssistant = () => {
+    if (assistantLines.length === 0) return;
+    let outputText = "";
+    let reasoningText = "";
+    for (const line of assistantLines) {
+      if (/^\s*\[Tool result\]\b/i.test(line)) continue;
+      const thinkingMatch = line.match(/^\s*\[Thinking\]\s*/);
+      if (thinkingMatch) {
+        const body = line.replace(/^\s*\[Thinking\]\s*/, "").trim();
+        if (body) reasoningText += `${body}\n`;
+        continue;
+      }
+      if (/^\s*\[Tool call\]\s*(.+?)\s*$/i.test(line)) continue;
+      outputText += `${line}\n`;
+    }
+    if (pendingUsers.length > 0) {
+      turns.push({
+        inputText: pendingUsers.shift()!,
+        outputText: outputText.trim(),
+        reasoningText: reasoningText.trim(),
+      });
+    }
+    assistantLines = [];
+  };
+
+  for (const line of raw.split(/\r?\n/)) {
+    if (/^\s*user:\s*/i.test(line)) {
+      if (active === "user") flushUser();
+      if (active === "assistant") flushAssistant();
+      active = "user";
+      userLines = [line.replace(/^\s*user:\s*/i, "")];
+      continue;
+    }
+    if (/^\s*A:\s*/.test(line)) {
+      if (active === "user") flushUser();
+      if (active === "assistant") flushAssistant();
+      active = "assistant";
+      assistantLines = [line.replace(/^\s*A:\s*/, "")];
+      continue;
+    }
+    if (active === "user") userLines.push(line);
+    if (active === "assistant") assistantLines.push(line);
+  }
+  if (active === "user") flushUser();
+  if (active === "assistant") flushAssistant();
+  return turns;
+}
+
+function cursorAgentConversationId(filePath: string): string {
+  return createHash("sha1").update(filePath).digest("hex").slice(0, 16);
+}
+
+export async function scanCursorAgentLogs(projectsDir = path.join(os.homedir(), ".cursor", "projects")): Promise<TokenEntry[]> {
+  const entries: TokenEntry[] = [];
+  const seen = new Set<string>();
+  const files = await findRecentFiles(projectsDir, LOCAL_COST_SCAN_ALL_DAYS, [".jsonl", ".txt"]);
+
+  for (const filePath of files) {
+    if (!filePath.includes(`${path.sep}agent-transcripts${path.sep}`)) continue;
+    try {
+      const raw = await fs.promises.readFile(filePath, "utf8");
+      const turns = filePath.endsWith(".jsonl")
+        ? parseCursorAgentJsonlTranscript(raw)
+        : parseCursorAgentTextTranscript(raw);
+      if (turns.length === 0) continue;
+      const stat = await fs.promises.stat(filePath);
+      const sessionId = cursorAgentConversationId(filePath);
+      for (let i = 0; i < turns.length; i++) {
+        const turn = turns[i]!;
+        const inputTokens = estimateTokensFromText(turn.inputText);
+        const outputTokens = estimateTokensFromText(turn.outputText);
+        const reasoningTokens = estimateTokensFromText(turn.reasoningText);
+        if (inputTokens + outputTokens === 0) continue;
+        const dedupeKey = `cursor-agent:${sessionId}:${i}`;
+        if (seen.has(dedupeKey)) continue;
+        seen.add(dedupeKey);
+        entries.push({
+          messageId: dedupeKey,
+          model: "cursor-agent-auto",
+          inputTokens,
+          outputTokens,
+          billableOutputTokens: outputTokens + reasoningTokens,
+          cachedTokens: 0,
+          cacheWriteTokens: 0,
+          timestamp: stat.mtimeMs,
+        });
+        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
+      }
+    } catch {
+      // Skip unreadable Cursor Agent transcripts.
+    }
+  }
+
+  return entries;
+}
+
+async function isSupportedCodexUsageSession(filePath: string): Promise<boolean> {
+  let file: fs.promises.FileHandle | null = null;
+  try {
+    file = await fs.promises.open(filePath, "r");
+    const buffer = Buffer.alloc(1024 * 1024);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    const firstLine = buffer.subarray(0, bytesRead).toString("utf8").split(/\r?\n/, 1)[0]?.trim();
+    if (!firstLine) return false;
+    const entry = safeJsonParse<Record<string, unknown>>(firstLine, {});
+    if (entry.type !== "session_meta" || !isRecord(entry.payload)) return false;
+    const originator = normalizeUsageLabel(entry.payload.originator, "").toLowerCase();
+    return !originator.startsWith("ade");
+  } catch {
+    return false;
+  } finally {
+    await file?.close().catch(() => {});
+  }
+}
+
+export async function findRecentFiles(dir: string, maxAgeDays: number, suffixes: string[]): Promise<string[]> {
+  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+  const files: Array<{ path: string; mtimeMs: number }> = [];
+
+  async function walk(current: string, depth: number) {
+    if (depth > 6) return; // Prevent deep traversal
+    try {
+      const entries = await fs.promises.readdir(current, { withFileTypes: true });
+      const dirPromises: Promise<void>[] = [];
+      const fileStatPromises: Promise<void>[] = [];
+      for (const entry of entries) {
+        const fullPath = path.join(current, entry.name);
+        if (entry.isDirectory()) {
+          dirPromises.push(walk(fullPath, depth + 1));
+        } else if (suffixes.some((suffix) => entry.name.endsWith(suffix))) {
+          fileStatPromises.push(
+            fs.promises.stat(fullPath).then((stat) => {
+              if (stat.mtimeMs >= cutoff && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
+                files.push({ path: fullPath, mtimeMs: stat.mtimeMs });
+              }
+            }).catch(() => {
+              // Skip files we can't stat
+            })
+          );
+        }
+      }
+      await Promise.all([...dirPromises, ...fileStatPromises]);
+    } catch {
+      // Skip directories we can't read
+    }
+  }
+
+  await walk(dir, 0);
+  return files
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, LOCAL_COST_SCAN_MAX_FILES)
+    .map((file) => file.path);
+}
+
+export async function findJsonlFiles(dir: string, maxAgeDays: number): Promise<string[]> {
+  return findRecentFiles(dir, maxAgeDays, [".jsonl"]);
+}
+
+async function findClaudeJsonlFilesInProjectDirs(projectDirs: string[], maxAgeDays: number): Promise<string[]> {
+  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+  const files = new Map<string, { path: string; mtimeMs: number }>();
+
+  async function addJsonlFilesInDir(dir: string): Promise<void> {
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.promises.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    await Promise.all(entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+      .map(async (entry) => {
+        const filePath = path.join(dir, entry.name);
+        try {
+          const stat = await fs.promises.stat(filePath);
+          if (stat.mtimeMs >= cutoff && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
+            files.set(filePath, { path: filePath, mtimeMs: stat.mtimeMs });
+          }
+        } catch {
+          // Skip files we can't stat
+        }
+      }));
+  }
+
+  for (const projectDir of projectDirs) {
+    const projectPath = projectDir;
+    await addJsonlFilesInDir(projectPath);
+    await addJsonlFilesInDir(path.join(projectPath, "subagents"));
+
+    let childEntries: fs.Dirent[];
+    try {
+      childEntries = await fs.promises.readdir(projectPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    await Promise.all(childEntries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => addJsonlFilesInDir(path.join(projectPath, entry.name, "subagents"))));
+  }
+
+  return newestCandidatePaths(Array.from(files.values()));
+}
+
+async function* readJsonlLines(filePath: string): AsyncGenerator<string> {
+  const stream = fs.createReadStream(filePath, { encoding: "utf8" });
+  const lines = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of lines) {
+      yield line;
+    }
+  } finally {
+    lines.close();
+    stream.destroy();
+  }
+}
diff --git a/apps/desktop/src/main/services/usage/usagePricing.ts b/apps/desktop/src/main/services/usage/usagePricing.ts
index 1396af71f..d41354557 100644
--- a/apps/desktop/src/main/services/usage/usagePricing.ts
+++ b/apps/desktop/src/main/services/usage/usagePricing.ts
@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isRecord } from "../shared/utils";
 
 export type TokenPrice = {
   input: number;
@@ -188,10 +189,6 @@ let sortedStaticPricingKeys: string[] | null = null;
 let refreshInFlight: Promise<number> | null = null;
 let disableDiskCacheForTest = false;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
 function normalizeModelVersion(model: string): string {
   return model.trim().replace(/@.*$/, "").replace(/-\d{8}$/, "");
 }
diff --git a/apps/desktop/src/main/services/usage/usageTrackingService.ts b/apps/desktop/src/main/services/usage/usageTrackingService.ts
index baa267dc3..cb65a99ce 100644
--- a/apps/desktop/src/main/services/usage/usageTrackingService.ts
+++ b/apps/desktop/src/main/services/usage/usageTrackingService.ts
@@ -10,9 +10,6 @@ import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import { createInterface } from "node:readline";
 import type { Logger } from "../logging/logger";
 import type {
   AdeUsageDailyPoint,
@@ -29,7 +26,6 @@ import type {
   ExtraUsage,
   UsageSnapshot,
 } from "../../../shared/types";
-import type { SqlValue } from "../state/kvDb";
 import { isRecord, nowIso, getErrorMessage, safeJsonParse } from "../shared/utils";
 import {
   decodeOpenCodeRegistryId,
@@ -57,6 +53,24 @@ import {
   setDynamicTokenPricingForTest,
   WEB_SEARCH_COST_USD,
 } from "./usagePricing";
+import {
+  type TokenEntry,
+  discoverClaudeProjectDirs,
+  findJsonlFiles,
+  findRecentFiles,
+  optionalNumber,
+  parseCopilotEvents,
+  parseGeminiEntries,
+  scanClaudeLogs,
+  scanCodexLogs,
+  scanCopilotLogs,
+  scanCursorAgentLogs,
+  scanCursorLogs,
+  scanDroidLogs,
+  scanGeminiLogs,
+  scanOpenClawLogs,
+  scanOpenCodeLogs,
+} from "./ledgers/localUsageLedgers";
 
 // ── Constants ────────────────────────────────────────────────────
 
@@ -65,13 +79,6 @@ const MIN_POLL_INTERVAL_MS = 60_000;          // 1 min
 const MAX_POLL_INTERVAL_MS = 15 * 60_000;     // 15 min
 const COST_CACHE_TTL_MS = 10 * 60_000;        // 10 min
 const CODEX_CLI_RPC_TIMEOUT_MS = 10_000;
-const LOCAL_COST_SCAN_MAX_FILES = 5_000;
-const LOCAL_COST_SCAN_MAX_FILE_BYTES = 768 * 1024 * 1024;
-const LOCAL_COST_SCAN_MAX_ENTRIES = 1_000_000;
-const LOCAL_COST_SCAN_ALL_DAYS = 3650;
-const LOCAL_SQLITE_SCAN_MAX_ROWS = 250_000;
-const LOCAL_CURSOR_SQLITE_RECENT_ROWS = 250_000;
-const CURSOR_CHARS_PER_TOKEN = 4;
 const FORCE_REFRESH_RESPONSE_TIMEOUT_MS = 60_000;
 const USAGE_SNAPSHOT_CACHE_VERSION = 2;
 const USAGE_SNAPSHOT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
@@ -81,19 +88,6 @@ const GITHUB_STATS_COMMAND_TIMEOUT_MS = 60_000;
 const GITHUB_STATS_FAST_RESPONSE_TIMEOUT_MS = 2_500;
 const GITHUB_STATS_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 
-type UsageSqliteStatement = {
-  all: (...params: SqlValue[]) => Record<string, unknown>[];
-};
-type UsageSqliteDatabase = {
-  prepare: (sql: string) => UsageSqliteStatement;
-  exec?: (sql: string) => void;
-  close: () => void;
-};
-type UsageSqliteConstructor = new (dbPath: string, options?: { readOnly?: boolean }) => UsageSqliteDatabase;
-
-const requireForUsageSqlite = createRequire(path.join(process.cwd(), "ade-runtime.cjs"));
-let usageSqliteConstructor: UsageSqliteConstructor | null | undefined;
-
 function isBenignStdinCloseError(error: unknown): boolean {
   if (!error || typeof error !== "object") return false;
   const code = (error as { code?: unknown }).code;
@@ -595,1378 +589,6 @@ async function pollCodexViaCliRpc(logger: Logger): Promise<{ windows: UsageWindo
 
 // ── Local Cost Scanning ──────────────────────────────────────────
 
-interface TokenEntry {
-  messageId: string;
-  model: string;
-  originator?: string;
-  inputTokens: number;
-  billableInputTokens?: number;
-  outputTokens: number;
-  billableOutputTokens?: number;
-  cachedTokens: number;
-  billableCachedTokens?: number;
-  cacheWriteTokens?: number;
-  oneHourCacheWriteTokens?: number;
-  webSearchRequests?: number;
-  costOverrideUsd?: number;
-  timestamp: number;
-}
-
-function optionalNumber(value: unknown): number | null {
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function numberFromRecord(record: Record<string, unknown> | undefined, ...keys: string[]): number {
-  if (!record) return 0;
-  for (const key of keys) {
-    const value = optionalNumber(record[key]);
-    if (value != null) return value;
-  }
-  return 0;
-}
-
-function timestampMsFromValue(value: unknown): number {
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  if (typeof value === "string") {
-    const ms = Date.parse(value);
-    if (Number.isFinite(ms)) return ms;
-  }
-  return Date.now();
-}
-
-function timestampMsFromUnixish(value: unknown): number {
-  const numeric = optionalNumber(value);
-  if (numeric != null) return numeric < 1_000_000_000_000 ? numeric * 1_000 : numeric;
-  return timestampMsFromValue(value);
-}
-
-function estimateTokensFromText(value: string): number {
-  if (!value) return 0;
-  return Math.ceil(value.length / CURSOR_CHARS_PER_TOKEN);
-}
-
-function textFromSqliteValue(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value instanceof Uint8Array) return Buffer.from(value).toString("utf8");
-  if (value == null) return "";
-  return String(value);
-}
-
-function loadUsageSqliteConstructor(): UsageSqliteConstructor | null {
-  if (usageSqliteConstructor !== undefined) return usageSqliteConstructor;
-  try {
-    const sqlite = requireForUsageSqlite("node:sqlite") as { DatabaseSync?: UsageSqliteConstructor };
-    usageSqliteConstructor = sqlite.DatabaseSync ?? null;
-  } catch {
-    usageSqliteConstructor = null;
-  }
-  return usageSqliteConstructor;
-}
-
-function openReadonlyUsageDatabase(dbPath: string): UsageSqliteDatabase | null {
-  if (!fs.existsSync(dbPath)) return null;
-  const DatabaseSync = loadUsageSqliteConstructor();
-  if (!DatabaseSync) return null;
-  try {
-    const db = new DatabaseSync(dbPath, { readOnly: true });
-    try {
-      db.exec?.("PRAGMA busy_timeout = 1000");
-    } catch {
-      // Best-effort only; read-only scans should still work without it.
-    }
-    return db;
-  } catch {
-    return null;
-  }
-}
-
-function usageSqliteAll<T extends Record<string, unknown>>(
-  db: UsageSqliteDatabase,
-  sql: string,
-  params: SqlValue[] = [],
-): T[] {
-  return db.prepare(sql).all(...params) as T[];
-}
-
-function claudeCacheCreationTokens(usage: Record<string, unknown>): { total: number; oneHour: number } {
-  const legacyTotal = numberFromRecord(usage, "cache_creation_input_tokens");
-  const cacheCreation = isRecord(usage.cache_creation) ? usage.cache_creation : undefined;
-  const fiveMinute = numberFromRecord(cacheCreation, "ephemeral_5m_input_tokens");
-  const oneHour = numberFromRecord(cacheCreation, "ephemeral_1h_input_tokens");
-  const splitTotal = fiveMinute + oneHour;
-  if (splitTotal === 0) return { total: legacyTotal, oneHour: 0 };
-  const total = Math.max(legacyTotal, splitTotal);
-  return { total, oneHour: Math.min(oneHour, total) };
-}
-
-function expandUsageHome(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/") || value.startsWith("~\\")) return path.join(os.homedir(), value.slice(2));
-  return value;
-}
-
-function dedupeResolvedPaths(paths: string[]): string[] {
-  const seen = new Set<string>();
-  const out: string[] = [];
-  for (const rawPath of paths) {
-    const resolved = path.resolve(expandUsageHome(rawPath));
-    if (seen.has(resolved)) continue;
-    seen.add(resolved);
-    out.push(resolved);
-  }
-  return out;
-}
-
-function getClaudeConfigDirs(): string[] {
-  const multi = process.env.CLAUDE_CONFIG_DIRS;
-  if (multi?.trim()) {
-    const dirs = multi
-      .split(path.delimiter)
-      .map((entry) => entry.trim())
-      .filter(Boolean);
-    if (dirs.length > 0) return dedupeResolvedPaths(dirs);
-  }
-
-  const single = process.env.CLAUDE_CONFIG_DIR;
-  if (single?.trim()) return dedupeResolvedPaths([single]);
-
-  return [path.join(os.homedir(), ".claude")];
-}
-
-function getClaudeDesktopSessionsDir(): string {
-  if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Library", "Application Support", "Claude", "local-agent-mode-sessions");
-  }
-  if (process.platform === "win32") {
-    return path.join(os.homedir(), "AppData", "Roaming", "Claude", "local-agent-mode-sessions");
-  }
-  return path.join(os.homedir(), ".config", "Claude", "local-agent-mode-sessions");
-}
-
-async function addClaudeProjectsFromProjectsDir(projectsDir: string, seen: Set<string>, out: string[]): Promise<void> {
-  let entries: fs.Dirent[];
-  try {
-    entries = await fs.promises.readdir(projectsDir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const projectDir = path.join(projectsDir, entry.name);
-    const resolved = path.resolve(projectDir);
-    if (seen.has(resolved)) continue;
-    seen.add(resolved);
-    out.push(projectDir);
-  }
-}
-
-async function findClaudeDesktopProjectDirs(base: string): Promise<string[]> {
-  const results: string[] = [];
-  async function walk(dir: string, depth: number): Promise<void> {
-    if (depth > 8) return;
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    await Promise.all(entries.map(async (entry) => {
-      if (!entry.isDirectory() || entry.name === "node_modules" || entry.name === ".git") return;
-      const fullPath = path.join(dir, entry.name);
-      if (entry.name === "projects") {
-        await addClaudeProjectsFromProjectsDir(fullPath, new Set(results.map((value) => path.resolve(value))), results);
-        return;
-      }
-      await walk(fullPath, depth + 1);
-    }));
-  }
-
-  await walk(base, 0);
-  return dedupeResolvedPaths(results);
-}
-
-async function discoverClaudeProjectDirs(): Promise<string[]> {
-  const seen = new Set<string>();
-  const projectDirs: string[] = [];
-
-  for (const claudeDir of getClaudeConfigDirs()) {
-    await addClaudeProjectsFromProjectsDir(path.join(claudeDir, "projects"), seen, projectDirs);
-  }
-
-  for (const desktopProjectDir of await findClaudeDesktopProjectDirs(getClaudeDesktopSessionsDir())) {
-    const resolved = path.resolve(desktopProjectDir);
-    if (seen.has(resolved)) continue;
-    seen.add(resolved);
-    projectDirs.push(desktopProjectDir);
-  }
-
-  return projectDirs;
-}
-
-async function scanClaudeLogs(projectDirsOverride?: string[]): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seenMessageIds = new Set<string>();
-  const projectDirs = projectDirsOverride ?? await discoverClaudeProjectDirs();
-  if (projectDirs.length === 0) return [];
-
-  const jsonlFiles = await findClaudeJsonlFilesInProjectDirs(projectDirs, LOCAL_COST_SCAN_ALL_DAYS);
-
-  for (const filePath of jsonlFiles) {
-    try {
-      const firstTimestampByMessageId = new Map<string, number>();
-      const lastEntryByMessageId = new Map<string, TokenEntry>();
-      const messageOrder: string[] = [];
-
-      for await (const line of readJsonlLines(filePath)) {
-        if (!line.trim()) continue;
-        const record = safeJsonParse<Record<string, unknown>>(line, {});
-        if (record.type !== "assistant") continue;
-
-        const message = record.message as Record<string, unknown> | undefined;
-        if (!message) continue;
-
-        const usage = message.usage as Record<string, unknown> | undefined;
-        if (!usage) continue;
-
-        const messageId = typeof message.id === "string" ? message.id : "";
-        const requestId = typeof record.requestId === "string" ? record.requestId : "";
-        const dedupeKey = messageId || `claude:${record.timestamp ?? ""}:${requestId}`;
-        const timestamp = typeof record.timestamp === "number" ? record.timestamp :
-          typeof record.timestamp === "string" ? new Date(record.timestamp).getTime() : Date.now();
-
-        const model = typeof message.model === "string" ? message.model :
-                      typeof record.model === "string" ? record.model : "unknown";
-        const cacheCreation = claudeCacheCreationTokens(usage);
-        const webSearchRequests = isRecord(usage.server_tool_use)
-          ? numberFromRecord(usage.server_tool_use, "web_search_requests")
-          : 0;
-
-        if (!firstTimestampByMessageId.has(dedupeKey)) {
-          firstTimestampByMessageId.set(dedupeKey, timestamp);
-          messageOrder.push(dedupeKey);
-        }
-
-        lastEntryByMessageId.set(dedupeKey, {
-          messageId: dedupeKey,
-          model,
-          inputTokens: typeof usage.input_tokens === "number" ? usage.input_tokens : 0,
-          outputTokens: typeof usage.output_tokens === "number" ? usage.output_tokens : 0,
-          cachedTokens: typeof usage.cache_read_input_tokens === "number"
-            ? usage.cache_read_input_tokens
-            : typeof usage.cached_tokens === "number" ? usage.cached_tokens : 0,
-          cacheWriteTokens: cacheCreation.total,
-          oneHourCacheWriteTokens: cacheCreation.oneHour,
-          webSearchRequests,
-          timestamp,
-        });
-      }
-
-      for (const dedupeKey of messageOrder) {
-        if (seenMessageIds.has(dedupeKey)) continue;
-        const entry = lastEntryByMessageId.get(dedupeKey);
-        if (!entry) continue;
-        seenMessageIds.add(dedupeKey);
-        entry.timestamp = firstTimestampByMessageId.get(dedupeKey) ?? entry.timestamp;
-        entries.push(entry);
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable files
-    }
-  }
-
-  return entries;
-}
-
-async function scanCodexLogs(): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  const sessionsDir = path.join(codexHome, "sessions");
-
-  try {
-    await fs.promises.access(sessionsDir);
-  } catch {
-    return entries;
-  }
-
-  const jsonlFiles = await findJsonlFiles(sessionsDir, LOCAL_COST_SCAN_ALL_DAYS);
-
-  for (const filePath of jsonlFiles) {
-    try {
-      if (!await isSupportedCodexUsageSession(filePath)) continue;
-      let sessionId = path.basename(filePath, ".jsonl");
-      let sessionModel = "codex";
-      let sessionOriginator = "";
-      let previousTotals: { input: number; cached: number; output: number; reasoning: number; total: number } | null = null;
-
-      for await (const line of readJsonlLines(filePath)) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        const mayContainUsage =
-          trimmed.includes("\"token_count\"") ||
-          trimmed.includes("\"session_meta\"") ||
-          trimmed.includes("\"turn_context\"") ||
-          trimmed.includes("\"input_tokens\"") ||
-          trimmed.includes("\"prompt_tokens\"") ||
-          trimmed.includes("\"token_count\"");
-        if (!mayContainUsage) continue;
-        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
-
-        const payload = isRecord(record.payload) ? record.payload : undefined;
-        if (record.type === "session_meta" && payload) {
-          const payloadSessionId = typeof payload.id === "string"
-            ? payload.id
-            : typeof payload.session_id === "string"
-              ? payload.session_id
-              : null;
-          if (payloadSessionId) sessionId = payloadSessionId;
-          if (typeof payload.model === "string" && payload.model.trim()) sessionModel = payload.model;
-          if (typeof payload.originator === "string" && payload.originator.trim()) sessionOriginator = payload.originator;
-          continue;
-        }
-
-        if (record.type === "turn_context" && payload) {
-          if (typeof payload.model === "string" && payload.model.trim()) sessionModel = payload.model;
-          continue;
-        }
-
-        if (record.type === "event_msg" && payload?.type === "token_count") {
-          const info = isRecord(payload.info) ? payload.info : undefined;
-          if (!info) continue;
-
-          const totalUsage = isRecord(info.total_token_usage) ? info.total_token_usage : undefined;
-          const lastUsage = isRecord(info.last_token_usage) ? info.last_token_usage : undefined;
-          const cumulativeTotal = numberFromRecord(totalUsage, "total_tokens");
-          if (previousTotals && cumulativeTotal > 0 && cumulativeTotal === previousTotals.total) continue;
-
-          let rawInputTokens = 0;
-          let cachedTokens = 0;
-          let outputTokens = 0;
-          let reasoningTokens = 0;
-
-          if (lastUsage) {
-            rawInputTokens = numberFromRecord(lastUsage, "input_tokens");
-            cachedTokens = numberFromRecord(lastUsage, "cached_input_tokens", "cache_read_input_tokens");
-            outputTokens = numberFromRecord(lastUsage, "output_tokens");
-            reasoningTokens = numberFromRecord(lastUsage, "reasoning_output_tokens");
-          } else if (totalUsage) {
-            rawInputTokens = numberFromRecord(totalUsage, "input_tokens") - (previousTotals?.input ?? 0);
-            cachedTokens = numberFromRecord(totalUsage, "cached_input_tokens", "cache_read_input_tokens") - (previousTotals?.cached ?? 0);
-            outputTokens = numberFromRecord(totalUsage, "output_tokens") - (previousTotals?.output ?? 0);
-            reasoningTokens = numberFromRecord(totalUsage, "reasoning_output_tokens") - (previousTotals?.reasoning ?? 0);
-          }
-
-          if (totalUsage) {
-            previousTotals = {
-              input: numberFromRecord(totalUsage, "input_tokens"),
-              cached: numberFromRecord(totalUsage, "cached_input_tokens", "cache_read_input_tokens"),
-              output: numberFromRecord(totalUsage, "output_tokens"),
-              reasoning: numberFromRecord(totalUsage, "reasoning_output_tokens"),
-              total: cumulativeTotal,
-            };
-          }
-
-          rawInputTokens = Math.max(0, rawInputTokens);
-          cachedTokens = Math.max(0, cachedTokens);
-          outputTokens = Math.max(0, outputTokens) + Math.max(0, reasoningTokens);
-          const billableInputTokens = Math.max(0, rawInputTokens - cachedTokens);
-          const inputTokens = Math.max(0, rawInputTokens);
-          if (inputTokens + outputTokens + cachedTokens === 0) continue;
-
-          const timestamp = timestampMsFromValue(record.timestamp);
-          const model = typeof payload.model === "string" && payload.model.trim()
-            ? payload.model
-            : sessionModel;
-          const dedupeKey = `${sessionId}:${record.timestamp ?? timestamp}:${cumulativeTotal || entries.length}`;
-          if (seen.has(dedupeKey)) continue;
-          seen.add(dedupeKey);
-
-          entries.push({
-            messageId: dedupeKey,
-            model,
-            originator: sessionOriginator,
-            inputTokens,
-            billableInputTokens,
-            outputTokens,
-            cachedTokens,
-            billableCachedTokens: cachedTokens,
-            cacheWriteTokens: 0,
-            timestamp,
-          });
-          if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-          continue;
-        }
-
-        // Codex uses event_msg format
-        const eventType = typeof record.type === "string" ? record.type :
-                          typeof record.event_type === "string" ? record.event_type : "";
-
-        if (!eventType.includes("token") && !eventType.includes("usage") && !eventType.includes("msg")) {
-          // Also check for direct usage fields
-          if (typeof record.input_tokens !== "number" && typeof record.token_count !== "number") continue;
-        }
-
-        const requestId = typeof record.requestId === "string" ? record.requestId :
-                          typeof record.request_id === "string" ? record.request_id :
-                          typeof record.id === "string" ? record.id : "";
-        const messageId = typeof record.message_id === "string" ? record.message_id : "";
-        const dedupeKey = `${messageId}:${requestId}`;
-        if (dedupeKey !== ":" && seen.has(dedupeKey)) continue;
-        if (dedupeKey !== ":") seen.add(dedupeKey);
-
-        const model = typeof record.model === "string" ? record.model : "codex";
-
-        const inputTokens = typeof record.input_tokens === "number" ? record.input_tokens :
-                            typeof record.prompt_tokens === "number" ? record.prompt_tokens : 0;
-        const outputTokens = typeof record.output_tokens === "number" ? record.output_tokens :
-                             typeof record.completion_tokens === "number" ? record.completion_tokens : 0;
-        const tokenCount = typeof record.token_count === "number" ? record.token_count : 0;
-
-        if (inputTokens === 0 && outputTokens === 0 && tokenCount === 0) continue;
-
-        entries.push({
-          messageId: dedupeKey,
-          model,
-          originator: sessionOriginator,
-          inputTokens: inputTokens || Math.floor(tokenCount * 0.4),
-          outputTokens: outputTokens || Math.ceil(tokenCount * 0.6),
-          cachedTokens: typeof record.cached_tokens === "number" ? record.cached_tokens : 0,
-          billableCachedTokens: typeof record.cached_tokens === "number" ? record.cached_tokens : 0,
-          cacheWriteTokens: 0,
-          timestamp: typeof record.timestamp === "number" ? record.timestamp :
-                     typeof record.timestamp === "string" ? new Date(record.timestamp).getTime() : Date.now(),
-        });
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable files
-    }
-  }
-
-  return entries;
-}
-
-function defaultOpenClawAgentRoots(): string[] {
-  return [
-    path.join(os.homedir(), ".openclaw", "agents"),
-    path.join(os.homedir(), ".clawdbot", "agents"),
-    path.join(os.homedir(), ".moltbot", "agents"),
-    path.join(os.homedir(), ".moldbot", "agents"),
-  ];
-}
-
-async function scanOpenClawLogs(agentRoots = defaultOpenClawAgentRoots()): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-
-  const jsonlFiles: string[] = [];
-  for (const root of agentRoots) {
-    jsonlFiles.push(...await findJsonlFiles(root, LOCAL_COST_SCAN_ALL_DAYS));
-  }
-
-  for (const filePath of jsonlFiles.slice(0, LOCAL_COST_SCAN_MAX_FILES)) {
-    try {
-      let sessionId = path.basename(filePath, ".jsonl");
-      let currentModel = "openclaw-auto";
-      let sessionTimestamp = "";
-
-      for await (const line of readJsonlLines(filePath)) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
-        const type = normalizeUsageLabel(record.type, "");
-
-        if (type === "session") {
-          if (typeof record.id === "string" && record.id.trim()) sessionId = record.id;
-          if (typeof record.timestamp === "string") sessionTimestamp = record.timestamp;
-          continue;
-        }
-
-        if (type === "model_change") {
-          if (typeof record.modelId === "string" && record.modelId.trim()) currentModel = record.modelId;
-          continue;
-        }
-
-        if (type === "custom" && record.customType === "model-snapshot" && isRecord(record.data)) {
-          if (typeof record.data.modelId === "string" && record.data.modelId.trim()) {
-            currentModel = record.data.modelId;
-          }
-          continue;
-        }
-
-        if (type !== "message" || !isRecord(record.message)) continue;
-        const message = record.message;
-        if (message.role !== "assistant" || !isRecord(message.usage)) continue;
-
-        const usage = message.usage;
-        const inputTokens = numberFromRecord(usage, "input");
-        const outputTokens = numberFromRecord(usage, "output");
-        const cachedTokens = numberFromRecord(usage, "cacheRead");
-        const cacheWriteTokens = numberFromRecord(usage, "cacheWrite");
-        if (inputTokens + outputTokens + cachedTokens + cacheWriteTokens === 0) continue;
-
-        const timestamp = timestampMsFromValue(record.timestamp ?? sessionTimestamp);
-        const cost = isRecord(usage.cost) ? optionalNumber(usage.cost.total) : null;
-        const model = typeof message.model === "string" && message.model.trim()
-          ? message.model
-          : currentModel;
-        const dedupeKey = `openclaw:${sessionId}:${typeof record.id === "string" && record.id ? record.id : `${record.timestamp ?? timestamp}:${entries.length}`}`;
-        if (seen.has(dedupeKey)) continue;
-        seen.add(dedupeKey);
-
-        entries.push({
-          messageId: dedupeKey,
-          model,
-          inputTokens,
-          outputTokens,
-          cachedTokens,
-          billableCachedTokens: cachedTokens,
-          cacheWriteTokens,
-          costOverrideUsd: cost != null && cost > 0 ? cost : undefined,
-          timestamp,
-        });
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable or malformed session files.
-    }
-  }
-
-  return entries;
-}
-
-function defaultDroidSessionsDir(): string {
-  return path.join(process.env.FACTORY_DIR ?? path.join(os.homedir(), ".factory"), "sessions");
-}
-
-function stripDroidModelPrefix(raw: string): string {
-  return raw
-    .replace(/^custom:/, "")
-    .replace(/\[.*?\]/g, "")
-    .replace(/-\d+$/, "")
-    .replace(/-+$/, "")
-    .replace(/^-/, "");
-}
-
-async function scanDroidLogs(sessionsDir = defaultDroidSessionsDir()): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const jsonlFiles = await findJsonlFiles(sessionsDir, LOCAL_COST_SCAN_ALL_DAYS);
-
-  for (const filePath of jsonlFiles) {
-    try {
-      const settings = safeJsonParse<Record<string, unknown>>(
-        await fs.promises.readFile(filePath.replace(/\.jsonl$/, ".settings.json"), "utf8").catch(() => "{}"),
-        {},
-      );
-      const tokenUsage = isRecord(settings.tokenUsage) ? settings.tokenUsage : null;
-      if (!tokenUsage) continue;
-
-      let sessionId = path.basename(filePath, ".jsonl");
-      const model = typeof settings.model === "string" && settings.model.trim()
-        ? stripDroidModelPrefix(settings.model)
-        : "droid-auto";
-      const assistantCalls: Array<{ id: string; timestamp: number }> = [];
-
-      for await (const line of readJsonlLines(filePath)) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        const record = safeJsonParse<Record<string, unknown>>(trimmed, {});
-        if (record.type === "session_start" && typeof record.id === "string" && record.id.trim()) {
-          sessionId = record.id;
-          continue;
-        }
-        if (record.type !== "message" || !isRecord(record.message)) continue;
-        const message = record.message;
-        if (message.role !== "assistant") continue;
-        const content = Array.isArray(message.content) ? message.content : [];
-        const hasAssistantActivity = content.some((block) => (
-          isRecord(block) &&
-          ((block.type === "text" && typeof block.text === "string" && block.text.trim()) || block.type === "tool_use")
-        ));
-        if (!hasAssistantActivity) continue;
-        assistantCalls.push({
-          id: typeof record.id === "string" && record.id ? record.id : `msg-${assistantCalls.length}`,
-          timestamp: timestampMsFromValue(record.timestamp),
-        });
-      }
-
-      if (assistantCalls.length === 0) continue;
-      const totalInput = numberFromRecord(tokenUsage, "inputTokens");
-      const totalOutput = numberFromRecord(tokenUsage, "outputTokens");
-      const totalCacheWrite = numberFromRecord(tokenUsage, "cacheCreationTokens");
-      const totalCacheRead = numberFromRecord(tokenUsage, "cacheReadTokens");
-      const totalThinking = numberFromRecord(tokenUsage, "thinkingTokens");
-      if (totalInput + totalOutput + totalCacheWrite + totalCacheRead + totalThinking === 0) continue;
-
-      const inputPerCall = Math.floor(totalInput / assistantCalls.length);
-      const outputPerCall = Math.floor(totalOutput / assistantCalls.length);
-      const cacheWritePerCall = Math.floor(totalCacheWrite / assistantCalls.length);
-      const cacheReadPerCall = Math.floor(totalCacheRead / assistantCalls.length);
-      const thinkingPerCall = Math.floor(totalThinking / assistantCalls.length);
-
-      for (let i = 0; i < assistantCalls.length; i++) {
-        const call = assistantCalls[i]!;
-        const isLast = i === assistantCalls.length - 1;
-        const dedupeKey = `droid:${sessionId}:${call.id}`;
-        if (seen.has(dedupeKey)) continue;
-        seen.add(dedupeKey);
-        entries.push({
-          messageId: dedupeKey,
-          model,
-          inputTokens: isLast ? totalInput - inputPerCall * i : inputPerCall,
-          outputTokens: (isLast ? totalOutput - outputPerCall * i : outputPerCall) +
-            (isLast ? totalThinking - thinkingPerCall * i : thinkingPerCall),
-          cachedTokens: isLast ? totalCacheRead - cacheReadPerCall * i : cacheReadPerCall,
-          billableCachedTokens: isLast ? totalCacheRead - cacheReadPerCall * i : cacheReadPerCall,
-          cacheWriteTokens: isLast ? totalCacheWrite - cacheWritePerCall * i : cacheWritePerCall,
-          timestamp: call.timestamp,
-        });
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable or malformed Droid sessions.
-    }
-  }
-
-  return entries;
-}
-
-function defaultCopilotSessionStateDir(): string {
-  return path.join(os.homedir(), ".copilot", "session-state");
-}
-
-function defaultVSCodeWorkspaceStorageDirs(): string[] {
-  if (process.platform === "darwin") {
-    return [
-      path.join(os.homedir(), "Library", "Application Support", "Code", "User", "workspaceStorage"),
-      path.join(os.homedir(), "Library", "Application Support", "Code - Insiders", "User", "workspaceStorage"),
-    ];
-  }
-  if (process.platform === "win32") {
-    return [
-      path.join(os.homedir(), "AppData", "Roaming", "Code", "User", "workspaceStorage"),
-      path.join(os.homedir(), "AppData", "Roaming", "Code - Insiders", "User", "workspaceStorage"),
-    ];
-  }
-  return [
-    path.join(os.homedir(), ".config", "Code", "User", "workspaceStorage"),
-    path.join(os.homedir(), ".config", "Code - Insiders", "User", "workspaceStorage"),
-    path.join(os.homedir(), ".vscode-server", "data", "User", "workspaceStorage"),
-  ];
-}
-
-function inferCopilotModelFromToolCalls(events: Record<string, unknown>[]): string {
-  const modelCounts = new Map<string, number>();
-  const bump = (model: string, weight: number) => {
-    if (!model.trim()) return;
-    modelCounts.set(model, (modelCounts.get(model) ?? 0) + weight);
-  };
-
-  for (const event of events) {
-    const data = isRecord(event.data) ? event.data : {};
-    if (typeof data.model === "string" && data.model.trim()) bump(data.model, 100);
-    if (event.type !== "assistant.message") continue;
-    const toolRequests = Array.isArray(data.toolRequests) ? data.toolRequests : [];
-    for (const tool of toolRequests) {
-      if (!isRecord(tool) || typeof tool.toolCallId !== "string") continue;
-      const toolCallId = tool.toolCallId;
-      if (toolCallId.startsWith("call_")) bump("copilot-openai-auto", 1);
-      if (toolCallId.startsWith("toolu_") || toolCallId.startsWith("tooluse_")) bump("copilot-anthropic-auto", 1);
-    }
-  }
-
-  return [...modelCounts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "copilot-auto";
-}
-
-function parseCopilotEvents(raw: string, sourcePath: string): TokenEntry[] {
-  const entries: TokenEntry[] = [];
-  const records = raw
-    .split(/\r?\n/)
-    .filter((line) => line.trim())
-    .map((line) => safeJsonParse<Record<string, unknown>>(line, {}))
-    .filter((record) => isRecord(record));
-  const first = records[0];
-  const isTranscript = first?.type === "session.start" && isRecord(first.data) && first.data.producer === "copilot-agent";
-  const sessionId = path.basename(sourcePath, ".jsonl").length === 36
-    ? path.basename(sourcePath, ".jsonl")
-    : path.basename(path.dirname(sourcePath));
-  let currentModel = "";
-  let pendingUserMessage = "";
-
-  if (isTranscript) {
-    const inferredModel = inferCopilotModelFromToolCalls(records);
-    for (const record of records) {
-      const data = isRecord(record.data) ? record.data : {};
-      if (record.type === "user.message") {
-        pendingUserMessage = typeof data.content === "string" ? data.content.slice(0, 500) : "";
-        continue;
-      }
-      if (record.type !== "assistant.message") continue;
-      const messageId = typeof data.messageId === "string" && data.messageId ? data.messageId : `${record.timestamp ?? entries.length}`;
-      const content = typeof data.content === "string" ? data.content : "";
-      const reasoning = typeof data.reasoningText === "string" ? data.reasoningText : "";
-      const toolRequests = Array.isArray(data.toolRequests) ? data.toolRequests : [];
-      if (!content && !reasoning && toolRequests.length === 0) continue;
-      let outputTokens = numberFromRecord(data, "outputTokens");
-      let reasoningTokens = 0;
-      if (outputTokens === 0) {
-        outputTokens = estimateTokensFromText(content);
-        reasoningTokens = estimateTokensFromText(reasoning);
-      }
-      entries.push({
-        messageId: `copilot:${sessionId}:${messageId}`,
-        model: typeof data.model === "string" && data.model.trim() ? data.model : inferredModel,
-        inputTokens: estimateTokensFromText(pendingUserMessage),
-        outputTokens,
-        billableOutputTokens: outputTokens + reasoningTokens,
-        cachedTokens: 0,
-        cacheWriteTokens: 0,
-        timestamp: timestampMsFromValue(record.timestamp),
-      });
-      pendingUserMessage = "";
-    }
-    return entries;
-  }
-
-  for (const record of records) {
-    const data = isRecord(record.data) ? record.data : {};
-    if (typeof data.model === "string" && data.model.trim()) currentModel = data.model;
-    if (record.type === "session.model_change") {
-      if (typeof data.newModel === "string" && data.newModel.trim()) currentModel = data.newModel;
-      continue;
-    }
-    if (record.type === "user.message") {
-      pendingUserMessage = typeof data.content === "string" ? data.content : "";
-      continue;
-    }
-    if (record.type !== "assistant.message") continue;
-    const outputTokens = numberFromRecord(data, "outputTokens");
-    if (outputTokens === 0 || !currentModel) continue;
-    const messageId = typeof data.messageId === "string" && data.messageId ? data.messageId : `${record.timestamp ?? entries.length}`;
-    entries.push({
-      messageId: `copilot:${sessionId}:${messageId}`,
-      model: currentModel,
-      inputTokens: estimateTokensFromText(pendingUserMessage),
-      outputTokens,
-      cachedTokens: 0,
-      cacheWriteTokens: 0,
-      timestamp: timestampMsFromValue(record.timestamp),
-    });
-    pendingUserMessage = "";
-  }
-
-  return entries;
-}
-
-async function discoverCopilotTranscriptFiles(
-  sessionStateDir = defaultCopilotSessionStateDir(),
-  workspaceStorageDirs = defaultVSCodeWorkspaceStorageDirs(),
-): Promise<string[]> {
-  const files: string[] = [];
-  try {
-    const sessionDirs = await fs.promises.readdir(sessionStateDir);
-    await Promise.all(sessionDirs.map(async (sessionId) => {
-      const eventsPath = path.join(sessionStateDir, sessionId, "events.jsonl");
-      const stat = await fs.promises.stat(eventsPath).catch(() => null);
-      if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) files.push(eventsPath);
-    }));
-  } catch {
-    // Missing Copilot legacy state is expected for users who never used it.
-  }
-
-  await Promise.all(workspaceStorageDirs.map(async (workspaceStorageDir) => {
-    let workspaceDirs: string[];
-    try {
-      workspaceDirs = await fs.promises.readdir(workspaceStorageDir);
-    } catch {
-      return;
-    }
-    await Promise.all(workspaceDirs.map(async (workspaceDir) => {
-      const transcriptsDir = path.join(workspaceStorageDir, workspaceDir, "GitHub.copilot-chat", "transcripts");
-      let transcriptFiles: string[];
-      try {
-        transcriptFiles = await fs.promises.readdir(transcriptsDir);
-      } catch {
-        return;
-      }
-      await Promise.all(transcriptFiles
-        .filter((file) => file.endsWith(".jsonl"))
-        .map(async (file) => {
-          const filePath = path.join(transcriptsDir, file);
-          const stat = await fs.promises.stat(filePath).catch(() => null);
-          if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) files.push(filePath);
-        }));
-    }));
-  }));
-
-  return files.slice(0, LOCAL_COST_SCAN_MAX_FILES);
-}
-
-async function scanCopilotLogs(
-  sessionStateDir = defaultCopilotSessionStateDir(),
-  workspaceStorageDirs = defaultVSCodeWorkspaceStorageDirs(),
-): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const files = await discoverCopilotTranscriptFiles(sessionStateDir, workspaceStorageDirs);
-  for (const filePath of files) {
-    try {
-      const raw = await fs.promises.readFile(filePath, "utf8");
-      for (const entry of parseCopilotEvents(raw, filePath)) {
-        if (entry.inputTokens + entry.outputTokens + entry.cachedTokens + toNonNegativeInt(entry.cacheWriteTokens) === 0) continue;
-        if (seen.has(entry.messageId)) continue;
-        seen.add(entry.messageId);
-        entries.push(entry);
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable Copilot logs.
-    }
-  }
-  return entries;
-}
-
-function defaultGeminiTmpDir(): string {
-  return path.join(os.homedir(), ".gemini", "tmp");
-}
-
-function parseGeminiSession(raw: string): { sessionId: string; startTime: string; messages: Record<string, unknown>[] } | null {
-  const parsed = safeJsonParse<Record<string, unknown>>(raw, {});
-  if (isRecord(parsed) && typeof parsed.sessionId === "string" && Array.isArray(parsed.messages)) {
-    return {
-      sessionId: parsed.sessionId,
-      startTime: typeof parsed.startTime === "string" ? parsed.startTime : "",
-      messages: parsed.messages.filter((message): message is Record<string, unknown> => isRecord(message)),
-    };
-  }
-
-  let sessionId = "";
-  let startTime = "";
-  const messages: Record<string, unknown>[] = [];
-  for (const line of raw.split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    const record = safeJsonParse<Record<string, unknown>>(line, {});
-    if (record.$set !== undefined) continue;
-    if (!sessionId && typeof record.sessionId === "string" && typeof record.startTime === "string") {
-      sessionId = record.sessionId;
-      startTime = record.startTime;
-      continue;
-    }
-    if (typeof record.id === "string" && typeof record.type === "string") {
-      messages.push(record);
-    }
-  }
-  return sessionId ? { sessionId, startTime, messages } : null;
-}
-
-function parseGeminiEntries(raw: string, sourcePath: string): TokenEntry[] {
-  const session = parseGeminiSession(raw);
-  if (!session) return [];
-  const entries: TokenEntry[] = [];
-  let ordinal = 0;
-
-  for (const message of session.messages) {
-    if (message.type === "user") continue;
-    if (message.type !== "gemini" || !isRecord(message.tokens)) continue;
-    const model = typeof message.model === "string" && message.model.trim() ? message.model : "gemini-auto";
-    const tokens = message.tokens;
-    const totalInput = numberFromRecord(tokens, "input");
-    const totalOutput = numberFromRecord(tokens, "output");
-    const totalCached = numberFromRecord(tokens, "cached");
-    const totalThoughts = numberFromRecord(tokens, "thoughts");
-    if (totalInput + totalOutput + totalCached + totalThoughts === 0) continue;
-    const freshInput = Math.max(0, totalInput - totalCached);
-    const timestamp = timestampMsFromValue(message.timestamp ?? session.startTime);
-    if (timestamp < 1_000_000_000_000) continue;
-    const messageId = typeof message.id === "string" && message.id ? message.id : `${path.basename(sourcePath)}:${ordinal}`;
-    ordinal += 1;
-    entries.push({
-      messageId: `gemini:${session.sessionId}:${messageId}`,
-      model,
-      inputTokens: freshInput,
-      outputTokens: totalOutput + totalThoughts,
-      cachedTokens: totalCached,
-      billableCachedTokens: totalCached,
-      cacheWriteTokens: 0,
-      timestamp,
-    });
-  }
-  return entries;
-}
-
-async function discoverGeminiSessionFiles(tmpDir = defaultGeminiTmpDir()): Promise<string[]> {
-  const files: string[] = [];
-  let projectDirs: fs.Dirent[];
-  try {
-    projectDirs = await fs.promises.readdir(tmpDir, { withFileTypes: true });
-  } catch {
-    return files;
-  }
-
-  await Promise.all(projectDirs
-    .filter((entry) => entry.isDirectory())
-    .map(async (projectDir) => {
-      const chatsDir = path.join(tmpDir, projectDir.name, "chats");
-      let chatFiles: string[];
-      try {
-        chatFiles = await fs.promises.readdir(chatsDir);
-      } catch {
-        return;
-      }
-      await Promise.all(chatFiles
-        .filter((file) => file.startsWith("session-") && (file.endsWith(".json") || file.endsWith(".jsonl")))
-        .map(async (file) => {
-          const filePath = path.join(chatsDir, file);
-          const stat = await fs.promises.stat(filePath).catch(() => null);
-          if (stat?.isFile() && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) files.push(filePath);
-        }));
-    }));
-
-  return files.slice(0, LOCAL_COST_SCAN_MAX_FILES);
-}
-
-async function scanGeminiLogs(tmpDir = defaultGeminiTmpDir()): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const files = await discoverGeminiSessionFiles(tmpDir);
-  for (const filePath of files) {
-    try {
-      const raw = await fs.promises.readFile(filePath, "utf8");
-      for (const entry of parseGeminiEntries(raw, filePath)) {
-        if (seen.has(entry.messageId)) continue;
-        seen.add(entry.messageId);
-        entries.push(entry);
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable Gemini logs.
-    }
-  }
-  return entries;
-}
-
-function defaultOpenCodeDataDir(): string {
-  return path.join(process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share"), "opencode");
-}
-
-async function scanOpenCodeLogs(dataDir = defaultOpenCodeDataDir()): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  let dbFiles: string[] = [];
-  try {
-    dbFiles = (await fs.promises.readdir(dataDir))
-      .filter((name) => name.startsWith("opencode") && name.endsWith(".db"))
-      .map((name) => path.join(dataDir, name));
-  } catch {
-    return entries;
-  }
-
-  const sinceMs = 0;
-  for (const dbPath of dbFiles) {
-    const db = openReadonlyUsageDatabase(dbPath);
-    if (!db) continue;
-    try {
-      const rows = usageSqliteAll<{ id: string; sessionId: string; timeCreated: number; data: string }>(
-        db,
-        `
-          select id, session_id as sessionId, time_created as timeCreated, cast(data as blob) as data
-          from message
-          where time_created >= ?
-          order by time_created desc, id desc
-          limit ?
-        `,
-        [sinceMs, LOCAL_SQLITE_SCAN_MAX_ROWS],
-      );
-      for (const row of rows) {
-        const data = safeJsonParse<Record<string, unknown>>(textFromSqliteValue(row.data), {});
-        if (data.role !== "assistant") continue;
-        const tokens = isRecord(data.tokens) ? data.tokens : {};
-        const cache = isRecord(tokens.cache) ? tokens.cache : {};
-        const inputTokens = numberFromRecord(tokens, "input");
-        const outputTokens = numberFromRecord(tokens, "output") + numberFromRecord(tokens, "reasoning");
-        const cachedTokens = numberFromRecord(cache, "read");
-        const cacheWriteTokens = numberFromRecord(cache, "write");
-        const cost = optionalNumber(data.cost);
-        if (inputTokens + outputTokens + cachedTokens + cacheWriteTokens === 0 && !(cost && cost > 0)) continue;
-
-        const sessionId = typeof row.sessionId === "string" && row.sessionId ? row.sessionId : "unknown";
-        const dedupeKey = `opencode:${sessionId}:${row.id}`;
-        if (seen.has(dedupeKey)) continue;
-        seen.add(dedupeKey);
-        entries.push({
-          messageId: dedupeKey,
-          model: typeof data.modelID === "string" && data.modelID.trim() ? data.modelID : "opencode-auto",
-          inputTokens,
-          outputTokens,
-          cachedTokens,
-          billableCachedTokens: cachedTokens,
-          cacheWriteTokens,
-          costOverrideUsd: cost != null && cost > 0 ? cost : undefined,
-          timestamp: timestampMsFromUnixish(row.timeCreated),
-        });
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unrecognized OpenCode DB schemas.
-    } finally {
-      db.close();
-    }
-  }
-
-  return entries;
-}
-
-function defaultCursorDbPath(): string {
-  if (process.platform === "darwin") {
-    return path.join(os.homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
-  }
-  if (process.platform === "win32") {
-    return path.join(os.homedir(), "AppData", "Roaming", "Cursor", "User", "globalStorage", "state.vscdb");
-  }
-  return path.join(os.homedir(), ".config", "Cursor", "User", "globalStorage", "state.vscdb");
-}
-
-async function scanCursorLogs(dbPath = defaultCursorDbPath()): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const db = openReadonlyUsageDatabase(dbPath);
-  if (!db) return entries;
-
-  try {
-    const cursorRows = usageSqliteAll<{
-      key: string;
-      value: string | Uint8Array | null;
-    }>(
-      db,
-      `
-        select
-          key,
-          cast(value as blob) as value
-        from cursorDiskKV
-        order by rowid desc
-        limit ?
-      `,
-      [LOCAL_CURSOR_SQLITE_RECENT_ROWS],
-    );
-
-    for (const row of cursorRows) {
-      if (!row.key.startsWith("bubbleId:")) continue;
-      const value = safeJsonParse<Record<string, unknown>>(textFromSqliteValue(row.value), {});
-      const createdAt = typeof value.createdAt === "string" ? value.createdAt : "";
-      if (!createdAt) continue;
-      const tokenCount = isRecord(value.tokenCount) ? value.tokenCount : {};
-      let inputTokens = numberFromRecord(tokenCount, "inputTokens");
-      let outputTokens = numberFromRecord(tokenCount, "outputTokens");
-      if (inputTokens + outputTokens === 0) {
-        const estimated = typeof value.text === "string" ? estimateTokensFromText(value.text) : 0;
-        if (value.type === 1) inputTokens = estimated;
-        else outputTokens = estimated;
-      }
-      if (inputTokens + outputTokens === 0) continue;
-      const dedupeKey = `cursor:bubble:${row.key}`;
-      if (seen.has(dedupeKey)) continue;
-      seen.add(dedupeKey);
-      const modelInfo = isRecord(value.modelInfo) ? value.modelInfo : {};
-      const rawModel = typeof modelInfo.modelName === "string" ? modelInfo.modelName.trim() : "";
-      const model = rawModel && rawModel !== "default"
-        ? rawModel
-        : "cursor-auto";
-      entries.push({
-        messageId: dedupeKey,
-        model,
-        inputTokens,
-        outputTokens,
-        cachedTokens: 0,
-        cacheWriteTokens: 0,
-        timestamp: timestampMsFromValue(createdAt),
-      });
-      if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-    }
-
-    // Cursor's bubble rows contain the real token counts surfaced by Cursor's
-    // UI. The agentKv rows are text blobs that require estimation and have
-    // proven noisy in parity checks, so ADE leaves them out and relies on the
-    // separate Cursor Agent transcript scanner for cursor-agent sessions.
-  } catch {
-    return entries;
-  } finally {
-    db.close();
-  }
-
-  return entries;
-}
-
-function extractCursorAgentUserQuery(text: string): string {
-  const matches = Array.from(text.matchAll(/<user_query>([\s\S]*?)<\/user_query>/g))
-    .map((match) => (match[1] ?? "").trim())
-    .filter(Boolean);
-  return (matches.length > 0 ? matches.join(" ") : text).replace(/\s+/g, " ").trim().slice(0, 500);
-}
-
-function parseCursorAgentJsonlTranscript(raw: string): Array<{ inputText: string; outputText: string; reasoningText: string }> {
-  const turns: Array<{ inputText: string; outputText: string; reasoningText: string }> = [];
-  let currentUser = "";
-  for (const line of raw.split(/\r?\n/)) {
-    if (!line.trim()) continue;
-    const record = safeJsonParse<Record<string, unknown>>(line, {});
-    if (record.role === "user" && isRecord(record.message)) {
-      const content = Array.isArray(record.message.content) ? record.message.content : [];
-      const text = content
-        .map((block) => isRecord(block) && typeof block.text === "string" ? block.text : "")
-        .filter(Boolean)
-        .join(" ");
-      currentUser = extractCursorAgentUserQuery(text);
-      continue;
-    }
-    if (record.role === "assistant" && currentUser && isRecord(record.message)) {
-      const content = Array.isArray(record.message.content) ? record.message.content : [];
-      const outputText = content
-        .map((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" ? block.text : "")
-        .filter(Boolean)
-        .join("\n");
-      turns.push({ inputText: currentUser, outputText, reasoningText: "" });
-      currentUser = "";
-    }
-  }
-  return turns;
-}
-
-function parseCursorAgentTextTranscript(raw: string): Array<{ inputText: string; outputText: string; reasoningText: string }> {
-  const turns: Array<{ inputText: string; outputText: string; reasoningText: string }> = [];
-  const pendingUsers: string[] = [];
-  let active: "none" | "user" | "assistant" = "none";
-  let userLines: string[] = [];
-  let assistantLines: string[] = [];
-
-  const flushUser = () => {
-    if (userLines.length === 0) return;
-    const inputText = extractCursorAgentUserQuery(userLines.join("\n"));
-    if (inputText) pendingUsers.push(inputText);
-    userLines = [];
-  };
-
-  const flushAssistant = () => {
-    if (assistantLines.length === 0) return;
-    let outputText = "";
-    let reasoningText = "";
-    for (const line of assistantLines) {
-      if (/^\s*\[Tool result\]\b/i.test(line)) continue;
-      const thinkingMatch = line.match(/^\s*\[Thinking\]\s*/);
-      if (thinkingMatch) {
-        const body = line.replace(/^\s*\[Thinking\]\s*/, "").trim();
-        if (body) reasoningText += `${body}\n`;
-        continue;
-      }
-      if (/^\s*\[Tool call\]\s*(.+?)\s*$/i.test(line)) continue;
-      outputText += `${line}\n`;
-    }
-    if (pendingUsers.length > 0) {
-      turns.push({
-        inputText: pendingUsers.shift()!,
-        outputText: outputText.trim(),
-        reasoningText: reasoningText.trim(),
-      });
-    }
-    assistantLines = [];
-  };
-
-  for (const line of raw.split(/\r?\n/)) {
-    if (/^\s*user:\s*/i.test(line)) {
-      if (active === "user") flushUser();
-      if (active === "assistant") flushAssistant();
-      active = "user";
-      userLines = [line.replace(/^\s*user:\s*/i, "")];
-      continue;
-    }
-    if (/^\s*A:\s*/.test(line)) {
-      if (active === "user") flushUser();
-      if (active === "assistant") flushAssistant();
-      active = "assistant";
-      assistantLines = [line.replace(/^\s*A:\s*/, "")];
-      continue;
-    }
-    if (active === "user") userLines.push(line);
-    if (active === "assistant") assistantLines.push(line);
-  }
-  if (active === "user") flushUser();
-  if (active === "assistant") flushAssistant();
-  return turns;
-}
-
-function cursorAgentConversationId(filePath: string): string {
-  return createHash("sha1").update(filePath).digest("hex").slice(0, 16);
-}
-
-async function scanCursorAgentLogs(projectsDir = path.join(os.homedir(), ".cursor", "projects")): Promise<TokenEntry[]> {
-  const entries: TokenEntry[] = [];
-  const seen = new Set<string>();
-  const files = await findRecentFiles(projectsDir, LOCAL_COST_SCAN_ALL_DAYS, [".jsonl", ".txt"]);
-
-  for (const filePath of files) {
-    if (!filePath.includes(`${path.sep}agent-transcripts${path.sep}`)) continue;
-    try {
-      const raw = await fs.promises.readFile(filePath, "utf8");
-      const turns = filePath.endsWith(".jsonl")
-        ? parseCursorAgentJsonlTranscript(raw)
-        : parseCursorAgentTextTranscript(raw);
-      if (turns.length === 0) continue;
-      const stat = await fs.promises.stat(filePath);
-      const sessionId = cursorAgentConversationId(filePath);
-      for (let i = 0; i < turns.length; i++) {
-        const turn = turns[i]!;
-        const inputTokens = estimateTokensFromText(turn.inputText);
-        const outputTokens = estimateTokensFromText(turn.outputText);
-        const reasoningTokens = estimateTokensFromText(turn.reasoningText);
-        if (inputTokens + outputTokens === 0) continue;
-        const dedupeKey = `cursor-agent:${sessionId}:${i}`;
-        if (seen.has(dedupeKey)) continue;
-        seen.add(dedupeKey);
-        entries.push({
-          messageId: dedupeKey,
-          model: "cursor-agent-auto",
-          inputTokens,
-          outputTokens,
-          billableOutputTokens: outputTokens + reasoningTokens,
-          cachedTokens: 0,
-          cacheWriteTokens: 0,
-          timestamp: stat.mtimeMs,
-        });
-        if (entries.length >= LOCAL_COST_SCAN_MAX_ENTRIES) return entries;
-      }
-    } catch {
-      // Skip unreadable Cursor Agent transcripts.
-    }
-  }
-
-  return entries;
-}
-
-async function isSupportedCodexUsageSession(filePath: string): Promise<boolean> {
-  let file: fs.promises.FileHandle | null = null;
-  try {
-    file = await fs.promises.open(filePath, "r");
-    const buffer = Buffer.alloc(1024 * 1024);
-    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
-    const firstLine = buffer.subarray(0, bytesRead).toString("utf8").split(/\r?\n/, 1)[0]?.trim();
-    if (!firstLine) return false;
-    const entry = safeJsonParse<Record<string, unknown>>(firstLine, {});
-    if (entry.type !== "session_meta" || !isRecord(entry.payload)) return false;
-    const originator = normalizeUsageLabel(entry.payload.originator, "").toLowerCase();
-    return !originator.startsWith("ade");
-  } catch {
-    return false;
-  } finally {
-    await file?.close().catch(() => {});
-  }
-}
-
-async function findRecentFiles(dir: string, maxAgeDays: number, suffixes: string[]): Promise<string[]> {
-  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
-  const files: Array<{ path: string; mtimeMs: number }> = [];
-
-  async function walk(current: string, depth: number) {
-    if (depth > 6) return; // Prevent deep traversal
-    try {
-      const entries = await fs.promises.readdir(current, { withFileTypes: true });
-      const dirPromises: Promise<void>[] = [];
-      const fileStatPromises: Promise<void>[] = [];
-      for (const entry of entries) {
-        const fullPath = path.join(current, entry.name);
-        if (entry.isDirectory()) {
-          dirPromises.push(walk(fullPath, depth + 1));
-        } else if (suffixes.some((suffix) => entry.name.endsWith(suffix))) {
-          fileStatPromises.push(
-            fs.promises.stat(fullPath).then((stat) => {
-              if (stat.mtimeMs >= cutoff && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
-                files.push({ path: fullPath, mtimeMs: stat.mtimeMs });
-              }
-            }).catch(() => {
-              // Skip files we can't stat
-            })
-          );
-        }
-      }
-      await Promise.all([...dirPromises, ...fileStatPromises]);
-    } catch {
-      // Skip directories we can't read
-    }
-  }
-
-  await walk(dir, 0);
-  return files
-    .sort((a, b) => b.mtimeMs - a.mtimeMs)
-    .slice(0, LOCAL_COST_SCAN_MAX_FILES)
-    .map((file) => file.path);
-}
-
-async function findJsonlFiles(dir: string, maxAgeDays: number): Promise<string[]> {
-  return findRecentFiles(dir, maxAgeDays, [".jsonl"]);
-}
-
-async function findClaudeJsonlFilesInProjectDirs(projectDirs: string[], maxAgeDays: number): Promise<string[]> {
-  const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
-  const files = new Map<string, { path: string; mtimeMs: number }>();
-
-  async function addJsonlFilesInDir(dir: string): Promise<void> {
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    await Promise.all(entries
-      .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
-      .map(async (entry) => {
-        const filePath = path.join(dir, entry.name);
-        try {
-          const stat = await fs.promises.stat(filePath);
-          if (stat.mtimeMs >= cutoff && stat.size <= LOCAL_COST_SCAN_MAX_FILE_BYTES) {
-            files.set(filePath, { path: filePath, mtimeMs: stat.mtimeMs });
-          }
-        } catch {
-          // Skip files we can't stat
-        }
-      }));
-  }
-
-  for (const projectDir of projectDirs) {
-    const projectPath = projectDir;
-    await addJsonlFilesInDir(projectPath);
-    await addJsonlFilesInDir(path.join(projectPath, "subagents"));
-
-    let childEntries: fs.Dirent[];
-    try {
-      childEntries = await fs.promises.readdir(projectPath, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    await Promise.all(childEntries
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => addJsonlFilesInDir(path.join(projectPath, entry.name, "subagents"))));
-  }
-
-  return Array.from(files.values())
-    .slice(0, LOCAL_COST_SCAN_MAX_FILES)
-    .map((file) => file.path);
-}
-
-async function* readJsonlLines(filePath: string): AsyncGenerator<string> {
-  const stream = fs.createReadStream(filePath, { encoding: "utf8" });
-  const lines = createInterface({ input: stream, crlfDelay: Infinity });
-  try {
-    for await (const line of lines) {
-      yield line;
-    }
-  } finally {
-    lines.close();
-    stream.destroy();
-  }
-}
-
 function bucketDaily7d(entries: TokenEntry[], nowMs: number): number[] {
   const buckets = new Array<number>(7).fill(0);
   const todayStart = new Date(nowMs);
@@ -2036,7 +658,6 @@ function aggregateCosts(
   entries: TokenEntry[],
   provider: string,
 ): CostSnapshot {
-  const now = Date.now();
   const todayStart = new Date();
   todayStart.setHours(0, 0, 0, 0);
   const todayStartMs = todayStart.getTime();
diff --git a/apps/desktop/src/preload/global.d.ts b/apps/desktop/src/preload/global.d.ts
index 0a536d06b..9f142155b 100644
--- a/apps/desktop/src/preload/global.d.ts
+++ b/apps/desktop/src/preload/global.d.ts
@@ -168,6 +168,7 @@ import type {
   GetAdeUsageStatsArgs,
   UsageSnapshot,
   BudgetCheckResult,
+  BudgetCheckArgs,
   BudgetCapScope,
   BudgetCapProvider,
   BudgetCapConfig,
@@ -1033,11 +1034,7 @@ declare global {
         getAdeStats: (args?: GetAdeUsageStatsArgs) => Promise<AdeUsageStats | null>;
         getSnapshot: () => Promise<UsageSnapshot | null>;
         refresh: () => Promise<UsageSnapshot | null>;
-        checkBudget: (args: {
-          scope: BudgetCapScope;
-          scopeId?: string;
-          provider: BudgetCapProvider;
-        }) => Promise<BudgetCheckResult>;
+        checkBudget: (args: BudgetCheckArgs) => Promise<BudgetCheckResult>;
         getCumulativeUsage: (args: {
           scope: BudgetCapScope;
           scopeId?: string;
diff --git a/apps/desktop/src/preload/preload.ts b/apps/desktop/src/preload/preload.ts
index 67777bd78..9370aa139 100644
--- a/apps/desktop/src/preload/preload.ts
+++ b/apps/desktop/src/preload/preload.ts
@@ -542,6 +542,7 @@ import type {
   GetAdeUsageStatsArgs,
   UsageSnapshot,
   BudgetCheckResult,
+  BudgetCheckArgs,
   BudgetCapScope,
   BudgetCapProvider,
   BudgetCapConfig,
@@ -4069,11 +4070,7 @@ contextBridge.exposeInMainWorld("ade", {
       callProjectRuntimeActionOr("usage", "forceRefresh", {}, () =>
         ipcRenderer.invoke(IPC.usageRefresh),
       ),
-    checkBudget: async (args: {
-      scope: BudgetCapScope;
-      scopeId?: string;
-      provider: BudgetCapProvider;
-    }): Promise<BudgetCheckResult> =>
+    checkBudget: async (args: BudgetCheckArgs): Promise<BudgetCheckResult> =>
       callProjectRuntimeActionOr("budget", "checkBudget", { args }, () =>
         ipcRenderer.invoke(IPC.usageCheckBudget, args),
       ),
diff --git a/apps/desktop/src/shared/types/usage.ts b/apps/desktop/src/shared/types/usage.ts
index b16d340ce..0f55e8e77 100644
--- a/apps/desktop/src/shared/types/usage.ts
+++ b/apps/desktop/src/shared/types/usage.ts
@@ -332,6 +332,18 @@ export type BudgetCheckResult = {
   warnings: string[];
 };
 
+export type BudgetCheckContext = {
+  /** Usage records for `usd-per-run` are keyed to the active run, not the rule. */
+  runScopeId?: string | null;
+};
+
+export type BudgetCheckArgs = {
+  scope: BudgetCapScope;
+  scopeId?: string;
+  provider: BudgetCapProvider;
+  runScopeId?: string | null;
+};
+
 export type BudgetUsageRecord = {
   id: string;
   scope: BudgetCapScope;
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 72ebdac75..d5fff3756 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -474,8 +474,8 @@ Most services described here live under `apps/desktop/src/main/services/<domain>
 |--------|-----------|------|
 | `ai/` | `aiIntegrationService.ts`, `authDetector.ts`, `providerConnectionStatus.ts`, `claudeRuntimeProbe.ts`, `modelsDevService.ts`, `compactionEngine.ts`, `tools/*` | Provider routing, detection, tool definitions, compaction. |
 | `agentTools/` | `agentToolsService.ts` | Agent tool registry metadata surfaced to the renderer. |
-| `appControl/` | `appControlService.ts` | Chrome DevTools Protocol bridge for developer-owned Electron apps. Launches a chat-owned PTY running the user's dev command (or connects to an existing `--remote-debugging-port`), polls `/json` for ready CDP targets, attaches a long-lived `CdpClient` WebSocket, and exposes screenshot / DOM snapshot / hit-test / click / type / scroll / key dispatch / screencast frames. `inspectPoint` and `selectPoint` produce `AppControlContextItem`s for the chat composer (DOM packet + screenshot + source-file candidates resolved by `findSourceMatches` over an indexed tree of project source files). See [features/computer-use/app-control.md](./features/computer-use/app-control.md). |
-| `builtInBrowser/` | `builtInBrowserService.ts` | In-app web browser owned by the main process. Allocates `WebContentsView` tabs against the shared `persist:ade-browser` partition (cap 10), positions them over a renderer-supplied bounds rect, drives navigation / tabs / reload / back / forward, attaches the Chrome DevTools Protocol debugger for inspect-mode hit tests, captures screenshots, and emits `BuiltInBrowserEventPayload`s to subscribers. Consumed by `ChatBuiltInBrowserPanel` (Work sidebar Browser tab) and by `openUrlInAdeBrowser()` in the renderer so renderer-side link clicks open inside ADE rather than the system browser. |
+| `appControl/` | `appControlService.ts`, `appControlLaunchCommand.ts` | Chrome DevTools Protocol bridge for developer-owned Electron apps. Launches a chat-owned PTY running the user's dev command (or connects to an existing `--remote-debugging-port`), polls `/json` for ready CDP targets, attaches a long-lived `CdpClient` WebSocket, and exposes screenshot / DOM snapshot / hit-test / click / type / scroll / key dispatch / screencast frames. `appControlLaunchCommand.ts` owns the shell-command detection and debug-flag injection helpers for direct Electron and package-script launches. `inspectPoint` and `selectPoint` produce `AppControlContextItem`s for the chat composer (DOM packet + screenshot + source-file candidates resolved by `findSourceMatches` over an indexed tree of project source files). See [features/computer-use/app-control.md](./features/computer-use/app-control.md). |
+| `builtInBrowser/` | `builtInBrowserService.ts`, `builtInBrowserNavigation.ts`, `builtInBrowserPermissions.ts` | In-app web browser owned by the main process. Allocates `WebContentsView` tabs against the shared `persist:ade-browser` partition (cap 10), positions them over a renderer-supplied bounds rect, drives navigation / tabs / reload / back / forward, attaches the Chrome DevTools Protocol debugger for inspect-mode hit tests, captures screenshots, and emits `BuiltInBrowserEventPayload`s to subscribers. Navigation normalization and protocol allowlisting live in `builtInBrowserNavigation.ts`; Google-auth permission policy lives in `builtInBrowserPermissions.ts`. Consumed by `ChatBuiltInBrowserPanel` (Work sidebar Browser tab) and by `openUrlInAdeBrowser()` in the renderer so renderer-side link clicks open inside ADE rather than the system browser. |
 | `automations/` | `automationService.ts`, `automationPlannerService.ts`, `automationIngressService.ts`, `automationSecretService.ts` | Rule lifecycle, NL → rule planner, inbound triggers, per-rule secrets. |
 | `chat/` | `agentChatService.ts`, `runtimeEvents.ts`, `buildClaudeV2Message.ts`, `markdownSlashCommandDiscovery.ts`, `claudeSlashCommandDiscovery.ts`, `codexSlashCommandDiscovery.ts`, `cursorSlashCommandDiscovery.ts`, `projectSlashCommandDiscovery.ts`, `slashCommandPromptExpansion.ts`, `cursorSdk*` (`cursorSdkPool.ts`, `cursorSdkWorker.ts`, `cursorSdkProtocol.ts`, `cursorSdkPolicy.ts`, `cursorSdkSystemPrompt.ts`, `cursorSdkEventMapper.ts`), `sessionRecovery.ts` | Agent chat sessions (lane-scoped + orchestration worker/coordinator). Builds Claude messages, hosts the Cursor SDK in a Node worker pool, formalizes the cross-runtime event vocabulary, discovers and resolves provider-specific slash commands through a shared markdown engine, recovers sessions on restart, derives prompt-based lane names for parallel model launches, and manages Codex app-server goals with persisted, unlimited-budget session state. |
 | `computerUse/` | `computerUseArtifactBrokerService.ts`, `controlPlane.ts`, `localComputerUse.ts`, `agentBrowserArtifactAdapter.ts`, `syntheticToolResult.ts` | Proof-artifact broker (ingests, owner links, review state, routing), control-plane snapshot helpers, macOS capture capability descriptor, agent-browser payload parser, and the synthetic-tool-result helper used by the Claude compaction path. `proofObserver.ts` was removed in the rebuild — there is no passive auto-ingest. |
@@ -497,8 +497,8 @@ Most services described here live under `apps/desktop/src/main/services/<domain>
 | `lanes/` | `laneService.ts`, `laneEnvironmentService.ts`, `laneTemplateService.ts`, `laneProxyService.ts`, `portAllocationService.ts`, `autoRebaseService.ts`, `rebaseSuggestionService.ts`, `laneLaunchContext.ts`, `oauthRedirectService.ts`, `runtimeDiagnosticsService.ts` | Worktree lifecycle, env bootstrap, templates, reverse proxy, port leases, auto-rebase, suggestions, OAuth redirect, diagnostics. |
 | `logging/` | `logger.ts` | File-backed structured logger. |
 | `localRuntime/` | `localRuntimeConnectionPool.ts` | Desktop-side client for the local `ade serve` daemon. Spawns or attaches to the machine socket, registers local projects with `projects.add`, dispatches local runtime actions with per-call timeouts where needed, emits `local_runtime.action_slow` warn logs (with `ensureProjectMs` / `connectMs` / `daemonCallMs` breakdown) whenever a call exceeds 500 ms or throws, polls runtime events, and installs the background service best-effort in packaged builds. |
-| `macosVm/` | `macosVmService.ts`, `rfbDirectClient.ts`, `credentialsStore.ts`, `runtimeBootstrap.ts`, `macosVmRecovery.ts` | Lane-tied macOS VM lifecycle and GUI control. `macosVmService.ts` uses Lume, stores VM records in `.ade/cache`, mounts direct lane roots when safe (otherwise a sanitized rsync mirror), and exposes screenshot/click/type/select through headless VNC or visible-window fallbacks. `credentialsStore.ts` keeps guest user credentials in the macOS Keychain (`/usr/bin/security`, service `ade-macos-vm-<vmName>` / account `ade-cli`); renderers only see a summary. `runtimeBootstrap.ts` installs the in-guest ade-runtime over SSH+SCP with a five-phase progress signal (`ssh-probe`, `write-script`, `scp-script`, `run-script`, `verify-marker`). `macosVmRecovery.ts` is a standalone CLI cleanup path for stale records / lease / VNC credentials when the desktop surface cannot reach them. |
-| `onboarding/` | `onboardingService.ts` | First-run flow, defaults detection, existing lane discovery. |
+| `macosVm/` | `macosVmService.ts`, `macosVmStores.ts`, `rfbDirectClient.ts`, `credentialsStore.ts`, `runtimeBootstrap.ts`, `macosVmRecovery.ts` | Lane-tied macOS VM lifecycle and GUI control. `macosVmService.ts` uses Lume, mounts direct lane roots when safe (otherwise a sanitized rsync mirror), and exposes screenshot/click/type/select through headless VNC or visible-window fallbacks. `macosVmStores.ts` owns JSON persistence for VM records, the global lease, and VNC credentials. `credentialsStore.ts` keeps guest user credentials in the macOS Keychain (`/usr/bin/security`, service `ade-macos-vm-<vmName>` / account `ade-cli`); renderers only see a summary. `runtimeBootstrap.ts` installs the in-guest ade-runtime over SSH+SCP with a five-phase progress signal (`ssh-probe`, `write-script`, `scp-script`, `run-script`, `verify-marker`). `macosVmRecovery.ts` is a standalone CLI cleanup path for stale records / lease / VNC credentials when the desktop surface cannot reach them. |
+| `onboarding/` | `onboardingService.ts`, `onboardingSuggestedConfig.ts` | First-run flow, defaults detection, existing lane discovery. `onboardingSuggestedConfig.ts` contains pure workflow parsing and suggested `.ade/ade.yaml` generation. |
 | `opencode/` | `openCodeRuntime.ts`, `openCodeServerManager.ts`, `openCodeBinaryManager.ts`, `openCodeInventory.ts`, `openCodeModelCatalog.ts` | OpenCode server spawn, binary resolution, model discovery. |
 | `orchestration/` | `orchestrationService.ts`, `applyPatches.ts`, `patchPolicy.ts`, `manifestNormalization.ts`, `runtimeProfile.ts` | Work-tab orchestration for multi-phase plans. `orchestrationService` manages run lifecycle, manifest persistence, plan markdown, and asset bundles. `applyPatches` + `patchPolicy` handle lead/worker manifest patches with safety constraints. `runtimeProfile` resolves the active orchestration profile per session. The renderer surfaces live in `renderer/components/orchestration/` (see §7.3). The former `orchestrator/` and `missions/` directories were consolidated into this service. |
 | `processes/` | `processService.ts` | Managed-process lifecycle per lane, readiness probes, restart policies. |
@@ -508,13 +508,13 @@ Most services described here live under `apps/desktop/src/main/services/<domain>
 | `remoteRuntime/` | `remoteTargetRegistry.ts`, `sshTransport.ts`, `remoteBootstrap.ts`, `remoteConnectionPool.ts`, `remoteConnectionService.ts`, `runtimeRpcClient.ts`, `runtimeDiscovery.ts` | Saved SSH machines (manual host + alternate `routes[]` with `lastSucceededAt`), ssh-agent/key transport with ssh2 keepalive and multi-route fallback, first-connect runtime upload/version verification with channel-home fallback (`.ade` / `.ade-alpha` / `.ade-beta`) and capability/version skew demoted from fatal errors to `RemoteRuntimeConnectResult.compatibilityWarnings`, remote project catalog, action dispatch (with a `projects.*` capability gate against `RemoteRuntimeCapabilities.machineProjects`), reconnect/eviction with pool eviction listeners, `powerMonitor` resume probe, and LAN + Tailscale discovery that returns diagnostics alongside machines. The JSON-RPC client formats remote errors with the original method name plus the JSON-RPC `code` / `message` / `data` for clearer diagnostics. |
 | `runtime/` | `tempCleanupService.ts`, `processRegistryService.ts`, `machineStateMigration.ts` | Runtime temp cleanup. `processRegistryService` is the per-process heartbeat registrar against machine-local `runtime_processes` (see §3.4); reconcile/dispose paths in `sessionService` and `ptyService` consult live and known owner sets before sweeping `terminal_sessions` rows so sibling processes and synced remote-machine owners are preserved. `machineStateMigration` carries one-shot migrations of the per-machine state files under `~/.ade/`. |
 | `sessions/` | `sessionService.ts`, `sessionDeltaService.ts` | Terminal session CRUD, post-session delta computation. |
-| `shared/` | `utils.ts`, `queueRebase.ts`, `packLegacyUtils.ts`, `transcriptInsights.ts` | Cross-domain utilities. |
+| `shared/` | `utils.ts`, `imageDimensions.ts`, `queueRebase.ts`, `packLegacyUtils.ts`, `transcriptInsights.ts` | Cross-domain utilities, including shared record guards and PNG/JPEG dimension parsing used by App Control and iOS Simulator capture paths. |
 | `state/` | `kvDb.ts`, `crsqliteExtension.ts`, `globalState.ts`, `projectState.ts`, `onConflictAudit.ts` | SQLite schema + open, CRR extension loader, global state file, per-project state init. `globalState.upsertRecentProject` accepts `preserveRecentOrder` so reactivating an already-known project (by app focus, deep link, etc.) refreshes its `lastOpenedAt` in place instead of jumping it to the front of the recents list. `model_picker_favorites` and `model_picker_recents` are per-project CRR tables shared by desktop, TUI, and iOS; they are primary-key-only so CRR can convert them, with the recents cap enforced in `modelPickerStore.ts`. `AdeDb.sync.discardUnpublishedChangesForTables(tableNames)` lets a service clear local CRR state for specific tables without leaking those clears to sync peers — it records the cleared tables and `through_db_version` in the local-only `local_crr_change_suppressions` table, and `exportChangesSince` filters local-site rows for those tables at or below that version on the way out. The local-only excluded set (still kept out of replication) includes that suppression table itself, the snapshot caches, `pr_auto_link_ignores`, `pull_request_ai_summaries`, and `runtime_processes`. `crsql_changes` DELETE statements run through a helper that swallows the read-only-table error the cr-sqlite extension raises when a CRR-managed table is wiped, with a `db.crr_changes_cleanup_skipped` warn log instead of failing the migration. |
 | `sync/` | `syncService.ts`, `syncHostService.ts`, `syncPeerService.ts`, `syncRemoteCommandService.ts`, `syncProtocol.ts`, `deviceRegistryService.ts`, `syncPairingStore.ts` | **Thin delegation to the runtime daemon's sync host.** The authoritative sync host now lives in `apps/ade-cli/src/services/sync/`; the desktop main-process instances default to a non-host viewer role for legacy state and tests. The old in-process host is disabled unless `ADE_ENABLE_DESKTOP_SYNC_HOST=1` (diagnostics only). Wire formats — WebSocket envelope, remote command routing, device registry, pairing secrets — are the same across both implementations. Viewer joins clear the local `devices` + `sync_cluster_state` rows and then call `db.sync.discardUnpublishedChangesForTables(["devices", "sync_cluster_state"])` so the resulting DELETE rows do not leak back to other peers; the peer client follows up with `syncPeerService.acknowledgeLocalDbVersion()` to advance the outbound cursor past the suppressed range. |
 | `notifications/` | `apnsService.ts`, `apnsBridgeService.ts`, `notificationMapper.ts`, `notificationEventBus.ts` | APNs HTTP/2 client (ES256 JWT, key persisted via Electron `safeStorage` on the desktop or `EncryptedFileCredentialStore` under `.ade/secrets/` in the headless daemon), pure domain-event → `MappedNotification` mapping (13 categories / 4 families), event bus routing to APNs alert pushes + Live Activity update pushes + in-app WS delivery, filtered by per-device `NotificationPreferences`. `apnsBridgeService.ts` is the `notifications_apns` ADE action domain (`getStatus`, `saveConfig`, `uploadKey`, `clearKey`, `sendTestPush`) so the same Settings flow works whether the active project is local-bound or SSH-bound. |
 | `tests/` | `testService.ts` | Test-suite execution + run history. |
-| `updates/` | `autoUpdateService.ts` | Electron auto-update wrapper around `electron-updater`. Owns the renderer-visible `AutoUpdateSnapshot` (`idle \| checking \| downloading \| ready \| installing \| error`), uses `compareUpdateVersions` (SemVer-aware) to dedupe / supersede staged installers and to reconcile `pendingInstallUpdate` against the running version on next boot. `quitAndInstall()` is async: it re-runs `checkForUpdates({ allowReady: true })` to confirm the staged build is still latest, and only then flips to `installing` and calls `updater.quitAndInstall(false, true)`. |
-| `usage/` | `usageTrackingService.ts`, `budgetCapService.ts` | Token/cost accounting, budget enforcement. Local cost scans stream bounded recent Claude/Codex JSONL files instead of loading the whole history into memory. Threshold state is shared at module level across all `createUsageTrackingService` instances so multiple project contexts don't fire duplicate threshold events; `main.ts` adds a final IPC-level dedup gate with a 10-minute TTL per `provider:threshold:resetCycle` key. |
+| `updates/` | `autoUpdateService.ts` | Electron auto-update wrapper around `electron-updater`. Owns the renderer-visible `AutoUpdateSnapshot` (`idle \| checking \| downloading \| ready \| installing \| error`), uses `compareUpdateVersions` (SemVer-aware) to dedupe / supersede staged installers and to reconcile `pendingInstallUpdate` against the running version on next boot. Packaged builds schedule startup/periodic checks; source/dev launches construct the service without auto-check timers so missing `app-update.yml` never surfaces as a renderer error. `quitAndInstall()` is async: it re-runs `checkForUpdates({ allowReady: true })` to confirm the staged build is still latest, and only then flips to `installing` and calls `updater.quitAndInstall(false, true)`. |
+| `usage/` | `usageTrackingService.ts`, `budgetCapService.ts`, `ledgers/localUsageLedgers.ts` | Token/cost accounting, budget enforcement. `usageTrackingService.ts` owns polling, aggregation, pacing, GitHub stats, and cache orchestration; local provider ledger scanners live under `usage/ledgers/`. Budget caps can match a rule scope while `usd-per-run` evaluates usage records keyed to the active run id. Threshold state is shared at module level across all `createUsageTrackingService` instances so multiple project contexts don't fire duplicate threshold events; `main.ts` adds a final IPC-level dedup gate with a 10-minute TTL per `provider:threshold:resetCycle` key. |
 | `perf/` | `perfLog.ts`, `perfIpc.ts`, `metricsSampler.ts`, `aggregator.ts` | Opt-in local performance harness. `ADE_PERF_RUN_ID` opens a JSONL event log, samples Electron process metrics, records IPC durations, accepts renderer perf marks/web-vitals, and aggregates each run into `summary.json`. |
 
 Startup sequencing: every background service goes through `scheduleBackgroundProjectTask()` in `main.ts`, which provides explicit labels, `ADE_ENABLE_*` env gates, `project.startup_task_begin`/`_done`/`_enabled`/`_skipped` telemetry, and per-task delays. Integrations stay **dormant-until-configured**.
@@ -995,7 +995,7 @@ Post-packaging hardening (`apps/desktop/scripts/`):
 - **IPC tracing** — every handler emits `ipc.invoke.begin` / `ipc.invoke.done` / `ipc.invoke.failed` with call ID, channel, window ID, duration, summarized args. Mandatory for new handlers.
 - **Renderer lifecycle** — `renderer.route_change`, `renderer.tab_change`, `renderer.window_error`, `renderer.unhandled_rejection`, `renderer.event_loop_stall`. Mandatory for new surfaces that introduce novel lifecycle transitions.
 - **Startup tasks** — `project.startup_task_enabled`, `project.startup_task_skipped`, `project.startup_task_begin`, `project.startup_task_done` with durations.
-- **Usage tracking** — `usageTrackingService.ts` + `budgetCapService.ts` account for tokens and cost per provider/model/call-type; surfaced in the top-bar Usage popup (`HeaderUsageControl` → `UsageQuotaPanel` + collapsible `BudgetCapEditor`).
+- **Usage tracking** — `usageTrackingService.ts` + `usage/ledgers/*` + `budgetCapService.ts` account for tokens and cost per provider/model/call-type; surfaced in the top-bar Usage popup (`HeaderUsageControl` → `UsageQuotaPanel` + collapsible `BudgetCapEditor`).
 - **Local perf runs** — `scripts/perf-launch.mjs` / `scripts/run-perf-scenario.mjs` launch ADE with a run id, feed renderer scenarios, and collect JSONL events plus `summary.json` under `~/.ade/perf-runs/<runId>/`. This is local-only diagnostics, not external telemetry.
 - **No external telemetry** — ADE does not ship analytics to any cloud service. All telemetry is local.
 
diff --git a/docs/features/automations/guardrails.md b/docs/features/automations/guardrails.md
index d6bab2d05..9f550bac8 100644
--- a/docs/features/automations/guardrails.md
+++ b/docs/features/automations/guardrails.md
@@ -143,7 +143,7 @@ Automations also support rule-level caps:
 
 - `guardrails.maxDurationMin` — duration cap.
 - Billing codes (`billingCode`) flag spend so operators can slice usage by rule.
-- `budgetCapService` enforces hard caps at the project level; breaches pause runs with an intervention.
+- `budgetCapService` enforces hard caps at the project level; `usd-per-run` caps match the automation rule but evaluate usage records keyed to the active run id, so a prior run's spend does not block the next one. Breaches pause runs with an intervention.
 
 ## Audit trail
 
diff --git a/docs/features/chat/README.md b/docs/features/chat/README.md
index 542db18f8..60462faf4 100644
--- a/docs/features/chat/README.md
+++ b/docs/features/chat/README.md
@@ -14,7 +14,7 @@ machinery layered on top.
 | `apps/desktop/src/main/services/chat/agentChatService.ts` | Main service: session lifecycle, turn dispatch, event emission, provider adapters, steer queue, handoff, auto-title, prompt-derived lane-name suggestions for auto-created / parallel lanes, event-history snapshots, slash-command discovery/merge (delegates to per-provider discovery modules and `slashCommandPromptExpansion` for unified prompt expansion), and active-workload detection used by project/window close guards. Lane naming runs through the session-intelligence prompt path, retries the requested/configured/default title models, then falls back to a prompt slug with an optional temporary suffix for uniqueness. Tracks Fast Mode with the legacy `codexFastMode: boolean` session field for every provider whose descriptor advertises `serviceTiers: ["fast"]`; Codex forwards it as `serviceTier: "fast" \| null` on every `thread/start` and `turn/start` JSON-RPC call, while Cursor SDK sessions resolve it through discovered model parameters (see [Agent Routing](agent-routing.md#provider-service-tiers-fast-mode)). Codex chat goals are managed through the app-server `thread/goal/get` / `set` / `clear` RPCs, persisted in session summaries, validated to the provider's 4,000-character objective limit, and normalized to ADE's unlimited-budget policy by sending `tokenBudget: null` and clearing provider-reported budgets. `applyCodexEffectiveThreadState` accepts a `requestedCodexPolicy` option and uses `shouldPreserveRequestedCodexPolicy` to keep ADE-controlled picker selections authoritative when the lifecycle response echoes an older thread policy (prevents a manual Plan→Edit switch from snapping back); it also syncs the abstract `permissionMode` via `syncLegacyPermissionMode` after every policy application. Builds ADE guidance from the active lane worktree so Agent Skill roots are lane-scoped in persistent system/developer prompts and provider fallback injection. Spawns Claude/Codex agent runtimes with `buildAgentRuntimeEnv(managed)` so every agent process inherits `ADE_CHAT_SESSION_ID`, `ADE_LANE_ID`, `ADE_PROJECT_ROOT`, and `ADE_WORKSPACE_ROOT` (used by the agent guidance to call `ade --socket app-control logs` / `terminal read --chat-session "$ADE_CHAT_SESSION_ID"` without resolving the chat ID itself). When the session has Linear issues attached (`session_linear_issues`), `buildAgentRuntimeEnv` also materializes them into a per-session context file via `writeSessionLinearIssueContextFile` (`<contextDir>/<sessionId>/linear-issues.json`, written atomically; stale files cleared when nothing is attached) and sets `ADE_LINEAR_ISSUE_IDS` (comma-joined identifiers) + `ADE_LINEAR_CONTEXT_FILE` so the agent reads its issue context without Linear credentials. Attaching a `linear_issue` context attachment at run time calls `laneService.attachLinearIssueToSession({ chatSessionId, issues, role: "worked", source: "chat_attach", includeInPr: true })` so the link is persisted even for standalone (laneless) chats; when the session has a lane it additionally runs `laneService.linkLinearIssues` for the lane/PR-card semantics. See [Linear integration](../linear-integration/README.md#session-scoped-issue-attachment-and-cli-context-injection). Claude SDK sessions also resolve the executable through `claudeCodeExecutable.ts` and pass `pathToClaudeCodeExecutable` so packaged builds can prefer the bundled native binary before PATH/auth fallbacks; interrupted Claude turns call `stopTask` for active subagents before emitting stopped subagent results. Claude resume paths run `claudeThinkingTranscriptRepair` before loading a transcript, and the runtime self-heals the same corruption after the Anthropic thinking-block 400 error. Full-auto plan acceptance emits the same plan-mode exit notice as the manual approval path so the renderer composer chip can update even when the session refresh races with compaction. Cursor SDK setup records interrupts that arrive while the worker is still being acquired, releases the acquired generation if setup loses the race, and suppresses false provider-health failures for user-initiated setup interrupts. Cursor provider slash commands use a dedicated discovery path (`cursorSlashCommandDiscovery`) instead of falling through to the generic filesystem-backed list. Large service file. |
 | `apps/desktop/src/main/services/chat/runtimeEvents.ts` | Canonical cross-runtime event vocabulary (`turn.*`, `content.delta`, `tool.*`, `subagent.*`, teammate/task events, compaction boundaries) plus shims between legacy `AgentChatEvent` rows and the canonical runtime envelope. Claude emits canonical subagent events alongside the legacy rows while the other adapters migrate. |
 | `apps/ade-cli/src/tuiClient/` | Terminal **Work** chat TUI (Ink + React): same action/RPC contracts as desktop, **attached** (socket) or **embedded** (headless runtime via `ade-cli`). See [ADE Code](../ade-code/README.md). |
-| `apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts` | Main-process broker for the in-app web browser. Owns a single `persist:ade-browser` partition and one window-scoped browser service per ADE `BrowserWindow`, so each desktop window keeps its own `WebContentsView` tabs, active tab, bounds, visibility, inspect state, and targeted status events while sharing the authenticated browser partition. Each window service manages multiple tabs (cap 10), debugger-protocol attachment for inspect-mode hit tests, screenshot capture, and emission of `BuiltInBrowserContextItem`s for selected page elements. Window-open requests from a page are handled via `setWindowOpenHandler` returning `action: "allow"` + a `createWindow` factory: a new internal tab is created and its `webContents` is returned to Chromium so the popup keeps its real `window.opener` relationship with the opener tab (important for OAuth flows that postMessage back to the parent). The browser session runs with the standard Electron Chrome UA — no header rewriting — but its permission handlers allow a narrow set of Google sign-in capabilities (`hid`, `serial`, `usb`, `storage-access`, `top-level-storage-access`) for requests that originate at `accounts.google.com` so the Google flow's WebAuthn / storage-access probes do not bounce. All other permissions are denied. Backs the `ade.builtInBrowser.*` IPC surface and is consumed by both `ChatBuiltInBrowserPanel` (sidebar Browser tab) and `openExternal.ts` (links inside the renderer route through the built-in browser when the protocol is `http`/`https`/`about:blank`). |
+| `apps/desktop/src/main/services/builtInBrowser/builtInBrowserService.ts` | Main-process broker for the in-app web browser. Owns a single `persist:ade-browser` partition and one window-scoped browser service per ADE `BrowserWindow`, so each desktop window keeps its own `WebContentsView` tabs, active tab, bounds, visibility, inspect state, and targeted status events while sharing the authenticated browser partition. Each window service manages multiple tabs (cap 10), debugger-protocol attachment for inspect-mode hit tests, screenshot capture, and emission of `BuiltInBrowserContextItem`s for selected page elements. Window-open requests from a page are handled via `setWindowOpenHandler` returning `action: "allow"` + a `createWindow` factory: a new internal tab is created and its `webContents` is returned to Chromium so the popup keeps its real `window.opener` relationship with the opener tab (important for OAuth flows that postMessage back to the parent). Navigation normalization/protocol policy lives in `builtInBrowserNavigation.ts`; Google sign-in permission policy lives in `builtInBrowserPermissions.ts`. Backs the `ade.builtInBrowser.*` IPC surface and is consumed by both `ChatBuiltInBrowserPanel` (sidebar Browser tab) and `openExternal.ts` (links inside the renderer route through the built-in browser when the protocol is `http`/`https`/`about:blank`). |
 | `apps/desktop/src/shared/types/builtInBrowser.ts` | Cross-process types for the built-in browser: `BuiltInBrowserStatus`, `BuiltInBrowserTab`, `BuiltInBrowserContextItem` (`kind: "built_in_browser_element" | "built_in_browser_capture"`), `BuiltInBrowserSelectResult`, `BuiltInBrowserScreenshot`, `BuiltInBrowserOpenPanelArgs`, and the `BuiltInBrowserEventPayload` union (`status`, `open-request`, `selection`, `selection-cleared`, `error`). Navigate / create-tab / switch-tab args carry an optional `openPanel: boolean` so callers can ask for the Work sidebar Browser tab to flip open atomically with the navigation. |
 | `apps/desktop/src/main/services/chat/buildClaudeV2Message.ts` | Builds Claude SDK user messages for the `query()` input stream. Handles base64 image content blocks and MIME inference. |
 | `apps/desktop/src/main/services/chat/claudeInputPump.ts` | Async iterable input pump that feeds live user turns into the Claude Agent SDK `query()` stream. |
diff --git a/docs/features/computer-use/README.md b/docs/features/computer-use/README.md
index bad4a3933..d806a52ed 100644
--- a/docs/features/computer-use/README.md
+++ b/docs/features/computer-use/README.md
@@ -150,10 +150,12 @@ tap, and refuses to attach a persistent black frame as review context.
 Main process — `apps/desktop/src/main/services/macosVm/`:
 
 - `macosVmService.ts` — lifecycle owner. Lume `pull`/`create`/`run`/`stop`/`delete`
-  drivers, VM state file (`records.json`) and global single-VM lease
-  (`lease.json`) under `.ade/cache/macos-vms`, sanitized rsync mirror builder,
+  drivers, sanitized rsync mirror builder,
   noVNC display proxy with idle/max timeouts, RFB framebuffer wake heuristics,
   and the `ade.macosVm.event` push channel.
+- `macosVmStores.ts` — atomic JSON store helpers for VM records
+  (`records.json`), the global single-VM lease (`lease.json`), and
+  VNC credentials under `.ade/secrets`.
 - `rfbDirectClient.ts` — minimal direct-VNC client used for headless capture
   and input. Negotiates RFB, waits through transient black framebuffer updates,
   wakes the display with a pointer move + Shift tap, encodes the framebuffer
diff --git a/docs/features/computer-use/app-control.md b/docs/features/computer-use/app-control.md
index 9c4a12859..a51229a6f 100644
--- a/docs/features/computer-use/app-control.md
+++ b/docs/features/computer-use/app-control.md
@@ -18,7 +18,9 @@ App Control runs on the runtime that owns the project. The launch terminal, CDP
   - input: `click`, `typeText`, `scroll`, `dispatchKey`
   - launch terminal passthrough: `readTerminal`, `writeTerminal`, `signalTerminal`
   - screencast frames stream out via the `onEvent` channel (`type: "frame"`)
+- `appControlLaunchCommand.ts` — pure shell-command helpers for detecting direct Electron launches, detecting package-manager script launches, rewriting package scripts to inject App Control debug flags, and preserving the `{ADE_APP_CONTROL_DEBUG_FLAGS}` opt-in path.
 - `appControlService.test.ts` — service tests.
+- `appControlLaunchCommand.test.ts` — launch-command rewrite coverage.
 
 ### Shared types
 
@@ -131,7 +133,7 @@ Routine capture and input paths do not raise or normalize the external Electron
 
 ## Input
 
-- `click({ x, y, scale, coordinateSpace })` sends CDP `Input.dispatchMouseEvent` at viewport coordinates. The default coordinate space is `"screenshot"` for backwards-compatible CLI/API calls, and the renderer panel sends `"viewport"` so live-frame clicks land on the actual element under the pointer without any scale conversion. Screenshot-space coordinates are normalized to viewport space using independent x and y scale factors derived from the most recent `Page.screencastFrame` metadata (`deviceWidth` / image-width for x, `deviceHeight` / image-height for y), so non-uniform scaling (e.g. a resized window) does not skew click targets. `imageDimensions` extracts width/height from both PNG and JPEG screenshot buffers (JPEG parsing scans SOF markers). For hidden renderers, App Control tries `dispatchDomClick` first as a synthetic in-page fallback.
+- `click({ x, y, scale, coordinateSpace })` sends CDP `Input.dispatchMouseEvent` at viewport coordinates. The default coordinate space is `"screenshot"` for backwards-compatible CLI/API calls, and the renderer panel sends `"viewport"` so live-frame clicks land on the actual element under the pointer without any scale conversion. Screenshot-space coordinates are normalized to viewport space using independent x and y scale factors derived from the most recent `Page.screencastFrame` metadata (`deviceWidth` / image-width for x, `deviceHeight` / image-height for y), so non-uniform scaling (e.g. a resized window) does not skew click targets. Shared `services/shared/imageDimensions.ts` extracts width/height from both PNG and JPEG screenshot buffers (JPEG parsing scans SOF markers). For hidden renderers, App Control tries `dispatchDomClick` first as a synthetic in-page fallback.
 - `typeText({ text })` calls `Input.insertText`. `dispatchKey({ type, key, code, text, modifiers })` is the lower-level escape hatch for shortcuts and special keys.
 - `scroll({ x, y, deltaX, deltaY, coordinateSpace })` is `Input.dispatchMouseEvent` with `type: "mouseWheel"`.
 - All input calls go through a single shared `CdpClient` (`withCdp`) so the WebSocket isn't reopened per click; this measurably reduces input latency.
diff --git a/docs/features/onboarding-and-settings/README.md b/docs/features/onboarding-and-settings/README.md
index d81a2a42e..4ce506aa4 100644
--- a/docs/features/onboarding-and-settings/README.md
+++ b/docs/features/onboarding-and-settings/README.md
@@ -40,7 +40,7 @@ desktops see live lanes / chats / processes.
 Main process:
 
 - `apps/desktop/src/main/services/onboarding/onboardingService.ts` —
-  status, stack detection, suggested config, existing lane detection,
+  status, stack detection, existing lane detection,
   and tour progress tracking. `OnboardingTourProgress` carries the
   legacy flat per-tour map (`tours: Record<string, OnboardingTourEntry>`)
   plus a new variant-aware `tourVariants: Record<string,
@@ -51,6 +51,9 @@ Main process:
   `ctxSnapshot`). Glossary terms seen are tracked in
   `glossaryTermsSeen[]`. Persisted to `kvDb` under
   `onboarding:tourProgress`.
+- `apps/desktop/src/main/services/onboarding/onboardingSuggestedConfig.ts` —
+  pure GitHub Actions workflow parsing and suggested process/test/stack
+  config generation for `.ade/ade.yaml`.
 - `apps/desktop/src/main/services/config/projectConfigService.ts` —
   YAML config read/merge/save, AI mode migration, lane env init,
   Linear sync resolver. ~2,870 lines, the largest service.
@@ -273,7 +276,9 @@ Auto-update (top-bar control, not a settings tab):
   comparator that handles `v` prefixes, missing patch, and
   prerelease ordering) so a same-or-older `update-available` while a
   newer build is already staged is logged and ignored instead of
-  clobbering the staged installer; if the new build is strictly
+  clobbering the staged installer; packaged builds schedule startup and
+  periodic update checks, while dev/source launches leave those timers off
+  to avoid surfacing missing-updater-config errors; if the new build is strictly
   newer, the cached installer dir is wiped and the snapshot
   transitions back through `downloading`. `quitAndInstall()` is
   asynchronous: it gates on the current snapshot being `ready`,