ship: prepare lane for review (automate + finalize passes)

- automate: extend ade-cli/cli.test.ts with 5 cases for the new
  `ade usage snapshot|refresh|budget` plan (123 → 123 incl. usage paths).
- automate: refresh docs/ARCHITECTURE.md telemetry pointer to the
  header Usage popup (HeaderUsageControl + UsageQuotaPanel).
- finalize/simplify: extract `finiteOrZero` for the Cursor spend
  reducers, flatten the cursorBlocker ternary into an if/else cascade,
  collapse the inline budget-set try block, drop unnecessary useMemo
  + try/catch on the ipc unsubscribe callbacks, replace nested
  ternaries in ExtraUsageCard / AuthChip / fillColor with explicit
  branches.
- finalize/cli-parity: add `ade usage` examples to apps/ade-cli/README
  CLI surface inventory.

Local gate: typecheck (desktop/ade-cli/web), eslint, vitest shards 1-8,
and ade-cli tests all green.

Author: arul28

apps/ade-cli/README.md

@@ -87,6 +87,12 @@ ade --socket macos-vm click --lane lane-id --x 120 --y 420 --text
 ade --socket update status --text
 ade --socket update check --text
 ade --socket update install --text
+ade usage snapshot --text
+ade usage refresh --text
+ade usage budget get --text
+ade usage budget set --from-file budget.json
+ade usage budget check --provider claude --scope global
+ade usage budget cumulative --scope global --text
 ade actions list
 ade actions run git.stageFile --arg laneId=lane-id --arg path=src/index.ts
 ade cursor cloud agents list --text

apps/ade-cli/src/cli.test.ts

@@ -2641,4 +2641,89 @@ describe("ADE CLI", () => {
     expect((summarized as any).visual).toContain("\\- main (id: main) [main]");
     expect((summarized as any).visual).toContain("\\- child (id: child) [feature]");
   });
+
+  it("usage snapshot routes to the usage.getUsageSnapshot action with no args", () => {
+    const plan = buildCliPlan(["usage", "snapshot"]);
+    expect(plan.kind).toBe("execute");
+    if (plan.kind !== "execute") return;
+    expect(plan.label).toBe("usage snapshot");
+    expect(plan.steps).toHaveLength(1);
+    expect(plan.steps[0]?.params).toEqual({
+      name: "run_ade_action",
+      arguments: { domain: "usage", action: "getUsageSnapshot", args: {} },
+    });
+
+    // The `quota`/`quotas` aliases must dispatch to the same plan.
+    const aliased = buildCliPlan(["quota", "snapshot"]);
+    expect(aliased.kind).toBe("execute");
+    if (aliased.kind !== "execute") return;
+    expect(aliased.steps[0]?.params).toEqual(plan.steps[0]?.params);
+  });
+
+  it("usage refresh routes to the usage.forceRefresh action", () => {
+    const plan = buildCliPlan(["usage", "refresh"]);
+    expect(plan.kind).toBe("execute");
+    if (plan.kind !== "execute") return;
+    expect(plan.label).toBe("usage refresh");
+    expect(plan.steps).toHaveLength(1);
+    expect(plan.steps[0]?.params).toEqual({
+      name: "run_ade_action",
+      arguments: { domain: "usage", action: "forceRefresh", args: {} },
+    });
+    // `poll` is the documented alias.
+    const polled = buildCliPlan(["usage", "poll"]);
+    expect(polled.kind).toBe("execute");
+    if (polled.kind !== "execute") return;
+    expect(polled.steps[0]?.params).toEqual(plan.steps[0]?.params);
+  });
+
+  it("usage budget get routes to the budget.getConfig action", () => {
+    const plan = buildCliPlan(["usage", "budget", "get"]);
+    expect(plan.kind).toBe("execute");
+    if (plan.kind !== "execute") return;
+    expect(plan.label).toBe("usage budget get");
+    expect(plan.steps).toHaveLength(1);
+    expect(plan.steps[0]?.params).toEqual({
+      name: "run_ade_action",
+      arguments: { domain: "budget", action: "getConfig", args: {} },
+    });
+  });
+
+  it("usage budget set --from-file parses the JSON body and forwards it as args", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "ade-cli-usage-budget-"));
+    const budgetPath = path.join(root, "budget.json");
+    const config = { caps: [{ provider: "claude", scope: "global", limitUsd: 25 }] };
+    fs.writeFileSync(budgetPath, JSON.stringify(config));
+
+    const plan = buildCliPlan(["usage", "budget", "set", "--from-file", budgetPath]);
+    expect(plan.kind).toBe("execute");
+    if (plan.kind !== "execute") return;
+    expect(plan.label).toBe("usage budget update");
+    expect(plan.steps[0]?.params).toEqual({
+      name: "run_ade_action",
+      arguments: { domain: "budget", action: "updateConfig", args: config },
+    });
+
+    // Empty body must surface as a CLI usage error, not silently send `{}`.
+    expect(() => buildCliPlan(["usage", "budget", "set", "--text", "[1,2,3]"]))
+      .toThrow(/must be a JSON object/i);
+  });
+
+  it("usage budget check defaults scope to global and forwards --provider", () => {
+    const plan = buildCliPlan(["usage", "budget", "check", "--provider", "claude"]);
+    expect(plan.kind).toBe("execute");
+    if (plan.kind !== "execute") return;
+    expect(plan.label).toBe("usage budget check");
+    expect(plan.steps[0]?.params).toEqual({
+      name: "run_ade_action",
+      arguments: {
+        domain: "budget",
+        action: "checkBudget",
+        args: { scope: "global", scopeId: null, provider: "claude" },
+      },
+    });
+
+    expect(() => buildCliPlan(["usage", "budget", "bogus"]))
+      .toThrow(/usage budget supports get, set, check, or cumulative/);
+  });
 });

