Add sealed local history persistence

Introduce sealed local-history support and persistence for provider usage. Adds a HistoryStore API with Memory and SQLite implementations, payload composition/sealing, and helper utilities (days, payload, compose, seal). Integrates history into the engine: EngineService persists live scans, falls back to composed history on refresh failures, and accepts a history DB path (USAGEATLAS_HISTORY_DB) from the main process. Updates provider adapters to surface accountKey and history lookback, extends sqlite platform API, and updates renderer UI (provider marks/logos, model-mix) and styles. Adds tests for history behavior, updates contracts with HISTORY_* types/constants, docs (README/VISION), and CI checks for PostHog secrets.

Author: SRX9

.github/workflows/release-desktop.yml

@@ -21,9 +21,8 @@ permissions:
   contents: read
 
 env:
-  # Repository variables, not secrets: a PostHog project token is a public client key.
-  POSTHOG_PROJECT_TOKEN: ${{ vars.POSTHOG_PROJECT_TOKEN }}
-  POSTHOG_HOST: ${{ vars.POSTHOG_HOST }}
+  POSTHOG_PROJECT_TOKEN: ${{ secrets.POSTHOG_PROJECT_TOKEN }}
+  POSTHOG_HOST: ${{ secrets.POSTHOG_HOST || 'https://usageatlas.com/signals' }}
 
 jobs:
   gate:
@@ -202,6 +201,13 @@ jobs:
           bun-version-file: package.json
       - run: bun ci
       - run: bun run generate:desktop-icons
+      - name: Require PostHog token
+        shell: bash
+        run: |
+          if [ -z "${POSTHOG_PROJECT_TOKEN}" ]; then
+            echo "::error::Add repository secret POSTHOG_PROJECT_TOKEN."
+            exit 1
+          fi
       - name: Prepare signing
         shell: pwsh
         # An unsigned Windows build is allowed and announced; set WINDOWS_CERTIFICATE_BASE64 to sign.
@@ -270,6 +276,13 @@ jobs:
         with:
           bun-version-file: package.json
       - run: bun ci
+      - name: Require PostHog token
+        shell: bash
+        run: |
+          if [ -z "${POSTHOG_PROJECT_TOKEN}" ]; then
+            echo "::error::Add repository secret POSTHOG_PROJECT_TOKEN."
+            exit 1
+          fi
       - name: Generate macOS icon
         shell: bash
         run: |
@@ -361,6 +374,13 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y fakeroot rpm squashfs-tools xvfb fuse3
       - run: bun ci
+      - name: Require PostHog token
+        shell: bash
+        run: |
+          if [ -z "${POSTHOG_PROJECT_TOKEN}" ]; then
+            echo "::error::Add repository secret POSTHOG_PROJECT_TOKEN."
+            exit 1
+          fi
       - run: bun run desktop:make -- --platform=linux --arch=${{ matrix.arch }}
       - name: Packaged smoke test
         shell: bash

README.md

@@ -58,13 +58,16 @@ handling, and deterministic adapter tests.
 - Usage alerts that fire a native notification before you run into a limit
 - Tray presence, launch at login, and system/light/dark themes
 - Local-first: no account, no sync, and no usage data leaves the machine
+- Sealed local history: completed days are stored on disk so past usage survives restarts and provider outages
 - Sandboxed renderer with no Node.js access, an allowlisted preload API, ASAR integrity, and Electron fuses
 
 ## Privacy
 
-Provider data is read from local files and provider APIs, cached in memory, and written nowhere else. There is no
-UsageAtlas account and no cloud sync. An anonymous install count tells us how many people use the app; it never
-includes usage figures and can be switched off in Settings. Diagnostics are redacted before they are shown or copied.
+Provider data is read from local files and provider APIs. Completed-day usage and capacity
+snapshots are sealed into a local history database in the app data directory. There is no
+UsageAtlas account and no cloud sync. An anonymous install count tells us how many people use
+the app; it never includes usage figures and can be switched off in Settings. Diagnostics are
+redacted before they are shown or copied.
 
 ## Build from source
 

VISION.md

@@ -5,3 +5,5 @@ UsageAtlas is a secure, cross-platform desktop command center for AI-provider ca
 Prefer working provider coverage over a large placeholder catalog. New providers should reuse the shared dashboard
 contract and engine services, require no provider-specific renderer privileges, and arrive with deterministic fixtures.
 Keep the application local-first, responsive, dependency-light, and honest about provider and platform capability.
+Completed local days should be sealed on disk so history survives restarts and provider failures, with an optional
+remote sync path designed as a later plug-in rather than a required account.

apps/desktop/src/engine/analytics/local-usage.ts

