sidekick-shared 0.24.4 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.25.0] - 2026-08-18
+
+### Added
+
+- `listSessionPreviewsAsync()` and `readSessionPreviewAsync()` provide bounded-concurrency, cooperative session preview reads while preserving the synchronous APIs and their signatures
+- Async preview labeling batches Codex and OpenCode database work into at most one `sqlite3` subprocess per provider per few hundred sessions listed (ids are chunked clear of argv limits); when `sqlite3` is absent, the same bounded file-scan fallback remains available
+- `OpenCodeProvider.listAllSessionFiles()` completes native preview enumeration across Claude Code, Codex, and OpenCode
+- `ObservedSessionCollector.subscribe()` and `SessionMonitor.subscribe()` emit debounced, coalesced session changes with the previous and current fingerprints, backed by filesystem watching plus a documented catch-up poll for unreliable filesystems
+- `createSessionProviders({ onDiagnostic })` constructs every usable provider independently and reports unavailable providers without aborting the host
+- `SessionProviderBase.findSessionById()` has provider-native implementations: filename lookup for Claude Code and Codex, and a database lookup with a bounded file-scan fallback for OpenCode
+- `exportResolvedModelCatalog()` and `importResolvedModelCatalog()` transfer serializable context-window and pricing resolutions between Node and browser realms without private hooks
+- `registerModelAlias()` lets hosts resolve short model names to canonical ids, and catalog provenance marks prefix-inherited context and pricing matches so callers can reject them
+- Stable provider-id arrays are exported as runtime values alongside their derived TypeScript unions
+- `onAccountsChanged()` reports process-local and filesystem-observed login, logout, and account-switch changes without account-state polling in each host
+
+### Changed
+
+- Provider constructors are environment-independent and perform no filesystem, configuration, database, or binary probing; environmental failures are deferred to first use and returned as structured diagnostics
+- Repeated identical provider degradations are coalesced in the factory diagnostic result, keeping first-use reporting bounded in long-lived hosts
+- `ObservedSessionCollector.collect()` caches parsed sessions by fingerprint, so a second collection over unchanged files performs no content reads
+- Observed sessions expose `fingerprintParts: { sizeBytes, mtimeMs }` alongside the compatible opaque fingerprint string
+- Collector reads accept bounded-concurrency and cooperative-yield hooks; cached observations refresh `observedAt` and activity state while retaining `contentObservedAt` to make the age of cached usage/model data explicit
+- `ObservedSessionDiagnostic` now includes `severity` and `phase` while retaining every existing `kind` value
+- Account and quota entry points guarantee results that validate against the same-release exported schemas, including additive schema fields, and their contract tests enforce the boundary
+- Every documented package subpath now declares explicit `types`, `import`, `require`, and `default` export conditions and resolves in both Vite and TypeScript's legacy `moduleResolution: node` mode without aliases
+- `readCodexHistory()` retains raw epoch-second `ts`, adds normalized `tsMs`, and sizes its tail read from `limit` unless an explicit byte bound is supplied
+- Observed-session projection accepts `observationOnly: true`, which reports transcripts as read-only observations with `capabilities.resume` disabled
+- `QuotaPoller`, `MultiProviderQuotaService`, and `CodexQuotaWatcher` stay dormant when their account is absent and wake on account changes instead of issuing empty polls
+
+### Fixed
+
+- Codex and OpenCode database-backed operations attach an availability diagnostic when the external `sqlite3` binary is missing, so an unavailable runtime is distinguishable from an empty workspace
+- A wrong session id resolves to `null` through every provider instead of surfacing discovery or environment errors
+- Exact model pricing/context entries are considered before prefix inheritance across all sources, and prefix-only matches are explicit in provenance rather than silently trusted as exact
+
+## [0.24.5] - 2026-08-18
+
+### Added
+
+- Session-preview index: `listSessionPreviews()` enumerates session files stat-first across providers, sorts by mtime, applies `since`/`limit`, and content-reads only the post-limit survivors — so cost tracks the size of the answer, not the size of the history. `readSessionPreview()` reads one file's bounded preview (label, first prompt, first timestamp, workspace path) and degrades to `null` fields instead of throwing. Both are exported from the root and `sidekick-shared/node`
+- `readCodexHistory()` returns the newest entries of `~/.codex/history.jsonl` from a bounded tail read, dropping the leading partial line and tolerating multibyte characters straddling the boundary. `findCodexRolloutFile()` resolves a Codex session id to its `sessions/YYYY/MM/DD/rollout-*.jsonl` transcript by filename only, newest mtime winning across monitored Codex homes
+- `parseMcpToolName()` is the canonical splitter for `mcp__<server>__<tool>` identifiers, exported browser-safe; the session-context projector's MCP-server inference delegates to it. The degenerate `mcp__server__` shape (empty tool part) now parses as `null` rather than yielding a server name
+- Async account entry points: `getAccountLoginStatusAsync`, `finalizeAccountLoginAsync`, `switchAccountAsync`, `prepareCodexAccountAsync`, `finalizeCodexAccountAsync`, `switchToCodexAccountAsync`. Each runs the codex CLI probes through `execFile` so the caller's event loop stays free, and probes are resolved before any lock is taken — never while holding one. Sync entry points keep their exact signatures for CLI callers
+- Synchronous locked writers: `withFileLockSync()`, `updateJsonStoreAtomicSync()`, and `atomicWriteFileSync()` share the async path's cross-process lock-file protocol (sync and async waiters exclude each other), with an absolute 15s wait ceiling because a sync waiter blocks its event loop
+- `AutoSwitchController.switchAccount` accepts a Promise-returning callback and defaults to `switchAccountAsync`, so a threshold crossing no longer runs blocking codex probes on the caller's loop. Overlapping quota updates are skipped while a switch is in flight, and a switch that lands after `dispose()` records its cooldown state without emitting a stale transition
+- `SessionProviderBase` gains an optional `listAllSessionFiles()` so providers can expose native session-file enumeration to the preview index
+
+### Fixed
+
+- The store lock's timeout is measured from the last time the lock changed hands rather than from a waiter's first attempt, so a burst of concurrent writers no longer manufactures "Timed out waiting for store lock" once the queue outlives the flat budget — a wedged holder still trips it in 3s
+- A lock whose heartbeat mtime has been frozen past two minutes is reclaimed even when its recorded PID probes alive: PID recycling made `process.kill(pid, 0)` an unreliable liveness signal, and a crashed owner with a recycled PID used to wedge the store until a human deleted the lock
+- The quota-snapshot store drops its private copy of the lock — which still had the flat 15s-from-first-attempt bug — and delegates to the shared one, keeping the same lock path so mixed-version processes still exclude each other. Snapshot writes pick up the shared writer's fsync and directory sync
+- Four account modules each carried their own lock-free atomic writer with a fixed `.tmp` suffix, so cross-process account writes were last-writer-wins and two processes could interleave the same temp file. All account writes go through the shared fsynced writers, registry read-modify-write cycles hold the registry lock, and live credential swaps hold a per-provider auth-swap lock so two switchers cannot interleave a stash/restore of a rotated Codex refresh token
+- `switchToAccount()` and `applyActiveClaudeToLiveHome()` threw on a held auth-swap lock where the Codex twins return a failed `AccountManagerResult`; they now keep the non-throwing contract their callers rely on
+- Codex login-status and `pgrep` probes no longer freeze the caller's event loop for up to 4s; `ensureDefaultAccounts` and `spawnAccountLogin` run on the async path
+- `AutoSwitchController`'s fire-and-forget update handler could surface a throwing registry read, snapshot read, or consumer `onTransition` as an unhandled promise rejection — process-fatal on modern Node. Those errors are now caught and logged
+- `readCodexHistory()` rejects entries whose `ts` is not a finite number — `JSON.parse` yields `Infinity` for out-of-range literals, which later RangeErrored out of `Date` serialization in consumers. `readSessionPreview()` likewise returns `null` for a file whose mtime cannot be serialized, per its degrade-don't-throw contract
+- `listRecentSessions()` sorts before labeling, so per-file content reads no longer scale with total session count, and a corrupt session beyond the limit no longer poisons the whole call
+
 ## [0.24.4] - 2026-07-25
 
 ### Fixed

