@omnicross/core 0.1.5 → 0.1.7

package/dist/pipeline/BoundAccountSelectionError.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Secret-free failure contract for a strict outbound subscription-account
+ * binding. The selector throws this value only when an endpoint explicitly (or
+ * by the migrated default) requires its bound account to serve the request.
+ */
+/** Persisted policy for an endpoint that binds a subscription account. */
+type BoundAccountFallbackPolicy = 'strict' | 'pool';
+/** Bounded reasons a strict bound account can refuse a request. */
+type BoundAccountSelectionFailureReason = 'unavailable' | 'not-found' | 'disabled' | 'unhealthy' | 'model-incompatible' | 'allowance-paused' | 'empty-token';
+/** Return the fixed public message for a validated failure reason. */
+declare function boundAccountSelectionMessage(reason: BoundAccountSelectionFailureReason): string;
+/**
+ * Stable, non-secret error thrown by strict account selection. Account ids and
+ * token material are intentionally absent from both the message and the wire
+ * projection; the reason is a small fixed vocabulary.
+ */
+declare class BoundAccountSelectionError extends Error {
+    readonly providerId: string;
+    readonly reason: BoundAccountSelectionFailureReason;
+    readonly resumeAt?: string | undefined;
+    readonly code: "bound_account_unavailable";
+    readonly status: 429 | 503;
+    constructor(providerId: string, reason: BoundAccountSelectionFailureReason, resumeAt?: string | undefined);
+}
+/** Structural guard that survives package/bundle boundaries. */
+declare function isBoundAccountSelectionError(error: unknown): error is BoundAccountSelectionError;
+
+export { type BoundAccountFallbackPolicy, BoundAccountSelectionError, type BoundAccountSelectionFailureReason, boundAccountSelectionMessage, isBoundAccountSelectionError };

package/dist/pipeline/BoundAccountSelectionError.js

@@ -0,0 +1,10 @@
+import {
+  BoundAccountSelectionError,
+  boundAccountSelectionMessage,
+  isBoundAccountSelectionError
+} from "../chunk-2JYRIADS.js";
+export {
+  BoundAccountSelectionError,
+  boundAccountSelectionMessage,
+  isBoundAccountSelectionError
+};

package/dist/pipeline/LlmConfigProviderAuth.d.cts

@@ -2,6 +2,7 @@ import { LLMProvider } from '@omnicross/contracts/llm-config';
 import { ApiKeyPoolService } from '../completion/ApiKeyPoolService.cjs';
 import { AuthSource, AuthApplyHints, AuthResultOutcome } from './AuthSource.cjs';
 import '../logger-4GvQNzhE.cjs';
