sidekick-shared 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ All notable changes to sidekick-shared will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.26.0] - 2026-09-05
+
+### Added
+
+- `summarizeTokens()`, `sumTokenTotals()`, `TOKEN_TOTAL_LABEL`, and `TOKEN_CONTEXT_LABEL` define the one token vocabulary every Sidekick surface uses: `total` is input + output + cache writes + cache reads, `context` is input + cache; browser-safe
+- `AggregatedTokens` gains `costUsd`, `costProvenance` (`reported` | `estimated` | `mixed` | `unpriced` | `none`), `reportedCostUsd`, `estimatedCostUsd`, and `unpricedCalls`; `describeCostProvenance()` and `classifyCostProvenance()` are exported; `CanonicalSessionTranscript.usage` adds `pricedCostUsd` and `unpricedEvents` (schema updated)
+- `parseClaudeStatuslinePayload()` and `quotaFromStatuslinePayload()` (also on the `sidekick-shared/statusline` subpath, which now exports `writeQuotaSnapshot`, `appendQuotaHistorySample`, and `getWorkspaceIdFromPath`) read the JSON Claude Code pipes to a status-line command; `QuotaState.source` and quota-history samples accept `statusline`
+- `formatStatusline({ live })` renders context %, session cost, prompt-cache hit rate, the seven-day window, and the snapshot age when it is older than five minutes
+- `readQuotaSnapshot()` reports `ageMs` and `freshness`; `classifyQuotaFreshness()`, `formatQuotaAge()`, `QUOTA_FRESH_MAX_AGE_MS`, and `QUOTA_AGING_MAX_AGE_MS` are exported and the quota schema accepts the new fields
+- `getScheduledPeakHoursState()`, `PEAK_HOURS_DESCRIPTION`, `PEAK_HOURS_CACHE_MS`, and `PeakHoursState.source` (`promoclock` | `schedule`); `fetchPeakHoursStatus({ force })` bypasses the ten-minute cache
+- `evaluateQuotaThresholds()`, `describeQuotaThresholdAlert()`, and `DEFAULT_QUOTA_THRESHOLDS` for once-per-reset-window threshold alerts
+- `formatLocalDateKey()`, `parseLocalDateKey()`, and `addLocalDays()` (root and browser entry points); `hydratePricingCatalog({ offline })`; `pruneSnapshots()` and `MAX_SNAPSHOT_FILES`; `getActiveAccountStatus(error, { selfHeal })`, mirrored on `resolveActiveClaudeAccount()` and `resolveActiveCodexAccount()`; `_resetProviderDetectionCache()` and `_resetPeakHoursCache()` for tests
+- `resolveQuota({ providerId, workspacePath, preferFresh, allowApi, … })` resolves Claude, Codex, or z.ai quota with one precedence — a persisted sample younger than `QUOTA_FRESH_MAX_AGE_MS` (any origin), then session logs, then the provider API (persisted on success), then an aging or stale sample with the API failure attached — returning `ResolvedQuota` with `resolution`, `source`, `capturedSource`, `freshness`, and `ageMs`; every side effect is injectable
+- `QuotaState.capturedSource` (`api` | `session` | `statusline`) records where a cached sample came from; `readQuotaSnapshot()` fills it and `writeQuotaSnapshot()` preserves it instead of storing `cache`; the quota schema accepts it; `QuotaSnapshotRecord`, `enrichCodexQuota()`, and `enrichZaiQuota()` are exported; `fetchQuota(token, { fetchImpl })` accepts an injected fetch
+- `computeSessionFileStats(events, options)` and `readSessionFileStats(provider, sessionPath, { resolveLabel })` compute `SessionFileStats` for every provider over the shared `EventAggregator`; `firstUserPrompt(events)` derives a session label from events already in memory. `SessionFileStats` gains `availability` (`full` | `partial` | `unavailable`), `unavailableReason`, `costUsd`, `costProvenance`, `unpricedCalls`, and `toolFailures`; `reportedCost` is deprecated (same value as `costUsd`)
+- `collectUsageEvents({ providers, since, until, workspacePath })` reads every session touched in a window once through its provider reader and returns priced usage events, caching raw token counts per session under `<configDir>/usage-cache/` keyed by size and mtime (priced at load, so a catalog refresh never leaves stale costs); `pruneUsageCache()`, `getUsageCacheDir()`, `USAGE_CACHE_VERSION`, and `MAX_USAGE_CACHE_FILES` are exported
+- `computeBillingBlocks(events, { now })` and `findActiveBillingBlock()` (root and browser entry points) group usage events into ccusage-style five-hour blocks aligned to the UTC hour, with cache-inclusive totals, cost provenance, per-model usage, burn rate, remaining time, and end-of-block projections; `BILLING_BLOCK_DURATION_MS` is exported
+- `bucketUsage(events, { granularity, utc, weekStartsOn, groupBy })`, `summarizeUsageRows()`, `usageBucketKey()`, and `weekKey()` (root and browser entry points) bucket usage events by event time into day, week, month, or session rows with provider, project, and model dimensions, cache-inclusive totals, and cost provenance
+- `applySessionSummary(store, summary)`, `removeSessionSummary()`, `markFileImported()`, `isFileImported()`, and `sessionSummaryFromStats()` (root and browser entry points) are the pure `historical-data.json` mutations ported from the VS Code extension, so the CLI and the extension credit sessions identically; `importSessionHistory({ providers, since, isImported, applySummary, markImported })` reads every finished session once through `readSessionFileStats()` and hands summaries to the caller's store, skipping files modified within `ACTIVE_SESSION_MTIME_THRESHOLD_MS`
+- `SessionFileStats.modelUsage` entries gain `costUsd` and `priced`
+- `classifySessionActivity({ events, mtimeMs })` classifies a session from events already in memory with the same states, reasons, grace period, and staleness rule as `detectSessionActivity()`; `refreshSessionActivityState()` accepts the previous reason so a session that was active only by grace period ends once the grace period lapses; `getObservedActivityReason()` exposes the reason behind an observed session's activity; `SESSION_ACTIVITY_GRACE_PERIOD_MS` and `SESSION_ACTIVITY_STALENESS_MS` are exported
+- `readSessionReportInputs(provider, sessionPath)` reads a session once and returns its events, aggregator metrics, and report transcript; `resolveSessionPath(provider, workspacePath, sessionId?)` is the session lookup `createWatcher()` uses (exact id, unique prefix, or most recent); `sessionFingerprintParts()` and `fingerprintString()` are exported alongside `fileFingerprintParts()`; `SessionMessage.stop_reason` is preserved by the event schema
+- `walkRolloutFiles(roots, { maxDepth, maxFiles, limit, sessionId })` and `walkRolloutFilesAsync()` are the one capped walker for Codex rollout files: newest-dated directories first, each file stat'ed once, results newest first with size and session id, an early exit for `limit`, and defaults of six levels and 20 000 files; `findSessionFilesWithStats()` returns a Claude Code session directory's files with the stat the listing already paid for
+- `writeStateFile()`, `readStateFile()`, `getStateFilePath()`, `quotaToStateFile()`, `billingBlockToStateFile()`, `STATE_FILE_SCHEMA_VERSION`, and the `SidekickStateFile` types (root, node, and `statusline` entry points) maintain the public, versioned `<configDir>/state.json` for external tools — account, quota windows with freshness, context usage, session cost, active billing block — writing atomically only when the content changed; `sidekickStateFileSchema` and its sub-schemas are exported from `sidekick-shared/schemas`
+- `SessionPreviewListResult.hasMore` reports whether `listSessionPreviewsAsync()` left candidates beyond `limit`, so callers can offer a larger limit only when one would show more
+- `mergeFailingToolWindows()`, `failingToolTrend()`, and `FAILING_TOOL_TREND_ARROWS` (root and `browser` entry points) merge the 7-day and 30-day `getTopFailingTools()` windows into per-tool rows with a trend, shared by `sidekick stats` and the VS Code Health tab
+
+### Changed
+
+- The HTML report and session dump label cost by provenance and render unpriced sessions as `—` with the unpriced call count; their "Total" row is cache-inclusive and labelled "Total (incl. cache)"
+- `calculateCompactionLedger()` prices re-establishment through `calculateNormalizedUsageCost()` instead of the deprecated additive-reasoning path
+- Codex `readSessionStats()` computes context as uncached + cached input, matching `CodexProvider.computeContextSize()`
+- OpenCode `workspaceMatches` only matches sessions started in the workspace or a subdirectory of it
+- `readQuotaHistoryDailyBuckets()` keys buckets by local calendar day
+- `detectProvider()` and `getAllDetectedProviders()` share one implementation memoised for five seconds
+- `loadObservedContextWindows()` ignores entries older than `OBSERVED_CONTEXT_WINDOW_TTL_MS` (30 days)
+- `saveSnapshot()` writes through the fsynced atomic writer and prunes the directory to the newest 200 files every 25 saves; quota-history append and prune run under a per-file cross-process lock with fsync; the pricing catalog cache is written atomically
+- `DEFAULT_PEAK_HOURS_TIMEOUT_MS` is 4 000 ms; `fetchPeakHoursStatus()` falls back to the schedule rather than returning `unavailable: true`
+- `listSessionPreviews({ since })` throws `RangeError` on an unparseable cutoff
+- `AggregatedTokens.reportedCost` is deprecated (same value as `costUsd`); `SNAPSHOT_SCHEMA_VERSION` is 5
+- Claude Code, Codex, and OpenCode `readSessionStats()` share one implementation: per-model `tokens` are cache-inclusive (`summarizeTokens().total`) for every provider, Claude sessions report catalog-estimated cost and a tool success/failure split instead of `reportedCost: 0`, OpenCode compaction and truncation counts come from the aggregator instead of hardcoded zeros, a missing or unreadable source reports `availability: 'unavailable'` with a reason instead of silent zeros, and the label is taken from the events already read (Codex and OpenCode still prefer their database title) so the file is never opened twice
+- OpenCode's file-backed reader implements `seekTo()` by message count (its `getPosition()` unit), so a reader restored from a snapshot emits only newer messages instead of replaying the whole session; the database-backed reader's `exists()` checks the session row (memoised for 30 s, treating a transient query failure as present) instead of always returning true
+- `createProviderSessionAdapterV1().read()` reads a session once: stats, transcript, activity, and the pending request all come from one flushed reader pass instead of three separate file reads, and activity is classified from the events, which also fixes Codex sessions (whose raw lines never matched the Claude-only tail patterns) and database-backed OpenCode sessions (which always read as ended). `watch()` checks the size/mtime fingerprint before re-reading and refreshes only the activity in place while the content is unchanged, so a 2 s poll on an idle session costs a `stat`
+- `ObservedSessionCollector` cache refreshes demote a session that was active only by grace period to ended after five seconds, matching a fresh classification
+- The Codex provider's six recursive walkers (session discovery, listing, id lookup, project folders, subagent scan) and the quota resolver's separate copy all use the capped walker; `getAllProjectFolders()` reads `session_meta` only for rollouts newer than the SQLite index's mtime when the index answered, and every discovery path uses the per-path cwd cache (now bounded to 5 000 entries) instead of re-reading the first line of every rollout; `scanSubagents()` stops after the 50 newest-dated rollouts instead of enumerating the whole history; the local Codex quota scan walks at most `maxSessionFiles` rollouts and no longer stats every path a second time to sort it; `ClaudeCodeProvider.listAllSessionFiles()` no longer stats every session twice
+
+### Fixed
+
+- `onAccountsChanged()` applies a later subscriber's faster `pollIntervalMs` and resets the interval after the last unsubscribe
+- `OpenCodeProvider.dispose()` resets `dbStatus`; `CodexProvider.listSessionFilesAsync()` records its filesystem fallback for `getLastOperationStatus()`
+- Observed-session cache hits could report a session as active for up to five minutes when a fresh parse would have said ended (the 0.25.0 grace-period drift note)
+- `addCurrentAccount()` and `removeAccount()` hold the registry lock across their whole read-modify-write (new `withSavedAccountRegistryLock()` and `replaceSavedAccountProfilesUnlocked()`), so a concurrent add from another process is no longer dropped when the Claude profile set is replaced
+- `resolveActiveClaudeAccount()`'s self-heal of the active pointer no longer fires an accounts-changed notification from a read path (`setActiveSavedAccount(..., { silent: true })`)
+- `readSessionPreview()` / `readSessionPreviewAsync()` honour `maxPrefixBytes: 0` as "skip the prefix scan" (`firstTimestamp` and `workspacePath` come back null, the file is not opened) instead of flooring the budget to one byte
+- `createSessionProviders()` documents that `diagnostics` is live (updated in place as providers run) and should be copied for a snapshot
+- The packaging contract tests create their scratch projects under the OS temp directory instead of inside the package, so an interrupted run cannot leave a recursive `node_modules/sidekick-shared` link behind
+
 ## [0.25.0] - 2026-08-18
 
 ### Added

