sidekick-shared 0.26.2 → 0.26.4

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.4] - 2026-09-09
+
+### Fixed
+
+- `diagnoseProviderFailure()` recognizes explicit login expiry and reauthentication requests, and gives refresh-token rejection precedence over conversation-expiry wording while preserving structured evidence and credential-aware recovery.
+- `Permission denied by policy` is classified as execution-policy denial, including HTTP 403 responses. Ambiguous session and permission messages retain their existing classifications.
+
+## [0.26.3] - 2026-09-09
+
+### Added
+
+- `diagnoseProviderFailure()` and its pure types are available from the root and browser entry points. Results contain bounded diagnosis/recovery identifiers, evidence provenance, and optional HTTP/retry-after data without raw errors or credentials.
+- `fetchProviderServiceStatus()` is available from the root and Node entry points, with pure result types also exported through browser. Stateless official-feed checks support cancellation and a ten-second deadline, preserve component/incident associations and independent timestamps, and distinguish observed, unavailable, and omitted incident evidence.
+- `HealthReport.serviceStatus` and `DoctorOptions.fetchServiceStatuses` add explicit service evidence while retaining legacy status output and injection. `toLegacyProviderStatus()` supports compatibility projections.
+
+### Changed
+
+- Doctor reports unavailable and partial public evidence explicitly. Existing `ErrorCategory`, quota guidance, and legacy status functions/types remain compatible; consumers needing availability semantics should adopt the new API.
+
 ## [0.26.2] - 2026-09-06
 
 ### Added

package/README.md

@@ -9,6 +9,7 @@ Types, parsers, providers, readers, formatters, aggregation, search, reporting,
 
 ## Recent additions
 
+- **0.26.3–0.26.4: provider failure diagnosis and service status** — `diagnoseProviderFailure()` (root and browser) classifies caller-designated terminal errors into bounded diagnosis and recovery identifiers with evidence provenance; `fetchProviderServiceStatus()` (root and Node) returns explicit observed/unavailable public status with component and incident associations. 0.26.4 recognizes expired-login and re-authentication messages, gives explicit refresh-token rejection precedence over conversation-expiry wording, and classifies `denied by policy` as `execution_policy_denied`.
 - **0.26.2: reliable monitoring and search** — complete-line JSONL cursors preserve Unicode and Codex parser context; watcher `onBatchComplete` signals a delivered batch. `searchSessions()` adds workspace-path filtering and cancellation, and Doctor accepts an explicit session provider.
 - **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.
@@ -449,20 +450,83 @@ const tasks = await readTasks(project, { status: 'pending' });
 console.log(`Found ${tasks.length} tasks`);
 ```
 
-### Check provider status
+### Diagnose terminal provider failures
+
+`diagnoseProviderFailure()` is a pure, synchronous helper exported from `sidekick-shared` and `sidekick-shared/browser`. The caller decides whether an SDK event is terminal: a Codex `ErrorItem`, including a reconnect notice, must not become terminal merely because its message can be classified.
 
 ```typescript
-import { fetchProviderStatus } from 'sidekick-shared';
+import { diagnoseProviderFailure } from 'sidekick-shared/browser';
 