+import './BoundAccountSelectionError.cjs';
 
 /**
  * LlmConfigProviderAuth — `AuthSource` for LLM-config provider rows.

package/dist/pipeline/LlmConfigProviderAuth.d.ts

@@ -2,6 +2,7 @@ import { LLMProvider } from '@omnicross/contracts/llm-config';
 import { ApiKeyPoolService } from '../completion/ApiKeyPoolService.js';
 import { AuthSource, AuthApplyHints, AuthResultOutcome } from './AuthSource.js';
 import '../logger-4GvQNzhE.js';
+import './BoundAccountSelectionError.js';
 
 /**
  * LlmConfigProviderAuth — `AuthSource` for LLM-config provider rows.

package/dist/pipeline/ServerOverloadCounter.cjs

@@ -0,0 +1,16 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+var _chunkOTZC4TNHcjs = require('../chunk-OTZC4TNH.cjs');
+
+
+
+
+
+
+
+exports.OVERLOAD_ENTRY_TTL_MS = _chunkOTZC4TNHcjs.OVERLOAD_ENTRY_TTL_MS; exports.OVERLOAD_RECENT_LIMIT = _chunkOTZC4TNHcjs.OVERLOAD_RECENT_LIMIT; exports.ServerOverloadCounterStore = _chunkOTZC4TNHcjs.ServerOverloadCounterStore; exports.__resetSharedOverloadCounterForTests = _chunkOTZC4TNHcjs.__resetSharedOverloadCounterForTests; exports.getSharedOverloadCounter = _chunkOTZC4TNHcjs.getSharedOverloadCounter; exports.setSharedOverloadCounter = _chunkOTZC4TNHcjs.setSharedOverloadCounter;

package/dist/pipeline/ServerOverloadCounter.d.cts

@@ -0,0 +1,77 @@
+import { AccountRouteEndpoint } from './AccountRouteActivity.cjs';
+
+/**
+ * ServerOverloadCounter — a bounded, metadata-only tally of Codex server-
+ * overload events (`response.failed` with `error.code` `server_is_overloaded` /
+ * `slow_down`) per provider+account+endpoint.
+ *
+ * WHY a dedicated store (not derived from {@link AccountRouteActivity}): those
+ * 200-status overloads are invisible at the route-activity HTTP-status layer, and
+ * the route-activity ring (300 rows) can be pushed out by normal traffic before
+ * an operator notices. This counter ACCUMULATES across the ring and keeps a
+ * bounded recent-timestamp ring for a trend sparkline, so "how often is account X
+ * being overloaded, and is it worsening" stays answerable.
+ *
+ * Overload is account-INDEPENDENT server capacity (retrying on another account is
+ * pointless), so — unlike {@link SubscriptionAccountHealth} — this store only
+ * OBSERVES; it never gates scheduling. It carries no secrets, only counts + epoch
+ * timestamps. In-memory (cleared on restart), same as the other pipeline stores.
+ *
+ * Shaped like `SubscriptionAccountHealth`: an in-memory `Map`, an injectable
+ * `now` clock, no external deps, opaque `providerId\0accountId\0endpoint` keys.
+ *
+ * @module pipeline/ServerOverloadCounter
+ */
+
+/** Bounded recent-event ring per entry — the sparkline's data source. */
+declare const OVERLOAD_RECENT_LIMIT = 64;
+/**
+ * Entries with no event in this window are pruned on read, so the map cannot
+ * grow unbounded across a long-lived process with many transient accounts.
+ */
+declare const OVERLOAD_ENTRY_TTL_MS: number;
+interface OverloadRecordInput {
+    providerId: string;
+    accountId: string;
+    endpoint: AccountRouteEndpoint;
+    /** Epoch-ms of the event. Omit to use the clock default. */
+    now?: number;
+}
+interface OverloadCounterEntry {
+    providerId: string;
+    accountId: string;
+    endpoint: AccountRouteEndpoint;
+    /** Lifetime count of overload events for this key (since first observed). */
+    count: number;
+    firstTs: number;
+    lastTs: number;
+    /** Most-recent-first epoch-ms events, capped at {@link OVERLOAD_RECENT_LIMIT}. */
+    recent: number[];
+}
+interface OverloadCounterQuery {
+    providerId?: string;
+    accountId?: string;
+}
+declare class ServerOverloadCounterStore {
+    private readonly entries;
+    /**
+     * Record one overload event. Creates the entry on first sight, then bumps
+     * `count`, `lastTs`, and prepends the event to the bounded `recent` ring.
+     */
+    recordOverload(input: OverloadRecordInput, now?: number): OverloadCounterEntry;
+    /**
+     * Snapshot all (optionally filtered) entries, pruning stale ones first. Returns
+     * copies — callers (admin API → JSON) never see the live mutable entries.
+     */
+    list(query?: OverloadCounterQuery, now?: number): OverloadCounterEntry[];
+    clear(): void;
+}
+declare function getSharedOverloadCounter(): ServerOverloadCounterStore;
+/**
+ * TEST SEAM — swap the singleton (e.g. with a fresh instance). Mirrors the
+ * `setShared…`/`__reset…ForTests` discipline of the sibling pipeline stores.
+ */
+declare function setSharedOverloadCounter(instance: ServerOverloadCounterStore): void;
+declare function __resetSharedOverloadCounterForTests(): void;
+
+export { OVERLOAD_ENTRY_TTL_MS, OVERLOAD_RECENT_LIMIT, type OverloadCounterEntry, type OverloadCounterQuery, type OverloadRecordInput, ServerOverloadCounterStore, __resetSharedOverloadCounterForTests, getSharedOverloadCounter, setSharedOverloadCounter };

package/dist/pipeline/ServerOverloadCounter.d.ts