package/README.md

@@ -9,6 +9,7 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **One token vocabulary and cost provenance (0.26.0)** — `summarizeTokens()` gives every surface the same `total` (input + output + cache writes + cache reads) and `context` (input + cache) figures; `AggregatedTokens.costUsd` carries `costProvenance` so reports can say whether a cost was provider-reported or estimated; `parseClaudeStatuslinePayload()` / `quotaFromStatuslinePayload()` turn Claude Code's status-line JSON into an official `statusline` quota source; `readQuotaSnapshot()` reports `ageMs` / `freshness` and keeps the sample's origin as `capturedSource`; `resolveQuota()` is the one quota resolution path (fresh persisted sample → session logs → provider API → older sample) shared by the CLI, the MCP server, and both dashboards; `readSessionFileStats()` / `computeSessionFileStats()` give every provider one `readSessionStats()` over the shared aggregator, with `availability`, `costProvenance`, and `toolFailures` on `SessionFileStats`; `collectUsageEvents()` reads priced usage events from session logs with a per-session cache, `computeBillingBlocks()` groups them into five-hour billing blocks, and `bucketUsage()` turns them into day, week, month, or session rows; `applySessionSummary()` and `importSessionHistory()` let any host fold finished sessions into `historical-data.json` the way the extension does; observed sessions are read once per discovery, re-read only when their fingerprint changes, and classified from events by `classifySessionActivity()`; `readSessionReportInputs()` derives report metrics and transcript from one read; `writeStateFile()` / `readStateFile()` (also on the `statusline` subpath) maintain the public, versioned `state.json` for external tools, validated by `sidekickStateFileSchema`; `getScheduledPeakHoursState()` and `evaluateQuotaThresholds()` are shared by the CLI and extension dashboards.
 - **Host-safe APIs (0.25.0)** — `listSessionPreviewsAsync()` / `readSessionPreviewAsync()` read previews with bounded concurrency and cooperative yielding; `ObservedSessionCollector.subscribe()` and `SessionMonitor.subscribe()` replace host polling loops with debounced change batches; `createSessionProviders({ onDiagnostic })` constructs every usable provider with structured diagnostics instead of throwing; `findSessionById()` resolves one session without scanning; `exportResolvedModelCatalog()` / `importResolvedModelCatalog()` and `registerModelAlias()` transfer context/pricing resolutions across realms; `onAccountsChanged()` reports login/logout/switch events; provider constructors perform no environment I/O, and quota pollers stay dormant without an account.
 - **Native session-file helpers** — `encodeClaudeWorkspacePath()` / `getClaudeSessionDirectory()` locate Claude Code's `~/.claude/projects/` directories with the real on-disk encoding, `findCodexRolloutFile()` resolves a Codex session id to its rollout path, `readCodexHistory()` tail-reads `~/.codex/history.jsonl`, `listSessionPreviews()` / `readSessionPreview()` build a cheap stat-first recent-sessions index across providers, and `parseMcpToolName()` splits `mcp__<server>__<tool>` identifiers (browser-safe).
 - **Non-blocking account APIs & locked sync writers** — every login/switch entry point gains an async variant (`switchAccountAsync()`, `getAccountLoginStatusAsync()`, `finalizeAccountLoginAsync()`, `prepareCodexAccountAsync()`, `finalizeCodexAccountAsync()`, `switchToCodexAccountAsync()`) that keeps `codex` CLI probes off the event loop, and synchronous callers get the same cross-process store lock via `atomicWriteFileSync()` / `updateJsonStoreAtomicSync()` / `withFileLockSync()`, with progress-based timeouts and abandoned-lock reclaim.
