@leo000001/opencode-quota-sidebar 2.0.1 → 2.0.2

package/README.md

@@ -13,7 +13,7 @@ Add the package name to `plugin` in your `opencode.json`. OpenCode uses Bun to i
 
 ```json
 {
-  "plugin": ["@leo000001/opencode-quota-sidebar@2.0.0"]
+  "plugin": ["@leo000001/opencode-quota-sidebar@2.0.1"]
 }
 ```
 
@@ -64,13 +64,13 @@ Want to add support for another provider (Google Antigravity, Zhipu AI, Firmware
   - quota lines: quota text like `OpenAI 5h 80% Rst 16:20`; short windows (`5h`, `1d`, `Daily`) show `HH:MM` on same-day resets and `MM-DD HH:MM` when crossing days, while longer windows continue to show `MM-DD`
   - RightCode daily quota shows `$remaining/$dailyTotal` + expiry (e.g. `RC Daily $105/$60 Exp 02-27`, without trailing percent) and also shows balance on the next indented line when available; `Exp` remains date-only
 - Session-scoped usage/quota can include descendant subagent sessions (enabled by default via `sidebar.includeChildren=true`). Traversal is bounded by `childrenMaxDepth` (default 6), `childrenMaxSessions` (default 128), and `childrenConcurrency` (default 5); truncation is logged when `OPENCODE_QUOTA_DEBUG=1`. Day/week/month ranges never merge children — only session scope does.
-- Toast message includes three sections: `Token Usage`, `Cost as API` (per provider), and `Quota`
+- Toast message can include four sections: `Token Usage`, `Cost as API` (per provider), `Provider Cache` (when provider-level cache coverage is available), and `Quota`
 - `quota_summary` markdown / toast also include `Cache Coverage` and `Cache Read Coverage` summary lines when available
 - Quota snapshots are de-duplicated before rendering to avoid repeated provider lines
 - Custom tools:
   - `quota_summary` — generate usage report for session/day/week/month (markdown + toast)
 - `quota_show` — toggle sidebar title display on/off (state persists across sessions)
-- After startup, titles refresh on the next relevant session/message event or when `quota_show` is toggled
+- After startup, titles are restored immediately when persisted display mode is OFF; when persisted display mode is ON, touched titles refresh on startup and the rest update on the next relevant session/message event or when `quota_show` is toggled
 - Quota connectors:
   - OpenAI Codex OAuth (`/backend-api/wham/usage`)
   - GitHub Copilot OAuth (`/copilot_internal/user`)
@@ -90,12 +90,17 @@ The plugin stores lightweight global state and date-partitioned session chunks.
   - `titleEnabled`
   - `sessionDateMap` (sessionID -> `YYYY-MM-DD`)
   - `quotaCache`
-- Session chunks: `<opencode-data>/quota-sidebar-sessions/YYYY/MM/DD.json`
-  - per-session title state (`baseTitle`, `lastAppliedTitle`)
-  - `createdAt`
-  - `parentID` (when the session is a subagent child session)
-  - cached usage summary used by `quota_summary`
-  - incremental aggregation cursor
+- Session chunks: `<opencode-data>/quota-sidebar-sessions/YYYY/MM/DD.json`
+  - per-session title state (`baseTitle`, `lastAppliedTitle`)
+  - `createdAt`
+  - `parentID` (when the session is a subagent child session)
+  - cached usage summary used by `quota_summary`, including session-level and provider-level `cacheBuckets` for cache coverage reporting
+  - incremental aggregation cursor
+
+Notes on cache coverage persistence:
+
+- Older cached usage written before `cacheBuckets` existed can only be approximated from top-level `cache_read` / `cache_write` totals.
+- In those legacy cases, mixed read-only + read-write cache traffic may be attributed to a single fallback bucket until the session is recomputed from messages.
 
 Example tree:
 

package/dist/format.js

@@ -1,4 +1,4 @@
-import { getCacheCoverageMetrics } from './usage.js';
+import { getCacheCoverageMetrics, getProviderCacheCoverageMetrics, } from './usage.js';
 import { canonicalProviderID, collapseQuotaSnapshots, displayShortLabel, quotaDisplayLabel, } from './quota_render.js';
 import { stripAnsi } from './title.js';
 /** M6 fix: handle negative, NaN, Infinity gracefully. */
@@ -161,6 +161,16 @@ function formatPercent(value, decimals = 1) {
     const pct = (safe * 100).toFixed(decimals);
     return `${pct.replace(/\.0+$/, '').replace(/(\.\d*[1-9])0+$/, '$1')}%`;
 }
+function formatQuotaPercent(value, options) {
+    const missing = options?.missing ?? '-';
+    if (value === undefined)
+        return missing;
+    if (!Number.isFinite(value) || value < 0)
+        return missing;
+    if (options?.rounded)
+        return `${Math.round(value)}%`;
+    return `${value.toFixed(options?.decimals ?? 1)}%`;
+}
 function alignPairs(pairs, indent = '  ') {
     if (pairs.length === 0)
         return [];
@@ -187,9 +197,10 @@ function compactQuotaInline(quota) {
         const first = quota.windows[0];
         const showPercent = first.showPercent !== false;
         const firstLabel = sanitizeLine(first.label || '');
-        const pct = first.remainingPercent === undefined
-            ? undefined
-            : `${Math.round(first.remainingPercent)}%`;
+        const pct = formatQuotaPercent(first.remainingPercent, {
+            rounded: true,
+            missing: '',
+        });
         const summary = showPercent
             ? [firstLabel, pct].filter(Boolean).join(' ')
             : firstLabel.replace(/^Daily\s+/i, '') || firstLabel;
@@ -200,8 +211,12 @@ function compactQuotaInline(quota) {
     if (quota.balance) {
         return `${label} Balance ${formatCurrency(quota.balance.amount, quota.balance.currency)}`;
     }
-    if (quota.remainingPercent !== undefined) {
-        return `${label} ${Math.round(quota.remainingPercent)}%`;
+    const singlePercent = formatQuotaPercent(quota.remainingPercent, {
+        rounded: true,
+        missing: '',
+    });
+    if (singlePercent) {
+        return `${label} ${singlePercent}`;
     }
     return label;
 }
@@ -351,9 +366,7 @@ function compactQuotaWide(quota, labelWidth = 0, options) {
         : undefined;
     const renderWindow = (win) => {
         const showPercent = win.showPercent !== false;
-        const pct = win.remainingPercent === undefined
-            ? '?'
-            : `${Math.round(win.remainingPercent)}%`;
+        const pct = formatQuotaPercent(win.remainingPercent, { rounded: true });
         const parts = win.label
             ? showPercent
                 ? [sanitizeLine(win.label), pct]
@@ -387,9 +400,7 @@ function compactQuotaWide(quota, labelWidth = 0, options) {
         return maybeBreak(balanceText, [balanceText]);
     }
     // Fallback: single value from top-level remainingPercent
-    const percent = quota.remainingPercent === undefined
-        ? '?'
-        : `${Math.round(quota.remainingPercent)}%`;
+    const percent = formatQuotaPercent(quota.remainingPercent, { rounded: true });
     const reset = compactReset(quota.resetAt, 'Rst');
     const fallbackText = `Remaining ${percent}${reset ? ` Rst ${reset}` : ''}`;
     return maybeBreak(fallbackText, [fallbackText]);
@@ -499,12 +510,71 @@ export function renderMarkdownReport(period, usage, quotas, options) {
             return '-';
         return formatApiCostValue(usage.apiCost);
     };
-    const providerRows = Object.values(usage.providers)
-        .sort((a, b) => b.total - a.total)
+    const cacheCoverageCell = (provider) => {
+        const metrics = getProviderCacheCoverageMetrics(provider);
+        return metrics.cacheCoverage !== undefined
+            ? formatPercent(metrics.cacheCoverage, 1)
+            : '-';
+    };
+    const cacheReadCoverageCell = (provider) => {
+        const metrics = getProviderCacheCoverageMetrics(provider);
+        return metrics.cacheReadCoverage !== undefined
+            ? formatPercent(metrics.cacheReadCoverage, 1)
+            : '-';
+    };
+    const providerEntries = Object.values(usage.providers).sort((a, b) => b.total - a.total);
+    const highlightLines = () => {
+        const lines = [];
+        const providerLabel = (providerID) => quotaDisplayLabel({
+            providerID,
+            label: providerID,
+            status: 'ok',
+            checkedAt: 0,
+        });
+        const topApiCost = providerEntries
+            .filter((provider) => provider.apiCost > 0)
+            .sort((a, b) => b.apiCost - a.apiCost)[0];
+        if (topApiCost) {
+            lines.push(`- Top API cost: ${quotaDisplayLabel({
+                providerID: topApiCost.providerID,
+                label: topApiCost.providerID,
+                status: 'ok',
+                checkedAt: 0,
+            })} (${formatUsd(topApiCost.apiCost)})`);
+        }
+        const bestCacheCoverage = providerEntries
+            .map((provider) => ({
+            provider,
+            value: getProviderCacheCoverageMetrics(provider).cacheCoverage,
+        }))
+            .filter((entry) => entry.value !== undefined)
+            .sort((a, b) => b.value - a.value)[0];
+        if (bestCacheCoverage) {
+            lines.push(`- Best Cache Coverage: ${providerLabel(bestCacheCoverage.provider.providerID)} (${formatPercent(bestCacheCoverage.value, 1)})`);
+        }
+        const bestCacheReadCoverage = providerEntries
+            .map((provider) => ({
+            provider,
+            value: getProviderCacheCoverageMetrics(provider).cacheReadCoverage,
+        }))
+            .filter((entry) => entry.value !== undefined)
+            .sort((a, b) => b.value - a.value)[0];
+        if (bestCacheReadCoverage) {
+            lines.push(`- Best Cache Read Coverage: ${providerLabel(bestCacheReadCoverage.provider.providerID)} (${formatPercent(bestCacheReadCoverage.value, 1)})`);
+        }
+        const highestMeasured = providerEntries
+            .filter((provider) => measuredCostCell(provider.providerID, provider.cost) !== '-')
+            .sort((a, b) => b.cost - a.cost)[0];
+        if (highestMeasured && highestMeasured.cost > 0) {
+            lines.push(`- Highest measured cost: ${providerLabel(highestMeasured.providerID)} (${formatUsd(highestMeasured.cost)})`);
+        }
+        return lines;
+    };
+    const providerRows = providerEntries
         .map((provider) => {
         const providerID = mdCell(provider.providerID);
         return showCost
-            ? `| ${providerID} | ${shortNumber(provider.input)} | ${shortNumber(provider.output)} | ${shortNumber(provider.cacheRead + provider.cacheWrite)} | ${shortNumber(provider.total)} | ${measuredCostCell(provider.providerID, provider.cost)} | ${apiCostCell(provider.providerID, provider.apiCost)} |`
+            ? `| ${providerID} | ${shortNumber(provider.input)} | ${shortNumber(provider.output)} | ${shortNumber(provider.cacheRead + provider.cacheWrite)} | ${shortNumber(provider.total)} | ${cacheCoverageCell(provider)} | ${cacheReadCoverageCell(provider)} | ${measuredCostCell(provider.providerID, provider.cost)} | ${apiCostCell(provider.providerID, provider.apiCost)} |`
             : `| ${providerID} | ${shortNumber(provider.input)} | ${shortNumber(provider.output)} | ${shortNumber(provider.cacheRead + provider.cacheWrite)} | ${shortNumber(provider.total)} |`;
     });
     const quotaLines = collapseQuotaSnapshots(quotas).flatMap((quota) => {
@@ -516,9 +586,7 @@ export function renderMarkdownReport(period, usage, quotas, options) {
                     const winLabel = win.label ? ` (${win.label})` : '';
                     return mdCell(`- ${displayLabel}${winLabel}: ${quota.status} | reset ${reportResetLine(win.resetAt, win.resetLabel, win.label)}`);
                 }
-                const remaining = win.remainingPercent === undefined
-                    ? '-'
-                    : `${win.remainingPercent.toFixed(1)}%`;
+                const remaining = formatQuotaPercent(win.remainingPercent);
                 const winLabel = win.label ? ` (${win.label})` : '';
                 return mdCell(`- ${displayLabel}${winLabel}: ${quota.status} | remaining ${remaining} | reset ${reportResetLine(win.resetAt, win.resetLabel, win.label)}`);
             });
@@ -537,9 +605,7 @@ export function renderMarkdownReport(period, usage, quotas, options) {
                 mdCell(`- ${displayLabel}: ${quota.status}${quota.note ? ` | ${quota.note}` : ''}`),
             ];
         }
-        const remaining = quota.remainingPercent === undefined
-            ? '-'
-            : `${quota.remainingPercent.toFixed(1)}%`;
+        const remaining = formatQuotaPercent(quota.remainingPercent);
         return [
             mdCell(`- ${displayLabel}: ${quota.status} | remaining ${remaining} | reset ${reportResetLine(quota.resetAt)}${quota.note ? ` | ${quota.note}` : ''}`),
         ];
@@ -564,17 +630,20 @@ export function renderMarkdownReport(period, usage, quotas, options) {
                 `- API cost: ${apiCostSummaryValue()}`,
             ]
             : []),
+        ...(highlightLines().length > 0
+            ? ['', '### Highlights', ...highlightLines()]
+            : []),
         '',
         '### Usage by Provider',
         showCost
-            ? '| Provider | Input | Output | Cache | Total | Measured Cost | API Cost |'
+            ? '| Provider | Input | Output | Cache | Total | Cache Coverage | Cache Read Coverage | Measured Cost | API Cost |'
             : '| Provider | Input | Output | Cache | Total |',
         showCost
-            ? '|---|---:|---:|---:|---:|---:|---:|'
+            ? '|---|---:|---:|---:|---:|---:|---:|---:|---:|'
             : '|---|---:|---:|---:|---:|',
         ...(providerRows.length
             ? providerRows
-            : [showCost ? '| - | - | - | - | - | - | - |' : '| - | - | - | - | - |']),
+            : [showCost ? '| - | - | - | - | - | - | - | - | - |' : '| - | - | - | - | - |']),
         '',
         '### Subscription Quota',
         ...(quotaLines.length
@@ -638,14 +707,35 @@ export function renderToastMessage(period, usage, quotas, options) {
             lines.push(fitLine(hasAnyUsage ? '  N/A (Copilot)' : '  -', width));
         }
     }
+    const providerCachePairs = Object.values(usage.providers)
+        .map((provider) => {
+        const metrics = getProviderCacheCoverageMetrics(provider);
+        const parts = [];
+        if (metrics.cacheCoverage !== undefined) {
+            parts.push(`Cov ${formatPercent(metrics.cacheCoverage, 1)}`);
+        }
+        if (metrics.cacheReadCoverage !== undefined) {
+            parts.push(`Read ${formatPercent(metrics.cacheReadCoverage, 1)}`);
+        }
+        if (parts.length === 0)
+            return undefined;
+        return {
+            label: displayShortLabel(provider.providerID),
+            value: parts.join('  '),
+        };
+    })
+        .filter((item) => Boolean(item));
+    if (providerCachePairs.length > 0) {
+        lines.push('');
+        lines.push(fitLine('Provider Cache', width));
+        lines.push(...alignPairs(providerCachePairs).map((line) => fitLine(line, width)));
+    }
     const quotaPairs = collapseQuotaSnapshots(quotas).flatMap((item) => {
         if (item.status === 'ok') {
             if (item.windows && item.windows.length > 0) {
                 const pairs = item.windows.map((win, idx) => {
                     const showPercent = win.showPercent !== false;
-                    const pct = win.remainingPercent === undefined
-                        ? '-'
-                        : `${win.remainingPercent.toFixed(1)}%`;
+                    const pct = formatQuotaPercent(win.remainingPercent);
                     const reset = compactReset(win.resetAt, win.resetLabel, win.label);
                     const parts = [win.label];
                     if (showPercent)
@@ -673,9 +763,7 @@ export function renderToastMessage(period, usage, quotas, options) {
                     },
                 ];
             }
-            const percent = item.remainingPercent === undefined
-                ? '-'
-                : `${item.remainingPercent.toFixed(1)}%`;
+            const percent = formatQuotaPercent(item.remainingPercent);
             const reset = compactReset(item.resetAt, 'Rst');
             return [
                 {

package/dist/index.js

@@ -12,6 +12,8 @@ import { createPersistenceScheduler } from './persistence.js';
 import { createQuotaService } from './quota_service.js';
 import { createUsageService } from './usage_service.js';
 import { createTitleApplicator } from './title_apply.js';
+const SHUTDOWN_HOOK_KEY = Symbol.for('opencode-quota-sidebar.shutdown-hook');
+const SHUTDOWN_CALLBACKS_KEY = Symbol.for('opencode-quota-sidebar.shutdown-callbacks');
 export async function QuotaSidebarPlugin(input) {
     const quotaRuntime = createQuotaRuntime();
     const configDir = resolveOpencodeConfigDir();
@@ -164,18 +166,61 @@ export async function QuotaSidebarPlugin(input) {
         restoreConcurrency: RESTORE_TITLE_CONCURRENCY,
     });
     const titleRefresh = createTitleRefreshScheduler({
-        apply: titleApplicator.applyTitle,
+        apply: async (sessionID) => {
+            await titleApplicator.applyTitle(sessionID);
+        },
         onError: swallow('titleRefresh'),
     });
     scheduleTitleRefresh = titleRefresh.schedule;
     const restoreAllVisibleTitles = titleApplicator.restoreAllVisibleTitles;
     const refreshAllTouchedTitles = titleApplicator.refreshAllTouchedTitles;
     const refreshAllVisibleTitles = titleApplicator.refreshAllVisibleTitles;
+    let startupTitleWork = Promise.resolve();
+    const runStartupRestore = async (attempt = 0) => {
+        const result = await restoreAllVisibleTitles({
+            abortIfEnabled: config.sidebar.enabled,
+        });
+        if (result.restored === result.attempted)
+            return;
+        debug(`startup restore incomplete: restored ${result.restored}/${result.attempted} touched titles while display mode remains OFF`);
+        if (state.titleEnabled || config.sidebar.enabled === false)
+            return;
+        if (attempt >= 2)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 1_000));
+        await runStartupRestore(attempt + 1);
+    };
     if (!state.titleEnabled || !config.sidebar.enabled) {
-        void restoreAllVisibleTitles().catch(swallow('startup:restoreAllVisibleTitles'));
+        startupTitleWork = runStartupRestore().catch(swallow('startup:restoreAllVisibleTitles'));
     }
     else {
-        void refreshAllTouchedTitles().catch(swallow('startup:refreshAllTouchedTitles'));
+        startupTitleWork = refreshAllTouchedTitles()
+            .then(() => undefined)
+            .catch(swallow('startup:refreshAllTouchedTitles'));
+    }
+    const shutdown = async () => {
+        await Promise.race([
+            startupTitleWork,
+            new Promise((resolve) => setTimeout(resolve, 5_000)),
+        ]).catch(swallow('shutdown:startupTitleWork'));
+        await titleRefresh.waitForQuiescence().catch(swallow('shutdown:titleQuiescence'));
+        await flushSave().catch(swallow('shutdown:flushSave'));
+    };
+    const processWithHook = process;
+    const shutdownCallbacks = (processWithHook[SHUTDOWN_CALLBACKS_KEY] ||= new Set());
+    shutdownCallbacks.add(shutdown);
+    if (!processWithHook[SHUTDOWN_HOOK_KEY]) {
+        processWithHook[SHUTDOWN_HOOK_KEY] = true;
+        process.once('beforeExit', () => {
+            void Promise.allSettled(Array.from(shutdownCallbacks).map((callback) => callback()));
+        });
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            process.once(signal, () => {
+                void Promise.allSettled(Array.from(shutdownCallbacks).map((callback) => callback())).finally(() => {
+                    process.kill(process.pid, signal);
+                });
+            });
+        }
     }
     const showToast = async (period, message) => {
         await input.client.tui
@@ -268,9 +313,12 @@ export async function QuotaSidebarPlugin(input) {
             },
             scheduleSave,
             flushSave,
+            waitForStartupTitleWork: () => startupTitleWork,
             refreshSessionTitle: (sessionID, delay) => titleRefresh.schedule(sessionID, delay ?? 250),
             cancelAllTitleRefreshes: () => titleRefresh.cancelAll(),
+            flushScheduledTitleRefreshes: () => titleRefresh.flushScheduled(),
             waitForTitleRefreshIdle: () => titleRefresh.waitForIdle(),
+            waitForTitleRefreshQuiescence: () => titleRefresh.waitForQuiescence(),
             restoreAllVisibleTitles,
             refreshAllTouchedTitles,
             refreshAllVisibleTitles,
@@ -279,7 +327,10 @@ export async function QuotaSidebarPlugin(input) {
             getQuotaSnapshots,
             renderMarkdownReport,
             renderToastMessage,
-            config,
+            config: {
+                sidebar: config.sidebar,
+                sidebarEnabled: config.sidebar.enabled,
+            },
         }),
     };
 }

package/dist/persistence.js

@@ -4,6 +4,17 @@ export function createPersistenceScheduler(deps) {
     let stateDirty = false;
     let saveTimer;
     let saveInFlight = Promise.resolve();
+    const scheduleRetry = (delayMs = 1_000) => {
+        if (saveTimer)
+            return;
+        saveTimer = setTimeout(() => {
+            saveTimer = undefined;
+            void persist().catch((error) => {
+                debug(`persistState retry failed: ${String(error)}`);
+                scheduleRetry(Math.min(delayMs * 2, 10_000));
+            });
+        }, delayMs);
+    };
     /**
      * Capture and delete specific dirty keys instead of clearing the whole set.
      * Keys added between capture and write completion are preserved.
@@ -34,7 +45,10 @@ export function createPersistenceScheduler(deps) {
             clearTimeout(saveTimer);
         saveTimer = setTimeout(() => {
             saveTimer = undefined;
-            void persist().catch(swallow('persistState:save'));
+            void persist().catch((error) => {
+                swallow('persistState:save')(error);
+                scheduleRetry();
+            });
         }, 200);
     };
     const flushSave = async () => {

package/dist/quota_service.js

@@ -11,6 +11,7 @@ export function createQuotaService(deps) {
     const authCache = new TtlValueCache();
     const providerOptionsCache = new TtlValueCache();
     const inFlight = new Map();
+    let lastSuccessfulProviderOptionsMap = {};
     const authFingerprint = (auth) => {
         if (!auth || typeof auth !== 'object')
             return undefined;
@@ -46,7 +47,7 @@ export function createQuotaService(deps) {
         if (cached)
             return cached;
         const value = await loadAuthMap(deps.authPath);
-        return authCache.set(value, 30_000);
+        return authCache.set(value, 5_000);
     };
     const getProviderOptionsMap = async () => {
         const cached = providerOptionsCache.get();
@@ -58,23 +59,127 @@ export function createQuotaService(deps) {
         }
         // Newer runtimes expose config.providers; older clients may only expose
         // provider.list with a slightly different response shape.
-        const response = await (client.config?.providers
-            ? client.config.providers({
+        let response;
+        let fromConfigProviders = false;
+        if (client.config?.providers) {
+            fromConfigProviders = true;
+            response = await client.config
+                .providers({
                 query: { directory: deps.directory },
                 throwOnError: true,
             })
-            : client.provider.list({
+                .catch(swallow('getProviderOptionsMap:configProviders'));
+        }
+        if (!response && client.provider?.list) {
+            response = await client.provider
+                .list({
                 query: { directory: deps.directory },
                 throwOnError: true,
-            })).catch(swallow('getProviderOptionsMap'));
-        const data = isRecord(response) && isRecord(response.data) ? response.data : undefined;
-        const list = Array.isArray(data?.providers)
-            ? data.providers
-            : Array.isArray(data?.all)
-                ? data.all
+            })
+                .catch(swallow('getProviderOptionsMap:providerList'));
+        }
+        const data = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+            ? response.data
+            : undefined;
+        if (!response || data === undefined) {
+            if (client.provider?.list && fromConfigProviders) {
+                response = await client.provider
+                    .list({
+                    query: { directory: deps.directory },
+                    throwOnError: true,
+                })
+                    .catch(swallow('getProviderOptionsMap:providerListNoDataFallback'));
+                const fallbackData = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+                    ? response.data
+                    : undefined;
+                const fallbackRecord = isRecord(fallbackData) ? fallbackData : undefined;
+                const fallbackList = Array.isArray(fallbackRecord?.providers)
+                    ? fallbackRecord.providers
+                    : Array.isArray(fallbackRecord?.all)
+                        ? fallbackRecord.all
+                        : Array.isArray(fallbackData)
+                            ? fallbackData
+                            : undefined;
+                const map = Array.isArray(fallbackList)
+                    ? fallbackList.reduce((acc, item) => {
+                        if (!item || typeof item !== 'object')
+                            return acc;
+                        const record = item;
+                        const id = record.id;
+                        const options = record.options;
+                        if (typeof id !== 'string')
+                            return acc;
+                        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+                            acc[id] = {};
+                            return acc;
+                        }
+                        acc[id] = options;
+                        return acc;
+                    }, {})
+                    : {};
+                if (Object.keys(map).length > 0) {
+                    lastSuccessfulProviderOptionsMap = map;
+                    return providerOptionsCache.set(map, 5_000);
+                }
+            }
+            return Object.keys(lastSuccessfulProviderOptionsMap).length > 0
+                ? lastSuccessfulProviderOptionsMap
+                : {};
+        }
+        const dataRecord = isRecord(data) ? data : undefined;
+        const list = Array.isArray(dataRecord?.providers)
+            ? dataRecord.providers
+            : Array.isArray(dataRecord?.all)
+                ? dataRecord.all
                 : Array.isArray(data)
                     ? data
                     : undefined;
+        if (!list && fromConfigProviders && client.provider?.list) {
+            response = await client.provider
+                .list({
+                query: { directory: deps.directory },
+                throwOnError: true,
+            })
+                .catch(swallow('getProviderOptionsMap:providerListFallback'));
+            const fallbackData = isRecord(response) && Object.prototype.hasOwnProperty.call(response, 'data')
+                ? response.data
+                : undefined;
+            const fallbackRecord = isRecord(fallbackData) ? fallbackData : undefined;
+            const fallbackList = Array.isArray(fallbackRecord?.providers)
+                ? fallbackRecord.providers
+                : Array.isArray(fallbackRecord?.all)
+                    ? fallbackRecord.all
+                    : Array.isArray(fallbackData)
+                        ? fallbackData
+                        : undefined;
+            const map = Array.isArray(fallbackList)
+                ? fallbackList.reduce((acc, item) => {
+                    if (!item || typeof item !== 'object')
+                        return acc;
+                    const record = item;
+                    const id = record.id;
+                    const options = record.options;
+                    if (typeof id !== 'string')
+                        return acc;
+                    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+                        acc[id] = {};
+                        return acc;
+                    }
+                    acc[id] = options;
+                    return acc;
+                }, {})
+                : {};
+            if (Object.keys(map).length > 0) {
+                lastSuccessfulProviderOptionsMap = map;
+                return providerOptionsCache.set(map, 5_000);
+            }
+            if (!Array.isArray(fallbackList)) {
+                return Object.keys(lastSuccessfulProviderOptionsMap).length > 0
+                    ? lastSuccessfulProviderOptionsMap
+                    : {};
+            }
+            return providerOptionsCache.set(map, 5_000);
+        }
         const map = Array.isArray(list)
             ? list.reduce((acc, item) => {
                 if (!item || typeof item !== 'object')
@@ -94,6 +199,15 @@ export function createQuotaService(deps) {
                 return acc;
             }, {})
             : {};
+        if (Object.keys(map).length > 0) {
+            lastSuccessfulProviderOptionsMap = map;
+            return providerOptionsCache.set(map, 5_000);
+        }
+        if (!Array.isArray(list)) {
+            return Object.keys(lastSuccessfulProviderOptionsMap).length > 0
+                ? lastSuccessfulProviderOptionsMap
+                : providerOptionsCache.set(map, 5_000);
+        }
         return providerOptionsCache.set(map, 5_000);
     };
     const isValidQuotaCache = (snapshot) => {
@@ -276,7 +390,11 @@ export function createQuotaService(deps) {
                     body: next,
                     throwOnError: true,
                 })
-                    .catch(swallow('getQuotaSnapshots:authSet'));
+                    .catch((error) => {
+                    swallow('getQuotaSnapshots:authSet')(error);
+                    throw error;
+                });
+                authCache.clear();
             }, providerOptions)
                 .then((latest) => {
                 if (!latest)

package/dist/storage_parse.js

@@ -27,6 +27,7 @@ function parseProviderUsage(value) {
         cost: asNumber(value.cost, 0),
         apiCost: asNumber(value.apiCost, 0),
         assistantMessages: asNumber(value.assistantMessages, 0),
+        cacheBuckets: parseCacheUsageBuckets(value.cacheBuckets),
     };
 }
 function parseCacheUsageBucket(value) {

package/dist/title_apply.d.ts

@@ -17,16 +17,32 @@ export declare function createTitleApplicator(deps: {
     scheduleParentRefreshIfSafe: (sessionID: string, parentID?: string) => void;
     restoreConcurrency: number;
 }): {
-    applyTitle: (sessionID: string) => Promise<void>;
+    applyTitle: (sessionID: string) => Promise<boolean>;
     handleSessionUpdatedTitle: (args: {
         sessionID: string;
         incomingTitle: string;
         sessionState: SessionState;
         scheduleRefresh: (sessionID: string, delay?: number) => void;
     }) => Promise<void>;
-    restoreSessionTitle: (sessionID: string) => Promise<void>;
-    restoreAllVisibleTitles: () => Promise<void>;
-    refreshAllTouchedTitles: () => Promise<void>;
-    refreshAllVisibleTitles: () => Promise<void>;
+    restoreSessionTitle: (sessionID: string, options?: {
+        abortIfEnabled?: boolean;
+    }) => Promise<boolean>;
+    restoreAllVisibleTitles: (options?: {
+        abortIfEnabled?: boolean;
+    }) => Promise<{
+        attempted: number;
+        restored: number;
+        listFailed: boolean;
+    }>;
+    refreshAllTouchedTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
+    refreshAllVisibleTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
     forgetSession: (sessionID: string) => void;
 };

package/dist/title_apply.js

@@ -2,12 +2,14 @@ import { canonicalizeTitle, canonicalizeTitleForCompare, looksDecorated, } from
 import { swallow, debug, mapConcurrent } from './helpers.js';
 export function createTitleApplicator(deps) {
     const pendingAppliedTitle = new Map();
+    const recentRestore = new Map();
     const forgetSession = (sessionID) => {
         pendingAppliedTitle.delete(sessionID);
+        recentRestore.delete(sessionID);
     };
     const applyTitle = async (sessionID) => {
         if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
-            return;
+            return false;
         let stateMutated = false;
         const session = await deps.client.session
             .get({
@@ -17,7 +19,14 @@ export function createTitleApplicator(deps) {
         })
             .catch(swallow('applyTitle:getSession'));
         if (!session)
-            return;
+            return false;
+        if (!session.data ||
+            typeof session.data.title !== 'string' ||
+            !session.data.time ||
+            typeof session.data.time.created !== 'number') {
+            debug(`applyTitle skipped malformed session payload for ${sessionID}`);
+            return false;
+        }
         const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
         // Detect whether the current title is our own decorated form.
         const currentTitle = session.data.title;
@@ -62,7 +71,7 @@ export function createTitleApplicator(deps) {
             : [];
         const nextTitle = deps.renderSidebarTitle(sessionState.baseTitle, usage, quotas, deps.config);
         if (!deps.config.sidebar.enabled || !deps.state.titleEnabled)
-            return;
+            return false;
         if (canonicalizeTitleForCompare(nextTitle) ===
             canonicalizeTitleForCompare(session.data.title)) {
             if (looksDecorated(session.data.title)) {
@@ -76,7 +85,7 @@ export function createTitleApplicator(deps) {
             }
             deps.scheduleSave();
             deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
-            return;
+            return true;
         }
         // Mark pending title to ignore the immediate echo `session.updated` event.
         // H3 fix: use longer TTL (15s) and add decoration detection as backup.
@@ -100,11 +109,12 @@ export function createTitleApplicator(deps) {
             sessionState.lastAppliedTitle = previousApplied;
             deps.scheduleSave();
             deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
-            return;
+            return false;
         }
         pendingAppliedTitle.delete(sessionID);
         deps.scheduleSave();
         deps.scheduleParentRefreshIfSafe(sessionID, sessionState.parentID);
+        return true;
     };
     const handleSessionUpdatedTitle = async (args) => {
         const pending = pendingAppliedTitle.get(args.sessionID);
@@ -138,13 +148,32 @@ export function createTitleApplicator(deps) {
                 return;
             }
         }
+        if (looksDecorated(args.incomingTitle) && !args.sessionState.lastAppliedTitle) {
+            debug(`ignoring untracked decorated title for session ${args.sessionID}`);
+            return;
+        }
+        const restored = recentRestore.get(args.sessionID);
+        if (restored) {
+            if (restored.expiresAt <= Date.now()) {
+                recentRestore.delete(args.sessionID);
+            }
+            else if (looksDecorated(args.incomingTitle) &&
+                (!restored.decoratedTitle ||
+                    canonicalizeTitleForCompare(args.incomingTitle) ===
+                        canonicalizeTitleForCompare(restored.decoratedTitle))) {
+                debug(`ignoring decorated echo after restore for session ${args.sessionID}`);
+                return;
+            }
+        }
         args.sessionState.baseTitle = canonicalizeTitle(args.incomingTitle) || 'Session';
         args.sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[args.sessionID]);
         deps.scheduleSave();
         args.scheduleRefresh(args.sessionID);
     };
-    const restoreSessionTitle = async (sessionID) => {
+    const restoreSessionTitle = async (sessionID, options) => {
+        if (options?.abortIfEnabled && deps.state.titleEnabled)
+            return false;
         const session = await deps.client.session
             .get({
             path: { id: sessionID },
@@ -153,7 +182,14 @@ export function createTitleApplicator(deps) {
         })
             .catch(swallow('restoreSessionTitle:get'));
         if (!session)
-            return;
+            return false;
+        if (!session.data ||
+            typeof session.data.title !== 'string' ||
+            !session.data.time ||
+            typeof session.data.time.created !== 'number') {
+            debug(`restoreSessionTitle skipped malformed session payload for ${sessionID}`);
+            return false;
+        }
         const sessionState = deps.ensureSessionState(sessionID, session.data.title, session.data.time.created, session.data.parentID ?? null);
         const baseTitle = canonicalizeTitle(sessionState.baseTitle) || 'Session';
         if (session.data.title === baseTitle) {
@@ -162,8 +198,10 @@ export function createTitleApplicator(deps) {
                 deps.markDirty(deps.state.sessionDateMap[sessionID]);
                 deps.scheduleSave();
             }
-            return;
+            return true;
         }
+        if (options?.abortIfEnabled && deps.state.titleEnabled)
+            return false;
         const updated = await deps.client.session
             .update({
             path: { id: sessionID },
@@ -173,26 +211,39 @@ export function createTitleApplicator(deps) {
         })
             .catch(swallow('restoreSessionTitle:update'));
         if (!updated)
-            return;
+            return false;
+        pendingAppliedTitle.delete(sessionID);
+        recentRestore.set(sessionID, {
+            baseTitle,
+            decoratedTitle: sessionState.lastAppliedTitle,
+            expiresAt: Date.now() + 15_000,
+        });
         sessionState.lastAppliedTitle = undefined;
         deps.markDirty(deps.state.sessionDateMap[sessionID]);
         deps.scheduleSave();
+        return true;
     };
-    const restoreAllVisibleTitles = async () => {
+    const restoreAllVisibleTitles = async (options) => {
         const touched = Object.entries(deps.state.sessions)
             .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
             .map(([sessionID]) => sessionID);
-        await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => {
-            await restoreSessionTitle(sessionID);
-        });
+        const results = await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => restoreSessionTitle(sessionID, options));
+        return {
+            attempted: touched.length,
+            restored: results.filter(Boolean).length,
+            listFailed: false,
+        };
     };
     const refreshAllTouchedTitles = async () => {
         const touched = Object.entries(deps.state.sessions)
             .filter(([, sessionState]) => Boolean(sessionState.lastAppliedTitle))
             .map(([sessionID]) => sessionID);
-        await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => {
-            await applyTitle(sessionID);
-        });
+        const results = await mapConcurrent(touched, deps.restoreConcurrency, async (sessionID) => applyTitle(sessionID));
+        return {
+            attempted: touched.length,
+            refreshed: results.filter(Boolean).length,
+            listFailed: false,
+        };
     };
     const refreshAllVisibleTitles = async () => {
         const list = await deps.client.session
@@ -201,11 +252,16 @@ export function createTitleApplicator(deps) {
             throwOnError: true,
         })
             .catch(swallow('refreshAllVisibleTitles:list'));
-        if (!list?.data)
-            return;
-        await mapConcurrent(list.data, deps.restoreConcurrency, async (session) => {
-            await applyTitle(session.id);
-        });
+        if (!list?.data || !Array.isArray(list.data)) {
+            return { attempted: 0, refreshed: 0, listFailed: true };
+        }
+        const sessions = list.data.filter((session) => Boolean(session && typeof session.id === 'string'));
+        const results = await mapConcurrent(sessions, deps.restoreConcurrency, async (session) => applyTitle(session.id));
+        return {
+            attempted: sessions.length,
+            refreshed: results.filter(Boolean).length,
+            listFailed: false,
+        };
     };
     return {
         applyTitle,

package/dist/title_refresh.d.ts

@@ -6,6 +6,8 @@ export declare function createTitleRefreshScheduler(options: {
     apply: (sessionID: string) => Promise<void>;
     cancel: (sessionID: string) => void;
     cancelAll: () => void;
-    waitForIdle: () => Promise<void>;
+    flushScheduled: () => Promise<void>;
+    waitForIdle: (timeoutMs?: number) => Promise<void>;
+    waitForQuiescence: (budgetMs?: number) => Promise<void>;
     dispose: () => void;
 };

package/dist/title_refresh.js

@@ -36,11 +36,32 @@ export function createTitleRefreshScheduler(options) {
             clearTimeout(timer);
         refreshTimer.clear();
     };
-    const waitForIdle = async () => {
+    const flushScheduled = async () => {
+        const pending = Array.from(refreshTimer.keys());
+        cancelAll();
+        await Promise.allSettled(pending.map((sessionID) => applyLocked(sessionID)));
+    };
+    const waitForIdle = async (timeoutMs) => {
         const inflight = Array.from(applyLocks.values());
         if (inflight.length === 0)
             return;
-        await Promise.allSettled(inflight);
+        if (timeoutMs === undefined) {
+            await Promise.allSettled(inflight);
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled(inflight),
+            new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+        ]);
+    };
+    const waitForQuiescence = async (budgetMs = 10_000) => {
+        const deadline = Date.now() + budgetMs;
+        while (Date.now() < deadline) {
+            await flushScheduled();
+            await waitForIdle(Math.max(0, deadline - Date.now()));
+            if (refreshTimer.size === 0 && applyLocks.size === 0)
+                return;
+        }
     };
     const dispose = () => {
         cancelAll();
@@ -51,7 +72,9 @@ export function createTitleRefreshScheduler(options) {
         apply: applyLocked,
         cancel,
         cancelAll,
+        flushScheduled,
         waitForIdle,
+        waitForQuiescence,
         dispose,
     };
 }

package/dist/tools.d.ts

@@ -5,12 +5,27 @@ export declare function createQuotaSidebarTools(deps: {
     setTitleEnabled: (enabled: boolean) => void;
     scheduleSave: () => void;
     flushSave: () => Promise<void>;
+    waitForStartupTitleWork: () => Promise<void>;
     refreshSessionTitle: (sessionID: string, delay?: number) => void;
     cancelAllTitleRefreshes: () => void;
+    flushScheduledTitleRefreshes: () => Promise<void>;
     waitForTitleRefreshIdle: () => Promise<void>;
-    restoreAllVisibleTitles: () => Promise<void>;
-    refreshAllTouchedTitles: () => Promise<void>;
-    refreshAllVisibleTitles: () => Promise<void>;
+    waitForTitleRefreshQuiescence: () => Promise<void>;
+    restoreAllVisibleTitles: () => Promise<{
+        attempted: number;
+        restored: number;
+        listFailed: boolean;
+    }>;
+    refreshAllTouchedTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
+    refreshAllVisibleTitles: () => Promise<{
+        attempted: number;
+        refreshed: number;
+        listFailed: boolean;
+    }>;
     showToast: (period: 'session' | 'day' | 'week' | 'month' | 'toggle', message: string) => Promise<void>;
     summarizeForTool: (period: 'session' | 'day' | 'week' | 'month', sessionID: string, includeChildren: boolean) => Promise<UsageSummary>;
     getQuotaSnapshots: (providerIDs: string[], options?: {
@@ -29,6 +44,7 @@ export declare function createQuotaSidebarTools(deps: {
             width: number;
             includeChildren: boolean;
         };
+        sidebarEnabled: boolean;
     };
 }): {
     quota_summary: {

package/dist/tools.js

@@ -1,6 +1,14 @@
 import { tool } from '@opencode-ai/plugin/tool';
 const z = tool.schema;
 export function createQuotaSidebarTools(deps) {
+    let toggleLock = Promise.resolve();
+    const waitForStartupTitleWork = async () => {
+        const timedOut = await Promise.race([
+            deps.waitForStartupTitleWork(),
+            new Promise((resolve) => setTimeout(() => resolve('timeout'), 3_000)),
+        ]);
+        return timedOut === 'timeout';
+    };
     return {
         quota_summary: tool({
             description: 'Show usage and quota summary for session/day/week/month.',
@@ -42,25 +50,59 @@ export function createQuotaSidebarTools(deps) {
                     .describe('Explicit on/off. Omit to toggle current state.'),
             },
             execute: async (args, context) => {
-                const current = deps.getTitleEnabled();
-                const next = args.enabled !== undefined ? args.enabled : !current;
-                deps.setTitleEnabled(next);
-                deps.scheduleSave();
-                await deps.flushSave();
-                if (next) {
-                    // Turning on — refresh visible sessions, plus touched sessions as backup.
+                const run = async () => {
+                    const current = deps.getTitleEnabled();
+                    const next = args.enabled !== undefined ? args.enabled : !current;
+                    if (next) {
+                        if (!deps.config.sidebarEnabled) {
+                            return 'Sidebar usage display cannot be enabled because `sidebar.enabled=false` in config. Re-enable the sidebar feature first.';
+                        }
+                        const startupTimedOut = await waitForStartupTitleWork();
+                        deps.setTitleEnabled(true);
+                        deps.scheduleSave();
+                        await deps.flushSave();
+                        const visible = await deps.refreshAllVisibleTitles();
+                        const touched = await deps.refreshAllTouchedTitles();
+                        deps.refreshSessionTitle(context.sessionID, 0);
+                        if (startupTimedOut) {
+                            void deps.waitForStartupTitleWork().then(() => {
+                                if (!deps.getTitleEnabled())
+                                    return;
+                                void deps.refreshAllVisibleTitles();
+                                void deps.refreshAllTouchedTitles();
+                                deps.refreshSessionTitle(context.sessionID, 0);
+                            });
+                        }
+                        await deps.showToast('toggle', 'Sidebar usage display: ON');
+                        if (visible.listFailed ||
+                            visible.refreshed < visible.attempted ||
+                            touched.refreshed < touched.attempted) {
+                            return 'Sidebar usage display is now ON. Visible-session refresh failed, so only touched/current session titles are guaranteed to refresh immediately.';
+                        }
+                        return 'Sidebar usage display is now ON. Visible session titles are refreshing to show token usage and quota.';
+                    }
+                    deps.setTitleEnabled(false);
+                    deps.scheduleSave();
+                    await deps.flushSave();
+                    deps.cancelAllTitleRefreshes();
+                    await deps.waitForTitleRefreshQuiescence();
+                    const restore = await deps.restoreAllVisibleTitles();
+                    if (restore.restored === restore.attempted) {
+                        await deps.showToast('toggle', 'Sidebar usage display: OFF');
+                        return 'Sidebar usage display is now OFF. Touched session titles were restored to base titles.';
+                    }
+                    deps.setTitleEnabled(true);
+                    deps.scheduleSave();
+                    await deps.flushSave();
                     await deps.refreshAllVisibleTitles();
                     await deps.refreshAllTouchedTitles();
                     deps.refreshSessionTitle(context.sessionID, 0);
-                    await deps.showToast('toggle', 'Sidebar usage display: ON');
-                    return 'Sidebar usage display is now ON. Visible session titles are refreshing to show token usage and quota.';
-                }
-                // Turning off — restore all touched sessions to base titles
-                deps.cancelAllTitleRefreshes();
-                await deps.waitForTitleRefreshIdle();
-                await deps.restoreAllVisibleTitles();
-                await deps.showToast('toggle', 'Sidebar usage display: OFF');
-                return 'Sidebar usage display is now OFF. Restore was attempted for touched session titles.';
+                    await deps.showToast('toggle', 'Sidebar usage display: OFF failed');
+                    return 'Sidebar usage display remains ON because some touched session titles could not be restored. Try again after the session service recovers.';
+                };
+                const pending = toggleLock.then(run, run);
+                toggleLock = pending.then(() => undefined, () => undefined);
+                return pending;
             },
         }),
     };

package/dist/types.d.ts

@@ -72,6 +72,8 @@ export type CachedProviderUsage = {
     /** Equivalent API billing cost (USD) computed from model pricing. */
     apiCost: number;
     assistantMessages: number;
+    /** Provider-level cache coverage buckets grouped by model cache behavior. */
+    cacheBuckets?: CacheUsageBuckets;
 };
 export type CachedSessionUsage = {
     /** Billing aggregation cache version for cost/apiCost refresh migrations. */

package/dist/usage.d.ts

@@ -19,6 +19,7 @@ export type ProviderUsage = {
     cost: number;
     apiCost: number;
     assistantMessages: number;
+    cacheBuckets?: CacheUsageBuckets;
 };
 export type UsageSummary = {
     input: number;
@@ -42,6 +43,7 @@ export type UsageOptions = {
     classifyCacheMode?: (message: AssistantMessage) => CacheCoverageMode;
 };
 export declare function getCacheCoverageMetrics(usage: Pick<UsageSummary, 'input' | 'cacheRead' | 'cacheWrite' | 'assistantMessages' | 'cacheBuckets'>): CacheCoverageMetrics;
+export declare function getProviderCacheCoverageMetrics(usage: Pick<ProviderUsage, 'input' | 'cacheRead' | 'cacheWrite' | 'assistantMessages' | 'cacheBuckets'>): CacheCoverageMetrics;
 export declare function emptyUsageSummary(): UsageSummary;
 export declare function summarizeMessages(entries: Array<{
     info: Message;

package/dist/usage.js

@@ -120,6 +120,9 @@ export function getCacheCoverageMetrics(usage) {
             : undefined,
     };
 }
+export function getProviderCacheCoverageMetrics(usage) {
+    return getCacheCoverageMetrics(usage);
+}
 export function emptyUsageSummary() {
     return {
         input: 0,
@@ -147,6 +150,7 @@ function emptyProviderUsage(providerID) {
         cost: 0,
         apiCost: 0,
         assistantMessages: 0,
+        cacheBuckets: undefined,
     };
 }
 function isAssistant(message) {
@@ -194,10 +198,14 @@ function addMessageUsage(target, message, options) {
     if (cacheMode === 'read-only') {
         const buckets = (target.cacheBuckets ||= emptyCacheUsageBuckets());
         addMessageCacheUsage(buckets.readOnly, message);
+        const providerBuckets = (provider.cacheBuckets ||= emptyCacheUsageBuckets());
+        addMessageCacheUsage(providerBuckets.readOnly, message);
     }
     else if (cacheMode === 'read-write') {
         const buckets = (target.cacheBuckets ||= emptyCacheUsageBuckets());
         addMessageCacheUsage(buckets.readWrite, message);
+        const providerBuckets = (provider.cacheBuckets ||= emptyCacheUsageBuckets());
+        addMessageCacheUsage(providerBuckets.readWrite, message);
     }
 }
 function completedTimeOf(message) {
@@ -445,6 +453,11 @@ export function mergeUsage(target, source, options) {
         }
         existing.apiCost += provider.apiCost;
         existing.assistantMessages += provider.assistantMessages;
+        if (provider.cacheBuckets) {
+            const providerBuckets = (existing.cacheBuckets ||= emptyCacheUsageBuckets());
+            mergeCacheUsageBucket(providerBuckets.readOnly, provider.cacheBuckets.readOnly);
+            mergeCacheUsageBucket(providerBuckets.readWrite, provider.cacheBuckets.readWrite);
+        }
         target.providers[provider.providerID] = existing;
     }
     return target;
@@ -462,6 +475,7 @@ export function toCachedSessionUsage(summary) {
             cost: provider.cost,
             apiCost: provider.apiCost,
             assistantMessages: provider.assistantMessages,
+            cacheBuckets: cloneCacheUsageBuckets(provider.cacheBuckets),
         };
         return acc;
     }, {});
@@ -509,6 +523,7 @@ export function fromCachedSessionUsage(cached, sessionCount = 1) {
                 cost: provider.cost,
                 apiCost: provider.apiCost || 0,
                 assistantMessages: provider.assistantMessages,
+                cacheBuckets: cloneCacheUsageBuckets(provider.cacheBuckets),
             };
             return acc;
         }, {}),

package/dist/usage_service.js

@@ -210,6 +210,7 @@ export function createUsageService(deps) {
             .filter((item) => Boolean(item));
         if (decoded.length > 0 && decoded.length < value.length) {
             debug(`message entries partially decoded: kept ${decoded.length}/${value.length}`);
+            return undefined;
         }
         // If the API returned entries but none match the expected shape,
         // treat it as a load failure so we don't silently undercount.
@@ -260,7 +261,7 @@ export function createUsageService(deps) {
                 key.startsWith(`${canonicalProviderID}:`));
         });
     };
-    const summarizeSessionUsage = async (sessionID, generationAtStart) => {
+    const summarizeSessionUsage = async (sessionID, generationAtStart, options) => {
         const entries = await loadSessionEntries(sessionID);
         const sessionState = deps.state.sessions[sessionID];
         // If we can't load messages (transient API failure), fall back to cached
@@ -272,6 +273,9 @@ export function createUsageService(deps) {
                     persist: false,
                 };
             }
+            if (options?.requireEntries) {
+                throw new Error(`session usage unavailable: failed to load messages for ${sessionID}`);
+            }
             const empty = emptyUsageSummary();
             empty.sessionCount = 1;
             return { usage: empty, persist: false };
@@ -301,7 +305,7 @@ export function createUsageService(deps) {
         }
         return { usage, persist: true };
     };
-    const summarizeSessionUsageLocked = async (sessionID) => {
+    const summarizeSessionUsageLocked = async (sessionID, options) => {
         for (let attempt = 0; attempt < 2; attempt++) {
             const generationAtStart = dirtyGeneration.get(sessionID) || 0;
             const existing = usageInFlight.get(sessionID);
@@ -311,13 +315,15 @@ export function createUsageService(deps) {
                     continue;
                 return result;
             }
-            const promise = summarizeSessionUsage(sessionID, generationAtStart);
+            const promise = summarizeSessionUsage(sessionID, generationAtStart, options);
             const entry = { generation: generationAtStart, promise };
-            promise.finally(() => {
+            void promise
+                .finally(() => {
                 const current = usageInFlight.get(sessionID);
                 if (current?.promise === promise)
                     usageInFlight.delete(sessionID);
-            });
+            })
+                .catch(() => undefined);
             usageInFlight.set(sessionID, entry);
             const result = await promise;
             if ((dirtyGeneration.get(sessionID) || 0) !== generationAtStart)
@@ -345,8 +351,11 @@ export function createUsageService(deps) {
             maxSessions: deps.config.sidebar.childrenMaxSessions,
             concurrency: deps.config.sidebar.childrenConcurrency,
         });
-        if (descendantIDs.length === 0)
+        if (descendantIDs.length === 0) {
+            if (dirty)
+                deps.persistence.scheduleSave();
             return usage;
+        }
         const merged = emptyUsageSummary();
         mergeUsage(merged, usage);
         const needsFetch = [];
@@ -424,6 +433,7 @@ export function createUsageService(deps) {
                         dateKey: session.dateKey,
                         createdAt: session.state.createdAt,
                         lastMessageTime: session.state.cursor?.lastMessageTime,
+                        dirty: session.state.dirty === true,
                         computed: emptyUsageSummary(),
                         fullUsage: undefined,
                         loadFailed: true,
@@ -442,6 +452,7 @@ export function createUsageService(deps) {
                         dateKey: session.dateKey,
                         createdAt: session.state.createdAt,
                         lastMessageTime: session.state.cursor?.lastMessageTime,
+                        dirty: session.state.dirty === true,
                         computed,
                         fullUsage: undefined,
                         loadFailed: false,
@@ -458,6 +469,7 @@ export function createUsageService(deps) {
                     dateKey: session.dateKey,
                     createdAt: session.state.createdAt,
                     lastMessageTime: cursor.lastMessageTime,
+                    dirty: false,
                     computed,
                     fullUsage,
                     loadFailed: false,
@@ -468,6 +480,8 @@ export function createUsageService(deps) {
             const failedLoads = fetched.filter((item) => {
                 if (!item.loadFailed)
                     return false;
+                if (item.dirty)
+                    return true;
                 const lastMessageTime = item.lastMessageTime;
                 if (typeof lastMessageTime === 'number' && lastMessageTime < startAt) {
                     return false;
@@ -492,6 +506,7 @@ export function createUsageService(deps) {
                         dateKeyFromTimestamp(memoryState.createdAt);
                     deps.state.sessionDateMap[sessionID] = resolvedDateKey;
                     deps.persistence.markDirty(resolvedDateKey);
+                    memoryState.dirty = false;
                     dirty = true;
                 }
                 else if (persist && fullUsage) {
@@ -504,7 +519,13 @@ export function createUsageService(deps) {
                 }
             }
             if (diskOnlyUpdates.length > 0) {
-                await updateSessionsInDayChunks(deps.statePath, diskOnlyUpdates).catch(swallow('updateSessionsInDayChunks'));
+                const persisted = await updateSessionsInDayChunks(deps.statePath, diskOnlyUpdates).catch((error) => {
+                    swallow('updateSessionsInDayChunks')(error);
+                    return false;
+                });
+                if (!persisted) {
+                    throw new Error(`range usage unavailable: failed to persist ${diskOnlyUpdates.length} disk-only session(s)`);
+                }
             }
             if (dirty)
                 deps.persistence.scheduleSave();
@@ -513,6 +534,16 @@ export function createUsageService(deps) {
     };
     const summarizeForTool = async (period, sessionID, includeChildren) => {
         if (period === 'session') {
+            if (!includeChildren) {
+                const session = await summarizeSessionUsageLocked(sessionID, {
+                    requireEntries: true,
+                });
+                if (session.persist) {
+                    persistSessionUsage(sessionID, toCachedSessionUsage(session.usage));
+                    deps.persistence.scheduleSave();
+                }
+                return session.usage;
+            }
             return summarizeSessionUsageForDisplay(sessionID, includeChildren);
         }
         return summarizeRangeUsage(period);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leo000001/opencode-quota-sidebar",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "OpenCode plugin that shows quota and token usage in session titles",
   "type": "module",
   "main": "dist/index.js",