@@ -0,0 +1,77 @@
+import { AccountRouteEndpoint } from './AccountRouteActivity.js';
+
+/**
+ * ServerOverloadCounter — a bounded, metadata-only tally of Codex server-
+ * overload events (`response.failed` with `error.code` `server_is_overloaded` /
+ * `slow_down`) per provider+account+endpoint.
+ *
+ * WHY a dedicated store (not derived from {@link AccountRouteActivity}): those
+ * 200-status overloads are invisible at the route-activity HTTP-status layer, and
+ * the route-activity ring (300 rows) can be pushed out by normal traffic before
+ * an operator notices. This counter ACCUMULATES across the ring and keeps a
+ * bounded recent-timestamp ring for a trend sparkline, so "how often is account X
+ * being overloaded, and is it worsening" stays answerable.
+ *
+ * Overload is account-INDEPENDENT server capacity (retrying on another account is
+ * pointless), so — unlike {@link SubscriptionAccountHealth} — this store only
+ * OBSERVES; it never gates scheduling. It carries no secrets, only counts + epoch
+ * timestamps. In-memory (cleared on restart), same as the other pipeline stores.
+ *
+ * Shaped like `SubscriptionAccountHealth`: an in-memory `Map`, an injectable
+ * `now` clock, no external deps, opaque `providerId\0accountId\0endpoint` keys.
+ *
+ * @module pipeline/ServerOverloadCounter
+ */
+
+/** Bounded recent-event ring per entry — the sparkline's data source. */
+declare const OVERLOAD_RECENT_LIMIT = 64;
+/**
+ * Entries with no event in this window are pruned on read, so the map cannot
+ * grow unbounded across a long-lived process with many transient accounts.
+ */
+declare const OVERLOAD_ENTRY_TTL_MS: number;
+interface OverloadRecordInput {
+    providerId: string;
+    accountId: string;
+    endpoint: AccountRouteEndpoint;
+    /** Epoch-ms of the event. Omit to use the clock default. */
+    now?: number;
+}
+interface OverloadCounterEntry {
+    providerId: string;
+    accountId: string;
+    endpoint: AccountRouteEndpoint;
+    /** Lifetime count of overload events for this key (since first observed). */
+    count: number;
+    firstTs: number;
+    lastTs: number;
+    /** Most-recent-first epoch-ms events, capped at {@link OVERLOAD_RECENT_LIMIT}. */
+    recent: number[];
+}
+interface OverloadCounterQuery {
+    providerId?: string;
+    accountId?: string;
+}
+declare class ServerOverloadCounterStore {
+    private readonly entries;
+    /**
+     * Record one overload event. Creates the entry on first sight, then bumps
+     * `count`, `lastTs`, and prepends the event to the bounded `recent` ring.
+     */
+    recordOverload(input: OverloadRecordInput, now?: number): OverloadCounterEntry;
+    /**
+     * Snapshot all (optionally filtered) entries, pruning stale ones first. Returns
+     * copies — callers (admin API → JSON) never see the live mutable entries.
+     */
+    list(query?: OverloadCounterQuery, now?: number): OverloadCounterEntry[];
+    clear(): void;
+}
+declare function getSharedOverloadCounter(): ServerOverloadCounterStore;
+/**
+ * TEST SEAM — swap the singleton (e.g. with a fresh instance). Mirrors the
+ * `setShared…`/`__reset…ForTests` discipline of the sibling pipeline stores.
+ */
+declare function setSharedOverloadCounter(instance: ServerOverloadCounterStore): void;
+declare function __resetSharedOverloadCounterForTests(): void;
+
+export { OVERLOAD_ENTRY_TTL_MS, OVERLOAD_RECENT_LIMIT, type OverloadCounterEntry, type OverloadCounterQuery, type OverloadRecordInput, ServerOverloadCounterStore, __resetSharedOverloadCounterForTests, getSharedOverloadCounter, setSharedOverloadCounter };

package/dist/pipeline/ServerOverloadCounter.js

@@ -0,0 +1,16 @@
+import {
+  OVERLOAD_ENTRY_TTL_MS,
+  OVERLOAD_RECENT_LIMIT,
+  ServerOverloadCounterStore,
+  __resetSharedOverloadCounterForTests,
+  getSharedOverloadCounter,
+  setSharedOverloadCounter
+} from "../chunk-PO3XB56Z.js";
+export {
+  OVERLOAD_ENTRY_TTL_MS,
+  OVERLOAD_RECENT_LIMIT,
+  ServerOverloadCounterStore,
+  __resetSharedOverloadCounterForTests,
+  getSharedOverloadCounter,
+  setSharedOverloadCounter
+};

package/dist/pipeline/SubscriptionAccountHealth.cjs

@@ -8,9 +8,9 @@
 
 
 
-var _chunkVQY5W4YWcjs = require('../chunk-VQY5W4YW.cjs');
 
 
+var _chunkYWL7YZWScjs = require('../chunk-YWL7YZWS.cjs');
 
 
 
@@ -19,4 +19,8 @@ var _chunkVQY5W4YWcjs = require('../chunk-VQY5W4YW.cjs');
 
 
 