package/README.md

@@ -9,6 +9,9 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **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.
 - **Canonical usage and pricing** — provider-specific counters normalize into disjoint input/cache/output/reasoning categories with `normalizeProviderUsage()`; `calculateNormalizedUsageCost()` prevents cache/reasoning double counting and reports pricing provenance.
 - **Transcripts and resilient collection** — `projectSessionTranscript()` is browser-safe; Node consumers can use `listRecentSessions()`, `readSessionTranscript()`, and `ObservedSessionCollector` across Claude Code, Codex, and OpenCode readers.
 - **Shared token estimation** — `estimateTextTokens()` / `estimateSerializedTokens()` provide an injectable exact-counter path and the stable tokenizer-free `sidekick-fallback-v1` heuristic.
@@ -39,16 +42,19 @@ shelling out to an executable **`sqlite3` on `PATH`**. There is no bundled
 driver. `CodexProvider` shells out to the same binary, but only for an optional
 index.
 
-Without it `OpenCodeProvider` returns **empty results rather than an error**,
-which is indistinguishable from an empty workspace. Call `getRuntimeStatus()`,
-implemented by `OpenCodeProvider` only, to tell the two apart:
+Without it, database-backed reads still return results rather than throwing —
+but as of 0.25.0 the missing binary is no longer invisible: Codex and OpenCode
+attach a `sqlite_missing` diagnostic to affected operations, so an unavailable
+runtime is distinguishable from an empty workspace. Construct providers through
+`createSessionProviders({ onDiagnostic })` to receive those diagnostics, or ask
+any provider directly — `getRuntimeStatus()` is implemented by all three:
 
 ```typescript
 const status = provider.getRuntimeStatus?.();
 // status.kind: 'available' | 'db_missing' | 'sqlite_missing'
-//            | 'sqlite_blocked' | 'query_failed'
+//            | 'sqlite_blocked' | 'query_failed' | ...
 if (status && status.kind !== 'available') {
-  console.warn(`Session data unavailable: ${status.kind}`);
+  console.warn(`Session data degraded: ${status.kind}`);
 }
 ```
 