@@ -104,7 +105,7 @@ returns the platform default that both overrides bypass.
 | **Quota**                       | Claude Max subscription quota fetching (5-hour and 7-day windows), Codex rate-limit extraction from event streams (plus Codex reset credits via `fetchCodexResetCreditsFromApi()`, attached to quota state by `fetchCodexQuotaFromApi()`), and authoritative z.ai Coding Plan quota fetching via `resolveZaiQuota()` / `fetchZaiQuotaFromApi()` (reads z.ai's `api/monitor/usage/quota/limit` endpoint with cached-snapshot fallback). The observed-traffic z.ai estimator was removed from the package root exports in 0.23.0 and every remaining export of it is `@deprecated` — `resolveZaiQuota()` is the single supported z.ai quota API                                                                                                                                                                                                                                                                                                                                    |
 | **Provider Status**             | API health checking via status.claude.com and status.openai.com (indicator, components, incidents)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **Doctor**                      | Typed cross-provider health diagnostics — `runDoctor()` checks project identity, sessions, accounts, providers, and dependencies into a `HealthReport`; `formatHealthReport()` renders it and `getSessionDiagnostics()` exposes the per-provider session probe                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Schemas**                     | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, observed-session V1 records, quota, account status, account management, and quota history — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Account and quota APIs guarantee results valid against the same-release schemas. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Schemas**                     | Zod schemas for runtime validation of data crossing process/IPC boundaries — JSONL session events (`sessionEventSchema`, `messageUsageSchema`, `sessionMessageSchema`), assistant turns, observed-session V1 records, quota, account status, account management, quota history, and the public `state.json` contract (`sidekickStateFileSchema`) — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. Account and quota APIs guarantee results valid against the same-release schemas. Also published fs-free via the [`sidekick-shared/schemas`](#supported-import-paths) subpath                                                                                                                                                                                                                                                                                                                                                                               |
 | **Extractors**                  | Pure functions for single-event processing: `extractTokenUsage()`, `extractToolCall()` (top-level `tool_use`), `extractToolCalls()` (assistant content blocks), plus Node-only session asset extraction (`gatherAssetsForCwd()`, `readClaudeAssets()`, `readCodexAssets()`) for URLs, file paths, commands, and plans                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | **Model Info & Pricing**        | Model family parsing (Anthropic / OpenAI / Google, including legacy `claude-3-opus-…` and `claude-3-5-sonnet-…` IDs), context-window lookup (including Fable 5 / Opus 4.8 / Opus 4.7 / Sonnet 4.7 1M and GPT-5.x variants), pricing tables with optional LiteLLM hydration, normalized non-double-counting cost (`calculateNormalizedUsageCost()`, fed by `normalizeProviderUsage()` / `extractNormalizedUsage()`), legacy cost helpers retained but deprecated (`calculateCost()`, `calculateCostWithProvenance()`), `mergeCostSources()`, display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`), and cross-realm catalog transfer — `exportResolvedModelCatalog()` / `importResolvedModelCatalog()` move resolved context windows and pricing (with provenance, prefix inheritance explicit) between Node and browser realms, and `registerModelAlias()` resolves short or host-specific names to canonical ids |
 | **Quota Polling**               | `QuotaPoller` class with exponential backoff, active/idle intervals, and cached fallback. Stays dormant while no account exists and wakes through the account-change signal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
@@ -130,7 +131,7 @@ returns the platform default that both overrides bypass.
 | `sidekick-shared/modelContext` | Any runtime                | Direct access to the context-window module.                                                                                                                                                                                                                                                                                                                                                                                   |
 | `sidekick-shared/modelInfo`    | Any runtime                | Direct access to model parsing and cost math.                                                                                                                                                                                                                                                                                                                                                                                 |
 | `sidekick-shared/formatting`   | Any runtime                | Direct access to pure token and duration display helpers.                                                                                                                                                                                                                                                                                                                                                                     |
-| `sidekick-shared/schemas`      | Any runtime                | Pure Zod boundary schemas (session events, assistant turns, observed-session V1, quota, account status, account management, quota history) — fs-free, no Node builtins.                                                                                                                                                                                                                                                       |
+| `sidekick-shared/schemas`      | Any runtime                | Pure Zod boundary schemas (session events, assistant turns, observed-session V1, quota, account status, account management, quota history, the `state.json` contract) — fs-free, no Node builtins.                                                                                                                                                                                                                            |
 | `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers, `formatStatusline()`, and burn-rate estimates.                                                                                                                                                                                                                                                                                                        |
 
 ### Browser / webview runtimes
@@ -238,6 +239,32 @@ const estimate = estimateTextTokens(sourceCode, {
 
 `sidekick-fallback-v1` counts Latin/source-code text at 3.5 characters per token, CJK code points at one token, emoji at two, and other non-ASCII code points at one. Empty input is zero. An injected finite, nonnegative exact result takes precedence.
 
+### Read session stats for any provider
+
+```typescript
+import { createSessionProviders, readSessionFileStats } from 'sidekick-shared';
+
+const { providers } = createSessionProviders();
+for (const provider of providers) {
+  for (const sessionPath of provider.findAllSessions(process.cwd())) {
+    const stats = provider.readSessionStats(sessionPath); // same as readSessionFileStats(provider, sessionPath)
+    if (stats.availability === 'unavailable') {
+      console.warn(`${provider.id}: ${stats.unavailableReason}`);
+      continue;
+    }
+    console.log(
+      stats.label,
+      stats.modelUsage,
+      stats.costUsd,
+      stats.costProvenance,
+      stats.toolFailures,
+    );
+  }
+}
+```
+
+Every provider computes `SessionFileStats` the same way — one reader pass through the shared `EventAggregator` — so per-model `tokens` are cache-inclusive, `costUsd` carries `costProvenance`, `toolFailures` splits out failed calls, and compaction and truncation counts are real for Claude Code, Codex, and OpenCode alike. `computeSessionFileStats(events, options)` does the same for events you already hold, and `firstUserPrompt(events)` derives the label.
+
 ### Read canonical session history
 
 ```typescript
@@ -308,7 +335,7 @@ Hosts with a UI loop should prefer the async variants from `sidekick-shared/node
 ```typescript
 import { listSessionPreviewsAsync, readSessionPreviewAsync } from 'sidekick-shared/node';
 
-const { previews, diagnostics } = await listSessionPreviewsAsync(providers, { limit: 10 });
+const { previews, diagnostics, hasMore } = await listSessionPreviewsAsync(providers, { limit: 10 });
 const { preview } = await readSessionPreviewAsync(provider, filePath);
 ```
 
@@ -448,6 +475,25 @@ if (!peak.unavailable && peak.isPeak) {
 }
 ```
 
+### Resolve quota with one precedence
+
+```typescript
+import { resolveQuota } from 'sidekick-shared';
+
+// Fresh persisted sample (status line, session, or API; under five minutes) →
+// session logs (Codex rollouts) → provider API → older sample labelled by age.
+const quota = await resolveQuota({ providerId: 'claude-code' });
+console.log(quota.resolution); // 'snapshot-fresh' | 'session' | 'api' | 'snapshot-aging' | 'snapshot-stale' | 'unavailable'
+console.log(quota.source, quota.capturedSource, quota.freshness, quota.ageMs);
+
+// `--refresh` semantics: ask the API first.
+await resolveQuota({ providerId: 'codex', workspacePath: process.cwd(), preferFresh: false });
+// Paint from local samples only (a poller will fetch live data next).
+await resolveQuota({ providerId: 'claude-code', allowApi: false });
+```
+
+`resolveQuota()` is what `sidekick quota`, `quota --all`, the MCP `get_quota_status` tool, and both dashboards call, so every surface reports the same numbers and the same `resolution`. Every side effect is injectable (`readSnapshot`, `writeSnapshot`, `fetchImpl`, `getClaudeAccessToken`, the account resolvers) for tests.
+
 ### Fetch subscription quota
 
 ```typescript

package/dist/accountChanges.js

@@ -48,7 +48,8 @@ let pollTimer;
 let stopRawListener;
 let lastFingerprint;
 let debounceTimer;
-let activePollIntervalMs = 30_000;
+const DEFAULT_POLL_INTERVAL_MS = 30_000;
+let activePollIntervalMs = DEFAULT_POLL_INTERVAL_MS;
 /**
  * Observe login, logout, and active-account switches. Local Sidekick mutations
  * signal immediately; filesystem watchers cover external CLIs; a low-frequency
@@ -56,8 +57,17 @@ let activePollIntervalMs = 30_000;
  */
 function onAccountsChanged(listener, options = {}) {
     listeners.add(listener);
-    activePollIntervalMs = Math.max(1_000, options.pollIntervalMs ?? activePollIntervalMs);
-    ensureMonitoring();
+    // The fastest interval any live subscriber asked for wins; a later, faster
+    // subscriber restarts the timer rather than being silently ignored.
+    const requestedPollMs = Math.max(1_000, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    if (!stopRawListener) {
+        activePollIntervalMs = requestedPollMs;
+        ensureMonitoring();
+    }
+    else if (requestedPollMs < activePollIntervalMs) {
+        activePollIntervalMs = requestedPollMs;
+        restartPollTimer();
+    }
     if (options.emitCurrent)
         emitIfChanged('poll', true, listener);
     return {
@@ -93,9 +103,17 @@ function ensureMonitoring() {
             // Missing/unwatchable directories are covered by the catch-up poll.
         }
     }
+    startPollTimer();
+}
+function startPollTimer() {
     pollTimer = setInterval(() => emitIfChanged('poll'), activePollIntervalMs);
     pollTimer.unref?.();
 }
+function restartPollTimer() {
+    if (pollTimer)
+        clearInterval(pollTimer);
+    startPollTimer();
+}
 function stopMonitoring() {
     stopRawListener?.();
     stopRawListener = undefined;
@@ -109,6 +127,7 @@ function stopMonitoring() {
         clearTimeout(debounceTimer);
     debounceTimer = undefined;
     lastFingerprint = undefined;
+    activePollIntervalMs = DEFAULT_POLL_INTERVAL_MS;
 }
 function watchTargets() {
     return Array.from(new Set([(0, accountRegistry_1.getAccountsDir)(), path.join(os.homedir(), '.claude'), (0, codexProfiles_1.getSystemCodexHome)()]));

package/dist/accountRegistry.d.ts

@@ -41,11 +41,32 @@ export interface ResolvedActiveAccount {
     source: 'live' | 'registry' | 'none';
 }
 export declare function getAccountsDir(): string;
+interface RegistryWriteOptions {
+    /**
+     * Skip the local change notification. Only for writes that change no
+     * observable account state, such as re-pointing the active pointer at the
+     * profile that already matches the live login (self-heal): a read path
+     * must not wake every subscriber.
+     */
+    silent?: boolean;
+}
+/**
+ * Run `operation` while holding the registry lock. For callers that need a
+ * read-modify-write across several steps (the legacy Claude facade's
+ * add/remove); inside it use the `*Unlocked` writers, never the locking ones:
+ * the lock is not re-entrant.
+ */
+export declare function withSavedAccountRegistryLock<T>(operation: () => T): T;
 export declare function readSavedAccountRegistry(): SavedAccountRegistry | null;
 export declare function writeSavedAccountRegistry(registry: SavedAccountRegistry): void;
 export declare function listSavedAccountProfiles(providerId?: AccountProviderId): SavedAccountProfile[];
 export declare function getActiveSavedAccount(providerId: AccountProviderId): SavedAccountProfile | null;
 export declare function upsertSavedAccountProfile(profile: SavedAccountProfile): SavedAccountRegistry;
-export declare function setActiveSavedAccount(providerId: AccountProviderId, accountId: string | null): SavedAccountRegistry;
+export declare function setActiveSavedAccount(providerId: AccountProviderId, accountId: string | null, options?: RegistryWriteOptions): SavedAccountRegistry;
 export declare function replaceSavedAccountProfiles(providerId: AccountProviderId, accounts: SavedAccountProfile[], activeId: string | null): SavedAccountRegistry;
+/**
+ * Same as {@link replaceSavedAccountProfiles} without taking the registry
+ * lock: for callers already inside {@link withSavedAccountRegistryLock}.
+ */
+export declare function replaceSavedAccountProfilesUnlocked(providerId: AccountProviderId, accounts: SavedAccountProfile[], activeId: string | null): SavedAccountRegistry;
 export declare function removeSavedAccountProfile(providerId: AccountProviderId, accountId: string): SavedAccountProfile | null;

package/dist/accountRegistry.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ACCOUNT_PROVIDER_IDS = void 0;
 exports.getAccountsDir = getAccountsDir;
+exports.withSavedAccountRegistryLock = withSavedAccountRegistryLock;
 exports.readSavedAccountRegistry = readSavedAccountRegistry;
 exports.writeSavedAccountRegistry = writeSavedAccountRegistry;
 exports.listSavedAccountProfiles = listSavedAccountProfiles;
@@ -42,6 +43,7 @@ exports.getActiveSavedAccount = getActiveSavedAccount;
 exports.upsertSavedAccountProfile = upsertSavedAccountProfile;
 exports.setActiveSavedAccount = setActiveSavedAccount;
 exports.replaceSavedAccountProfiles = replaceSavedAccountProfiles;
+exports.replaceSavedAccountProfilesUnlocked = replaceSavedAccountProfilesUnlocked;
 exports.removeSavedAccountProfile = removeSavedAccountProfile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -62,9 +64,20 @@ function getRegistryLockPath() {
 function ensureAccountsDir() {
     fs.mkdirSync(getAccountsDir(), { recursive: true, mode: 0o700 });
 }
-function writeRegistryUnlocked(registry) {
+function writeRegistryUnlocked(registry, options = {}) {
     (0, atomic_1.atomicWriteJsonSync)(getRegistryPath(), normalizeRegistry(registry));
-    (0, accountChangeSignal_1._emitAccountsChanged)('local');
+    if (!options.silent)
+        (0, accountChangeSignal_1._emitAccountsChanged)('local');
+}
+/**
+ * Run `operation` while holding the registry lock. For callers that need a
+ * read-modify-write across several steps (the legacy Claude facade's
+ * add/remove); inside it use the `*Unlocked` writers, never the locking ones:
+ * the lock is not re-entrant.
+ */
+function withSavedAccountRegistryLock(operation) {
+    ensureAccountsDir();
+    return (0, atomic_1.withFileLockSync)(getRegistryLockPath(), operation);
 }
 /**
  * Serializes registry read-modify-write cycles across processes. Without the
@@ -73,13 +86,13 @@ function writeRegistryUnlocked(registry) {
  * mutation. Lock ordering: callers that also hold a provider auth-swap lock
  * take that lock first and this one inside it, never the reverse.
  */
-function mutateSavedAccountRegistry(mutator) {
-    ensureAccountsDir();
-    return (0, atomic_1.withFileLockSync)(getRegistryLockPath(), () => {
-        const next = mutator(readSavedAccountRegistry() ?? createEmptyRegistry());
-        writeRegistryUnlocked(next);
-        return next;
-    });
+function mutateSavedAccountRegistry(mutator, options = {}) {
+    return withSavedAccountRegistryLock(() => mutateSavedAccountRegistryUnlocked(mutator, options));
+}
+function mutateSavedAccountRegistryUnlocked(mutator, options = {}) {
+    const next = mutator(readSavedAccountRegistry() ?? createEmptyRegistry());
+    writeRegistryUnlocked(next, options);
+    return next;
 }
 function createEmptyRegistry() {
     return {
@@ -187,20 +200,30 @@ function upsertSavedAccountProfile(profile) {
         return registry;
     });
 }
-function setActiveSavedAccount(providerId, accountId) {
+function setActiveSavedAccount(providerId, accountId, options = {}) {
     return mutateSavedAccountRegistry((registry) => {
         registry.activeByProvider[providerId] = accountId;
         return registry;
-    });
+    }, options);
 }
-function replaceSavedAccountProfiles(providerId, accounts, activeId) {
-    return mutateSavedAccountRegistry((registry) => {
+function replaceProfiles(providerId, accounts, activeId) {
+    return (registry) => {
         registry.accounts = registry.accounts
             .filter((account) => account.providerId !== providerId)
             .concat(accounts);
         registry.activeByProvider[providerId] = activeId;
         return registry;
-    });
+    };
+}
+function replaceSavedAccountProfiles(providerId, accounts, activeId) {
+    return mutateSavedAccountRegistry(replaceProfiles(providerId, accounts, activeId));
+}
+/**
+ * Same as {@link replaceSavedAccountProfiles} without taking the registry
+ * lock: for callers already inside {@link withSavedAccountRegistryLock}.
+ */
+function replaceSavedAccountProfilesUnlocked(providerId, accounts, activeId) {
+    return mutateSavedAccountRegistryUnlocked(replaceProfiles(providerId, accounts, activeId));
 }
 function removeSavedAccountProfile(providerId, accountId) {
     ensureAccountsDir();

package/dist/accountStatus.d.ts

@@ -10,10 +10,18 @@ export interface ActiveAccountStatus {
     codex: ActiveProviderAccountStatus;
     error?: string;
 }
+export interface ActiveAccountStatusOptions {
+    /**
+     * Re-point a stale saved-account pointer at the live identity when they
+     * disagree (default true). Hot paths such as the status line pass `false`
+     * so they never write; an ordinary command repairs the pointer later.
+     */
+    selfHeal?: boolean;
+}
 /**
  * Reads active Claude Code and Codex account status in one filesystem pass.
  *
  * If reading either provider throws, the result still has provider-shaped
  * fields so startup flows can render a consistent "not configured" state.
  */
-export declare function getActiveAccountStatus(error?: string): ActiveAccountStatus;
+export declare function getActiveAccountStatus(error?: string, options?: ActiveAccountStatusOptions): ActiveAccountStatus;

package/dist/accountStatus.js

@@ -12,10 +12,10 @@ function errorMessage(error) {
  * If reading either provider throws, the result still has provider-shaped
  * fields so startup flows can render a consistent "not configured" state.
  */
-function getActiveAccountStatus(error) {
+function getActiveAccountStatus(error, options = {}) {
     try {
-        const claudeAccount = (0, accounts_1.resolveActiveClaudeAccount)();
-        const codexAccount = (0, codexProfiles_1.resolveActiveCodexAccount)();
+        const claudeAccount = (0, accounts_1.resolveActiveClaudeAccount)(options);
+        const codexAccount = (0, codexProfiles_1.resolveActiveCodexAccount)(options);
         const claude = claudeAccount.source !== 'none'
             ? {
                 present: true,

package/dist/accounts.d.ts

@@ -50,5 +50,7 @@ export declare function getActiveAccount(): AccountEntry | null;
  * re-pointed so registry-keyed data tracks reality too. Never creates or deletes
  * profiles; an unknown live account is shown as-is with no label and no write.
  */
-export declare function resolveActiveClaudeAccount(): ResolvedActiveAccount;
+export declare function resolveActiveClaudeAccount(options?: {
+    selfHeal?: boolean;
+}): ResolvedActiveAccount;
 export declare function isMultiAccountEnabled(): boolean;

package/dist/accounts.js

@@ -201,7 +201,14 @@ function readAccountRegistry() {
     };
 }
 function writeAccountRegistry(registry) {
-    const mappedClaudeProfiles = registry.accounts.map((account) => ({
+    (0, accountRegistry_1.replaceSavedAccountProfiles)('claude-code', mapClaudeProfiles(registry), registry.activeAccountUuid);
+}
+/** For callers already holding the registry lock (see withSavedAccountRegistryLock). */
+function writeAccountRegistryUnlocked(registry) {
+    (0, accountRegistry_1.replaceSavedAccountProfilesUnlocked)('claude-code', mapClaudeProfiles(registry), registry.activeAccountUuid);
+}
+function mapClaudeProfiles(registry) {
+    return registry.accounts.map((account) => ({
         id: account.uuid,
         providerId: 'claude-code',
         providerAccountId: account.uuid,
@@ -212,7 +219,6 @@ function writeAccountRegistry(registry) {
             email: account.email,
         },
     }));
-    (0, accountRegistry_1.replaceSavedAccountProfiles)('claude-code', mappedClaudeProfiles, registry.activeAccountUuid);
 }
 // ── Read active Claude account ───────────────────────────────────────────
 function readActiveClaudeAccount() {
@@ -254,17 +260,34 @@ function addCurrentAccount(label) {
         return { success: false, error: 'Could not read Claude config file.' };
     }
     ensureDirs();
-    // 4. Load or create registry
-    const registry = readAccountRegistry() ?? {
-        version: 1,
-        activeAccountUuid: null,
-        accounts: [],
-    };
-    // 5. Check if account already exists — update credentials + label
-    const existing = registry.accounts.find((a) => a.uuid === active.uuid);
-    if (existing) {
-        if (label !== undefined)
-            existing.label = label;
+    // 4–7 are one read-modify-write of the registry: hold the registry lock
+    // across them so a concurrent add from another process is not dropped
+    // when this write replaces the whole Claude profile set.
+    return (0, accountRegistry_1.withSavedAccountRegistryLock)(() => {
+        // 4. Load or create registry
+        const registry = readAccountRegistry() ?? {
+            version: 1,
+            activeAccountUuid: null,
+            accounts: [],
+        };
+        // 5. Check if account already exists — update credentials + label
+        const existing = registry.accounts.find((a) => a.uuid === active.uuid);
+        if (existing) {
+            if (label !== undefined)
+                existing.label = label;
+            (0, atomic_1.atomicWriteJsonSync)(path.join(getCredentialsDir(), `${active.uuid}.credentials.json`), credBlob);
+            (0, atomic_1.atomicWriteJsonSync)(path.join(getConfigsDir(), `${active.uuid}.config.json`), configBlob);
+            try {
+                writeClaudeProfileMirror(active.uuid, credBlob, configBlob);
+            }
+            catch {
+                /* flat backups remain available */
+            }
+            registry.activeAccountUuid = active.uuid;
+            writeAccountRegistryUnlocked(registry);
+            return { success: true };
+        }
+        // 6. New account — back up credentials
         (0, atomic_1.atomicWriteJsonSync)(path.join(getCredentialsDir(), `${active.uuid}.credentials.json`), credBlob);
         (0, atomic_1.atomicWriteJsonSync)(path.join(getConfigsDir(), `${active.uuid}.config.json`), configBlob);
         try {
@@ -273,29 +296,17 @@ function addCurrentAccount(label) {
         catch {
             /* flat backups remain available */
         }
+        // 7. Add entry
+        registry.accounts.push({
+            uuid: active.uuid,
+            email: active.email,
+            label,
+            addedAt: new Date().toISOString(),
+        });
         registry.activeAccountUuid = active.uuid;
-        writeAccountRegistry(registry);
+        writeAccountRegistryUnlocked(registry);
         return { success: true };
-    }
-    // 6. New account — back up credentials
-    (0, atomic_1.atomicWriteJsonSync)(path.join(getCredentialsDir(), `${active.uuid}.credentials.json`), credBlob);
-    (0, atomic_1.atomicWriteJsonSync)(path.join(getConfigsDir(), `${active.uuid}.config.json`), configBlob);
-    try {
-        writeClaudeProfileMirror(active.uuid, credBlob, configBlob);
-    }
-    catch {
-        /* flat backups remain available */
-    }
-    // 7. Add entry
-    registry.accounts.push({
-        uuid: active.uuid,
-        email: active.email,
-        label,
-        addedAt: new Date().toISOString(),
     });
-    registry.activeAccountUuid = active.uuid;
-    writeAccountRegistry(registry);
-    return { success: true };
 }
 // ── Switch to account ────────────────────────────────────────────────────
 /**
@@ -486,34 +497,37 @@ function reconcileClaudeAuthState() {
 }
 // ── Remove account ───────────────────────────────────────────────────────
 function removeAccount(uuid) {
-    const registry = readAccountRegistry();
-    if (!registry) {
-        return { success: false, error: 'No account registry found.' };
-    }
-    const idx = registry.accounts.findIndex((a) => a.uuid === uuid);
-    if (idx === -1) {
-        return { success: false, error: `Account ${uuid} not found.` };
-    }
-    // Remove backed-up files
-    try {
-        fs.unlinkSync(path.join(getCredentialsDir(), `${uuid}.credentials.json`));
-    }
-    catch {
-        /* ok */
-    }
-    try {
-        fs.unlinkSync(path.join(getConfigsDir(), `${uuid}.config.json`));
-    }
-    catch {
-        /* ok */
-    }
-    // Remove from registry
-    registry.accounts.splice(idx, 1);
-    if (registry.activeAccountUuid === uuid) {
-        registry.activeAccountUuid = registry.accounts[0]?.uuid ?? null;
-    }
-    writeAccountRegistry(registry);
-    return { success: true };
+    // One read-modify-write under the registry lock (see addCurrentAccount).
+    return (0, accountRegistry_1.withSavedAccountRegistryLock)(() => {
+        const registry = readAccountRegistry();
+        if (!registry) {
+            return { success: false, error: 'No account registry found.' };
+        }
+        const idx = registry.accounts.findIndex((a) => a.uuid === uuid);
+        if (idx === -1) {
+            return { success: false, error: `Account ${uuid} not found.` };
+        }
+        // Remove backed-up files
+        try {
+            fs.unlinkSync(path.join(getCredentialsDir(), `${uuid}.credentials.json`));
+        }
+        catch {
+            /* ok */
+        }
+        try {
+            fs.unlinkSync(path.join(getConfigsDir(), `${uuid}.config.json`));
+        }
+        catch {
+            /* ok */
+        }
+        // Remove from registry
+        registry.accounts.splice(idx, 1);
+        if (registry.activeAccountUuid === uuid) {
+            registry.activeAccountUuid = registry.accounts[0]?.uuid ?? null;
+        }
+        writeAccountRegistryUnlocked(registry);
+        return { success: true };
+    });
 }
 // ── Query helpers ────────────────────────────────────────────────────────
 function listAccounts() {
@@ -546,7 +560,8 @@ function getActiveAccount() {
  * re-pointed so registry-keyed data tracks reality too. Never creates or deletes
  * profiles; an unknown live account is shown as-is with no label and no write.
  */
-function resolveActiveClaudeAccount() {
+function resolveActiveClaudeAccount(options = {}) {
+    const selfHeal = options.selfHeal ?? true;
     const live = readActiveClaudeAccount();
     if (live) {
         const profiles = (0, accountRegistry_1.listSavedAccountProfiles)('claude-code');
@@ -554,12 +569,17 @@ function resolveActiveClaudeAccount() {
             profiles.find((p) => (p.email ?? p.metadata?.email) === live.email);
         if (match) {
             const active = (0, accountRegistry_1.getActiveSavedAccount)('claude-code');
-            if (!active || active.id !== match.id) {
+            // Hot paths (the status line runs on every prompt) pass selfHeal: false
+            // so a persistently failing registry write never becomes a write per
+            // prompt; the next ordinary command repairs the pointer instead.
+            if (selfHeal && (!active || active.id !== match.id)) {
                 // Self-heal is best-effort: a registry write failure (read-only/full
                 // disk) must never break display or extension activation. We still
                 // return the correct live identity below.
+                // Silent: this is a read path repairing a pointer to the profile that
+                // already matches the live login, so subscribers have nothing new to see.
                 try {
-                    (0, accountRegistry_1.setActiveSavedAccount)('claude-code', match.id);
+                    (0, accountRegistry_1.setActiveSavedAccount)('claude-code', match.id, { silent: true });
                 }
                 catch {
                     /* keep going with the live identity */