@oh-my-pi/pi-ai 18.4.0 → 18.4.2

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [18.4.2] - 2026-09-28
+
+### Fixed
+
+- Fixed successful Cursor agent turns being treated as context overflows, which ran overflow compaction and showed "Compaction freed too little context to make progress" while `/context` read well under the window; overflow detection now uses the reported context size instead of input totals summed across a turn's model calls ([#13608](https://github.com/can1357/oh-my-pi/pull/13608) by [@H4vC](https://github.com/H4vC))
+- Fixed Anthropic requests with thinking enabled failing on models whose output ceiling cannot fit the minimum thinking budget; thinking is now disabled for those requests instead ([#13359](https://github.com/can1357/oh-my-pi/pull/13359) by [@jchanghong023](https://github.com/jchanghong023))
+- Fixed Cursor native Grep/Glob results showing no matches or raw output, Write failing to create files, StrReplace missing edits beyond the read limit, and Read/Shell/Delete results misreporting content or metadata ([#13600](https://github.com/can1357/oh-my-pi/issues/13600)).
+
+## [18.4.1] - 2026-09-28
+
+### Fixed
+
+- Fixed extension-provided usage reports missing from broker-connected clients when the broker does not have that provider ([#13579](https://github.com/can1357/oh-my-pi/issues/13579)).
+- Fixed signed LiteLLM `thinking_blocks` being dropped on openai-completions tool-call turns ([#13407](https://github.com/can1357/oh-my-pi/issues/13407)).
+- Fixed Anthropic turns ending on a bare `aborted` error with no retry when the connection dropped mid-response (typically during long thinking). The first-party Anthropic transport runs on `node:https`, whose Bun shim reports a response cut off mid-body as `Error("aborted")` (ECONNRESET) — indistinguishable from a cancellation, so it classified as unknown. It now surfaces as "The socket connection was closed unexpectedly…", the same wording native `fetch` uses, so the drop classifies as transient and the turn is retried; caller aborts keep their original error ([#13384](https://github.com/can1357/oh-my-pi/pull/13384) by [@jerryfane](https://github.com/jerryfane))
+- Fixed a stale Z.AI quota block pinning sessions to a fallback model after live usage recovered ([#13343](https://github.com/can1357/oh-my-pi/issues/13343)).
+- Fixed OAuth credentials being re-minted on every provider 401 during an outage; recently minted tokens are reused for auth recovery ([#13350](https://github.com/can1357/oh-my-pi/issues/13350)) ([#13485](https://github.com/can1357/oh-my-pi/pull/13485) by [@ShivamB25](https://github.com/ShivamB25)).
+- Fixed Claude usage reports intermittently dropping an account's saved resets when the separate reset probe was rate-limited or timed out; the last known saved resets now stay visible until the probe answers again ([#13474](https://github.com/can1357/oh-my-pi/pull/13474) by [@schickling-assistant](https://github.com/schickling-assistant))
+- Fixed transient Windows `EPERM` when creating the provider in-flight lock failing the request instead of retrying ([#13334](https://github.com/can1357/oh-my-pi/pull/13334) by [@1Morganmore](https://github.com/1Morganmore)).
+- Fixed rolling per-minute TPM/RPM 429s worded as quota errors being treated as exhausted quota and ending the turn ([#13253](https://github.com/can1357/oh-my-pi/issues/13253)).
+- Fixed keyless Anthropic-compatible endpoints receiving `Authorization: Bearer N/A` and `X-Api-Key: N/A` headers ([#13043](https://github.com/can1357/oh-my-pi/pull/13043) by [@jchanghong023](https://github.com/jchanghong023)).
+- Fixed legacy Windsurf Enterprise API keys being rejected because they were always sent with the Devin session-token prefix ([#12960](https://github.com/can1357/oh-my-pi/pull/12960)).
+- Fixed an exhausted Cursor "Other Models" pool blocking Grok and Composer, which Cursor bills to its own pool ([#13198](https://github.com/can1357/oh-my-pi/issues/13198)).
+- Fixed Anthropic OAuth requests leaving the agent system prompt without its own cache breakpoint: the breakpoint on the short Claude Code identity block now moves to the last system block, so a request whose messages miss the cache (such as the first after a compaction) reads the cached system prompt instead of writing it again ([#13104](https://github.com/can1357/oh-my-pi/issues/13104), [#13556](https://github.com/can1357/oh-my-pi/pull/13556) by [@aktanazat](https://github.com/aktanazat)).
+- Fixed the Anthropic system cache breakpoint covering working-directory-specific system text: it now sits before the first `<project-context>` or `<memories>` block, and on OAuth it replaces the identity-block breakpoint instead of taking a message breakpoint ([#13104](https://github.com/can1357/oh-my-pi/issues/13104)).
+
 ## [18.4.0] - 2026-09-28
 
 ### Breaking Changes

package/README.md

@@ -1161,6 +1161,18 @@ const response = await complete(
 );
 ```
 
+When an auth-broker client requests recovery after a provider rejects an OAuth
+bearer, the broker may reuse a still-fresh token that it minted in the previous
+five minutes instead of rotating the refresh token again. The process-local
+cache is bound to the credential ID and access token. Scheduled expiry refreshes,
+direct forced refreshes such as MCP recovery, ordinary hard-auth blocks, and
+sibling rotation keep their existing behavior. Cached refresh responses rebind
+by durable credential ID so concurrent row removal cannot switch a pinned
+session to another account.
+Generic `forceRefresh: true` requests do not opt into reuse. Provider-401 retry
+paths pass `refreshReason: "auth-recovery"` explicitly; expiry sentinels and
+usage polling do not imply that reason.
+
 ### Provider Notes
 
 **OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options.

package/dist/types/auth/oauth.d.ts

@@ -5,7 +5,7 @@ import type { AccountPolicies } from "./policy.js";
 import type { CredentialPool } from "./pool.js";
 import type { OAuthRefresher } from "./refresh.js";
 import type { CredentialSelector } from "./select.js";
-import type { AuthAccountPolicy, AuthApiKeyOptions, OAuthAccess, OAuthAccessResolution, OAuthAccountIdentity, OAuthAccountSummary, OAuthApi, OAuthCredential, OAuthLoginController, OAuthLoginIdentity, StoredOAuthRefreshOptions, StoredOAuthRefreshResult, AuthCredentialSnapshotEntry } from "./types.js";
+import type { AuthAccountPolicy, AuthApiKeyOptions, AuthCredentialSnapshotEntry, OAuthAccess, OAuthAccessResolution, OAuthAccountIdentity, OAuthAccountSummary, OAuthApi, OAuthCredential, OAuthLoginController, OAuthLoginIdentity, OAuthRefreshByIdOptions, StoredOAuthRefreshOptions, StoredOAuthRefreshResult } from "./types.js";
 /** Dependencies used by the OAuth account operations. */
 export interface OAuthAccountsDeps {
     pool: CredentialPool;
@@ -87,7 +87,7 @@ export declare class OAuthAccounts implements OAuthApi {
      */
     policy(provider: string, identity: OAuthAccountIdentity): AuthAccountPolicy | undefined;
     /** Force-refresh one stored credential by its durable row id. */
-    refresh(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /** Refresh one stored OAuth credential through the durable ownership path. */
     refreshStored<T extends OAuthCredential = OAuthCredential>(provider: string, options: StoredOAuthRefreshOptions<T>): Promise<StoredOAuthRefreshResult<T>>;
 }

package/dist/types/auth/refresh.d.ts

@@ -3,7 +3,7 @@ import type { Provider } from "../types.js";
 import { type CredentialPool } from "./pool.js";
 import type { AccountPolicies } from "./policy.js";
 import { type AuthCredentialStore } from "./store.js";
-import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
+import { type AuthCredentialSnapshotEntry, type AuthStorageOptions, type OAuthCredential, type OAuthRefreshByIdOptions, type OAuthRefreshReason, type StoredOAuthRefreshOptions, type StoredOAuthRefreshResult } from "./types.js";
 /**
  * Refresh OAuth access tokens this many ms before their stated expiry. The
  * skew exists so callers downstream of {@link OAuthRefresher} (stream providers,
@@ -48,12 +48,12 @@ export declare class OAuthRefresher {
      * continuing.
      */
     disableDefinitiveFailure(provider: string, credentialId: number | undefined, attemptedCredential: OAuthCredential, index: number, errorMsg: string): Promise<"disabled" | "peer-rotated" | "cas-lost">;
-    refresh(provider: Provider, credential: OAuthCredential, credentialId: number | undefined, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refresh(provider: Provider, credential: OAuthCredential, credentialId: number | undefined, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Refresh the OAuth credential with the given id through a per-credential
      * single-flight. Concurrent callers for the same row await the same upstream
      * refresh attempt, which is required for providers that rotate refresh tokens
      * on every successful refresh.
      */
-    refreshById(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refreshById(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
 }

package/dist/types/auth/store.d.ts

@@ -1,7 +1,7 @@
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
 import type { ClientUsageIdentity, ClientUsageReport, ClientUsageSummary, ObservedUsageEntry, UsageHistoryEntry, UsageHistoryQuery, UsageReport } from "../usage.js";
-import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthCredential, OAuthRefreshReason, StoredAuthCredential, StoredCredentialBlock } from "./types.js";
 /** Owner and timestamp that fence a durable credential refresh lease. */
 export interface CredentialRefreshLeaseFence {
     owner: string;
@@ -128,8 +128,10 @@ export interface CredentialUpstream {
      * `signal` propagates the agent's cancel (ESC, request abort, …) all the
      * way to the broker fetch so a hung connection can't strand the caller
      * for `timeoutMs * (maxRetries + 1)`.
+     * `reason` distinguishes provider-auth recovery from generic/MCP refreshes
+     * that must always mint a new access token.
      */
-    refreshOAuthCredential(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refreshOAuthCredential(provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Optional async pre-read hook invoked after AuthStorage selects a stored
      * credential but before it returns that credential for an outbound request.

package/dist/types/auth/types.d.ts

@@ -272,6 +272,8 @@ export interface CredentialDisabledEvent {
     orgId?: string;
     orgName?: string;
 }
+/** Why a delegated OAuth refresh was requested. */
+export type OAuthRefreshReason = "auth-recovery";
 /** Configuration supplied when constructing credential storage. */
 export type AuthStorageOptions = {
     usageProviderResolver?: (provider: Provider) => UsageProvider | undefined;
@@ -301,11 +303,14 @@ export type AuthStorageOptions = {
      * per-provider local refresh function. Receives the credential id so the
      * implementation can address remote credentials.
      *
+     * `reason` is `"auth-recovery"` only for a provider-auth retry; generic and
+     * managed MCP force-refresh calls leave it unset.
+     *
      * Must return updated {@link OAuthCredentials} with at least `access` and
      * `expires`. `refresh` may be an opaque sentinel (e.g. `"__remote__"`) when
      * the actual refresh token never leaves the broker.
      */
-    refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal) => Promise<OAuthCredentials>;
+    refreshOAuthCredential?: (provider: Provider, credentialId: number, credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason) => Promise<OAuthCredentials>;
     /**
      * Human-readable description of the credential store backing this
      * AuthStorage instance. Surfaced through {@link AuthStorage.keys.describe}
@@ -414,6 +419,8 @@ export type AuthApiKeyOptions = {
      * that a peer/broker rotated out from under us is replaced before retrying.
      */
     forceRefresh?: boolean;
+    /** Explicit provider-401 recovery; generic force refreshes leave this unset. */
+    refreshReason?: OAuthRefreshReason;
 };
 /**
  * Refreshed OAuth access plus identity metadata returned by
@@ -876,6 +883,15 @@ export interface KeysApi {
         modelId?: string;
     }): ApiKeyResolver;
 }
+/** Controls whether a row-id refresh may reuse a token minted by this refresher. */
+export interface OAuthRefreshByIdOptions {
+    /**
+     * Return the stored credential when it still holds a fresh access token this
+     * refresher minted recently. Auth-recovery callers use this to avoid rotating
+     * refresh tokens repeatedly when a provider rejects every valid bearer.
+     */
+    reuseRecentMint?: boolean;
+}
 /** OAuth login, access, account identity, and refresh operations. */
 export interface OAuthApi {
     /**
@@ -950,9 +966,10 @@ export interface OAuthApi {
      * Refresh the OAuth credential with the given id through a per-credential
      * single-flight. Concurrent callers for the same row await the same upstream
      * refresh attempt, which is required for providers that rotate refresh tokens
-     * on every successful refresh.
+     * on every successful refresh. Mints unconditionally unless
+     * {@link OAuthRefreshByIdOptions.reuseRecentMint} is set.
      */
-    refresh(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry>;
+    refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry>;
     /**
      * Refresh one stored OAuth credential under durable row ownership.
      */

package/dist/types/auth/usage-cache.d.ts

@@ -66,10 +66,17 @@ export declare class UsageCache {
     /**
      * Force the next usage fetch for `provider` to bypass the 5-min cache, so
      * `/usage` reflects a freshly-redeemed reset instead of stale numbers.
+     * `resetSpentCredentialId` also forgets that credential's cached saved-reset
+     * block, so a failed follow-up reset probe cannot carry the pre-spend
+     * inventory forward.
      */
-    invalidate(provider: string, baseUrl?: string): void;
+    invalidate(provider: string, baseUrl?: string, options?: {
+        resetSpentCredentialId?: number;
+    }): void;
     /** A confirmed reset permits one fresh probe even during a pre-reset failure cooldown. */
-    invalidateAfterReset(provider: Provider, baseUrl?: string): void;
+    invalidateAfterReset(provider: Provider, baseUrl?: string, options?: {
+        resetSpentCredentialId?: number;
+    }): void;
     /**
      * Expire cached reports for a provider after its runtime usage implementation changes.
      * This keeps a newly installed extension provider from serving a built-in snapshot.

package/dist/types/auth/usage.d.ts

@@ -29,6 +29,10 @@ export interface UsageServiceDeps {
     requestTimeoutMs: number;
     logger: UsageLogger;
 }
+type UsageReportsOptions = {
+    baseUrlResolver?: (provider: Provider) => string | undefined;
+    signal?: AbortSignal;
+};
 /** Usage reports: per-credential cached fetches, aggregate reports, header ingestion, history. */
 export declare class UsageService implements UsageApi {
     #private;
@@ -95,11 +99,7 @@ export declare class UsageService implements UsageApi {
      */
     reportingModelIds(provider: Provider, modelIds: readonly string[], reports: readonly UsageReport[]): string[];
     /** Fetch all providers’ current usage reports, sharing concurrent polls. */
-    reports(options?: {
-        baseUrlResolver?: (provider: Provider) => string | undefined;
-        /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
-        signal?: AbortSignal;
-    }): Promise<UsageReport[] | null>;
+    reports(options?: UsageReportsOptions): Promise<UsageReport[] | null>;
     /**
      * Discard cached usage reports before a user-requested refresh. The next
      * read probes upstream serially per provider unless a failure cooldown is
@@ -107,3 +107,4 @@ export declare class UsageService implements UsageApi {
      */
     invalidate(provider?: string, signal?: AbortSignal): Promise<void>;
 }
+export {};

package/dist/types/auth-broker/client.d.ts

@@ -5,7 +5,7 @@
  * `omp auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
-import type { AuthCredential, DisabledCredentialSummary } from "../auth-storage.js";
+import type { AuthCredential, DisabledCredentialSummary, OAuthRefreshReason } from "../auth-storage.js";
 import type { ClientUsageReportRequest, ClientUsageReportResponse, ClientUsageSummaryResponse, CredentialBlockDeleteRequest, CredentialBlockRequest, CredentialBlockResponse, CredentialBlocksDeleteResponse, CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageHistoryResponse, UsageResponse, UsageStaleResponse } from "./types.js";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
@@ -86,7 +86,7 @@ export declare class AuthBrokerClient {
         sinceMs?: number;
     }, signal?: AbortSignal): Promise<ClientUsageSummaryResponse>;
     notifyUsageStale(signal?: AbortSignal): Promise<UsageStaleResponse>;
-    refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
+    refreshCredential(id: number, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;
     /**
      * Disabled-credential tombstones (identity + cause, no token material).

package/dist/types/auth-broker/remote-store.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredentialStore } from "../auth/store.js";
-import { type AuthCredential, type DisabledCredentialSummary, type OAuthCredential, type StoredAuthCredential, type StoredCredentialBlock } from "../auth/types.js";
+import { type AuthCredential, type DisabledCredentialSummary, type OAuthCredential, type OAuthRefreshReason, type StoredAuthCredential, type StoredCredentialBlock } from "../auth/types.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
 import type { Provider } from "../types.js";
 import type { ClientUsageIdentity, ObservedUsageEntry, UsageReport } from "../usage.js";
@@ -128,7 +128,7 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * the broker-redacted credential with {@link REMOTE_REFRESH_SENTINEL} in
      * the `refresh` slot.
      */
-    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal): Promise<OAuthCredentials>;
+    refreshOAuthCredential(_provider: Provider, credentialId: number, _credential: OAuthCredential, signal?: AbortSignal, reason?: OAuthRefreshReason): Promise<OAuthCredentials>;
     /**
      * Store-level hook consumed by `AuthStorage.usage.reports()` — proxies
      * to the broker's `/v1/usage` endpoint. Shared per-credential caches and

package/dist/types/error/flags.d.ts

@@ -126,9 +126,16 @@ export declare function classifyMessage(message: {
 export declare function attach<E extends object>(error: E, id: number): E;
 /** Overflow-classification evidence, including errors received before token usage is available. */
 export interface ContextOverflowMessage extends Pick<AssistantMessage, "errorId" | "stopReason" | "errorMessage"> {
-    readonly usage?: Pick<Usage, "input" | "cacheRead" | "cacheWrite">;
+    readonly usage?: Pick<Usage, "input" | "cacheRead" | "cacheWrite" | "contextTokens">;
 }
-/** Provider-reported usage proves context-window excess — authoritative, compaction-owned (#9235). */
+/**
+ * Provider-reported usage proves context-window excess — authoritative, compaction-owned (#9235).
+ *
+ * Prefers `contextTokens` when the provider reports it: providers that run
+ * several model calls per turn (Cursor's server-side tool loop) report
+ * `input`/`cacheRead` summed across those calls, which can exceed the window
+ * many times over while the conversation itself stays small.
+ */
 export declare function isUsageBackedContextOverflow(message: ContextOverflowMessage, contextWindow?: number): boolean;
 /** Classify overflow from error flags, available token usage, or provider error text. */
 export declare function isContextOverflow(message: ContextOverflowMessage, contextWindow?: number): boolean;

package/dist/types/error/rate-limit.d.ts

@@ -9,8 +9,9 @@ export declare function isDashScopeTokenLimitText(errorMessage: string): boolean
  * Classify a rate-limit error message into a reason category.
  * Priority order: explicit details in a resource-exhausted error > QUOTA
  * (Antigravity "quota will reset") > CN quota > DASHSCOPE_TOKEN_LIMIT (TPM/TPS
- * throttle) > CONCURRENT_LIMIT > MODEL_CAPACITY > QUOTA (account) > RATE_LIMIT >
- * QUOTA (generic) > SERVER_ERROR > bare resource-exhausted > UNKNOWN.
+ * throttle) > CONCURRENT_LIMIT > MODEL_CAPACITY > QUOTA (account) > RATE_LIMIT
+ * (including TPM/RPM rolling windows) > QUOTA (generic) > SERVER_ERROR > bare
+ * resource-exhausted > UNKNOWN.
  *
  * Bare "resource exhausted" / "resource_exhausted" maps to MODEL_CAPACITY (transient, short wait).
  * Explicit details such as "quota exceeded" retain their normal classification.

package/dist/types/providers/cursor/exec-modern.d.ts

@@ -17,7 +17,7 @@ import type { ToolResultMessage } from "../../types.js";
  * virtual registry. Re-exported here because this is where the frame builders
  * and their translation are consumed together.
  */
-export { cursorEditOwnedReadPath, cursorRawReadPath, omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, shellTimeoutSeconds, } from "../cursor-pi-args.js";
+export { cursorExecReadPath, cursorRawReadPath, omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, shellTimeoutSeconds, } from "../cursor-pi-args.js";
 /** Flatten a tool result's content into the single `output` string the Pi frames carry. */
 export declare function piOutputText(toolResult: ToolResultMessage): string;
 /**

package/dist/types/providers/cursor-pi-args.d.ts

@@ -22,18 +22,14 @@
  * A `pi_read` range composed onto the path as `read`'s inline `:raw:N+K`
  * selector.
  *
- * `read` exposes no range kwargs, so an uncomposed range reads the whole file.
- * `offset` is a 1-indexed start clamped like the reference's
- * `Math.max(0, offset - 1)` over 0-indexed lines; `limit` is a line count.
- * `null` marks a present `limit: 0` — zero lines, which no selector expresses
- * and which must not degrade into a whole-file read.
- *
- * The range is `raw` because a plain `:N+K` deliberately pads with one leading
- * and three trailing context lines: helpful for a human reading a snippet,
- * wrong for a caller that asked for exactly `limit` lines from `offset`. The
- * wire result is an opaque `output` string, so the hashline and line-number
- * gutter that `raw` also drops carry nothing the frame's contract needs.
- * A range-free read keeps the ordinary form — whole-file reads want them.
+ * `read` exposes no range kwargs; `offset` and `limit` are composed onto the
+ * path. A negative offset needs the source line count and is resolved by the
+ * coding-agent bridge before calling this helper. `limit: 0` has no selector
+ * representation and returns `null`.
+ *
+ * Range selectors are raw because plain ranges add context lines. Cursor
+ * numbers the returned text itself, so it cannot use read's hashline gutter.
+ * Use [`cursorExecReadPath`] for a range-free read, which also needs `:raw`.
  */
 export declare function piReadPath(readPath: string, offset?: number, limit?: number): string | null;
 /**
@@ -55,14 +51,13 @@ export declare function piReadPathHasRange(readPath: string): boolean;
  */
 export declare function cursorRawReadPath(readPath: string): string;
 /**
- * Path the edit-owned materialization read should execute.
+ * Raw selector for a Cursor exec read, including edit-owned materialization.
  *
- * Range is composed first (`piReadPath` already uses `:raw` for a range),
- * then a whole-file path is forced onto `:raw`. The caller must drop
- * `offset`/`limit` after this so the bridge's `piReadPath` cannot append a
- * second `:raw` onto the already-composed selector.
+ * Compose a requested window before forcing `:raw` on whole-file reads. The
+ * caller drops `offset`/`limit` after composing so the handler cannot append
+ * another selector.
  */
-export declare function cursorEditOwnedReadPath(readPath: string, offset?: number, limit?: number): string | null;
+export declare function cursorExecReadPath(readPath: string, offset?: number, limit?: number): string | null;
 /**
  * The same range as {@link piReadPath}, rendered for a transcript block rather
  * than for execution.

package/dist/types/stream.d.ts

@@ -19,6 +19,13 @@ export declare const __providerInFlightForTesting: {
     setWaitObserver(observer: ((provider: string) => void) | undefined): void;
     setLockCreatedObserver(observer: ((lockDir: string) => Promise<void>) | undefined): void;
     setLockIdentifiedObserver(observer: ((lockDir: string) => Promise<void>) | undefined): void;
+    setLockMkdirOverride(mkdir: ((lockDir: string) => Promise<void>) | undefined): void;
+    setLockPlatformOverride(platform: NodeJS.Platform | undefined): void;
+    setLockRetryTimings(timings: {
+        budgetMs?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+    } | undefined): void;
     providerDir(provider: string): string;
     lockDir(provider: string): string;
     captureStaleLockRelease(provider: string): Promise<(() => Promise<void>) | null>;

package/dist/types/usage/cursor.d.ts

@@ -1,4 +1,4 @@
-import type { UsageProvider, UsageReport } from "../usage.js";
+import type { CredentialRankingStrategy, UsageProvider, UsageReport } from "../usage.js";
 /**
  * Cursor's `/api/usage-summary` has shipped two personal-bucket shapes:
  * - Enterprise/team dashboards historically exposed `individualUsage.overall`
@@ -12,4 +12,6 @@ import type { UsageProvider, UsageReport } from "../usage.js";
  */
 export declare function parseCursorIndividualUsage(payload: unknown, fetchedAt?: number): UsageReport | null;
 export declare function parseCursorUsage(payload: unknown, fetchedAt?: number): UsageReport | null;
+/** Routes Cursor credential ranking and reserve checks through the requested model's billing pool. */
+export declare const cursorRankingStrategy: CredentialRankingStrategy;
 export declare const cursorUsageProvider: UsageProvider;

package/dist/types/usage/zai.d.ts

@@ -1,3 +1,5 @@
 import type { CredentialRankingStrategy, UsageProvider } from "../usage.js";
+/** Fetches the account-wide quota windows for ZAI credentials. */
 export declare const zaiUsageProvider: UsageProvider;
+/** Ranks ZAI credentials and identifies quota blocks a live report can heal. */
 export declare const zaiRankingStrategy: CredentialRankingStrategy;

package/dist/types/usage.d.ts

@@ -580,6 +580,12 @@ export interface UsageFetchContext {
     fetch: FetchImpl;
     logger?: UsageLogger;
     retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Last report cached for this exact credential cache key, when one exists.
+     * Lets a fetcher keep a field it could not re-read this time (a failed
+     * secondary probe) instead of reporting it as absent.
+     */
+    previousReport?: UsageReport;
 }
 /** Provider implementation for fetching usage information. */
 export interface UsageProvider {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.4.0",
+	"version": "18.4.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.4.0",
-		"@oh-my-pi/pi-catalog": "18.4.0",
-		"@oh-my-pi/pi-natives": "18.4.0",
-		"@oh-my-pi/pi-utils": "18.4.0",
-		"@oh-my-pi/pi-wire": "18.4.0"
+		"@oh-my-pi/omptype": "18.4.2",
+		"@oh-my-pi/pi-catalog": "18.4.2",
+		"@oh-my-pi/pi-natives": "18.4.2",
+		"@oh-my-pi/pi-utils": "18.4.2",
+		"@oh-my-pi/pi-wire": "18.4.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/auth/cascade.ts

@@ -399,6 +399,7 @@ export class KeyCascade implements KeysApi {
 				baseUrl,
 				modelId,
 				forceRefresh: true,
+				refreshReason: AIError.status(error) === 401 ? "auth-recovery" : undefined,
 				signal,
 			});
 		};

package/src/auth/oauth.ts

@@ -13,6 +13,7 @@ import type { CredentialSelector } from "./select";
 import type {
 	AuthAccountPolicy,
 	AuthApiKeyOptions,
+	AuthCredentialSnapshotEntry,
 	OAuthAccess,
 	OAuthAccessResolution,
 	OAuthAccountIdentity,
@@ -21,9 +22,9 @@ import type {
 	OAuthCredential,
 	OAuthLoginController,
 	OAuthLoginIdentity,
+	OAuthRefreshByIdOptions,
 	StoredOAuthRefreshOptions,
 	StoredOAuthRefreshResult,
-	AuthCredentialSnapshotEntry,
 } from "./types";
 
 type StoredOAuthSelection = {
@@ -338,8 +339,8 @@ export class OAuthAccounts implements OAuthApi {
 	}
 
 	/** Force-refresh one stored credential by its durable row id. */
-	refresh(id: number, signal?: AbortSignal): Promise<AuthCredentialSnapshotEntry> {
-		return this.#deps.refresher.refreshById(id, signal);
+	refresh(id: number, signal?: AbortSignal, options?: OAuthRefreshByIdOptions): Promise<AuthCredentialSnapshotEntry> {
+		return this.#deps.refresher.refreshById(id, signal, options);
 	}
 
 	/** Refresh one stored OAuth credential through the durable ownership path. */