-const status = await fetchProviderStatus();
-if (status.indicator !== 'none') {
-  console.log(`Claude API: ${status.description}`);
-  for (const c of status.affectedComponents) {
-    console.log(`  ${c.name}: ${c.status}`);
-  }
+function diagnoseTerminalError(error: unknown) {
+  return diagnoseProviderFailure({
+    provider: 'codex', // AccountProviderId: 'claude-code' | 'codex'
+    credentialKind: 'oauth', // 'oauth' | 'api-key' | 'unknown'
+    error,
+    authentication: {
+      credentialKind: 'oauth',
+      state: 'authenticated',
+      source: 'local-check',
+      checkedAt: '2026-09-09T12:00:00.000Z',
+    },
+  });
+}
+```
+
+Authentication evidence is optional. Its states are `authenticated`, `missing`, `signed-out`, `expired`, `rejected`, and `unknown`; sources are `local-check` and `provider-response`. The caller owns the observation's freshness and relevance. File presence alone does not establish authenticated request success.
+
+The result contains `provider`, caller-supplied `credentialKind`, `diagnosis`, `recovery`, and `evidence`. Evidence records a bounded rule and its source (`structured-error`, `http-status`, `message`, or `authentication-check`); authentication-check evidence includes `checkedAt`. Valid supplied authentication evidence is preserved separately. Optional `httpStatus` and `retryAfter` retain request information; retry-after is `{ kind: 'delay', delayMs }` or `{ kind: 'date', at }`, without a clock-dependent conversion.
+
+| Diagnosis                                                      | Recovery identifier                                                                      |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `missing_credentials`                                          | `sign_in`, `update_credentials`, or `check_authentication`, according to credential kind |
+| `oauth_reauthentication_required`                              | `sign_in`                                                                                |
+| `api_credentials_rejected`                                     | `update_credentials`                                                                     |
+| `authentication_rejected` (credential kind unknown)            | `check_authentication`                                                                   |
+| `invalid_provider_session`                                     | `start_new_session`                                                                      |
+| `service_unavailable`, `timeout`, `rate_limited`, `overloaded` | `retry_later`                                                                            |
+| `connection_failed`                                            | `check_connection`                                                                       |
+| `execution_policy_denied`                                      | `review_execution_policy`                                                                |
+| `runtime_unavailable`                                          | `repair_runtime`                                                                         |
+| `context_overflow`                                             | `reduce_context`                                                                         |
+| `unknown`                                                      | `inspect_error`                                                                          |
+
+Recognized structured request codes take precedence over HTTP status, followed by narrow message patterns. A bare 401 establishes credential rejection, with recovery chosen from the credential kind; a bare 403 does not distinguish authentication from execution policy and remains unknown, while a message containing `denied by policy` is `execution_policy_denied` regardless of status. An explicit OAuth or refresh-token rejection (`refresh token is invalid`) outranks overlapping thread/conversation-expiry wording; `login has expired` and `please re-authenticate` resolve according to the credential kind. Ambiguous phrases such as `Session expired` or `Permission denied` on their own remain unknown. Explicit credential rejection from the request overrides a successful local OAuth check. OAuth observations never validate API keys. Thread/conversation failures, 5xx responses, DNS failures, and connection resets do not establish rejected account credentials. The reported `Reconnecting... 2/5 (unexpected status 503 Service Unavailable: upstream connect error or disconnect/reset before headers. reset reason: connection termination)` is classified as `service_unavailable`, with message provenance and HTTP 503, if the caller supplies it as a terminal error.
+
+The projection contains no raw errors, stacks, credentials, or request URLs. Product wording belongs to consumers. The helper performs no I/O, credential reads, SDK calls, stream control, retries, or UI actions. Existing transcript/tool `ErrorCategory` and quota-specific guidance contracts remain unchanged.
+
+### Check public provider service status
+
+```typescript
+import { fetchProviderServiceStatus } from 'sidekick-shared/node';
+import type { ProviderServiceStatus } from 'sidekick-shared/browser';
+
+const controller = new AbortController();
+const status: ProviderServiceStatus = await fetchProviderServiceStatus('codex', {
+  signal: controller.signal,
+});
+
+if (status.availability === 'unavailable') {
+  console.log('Public status unavailable', status.reason, status.checkedAt);
+} else {
+  console.log(status.severity, status.checkedAt, status.providerUpdatedAt);
+  // null means the feed omitted incident evidence; [] explicitly reports none unresolved.
+  console.log(status.incidents === null ? 'Incident information unavailable' : status.incidents);
 }
 ```
 
+The fetcher is exported from root and Node, with pure result types also exported from browser. It requests the official [Claude summary](https://status.claude.com/api/v2/summary.json) or [OpenAI summary](https://status.openai.com/api/v2/summary.json) without credentials. Every call has a ten-second deadline covering headers and body consumption, supports caller cancellation, and performs one request with no retries or cache.
+
+- `observed` results contain provider, source URL, check timestamp, reported severity/description, provider page update timestamp, all reported components, and unresolved incidents. Supported severity values are `none`, `minor`, `major`, `critical`, and `maintenance`.
+- Components retain IDs, names, and reported states. Incidents retain IDs, titles, status, impact, HTTP(S) links, provider update timestamps, and component IDs. Unknown associations are `null`; unmatched IDs are preserved. Resolved and postmortem incidents are excluded.
+- Omitted incident data is represented as `incidents: null`, preserving a partial observation without claiming zero incidents. Missing provider timestamps and links remain `null`; the check timestamp never substitutes for a provider update.
+- `unavailable` results contain no severity. Reasons are `http_error`, `network_error`, `timeout`, `cancelled`, or `invalid_response`, with optional HTTP status and no raw error text. Malformed supplied fields are rejected rather than defaulted to operational.
+
+Request failure, authentication, CLI readiness, and public service status are separate observations. Public incidents supplement a diagnosis but do not prove a failed request's cause. An operational public page does not prove that the user's connection works. Preserve component associations to avoid attributing unrelated vendor incidents to Claude Code or Codex; unknown component mappings and custom provider endpoints remain uncorrelated. The result's `provider` identifies the selected public feed, not a verified request-backend mapping.
+
+Consumers own caching, stale-evidence presentation, polling, and request coalescing. Neither API initiates sign-in, modifies credentials, switches providers, requests a model response, or replays a turn.
+
+`fetchProviderStatus()`, `fetchOpenAIStatus()`, and `ProviderStatusState` remain compatible. Their historical fallback combines `indicator: 'none'` with `Status unavailable`; migrate to the new API for reliable availability semantics. `toLegacyProviderStatus()` is a lossy compatibility projection for older output contracts, not an availability check. Doctor includes optional `serviceStatus` evidence alongside legacy `providerStatus`; its new `fetchServiceStatuses` injection takes precedence over legacy `fetchStatuses`, which remains supported without additional network requests.
+
 ### Check Claude peak-hours state
 
 ```typescript

package/dist/browser.d.ts

@@ -39,3 +39,6 @@ export { applySessionSummary, isFileImported, markFileImported, removeSessionSum
 export type { ApplySessionSummaryOptions, SessionSummaryFromStatsOptions } from './historicalStore';
 export { FAILING_TOOL_TREND_ARROWS, failingToolTrend, mergeFailingToolWindows, } from './failingTools';
 export type { FailingToolTrend, FailingToolTrendRow, FailingToolWindow } from './failingTools';
+export { diagnoseProviderFailure } from './providerFailure';
+export type { ProviderCredentialKind, ProviderAuthenticationEvidence, ProviderFailureInput, ProviderFailureCode, ProviderRecoveryAction, ProviderRetryAfter, ProviderFailureEvidence, ProviderFailureDiagnosis, } from './providerFailure';
+export type { ProviderServiceSeverity, ProviderServiceComponent, ProviderServiceIncident, ProviderServiceStatusFailureReason, ObservedProviderServiceStatus, UnavailableProviderServiceStatus, ProviderServiceStatus, FetchProviderServiceStatusOptions, } from './providerServiceStatusTypes';

package/dist/browser.js

@@ -10,7 +10,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.resolveModelPricing = exports.getModelPricing = exports.parseModelId = exports.segmentAssistantTurn = exports.reasoningSummary = exports.isAssistantTurnSubagentTool = exports.extractTurnSubagents = exports.assistantTurnEventsFromSessionEvents = exports.SESSION_PROVIDER_IDS = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.QUOTA_PROVIDER_IDS = exports.MODEL_PROVIDER_IDS = exports.ACCOUNT_PROVIDER_IDS = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.parseMcpToolName = exports.parseLocalDateKey = exports.formatTokenCount = exports.formatLocalDateKey = exports.formatDurationMs = exports.addLocalDays = exports.projectSessionTranscript = exports.estimateSerializedTokens = exports.estimateTextTokens = exports.TOKEN_TOTAL_LABEL = exports.TOKEN_CONTEXT_LABEL = exports.sumTokenTotals = exports.summarizeTokens = exports.calculateNormalizedUsageCost = exports.extractNormalizedUsage = exports.normalizeProviderUsage = exports.DEFAULT_CONTEXT_WINDOW = exports.resolveModelContextWindow = exports.getModelContextWindowSize = void 0;
-exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = void 0;
+exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = void 0;
 var modelContext_1 = require("./modelContext");
 Object.defineProperty(exports, "getModelContextWindowSize", { enumerable: true, get: function () { return modelContext_1.getModelContextWindowSize; } });
 Object.defineProperty(exports, "resolveModelContextWindow", { enumerable: true, get: function () { return modelContext_1.resolveModelContextWindow; } });
@@ -92,3 +92,5 @@ var failingTools_1 = require("./failingTools");
 Object.defineProperty(exports, "FAILING_TOOL_TREND_ARROWS", { enumerable: true, get: function () { return failingTools_1.FAILING_TOOL_TREND_ARROWS; } });
 Object.defineProperty(exports, "failingToolTrend", { enumerable: true, get: function () { return failingTools_1.failingToolTrend; } });
 Object.defineProperty(exports, "mergeFailingToolWindows", { enumerable: true, get: function () { return failingTools_1.mergeFailingToolWindows; } });
+var providerFailure_1 = require("./providerFailure");
+Object.defineProperty(exports, "diagnoseProviderFailure", { enumerable: true, get: function () { return providerFailure_1.diagnoseProviderFailure; } });

package/dist/doctor.d.ts

@@ -1,6 +1,7 @@
 import { type ActiveAccountStatus } from './accountStatus';
 import { type ProjectIdentity } from './paths';
 import { type ProviderStatusState } from './providerStatus';
+import type { ProviderServiceStatus } from './providerServiceStatusTypes';
 import type { ProviderId } from './providers/types';
 import { type OpenCodeDbRuntimeStatus } from './providers/openCodeDatabase';
 export type HealthCheckStatus = 'ok' | 'warning' | 'error' | 'info';
@@ -39,6 +40,10 @@ export interface HealthReport {
         claude: ProviderStatusState;
         openai: ProviderStatusState;
     };
+    serviceStatus?: {
+        claude: ProviderServiceStatus;
+        openai: ProviderServiceStatus;
+    };
     /** Legacy Claude Code path diagnostics, retained for compatibility. */
     sessions: SessionDiagnostics;
     sessionProvider?: ProviderId;
@@ -49,6 +54,11 @@ export interface DoctorOptions {
     provider?: ProviderId | 'auto';
     deprecatedSettings?: DeprecatedSetting[];
     openCodeStatus?: OpenCodeDbRuntimeStatus;
+    fetchServiceStatuses?: () => Promise<{
+        claude: ProviderServiceStatus;
+        openai: ProviderServiceStatus;
+    }>;
+    /** Legacy injection; does not establish service evidence availability. */
     fetchStatuses?: () => Promise<{
         claude: ProviderStatusState;
         openai: ProviderStatusState;

package/dist/doctor.js

@@ -43,6 +43,7 @@ const accountStatus_1 = require("./accountStatus");
 const paths_1 = require("./paths");
 const sessionPathResolver_1 = require("./parsers/sessionPathResolver");
 const providerStatus_1 = require("./providerStatus");
+const providerServiceStatus_1 = require("./providerServiceStatus");
 const openCode_1 = require("./providers/openCode");
 const factory_1 = require("./providers/factory");
 const detect_1 = require("./providers/detect");
@@ -163,11 +164,34 @@ async function runDoctor(options = {}) {
         openCode = database.getRuntimeStatus();
         database.close();
     }
-    const providerStatus = await (options.fetchStatuses ??
-        (async () => {
-            const [claude, openai] = await Promise.all([(0, providerStatus_1.fetchProviderStatus)(), (0, providerStatus_1.fetchOpenAIStatus)()]);
-            return { claude, openai };
-        }))().catch(() => ({ claude: statusUnavailable(), openai: statusUnavailable() }));
+    const serviceStatus = options.fetchServiceStatuses || !options.fetchStatuses
+        ? await (options.fetchServiceStatuses ??
+            (async () => {
+                const [claude, openai] = await Promise.all([
+                    (0, providerServiceStatus_1.fetchProviderServiceStatus)('claude-code'),
+                    (0, providerServiceStatus_1.fetchProviderServiceStatus)('codex'),
+                ]);
+                return { claude, openai };
+            }))().catch(() => {
+            const unavailable = (provider) => ({
+                availability: 'unavailable',
+                provider,
+                checkedAt: new Date().toISOString(),
+                sourceUrl: `https://status.${provider === 'codex' ? 'openai' : 'claude'}.com/api/v2/summary.json`,
+                reason: 'network_error',
+            });
+            return { claude: unavailable('claude-code'), openai: unavailable('codex') };
+        })
+        : undefined;
+    const providerStatus = serviceStatus
+        ? {
+            claude: (0, providerStatus_1.toLegacyProviderStatus)(serviceStatus.claude),
+            openai: (0, providerStatus_1.toLegacyProviderStatus)(serviceStatus.openai),
+        }
+        : await options.fetchStatuses().catch(() => ({
+            claude: statusUnavailable(),
+            openai: statusUnavailable(),
+        }));
     const checks = [];
     checks.push(project.hasLegacyMismatch
         ? {
@@ -225,25 +249,48 @@ async function runDoctor(options = {}) {
             }
             : {}),
     });
-    const unavailableProviders = Object.entries(providerStatus)
-        .filter(([, status]) => status.description === 'Status unavailable')
-        .map(([name]) => name);
-    const degradedProviders = Object.entries(providerStatus)
-        .filter(([, status]) => status.indicator !== 'none')
-        .map(([name]) => name);
+    const unavailableProviders = serviceStatus
+        ? Object.entries(serviceStatus)
+            .filter(([, status]) => status.availability === 'unavailable')
+            .map(([name]) => name)
+        : Object.entries(providerStatus)
+            .filter(([, status]) => status.description === 'Status unavailable')
+            .map(([name]) => name);
+    const degradedProviders = serviceStatus
+        ? Object.entries(serviceStatus)
+            .filter(([, status]) => status.availability === 'observed' && status.severity !== 'none')
+            .map(([name]) => name)
+        : Object.entries(providerStatus)
+            .filter(([, status]) => status.indicator !== 'none')
+            .map(([name]) => name);
+    const partialProviders = serviceStatus
+        ? Object.entries(serviceStatus)
+            .filter(([, status]) => status.availability === 'observed' && status.incidents === null)
+            .map(([name]) => name)
+        : [];
+    const observations = [
+        ...(degradedProviders.length
+            ? [`Public vendor degradation reported for: ${degradedProviders.join(', ')}.`]
+            : []),
+        ...(unavailableProviders.length
+            ? [`Status pages unavailable for: ${unavailableProviders.join(', ')}.`]
+            : []),
+        ...(partialProviders.length
+            ? [`Incident information unavailable for: ${partialProviders.join(', ')}.`]
+            : []),
+    ];
     checks.push({
         id: 'provider_api',
         status: degradedProviders.includes(sessionProvider === 'codex' ? 'openai' : sessionProvider === 'claude-code' ? 'claude' : '')
             ? 'warning'
-            : degradedProviders.length > 0 || unavailableProviders.length > 0
+            : observations.length
                 ? 'info'
                 : 'ok',
-        title: 'Provider API status',
-        message: degradedProviders.length > 0
-            ? `Provider incidents reported for: ${degradedProviders.join(', ')}.`
-            : unavailableProviders.length > 0
-                ? `Status pages unavailable for: ${unavailableProviders.join(', ')}.`
-                : 'Claude and OpenAI status pages report normal operation.',
+        title: 'Public provider service status',
+        message: (observations.length
+            ? observations.join(' ')
+            : 'Claude and OpenAI status pages report normal operation.') +
+            ' Public status does not establish request connectivity or authentication.',
     });
     const deprecatedSettings = options.deprecatedSettings ?? [];
     checks.push({
@@ -275,6 +322,7 @@ async function runDoctor(options = {}) {
         accounts,
         openCode,
         providerStatus,
+        ...(serviceStatus ? { serviceStatus } : {}),
         sessions,
         sessionProvider,
     };

package/dist/index.d.ts

@@ -233,7 +233,7 @@ export { quotaHistoryRuntimeProviderSchema, quotaHistorySampleSchema, quotaHisto
 export { activeProviderAccountStatusSchema, activeAccountStatusSchema, } from './schemas/accountStatus';
 export { accountProviderIdSchema, accountManagerResultSchema, beginAccountLoginResultSchema, accountLoginStatusSchema, accountEntrySchema, savedAccountProfileSchema, listAllAccountsResultSchema, } from './schemas/accountManager';
 export { assistantTurnEventSchema, assistantTurnEventTypeSchema, assistantTurnNarrationStepSchema, assistantTurnProcessSchema, assistantTurnProcessStepSchema, assistantTurnProjectionSchema, assistantTurnReasoningTimelineItemSchema, assistantTurnSubagentSchema, assistantTurnSubagentStatusSchema, assistantTurnTimelineItemSchema, assistantTurnToolGroupStepSchema, assistantTurnToolRefSchema, } from './schemas/assistantTurn';
-export { fetchProviderStatus, fetchOpenAIStatus } from './providerStatus';
+export { fetchProviderStatus, fetchOpenAIStatus, toLegacyProviderStatus } from './providerStatus';
 export type { ProviderStatusState } from './providerStatus';
 export { formatHealthReport, getSessionDiagnostics, runDoctor } from './doctor';
 export type { DeprecatedSetting, DoctorOptions, HealthCheck, HealthCheckStatus, HealthReport, SessionDiagnostics, } from './doctor';
@@ -241,3 +241,7 @@ export { _resetPeakHoursCache, createPeakHoursNotApplicableState, DEFAULT_PEAK_H
 export type { FetchPeakHoursOptions, PeakHoursState } from './peakHours';
 export { FAILING_TOOL_TREND_ARROWS, failingToolTrend, mergeFailingToolWindows, } from './failingTools';
 export type { FailingToolTrend, FailingToolTrendRow, FailingToolWindow } from './failingTools';
+export { diagnoseProviderFailure } from './providerFailure';
+export type { ProviderCredentialKind, ProviderAuthenticationEvidence, ProviderFailureInput, ProviderFailureCode, ProviderRecoveryAction, ProviderRetryAfter, ProviderFailureEvidence, ProviderFailureDiagnosis, } from './providerFailure';
+export type { ProviderServiceSeverity, ProviderServiceComponent, ProviderServiceIncident, ProviderServiceStatusFailureReason, ObservedProviderServiceStatus, UnavailableProviderServiceStatus, ProviderServiceStatus, FetchProviderServiceStatusOptions, } from './providerServiceStatusTypes';
+export { fetchProviderServiceStatus } from './providerServiceStatus';

package/dist/index.js

@@ -11,7 +11,7 @@ exports.finalizeAccountLogin = exports.getAccountLoginStatusAsync = exports.getA
 exports.FIVE_HOUR_WINDOW_MS = exports.AutoSwitchController = exports.decideAutoSwitch = exports.DEFAULT_AUTO_SWITCH_CONFIG = exports.removeLauncher = exports.writeLauncher = exports.isShellHookInstalled = exports.uninstallShellHook = exports.installShellHook = exports.setTerminalActiveProfile = exports.removeCodexAccount = exports.switchToCodexAccountAsync = exports.switchToCodexAccount = exports.finalizeCodexAccountAsync = exports.finalizeCodexAccount = exports.prepareCodexAccountAsync = exports.prepareCodexAccount = exports.getCodexExecutionEnv = exports.resolveSidekickCodexHome = exports.resolveActiveCodexAccount = exports.getActiveCodexAccount = exports.listCodexAccounts = exports.getSystemCodexHome = exports.getCodexMonitoringHomes = exports.getCodexProfileHome = exports.getCodexProfilesDir = exports.readClaudeProfileIdentity = exports.isClaudeProfileAuthenticated = exports.claudeKeychainService = exports.claudeKeychainSuffix = exports.getClaudeProfileHome = exports.getClaudeProfilesDir = exports.onAccountsChanged = exports.getActiveAccountStatus = exports.ACCOUNT_PROVIDER_IDS = exports.removeSavedAccountProfile = exports.replaceSavedAccountProfiles = exports.setActiveSavedAccount = exports.upsertSavedAccountProfile = exports.getActiveSavedAccount = exports.listSavedAccountProfiles = exports.writeSavedAccountRegistry = exports.readSavedAccountRegistry = exports.getAccountsDir = exports.resolveClaudeLoginCommand = exports.listAllAccounts = exports.switchAccountAsync = exports.switchAccount = exports.spawnAccountLogin = exports.finalizeAccountLoginAsync = void 0;
 exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.resolveModelPricing = exports.getModelPricing = exports.parseModelId = exports.DEFAULT_CONTEXT_WINDOW = exports.resolveModelContextWindow = exports.getModelContextWindowSize = exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.RUNTIME_QUOTA_PROVIDER_IDS = exports.MultiProviderQuotaService = exports.resolveZaiQuota = exports.readZaiCredentials = exports.quotaStateFromZaiQuotaLimitPayload = exports.fetchZaiQuotaFromApi = exports.CodexQuotaWatcher = exports.resolveCodexQuotaFromLocalSources = exports.resolveCodexQuota = exports.readLatestCodexQuotaFromRollouts = exports.quotaFromCodexRateLimits = exports.fetchCodexQuotaFromApi = exports.fetchCodexResetCreditsFromApi = exports.getWorkspaceIdFromPath = exports.pruneQuotaHistory = exports.readQuotaHistoryDailyBuckets = exports.readQuotaHistoryRange = exports.appendQuotaHistorySample = exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = exports.evaluateQuotaThresholds = exports.describeQuotaThresholdAlert = exports.DEFAULT_QUOTA_THRESHOLDS = exports.QUOTA_FRESH_MAX_AGE_MS = exports.QUOTA_AGING_MAX_AGE_MS = exports.formatQuotaAge = exports.classifyQuotaFreshness = exports.resolveQuota = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.QuotaPoller = exports.describeQuotaFailure = exports.withQuotaProjections = exports.projectQuotaWindow = exports.fetchQuota = exports.SEVEN_DAY_WINDOW_MS = exports.QUOTA_PROVIDER_IDS = void 0;
 exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaStateSchema = exports.quotaWindowSchema = exports.extractSessionEvents = exports.permissionModeSchema = exports.sessionEventSchema = exports.sessionMessageSchema = exports.messageUsageSchema = exports.ToolCallTracker = exports.extractToolCalls = exports.extractToolCall = exports.extractErrorMessage = exports.categorizeError = exports.gatherAssetsForCwd = exports.codexSessions = exports.readCodexAssets = exports.claudeSessions = exports.readClaudeAssets = exports.extractCommands = exports.extractFilePaths = exports.extractUrls = exports.extractTokenUsage = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = exports.RESOLVED_MODEL_CATALOG_SCHEMA_VERSION = exports.resolveModelAlias = exports.registerModelAlias = exports.importResolvedModelCatalog = exports.exportResolvedModelCatalog = exports.MODEL_PROVIDER_IDS = exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = void 0;
-exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.scopePeakHoursToSessionProvider = exports.PEAK_HOURS_DESCRIPTION = exports.PEAK_HOURS_CACHE_MS = exports.isClaudeCodeSessionProvider = exports.getScheduledPeakHoursState = exports.fetchPeakHoursStatus = exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = exports.createPeakHoursNotApplicableState = exports._resetPeakHoursCache = exports.runDoctor = exports.getSessionDiagnostics = exports.formatHealthReport = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = void 0;
+exports.fetchProviderServiceStatus = exports.diagnoseProviderFailure = exports.mergeFailingToolWindows = exports.failingToolTrend = exports.FAILING_TOOL_TREND_ARROWS = exports.scopePeakHoursToSessionProvider = exports.PEAK_HOURS_DESCRIPTION = exports.PEAK_HOURS_CACHE_MS = exports.isClaudeCodeSessionProvider = exports.getScheduledPeakHoursState = exports.fetchPeakHoursStatus = exports.DEFAULT_PEAK_HOURS_TIMEOUT_MS = exports.createPeakHoursNotApplicableState = exports._resetPeakHoursCache = exports.runDoctor = exports.getSessionDiagnostics = exports.formatHealthReport = exports.toLegacyProviderStatus = exports.fetchOpenAIStatus = exports.fetchProviderStatus = exports.assistantTurnToolRefSchema = exports.assistantTurnToolGroupStepSchema = exports.assistantTurnTimelineItemSchema = exports.assistantTurnSubagentStatusSchema = exports.assistantTurnSubagentSchema = exports.assistantTurnReasoningTimelineItemSchema = exports.assistantTurnProjectionSchema = exports.assistantTurnProcessStepSchema = exports.assistantTurnProcessSchema = exports.assistantTurnNarrationStepSchema = exports.assistantTurnEventTypeSchema = exports.assistantTurnEventSchema = exports.listAllAccountsResultSchema = exports.savedAccountProfileSchema = exports.accountEntrySchema = exports.accountLoginStatusSchema = exports.beginAccountLoginResultSchema = exports.accountManagerResultSchema = exports.accountProviderIdSchema = exports.activeAccountStatusSchema = exports.activeProviderAccountStatusSchema = exports.quotaHistoryDailyBucketSchema = exports.quotaHistorySampleSchema = exports.quotaHistoryRuntimeProviderSchema = exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = void 0;
 var usageNormalization_1 = require("./usageNormalization");
 Object.defineProperty(exports, "normalizeProviderUsage", { enumerable: true, get: function () { return usageNormalization_1.normalizeProviderUsage; } });
 Object.defineProperty(exports, "extractNormalizedUsage", { enumerable: true, get: function () { return usageNormalization_1.extractNormalizedUsage; } });
@@ -615,6 +615,7 @@ Object.defineProperty(exports, "assistantTurnToolRefSchema", { enumerable: true,
 var providerStatus_1 = require("./providerStatus");
 Object.defineProperty(exports, "fetchProviderStatus", { enumerable: true, get: function () { return providerStatus_1.fetchProviderStatus; } });
 Object.defineProperty(exports, "fetchOpenAIStatus", { enumerable: true, get: function () { return providerStatus_1.fetchOpenAIStatus; } });
+Object.defineProperty(exports, "toLegacyProviderStatus", { enumerable: true, get: function () { return providerStatus_1.toLegacyProviderStatus; } });
 // Shared diagnostics / health report
 var doctor_1 = require("./doctor");
 Object.defineProperty(exports, "formatHealthReport", { enumerable: true, get: function () { return doctor_1.formatHealthReport; } });
@@ -635,3 +636,7 @@ var failingTools_1 = require("./failingTools");
 Object.defineProperty(exports, "FAILING_TOOL_TREND_ARROWS", { enumerable: true, get: function () { return failingTools_1.FAILING_TOOL_TREND_ARROWS; } });
 Object.defineProperty(exports, "failingToolTrend", { enumerable: true, get: function () { return failingTools_1.failingToolTrend; } });
 Object.defineProperty(exports, "mergeFailingToolWindows", { enumerable: true, get: function () { return failingTools_1.mergeFailingToolWindows; } });
+var providerFailure_1 = require("./providerFailure");
+Object.defineProperty(exports, "diagnoseProviderFailure", { enumerable: true, get: function () { return providerFailure_1.diagnoseProviderFailure; } });
+var providerServiceStatus_1 = require("./providerServiceStatus");
+Object.defineProperty(exports, "fetchProviderServiceStatus", { enumerable: true, get: function () { return providerServiceStatus_1.fetchProviderServiceStatus; } });

package/dist/node.d.ts

@@ -38,3 +38,5 @@ export { listSessionPreviews, listSessionPreviewsAsync, readSessionPreview, read
 export type { AsyncSessionPreviewOptions, ListSessionPreviewsAsyncOptions, ListSessionPreviewsOptions, ReadSessionPreviewAsyncOptions, ReadSessionPreviewOptions, SessionPreview, SessionPreviewListResult, SessionPreviewReadResult, } from './sessionPreviews';
 export { ObservedSessionCollector, observedSessionSourceFromProvider, fileFingerprint, fileFingerprintParts, } from './observedSessionCollector';
 export type { KnownObservedSessionFingerprint, ObservedSessionChange, ObservedSessionChangeBatch, ObservedSessionChangeType, ObservedSessionReference, ObservedSessionFingerprintParts, ObservedSessionSourceSubscribeOptions, ObservedSessionSubscribeOptions, ObservedSessionCollectionSource, ProviderObservedSessionCollectionSource, ObservedSessionDiagnosticKind, ObservedSessionDiagnosticPhase, ObservedSessionDiagnosticSeverity, ObservedSessionDiagnostic, ObservedSessionCollection, ObservedSessionCollectorOptions, } from './observedSessionCollector';
+export type { ProviderServiceSeverity, ProviderServiceComponent, ProviderServiceIncident, ProviderServiceStatusFailureReason, ObservedProviderServiceStatus, UnavailableProviderServiceStatus, ProviderServiceStatus, FetchProviderServiceStatusOptions, } from './providerServiceStatusTypes';
+export { fetchProviderServiceStatus } from './providerServiceStatus';

package/dist/node.js

@@ -8,7 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readSessionPreviewAsync = exports.readSessionPreview = exports.listSessionPreviewsAsync = exports.listSessionPreviews = exports.readCodexHistory = exports.walkRolloutFilesAsync = exports.walkRolloutFiles = exports.findCodexRolloutFile = exports.weekKey = exports.usageBucketKey = exports.summarizeUsageRows = exports.bucketUsage = exports.importSessionHistory = exports.ACTIVE_SESSION_MTIME_THRESHOLD_MS = exports.sessionSummaryFromStats = exports.removeSessionSummary = exports.markFileImported = exports.isFileImported = exports.applySessionSummary = exports.pruneUsageCache = exports.getUsageCacheDir = exports.collectUsageEvents = exports.USAGE_CACHE_VERSION = exports.MAX_USAGE_CACHE_FILES = exports.findActiveBillingBlock = exports.computeBillingBlocks = exports.BILLING_BLOCK_DURATION_MS = exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.sessionFingerprintParts = exports.fingerprintString = exports.readSessionReportInputs = exports.readSessionFileStats = exports.providerContextSizeFn = exports.firstUserPrompt = exports.computeSessionFileStats = exports.readSessionTranscript = exports.listRecentSessions = exports.getObservedContextWindowPath = exports.recordObservedContextWindow = exports.loadObservedContextWindows = exports.LITELLM_CATALOG_URL = exports.normalizeLiteLlmContextWindows = exports.normalizeLiteLlmCatalog = exports.hydratePricingCatalog = void 0;
-exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = void 0;
+exports.fetchProviderServiceStatus = exports.fileFingerprintParts = exports.fileFingerprint = exports.observedSessionSourceFromProvider = exports.ObservedSessionCollector = void 0;
 var pricingCatalog_1 = require("./pricingCatalog");
 Object.defineProperty(exports, "hydratePricingCatalog", { enumerable: true, get: function () { return pricingCatalog_1.hydratePricingCatalog; } });
 Object.defineProperty(exports, "normalizeLiteLlmCatalog", { enumerable: true, get: function () { return pricingCatalog_1.normalizeLiteLlmCatalog; } });
@@ -80,3 +80,5 @@ Object.defineProperty(exports, "ObservedSessionCollector", { enumerable: true, g
 Object.defineProperty(exports, "observedSessionSourceFromProvider", { enumerable: true, get: function () { return observedSessionCollector_1.observedSessionSourceFromProvider; } });
 Object.defineProperty(exports, "fileFingerprint", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprint; } });
 Object.defineProperty(exports, "fileFingerprintParts", { enumerable: true, get: function () { return observedSessionCollector_1.fileFingerprintParts; } });
+var providerServiceStatus_1 = require("./providerServiceStatus");
+Object.defineProperty(exports, "fetchProviderServiceStatus", { enumerable: true, get: function () { return providerServiceStatus_1.fetchProviderServiceStatus; } });

package/dist/providerFailure.d.ts

@@ -0,0 +1,46 @@
+import type { AccountProviderId } from './providerIds';
+export type ProviderCredentialKind = 'oauth' | 'api-key' | 'unknown';
+export interface ProviderAuthenticationEvidence {
+    credentialKind: ProviderCredentialKind;
+    state: 'authenticated' | 'missing' | 'signed-out' | 'expired' | 'rejected' | 'unknown';
+    checkedAt: string;
+    source: 'local-check' | 'provider-response';
+}
+export interface ProviderFailureInput {
+    provider: AccountProviderId;
+    credentialKind: ProviderCredentialKind;
+    /** The caller, not this helper, determines whether the error is terminal. */
+    error: unknown;
+    /** The caller owns freshness and relevance of this separate observation. */
+    authentication?: ProviderAuthenticationEvidence;
+}
+export type ProviderFailureCode = 'missing_credentials' | 'oauth_reauthentication_required' | 'api_credentials_rejected' | 'authentication_rejected' | 'invalid_provider_session' | 'service_unavailable' | 'connection_failed' | 'timeout' | 'rate_limited' | 'overloaded' | 'execution_policy_denied' | 'runtime_unavailable' | 'context_overflow' | 'unknown';
+export type ProviderRecoveryAction = 'sign_in' | 'update_credentials' | 'check_authentication' | 'start_new_session' | 'retry_later' | 'check_connection' | 'review_execution_policy' | 'repair_runtime' | 'reduce_context' | 'inspect_error';
+export type ProviderRetryAfter = {
+    kind: 'delay';
+    delayMs: number;
+} | {
+    kind: 'date';
+    at: string;
+};
+export interface ProviderFailureEvidence {
+    source: 'structured-error' | 'http-status' | 'message' | 'authentication-check';
+    rule: ProviderFailureCode;
+    checkedAt?: string;
+}
+/** Safe diagnostic projection. No raw error text, request data, or credentials. */
+export interface ProviderFailureDiagnosis {
+    provider: AccountProviderId;
+    credentialKind: ProviderCredentialKind;
+    diagnosis: ProviderFailureCode;
+    recovery: ProviderRecoveryAction;
+    evidence: ProviderFailureEvidence[];
+    authentication?: ProviderAuthenticationEvidence;
+    httpStatus?: number;
+    retryAfter?: ProviderRetryAfter;
+}
+/**
+ * Classify a caller-designated terminal failure without I/O or recovery actions.
+ * Public status and runtime readiness do not establish request authentication.
+ */
+export declare function diagnoseProviderFailure(input: ProviderFailureInput): ProviderFailureDiagnosis;

package/dist/providerFailure.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diagnoseProviderFailure = diagnoseProviderFailure;
+function read(value, key) {
+    try {
+        return value && typeof value === 'object' ? value[key] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function text(value) {
+    return typeof value === 'string' ? value.slice(0, 16_384) : '';
+}
+function statusNumber(value) {
+    const number = typeof value === 'string' && /^\d{3}$/.test(value) ? Number(value) : value;
+    return typeof number === 'number' && Number.isInteger(number) && number >= 100 && number <= 599
+        ? number
+        : undefined;
+}
+function timestamp(value) {
+    return typeof value === 'string' &&
+        value.length <= 64 &&
+        /^(?:\d{4}-\d{2}-\d{2}T|(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), )/.test(value) &&
+        Number.isFinite(Date.parse(value))
+        ? new Date(value).toISOString()
+        : undefined;
+}
+function retryAfter(value) {
+    if (typeof value === 'number' || (typeof value === 'string' && /^\d+(\.\d+)?$/.test(value))) {
+        const delayMs = Number(value) * 1000;
+        return Number.isFinite(delayMs) && delayMs >= 0 && delayMs <= Number.MAX_SAFE_INTEGER
+            ? { kind: 'delay', delayMs }
+            : undefined;
+    }
+    const at = timestamp(value);
+    return at ? { kind: 'date', at } : undefined;
+}
+function rejected(kind) {
+    return kind === 'oauth'
+        ? 'oauth_reauthentication_required'
+        : kind === 'api-key'
+            ? 'api_credentials_rejected'
+            : 'authentication_rejected';
+}
+function classifyCode(code, kind) {
+    switch (code.toLowerCase().replace(/[^a-z0-9]/g, '')) {
+        case 'missingcredentials':
+        case 'notloggedin':
+        case 'signedout':
+            return 'missing_credentials';
+        case 'invalidapikey':
+        case 'apikeyrejected':
+            return 'api_credentials_rejected';
+        case 'oauthtokenexpired':
+        case 'refreshtokenexpired':
+        case 'refreshtokenreused':
+        case 'invalidgrant':
+            return 'oauth_reauthentication_required';
+        case 'authenticationerror':
+        case 'autherror':
+        case 'invalidtoken':
+        case 'tokenexpired':
+        case 'unauthorized':
+            return rejected(kind);
+        case 'threadnotfound':
+        case 'invalidthreadid':
+        case 'conversationnotfound':
+        case 'invalidconversation':
+        case 'conversationexpired':
+        case 'invalidsessionid':
+            return 'invalid_provider_session';
+        case 'executionpolicydenied':
+        case 'sandboxdenied':
+        case 'approvaldenied':
+            return 'execution_policy_denied';
+        case 'ratelimiterror':
+        case 'ratelimitexceeded':
+        case 'toomanyrequests':
+            return 'rate_limited';
+        case 'overloadederror':
+        case 'serveroverloaded':
+            return 'overloaded';
+        case 'serviceunavailable':
+        case 'internalservererror':
+        case 'servererror':
+            return 'service_unavailable';
+        case 'timeouterror':
+        case 'apiconnectiontimeouterror':
+        case 'etimedout':
+        case 'underrconnecttimeout':
+        case 'underrheaderstimeout':
+        case 'deadlineexceeded':
+            return 'timeout';
+        case 'econnreset':
+        case 'econnrefused':
+        case 'enotfound':
+        case 'eaiagain':
+        case 'enetunreach':
+        case 'ehostunreach':
+        case 'apiconnectionerror':
+            return 'connection_failed';
+        case 'runtimenotfound':
+        case 'runtimeunavailable':
+        case 'modulenotfound':
+        case 'errmodulenotfound':
+            return 'runtime_unavailable';
+        case 'contextlengthexceeded':
+        case 'contextwindowexceeded':
+        case 'prompttoolong':
+            return 'context_overflow';
+        default:
+            return undefined;
+    }
+}
+function classifyStatus(status, kind) {
+    if (status === 401)
+        return rejected(kind);
+    if (status === 408 || status === 504)
+        return 'timeout';
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 529)
+        return 'overloaded';
+    if (status >= 500)
+        return 'service_unavailable';
+    return undefined;
+}
+function classifyMessage(message, kind) {
+    if (/\b(execution policy|sandbox policy|approval)\b.{0,60}\b(denied|blocked|rejected|not allowed)\b|\bdenied by policy\b/i.test(message))
+        return 'execution_policy_denied';
+    // Only explicit credential rejection outranks an overlapping conversation error.
+    if (/\b(oauth (?:(?:access |refresh )?token|credentials?)|refresh token) (?:is |was |has (?:been )?)?(expired|invalid|rejected|revoked)\b/i.test(message))
+        return 'oauth_reauthentication_required';
+    if (/\b(thread|conversation|session id)\b.{0,60}\b(not found|invalid|expired|does not exist)\b|\b(invalid|expired) (thread|conversation|session id)\b/i.test(message))
+        return 'invalid_provider_session';
+    if (/\b(oauth|refresh token)\b.{0,60}\b(expired|invalid|rejected|revoked)\b/i.test(message))
+        return 'oauth_reauthentication_required';
+    if (/\b(api[ _-]?key)\b.{0,60}\b(invalid|incorrect|rejected|revoked|expired)\b|\b(invalid|incorrect|rejected) api[ _-]?key\b/i.test(message))
+        return 'api_credentials_rejected';
+    if (/\b(no|missing) (oauth |api[ _-]?key |authentication )?(credentials|token|api[ _-]?key)\b|\bnot (logged|signed) in\b|\bsigned out\b|\bapi[ _-]?key (not configured|not set)\b/i.test(message))
+        return 'missing_credentials';
+    if (/\b(authentication failed|invalid authentication|credentials (rejected|expired)|token (expired|rejected|invalid)|login (has |is )?expired|please re-?authenticate)\b/i.test(message))
+        return rejected(kind);
+    if (/\b(context (length|window).{0,40}(exceed|overflow)|prompt (is )?too long|maximum context length)\b/i.test(message))
+        return 'context_overflow';
+    if (/\b(overloaded|over capacity|server busy)\b/i.test(message))
+        return 'overloaded';
+    if (/\b(rate[ _-]?limit|too many requests)\b/i.test(message))
+        return 'rate_limited';
+    if (/\b(timed? ?out|deadline exceeded|etimedout)\b/i.test(message))
+        return 'timeout';
+    if (/\b(service unavailable|bad gateway|internal server error)\b/i.test(message))
+        return 'service_unavailable';
+    if (/\b(enotfound|eai_again|econnreset|econnrefused|dns (failure|lookup failed)|fetch failed|network (error|unreachable)|connection (reset|refused|terminated|termination)|upstream connect error|socket hang up)\b/i.test(message))
+        return 'connection_failed';
+    if (/\b(claude|codex|cli|runtime|executable)\b.{0,60}\b(not found|not installed|unavailable|not executable)\b|\bspawn\s+\S+\s+(ENOENT|EACCES)\b/i.test(message))
+        return 'runtime_unavailable';
+    return undefined;
+}
+function recovery(code, kind) {
+    switch (code) {
+        case 'missing_credentials':
+            return kind === 'oauth'
+                ? 'sign_in'
+                : kind === 'api-key'
+                    ? 'update_credentials'
+                    : 'check_authentication';
+        case 'oauth_reauthentication_required':
+            return 'sign_in';
+        case 'api_credentials_rejected':
+            return 'update_credentials';
+        case 'authentication_rejected':
+            return 'check_authentication';
+        case 'invalid_provider_session':
+            return 'start_new_session';
+        case 'connection_failed':
+            return 'check_connection';
+        case 'execution_policy_denied':
+            return 'review_execution_policy';
+        case 'runtime_unavailable':
+            return 'repair_runtime';
+        case 'context_overflow':
+            return 'reduce_context';
+        case 'unknown':
+            return 'inspect_error';
+        default:
+            return 'retry_later';
+    }
+}
+/**
+ * Classify a caller-designated terminal failure without I/O or recovery actions.
+ * Public status and runtime readiness do not establish request authentication.
+ */
+function diagnoseProviderFailure(input) {
+    const codes = [];
+    const messages = [];
+    const visited = new Set();
+    const queue = [{ value: input.error, depth: 0 }];
+    let httpStatus;
+    let retry;
+    for (let index = 0; index < queue.length && index < 32; index++) {
+        const { value, depth } = queue[index];
+        if (typeof value === 'string') {
+            messages.push(text(value));
+            continue;
+        }
+        if (!value || typeof value !== 'object' || visited.has(value))
+            continue;
+        visited.add(value);
+        for (const key of ['code', 'type', 'name'])
+            codes.push(text(read(value, key)));
+        messages.push(text(read(value, 'message')));
+        for (const key of ['status', 'statusCode', 'httpStatus', 'status_code'])
+            httpStatus ??= statusNumber(read(value, key));
+        const headers = read(value, 'headers');
+        const header = typeof Headers !== 'undefined' && headers instanceof Headers
+            ? headers.get('retry-after')
+            : (read(headers, 'retry-after') ?? read(headers, 'Retry-After'));
+        retry ??= retryAfter(header);
+        const delay = read(value, 'retryAfterMs');
+        if (!retry &&
+            typeof delay === 'number' &&
+            Number.isFinite(delay) &&
+            delay >= 0 &&
+            delay <= Number.MAX_SAFE_INTEGER)
+            retry = { kind: 'delay', delayMs: delay };
+        // ENOENT by itself can be a missing document. Require a spawn operation.
+        if (read(value, 'code') === 'ENOENT' && /^spawn\b/.test(text(read(value, 'syscall'))))
+            codes.push('runtime_unavailable');
+        if (depth < 5) {
+            for (const key of ['error', 'cause', 'response', 'data', 'body']) {
+                let nested = read(value, key);
+                if (typeof nested === 'string' &&
+                    nested.length <= 16_384 &&
+                    nested.trim().startsWith('{')) {
+                    try {
+                        nested = JSON.parse(nested);
+                    }
+                    catch {
+                        /* Keep message evidence. */
+                    }
+                }
+                if (nested != null)
+                    queue.push({ value: nested, depth: depth + 1 });
+            }
+            const errors = read(value, 'errors');
+            if (Array.isArray(errors))
+                for (const error of errors.slice(0, 8))
+                    queue.push({ value: error, depth: depth + 1 });
+        }
+    }
+    let authentication;
+    const auth = input.authentication;
+    const checkedAt = timestamp(auth?.checkedAt);
+    if (auth &&
+        checkedAt &&
+        ['oauth', 'api-key', 'unknown'].includes(auth.credentialKind) &&
+        ['authenticated', 'missing', 'signed-out', 'expired', 'rejected', 'unknown'].includes(auth.state) &&
+        ['local-check', 'provider-response'].includes(auth.source)) {
+        authentication = {
+            credentialKind: auth.credentialKind,
+            state: auth.state,
+            checkedAt,
+            source: auth.source,
+        };
+    }
+    let diagnosis = codes
+        .map((code) => classifyCode(code, input.credentialKind))
+        .find((code) => code !== undefined);
+    let source = 'structured-error';
+    if (!diagnosis && httpStatus !== undefined) {
+        diagnosis = classifyStatus(httpStatus, input.credentialKind);
+        source = 'http-status';
+    }
+    if (!diagnosis) {
+        source = 'message';
+        for (const message of messages) {
+            // Message HTTP codes must have an HTTP/status context, not just a stray number.
+            const match = message.match(/\b(?:HTTP(?:\/\d(?:\.\d)?)?(?: error)?|(?:unexpected )?status(?: code)?|API error)\s*[:=]?\s*(\d{3})\b|\b(401|403|429|50[02349]|529)\s+(?:Unauthorized|Forbidden|Too Many Requests|Bad Gateway|Service Unavailable|Internal Server Error|Gateway Timeout)\b/i);
+            const status = match ? statusNumber(match[1] ?? match[2]) : undefined;
+            // A structured status cannot be replaced by a contradictory status in prose.
+            if (httpStatus === undefined && status !== undefined) {
+                httpStatus = status;
+                diagnosis = classifyStatus(status, input.credentialKind);
+            }
+            diagnosis ??= classifyMessage(message, input.credentialKind);
+            if (diagnosis)
+                break;
+        }
+    }
+    if (!diagnosis && authentication && authentication.credentialKind === input.credentialKind) {
+        if (authentication.state === 'missing' || authentication.state === 'signed-out')
+            diagnosis = 'missing_credentials';
+        if (authentication.state === 'expired' || authentication.state === 'rejected')
+            diagnosis = rejected(input.credentialKind);
+        if (diagnosis)
+            source = 'authentication-check';
+    }
+    diagnosis ??= 'unknown';
+    return {
+        provider: input.provider,
+        credentialKind: input.credentialKind,
+        diagnosis,
+        recovery: recovery(diagnosis, input.credentialKind),
+        evidence: diagnosis === 'unknown'
+            ? []
+            : [
+                {
+                    source,
+                    rule: diagnosis,
+                    ...(source === 'authentication-check'
+                        ? { checkedAt: authentication.checkedAt }
+                        : {}),
+                },
+            ],
+        ...(authentication ? { authentication } : {}),
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        ...(retry ? { retryAfter: retry } : {}),
+    };
+}

package/dist/providerServiceStatus.d.ts

@@ -0,0 +1,8 @@
+import type { AccountProviderId } from './providerIds';
+import type { FetchProviderServiceStatusOptions, ProviderServiceStatus } from './providerServiceStatusTypes';
+/**
+ * Fetch public vendor status without credentials, caching, polling, or retries.
+ * Incidents supplement a request diagnosis; they do not prove its cause. Consumers
+ * own freshness and component/endpoint correlation. Omitted incidents are null.
+ */
+export declare function fetchProviderServiceStatus(provider: AccountProviderId, { signal }?: FetchProviderServiceStatusOptions): Promise<ProviderServiceStatus>;

package/dist/providerServiceStatus.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchProviderServiceStatus = fetchProviderServiceStatus;
+const SOURCES = {
+    'claude-code': 'https://status.claude.com/api/v2/summary.json',
+    codex: 'https://status.openai.com/api/v2/summary.json',
+};
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid object');
+    return value;
+}
+function string(value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error('Invalid string');
+    return value;
+}
+function date(value) {
+    if (value === undefined || value === null)
+        return null;
+    const raw = string(value);
+    if (!/^\d{4}-\d{2}-\d{2}T/.test(raw) || !Number.isFinite(Date.parse(raw)))
+        throw new Error('Invalid date');
+    return raw;
+}
+function url(value) {
+    if (value === undefined || value === null)
+        return null;
+    const raw = string(value);
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        throw new Error('Invalid link');
+    return raw;
+}
+function array(value) {
+    if (!Array.isArray(value))
+        throw new Error('Invalid array');
+    return value;
+}
+function parseSummary(raw) {
+    const data = object(raw);
+    const status = object(data.status);
+    const severity = string(status.indicator);
+    if (!['none', 'minor', 'major', 'critical', 'maintenance'].includes(severity))
+        throw new Error('Invalid severity');
+    const components = array(data.components).map((rawComponent) => {
+        const component = object(rawComponent);
+        return {
+            id: string(component.id),
+            name: string(component.name),
+            status: string(component.status),
+        };
+    });
+    const incidents = data.incidents === undefined
+        ? null
+        : array(data.incidents)
+            .map((rawIncident) => {
+            const incident = object(rawIncident);
+            // Statuspage uses objects; its compatible feeds may supply component IDs directly.
+            const associations = incident.components ?? incident.component_ids;
+            return {
+                id: string(incident.id),
+                title: string(incident.name),
+                status: string(incident.status),
+                impact: string(incident.impact),
+                url: url(incident.shortlink ?? incident.url),
+                updatedAt: date(incident.updated_at),
+                componentIds: associations === undefined
+                    ? null
+                    : array(associations).map((component) => typeof component === 'string'
+                        ? string(component)
+                        : string(object(component).id)),
+            };
+        })
+            .filter((incident) => !['resolved', 'postmortem'].includes(incident.status.toLowerCase()));
+    return {
+        availability: 'observed',
+        severity: severity,
+        description: string(status.description),
+        providerUpdatedAt: date(object(data.page).updated_at),
+        components,
+        incidents,
+    };
+}
+/**
+ * Fetch public vendor status without credentials, caching, polling, or retries.
+ * Incidents supplement a request diagnosis; they do not prove its cause. Consumers
+ * own freshness and component/endpoint correlation. Omitted incidents are null.
+ */
+async function fetchProviderServiceStatus(provider, { signal } = {}) {
+    const sourceUrl = SOURCES[provider];
+    const observation = () => ({ provider, sourceUrl, checkedAt: new Date().toISOString() });
+    const unavailable = (reason, httpStatus) => ({
+        ...observation(),
+        availability: 'unavailable',
+        reason,
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+    });
+    if (signal?.aborted)
+        return unavailable('cancelled');
+    const controller = new AbortController();
+    let aborted;
+    let rejectAbort = () => { };
+    const abortPromise = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const abort = (reason) => {
+        if (aborted)
+            return;
+        aborted = reason;
+        controller.abort();
+        rejectAbort(new Error(reason));
+    };
+    const onCancel = () => abort('cancelled');
+    signal?.addEventListener('abort', onCancel, { once: true });
+    const timer = setTimeout(() => abort('timeout'), 10_000);
+    timer.unref?.();
+    try {
+        return await Promise.race([
+            abortPromise,
+            (async () => {
+                const response = await fetch(sourceUrl, { signal: controller.signal, credentials: 'omit' });
+                if (!response.ok)
+                    return unavailable('http_error', response.status);
+                let body;
+                try {
+                    body = await response.json();
+                }
+                catch (error) {
+                    return unavailable(aborted ?? (error instanceof SyntaxError ? 'invalid_response' : 'network_error'));
+                }
+                try {
+                    return { ...observation(), ...parseSummary(body) };
+                }
+                catch {
+                    return unavailable('invalid_response');
+                }
+            })(),
+        ]);
+    }
+    catch {
+        return unavailable(aborted ?? 'network_error');
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onCancel);
+    }
+}

package/dist/providerServiceStatusTypes.d.ts

@@ -0,0 +1,43 @@
+import type { AccountProviderId } from './providerIds';
+export type ProviderServiceSeverity = 'none' | 'minor' | 'major' | 'critical' | 'maintenance';
+export interface ProviderServiceComponent {
+    id: string;
+    name: string;
+    status: string;
+}
+export interface ProviderServiceIncident {
+    id: string;
+    title: string;
+    status: string;
+    impact: string;
+    url: string | null;
+    updatedAt: string | null;
+    /** null means associations were not supplied; [] means explicitly no associations. */
+    componentIds: string[] | null;
+}
+export type ProviderServiceStatusFailureReason = 'http_error' | 'network_error' | 'timeout' | 'cancelled' | 'invalid_response';
+interface ProviderServiceObservation {
+    provider: AccountProviderId;
+    /** Completion time of this check, independent of the provider's update time. */
+    checkedAt: string;
+    sourceUrl: string;
+}
+export interface ObservedProviderServiceStatus extends ProviderServiceObservation {
+    availability: 'observed';
+    severity: ProviderServiceSeverity;
+    description: string;
+    providerUpdatedAt: string | null;
+    components: ProviderServiceComponent[];
+    /** null means the feed omitted incident evidence, not that there are no incidents. */
+    incidents: ProviderServiceIncident[] | null;
+}
+export interface UnavailableProviderServiceStatus extends ProviderServiceObservation {
+    availability: 'unavailable';
+    reason: ProviderServiceStatusFailureReason;
+    httpStatus?: number;
+}
+export type ProviderServiceStatus = ObservedProviderServiceStatus | UnavailableProviderServiceStatus;
+export interface FetchProviderServiceStatusOptions {
+    signal?: AbortSignal;
+}
+export {};

package/dist/providerServiceStatusTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/providerStatus.d.ts

@@ -4,6 +4,7 @@
  * Supports both status.claude.com and status.openai.com (same API format).
  * Polling / eventing is the caller's responsibility.
  */
+/** Legacy projection. Use ProviderServiceStatus for explicit availability evidence. */
 export interface ProviderStatusState {
     indicator: 'none' | 'minor' | 'major' | 'critical';
     description: string;
@@ -19,15 +20,19 @@ export interface ProviderStatusState {
     } | null;
     updatedAt: string;
 }
+/** Compatibility projection only; it cannot express evidence availability. */
+export declare function toLegacyProviderStatus(status: import('./providerServiceStatusTypes').ProviderServiceStatus): ProviderStatusState;
 /**
  * Fetch current Claude API status from status.claude.com.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
+ * Consumers requiring reliable availability semantics should use fetchProviderServiceStatus.
  */
 export declare function fetchProviderStatus(): Promise<ProviderStatusState>;
 /**
  * Fetch current OpenAI API status from status.openai.com.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
+ * Consumers requiring reliable availability semantics should use fetchProviderServiceStatus.
  */
 export declare function fetchOpenAIStatus(): Promise<ProviderStatusState>;

package/dist/providerStatus.js

@@ -6,8 +6,38 @@
  * Polling / eventing is the caller's responsibility.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLegacyProviderStatus = toLegacyProviderStatus;
 exports.fetchProviderStatus = fetchProviderStatus;
 exports.fetchOpenAIStatus = fetchOpenAIStatus;
+/** Compatibility projection only; it cannot express evidence availability. */
+function toLegacyProviderStatus(status) {
+    if (status.availability === 'unavailable') {
+        return {
+            indicator: 'none',
+            description: 'Status unavailable',
+            affectedComponents: [],
+            activeIncident: null,
+            updatedAt: status.checkedAt,
+        };
+    }
+    const incident = status.incidents?.[0];
+    return {
+        indicator: status.severity === 'maintenance' ? 'minor' : status.severity,
+        description: status.description,
+        affectedComponents: status.components
+            .filter((component) => component.status !== 'operational')
+            .map(({ name, status }) => ({ name, status })),
+        activeIncident: incident
+            ? {
+                name: incident.title,
+                impact: incident.impact,
+                shortlink: incident.url ?? '',
+                updatedAt: incident.updatedAt ?? '',
+            }
+            : null,
+        updatedAt: status.providerUpdatedAt ?? '',
+    };
+}
 const CLAUDE_BASE = 'https://status.claude.com';
 const OPENAI_BASE = 'https://status.openai.com';
 function fallbackState() {
@@ -76,6 +106,7 @@ async function fetchWithTimeout(url) {
  * Fetch current Claude API status from status.claude.com.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
+ * Consumers requiring reliable availability semantics should use fetchProviderServiceStatus.
  */
 async function fetchProviderStatus() {
     return fetchStatusPage(CLAUDE_BASE);
@@ -84,6 +115,7 @@ async function fetchProviderStatus() {
  * Fetch current OpenAI API status from status.openai.com.
  *
  * Single-shot — caller wraps in polling loop, EventEmitter, or interval.
+ * Consumers requiring reliable availability semantics should use fetchProviderServiceStatus.
  */
 async function fetchOpenAIStatus() {
     return fetchStatusPage(OPENAI_BASE);

package/package.json

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