-exports.AUTH_ERROR_TTL_MS = _chunkVQY5W4YWcjs.AUTH_ERROR_TTL_MS; exports.OVERLOAD_ENABLED_DEFAULT = _chunkVQY5W4YWcjs.OVERLOAD_ENABLED_DEFAULT; exports.OVERLOAD_TTL_MS = _chunkVQY5W4YWcjs.OVERLOAD_TTL_MS; exports.SERVER_ERROR_TTL_MS = _chunkVQY5W4YWcjs.SERVER_ERROR_TTL_MS; exports.SubscriptionAccountHealth = _chunkVQY5W4YWcjs.SubscriptionAccountHealth; exports.__resetSharedAccountHealthForTests = _chunkVQY5W4YWcjs.__resetSharedAccountHealthForTests; exports.getSharedAccountHealth = _chunkVQY5W4YWcjs.getSharedAccountHealth; exports.resolveResetSeconds = _chunkVQY5W4YWcjs.resolveResetSeconds; exports.setSharedAccountHealth = _chunkVQY5W4YWcjs.setSharedAccountHealth;
+
+
+
+
+exports.ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT = _chunkYWL7YZWScjs.ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT; exports.AUTH_ERROR_TTL_MS = _chunkYWL7YZWScjs.AUTH_ERROR_TTL_MS; exports.MAX_QUOTA_COOLDOWN_MS = _chunkYWL7YZWScjs.MAX_QUOTA_COOLDOWN_MS; exports.OVERLOAD_ENABLED_DEFAULT = _chunkYWL7YZWScjs.OVERLOAD_ENABLED_DEFAULT; exports.OVERLOAD_TTL_MS = _chunkYWL7YZWScjs.OVERLOAD_TTL_MS; exports.SERVER_ERROR_TTL_MS = _chunkYWL7YZWScjs.SERVER_ERROR_TTL_MS; exports.SubscriptionAccountHealth = _chunkYWL7YZWScjs.SubscriptionAccountHealth; exports.__resetSharedAccountHealthForTests = _chunkYWL7YZWScjs.__resetSharedAccountHealthForTests; exports.getSharedAccountHealth = _chunkYWL7YZWScjs.getSharedAccountHealth; exports.resolveResetSeconds = _chunkYWL7YZWScjs.resolveResetSeconds; exports.setSharedAccountHealth = _chunkYWL7YZWScjs.setSharedAccountHealth;

package/dist/pipeline/SubscriptionAccountHealth.d.cts

@@ -27,10 +27,16 @@
 declare const OVERLOAD_TTL_MS: number;
 /** 529 overload cooldown enabled by default (LEAD OQ1). */
 declare const OVERLOAD_ENABLED_DEFAULT = true;
-/** Transient cooldown for a final-401 / plain-403 (CRS auth_error 1800s). */
+/** Transient cooldown for a final 401 or non-ban 403 response. */
 declare const AUTH_ERROR_TTL_MS: number;
-/** Transient cooldown for a 5xx / thrown network failure (CRS server_error 300s). */
+/** Transient cooldown for a 5xx response or network failure. */
 declare const SERVER_ERROR_TTL_MS: number;
