@cortexkit/anthropic-auth-core 2.0.2 → 2.1.0

package/dist/native-migration.d.ts

@@ -1,14 +1,15 @@
 import { type PoolRow } from "./internal-types/store/index.js";
+import type { NativeAccountSnapshot } from './native-account-view.ts';
 import type { NativeCustodyInventory } from './native-custody.ts';
 import { type NativeHostAuthWriteHooks } from './native-host-auth-write.ts';
 import { type NativeRosterSeedInput, type NativeVaultRosterSeed } from './native-roster-seed.ts';
 import { type NativeRuntimeState } from './native-runtime.ts';
-import { type NativeMigrationJournal } from './pool-authority.ts';
+import { type NativeEmptyInitJournal, type NativeLegacyMigrationJournal } from './pool-authority.ts';
 import { type NativePoolPaths } from './pool-paths.ts';
 import { createNativePoolStore } from './pool-store.ts';
 export declare class NativeMigrationError extends Error {
-    readonly code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'retirement-refused';
-    constructor(code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'retirement-refused');
+    readonly code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'pool-populated' | 'host-login-present' | 'settings-changed' | 'retirement-refused';
+    constructor(code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'pool-populated' | 'host-login-present' | 'settings-changed' | 'retirement-refused');
 }
 export interface NativeMigrationCustody {
     /** Use the host’s approved Claustrum token and account-list permission to discover accounts; never open the vault’s credential files. */
@@ -54,6 +55,26 @@ export interface NativeMigrationHooks {
     hostWrite?: NativeHostAuthWriteHooks;
     store?: Pick<Parameters<typeof createNativePoolStore>[0], 'onStep' | 'onLockStep'>;
 }
+/** Session pins and preferences do not establish account ownership. */
+export declare function nativePoolHoldsAccountData({ paths, }: {
+    paths: NativePoolPaths;
+}): Promise<boolean>;
+/** Only enabled local OAuth rows can authorize local OAuth serving. */
+export declare function snapshotHasServableLocalOAuth(snapshot: Pick<NativeAccountSnapshot, 'accounts'>): boolean;
+export interface NativeEmptyInitOptions {
+    paths: NativePoolPaths;
+    routingDestinationPath: string;
+    processFence: () => Promise<void>;
+    env: NodeJS.ProcessEnv;
+}
+export interface NativeEmptyInitHooks extends Pick<NativeMigrationHooks, 'onStep'> {
+    lockOptions?: {
+        ttlMs: number;
+        timeoutMs: number;
+    };
+}
+/** Establish local authority for a new OpenCode pool without reading legacy credentials. */
+export declare function publishNativeEmptyInit(input: NativeEmptyInitOptions, hooks?: NativeEmptyInitHooks): Promise<NativeEmptyInitJournal>;
 /** Preflight is read-only so setup can validate all selected hosts before any begin. */
 export declare function prepareNativeMigration(input: NativeMigrationOptions): Promise<NativeMigrationPreflight>;
 export declare function releaseNativeMigrationPreflight(token: NativeMigrationPreflight): void;
@@ -63,4 +84,4 @@ export declare function releaseNativeMigrationPreflight(token: NativeMigrationPr
  */
 export declare function importedRuntimeProjection(paths: NativePoolPaths, store: ReturnType<typeof createNativePoolStore>, rows: PoolRow[]): Promise<unknown>;
 /** Offline, crash-forward transaction. Native serving never calls this controller. */
-export declare function runNativeMigration(input: NativeMigrationOptions, hooks?: NativeMigrationHooks): Promise<NativeMigrationJournal>;
+export declare function runNativeMigration(input: NativeMigrationOptions, hooks?: NativeMigrationHooks): Promise<NativeLegacyMigrationJournal>;

package/dist/native-quota-observations.d.ts

@@ -0,0 +1,26 @@
+import { type AccountStorage, type OAuthQuotaSnapshot } from './accounts.ts';
+import type { NativeLocalPoolBinding } from './pool-binding.ts';
+import type { QuotaEntry } from './quota-manager.ts';
+export type NativeQuotaObservation = {
+    lineage: string;
+    accountUuid: string;
+    entry: QuotaEntry;
+    generalExhausted: boolean;
+    quotaErrorClearedAt?: number;
+};
+export declare function nativePollQuotaGenerallyExhausted(quota: OAuthQuotaSnapshot): boolean;
+export declare function nativeLocalQuotaLineage(binding: NativeLocalPoolBinding & {
+    readonly identity: string;
+}): string;
+export declare function nativeLocalQuotaLineage(binding: NativeLocalPoolBinding | undefined): string | undefined;
+/** Shared by header receipt, poll completion, routing and display; contains no credentials. */
+export declare class NativeQuotaObservations extends Map<string, NativeQuotaObservation> {
+    private readonly publications;
+    set(accountId: string, observation: NativeQuotaObservation): this;
+    quota(lineage: string | undefined, accountUuid: string | undefined, committed: OAuthQuotaSnapshot | undefined, storage: AccountStorage, now?: number): {
+        quota: OAuthQuotaSnapshot;
+        clearAt?: number;
+    } | undefined;
+    publish(accountId: string, observation: NativeQuotaObservation, write: () => Promise<boolean>): Promise<void>;
+    drain(): Promise<void>;
+}

package/dist/native-runtime.d.ts

@@ -2,8 +2,10 @@ import type { AccountOperationError, OAuthAccountProfile, PrimeUsageCounters } f
 import { type NativeLocalCredentialValidation } from './native-credential-validation.ts';
 import { type NativeQuotaMap } from './native-quota-codec.ts';
 import type { NativeRefreshObservation, NativeRefreshSubject } from './native-refresh-coordinator.ts';
+import { type OwnerOnlyOptions } from './owner-only.ts';
 import { type NativeLocalPoolBinding } from './pool-binding.ts';
 import type { NativePoolPaths } from './pool-paths.ts';
+import { type PublicationOptions } from './publication-rename.ts';
 /** Identifies the vault credential and Claude account that supplied an observation. This binding contains no access token. */
 export interface NativeCustodyRuntimeBinding {
     kind: 'custody';
@@ -83,8 +85,9 @@ export declare class NativeRuntimeError extends Error {
 }
 /** Validate structure and internal identifier consistency. The publisher separately checks these identifiers against the current pool or vault roster. */
 export declare function decodeNativeRuntime(value: unknown, storageId: string): NativeRuntimeState;
-export declare function readNativeRuntime(path: string, storageId: string): Promise<NativeRuntimeRead>;
+export declare function readNativeRuntime(path: string, storageId: string, ownership?: OwnerOnlyOptions): Promise<NativeRuntimeRead>;
 export interface NativeRuntimeWriteHooks {
+    publication?: PublicationOptions;
     /** Verify that the observed account still matches the current pool record or vault roster and that the caller still owns the locks protecting those records. */
     beforeRename?: () => Promise<void>;
     /** Check caller authority after every lease assertion, immediately before replacement. This hook can only refuse publication. */
@@ -112,6 +115,7 @@ export type NativeRuntimeOptionalPublication = {
     status: 'skipped';
 };
 export interface NativeRuntimeOptionalWriteHooks {
+    publication?: PublicationOptions;
     /**
      * Same checks as NativeRuntimeWriteHooks.beforeRename, run at the same
      * point. Resolve 'skip' to discard the staged write without an error; throw

package/dist/native-transient-account.d.ts

@@ -31,8 +31,7 @@ export declare function isNativeTransientAccountError(value: unknown): value is
  * budget. Each wait between attempts ends early when any of `signals`
  * aborts; `check` is then called after the leases are released and is
  * expected to throw the caller's cancellation error. `check` runs before
- * every attempt too, so a cancelled caller never takes a lock. `now` must be
- * the clock the pool's writers stamp their lock expiry with, or a live
- * writer's lock could be judged expired and taken over.
+ * every attempt too, so a cancelled caller never takes a lock. All pool
+ * leases use wall time, independently of logical observation timestamps.
  */
-export declare function joinNativePoolWrite(paths: NativePoolStorePaths, signals: readonly AbortSignal[], check: () => void, now?: () => number): Promise<'joined' | 'deadline'>;
+export declare function joinNativePoolWrite(paths: NativePoolStorePaths, signals: readonly AbortSignal[], check: () => void): Promise<'joined' | 'deadline'>;

package/dist/native-ui.d.ts

@@ -21,6 +21,8 @@ export interface NativeUiOptions {
     readonly readMode: () => Promise<NativeMenuCustodyMode>;
     /** Token-free account names, credential IDs and states used to show which vault account needs re-login and its replacement command. */
     readonly readAccounts?: () => Promise<import('./native-account-view.ts').NativeAccountSnapshot>;
+    /** Re-read the separate host-login notice on each local Accounts render. */
+    readonly readSeparateHostLoginNotice?: () => Promise<boolean>;
     /**
      * Disconnects this host from the vault; while enrolled, this is the host's
      * only enrollment action. Before ending the enrollment, the callback

package/dist/native-usage-publication.d.ts

@@ -4,6 +4,11 @@
  * The error classes are not public runtime exports, so match name and code.
  */
 export declare function usagePublicationRefusalIsFatal(error: unknown): boolean;
+/** Return only allowlisted classes and codes, never the exception text. */
+export declare function classifySafeErrorForLog(error: unknown): {
+    name: string;
+    code: string;
+};
 /** Own advisory writes for one host instance and join them before runtime close. */
 export declare function createNativeUsagePublisher(channel: string): {
     observe: (write: Promise<unknown>) => Promise<void>;

package/dist/native-vault-invalidation.d.ts

@@ -0,0 +1,9 @@
+import type { NativeVaultRosterDocument } from './native-roster-seed.ts';
+export declare function watchNativeVaultAuthority(holder: {
+    roster: string;
+    tokenPath: string;
+    retain: (roster: NativeVaultRosterDocument | undefined) => void;
+    close: () => void;
+}): () => void;
+export declare function retainNativeVaultRoster(path: string, roster: NativeVaultRosterDocument | undefined): void;
+export declare function closeNativeVaultAuthority(tokenPath: string): void;

package/dist/native-vault-runtime.d.ts

@@ -1,12 +1,13 @@
-import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import { type OAuthAccountProfile, type OAuthQuotaSnapshot, type PrimeUsageDelta } from './accounts.ts';
 import { type NativeAccountMetadataPatch } from './native-account-view.ts';
 import { type NativeCustodyClient, type NativeCustodyInventory, type NativeCustodyReceipt, type NativeCustodyReporterSource, type NativeCustodyRetry } from './native-custody.ts';
+import { NativeQuotaObservations } from './native-quota-observations.ts';
 import { type NativeRosterSeedInput, type NativeVaultRosterDocument, type NativeVaultRosterSeed } from './native-roster-seed.ts';
 import { type NativeRuntimeState } from './native-runtime.ts';
 import type { NativeVaultPaths } from './native-vault-paths.ts';
 import type { NativePoolPaths } from './pool-paths.ts';
-import type { QuotaRequestDispatch } from './quota-manager.ts';
+import type { QuotaReadingPurpose, QuotaRequestDispatch } from './quota-manager.ts';
 export interface NativeVaultRuntimeOptions {
     paths: NativePoolPaths;
     host: 'opencode' | 'pi';
@@ -20,7 +21,34 @@ export interface NativeVaultRuntimeOptions {
     }>;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    /**
+     * Timer functions for the vault custody's outage probe and roster watch
+     * retries. Defaults to the global ones; tests pass their own.
+     */
+    setTimeout?: typeof globalThis.setTimeout;
+    clearTimeout?: typeof globalThis.clearTimeout;
+    /**
+     * Called each time the runtime has finished handling a vault notice that
+     * asked it to rediscover the roster, after the discovery that notice ran.
+     * Common-auth asks when the notice's view differs from the roster held,
+     * after a gap in the notices, and on a re-subscribed watch's first notice.
+     * Tests use it to wait for that handling instead of for the clock.
+     */
+    onRosterNoticeHandled?: () => void;
 }
+/**
+ * Why a vault quota reading is wanted, which decides whether insula's
+ * background quota cache may answer instead of Anthropic's usage endpoint.
+ * - 'background': a periodic sweep. Refresh insula's cache (at most once a
+ *   minute per daemon and enrollment), look the route's account up in it,
+ *   and skip the usage GET when it holds a current reading.
+ * - 'admission': a request needs a reading. Look the served credential's
+ *   account up in insula's cache only, never refreshing it, then poll on a
+ *   miss.
+ * Omitted: poll Anthropic directly (explicit user refreshes and other
+ *   callers that must see the provider's own reading).
+ */
+export type NativeVaultQuotaPurpose = QuotaReadingPurpose;
 export interface NativeVaultWatchOptions {
     intervalMs: number;
     onRefresh?: () => void | Promise<void>;
@@ -53,6 +81,9 @@ export interface NativeDisplayProfile {
 /** Build a NativeDisplayProfile from a validated profile and its publication. */
 export declare function nativeDisplayProfile(profile: OAuthAccountProfile, publish: () => Promise<boolean>, isCurrent: () => Promise<boolean>): NativeDisplayProfile;
 export interface NativeVaultRuntime {
+    readonly quotaObservations: NativeQuotaObservations;
+    drainQuotaPublications(): Promise<void>;
+    quotaLineage(routeId: string, credentialId: string | undefined, accountIdentity: string | undefined): string | undefined;
     /** Subscribe to one discovery loop; notifications contain no credential material. */
     watch(options: NativeVaultWatchOptions): NativeVaultWatch;
     initializeSettings(): Promise<void>;
@@ -69,7 +100,7 @@ export interface NativeVaultRuntime {
      */
     prepareRetry(receipt: NativeCustodyReceipt, signal?: AbortSignal, site?: NativeScoped401Site): Promise<NativeCustodyRetry>;
     publish(receipt: NativeCustodyReceipt, patch: NativeAccountMetadataPatch): Promise<boolean>;
-    fetchQuota(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal, dispatch?: QuotaRequestDispatch): Promise<OAuthQuotaSnapshot>;
+    fetchQuota(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal, dispatch?: QuotaRequestDispatch, purpose?: NativeVaultQuotaPurpose): Promise<OAuthQuotaSnapshot>;
     fetchProfile(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<OAuthAccountProfile>;
     /** Return the fetched account profile without waiting for its metadata write. NativeDisplayProfile.persisted reports whether that asynchronous write succeeded, failed or was refused. */
     fetchProfileForDisplay(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<NativeDisplayProfile>;
@@ -91,6 +122,8 @@ export declare function publishNativeVaultRosterSeed(paths: Pick<NativeVaultPath
 export declare function publishNativeVaultRuntimeSeed(paths: Pick<NativeVaultPaths, 'roster' | 'runtime' | 'storageId'>, state: NativeRuntimeState, options?: {
     assertOwned?: () => Promise<void>;
 }): Promise<void>;
+/** Connect through the same short deadline used when requests wait for a vault roster. */
+export declare function connectNativeVaultScopedClient(connectionFile: string, identity?: ClaustrumClientOptions['identity']): Promise<import("./internal-types/claustrum/index.js").ClaustrumScopedClient>;
 /** List accounts readable by this host's enrollment for offline setup. An inventory grants no bearer authority; every outbound request still needs a fresh scoped receipt. */
 export declare function discoverNativeVaultInventory(options: NativeVaultRuntimeOptions, signal?: AbortSignal): Promise<NativeCustodyInventory>;
 /** Retain the vault client's original per-attempt receipts and version provenance; access tokens never persist in roster or runtime metadata. */

package/dist/network-errors.d.ts

@@ -1 +1,2 @@
+export declare function transientNetworkErrorCode(error: unknown): string | undefined;
 export declare function isTransientNetworkError(error: unknown): boolean;

package/dist/owner-only.d.ts

@@ -0,0 +1,19 @@
+import type * as PrivateFiles from '@cortexkit/private-files';
+/** Per-operation injection keeps simulated Windows policy out of process globals. */
+export interface OwnerOnlyOptions {
+    platform?: NodeJS.Platform;
+    privateFiles?: Pick<typeof PrivateFiles, 'verifyOwnerOnly' | 'readPrivateFile'> & Partial<Pick<typeof PrivateFiles, 'verifySafeParent' | 'createPrivateFile' | 'createPrivateDirectory'>>;
+}
+/** POSIX callers retain their exact mode/uid policy; Windows must prove its DACL. */
+export declare function isOwnerOnly(path: string, posix: () => boolean, options?: OwnerOnlyOptions): Promise<boolean>;
+/** Windows reads through the ACL-verified native handle, not a pathname reopen. */
+export declare function readWindowsOwnerOnly(path: string, options?: OwnerOnlyOptions): Promise<Buffer | undefined>;
+/** Ancestors protect directory entries; they need not themselves be private. */
+export declare function isSafeWindowsParent(path: string, options?: OwnerOnlyOptions): Promise<boolean | undefined>;
+/** Native creation establishes a protected DACL before any bytes are written. */
+export declare function createWindowsOwnerOnly(path: string, bytes: string, options?: OwnerOnlyOptions): Promise<boolean>;
+/**
+ * Create only missing Windows directories; never tighten an existing shared directory.
+ * Returns false off Windows so callers retain their POSIX directory policy.
+ */
+export declare function ensureWindowsOwnerOnlyDirectory(path: string, options?: OwnerOnlyOptions): Promise<boolean>;

package/dist/pool-authority.d.ts

@@ -1,4 +1,5 @@
 import { type NativeMigrationPreparedProof } from './native-migration-proof.ts';
+import { type OwnerOnlyOptions } from './owner-only.ts';
 import type { NativePoolPaths } from './pool-paths.ts';
 declare const PHASES: readonly ['building', 'verified', 'activation-installed', 'committed', 'retired'];
 export type NativeMigrationPhase = (typeof PHASES)[number];
@@ -23,6 +24,7 @@ export interface NativeMigrationInput {
      * keeps native serving blocked until the separate vault activation commits.
      */
     activation?: 'requested';
+    nativeSettingsDigest?: string;
 }
 export interface NativeMigrationExpectations {
     expectedHostAuth: string;
@@ -97,8 +99,7 @@ export interface NativeCustodyActivationPlan {
 export type NativeCustodyActivation = {
     kind: 'requested';
 } | NativeCustodyActivationPlan;
-export interface NativeMigrationJournal {
-    version: 4;
+interface NativeMigrationRecord {
     storageId: string;
     host: 'opencode' | 'pi';
     phase: NativeMigrationPhase;
@@ -114,11 +115,27 @@ export interface NativeMigrationJournal {
      */
     activation: NativeCustodyActivation | null;
 }
+export type NativeLegacyMigrationJournal = NativeMigrationRecord & ({
+    version: 4;
+    kind?: never;
+} | {
+    version: 5;
+    kind: 'legacy-import';
+    nativeSettingsDigest: string;
+});
+export interface NativeEmptyInitJournal {
+    version: 5;
+    kind: 'empty-init';
+    storageId: string;
+    host: 'opencode';
+    phase: 'committed';
+}
+export type NativeMigrationJournal = NativeLegacyMigrationJournal | NativeEmptyInitJournal;
 export declare class NativeAuthorityError extends Error {
     readonly code: 'migration-required' | 'migration-incomplete' | 'invalid-journal' | 'journal-conflict';
     constructor(code: 'migration-required' | 'migration-incomplete' | 'invalid-journal' | 'journal-conflict');
 }
-export declare function readNativeMigrationJournal(paths: NativePoolPaths): Promise<NativeMigrationJournal | undefined>;
+export declare function readNativeMigrationJournal(paths: NativePoolPaths, ownership?: OwnerOnlyOptions): Promise<NativeMigrationJournal | undefined>;
 /**
  * The migration phase that authorizes serving, or undefined while the
  * migration or a requested switch to vault custody is unfinished. Every reader
@@ -137,23 +154,25 @@ interface JournalHooks {
     onWriteStep?: (step: 'before-write' | 'after-write', journal: NativeMigrationJournal) => Promise<void>;
 }
 /** Migration resume retains the original digests and resolved paths so a retry cannot adopt changed inputs or redirect writes. */
-export declare function beginNativeMigration(paths: NativePoolPaths, input: NativeMigrationInput, hooks?: JournalHooks): Promise<NativeMigrationJournal>;
+export declare function beginNativeMigration(paths: NativePoolPaths, input: NativeMigrationInput, hooks?: JournalHooks): Promise<NativeLegacyMigrationJournal>;
 /** Save the expected host-auth entry and routing digests together before changing files, so recovery can recognize completed writes. */
-export declare function recordNativeMigrationExpectations(paths: NativePoolPaths, expectations: NativeMigrationExpectations, hooks?: JournalHooks): Promise<NativeMigrationJournal>;
+export declare function recordNativeMigrationExpectations(paths: NativePoolPaths, expectations: NativeMigrationExpectations, hooks?: JournalHooks): Promise<NativeLegacyMigrationJournal>;
 /**
  * Advance one phase at a time. A retry of the same transition returns the journal.
  * Before recording activation, the caller must compare the host's Anthropic auth
  * entry and routing file with the saved expected values. This journal records the
  * migration stage; it does not read or verify those files.
  */
-export declare function advanceNativeMigration(paths: NativePoolPaths, expected: NativeMigrationPhase, next: NativeMigrationPhase, hooks?: JournalHooks): Promise<NativeMigrationJournal>;
+export declare function advanceNativeMigration(paths: NativePoolPaths, expected: NativeMigrationPhase, next: NativeMigrationPhase, hooks?: JournalHooks): Promise<NativeLegacyMigrationJournal>;
 /**
  * Record the prepared switch to vault custody on a retired migration. From
  * this write until the activation commits, the pool authorizes no serving.
  * Retrying with the identical plan returns the journal; any other plan is a
  * conflict, so a resumed setup can never replace what it recorded.
  */
-export declare function recordNativeCustodyActivation(paths: NativePoolPaths, plan: NativeCustodyActivationPlan, hooks?: JournalHooks): Promise<NativeMigrationJournal>;
+export declare function recordNativeCustodyActivation(paths: NativePoolPaths, plan: NativeCustodyActivationPlan, hooks?: JournalHooks): Promise<NativeLegacyMigrationJournal>;
 /** Advance a recorded activation one phase; never backwards or across a phase. */
-export declare function advanceNativeCustodyActivation(paths: NativePoolPaths, expected: NativeCustodyActivationPhase, next: NativeCustodyActivationPhase, hooks?: JournalHooks): Promise<NativeMigrationJournal>;
+export declare function advanceNativeCustodyActivation(paths: NativePoolPaths, expected: NativeCustodyActivationPhase, next: NativeCustodyActivationPhase, hooks?: JournalHooks): Promise<NativeLegacyMigrationJournal>;
+/** Publish local authority without inventing migration inputs or creating a pool. */
+export declare function beginNativeEmptyInit(paths: NativePoolPaths, hooks?: JournalHooks): Promise<NativeEmptyInitJournal>;
 export {};

package/dist/pool-paths.d.ts

@@ -8,6 +8,8 @@ export interface NativePoolPaths {
     roster: string;
     storageId: string;
 }
+/** Local hosts share the native pool's routing file unless explicitly overridden. */
+export declare function resolveLocalRoutingDestination(host: 'opencode' | 'pi', paths: NativePoolPaths, env: NodeJS.ProcessEnv): string;
 /**
  * Resolve existing parent aliases and nonexistent leaves without creating files.
  * This can follow a leaf symlink, so it does not establish configured-leaf safety.

package/dist/provider-error.d.ts

@@ -33,6 +33,39 @@ export declare const PROVIDER_ERROR_OVERSIZED_MESSAGE = "Provider error body exc
 export declare const PROVIDER_ERROR_MAX_BODY_BYTES: number;
 /** Largest SSE frame carried while looking for its end. */
 export declare const PROVIDER_ERROR_MAX_FRAME_BYTES: number;
+/**
+ * Error types kept in a generic replacement body. A closed list rather than
+ * a syntax check: an opaque credential can look like any identifier.
+ */
+declare const PROVIDER_ERROR_TYPES: readonly ['api_error', 'authentication_error', 'billing_error', 'invalid_request_error', 'not_found_error', 'overloaded_error', 'permission_error', 'rate_limit_error', 'relay_upstream_error', 'request_too_large', 'timeout_error'];
+type ProviderErrorType = (typeof PROVIDER_ERROR_TYPES)[number];
+declare const PREWARM_ERROR_MESSAGES: {
+    readonly http_validation: 'Provider rejected the prewarm request';
+    readonly http_error: 'Provider prewarm request failed';
+    readonly credential_unavailable: 'OAuth cache prewarm credential is unavailable';
+    readonly transport: 'Provider prewarm transport failed';
+    readonly withheld: 'Provider prewarm error details were withheld';
+    readonly parse_failure: 'Provider prewarm error response could not be parsed';
+};
+export type ProviderErrorSummary = {
+    status?: number;
+    provider_error: {
+        type: ProviderErrorType | 'unknown';
+        reason: keyof typeof PREWARM_ERROR_MESSAGES;
+        message: (typeof PREWARM_ERROR_MESSAGES)[keyof typeof PREWARM_ERROR_MESSAGES];
+    };
+};
+/**
+ * Prompt-safe prewarm metadata, not a replacement for per-send redaction.
+ * Read input.body from the response returned by ProviderErrorResponseScope's
+ * redactResponse, using a scope created for the physical request's credentials.
+ * Parsing is bounded independently; no provider text is copied to the result.
+ */
+export declare function summarizePrewarmProviderError(input: {
+    status?: number;
+    body?: string;
+    failure?: 'credential_unavailable' | 'transport';
+}): ProviderErrorSummary;
 /**
  * For producers of a non-2xx body, such as the relay, that stop buffering it
  * at PROVIDER_ERROR_MAX_BODY_BYTES: error the raw body stream with a new
@@ -137,3 +170,4 @@ export declare const PROVIDER_ERROR_RESPONSE_SCOPE_USED_MESSAGE = "Provider erro
  * once settled, `redactError` only returns a generic error.
  */
 export declare function createProviderErrorResponseScope(secrets: readonly string[], mode: ProviderResponseMode): ProviderErrorResponseScope;
+export {};

package/dist/publication-rename.d.ts

@@ -0,0 +1,11 @@
+/** Per-publication seams keep platform and sharing-failure tests out of process globals. */
+export interface PublicationOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly rename?: (from: string, to: string) => Promise<void>;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** Capture optional callbacks before staging I/O, just like the writer's other hooks. */
+export declare function capturePublicationOptions(options?: PublicationOptions): PublicationOptions;
+/** First publication is unconditional; only subsequent Windows sharing failures are retried. */
+export declare function renameWithWindowsSharingRetry(from: string, to: string, options?: PublicationOptions, beforeRetry?: () => Promise<'publish' | 'skip'>): Promise<'published' | 'skipped'>;

package/dist/quota-manager.d.ts

@@ -17,6 +17,13 @@ export type QuotaRefreshResult = {
     /** False when backoff or a cross-process lock served the existing cache. */
     fetched: boolean;
 };
+/**
+ * Why a quota reading is wanted, passed to fetchQuotaSnapshot unchanged.
+ * Vault custody uses it to decide whether insula's background quota cache
+ * may answer instead of a usage GET (see NativeVaultQuotaPurpose); omitted
+ * means poll the provider directly.
+ */
+export type QuotaReadingPurpose = 'background' | 'admission';
 /** Pace a physical usage GET and verify the selected credential is still eligible before sending. */
 export type QuotaRequestDispatch = (send: () => Promise<Response>, revalidate: () => Promise<void>) => Promise<Response>;
 export type QuotaManagerOptions = {
@@ -34,8 +41,17 @@ export type QuotaManagerOptions = {
         kind: 'main' | 'fallback';
         accountId: string | undefined;
         accessToken: string;
+        purpose?: QuotaReadingPurpose;
     }, dispatch: QuotaRequestDispatch) => Promise<OAuthQuotaSnapshot>;
     now?: () => number;
+    /**
+     * Waits before a physical usage GET until the minimum gap since the previous
+     * one has passed. It receives the milliseconds still to wait, measured with
+     * `now`, and is called only when that remainder is positive. Defaults to a
+     * real timer that does not keep the process alive. Tests pass one that
+     * records the requested wait and resolves at once.
+     */
+    pauseBetweenQuotaCalls?: (ms: number) => Promise<void>;
     onMainQuotaFetched?: (quota: OAuthQuotaSnapshot, checkedAt: number, tokenFingerprint: string, fetchStartedAt: number, quotaErrorGeneration: number, quotaErrorClearedAt: number | undefined) => void;
     onApiError?: (error: AccountOperationError, quotaErrorGeneration: number) => void;
     onFallbackQuotaFetched?: (accountId: string, quota: OAuthQuotaSnapshot, checkedAt: number, fetchStartedAt: number) => void;
@@ -66,6 +82,7 @@ export declare class QuotaManager {
     private readonly fetchImpl;
     private readonly fetchQuotaSnapshot;
     private readonly now;
+    private readonly pauseBetweenQuotaCalls;
     private readonly onMainQuotaFetched;
     private readonly onApiError;
     private readonly onFallbackQuotaFetched;
@@ -91,10 +108,10 @@ export declare class QuotaManager {
     clearFallback(accountId: string): void;
     pushMainFromHeaders(mainAccountId: string | undefined, incoming: OAuthQuotaSnapshot): QuotaEntry;
     pushFallbackFromHeaders(accountId: string, incoming: OAuthQuotaSnapshot, account: Pick<OAuthAccount, 'authLineageId'> | undefined): QuotaEntry | null;
-    refreshMain(mainAccountIdOrAccessToken: string | undefined, accessToken?: string, expectedIdentityGeneration?: number): Promise<OAuthQuotaSnapshot>;
-    refreshMainWithMetadata(mainAccountIdOrAccessToken: string | undefined, accessToken?: string, expectedIdentityGeneration?: number): Promise<QuotaRefreshResult>;
-    refreshFallback(accountId: string, accessToken: string, account: Pick<OAuthAccount, 'authLineageId'> | undefined): Promise<OAuthQuotaSnapshot>;
-    refreshFallbackWithMetadata(accountId: string, accessToken: string, account: Pick<OAuthAccount, 'authLineageId'> | undefined): Promise<QuotaRefreshResult>;
+    refreshMain(mainAccountIdOrAccessToken: string | undefined, accessToken?: string, expectedIdentityGeneration?: number, purpose?: QuotaReadingPurpose): Promise<OAuthQuotaSnapshot>;
+    refreshMainWithMetadata(mainAccountIdOrAccessToken: string | undefined, accessToken?: string, expectedIdentityGeneration?: number, purpose?: QuotaReadingPurpose): Promise<QuotaRefreshResult>;
+    refreshFallback(accountId: string, accessToken: string, account: Pick<OAuthAccount, 'authLineageId'> | undefined, purpose?: QuotaReadingPurpose): Promise<OAuthQuotaSnapshot>;
+    refreshFallbackWithMetadata(accountId: string, accessToken: string, account: Pick<OAuthAccount, 'authLineageId'> | undefined, purpose?: QuotaReadingPurpose): Promise<QuotaRefreshResult>;
     refreshAllFallbacks(accounts: OAuthAccount[], resolveAccessToken?: (account: OAuthAccount) => string | undefined): Promise<void>;
     /**
      * Fire-and-forget refresh. Does not await, swallows errors.

package/dist/quotas.d.ts

@@ -1,5 +1,35 @@
-import type { AccountStorage, OAuthQuotaSnapshot, QuotaMoney } from './accounts.ts';
+import { formatQuota, isQuotaStale, type ProjectedQuota, quotaTextParts, quotaWindowParts } from "./internal-types/quota/index.js";
+import type { AccountQuotaWindow, AccountScopedQuotaWindow, AccountStorage, OAuthExtraUsageSnapshot, OAuthQuotaSnapshot, QuotaMoney } from './accounts.ts';
 export declare const CLAUDE_QUOTAS_COMMAND_NAME = "claude-quota";
+export type { QuotaWindowPart } from "./internal-types/quota/index.js";
+export { formatQuota, isQuotaStale, quotaTextParts, quotaWindowParts };
+type DisplayWindow = Omit<AccountQuotaWindow, 'checkedAt'> & {
+    checkedAt?: number;
+};
+/** Sidebar files written by older versions may not retain reading times. */
+export type QuotaDisplaySnapshot = Pick<OAuthQuotaSnapshot, 'checkedAt' | 'extraUsage' | 'bindingWindow'> & {
+    five_hour?: DisplayWindow;
+    seven_day?: DisplayWindow;
+    scoped?: (Omit<AccountScopedQuotaWindow, 'checkedAt'> & DisplayWindow)[];
+};
+/** Adapt every reported window without projecting away other model families. */
+export declare function quotaDisplayProjection(snapshot: QuotaDisplaySnapshot | null | undefined, now: number): ProjectedQuota | undefined;
+export type QuotaMoneyFormat = {
+    /** Leave out the fractional digits, cutting the amount down to whole units. */
+    wholeUnits?: boolean;
+};
+/**
+ * A stored money amount in its own currency, such as `$25.00` or `€1,250.00`.
+ * An amount whose currency the runtime cannot format reads as its raw minor
+ * units and currency code.
+ */
+export declare function formatQuotaMoney(money: QuotaMoney, options?: QuotaMoneyFormat): string;
+/**
+ * The credit amounts shown after the shared credit figure: `$25.00/$100.00`
+ * (spent / monthly limit). Undefined when the limit is zero or either amount
+ * is missing or malformed, so the figure is then shown on its own.
+ */
+export declare function formatCreditAmounts(extraUsage: Partial<OAuthExtraUsageSnapshot> | null | undefined, options?: QuotaMoneyFormat): string | undefined;
 export type QuotaAccountSummary = {
     name: string;
     role: 'main' | 'fallback';
@@ -9,7 +39,6 @@ export type QuotaAccountSummary = {
     error?: string;
     tierLabel?: string;
 };
-export declare function formatQuotaMoney(money: QuotaMoney): string;
 export declare function buildFallbackQuotaSummaries(storage: AccountStorage | null, errors?: ReadonlyMap<string, string>): {
     name: string;
     role: 'fallback';

package/dist/relay.d.ts

@@ -6,6 +6,26 @@ export type RelayConfig = {
     fallbackToDirect: boolean;
     transport: 'http' | 'websocket';
 };
+/**
+ * The transport a stored relay configuration selects. A stored `http` or
+ * `websocket` value always wins. Without one (missing or unrecognized), the
+ * URL decides: a `ws://` or `wss://` URL selects WebSocket, so hand-edited
+ * WebSocket configurations keep working; any other URL selects HTTP, the
+ * documented default. Request dispatch and the relay status shown to users
+ * both call this, so they cannot report different transports.
+ */
+export declare function effectiveRelayTransport(stored: unknown, url: unknown): RelayConfig['transport'];
+/**
+ * Secret-free relay status for displays such as the OpenCode sidebar: the
+ * transport requests will use, or null when requests cannot use the relay
+ * because it is disabled, has no URL or has no token. Native account
+ * snapshots never carry the private token; they set `tokenConfigured` to say
+ * whether one is stored.
+ */
+export declare function effectiveRelayStatus(relay: AccountStorage['relay'] | undefined): {
+    enabled: true;
+    transport: RelayConfig['transport'];
+} | null;
 export type RelayPatch = {
     start: number;
     deleteCount: number;