apps/ade-cli/src/cli.ts

@@ -3673,10 +3673,12 @@ function buildUsagePlan(args: string[]): CliPlan {
     }
     if (mode === "set" || mode === "update") {
       const text = readFileTextInput(args);
-      let parsed: unknown = null;
-      if (text != null && text.trim().length > 0) {
-        try { parsed = JSON.parse(text); }
-        catch (error) {
+      const hasInlineBody = text != null && text.trim().length > 0;
+      let parsed: unknown;
+      if (hasInlineBody) {
+        try {
+          parsed = JSON.parse(text);
+        } catch (error) {
           throw new CliUsageError(`Failed to parse budget config: ${error instanceof Error ? error.message : String(error)}`);
         }
       } else {

apps/desktop/src/main/services/ai/providerConnectionStatus.ts

@@ -186,9 +186,10 @@ export async function buildProviderConnections(
   }
   const cursorSdkAuth = Boolean(cursorEnvAuth || cursorStoredAuth);
   const cursorUsageAuth = Boolean(cursorSdkAuth || cursorAdminEnvAuth);
-  let cursorCredsSource: "cursor-env" | "cursor-api-key-store" | undefined;
+  let cursorCredsSource: "cursor-env" | "cursor-api-key-store" | "cursor-admin-env" | undefined;
   if (cursorEnvAuth) cursorCredsSource = "cursor-env";
   else if (cursorStoredAuth) cursorCredsSource = "cursor-api-key-store";
+  else if (cursorAdminEnvAuth) cursorCredsSource = "cursor-admin-env";
   // Runtime is bundled with the app — it always exists. Only auth-related
   // fields should depend on whether a Cursor API key is present.
   const cursorFlags = {
@@ -200,13 +201,16 @@ export async function buildProviderConnections(
     runtimeAvailable: cursorSdkAuth,
   };
 
-  const cursorBlocker: string | null = cursorSdkAuth
-    ? null
-    : cursorAdminEnvAuth
-      ? "Cursor Admin API key is configured for usage; add a Cursor agent API key for Cursor runtime access."
-    : cursorStoreUnavailable
-      ? "ADE could not read the Cursor API key store yet. Retry after the key store is ready."
-      : "Enter a Cursor API key from https://cursor.com/dashboard/integrations.";
+  let cursorBlocker: string | null;
+  if (cursorSdkAuth) {
+    cursorBlocker = null;
+  } else if (cursorAdminEnvAuth) {
+    cursorBlocker = "Cursor Admin API key is configured for usage; add a Cursor agent API key for Cursor runtime access.";
+  } else if (cursorStoreUnavailable) {
+    cursorBlocker = "ADE could not read the Cursor API key store yet. Retry after the key store is ready.";
+  } else {
+    cursorBlocker = "Enter a Cursor API key from https://cursor.com/dashboard/integrations.";
+  }
 
   const cursor: AiProviderConnectionStatus = {
     ...createUnavailableStatus("cursor", checkedAt),
@@ -219,7 +223,7 @@ export async function buildProviderConnections(
       {
         kind: "local-credentials",
         detected: cursorUsageAuth,
-        source: cursorCredsSource ?? (cursorAdminEnvAuth ? "cursor-admin-env" : undefined),
+        source: cursorCredsSource,
       },
       {
         kind: "cli",

apps/desktop/src/main/services/usage/usageTrackingService.ts

@@ -285,10 +285,13 @@ function getCursorApiKey(): { key: string; source: "cursor-admin-env" | "cursor-
   return null;
 }
 
+function finiteOrZero(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
 function addOneMonth(timestampMs: number): number {
-  const date = new Date(timestampMs);
-  if (!Number.isFinite(date.getTime())) return 0;
-  const next = new Date(date.getTime());
+  const next = new Date(timestampMs);
+  if (!Number.isFinite(next.getTime())) return 0;
   next.setMonth(next.getMonth() + 1);
   return next.getTime();
 }
@@ -300,40 +303,30 @@ function parseCursorSpendUsage(data: CursorSpendResponse): {
   const members = Array.isArray(data.teamMemberSpend) ? data.teamMemberSpend : [];
   if (members.length === 0) return { windows: [], extraUsage: null };
 
+  // overallSpendCents = on-demand + included usage (the real total spend);
+  // spendCents alone captures only on-demand pay-as-you-go.
   const memberSpendCents = (member: CursorSpendMember): number => {
-    // overallSpendCents = on-demand + included usage (the real total spend)
-    // spendCents alone captures only on-demand pay-as-you-go.
-    const overall = typeof member.overallSpendCents === "number" && Number.isFinite(member.overallSpendCents)
-      ? member.overallSpendCents
-      : null;
-    if (overall != null) return overall;
-    return typeof member.spendCents === "number" && Number.isFinite(member.spendCents) ? member.spendCents : 0;
+    if (typeof member.overallSpendCents === "number" && Number.isFinite(member.overallSpendCents)) {
+      return member.overallSpendCents;
+    }
+    return finiteOrZero(member.spendCents);
   };
+  // hardLimitOverrideDollars is the per-user override; fall back to the
+  // team-wide monthlyLimitDollars when no override is configured.
   const memberLimitCents = (member: CursorSpendMember): number => {
-    // hardLimitOverrideDollars is the per-user override; fall back to the
-    // team-wide monthlyLimitDollars when no override is configured.
-    const override =
-      typeof member.hardLimitOverrideDollars === "number" && Number.isFinite(member.hardLimitOverrideDollars) && member.hardLimitOverrideDollars > 0
-        ? member.hardLimitOverrideDollars
-        : 0;
-    if (override > 0) return override * 100;
-    const monthly =
-      typeof member.monthlyLimitDollars === "number" && Number.isFinite(member.monthlyLimitDollars) && member.monthlyLimitDollars > 0
-        ? member.monthlyLimitDollars
-        : 0;
-    return monthly > 0 ? monthly * 100 : 0;
+    const overrideDollars = finiteOrZero(member.hardLimitOverrideDollars);
+    if (overrideDollars > 0) return overrideDollars * 100;
+    const monthlyDollars = finiteOrZero(member.monthlyLimitDollars);
+    return monthlyDollars > 0 ? monthlyDollars * 100 : 0;
   };
 
   const totalSpendCents = members.reduce((sum, member) => sum + memberSpendCents(member), 0);
   const totalLimitCents = members.reduce((sum, member) => sum + memberLimitCents(member), 0);
 
-  const cycleStartMs =
-    typeof data.subscriptionCycleStart === "number" && Number.isFinite(data.subscriptionCycleStart)
-      ? data.subscriptionCycleStart
-      : 0;
+  const cycleStartMs = finiteOrZero(data.subscriptionCycleStart);
   const resetMs = cycleStartMs > 0 ? addOneMonth(cycleStartMs) : 0;
   const resetsAt = resetMs > 0 ? new Date(resetMs).toISOString() : "";
-  const windowDurationMs = resetMs > 0 && cycleStartMs > 0 ? Math.max(0, resetMs - cycleStartMs) : undefined;
+  const windowDurationMs = resetMs > 0 ? Math.max(0, resetMs - cycleStartMs) : undefined;
 
   const windows: UsageWindow[] = [];
   const utilization = totalLimitCents > 0 ? Math.min(100, (totalSpendCents / totalLimitCents) * 100) : null;

apps/desktop/src/renderer/components/usage/HeaderUsageControl.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { CaretDown, CaretRight, Gauge, X } from "@phosphor-icons/react";
 import type {
   BudgetCapConfig,
@@ -73,11 +73,7 @@ export function HeaderUsageControl() {
     });
     return () => {
       cancelled = true;
-      try {
-        unsubscribe();
-      } catch {
-        // noop
-      }
+      unsubscribe();
     };
   }, []);
 
@@ -124,7 +120,7 @@ export function HeaderUsageControl() {
 
   const percent = summaryPercent(snapshot);
   const hasErrors = (snapshot?.errors.length ?? 0) > 0;
-  const tone = useMemo(() => usageTone(percent, hasErrors), [hasErrors, percent]);
+  const tone = usageTone(percent, hasErrors);
   const title = summaryTitle(snapshot, percent, hasErrors);
   const showDot = percent > 0 || hasErrors;
 

apps/desktop/src/renderer/components/usage/UsageQuotaPanel.tsx

@@ -130,14 +130,8 @@ export function UsageQuotaPanel({
   useEffect(() => {
     void load();
     if (!window.ade?.usage) return;
-    const unsubscribe = window.ade.usage.onUpdate((nextSnapshot) => applySnapshot(nextSnapshot));
-    return () => {
-      try {
-        unsubscribe();
-      } catch {
-        // noop
-      }
-    };
+    const unsubscribe = window.ade.usage.onUpdate(applySnapshot);
+    return unsubscribe;
   }, [applySnapshot, load]);
 
   useEffect(() => {
@@ -306,7 +300,9 @@ function ExtraUsageCard({ extra }: { extra: ExtraUsage }) {
   const usedUsd = extra.usedCreditsUsd;
   const limitUsd = extra.monthlyLimitUsd;
   const percent = limitUsd > 0 ? Math.min(100, (usedUsd / limitUsd) * 100) : 0;
-  const fillColor = percent > 90 ? "#EF4444" : percent > 70 ? "#F59E0B" : meta.color;
+  let fillColor = meta.color;
+  if (percent > 90) fillColor = "#EF4444";
+  else if (percent > 70) fillColor = "#F59E0B";
 
   const formatUsd = (v: number) => v.toLocaleString("en-US", { style: "currency", currency: extra.currency.toUpperCase() });
 
@@ -353,11 +349,15 @@ function AuthChip({
   label: string;
   entry: AiProviderConnectionStatus | null;
 }) {
-  const tone = entry?.runtimeAvailable
-    ? { border: "rgba(34,197,94,0.3)", bg: "rgba(34,197,94,0.12)", text: "#22C55E", copy: "runtime ready" }
-    : entry?.authAvailable
-      ? { border: "rgba(59,130,246,0.3)", bg: "rgba(59,130,246,0.12)", text: "#60A5FA", copy: entry.runtimeDetected ? "sign-in required" : "auth found locally" }
-      : { border: "rgba(113,113,122,0.3)", bg: "rgba(113,113,122,0.12)", text: "#A1A1AA", copy: "not detected" };
+  let tone: { border: string; bg: string; text: string; copy: string };
+  if (entry?.runtimeAvailable) {
+    tone = { border: "rgba(34,197,94,0.3)", bg: "rgba(34,197,94,0.12)", text: "#22C55E", copy: "runtime ready" };
+  } else if (entry?.authAvailable) {
+    const copy = entry.runtimeDetected ? "sign-in required" : "auth found locally";
+    tone = { border: "rgba(59,130,246,0.3)", bg: "rgba(59,130,246,0.12)", text: "#60A5FA", copy };
+  } else {
+    tone = { border: "rgba(113,113,122,0.3)", bg: "rgba(113,113,122,0.12)", text: "#A1A1AA", copy: "not detected" };
+  }
 
   return (
     <div

docs/ARCHITECTURE.md

@@ -1015,7 +1015,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 Missions UI + Settings.
+- **Usage tracking** — `usageTrackingService.ts` + `budgetCapService.ts` account for tokens and cost per provider/model/call-type; surfaced in Missions UI and the top-bar Usage popup (`HeaderUsageControl` → `UsageQuotaPanel` + collapsible `BudgetCapEditor`).
 - **No external telemetry** — ADE does not ship analytics to any cloud service. All telemetry is local.
 
 ### 15.3 Error surfaces