+/**
+ * Hard cap on a quota-exhaustion cooldown (the weekly usage window is ~1 week).
+ * A parsed/supplied deadline farther than this into the future is clamped, so a
+ * bogus parse can never strand an account indefinitely.
+ */
+declare const MAX_QUOTA_COOLDOWN_MS: number;
 /** Per-account health record (all timers are epoch ms). Absent fields ⇒ healthy. */
 interface HealthRecord {
     /** From a 429 authoritative reset header — rate-limited until this instant. */
@@ -39,11 +45,20 @@ interface HealthRecord {
     overloadUntil?: number;
     /** From a final-401 / plain-403 / 5xx / thrown — transient cooldown until this. */
     tempUnavailableUntil?: number;
+    /**
+     * From a detected quota/usage-limit error (e.g. Codex weekly window exhausted).
+     * Intentionally NOT cleared by a 2xx: while the account's credits/window are
+     * exhausted, in-flight sessions on the SAME account keep returning 2xx (Codex
+     * does not kill them mid-session), which would otherwise immediately heal a
+     * transient/rate-limit mark and re-strand every NEW session onto this account.
+     * Self-heals only when the deadline elapses.
+     */
+    quotaExhaustedUntil?: number;
     /** From a 403-ban — permanent, self-heal never clears it. */
     blocked?: boolean;
 }
 /** The coarse health state surfaced to the admin accounts view (secret-free). */
-type AccountHealthState = 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+type AccountHealthState = 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'quota_exhausted' | 'blocked';
 /** Admin-facing status projection for one account. */
 interface AccountHealthStatus {
     state: AccountHealthState;
@@ -68,7 +83,7 @@ interface AccountRecoveryEvent {
 /** A recovery listener (fire-and-forget; the emitter never awaits it). */
 type AccountRecoveryListener = (event: AccountRecoveryEvent) => void;
 /** The coarse anomaly state an account transitioned into (secret-free). */
-type AccountAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+type AccountAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded' | 'quota_exhausted';
 /**
  * The anomaly signal emitted when a HEALTHY account transitions to unhealthy —
  * the additive union #5 (webhooks) consumes, which this tracker's frozen `kind`
@@ -89,6 +104,30 @@ interface AccountAnomalyEvent {
 }
 /** An anomaly listener (fire-and-forget; the emitter never awaits it). */
 type AccountAnomalyListener = (event: AccountAnomalyEvent) => void;
+/**
+ * Admin-readable projection of the existing health event stream. It is kept in
+ * the tracker itself so webhooks and diagnostics consume the same edge events;
+ * this is not a second marking/event mechanism. Only opaque ids, timestamps,
+ * and coarse states are retained.
+ */
+type AccountHealthDiagnostic = {
+    kind: 'health-anomaly';
+    providerId: string;
+    accountId: string;
+    at: number;
+    state: AccountAnomalyState;
+} | {
+    kind: 'health-recovery';
+    providerId: string;
+    accountId: string;
+    at: number;
+};
+interface AccountHealthDiagnosticFilter {
+    providerId?: string;
+    accountId?: string;
+    limit?: number;
+}
+declare const ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT = 200;
 /** The inputs one upstream attempt contributes to health marking (design D3). */
 interface RecordUpstreamOutcomeInput {
     /** The final HTTP status, or `null` for a thrown / network failure. */
@@ -134,6 +173,7 @@ declare class SubscriptionAccountHealth {
     private readonly records;
     private readonly listeners;
     private readonly anomalyListeners;
+    private readonly diagnostics;
     private readonly now;
     private overloadEnabled;
     private overloadTtlMs;
@@ -150,14 +190,14 @@ declare class SubscriptionAccountHealth {
     configure(opts: Pick<SubscriptionAccountHealthOptions, 'overloadEnabled' | 'overloadTtlMs' | 'authErrorTtlMs' | 'serverErrorTtlMs'>): void;
     /**
      * Whether an account may be scheduled RIGHT NOW. `blocked` → false; any timer
-     * still in the future → false. Expired timers are lazily deleted on read (CRS
-     * lazy-clear parity) so an elapsed cooldown restores the account WITHOUT a
+     * still in the future → false. Expired timers are lazily deleted on read so
+     * an elapsed cooldown restores the account WITHOUT a
      * timer — but the recovery SIGNAL is the sweeper's job (`sweepRecoveries`), so
      * this read never emits (correctness is independent of the tick).
      */
     isSchedulable(providerId: string, accountId: string, now?: number): boolean;
     /**
-     * The single marking entry point (design D3). Faithful to CRS status semantics:
+     * The single marking entry point (design D3):
      *  - 429 + authoritative reset → `rateLimitEndAt`; a non-claude 429 may use
      *    `retryAfterSeconds`; a bare 429 (no resolvable reset) is NOT marked;
      *  - 529 → `overloadUntil` (gated by `overloadEnabled`);
@@ -167,6 +207,20 @@ declare class SubscriptionAccountHealth {
      *  - 2xx → clear rate-limit + transient state (keep `blocked`).
      */
     recordUpstreamOutcome(providerId: string, accountId: string, input: RecordUpstreamOutcomeInput): void;
+    /**
+     * Mark an account quota/usage-exhausted until `untilEpochMs` (the Codex weekly
+     * usage-limit wall). Unlike the status-driven timers set by
+     * {@link recordUpstreamOutcome}, this mark is NOT cleared by a 2xx: in-flight
+     * sessions on the same account keep succeeding after the window is exhausted,
+     * so a traffic-driven clear would re-strand every NEW session onto this
+     * account. It excludes the account from NEW-session selection until the
+     * deadline elapses (existing sessions are unaffected — they already hold their
+     * token). Self-heals lazily on read and via {@link sweepRecoveries}.
+     * `untilEpochMs` is clamped to {@link MAX_QUOTA_COOLDOWN_MS}; an already-elapsed
+     * deadline is a no-op. Emits a `quota_exhausted` anomaly on the healthy→
+     * unhealthy edge.
+     */
+    markQuotaExhausted(providerId: string, accountId: string, untilEpochMs: number, now?: number): void;
     /** Whether a record is unhealthy at `now`: blocked, or any timer still future. */
     private isUnhealthyAt;
     /**
@@ -194,6 +248,8 @@ declare class SubscriptionAccountHealth {
     sweepRecoveries(now?: number): AccountRecoveryEvent[];
     /** Admin-facing coarse status + cooldown-until for one account (secret-free). */
     getStatus(providerId: string, accountId: string, now?: number): AccountHealthStatus;
+    /** Return newest-first, bounded, secret-free health edge diagnostics. */
+    getDiagnostics(filter?: AccountHealthDiagnosticFilter): AccountHealthDiagnostic[];
     /**
      * Register a recovery listener (the OQ3 seam #5 webhooks + #8 health-cron
      * consume). Returns an unsubscribe function. Two edges fire it:
@@ -216,6 +272,7 @@ declare class SubscriptionAccountHealth {
      */
     onAnomaly(listener: AccountAnomalyListener): () => void;
     private emitAnomaly;
+    private recordDiagnostic;
     /**
      * Delete every EXPIRED timer field on the record in place; return whether any
      * timer is STILL active (in the future). `blocked` is not a timer and is left
@@ -232,4 +289,4 @@ declare function setSharedAccountHealth(instance: SubscriptionAccountHealth): vo
 /** Reset the shared singleton (tests / teardown only). */
 declare function __resetSharedAccountHealthForTests(): void;
 
-export { AUTH_ERROR_TTL_MS, type AccountAnomalyEvent, type AccountAnomalyListener, type AccountAnomalyState, type AccountHealthState, type AccountHealthStatus, type AccountRecoveryEvent, type AccountRecoveryListener, type HeadersLike, type HealthRecord, OVERLOAD_ENABLED_DEFAULT, OVERLOAD_TTL_MS, type RecordUpstreamOutcomeInput, SERVER_ERROR_TTL_MS, SubscriptionAccountHealth, type SubscriptionAccountHealthOptions, __resetSharedAccountHealthForTests, getSharedAccountHealth, resolveResetSeconds, setSharedAccountHealth };
+export { ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT, AUTH_ERROR_TTL_MS, type AccountAnomalyEvent, type AccountAnomalyListener, type AccountAnomalyState, type AccountHealthDiagnostic, type AccountHealthDiagnosticFilter, type AccountHealthState, type AccountHealthStatus, type AccountRecoveryEvent, type AccountRecoveryListener, type HeadersLike, type HealthRecord, MAX_QUOTA_COOLDOWN_MS, OVERLOAD_ENABLED_DEFAULT, OVERLOAD_TTL_MS, type RecordUpstreamOutcomeInput, SERVER_ERROR_TTL_MS, SubscriptionAccountHealth, type SubscriptionAccountHealthOptions, __resetSharedAccountHealthForTests, getSharedAccountHealth, resolveResetSeconds, setSharedAccountHealth };

package/dist/pipeline/SubscriptionAccountHealth.d.ts

@@ -27,10 +27,16 @@
 declare const OVERLOAD_TTL_MS: number;
 /** 529 overload cooldown enabled by default (LEAD OQ1). */
 declare const OVERLOAD_ENABLED_DEFAULT = true;
-/** Transient cooldown for a final-401 / plain-403 (CRS auth_error 1800s). */
+/** Transient cooldown for a final 401 or non-ban 403 response. */
 declare const AUTH_ERROR_TTL_MS: number;
-/** Transient cooldown for a 5xx / thrown network failure (CRS server_error 300s). */
+/** Transient cooldown for a 5xx response or network failure. */
 declare const SERVER_ERROR_TTL_MS: number;
+/**
+ * Hard cap on a quota-exhaustion cooldown (the weekly usage window is ~1 week).
+ * A parsed/supplied deadline farther than this into the future is clamped, so a
+ * bogus parse can never strand an account indefinitely.
+ */
+declare const MAX_QUOTA_COOLDOWN_MS: number;
 /** Per-account health record (all timers are epoch ms). Absent fields ⇒ healthy. */
 interface HealthRecord {
     /** From a 429 authoritative reset header — rate-limited until this instant. */
@@ -39,11 +45,20 @@ interface HealthRecord {
     overloadUntil?: number;
     /** From a final-401 / plain-403 / 5xx / thrown — transient cooldown until this. */
     tempUnavailableUntil?: number;
+    /**
+     * From a detected quota/usage-limit error (e.g. Codex weekly window exhausted).
+     * Intentionally NOT cleared by a 2xx: while the account's credits/window are
+     * exhausted, in-flight sessions on the SAME account keep returning 2xx (Codex
+     * does not kill them mid-session), which would otherwise immediately heal a
+     * transient/rate-limit mark and re-strand every NEW session onto this account.
+     * Self-heals only when the deadline elapses.
+     */
+    quotaExhaustedUntil?: number;
     /** From a 403-ban — permanent, self-heal never clears it. */
     blocked?: boolean;
 }
 /** The coarse health state surfaced to the admin accounts view (secret-free). */
-type AccountHealthState = 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'blocked';
+type AccountHealthState = 'healthy' | 'rate_limited' | 'overloaded' | 'transient' | 'quota_exhausted' | 'blocked';
 /** Admin-facing status projection for one account. */
 interface AccountHealthStatus {
     state: AccountHealthState;
@@ -68,7 +83,7 @@ interface AccountRecoveryEvent {
 /** A recovery listener (fire-and-forget; the emitter never awaits it). */
 type AccountRecoveryListener = (event: AccountRecoveryEvent) => void;
 /** The coarse anomaly state an account transitioned into (secret-free). */
-type AccountAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded';
+type AccountAnomalyState = 'blocked' | 'unauthorized' | 'rate_limited' | 'overloaded' | 'quota_exhausted';
 /**
  * The anomaly signal emitted when a HEALTHY account transitions to unhealthy —
  * the additive union #5 (webhooks) consumes, which this tracker's frozen `kind`
@@ -89,6 +104,30 @@ interface AccountAnomalyEvent {
 }
 /** An anomaly listener (fire-and-forget; the emitter never awaits it). */
 type AccountAnomalyListener = (event: AccountAnomalyEvent) => void;
+/**
+ * Admin-readable projection of the existing health event stream. It is kept in
+ * the tracker itself so webhooks and diagnostics consume the same edge events;
+ * this is not a second marking/event mechanism. Only opaque ids, timestamps,
+ * and coarse states are retained.
+ */
+type AccountHealthDiagnostic = {
+    kind: 'health-anomaly';
+    providerId: string;
+    accountId: string;
+    at: number;
+    state: AccountAnomalyState;
+} | {
+    kind: 'health-recovery';
+    providerId: string;
+    accountId: string;
+    at: number;
+};
+interface AccountHealthDiagnosticFilter {
+    providerId?: string;
+    accountId?: string;
+    limit?: number;
+}
+declare const ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT = 200;
 /** The inputs one upstream attempt contributes to health marking (design D3). */
 interface RecordUpstreamOutcomeInput {
     /** The final HTTP status, or `null` for a thrown / network failure. */
@@ -134,6 +173,7 @@ declare class SubscriptionAccountHealth {
     private readonly records;
     private readonly listeners;
     private readonly anomalyListeners;
+    private readonly diagnostics;
     private readonly now;
     private overloadEnabled;
     private overloadTtlMs;
@@ -150,14 +190,14 @@ declare class SubscriptionAccountHealth {
     configure(opts: Pick<SubscriptionAccountHealthOptions, 'overloadEnabled' | 'overloadTtlMs' | 'authErrorTtlMs' | 'serverErrorTtlMs'>): void;
     /**
      * Whether an account may be scheduled RIGHT NOW. `blocked` → false; any timer
-     * still in the future → false. Expired timers are lazily deleted on read (CRS
-     * lazy-clear parity) so an elapsed cooldown restores the account WITHOUT a
+     * still in the future → false. Expired timers are lazily deleted on read so
+     * an elapsed cooldown restores the account WITHOUT a
      * timer — but the recovery SIGNAL is the sweeper's job (`sweepRecoveries`), so
      * this read never emits (correctness is independent of the tick).
      */
     isSchedulable(providerId: string, accountId: string, now?: number): boolean;
     /**
-     * The single marking entry point (design D3). Faithful to CRS status semantics:
+     * The single marking entry point (design D3):
      *  - 429 + authoritative reset → `rateLimitEndAt`; a non-claude 429 may use
      *    `retryAfterSeconds`; a bare 429 (no resolvable reset) is NOT marked;
      *  - 529 → `overloadUntil` (gated by `overloadEnabled`);
@@ -167,6 +207,20 @@ declare class SubscriptionAccountHealth {
      *  - 2xx → clear rate-limit + transient state (keep `blocked`).
      */
     recordUpstreamOutcome(providerId: string, accountId: string, input: RecordUpstreamOutcomeInput): void;
+    /**
+     * Mark an account quota/usage-exhausted until `untilEpochMs` (the Codex weekly
+     * usage-limit wall). Unlike the status-driven timers set by
+     * {@link recordUpstreamOutcome}, this mark is NOT cleared by a 2xx: in-flight
+     * sessions on the same account keep succeeding after the window is exhausted,
+     * so a traffic-driven clear would re-strand every NEW session onto this
+     * account. It excludes the account from NEW-session selection until the
+     * deadline elapses (existing sessions are unaffected — they already hold their
+     * token). Self-heals lazily on read and via {@link sweepRecoveries}.
+     * `untilEpochMs` is clamped to {@link MAX_QUOTA_COOLDOWN_MS}; an already-elapsed
+     * deadline is a no-op. Emits a `quota_exhausted` anomaly on the healthy→
+     * unhealthy edge.
+     */
+    markQuotaExhausted(providerId: string, accountId: string, untilEpochMs: number, now?: number): void;
     /** Whether a record is unhealthy at `now`: blocked, or any timer still future. */
     private isUnhealthyAt;
     /**
@@ -194,6 +248,8 @@ declare class SubscriptionAccountHealth {
     sweepRecoveries(now?: number): AccountRecoveryEvent[];
     /** Admin-facing coarse status + cooldown-until for one account (secret-free). */
     getStatus(providerId: string, accountId: string, now?: number): AccountHealthStatus;
+    /** Return newest-first, bounded, secret-free health edge diagnostics. */
+    getDiagnostics(filter?: AccountHealthDiagnosticFilter): AccountHealthDiagnostic[];
     /**
      * Register a recovery listener (the OQ3 seam #5 webhooks + #8 health-cron
      * consume). Returns an unsubscribe function. Two edges fire it:
@@ -216,6 +272,7 @@ declare class SubscriptionAccountHealth {
      */
     onAnomaly(listener: AccountAnomalyListener): () => void;
     private emitAnomaly;
+    private recordDiagnostic;
     /**
      * Delete every EXPIRED timer field on the record in place; return whether any
      * timer is STILL active (in the future). `blocked` is not a timer and is left
@@ -232,4 +289,4 @@ declare function setSharedAccountHealth(instance: SubscriptionAccountHealth): vo
 /** Reset the shared singleton (tests / teardown only). */
 declare function __resetSharedAccountHealthForTests(): void;
 
-export { AUTH_ERROR_TTL_MS, type AccountAnomalyEvent, type AccountAnomalyListener, type AccountAnomalyState, type AccountHealthState, type AccountHealthStatus, type AccountRecoveryEvent, type AccountRecoveryListener, type HeadersLike, type HealthRecord, OVERLOAD_ENABLED_DEFAULT, OVERLOAD_TTL_MS, type RecordUpstreamOutcomeInput, SERVER_ERROR_TTL_MS, SubscriptionAccountHealth, type SubscriptionAccountHealthOptions, __resetSharedAccountHealthForTests, getSharedAccountHealth, resolveResetSeconds, setSharedAccountHealth };
+export { ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT, AUTH_ERROR_TTL_MS, type AccountAnomalyEvent, type AccountAnomalyListener, type AccountAnomalyState, type AccountHealthDiagnostic, type AccountHealthDiagnosticFilter, type AccountHealthState, type AccountHealthStatus, type AccountRecoveryEvent, type AccountRecoveryListener, type HeadersLike, type HealthRecord, MAX_QUOTA_COOLDOWN_MS, OVERLOAD_ENABLED_DEFAULT, OVERLOAD_TTL_MS, type RecordUpstreamOutcomeInput, SERVER_ERROR_TTL_MS, SubscriptionAccountHealth, type SubscriptionAccountHealthOptions, __resetSharedAccountHealthForTests, getSharedAccountHealth, resolveResetSeconds, setSharedAccountHealth };

package/dist/pipeline/SubscriptionAccountHealth.js

@@ -1,5 +1,7 @@
 import {
+  ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT,
   AUTH_ERROR_TTL_MS,
+  MAX_QUOTA_COOLDOWN_MS,
   OVERLOAD_ENABLED_DEFAULT,
   OVERLOAD_TTL_MS,
   SERVER_ERROR_TTL_MS,
@@ -8,9 +10,11 @@ import {
   getSharedAccountHealth,
   resolveResetSeconds,
   setSharedAccountHealth
-} from "../chunk-5ENKBSWO.js";
+} from "../chunk-N7OOJI5V.js";
 export {
+  ACCOUNT_HEALTH_DIAGNOSTIC_LIMIT,
   AUTH_ERROR_TTL_MS,
+  MAX_QUOTA_COOLDOWN_MS,
   OVERLOAD_ENABLED_DEFAULT,
   OVERLOAD_TTL_MS,
   SERVER_ERROR_TTL_MS,

package/dist/pipeline/SubscriptionAuthSource.cjs

@@ -1,9 +1,12 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunkKFI44N2Rcjs = require('../chunk-KFI44N2R.cjs');
+var _chunkYNJNTCSQcjs = require('../chunk-YNJNTCSQ.cjs');
 require('../chunk-SVNDB62D.cjs');
+require('../chunk-6QQG7YG3.cjs');
+require('../chunk-25GXJCEZ.cjs');
+require('../chunk-HVBBDBS3.cjs');
 
 
 
-exports.SubscriptionAuthSource = _chunkKFI44N2Rcjs.SubscriptionAuthSource; exports.stripAuthHeaders = _chunkKFI44N2Rcjs.stripAuthHeaders;
+exports.SubscriptionAuthSource = _chunkYNJNTCSQcjs.SubscriptionAuthSource; exports.stripAuthHeaders = _chunkYNJNTCSQcjs.stripAuthHeaders;

package/dist/pipeline/SubscriptionAuthSource.d.cts

@@ -1,6 +1,7 @@
 import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
 import { AuthSource, AuthApplyHints } from './AuthSource.cjs';
 import { AuthStrategy } from './SubscriptionAuthStrategy.cjs';
+import './BoundAccountSelectionError.cjs';
 
 /**
  * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.

package/dist/pipeline/SubscriptionAuthSource.d.ts

@@ -1,6 +1,7 @@
 import { OpenCodeGoTokenConfig, OpenCodeGoScenario, OpenCodeGoModelEntry } from '@omnicross/contracts/subscription-types';
 import { AuthSource, AuthApplyHints } from './AuthSource.js';
 import { AuthStrategy } from './SubscriptionAuthStrategy.js';
+import './BoundAccountSelectionError.js';
 
 /**
  * SubscriptionAuthSource — `AuthSource` wrapping a subscription `AuthStrategy`.

package/dist/pipeline/SubscriptionAuthSource.js

@@ -1,8 +1,11 @@
 import {
   SubscriptionAuthSource,
   stripAuthHeaders
-} from "../chunk-HRRYG2AX.js";
+} from "../chunk-23S5OPIO.js";
 import "../chunk-AVYJ4YBN.js";
+import "../chunk-OPRS4IQZ.js";
+import "../chunk-2JYRIADS.js";
+import "../chunk-MKF46GNZ.js";
 export {
   SubscriptionAuthSource,
   stripAuthHeaders