sidekick-shared 0.26.0 → 0.26.1

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.1] - 2026-09-05
+
+### Fixed
+
+- Static model metadata verified on 2026-09-05 adds exact Fable 5.1 pricing/context entries in dashed and dotted forms, with its $0.25/M cache-read rate, and GPT-6 Astra pricing with a 1.05M context window. GPT-5.6 Sol/Terra/Luna rates and the Sol alias are current; GPT-5.4 mini cache reads cost $0.075/M and mini/nano context windows are 400K. Sonnet 5's permanent $2/$10 rate is documented. Catalog overrides, observed limits, and historical models are preserved.
+- `resolveQuota({ preferFresh: false })` tries the API before local samples when API access is allowed. Failed live queries select the newer session or cached sample by capture time, prefer the cache on ties, and retain the API failure. Only a selected session sample is persisted.
+- Codex quota failures name Codex instead of Claude or Anthropic. Default cache preferences and API-disabled resolution are unchanged.
+
 ## [0.26.0] - 2026-09-05
 
 ### Added

package/README.md

@@ -9,7 +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.
+- **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()` shares quota resolution across CLI, MCP, and dashboard startup, with default local-sample preferences and an API-first option used by one-shot Codex queries; `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.
@@ -475,24 +475,25 @@ if (!peak.unavailable && peak.isPeak) {
 }
 ```
 
-### Resolve quota with one precedence
+### Resolve quota with shared source policies
 
 ```typescript
 import { resolveQuota } from 'sidekick-shared';
 
-// Fresh persisted sample (status line, session, or API; under five minutes) →
+// Default: 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.
+// Ask the API before any local sample: used by every one-shot Codex query
+// and by --refresh for other providers. API failures retain local fallbacks.
 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.
+`resolveQuota()` is shared by `sidekick quota`, `quota --all`, the MCP `get_quota_status` tool, and dashboard startup. CLI and MCP Codex queries pass `preferFresh: false` to fetch live utilization and reset credits every time; dashboard schedules and default cache preferences are unchanged. After a failed live query, the newer session or persisted sample wins by `capturedAt`, with ties going to the persisted sample and missing timestamps treated as oldest. Only a selected session sample is persisted. Fallback results keep their source and age plus the API `failure` descriptor. `allowApi: false` always prevents network access, including when `preferFresh` is false. Every side effect is injectable (`readSnapshot`, `writeSnapshot`, `fetchImpl`, `getClaudeAccessToken`, the account resolvers) for tests.
 
 ### Fetch subscription quota
 

package/dist/modelContext.js

@@ -42,9 +42,11 @@ exports._getModelContextIds = _getModelContextIds;
 exports.resolveModelContextWindow = resolveModelContextWindow;
 exports.getModelContextWindowSize = getModelContextWindowSize;
 const modelAliases_1 = require("./modelAliases");
