@cortexkit/antigravity-auth-core 3.0.5 → 3.0.7

package/dist/common-auth-embedded/claustrum/consumer.js

@@ -1,8 +1,10 @@
 import { createLogger } from '../logger/index.js';
 import { combineAbortSignals } from '../util/any-signal.js';
 import { ClaustrumScopedCustody, decideScopedRetryAfter401, } from './custody.js';
+import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
-import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+import { acquireInsulaQuotaSource } from './insula.js';
+import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
 /**
  * One plugin host's view of its vault accounts. It turns vault credentials
  * into rows for `/routing`, authorizes each physical send with the vault, and
@@ -19,8 +21,14 @@ export class ClaustrumConsumer {
     #connecting;
     #refreshing;
     #roster;
+    /**
+     * The grants named by this instance's latest discovery, with the view that
+     * discovery committed. Memory only: the roster file never carries it.
+     */
+    #grantReach;
     #timer;
     #started = false;
+    #insula;
     constructor(options) {
         this.#options = options;
         this.#logger = options.logger ?? createLogger('claustrum');
@@ -84,6 +92,9 @@ export class ClaustrumConsumer {
                     now: this.#options.now,
                     logger: this.#logger,
                 });
+                if (this.#options.insula && client.insula) {
+                    this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
+                }
                 return this.#custody;
             })
                 .finally(() => {
@@ -96,6 +107,21 @@ export class ClaustrumConsumer {
     snapshot() {
         return this.#roster;
     }
+    /**
+     * What this consumer is granted, from its latest discovery, without any I/O.
+     * It explains an empty roster: `grants === 0` means no grant at all, while
+     * `grants > 0` means a grant that reaches no credential (`tuples` names its
+     * selector). Undefined means unknown, never zero: the vault or client is too
+     * old to send it, nothing was discovered yet, or the roster now in memory is
+     * a different view than the one this instance discovered (a peer process
+     * held the discovery lease and its newer roster was served instead).
+     */
+    grantReach() {
+        const latest = this.#grantReach;
+        return latest && this.#roster?.view === latest.view
+            ? latest.reach
+            : undefined;
+    }
     /** Rows for `/routing`, from the last committed roster. */
     routingRows() {
         return vaultRoutingRows(this.#roster);
@@ -107,14 +133,25 @@ export class ClaustrumConsumer {
         this.#refreshing = (async () => {
             if (!(await this.#active())) {
                 this.#roster = undefined;
+                this.#grantReach = undefined;
                 this.#custody?.close();
                 this.#custody = undefined;
+                this.#insula?.release();
+                this.#insula = undefined;
                 return undefined;
             }
             const custody = await this.#getCustody();
+            // Capture the inventory so its grant fields can be kept beside the roster;
+            // the roster file itself never stores them.
+            let discovered;
             const roster = await refreshVaultRoster({
                 path: this.#options.rosterPath,
-                custody,
+                custody: {
+                    discover: async (signal) => {
+                        discovered = await custody.discover(signal);
+                        return discovered;
+                    },
+                },
                 isActive: () => this.#active(),
                 signal: this.#shutdown.signal,
                 projection: () => ({
@@ -127,6 +164,13 @@ export class ClaustrumConsumer {
             this.#assertOpen();
             const changed = roster?.view !== this.#roster?.view;
             this.#roster = roster;
+            // Each discovery replaces the previous value, including with unknown. A
+            // refresh that served a peer's roster discovered nothing and leaves it;
+            // grantReach() hides it once the roster's view no longer matches.
+            if (discovered && roster?.view !== undefined)
+                this.#grantReach = discovered.grantReach
+                    ? { view: roster.view, reach: discovered.grantReach }
+                    : undefined;
             // Notify on view changes only: subscribers rewrite shared state on each
             // notification, and the poll runs every few seconds.
             if (roster && changed)
@@ -145,6 +189,7 @@ export class ClaustrumConsumer {
         const tick = async () => {
             try {
                 await this.refresh();
+                await this.refreshInsulaQuota();
             }
             catch (error) {
                 if (!this.#shutdown.signal.aborted)
@@ -163,6 +208,72 @@ export class ClaustrumConsumer {
         };
         void tick();
     }
+    /**
+     * Fetch on a background tick, at most once per minute across projects with
+     * the same daemon and enrollment token path. Admission must use the cache
+     * instead, so an optional quota daemon never delays a provider request.
+     */
+    async refreshInsulaQuota() {
+        if (!this.#options.insula ||
+            this.#shutdown.signal.aborted ||
+            !(await this.#active()))
+            return;
+        try {
+            await readClaustrumEnrollmentToken(this.#options.tokenPath);
+            await this.#getCustody();
+            await this.#insula?.source.refresh((this.#options.now ?? Date.now)());
+        }
+        catch {
+            // An optional source must never prevent the plugin's own quota poll.
+        }
+    }
+    /**
+     * Cache-only, for unknown-quota admission with a served receipt. Undefined
+     * means poll the provider normally. Only get_scoped's asserted account_id
+     * joins insula; parsed identities and display metadata cannot substitute.
+     * Background polling should use cachedInsulaQuotaForRoute instead.
+     */
+    async cachedInsulaQuota(receipt) {
+        if (!this.#options.insula ||
+            this.#shutdown.signal.aborted ||
+            !(await this.#active()))
+            return undefined;
+        try {
+            await readClaustrumEnrollmentToken(this.#options.tokenPath);
+            return this.#normalizeInsulaQuota(receipt.assertedAccountIdentity);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Background cache lookup without fetching a credential. Re-read the roster
+     * so a peer's account replacement invalidates the old route immediately.
+     * A route without a known provider account cannot join an insula entry.
+     */
+    async cachedInsulaQuotaForRoute(routeId) {
+        if (!this.#options.insula ||
+            this.#shutdown.signal.aborted ||
+            !(await this.#active()))
+            return undefined;
+        try {
+            await readClaustrumEnrollmentToken(this.#options.tokenPath);
+            const roster = await readVaultRoster(this.#options.rosterPath);
+            const row = roster?.rows.find((entry) => entry.routeId === routeId);
+            return this.#normalizeInsulaQuota(row?.accountIdentity);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    #normalizeInsulaQuota(accountIdentity) {
+        if (!this.#options.insula || !accountIdentity)
+            return undefined;
+        const current = this.#insula?.source.current(this.#options.insula.provider, accountIdentity, (this.#options.now ?? Date.now)());
+        return current
+            ? this.#options.insula.normalize(current.entry, current.context)
+            : undefined;
+    }
     /**
      * Authorize one physical send on a vault route. The roster file is re-read
      * first, so a decline committed by another process applies before the next
@@ -285,6 +396,24 @@ export class ClaustrumConsumer {
             this.#roster = await readVaultRoster(this.#options.rosterPath);
         return kept;
     }
+    /**
+     * Store a background observation that belongs to an account rather than to
+     * a served credential (an insula reading from `cachedInsulaQuotaForRoute`).
+     * It lands only while the route is still bound to that known account, so no
+     * credential fetch is needed and a replaced account's reading is dropped.
+     * The in-memory roster is reloaded from the file, without a vault call.
+     */
+    async recordAccountQuota(routeId, accountIdentity, observation) {
+        this.#assertOpen();
+        const kept = await recordVaultAccountQuota(this.#options.rosterPath, {
+            routeId,
+            accountIdentity,
+            observation,
+        });
+        if (kept)
+            this.#roster = await readVaultRoster(this.#options.rosterPath);
+        return kept;
+    }
     close() {
         if (this.#shutdown.signal.aborted)
             return;
@@ -293,6 +422,9 @@ export class ClaustrumConsumer {
             (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
         this.#timer = undefined;
         this.#custody?.close();
+        this.#insula?.release();
+        this.#insula = undefined;
         this.#roster = undefined;
+        this.#grantReach = undefined;
     }
 }

package/dist/common-auth-embedded/claustrum/custody.d.ts

@@ -1,6 +1,9 @@
 import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
 import { type ClaustrumLogger } from './errors.js';
-export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'>;
+import type { InsulaUsageTransport } from './insula.js';
+export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
+    insula?: InsulaUsageTransport;
+};
 /** The two credential types a plugin's family can hold; routing differs by type. */
 export type VaultCredentialType = 'oauth' | 'api_key';
 /**
@@ -41,6 +44,30 @@ export interface SkippedVaultRecord {
     readonly credentialId?: string;
     readonly reason: SkippedVaultReason;
 }
+/**
+ * One grant this consumer's enrollment holds, as the vault's list reply names
+ * it: for example `{ selectorKind: 'category', selector: 'openai-native',
+ * operation: 'read' }`. `selectorKind` is `exact` (the selector is a credential
+ * id) or `category` (a bare category name); both open strings.
+ */
+export interface VaultGrantTuple {
+    readonly selectorKind: string;
+    readonly selector: string;
+    readonly operation: string;
+}
+/**
+ * What this consumer is granted, independent of what those grants currently
+ * reach. It is what tells two empty listings apart: no rows with `grants === 0`
+ * means no grant at all (the fix is `ck auth grant`), while no rows with
+ * `grants > 0` means a grant that reaches no credential, usually logins that
+ * lack the category (`ck auth reclassify --from-registry`); `tuples` names the
+ * selector that matched nothing. Never written to the roster file.
+ */
+export interface VaultGrantReach {
+    /** How many grants the consumer holds, deposit grants excluded. */
+    readonly grants: number;
+    readonly tuples: readonly VaultGrantTuple[];
+}
 export interface VaultInventory {
     /**
      * The vault's change cursor: a digest over exactly what this consumer can see
@@ -50,6 +77,11 @@ export interface VaultInventory {
     readonly view: string;
     readonly credentials: readonly VaultCredential[];
     readonly skipped: readonly SkippedVaultRecord[];
+    /**
+     * The consumer's grants, as the vault's list reply named them. Undefined means unknown
+     * (the vault or client predates the fields), never zero grants.
+     */
+    readonly grantReach?: VaultGrantReach;
 }
 export interface ClaustrumScopedIdentity {
     readonly credentialId: string;

package/dist/common-auth-embedded/claustrum/custody.js

@@ -83,6 +83,21 @@ function credentialTypeOf(row, family) {
         return row.refreshAdapter === undefined ? 'api_key' : undefined;
     return undefined;
 }
+/**
+ * The grants named in the vault's list reply, or undefined when it names none.
+ * Both fields must be present: a reply carrying only one of them is treated as
+ * unknown rather than completed with a guess. claustrum-client already refuses
+ * a malformed value, so nothing here validates it again.
+ */
+function grantReachOf(listed) {
+    const { grants, grantTuples } = listed;
+    if (grants === undefined || grantTuples === undefined)
+        return undefined;
+    return Object.freeze({
+        grants,
+        tuples: Object.freeze(grantTuples.map(({ selectorKind, selector, operation }) => Object.freeze({ selectorKind, selector, operation }))),
+    });
+}
 /**
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
  * enrollment token as authorization. Used by every host of a plugin. There is
@@ -217,10 +232,12 @@ export class ClaustrumScopedCustody {
         }
         for (const record of skipped)
             this.#logger.warn('skipped malformed vault record', record);
+        const grantReach = grantReachOf(inventory);
         return {
             view: inventory.view,
             credentials: Object.freeze(credentials),
             skipped: Object.freeze(skipped),
+            ...(grantReach && { grantReach }),
         };
     }
     /**

package/dist/common-auth-embedded/claustrum/enrollment.d.ts

@@ -103,7 +103,12 @@ export interface EnrollmentAncestorOptions {
  */
 export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
 export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentStatus>;
-/** Resolve the host's account mode from its enrollment files without writing. */
+/**
+ * Resolve the host's account mode from its enrollment files. It never changes
+ * their contents or the host's mode. On Windows, reading them may create a
+ * missing private state folder and tighten an enrollment file's permissions to
+ * owner-only, as every private-file read there does.
+ */
 export declare function enrollmentAuthority(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<'vault' | 'local' | 'unreadable'>;
 /**
  * Read fresh bearer material for one scoped operation; never publish it.

package/dist/common-auth-embedded/claustrum/enrollment.js

@@ -419,7 +419,12 @@ export async function readClaustrumEnrollmentStatus(paths, proposedName) {
     }
     return statusFromState(state);
 }
-/** Resolve the host's account mode from its enrollment files without writing. */
+/**
+ * Resolve the host's account mode from its enrollment files. It never changes
+ * their contents or the host's mode. On Windows, reading them may create a
+ * missing private state folder and tighten an enrollment file's permissions to
+ * owner-only, as every private-file read there does.
+ */
 export async function enrollmentAuthority(paths, proposedName) {
     let status;
     try {

package/dist/common-auth-embedded/claustrum/index.d.ts

@@ -2,12 +2,13 @@ import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import type { ClaustrumScopedClient } from './custody.js';
 export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
 export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
-export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
 export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
 export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export type { InsulaQuotaContext, InsulaQuotaOptions, InsulaUsageEntry, InsulaUsageTransport, InsulaUsageWindow, } from './insula.js';
 export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
-export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library

package/dist/common-auth-embedded/claustrum/index.js

@@ -4,6 +4,7 @@
 // declined-account interlock and the host-slot guard. Needs the optional
 // peer `@cortexkit/claustrum-client`.
 import { ClaustrumClient, } from '@cortexkit/claustrum-client';
+import { insulaUsageTransport } from './insula.js';
 export { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
 export { ClaustrumConsumer, } from './consumer.js';
 export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, SERVING_MARGIN_MS, } from './custody.js';
@@ -11,12 +12,13 @@ export { ClaustrumEnrollmentManager, classifyEnrollmentError, connectClaustrumEn
 export { ClaustrumConsumerError, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
 export { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
-export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
+export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library
  * reads no environment, so the plugin resolves the vault's connection file.
  */
-export function connectClaustrumScopedClient(options) {
-    return ClaustrumClient.connect(options);
+export async function connectClaustrumScopedClient(options) {
+    const client = await ClaustrumClient.connect(options);
+    return Object.assign(client, { insula: insulaUsageTransport(options) });
 }

package/dist/common-auth-embedded/claustrum/insula.d.ts

@@ -0,0 +1,69 @@
+import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+/** Insula's window fields are open: plugins choose which limits they understand. */
+export interface InsulaUsageWindow {
+    usedPercent: number;
+    rawUsedPercent?: number;
+    resetsAt?: string;
+    windowMinutes?: number;
+    windowKind?: string;
+    [field: string]: unknown;
+}
+export interface InsulaUsageEntry {
+    provider: string;
+    account?: string;
+    fetchedAt?: string;
+    source?: string;
+    stale?: unknown;
+    errorClass?: unknown;
+    usage?: {
+        primary?: InsulaUsageWindow;
+        secondary?: InsulaUsageWindow;
+        tertiary?: InsulaUsageWindow;
+        extraRateWindows?: Array<{
+            id?: string;
+            title?: string;
+            window?: InsulaUsageWindow;
+        }>;
+        [field: string]: unknown;
+    };
+    [field: string]: unknown;
+}
+export interface InsulaQuotaContext {
+    /** Milliseconds since the epoch, parsed from the producer's fetchedAt. */
+    fetchedAt: number;
+    source?: string;
+}
+export interface InsulaQuotaOptions<Q> {
+    provider: 'codex' | 'claude' | 'antigravity';
+    /**
+     * Set every converted window's reading time to context.fetchedAt, not poll
+     * time. Return undefined for entries the plugin cannot use. Antigravity can
+     * receive its own sidebar reading back from insula: accept it only from the
+     * vault or when fetchedAt is newer than the plugin's last reading.
+     */
+    normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
+}
+/** Optional transport for custom scoped clients; getUsage must not retry refusals. */
+export interface InsulaUsageTransport {
+    connectionFile: string;
+    getUsage(): Promise<unknown>;
+}
+/** Constructing this transport opens no connection; getUsage opens one per call. */
+export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): InsulaUsageTransport;
+export declare class InsulaQuotaSource {
+    #private;
+    private readonly transport;
+    private readonly key;
+    constructor(transport: InsulaUsageTransport, key: string);
+    refresh(now: number): Promise<void>;
+    current(provider: string, accountId: string, now: number): {
+        entry: InsulaUsageEntry;
+        context: InsulaQuotaContext;
+    } | undefined;
+}
+export declare function acquireInsulaQuotaSource(transport: InsulaUsageTransport, tokenPath: string): {
+    source: InsulaQuotaSource;
+    release(): void;
+};

package/dist/common-auth-embedded/claustrum/insula.js

@@ -0,0 +1,152 @@
+import { resolve } from 'node:path';
+import { storeIdentity } from '@cortexkit/claustrum-client';
+// A static import: claustrum-client already loads subc-client whenever
+// /claustrum is imported, so loading it lazily saves nothing, and a dynamic
+// import makes bundlers emit a separate chunk that a running host loses when
+// its dist folder is rebuilt underneath it.
+import { SubcClient } from '@cortexkit/subc-client';
+/** Constructing this transport opens no connection; getUsage opens one per call. */
+export function insulaUsageTransport(options) {
+    const identity = options.identity ??
+        storeIdentity(options.projectRoot ?? process.cwd(), options.storagePath ?? process.cwd());
+    return {
+        connectionFile: options.connectionFile,
+        async getUsage() {
+            let client;
+            let expired = false;
+            let timer;
+            const timeout = new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('insula usage timeout')), 3_000);
+                timer.unref?.();
+            });
+            const request = (async () => {
+                client = options.connector
+                    ? await options.connector({
+                        connectionFile: options.connectionFile,
+                        handshakeTimeoutMs: Math.min(options.handshakeTimeoutMs ?? 3_000, 3_000),
+                    })
+                    : await SubcClient.connect({
+                        connectionFile: options.connectionFile,
+                        handshakeTimeoutMs: Math.min(options.handshakeTimeoutMs ?? 3_000, 3_000),
+                    });
+                // A slow connector may resolve after the whole-call deadline. It still
+                // owns a socket, which must not survive or open a route after fallback.
+                if (expired) {
+                    client.close();
+                    throw new Error('insula usage timeout');
+                }
+                // Managed call() retries warming routes. A single routeOpen/request
+                // instead lets the plugin fall back as soon as the daemon refuses.
+                const route = await client.routeOpen({ kind: 'management_surface', module_id: 'insula' }, identity);
+                return await client.request(route, { method: 'usage.get', params: {} });
+            })();
+            try {
+                return await Promise.race([request, timeout]);
+            }
+            finally {
+                expired = true;
+                clearTimeout(timer);
+                client?.close();
+            }
+        },
+    };
+}
+const MINUTE = 60_000;
+const MAX_AGE = 4 * MINUTE;
+const sources = new Map();
+// Keep only the minute budget after the last owner closes, so project churn
+// cannot reset the bound. Expired budgets are pruned on the next tick.
+const attempts = new Map();
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export class InsulaQuotaSource {
+    transport;
+    key;
+    #entries = [];
+    #pending;
+    constructor(transport, key) {
+        this.transport = transport;
+        this.key = key;
+    }
+    refresh(now) {
+        if (this.#pending)
+            return this.#pending;
+        for (const [key, time] of attempts) {
+            if (now - time >= MINUTE)
+                attempts.delete(key);
+        }
+        const lastAttempt = attempts.get(this.key);
+        if (lastAttempt !== undefined && now - lastAttempt < MINUTE)
+            return Promise.resolve();
+        // Reserve the minute before I/O, so concurrent projects cannot each poll.
+        attempts.set(this.key, now);
+        this.#pending = (async () => {
+            try {
+                const reply = await this.transport.getUsage();
+                if (!record(reply) ||
+                    !Array.isArray(reply.result) ||
+                    reply.error !== undefined)
+                    throw new Error('unavailable insula usage');
+                // Each response is a snapshot, not a delta. Missing accounts fall back;
+                // neither pending nor the entry count asserts provider completeness.
+                this.#entries = reply.result.filter((entry) => record(entry) && typeof entry.provider === 'string');
+            }
+            catch {
+                // Refusal is absence, even if the previous reading was still young.
+                this.#entries = [];
+            }
+        })().finally(() => {
+            this.#pending = undefined;
+        });
+        return this.#pending;
+    }
+    current(provider, accountId, now) {
+        for (const entry of this.#entries) {
+            if (entry.provider !== provider ||
+                typeof entry.account !== 'string' ||
+                entry.account.trim() !== accountId)
+                continue;
+            if (entry.stale !== undefined ||
+                entry.errorClass !== undefined ||
+                !record(entry.usage))
+                continue;
+            const fetchedAt = typeof entry.fetchedAt === 'string'
+                ? Date.parse(entry.fetchedAt)
+                : Number.NaN;
+            if (!Number.isFinite(fetchedAt) || now - fetchedAt >= MAX_AGE)
+                continue;
+            return {
+                entry,
+                context: {
+                    fetchedAt,
+                    ...(typeof entry.source === 'string' && { source: entry.source }),
+                },
+            };
+        }
+        return undefined;
+    }
+}
+export function acquireInsulaQuotaSource(transport, tokenPath) {
+    const key = JSON.stringify([
+        resolve(transport.connectionFile),
+        resolve(tokenPath),
+    ]);
+    let shared = sources.get(key);
+    if (!shared) {
+        shared = { source: new InsulaQuotaSource(transport, key), refs: 0 };
+        sources.set(key, shared);
+    }
+    shared.refs++;
+    let released = false;
+    return {
+        source: shared.source,
+        release() {
+            if (released)
+                return;
+            released = true;
+            if (--shared.refs === 0)
+                sources.delete(key);
+        },
+    };
+}

package/dist/common-auth-embedded/claustrum/roster.d.ts

@@ -133,6 +133,19 @@ export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
     routeId: string;
     observation: QuotaObservation;
 }): Promise<boolean>;
+/**
+ * Merge a quota observation that belongs to an account rather than to a
+ * served credential, such as a background reading from insula. The write
+ * lands only while the row is still bound to that exact known account, so a
+ * reading taken before a replacement never reaches the successor. Unlike
+ * `recordVaultQuota` it never binds an account: a row without a known account
+ * is refused. Returns whether the observation was kept.
+ */
+export declare function recordVaultAccountQuota(path: string, input: {
+    routeId: string;
+    accountIdentity: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
 /**
  * Discover and commit the roster. The lease covers the list call and the
  * commit, not just the write: an opaque view cannot tell a delayed old reply