@@ -27,6 +27,7 @@ export type AnalyticsProvider = "codex" | "claude";
 export interface AnalyticsScanContext {
   signal: AbortSignal;
   now: Date;
+  historyDays?: number;
 }
 
 export interface AnalyticsScanner {
@@ -141,6 +142,7 @@ export class LocalUsageScanner implements AnalyticsScanner {
 
   async scan(provider: AnalyticsProvider, context: AnalyticsScanContext): Promise<LocalUsageAnalytics> {
     context.signal.throwIfAborted();
+    const historyDays = clampInteger(context.historyDays ?? this.historyDays, 1, 366);
     const catalog = this.pricingCatalogLoader
       ? await this.pricingCatalogLoader(context).catch(() => emptyPricingCatalog())
       : emptyPricingCatalog();
@@ -177,7 +179,7 @@ export class LocalUsageScanner implements AnalyticsScanner {
     await Promise.all(workers);
     context.signal.throwIfAborted();
     if (unreadableFiles > 0 && unreadableFiles === discovery.files.length) {
-      return unavailableAnalytics(context.now, this.historyDays, {
+      return unavailableAnalytics(context.now, historyDays, {
         code: "analytics_unavailable",
         message: "Local session analytics could not read the available logs.",
         retryable: true
@@ -196,7 +198,7 @@ export class LocalUsageScanner implements AnalyticsScanner {
     return buildAnalytics(
       records,
       context.now,
-      this.historyDays,
+      historyDays,
       discovery.files.length,
       gapMessage !== null,
       "local_sessions",

apps/desktop/src/engine/analytics/opencode-usage.ts

@@ -68,22 +68,23 @@ export class OpenCodeUsageScanner {
     return await fileExists(this.locations.database) || await fileExists(this.locations.auth);
   }
 
-  async scan(context: { signal: AbortSignal; now: Date }): Promise<OpenCodeUsageSnapshot> {
+  async scan(context: { signal: AbortSignal; now: Date; historyDays?: number }): Promise<OpenCodeUsageSnapshot> {
     context.signal.throwIfAborted();
     if (!await fileExists(this.locations.database)) {
       throw new ProviderError(
         "credentials_missing",
         "OpenCode local data was not found. Run OpenCode once, then refresh."
       );
     }
+    const historyDays = clampInteger(context.historyDays ?? this.historyDays, 1, 366);
     const parsed = this.readRecords(context.signal);
     const hasGoAuth = await hasOpenCodeGoAuth(this.locations.auth);
     const hasGoPlan = hasGoAuth || parsed.records.some((record) => record.serviceTier === "opencode-go");
     return {
       analytics: buildAnalytics(
         parsed.records,
         context.now,
-        this.historyDays,
+        historyDays,
         1,
         parsed.partial
       ),

apps/desktop/src/engine/analytics/provider-analytics.ts

@@ -12,7 +12,7 @@ export async function scanProviderAnalytics(
     return await scanner.scan(provider, context);
   } catch {
     if (context.signal.aborted) throw new DOMException("Analytics scan timed out.", "AbortError");
-    return unavailableAnalytics(context.now, 90, {
+    return unavailableAnalytics(context.now, context.historyDays ?? 90, {
       code: "analytics_unavailable",
       message: "Local session analytics could not be refreshed.",
       retryable: true

apps/desktop/src/engine/engine-entry.ts

@@ -1,4 +1,5 @@
 import { EngineService } from "./engine-service";
+import { MemoryHistoryStore, SqliteHistoryStore, type HistoryStore } from "./history";
 import {
   createEngineReadyMessage,
   EngineRequestError,
@@ -10,7 +11,8 @@ import { createProviderAdapters } from "./providers/registry";
 const port = process.parentPort;
 if (!port) throw new Error("Engine utility process parent port is unavailable");
 
-const engine = new EngineService(createProviderAdapters());
+const history = openHistoryStore(process.env.USAGEATLAS_HISTORY_DB);
+const engine = new EngineService(createProviderAdapters(), () => new Date(), history);
 let queue = Promise.resolve();
 
 port.on("message", (event) => {
@@ -39,6 +41,20 @@ port.on("message", (event) => {
 
 port.postMessage(createEngineReadyMessage());
 
+function openHistoryStore(databasePath: string | undefined): HistoryStore {
+  if (!databasePath?.trim()) return new MemoryHistoryStore();
+  try {
+    return SqliteHistoryStore.open(databasePath.trim());
+  } catch (error) {
+    process.stderr.write(
+      `History store unavailable; continuing without persistence (${
+        error instanceof Error ? error.message : "open failed"
+      })\n`
+    );
+    return new MemoryHistoryStore();
+  }
+}
+
 function requestID(value: unknown): string {
   if (!value || typeof value !== "object" || Array.isArray(value)) return "invalid";
   const id = (value as Record<string, unknown>).id;