@@ -76,56 +82,56 @@ returns the platform default that both overrides bypass.
 
 ## API Overview
 
-| Module                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Types**                       | Session events, OpenCode/Codex format types, persistence schemas (tasks, decisions, notes, plans, historical data)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Paths**                       | Config directory resolution, project data paths, workspace encoding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| **Readers**                     | Read tasks, decisions, notes, history, handoff, and plans from `~/.config/sidekick/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| **Writers**                     | Atomic persistence writers — `atomicWriteJson()` / `updateJsonStoreAtomic()` plus lock-coordinated capture helpers `addTask()`, `completeTask()`, `addDecision()`, `addNote()` that merge into the shared stores without clobbering concurrent writers                                                                                                                                                                                                                                                                                                                                                                                                               |
-| **Providers**                   | Session provider abstraction with Claude Code, OpenCode, and Codex implementations; auto-detection via filesystem                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| **Observed Sessions (V1)**      | Versioned provider-neutral observation contracts — `createProviderSessionAdapterV1()` / `derivePendingUserRequestV1()` with `ObservedAgentSessionV1`, `ProviderCapabilitiesV1`, `PendingUserRequestV1`, `SessionEvidenceRefV1`, and provenance/confidence wrapper types (Zod schemas in `sidekick-shared/schemas`)                                                                                                                                                                                                                                                                                                                                                   |
-| **Parsers**                     | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **Watchers**                    | Live session file watching with event bridging, plus `createJsonlTail()` for raw incremental JSONL consumers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **Formatters**                  | Display helpers (`formatTokenCount()`, `formatDurationMs()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **Search**                      | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Aggregation**                 | Event aggregation, frequency tracking, activity heatmaps, pattern extraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **Analytics**                   | Session-quality scoring (beta) with factor contributions and weekly trends (`scoreSessionQuality()`, `calculateQualityTrend()`), code-impact metrics including cost per changed line and per-model churn/cost (`calculateCodeImpact()`), and reported-vs-heuristic compaction accounting (`calculateCompactionLedger()`, `formatCompactionLedger()`)                                                                                                                                                                                                                                                                                                                 |
-| **Error History**               | Shared error taxonomy (`categorizeError()`, `extractErrorMessage()`) plus append-only per-project failure history (`appendErrorHistory()`, `readErrorHistory()`, `getTopFailingTools()`) behind per-tool/hour/model error rollups                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| **Session Context**             | Provider-neutral context evidence snapshots (`buildSessionContextSnapshot()`, `calculateSessionContextPressure()`, `createSessionContextProjector()`, `readSessionContextSnapshot()`): layered evidence sources, low/medium/high context pressure, and observed capabilities (tools, MCP servers, permission mode, rate limits)                                                                                                                                                                                                                                                                                                                                      |
-| **Assistant Turns**             | Browser-safe timeline/process/answer projection for provider-normalized assistant turns (`segmentAssistantTurn()`, `assistantTurnEventsFromSessionEvents()`), including interleaved reasoning, compact tool groups, and Claude `Task` subagent refs without prompt leakage                                                                                                                                                                                                                                                                                                                                                                                           |
-| **Report**                      | Self-contained HTML session report generation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **Credentials**                 | Claude Max OAuth credential reading from `~/.claude/.credentials.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| **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, and quota history — plus `extractSessionEvents()` to unwrap `progress`-wrapped events. 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()`, and display helpers (`shortModelName()`, `getModelDisplayInfo()`, `compareModelIds()`, `sortModelIds()`, `formatCost()`) |
-| **Quota Polling**               | `QuotaPoller` class with exponential backoff, active/idle intervals, and cached fallback                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| **Multi-Provider Quota**        | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex/z.ai quota updates behind one typed event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback; z.ai quota uses the API resolver with snapshot fallback                                                                                                                                                                                                                                                                                                                                                            |
-| **Accounts**                    | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for first-run bootstrap of the active system Claude/Codex credentials as a "Default" saved account, `getActiveAccountStatus()` for a single-pass active-account read across providers, and live-first `resolveActiveClaudeAccount()` / `resolveActiveCodexAccount()` that report the currently logged-in account (self-healing the saved pointer) for display                                                                                                                                                                     |
-| **Account Management 2.0**      | Provider-neutral acquisition + switching: `beginAccountLogin()` / `getAccountLoginStatus()` / `finalizeAccountLogin()` / `spawnAccountLogin()` drive a TTY-less, profile-isolated login that doesn't disturb the active account until finalization; `listAllAccounts()` and `switchAccount()` expose a shared switcher across Claude and Codex. Claude accounts get canonical profile homes with account-scoped macOS keychain suffixes and startup migration from legacy flat backups                                                                                                                                                                               |
-| **Terminal sync & auto-switch** | Opt-in terminal profile pointers, shell-hook/launcher helpers, and a default-off `AutoSwitchController` (`decideAutoSwitch()`) that moves to a healthier saved account when quota crosses a configured threshold                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Codex Profiles**              | Codex account lifecycle — prepare, finalize, switch, remove — switching atomically swaps the profile's backed-up credentials into the system `~/.codex/auth.json`, with rotated-token staleness protection, one-time dual-home migration, and legacy multi-home session monitoring                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Quota Snapshots**             | Persistent quota caching per provider/account for offline fallback                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| **Statusline**                  | Cache-only one-line account/quota/burn footer — `formatStatusline()`, `selectStatuslineAccount()`, `BurnRateCalculator`, and `estimateTimeToQuota()`, also published via the [`sidekick-shared/statusline`](#supported-import-paths) subpath for fast per-prompt rendering                                                                                                                                                                                                                                                                                                                                                                                           |
-| **Phrases**                     | Curated humorous phrases for loading/idle states, available as a flat `ALL_PHRASES` array or grouped via `PHRASE_CATEGORIES` for category-aware UI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Module                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Types**                       | Session events, OpenCode/Codex format types, persistence schemas (tasks, decisions, notes, plans, historical data)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Paths**                       | Config directory resolution, project data paths, workspace encoding                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| **Readers**                     | Read tasks, decisions, notes, history, handoff, and plans from `~/.config/sidekick/`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Writers**                     | Atomic persistence writers — `atomicWriteJson()` / `updateJsonStoreAtomic()` and their synchronous twins `atomicWriteJsonSync()` / `atomicWriteFileSync()` / `updateJsonStoreAtomicSync()` / `withFileLockSync()` (same cross-process lock file, progress-based timeouts, abandoned-lock reclaim), plus lock-coordinated capture helpers `addTask()`, `completeTask()`, `addDecision()`, `addNote()` that merge into the shared stores without clobbering concurrent writers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **Providers**                   | Session provider abstraction with Claude Code, OpenCode, and Codex implementations; auto-detection via filesystem. As of 0.25.0 constructors perform no environment I/O — build them all with `createSessionProviders({ onDiagnostic })`, which reports unavailable providers as structured diagnostics instead of failing; `findSessionById()` resolves one session through provider-native indexes; stable provider-id const arrays (`SESSION_PROVIDER_IDS`, `ACCOUNT_PROVIDER_IDS`, `QUOTA_PROVIDER_IDS`, `MODEL_PROVIDER_IDS`) accompany the derived unions                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Observed Sessions (V1)**      | Versioned provider-neutral observation contracts — `createProviderSessionAdapterV1()` / `derivePendingUserRequestV1()` with `ObservedAgentSessionV1`, `ProviderCapabilitiesV1`, `PendingUserRequestV1`, `SessionEvidenceRefV1`, and provenance/confidence wrapper types (Zod schemas in `sidekick-shared/schemas`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Parsers**                     | JSONL event parsing, OpenCode/Codex format normalization, subagent scanning, session path resolution, debug log parsing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **Watchers**                    | Live session file watching with event bridging, plus `createJsonlTail()` for raw incremental JSONL consumers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **Formatters**                  | Display helpers (`formatTokenCount()`, `formatDurationMs()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| **Search**                      | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Aggregation**                 | Event aggregation, frequency tracking, activity heatmaps, pattern extraction                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **Analytics**                   | Session-quality scoring (beta) with factor contributions and weekly trends (`scoreSessionQuality()`, `calculateQualityTrend()`), code-impact metrics including cost per changed line and per-model churn/cost (`calculateCodeImpact()`), and reported-vs-heuristic compaction accounting (`calculateCompactionLedger()`, `formatCompactionLedger()`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **Error History**               | Shared error taxonomy (`categorizeError()`, `extractErrorMessage()`) plus append-only per-project failure history (`appendErrorHistory()`, `readErrorHistory()`, `getTopFailingTools()`) behind per-tool/hour/model error rollups                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| **Session Context**             | Provider-neutral context evidence snapshots (`buildSessionContextSnapshot()`, `calculateSessionContextPressure()`, `createSessionContextProjector()`, `readSessionContextSnapshot()`): layered evidence sources, low/medium/high context pressure, and observed capabilities (tools, MCP servers, permission mode, rate limits)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| **Assistant Turns**             | Browser-safe timeline/process/answer projection for provider-normalized assistant turns (`segmentAssistantTurn()`, `assistantTurnEventsFromSessionEvents()`), including interleaved reasoning, compact tool groups, and Claude `Task` subagent refs without prompt leakage                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Report**                      | Self-contained HTML session report generation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **Credentials**                 | Claude Max OAuth credential reading from `~/.claude/.credentials.json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **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                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| **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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| **Multi-Provider Quota**        | `MultiProviderQuotaService` orchestrates Claude polling + peak-hours + account labels + Codex/z.ai quota updates behind one typed event stream. `CodexQuotaWatcher` watches the active Codex rollout for live rate limits with snapshot fallback; z.ai quota uses the API resolver with snapshot fallback. All three stay dormant without a matching account and wake on account changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| **Accounts**                    | Multi-provider account registry (v2) with per-provider active account, save/switch/remove, v1 migration, `ensureDefaultAccounts()` for first-run bootstrap of the active system Claude/Codex credentials as a "Default" saved account, `getActiveAccountStatus()` for a single-pass active-account read across providers, `onAccountsChanged()` for push-based login/logout/switch notification (process-local mutations, filesystem watches, and a catch-up poll), and live-first `resolveActiveClaudeAccount()` / `resolveActiveCodexAccount()` that report the currently logged-in account (self-healing the saved pointer) for display                                                                                                                                                                                                                                                                                                                                       |
+| **Account Management 2.0**      | Provider-neutral acquisition + switching: `beginAccountLogin()` / `getAccountLoginStatus()` / `finalizeAccountLogin()` / `spawnAccountLogin()` drive a TTY-less, profile-isolated login that doesn't disturb the active account until finalization; `listAllAccounts()` and `switchAccount()` expose a shared switcher across Claude and Codex. Every status/finalize/switch entry point also has an `-Async` variant (`getAccountLoginStatusAsync()`, `finalizeAccountLoginAsync()`, `switchAccountAsync()`, …) that keeps `codex` CLI probes off the event loop — prefer those from hosts with a UI loop. Claude accounts get canonical profile homes with account-scoped macOS keychain suffixes and startup migration from legacy flat backups                                                                                                                                                                                                                               |
+| **Terminal sync & auto-switch** | Opt-in terminal profile pointers, shell-hook/launcher helpers, and a default-off `AutoSwitchController` (`decideAutoSwitch()`) that moves to a healthier saved account when quota crosses a configured threshold; its `switchAccount` callback may return a Promise and defaults to `switchAccountAsync()`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Codex Profiles**              | Codex account lifecycle — prepare, finalize, switch, remove — switching atomically swaps the profile's backed-up credentials into the system `~/.codex/auth.json`, with rotated-token staleness protection, one-time dual-home migration, and legacy multi-home session monitoring                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Quota Snapshots**             | Persistent quota caching per provider/account for offline fallback                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Statusline**                  | Cache-only one-line account/quota/burn footer — `formatStatusline()`, `selectStatuslineAccount()`, `BurnRateCalculator`, and `estimateTimeToQuota()`, also published via the [`sidekick-shared/statusline`](#supported-import-paths) subpath for fast per-prompt rendering                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| **Phrases**                     | Curated humorous phrases for loading/idle states, available as a flat `ALL_PHRASES` array or grouped via `PHRASE_CATEGORIES` for category-aware UI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 ## Supported import paths
 
-`sidekick-shared` ships three public entry points plus a few convenience subpaths. Pick the one that matches your runtime.
+`sidekick-shared` ships three public entry points plus a few convenience subpaths. Pick the one that matches your runtime. As of 0.25.0 every documented subpath declares explicit `types` / `import` / `require` / `default` export conditions and resolves under Vite and TypeScript's legacy `moduleResolution: node` without consumer-side aliases.
 
-| Path                           | Runtime                    | What it exposes                                                                                                                                                                   |
-| ------------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sidekick-shared`              | Node (CLI, extension host) | Full public API (readers, providers, parsers, pricing, …).                                                                                                                        |
-| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math.                                                        |
-| `sidekick-shared/node`         | Node only                  | LiteLLM pricing and context-window hydration, observed context-window persistence, recent-session/transcript reads, and resilient observed-session collection (`fs` + providers). |
-| `sidekick-shared/phrases`      | Any runtime                | Phrase arrays + `getRandomPhrase()`.                                                                                                                                              |
-| `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, quota history) — fs-free, no Node builtins.                               |
-| `sidekick-shared/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers, `formatStatusline()`, and burn-rate estimates.                                                            |
+| Path                           | Runtime                    | What it exposes                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sidekick-shared`              | Node (CLI, extension host) | Full public API (readers, providers, parsers, pricing, …).                                                                                                                                                                                                                                                                                                                                                                    |
+| `sidekick-shared/browser`      | **Browser / webview**      | Pure helpers: usage normalization/pricing, token estimation, transcript and assistant-turn projection, model/context math, `parseMcpToolName()`.                                                                                                                                                                                                                                                                              |
+| `sidekick-shared/node`         | Node only                  | LiteLLM pricing and context-window hydration, observed context-window persistence, recent-session/transcript reads, session previews (`listSessionPreviews()` / `readSessionPreview()` plus the bounded-concurrency `listSessionPreviewsAsync()` / `readSessionPreviewAsync()`), Codex history/rollout lookup (`readCodexHistory()`, `findCodexRolloutFile()`), and resilient observed-session collection (`fs` + providers). |
+| `sidekick-shared/phrases`      | Any runtime                | Phrase arrays + `getRandomPhrase()`.                                                                                                                                                                                                                                                                                                                                                                                          |
+| `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/statusline`   | Node only                  | Cache-only statusline surface: account status + quota snapshot readers, `formatStatusline()`, and burn-rate estimates.                                                                                                                                                                                                                                                                                                        |
 
 ### Browser / webview runtimes
 
@@ -167,6 +173,31 @@ await loadObservedContextWindows();
 
 Both calls always resolve; a network failure, missing cache, or malformed store leaves lookups on the static tables. To record a window a provider reports at runtime, call `recordObservedContextWindow(modelId, window)` — it persists only when the value changes.
 
+### Transfer resolved model data across realms
+
+A realm that can hydrate (extension host, CLI) can hand its resolved context
+windows and pricing to one that cannot (webview, browser bundle) as one
+serializable snapshot — no private hooks, no re-hydration:
+
+```typescript
+// Node side (after hydratePricingCatalog / loadObservedContextWindows):
+import { exportResolvedModelCatalog } from 'sidekick-shared';
+const snapshot = exportResolvedModelCatalog(); // or pass specific model ids
+
+// Browser side:
+import { importResolvedModelCatalog, registerModelAlias } from 'sidekick-shared/browser';
+const { imported, diagnostics } = importResolvedModelCatalog(snapshot);
+```
+
+Entries carry provenance (`source`, `match`, `matchedModelId`, and
+`inheritedByPrefix` for pricing), so consumers can reject prefix-inherited
+guesses. Unresolved entries (`default` window / `none` pricing) are skipped on
+import rather than pinned, successive partial imports merge, and imported data
+ranks below anything the importing realm has observed first-hand.
+`registerModelAlias('sonnet', 'claude-sonnet-5')` resolves short or
+host-specific names everywhere lookups happen; data recorded under the alias id
+itself keeps winning over the canonical fallback.
+
 ### Normalize and price provider usage
 
 ```typescript
@@ -235,6 +266,56 @@ const humanCliPrompts = transcript.messages.filter(
 
 For an already-open incremental Codex rollout, keep one `CodexRolloutParser` per stream and pass each parsed `SessionEvent[]` batch to `projectSessionTranscript()` (or append the events to an existing projection). This preserves parser state for paired tool calls, model context, and cumulative token deltas; consumers should not convert raw `response_item` rows themselves.
 
+### Locate provider-native session files
+
+The library exports the same primitives its providers use to find session files on disk, so consumers never need to hand-roll path encoding or directory walks:
+
+```typescript
+import {
+  getClaudeSessionDirectory, // ~/.claude/projects/<encoded workspace>
+  encodeClaudeWorkspacePath, // the encoding itself, if you need the raw string
+  discoverSessionDirectory, // mismatch-tolerant lookup — prefer this for reads
+  findAllClaudeSessions,
+  findCodexRolloutFile, // Codex session id -> rollout file path
+  readCodexHistory, // bounded tail of ~/.codex/history.jsonl, newest first
+} from 'sidekick-shared';
+
+const sessions = findAllClaudeSessions('/home/user/code/my-project');
+
+const [latest] = readCodexHistory({ limit: 1 });
+const rolloutPath = latest ? findCodexRolloutFile(latest.sessionId) : null;
+```
+
+> **Naming trap:** the top-level `encodeWorkspacePath` export is Sidekick's own config-store slug (it keeps dots) and does **not** match Claude Code's directory scheme. For `~/.claude/projects/` paths always use `encodeClaudeWorkspacePath` — or better, `getClaudeSessionDirectory` / `discoverSessionDirectory`, which tolerate encoding drift.
+
+For a cross-provider "recent sessions" surface, `listSessionPreviews()` enumerates stat-only, sorts by mtime, applies `since`/`limit`, and only then does bounded content reads for the survivors — so cost tracks the size of the answer, not the size of the history:
+
+```typescript
+import { ClaudeCodeProvider, CodexProvider, listSessionPreviews } from 'sidekick-shared';
+
+const previews = listSessionPreviews([new ClaudeCodeProvider(), new CodexProvider()], {
+  limit: 10,
+  since: lastRefreshTime, // optional incremental refresh
+});
+// -> [{ provider, sessionId, filePath, modifiedAt, sizeBytes,
+//       firstUserPrompt, firstTimestamp, workspacePath }, ...]
+```
+
+`readSessionPreview(provider, filePath)` reads the same bounded preview for one known session file — `null` when the file is missing or unreadable, `null` fields when its content is malformed.
+
+Hosts with a UI loop should prefer the async variants from `sidekick-shared/node`. They read with bounded concurrency, yield between files, batch Codex/OpenCode label lookups into non-blocking `sqlite3` subprocesses, and — unlike their sync twins — return degradation status alongside the data:
+
+```typescript
+import { listSessionPreviewsAsync, readSessionPreviewAsync } from 'sidekick-shared/node';
+
+const { previews, diagnostics } = await listSessionPreviewsAsync(providers, { limit: 10 });
+const { preview } = await readSessionPreviewAsync(provider, filePath);
+```
+
+To resolve one session id to its file without scanning, every bundled provider implements `findSessionById(workspacePath, sessionId)` — a filename join for Claude Code and Codex, a database lookup for OpenCode — returning `null` for misses instead of reading transcripts. (It is optional on the `SessionProviderBase` interface so pre-0.25 external implementations keep compiling; fall back to `findAllSessions()` when absent.)
+
+MCP tool identifiers (`mcp__<server>__<tool>`) split with `parseMcpToolName(name)` — first-double-underscore rule, `null` for malformed names, safe in browser bundles.
+
 ### Collect observed sessions with isolation and retry
 
 ```typescript
@@ -258,10 +339,55 @@ applyReadOnlyProjection(source.capabilities);
 
 Discovery and reads are isolated, retries use bounded 30-second-to-5-minute exponential backoff, file changes bypass delay, duplicate identical failures are suppressed, and recovery emits a content-free diagnostic. Clock and fingerprint callbacks are injectable for deterministic hosts/tests.
 
+As of 0.25.0, parses are cached by fingerprint — a second `collect()` over unchanged files performs no content reads (cache hits refresh `observedAt` and activity state; `contentObservedAt` reports how old the cached usage/model data actually is, and `cacheHit` marks them). Observations expose structured `fingerprintParts: { sizeBytes, mtimeMs }` alongside the opaque fingerprint string, and diagnostics carry `severity` and `phase` in addition to their existing `kind`.
+
+Instead of a host polling loop, subscribe to debounced change batches. Each change carries the previous and current fingerprints; filesystem watching is combined with a catch-up poll for filesystems that drop events:
+
+```typescript
+const subscription = collector.subscribe(
+  (batch) => {
+    for (const change of batch.changes) {
+      // change.type: 'added' | 'changed' | 'removed'
+      console.log(batch.providerId, change.type, change.reference.sessionId);
+      console.log(change.previousFingerprint, '→', change.fingerprint);
+    }
+    void collector.collect(); // consume changed sessions through the parse cache
+  },
+  { debounceMs: 250, pollIntervalMs: 30_000 },
+);
+// later: subscription.dispose();
+```
+
+`SessionMonitor.subscribe()` offers the same push model at the session-event level.
+
 ## Usage Examples
 
+### Construct session providers for a long-lived host
+
+`createSessionProviders()` builds every requested provider without probing the
+filesystem or binaries — constructors are I/O-free as of 0.25.0, so one
+unavailable provider cannot abort host startup. Environmental failures surface
+on first use as structured diagnostics instead:
+
+```typescript
+import { createSessionProviders } from 'sidekick-shared';
+
+const { providers, diagnostics } = createSessionProviders({
+  onDiagnostic: (diagnostic) => {
+    // e.g. { providerId: 'opencode', kind: 'sqlite_missing',
+    //        severity: 'warning', phase: 'query', message: '...' }
+    log(diagnostic);
+  },
+});
+```
+
+Repeated identical degradations are coalesced, so the diagnostic stream stays
+bounded across long-lived polling and subscription cycles.
+
 ### Detect the active session provider
 
+For a single-provider surface, auto-detect and construct just one:
+
 ```typescript
 import {
   detectProvider,
@@ -477,7 +603,7 @@ const parser = new JsonlParser(
 parser.processChunk(rawData);
 ```
 
-The boundary schemas — `sessionEventSchema` plus the quota, account-status, and quota-history schemas — are also importable fs-free from `sidekick-shared/schemas`, which keeps Zod out of bundles that only need the pure math/formatting helpers. `extractSessionEvents()` from the same subpath unwraps Claude Code `progress`-wrapped events into canonical `SessionEvent[]`.
+The boundary schemas — `sessionEventSchema` plus the quota, account-status, account-management, and quota-history schemas — are also importable fs-free from `sidekick-shared/schemas`, which keeps Zod out of bundles that only need the pure math/formatting helpers. Account and quota APIs are guaranteed to return values valid against the schemas exported in the same release, so consumers do not need to parse those library results again. Additive account or quota fields are added to the matching exported schema in the same release. `extractSessionEvents()` from the same subpath unwraps Claude Code `progress`-wrapped events into canonical `SessionEvent[]`.
 
 ### Tail raw JSONL events incrementally
 
@@ -553,6 +679,28 @@ console.log(status.claude.present, status.claude.email);
 console.log(status.codex.present, status.codex.label);
 ```
 
+To react to logins, logouts, and switches without polling that status yourself,
+subscribe to `onAccountsChanged()`. It combines process-local mutation signals,
+filesystem watches on the account stores, and a low-frequency catch-up poll —
+and only emits when the status actually changed:
+
+```typescript
+import { onAccountsChanged } from 'sidekick-shared';
+
+const subscription = onAccountsChanged(
+  ({ reason, status }) => {
+    // reason: 'local' | 'filesystem' | 'poll'
+    render(status.claude, status.codex);
+  },
+  { emitCurrent: true },
+);
+// later: subscription.dispose();
+```
+
+`QuotaPoller`, `MultiProviderQuotaService`, and `CodexQuotaWatcher` use the same
+signal internally: they stay dormant while no matching account exists and wake
+when one appears.
+
 For display surfaces that must reflect the **currently logged-in** account — even after a native `claude /login` or `codex login` outside Sidekick — use the live-first resolvers. They prefer the live provider auth (`~/.claude/.claude.json` oauthAccount; the `~/.codex/auth.json` id_token JWT) over the saved `activeByProvider` pointer, fall back to the registry, and self-heal the saved pointer on an unambiguous match (best-effort, never creating or deleting profiles):
 
 ```typescript

package/dist/accountChangeSignal.d.ts

@@ -0,0 +1,3 @@
+export type AccountChangeReason = 'local' | 'filesystem' | 'poll';
+export declare function _onRawAccountsChanged(listener: (reason: AccountChangeReason) => void): () => void;
+export declare function _emitAccountsChanged(reason: AccountChangeReason): void;

package/dist/accountChangeSignal.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._onRawAccountsChanged = _onRawAccountsChanged;
+exports._emitAccountsChanged = _emitAccountsChanged;
+const listeners = new Set();
+function _onRawAccountsChanged(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function _emitAccountsChanged(reason) {
+    for (const listener of listeners) {
+        try {
+            listener(reason);
+        }
+        catch {
+            // Account notifications are observational and cannot break mutations.
+        }
+    }
+}

package/dist/accountChanges.d.ts

@@ -0,0 +1,21 @@
+import { type AccountChangeReason } from './accountChangeSignal';
+import { type ActiveAccountStatus } from './accountStatus';
+import type { Disposable } from './quotaPoller';
+export interface AccountsChangedEvent {
+    reason: AccountChangeReason;
+    status: ActiveAccountStatus;
+}
+export interface OnAccountsChangedOptions {
+    /** Emit the current status immediately after subscribing. */
+    emitCurrent?: boolean;
+    /** Catch-up poll for filesystems where watch delivery is unreliable. Default: 30s. */
+    pollIntervalMs?: number;
+}
+/**
+ * Observe login, logout, and active-account switches. Local Sidekick mutations
+ * signal immediately; filesystem watchers cover external CLIs; a low-frequency
+ * catch-up poll protects network mounts and watcher-hostile filesystems.
+ */
+export declare function onAccountsChanged(listener: (event: AccountsChangedEvent) => void, options?: OnAccountsChangedOptions): Disposable;
+/** Internal bridge for account mutations outside the registry module. */
+export declare function _notifyAccountsChanged(): void;