-/** Known model context window sizes (in tokens). */
+/** Known model context window sizes (in tokens); current models verified 2026-09-05. */
 const MODEL_CONTEXT_SIZES = {
-    // Claude — native 1M context (Fable 5, Opus 4.6+, Sonnet 4.6+)
+    // Claude — native 1M context (Fable 5+, Opus 4.6+, Sonnet 4.6+)
+    'claude-fable-5-1': 1_000_000,
+    'claude-fable-5.1': 1_000_000,
     'claude-fable-5': 1_000_000,
     'claude-opus-5': 1_000_000,
     'claude-opus-4-8': 1_000_000,
@@ -67,16 +69,19 @@ const MODEL_CONTEXT_SIZES = {
     'claude-3-haiku': 200_000,
     // OpenAI GPT-4.1 series (1M context)
     'gpt-4.1': 1_048_576,
-    // OpenAI GPT-5 series (keys sorted longest-first below; explicit entries
+    // OpenAI GPT-5/6 series (keys sorted longest-first below; explicit entries
     // for every variant so prefix matching can't misclassify a new one).
     // These are published model maxima. Codex reports a smaller *effective*
     // window per account tier via token_count; that value wins through the
     // observed-override layer.
+    'gpt-6-astra': 1_050_000,
     'gpt-5.6-sol': 1_050_000,
     'gpt-5.6-terra': 1_050_000,
     'gpt-5.6-luna': 1_050_000,
     'gpt-5.6': 1_050_000,
     'gpt-5.5': 1_050_000,
+    'gpt-5.4-mini': 400_000,
+    'gpt-5.4-nano': 400_000,
     'gpt-5.4': 1_050_000,
     'gpt-5.3-codex-spark': 128_000,
     'gpt-5.3-codex': 400_000,

package/dist/modelInfo.js

@@ -50,9 +50,10 @@ Object.defineProperty(exports, "MODEL_PROVIDER_IDS", { enumerable: true, get: fu
  * against `claude-sonnet-4.5`.
  *
  * Sources:
- *   - Anthropic: https://www.anthropic.com/pricing
- *   - OpenAI: https://openai.com/api/pricing/
- * Snapshot taken: 2026-06-09. Runtime LiteLLM hydration refreshes this.
+ *   - Anthropic: https://platform.claude.com/docs/en/about-claude/pricing
+ *   - OpenAI: https://developers.openai.com/api/docs/models
+ * Current Anthropic and GPT-5.6/6 rates verified: 2026-09-05.
+ * Runtime LiteLLM hydration refreshes this offline baseline.
  *
  * Anthropic keys appear in both dashed (`claude-opus-4-8`, the real model-ID
  * form) and dotted (`claude-opus-4.8`, the LiteLLM catalog form) spellings —
@@ -60,6 +61,19 @@ Object.defineProperty(exports, "MODEL_PROVIDER_IDS", { enumerable: true, get: fu
  */
 const PRICING_TABLE = {
     // ── Anthropic: Claude ──
+    // Fable 5.1 cache reads cost 0.025x input; Fable 5 retains its 0.1x rate.
+    'claude-fable-5-1': {
+        inputCostPerMillion: 10.0,
+        outputCostPerMillion: 50.0,
+        cacheWriteCostPerMillion: 12.5,
+        cacheReadCostPerMillion: 0.25,
+    },
+    'claude-fable-5.1': {
+        inputCostPerMillion: 10.0,
+        outputCostPerMillion: 50.0,
+        cacheWriteCostPerMillion: 12.5,
+        cacheReadCostPerMillion: 0.25,
+    },
     'claude-fable-5': {
         inputCostPerMillion: 10.0,
         outputCostPerMillion: 50.0,
@@ -84,11 +98,8 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 1.0,
         cacheReadCostPerMillion: 0.08,
     },
-    // Sonnet 5 carries the standard rate here. The introductory $2/$10 (through
-    // 2026-08-31) arrives via catalog hydration, which supersedes this baseline.
-    // Sonnet 5 is $2/$10, not the $3/$15 every earlier Sonnet charged, and it
-    // carries no >200K surcharge the way Sonnet 4.5 does. The catalog agrees
-    // across all eleven of its Sonnet 5 entries.
+    // Sonnet 5's $2/$10 introductory rate is now permanent. Standard pricing
+    // applies across its full 1M context window.
     'claude-sonnet-5': {
         inputCostPerMillion: 2.0,
         outputCostPerMillion: 10.0,
@@ -234,37 +245,44 @@ const PRICING_TABLE = {
         cacheWriteCostPerMillion: 0,
         cacheReadCostPerMillion: 0,
     },
-    // ── OpenAI: GPT-5 family ──
-    // Published rates, verified against the LiteLLM catalog. Runtime hydration
+    // ── OpenAI: GPT-5/6 families ──
+    // Published rates, cross-checked with the LiteLLM catalog. Runtime hydration
     // still supersedes these; they are the offline baseline.
     //
     // Every tier that ships at a rate of its own needs an entry of its own. Keys
     // are matched longest-first, so a `-mini`/`-nano`/`-pro` variant with no entry
     // silently inherits its base model's rate and reports a wrong number rather
     // than none — `gpt-5-nano` read 25x its true cost this way.
+    'gpt-6-astra': {
+        inputCostPerMillion: 10.0,
+        outputCostPerMillion: 50.0,
+        cacheWriteCostPerMillion: 12.5,
+        cacheReadCostPerMillion: 1.0,
+    },
     'gpt-5.6-sol': {
-        inputCostPerMillion: 5.0,
-        outputCostPerMillion: 30.0,
-        cacheWriteCostPerMillion: 6.25,
-        cacheReadCostPerMillion: 0.5,
+        inputCostPerMillion: 4.0,
+        outputCostPerMillion: 20.0,
+        cacheWriteCostPerMillion: 5.0,
+        cacheReadCostPerMillion: 0.4,
     },
     'gpt-5.6-terra': {
-        inputCostPerMillion: 2.5,
-        outputCostPerMillion: 15.0,
-        cacheWriteCostPerMillion: 3.13,
-        cacheReadCostPerMillion: 0.25,
+        inputCostPerMillion: 2.0,
+        outputCostPerMillion: 12.0,
+        cacheWriteCostPerMillion: 2.5,
+        cacheReadCostPerMillion: 0.2,
     },
     'gpt-5.6-luna': {
-        inputCostPerMillion: 1.0,
-        outputCostPerMillion: 6.0,
-        cacheWriteCostPerMillion: 1.25,
-        cacheReadCostPerMillion: 0.1,
+        inputCostPerMillion: 0.2,
+        outputCostPerMillion: 1.2,
+        cacheWriteCostPerMillion: 0.25,
+        cacheReadCostPerMillion: 0.02,
     },
+    // The GPT-5.6 alias routes to Sol.
     'gpt-5.6': {
-        inputCostPerMillion: 5.0,
-        outputCostPerMillion: 30.0,
-        cacheWriteCostPerMillion: 6.25,
-        cacheReadCostPerMillion: 0.5,
+        inputCostPerMillion: 4.0,
+        outputCostPerMillion: 20.0,
+        cacheWriteCostPerMillion: 5.0,
+        cacheReadCostPerMillion: 0.4,
     },
     'gpt-5.5-pro': {
         inputCostPerMillion: 30.0,
@@ -282,7 +300,7 @@ const PRICING_TABLE = {
         inputCostPerMillion: 0.75,
         outputCostPerMillion: 4.5,
         cacheWriteCostPerMillion: 0,
-        cacheReadCostPerMillion: 0.07,
+        cacheReadCostPerMillion: 0.075,
     },
     'gpt-5.4-nano': {
         inputCostPerMillion: 0.2,

package/dist/quotaPresentation.js

@@ -23,8 +23,20 @@ function formatRetryAfter(ms) {
 function describeQuotaFailure(quota) {
     if (!quota || quota.available || !quota.failureKind)
         return null;
+    const isCodex = quota.providerId === 'codex';
+    const apiName = isCodex ? 'Codex' : 'Anthropic';
     switch (quota.failureKind) {
         case 'auth':
+            if (isCodex) {
+                return {
+                    severity: 'error',
+                    title: quota.httpStatus ? 'Codex sign-in expired' : 'Codex sign-in required',
+                    message: quota.error ?? 'The current Codex login could not be used.',
+                    detail: 'Run `codex login` to sign in, then retry quota refresh.',
+                    alertKey: `auth:${quota.httpStatus ?? 'no-credentials'}`,
+                    isRetryable: false,
+                };
+            }
             if (quota.error === 'No OAuth token available') {
                 return {
                     severity: 'error',
@@ -47,7 +59,7 @@ function describeQuotaFailure(quota) {
             return {
                 severity: 'warning',
                 title: 'Quota API unreachable',
-                message: 'Could not reach Anthropic from the current environment.',
+                message: `Could not reach ${apiName} from the current environment.`,
                 detail: 'Check connectivity, proxy, or firewall settings, then retry.',
                 alertKey: 'network',
                 isRetryable: true,
@@ -59,7 +71,7 @@ function describeQuotaFailure(quota) {
                 message: quota.retryAfterMs != null
                     ? `Retry in ${formatRetryAfter(quota.retryAfterMs)}.`
                     : 'Retry shortly.',
-                detail: quota.httpStatus != null ? `Anthropic returned HTTP ${quota.httpStatus}.` : undefined,
+                detail: quota.httpStatus != null ? `${apiName} returned HTTP ${quota.httpStatus}.` : undefined,
                 alertKey: `rate_limit:${quota.httpStatus ?? 429}`,
                 isRetryable: true,
             };
@@ -68,8 +80,8 @@ function describeQuotaFailure(quota) {
                 severity: 'warning',
                 title: 'Quota API unavailable',
                 message: quota.httpStatus != null
-                    ? `Anthropic returned HTTP ${quota.httpStatus}. Try again shortly.`
-                    : 'Anthropic quota data is temporarily unavailable.',
+                    ? `${apiName} returned HTTP ${quota.httpStatus}. Try again shortly.`
+                    : `${apiName} quota data is temporarily unavailable.`,
                 alertKey: `server:${quota.httpStatus ?? 'unknown'}`,
                 isRetryable: true,
             };
@@ -78,7 +90,7 @@ function describeQuotaFailure(quota) {
                 severity: 'error',
                 title: 'Unexpected quota response',
                 message: quota.httpStatus != null
-                    ? `Anthropic returned HTTP ${quota.httpStatus}.`
+                    ? `${apiName} returned HTTP ${quota.httpStatus}.`
                     : (quota.error ?? 'Quota data could not be retrieved.'),
                 detail: 'This failure is not classified as retryable.',
                 alertKey: `unknown:${quota.httpStatus ?? 'none'}`,

package/dist/quotaResolver.d.ts

@@ -3,7 +3,7 @@
  *
  * `sidekick quota`, `quota --all`, the MCP facts server, and both dashboards
  * used to pick between the live API, session logs, and the persisted snapshot
- * in four different orders. `resolveQuota()` applies one precedence:
+ * in four different orders. `resolveQuota()` defaults to this precedence:
  *
  * 1. a fresh persisted snapshot (younger than `QUOTA_FRESH_MAX_AGE_MS`, whatever
  *    its origin: the official status-line sample, a session log, or an earlier
@@ -14,7 +14,9 @@
  * 4. an aging or stale snapshot, labelled as such, with the API failure attached;
  * 5. an unavailable state describing why nothing could be resolved.
  *
- * `preferFresh: false` skips step 1 (the `--refresh` flag). Every result carries
+ * `preferFresh: false` asks the API first when allowed (the `--refresh` flag
+ * and one-shot Codex queries). On failure, the newer session or persisted
+ * sample wins, with ties going to the persisted sample. Every result carries
  * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
  */
 import type { ResolvedActiveAccount, SavedAccountProfile } from './accountRegistry';
@@ -38,9 +40,9 @@ export interface ResolveQuotaOptions<T extends QuotaResolveProviderId = QuotaRes
     accountId?: string;
     /** Workspace whose Codex rollouts are searched first for session-derived rate limits. */
     workspacePath?: string;
-    /** Use a fresh persisted snapshot before anything else (default true). `--refresh` passes false. */
+    /** Prefer local samples (default true). False asks the API before any local sample when allowed. */
     preferFresh?: boolean;
-    /** Allow a provider API call when no fresh local sample exists (default true). */
+    /** Allow provider API calls (default true), including when preferFresh is false. */
     allowApi?: boolean;
     /** Re-point a stale saved-account pointer while resolving the account (default true). */
     selfHeal?: boolean;

package/dist/quotaResolver.js

@@ -4,7 +4,7 @@
  *
  * `sidekick quota`, `quota --all`, the MCP facts server, and both dashboards
  * used to pick between the live API, session logs, and the persisted snapshot
- * in four different orders. `resolveQuota()` applies one precedence:
+ * in four different orders. `resolveQuota()` defaults to this precedence:
  *
  * 1. a fresh persisted snapshot (younger than `QUOTA_FRESH_MAX_AGE_MS`, whatever
  *    its origin: the official status-line sample, a session log, or an earlier
@@ -15,7 +15,9 @@
  * 4. an aging or stale snapshot, labelled as such, with the API failure attached;
  * 5. an unavailable state describing why nothing could be resolved.
  *
- * `preferFresh: false` skips step 1 (the `--refresh` flag). Every result carries
+ * `preferFresh: false` asks the API first when allowed (the `--refresh` flag
+ * and one-shot Codex queries). On failure, the newer session or persisted
+ * sample wins, with ties going to the persisted sample. Every result carries
  * `source`, `capturedSource`, `freshness`, `ageMs`, and a `resolution` tag.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -146,6 +148,10 @@ function snapshotResolution(state) {
         return 'snapshot-aging';
     return 'snapshot-stale';
 }
+function captureTimeMs(state) {
+    const capturedMs = state.capturedAt ? Date.parse(state.capturedAt) : NaN;
+    return Number.isFinite(capturedMs) ? capturedMs : Number.NEGATIVE_INFINITY;
+}
 /**
  * Resolve the current quota for one provider with the shared precedence
  * described at the top of this file.
@@ -160,6 +166,7 @@ async function resolveQuota(options) {
     const capturedAt = now.toISOString();
     const preferFresh = options.preferFresh ?? true;
     const allowApi = options.allowApi ?? true;
+    const apiFirst = !preferFresh && allowApi;
     const readSnapshot = options.readSnapshot ?? quotaSnapshots_1.readQuotaSnapshot;
     const writeSnapshot = options.writeSnapshot ?? quotaSnapshots_1.writeQuotaSnapshot;
     const identity = resolveIdentity(options);
@@ -178,19 +185,27 @@ async function resolveQuota(options) {
     if (preferFresh && snapshot && snapshot.freshness === 'fresh') {
         return finish(snapshot, 'snapshot-fresh');
     }
-    if (providerId === 'codex') {
-        const local = (0, codexQuota_1.resolveCodexQuotaFromLocalSources)({
-            workspacePath: options.workspacePath,
-            provider: options.codexProvider,
-            activeAccount: identity.codexAccount,
-            codexHome: options.codexHome,
-            // Only rollout hits count as "session-derived"; the snapshot fallback is
-            // handled below so it can be labelled by age.
-            readSnapshot: () => null,
-            writeSnapshot,
-        });
-        if (local)
-            return finish(local, 'session');
+    const readLocalCodex = () => (0, codexQuota_1.resolveCodexQuotaFromLocalSources)({
+        workspacePath: options.workspacePath,
+        provider: options.codexProvider,
+        activeAccount: identity.codexAccount,
+        codexHome: options.codexHome,
+        // Only rollout hits count as "session-derived"; the snapshot fallback is
+        // handled below so it can be labelled by age.
+        readSnapshot: () => null,
+        // Inspect candidates without overwriting the persisted fallback. Only
+        // the selected session sample is written, using the resolved account key.
+        writeSnapshot: () => { },
+    });
+    const finishLocal = (local) => {
+        if (identity.accountId)
+            writeSnapshot('codex', identity.accountId, local);
+        return finish(local, 'session');
+    };
+    if (providerId === 'codex' && !apiFirst) {
+        const local = readLocalCodex();
+        if (local?.available)
+            return finishLocal(local);
     }
     let apiState = null;
     if (allowApi) {
@@ -202,6 +217,12 @@ async function resolveQuota(options) {
             return finish(apiState, 'api');
         }
     }
+    if (providerId === 'codex' && apiFirst) {
+        const local = readLocalCodex();
+        if (local?.available && (!snapshot || captureTimeMs(local) > captureTimeMs(snapshot))) {
+            return { ...finishLocal(local), failure: (0, quotaPresentation_1.describeQuotaFailure)(apiState) };
+        }
+    }
     if (snapshot) {
         const fallback = finish(snapshot, snapshotResolution(snapshot));
         return apiState ? { ...fallback, failure: (0, quotaPresentation_1.describeQuotaFailure)(apiState) } : fallback;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.26.0",
+  "version": "0.26.1",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "keywords": [
     "claude-code",