@cortexkit/antigravity-auth-core 3.0.7 → 3.0.8

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

@@ -0,0 +1,89 @@
+import { ClaustrumConsumerError } from './errors.js';
+export type VaultFailureClass = 'unreachable' | 'answered';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export declare const VAULT_FAILURE_CLASSES: Readonly<{
+    ECONNREFUSED: "unreachable";
+    ENOENT: "unreachable";
+    ECONNRESET: "unreachable";
+    EPIPE: "unreachable";
+    ETIMEDOUT: "unreachable";
+    transport_error: "unreachable";
+    unavailable: "unreachable";
+    timeout: "unreachable";
+    route_closed: "unreachable";
+    daemon_draining: "unreachable";
+    connection_closed: "unreachable";
+    connection_dropped: "unreachable";
+    request_deadline: "unreachable";
+    deadline_exceeded_no_drop_observed: "unreachable";
+    module_reloading: "unreachable";
+    module_warming: "unreachable";
+    target_unavailable: "unreachable";
+    module_timeout: "unreachable";
+    invalid_response: "answered";
+    invalid_record_version: "answered";
+    invalid_expiry: "answered";
+    invalid_status: "answered";
+    invalid_params: "answered";
+    ttl_unsatisfiable: "answered";
+    not_found: "answered";
+    enrollment_revoked: "answered";
+    enrollment_invalid: "answered";
+    grant_denied: "answered";
+    credential_unavailable: "answered";
+    needs_reauth: "answered";
+    declined: "answered";
+    disabled: "answered";
+    identity_changed: "answered";
+    closed: "answered";
+    client_closed: "answered";
+    pending_exists: "answered";
+    pending_queue_full: "answered";
+    already_consumed: "answered";
+    superseded: "answered";
+    stale_generation: "answered";
+    missing_identity: "answered";
+    invalid_control_body: "answered";
+    unknown_module: "answered";
+    module_removed: "answered";
+    capability_denied: "answered";
+    unknown_channel: "unreachable";
+    stale_route_epoch: "unreachable";
+    capability_forbidden: "answered";
+    capability_unprovided: "answered";
+    capability_ambiguous: "answered";
+    invalid_capability_identifier: "answered";
+    binary_body_required: "answered";
+    binary_call_requires_call_binary: "answered";
+    corr_exhausted: "answered";
+    late_route_cleanup_failed: "answered";
+    reverse_request_capability_not_declared: "answered";
+    stale_route_handle: "answered";
+    reverse_request_unhandled: "answered";
+    handler_error: "answered";
+    health_error: "answered";
+    duplicate_module_id: "answered";
+    route_rejected: "answered";
+    lock_busy: "answered";
+    owner_invalid: "answered";
+    renewal_failed: "answered";
+    unsupported_platform: "answered";
+    EACCES: "answered";
+    EPERM: "answered";
+    ERR_PRIVATE_FILES_SECURITY: "answered";
+}>;
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor();
+}
+export declare function classifyVaultFailure(error: unknown): VaultFailureClass;

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

@@ -0,0 +1,106 @@
+import { ClaustrumCredentialError } from '@cortexkit/claustrum-client';
+import { SocketClosedError, SocketTimeoutError, SubcCallError, } from '@cortexkit/subc-client';
+import { ClaustrumConsumerError } from './errors.js';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export const VAULT_FAILURE_CLASSES = Object.freeze({
+    ECONNREFUSED: 'unreachable',
+    ENOENT: 'unreachable',
+    ECONNRESET: 'unreachable',
+    EPIPE: 'unreachable',
+    ETIMEDOUT: 'unreachable',
+    transport_error: 'unreachable',
+    unavailable: 'unreachable',
+    timeout: 'unreachable',
+    route_closed: 'unreachable',
+    daemon_draining: 'unreachable',
+    connection_closed: 'unreachable',
+    connection_dropped: 'unreachable',
+    request_deadline: 'unreachable',
+    deadline_exceeded_no_drop_observed: 'unreachable',
+    module_reloading: 'unreachable',
+    module_warming: 'unreachable',
+    target_unavailable: 'unreachable',
+    module_timeout: 'unreachable',
+    invalid_response: 'answered',
+    invalid_record_version: 'answered',
+    invalid_expiry: 'answered',
+    invalid_status: 'answered',
+    invalid_params: 'answered',
+    ttl_unsatisfiable: 'answered',
+    not_found: 'answered',
+    enrollment_revoked: 'answered',
+    enrollment_invalid: 'answered',
+    grant_denied: 'answered',
+    credential_unavailable: 'answered',
+    needs_reauth: 'answered',
+    declined: 'answered',
+    disabled: 'answered',
+    identity_changed: 'answered',
+    closed: 'answered',
+    client_closed: 'answered',
+    pending_exists: 'answered',
+    pending_queue_full: 'answered',
+    already_consumed: 'answered',
+    superseded: 'answered',
+    stale_generation: 'answered',
+    missing_identity: 'answered',
+    invalid_control_body: 'answered',
+    unknown_module: 'answered',
+    module_removed: 'answered',
+    capability_denied: 'answered',
+    unknown_channel: 'unreachable',
+    stale_route_epoch: 'unreachable',
+    capability_forbidden: 'answered',
+    capability_unprovided: 'answered',
+    capability_ambiguous: 'answered',
+    invalid_capability_identifier: 'answered',
+    binary_body_required: 'answered',
+    binary_call_requires_call_binary: 'answered',
+    corr_exhausted: 'answered',
+    late_route_cleanup_failed: 'answered',
+    reverse_request_capability_not_declared: 'answered',
+    stale_route_handle: 'answered',
+    reverse_request_unhandled: 'answered',
+    handler_error: 'answered',
+    health_error: 'answered',
+    duplicate_module_id: 'answered',
+    route_rejected: 'answered',
+    lock_busy: 'answered',
+    owner_invalid: 'answered',
+    renewal_failed: 'answered',
+    unsupported_platform: 'answered',
+    EACCES: 'answered',
+    EPERM: 'answered',
+    ERR_PRIVATE_FILES_SECURITY: 'answered',
+});
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor() {
+        super('unavailable', 'Claustrum scoped operation unavailable');
+        this.name = 'ClaustrumUnreachableError';
+    }
+}
+export function classifyVaultFailure(error) {
+    if (error instanceof ClaustrumUnreachableError ||
+        error instanceof SocketClosedError ||
+        error instanceof SocketTimeoutError)
+        return 'unreachable';
+    const code = error instanceof ClaustrumCredentialError || error instanceof SubcCallError
+        ? error.code
+        : error instanceof Error && 'code' in error
+            ? error.code
+            : undefined;
+    if (typeof code !== 'string' || !Object.hasOwn(VAULT_FAILURE_CLASSES, code))
+        return 'answered';
+    return VAULT_FAILURE_CLASSES[code];
+}

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

@@ -1,10 +1,11 @@
 import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
 import type { QuotaObservation } from '../quota/index.js';
 import type { RoutingRow } from '../routing/index.js';
-import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type VaultGrantReach } from './custody.js';
+import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
 import { type ClaustrumLogger } from './errors.js';
 import { type InsulaQuotaOptions } from './insula.js';
 import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
 export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /**
      * The roster file: one row per vault account (route id, credential id,
@@ -41,6 +42,12 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
      */
     onRoster?: (roster: VaultRosterFile) => void;
     onError?: (error: unknown) => void;
+    /**
+     * How often `start()` ticks. A tick lists the vault when no vault watch is
+     * open (before it is accepted, or when the vault or the client cannot
+     * watch), and otherwise only every five minutes, as a safety net. A tick
+     * polls insula (at most once a minute) only while its watch is not open.
+     */
     pollIntervalMs?: number;
     setTimeoutImpl?: typeof setTimeout;
     clearTimeoutImpl?: typeof clearTimeout;
@@ -49,6 +56,15 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /** Optional background quota source. In-band readings still use recordQuota. */
     insula?: InsulaQuotaOptions<Q>;
 }
+/**
+ * How a started consumer learns about changes, for logs and status displays.
+ * `insula` is present when the consumer was given an insula source. Never
+ * carries secrets.
+ */
+export interface ClaustrumWatchState {
+    readonly vault: WatchMode;
+    readonly insula?: WatchMode;
+}
 export interface SendOptions {
     /**
      * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -81,9 +97,23 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
      * held the discovery lease and its newer roster was served instead).
      */
     grantReach(): VaultGrantReach | undefined;
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState(): ClaustrumWatchState;
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState(): KeptReceiptState;
     /** Rows for `/routing`, from the last committed roster. */
     routingRows(): RoutingRow[];
     refresh(): Promise<VaultRosterFile | undefined>;
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
     start(): void;
     /**
      * Fetch on a background tick, at most once per minute across projects with

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

@@ -5,6 +5,7 @@ import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { acquireInsulaQuotaSource } from './insula.js';
 import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+import { SAFETY_POLL_MS } from './watch.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
@@ -29,6 +30,10 @@ export class ClaustrumConsumer {
     #timer;
     #started = false;
     #insula;
+    #vaultWatch;
+    #releaseInsulaWatch;
+    /** When this instance last completed a discovery, by `now`. */
+    #discoveredAt;
     constructor(options) {
         this.#options = options;
         this.#logger = options.logger ?? createLogger('claustrum');
@@ -91,6 +96,8 @@ export class ClaustrumConsumer {
                     requireAssertion: this.#options.requireAssertion,
                     now: this.#options.now,
                     logger: this.#logger,
+                    setTimeoutImpl: this.#options.setTimeoutImpl,
+                    clearTimeoutImpl: this.#options.clearTimeoutImpl,
                 });
                 if (this.#options.insula && client.insula) {
                     this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
@@ -122,6 +129,27 @@ export class ClaustrumConsumer {
             ? latest.reach
             : undefined;
     }
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState() {
+        return Object.freeze({
+            vault: this.#vaultWatch?.mode ?? 'polling',
+            ...(this.#options.insula && {
+                insula: this.#insula?.source.watchMode() ?? 'polling',
+            }),
+        });
+    }
+    /** Close the watches with the connection they belong to. */
+    #stopWatch() {
+        this.#vaultWatch?.close();
+        this.#vaultWatch = undefined;
+        this.#releaseInsulaWatch?.();
+        this.#releaseInsulaWatch = undefined;
+    }
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState() {
+        return (this.#custody?.keptReceiptState() ??
+            Object.freeze({ active: false, since: null }));
+    }
     /** Rows for `/routing`, from the last committed roster. */
     routingRows() {
         return vaultRoutingRows(this.#roster);
@@ -134,6 +162,7 @@ export class ClaustrumConsumer {
             if (!(await this.#active())) {
                 this.#roster = undefined;
                 this.#grantReach = undefined;
+                this.#stopWatch();
                 this.#custody?.close();
                 this.#custody = undefined;
                 this.#insula?.release();
@@ -164,6 +193,7 @@ export class ClaustrumConsumer {
             this.#assertOpen();
             const changed = roster?.view !== this.#roster?.view;
             this.#roster = roster;
+            custody.retain(roster?.rows ?? []);
             // 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.
@@ -175,12 +205,23 @@ export class ClaustrumConsumer {
             // notification, and the poll runs every few seconds.
             if (roster && changed)
                 this.#options.onRoster?.(roster);
+            this.#discoveredAt = (this.#options.now ?? Date.now)();
             return roster;
         })().finally(() => {
             this.#refreshing = undefined;
         });
         return this.#refreshing;
     }
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
     start() {
         if (this.#started)
             return;
@@ -188,8 +229,10 @@ export class ClaustrumConsumer {
         this.#started = true;
         const tick = async () => {
             try {
-                await this.refresh();
+                if (await this.#listDue())
+                    await this.refresh();
                 await this.refreshInsulaQuota();
+                this.#openWatch();
             }
             catch (error) {
                 if (!this.#shutdown.signal.aborted)
@@ -208,6 +251,53 @@ export class ClaustrumConsumer {
         };
         void tick();
     }
+    /** Whether a background tick must list the vault now. */
+    async #listDue() {
+        if (this.#vaultWatch?.mode !== 'watching')
+            return true;
+        const now = (this.#options.now ?? Date.now)();
+        if (this.#discoveredAt === undefined ||
+            now - this.#discoveredAt >= SAFETY_POLL_MS)
+            return true;
+        // refresh() is what closes the connection when the host left vault mode.
+        return !(await this.#active());
+    }
+    /**
+     * Open the vault and insula watches once a vault connection exists. Only
+     * reached in vault mode: a host in local mode never connects.
+     */
+    #openWatch() {
+        const custody = this.#custody;
+        if (this.#shutdown.signal.aborted || !custody)
+            return;
+        // The same entry point a host without a consumer uses, so both apply
+        // notices, refusals and outages alike.
+        this.#vaultWatch ??= custody.watchRoster({
+            view: () => this.#roster?.view,
+            // The existing discovery, so a watched change commits the roster and
+            // re-applies it to kept receipts exactly as a poll does. A refresh
+            // already in flight may have listed before the change was announced,
+            // so wait for it and list again.
+            onView: async () => {
+                while (this.#refreshing)
+                    await this.#refreshing.catch(() => { });
+                await this.refresh();
+            },
+            // Custody has dropped kept receipts, as a poll meeting the same
+            // refusal from list_scoped would.
+            onRefused: (error) => this.#options.onError?.(error),
+            onError: (error) => {
+                if (!this.#shutdown.signal.aborted)
+                    this.#options.onError?.(error);
+            },
+        });
+        if (this.#options.insula && this.#insula && !this.#releaseInsulaWatch)
+            this.#releaseInsulaWatch = this.#insula.source.watch({
+                provider: this.#options.insula.provider,
+                setTimeoutImpl: this.#options.setTimeoutImpl,
+                clearTimeoutImpl: this.#options.clearTimeoutImpl,
+            });
+    }
     /**
      * 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
@@ -282,20 +372,33 @@ export class ClaustrumConsumer {
     async authorize(routeId, signal) {
         this.#assertOpen(signal);
         const roster = this.#roster ?? (await this.#wait(this.refresh(), signal));
-        if (!roster || !(await this.#active()))
+        if (!roster || !(await this.#active())) {
+            this.#custody?.close();
+            this.#custody = undefined;
+            this.#stopWatch();
+            this.#insula?.release();
+            this.#insula = undefined;
             throw new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
+        }
         const current = await readVaultRoster(this.#options.rosterPath);
         this.#assertOpen(signal);
         const observed = roster.rows.find((row) => row.routeId === routeId);
         const configured = current?.rows.find((row) => row.routeId === routeId);
-        if (configured && !configured.enabled)
+        if (configured && !configured.enabled) {
+            if (observed)
+                this.#custody?.forget(observed.credentialId);
             throw new ClaustrumConsumerError('route-declined', 'Claustrum route is disabled');
+        }
         if (!observed ||
             !configured ||
             configured.state !== 'active' ||
             configured.credentialId !== observed.credentialId ||
-            configured.accountIdentity !== observed.accountIdentity)
+            configured.accountIdentity !== observed.accountIdentity ||
+            configured.credentialType !== observed.credentialType) {
+            if (observed)
+                this.#custody?.forget(observed.credentialId);
             throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is disabled, removed or changed');
+        }
         const custody = await this.#wait(this.#getCustody(), signal);
         const combined = combineAbortSignals([
             this.#shutdown.signal,
@@ -308,7 +411,7 @@ export class ClaustrumConsumer {
                 ...(configured.accountIdentity !== undefined && {
                     accountIdentity: configured.accountIdentity,
                 }),
-            }, combined.signal);
+            }, combined.signal, routeId);
         }
         finally {
             combined.dispose();
@@ -332,6 +435,10 @@ export class ClaustrumConsumer {
         const signal = options.signal;
         let served = await this.authorize(routeId, signal);
         let response = await dispatch(served, signal);
+        if (response.status === 401 && served.fromKeptReceipt) {
+            await this.reportFailure(served, 401, options.reporterSource ?? 'direct');
+            return response;
+        }
         if (response.status === 401 && !signal?.aborted) {
             let current;
             try {
@@ -366,6 +473,7 @@ export class ClaustrumConsumer {
         this.#assertOpen();
         await declineVaultRoute(this.#options.rosterPath, routeId);
         this.#roster = await readVaultRoster(this.#options.rosterPath);
+        this.#custody?.retain(this.#roster?.rows ?? []);
     }
     async accept(routeId) {
         this.#assertOpen();
@@ -421,6 +529,7 @@ export class ClaustrumConsumer {
         if (this.#timer)
             (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
         this.#timer = undefined;
+        this.#stopWatch();
         this.#custody?.close();
         this.#insula?.release();
         this.#insula = undefined;

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

@@ -1,9 +1,14 @@
 import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
 import { type ClaustrumLogger } from './errors.js';
 import type { InsulaUsageTransport } from './insula.js';
+import { type ScopedWatchSource, type WatchMode } from './watch.js';
+/**
+ * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
+ * run time and keep polling without it.
+ */
 export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
     insula?: InsulaUsageTransport;
-};
+} & ScopedWatchSource;
 /** The two credential types a plugin's family can hold; routing differs by type. */
 export type VaultCredentialType = 'oauth' | 'api_key';
 /**
@@ -132,6 +137,57 @@ export interface ClaustrumScopedAttempt {
     readonly accessToken: string;
     readonly recordVersion: number;
     readonly expiresAtMs: number | null;
+    /**
+     * True when this receipt was not freshly served but is the last token kept
+     * from an earlier read, used because the vault could not be reached. A 401
+     * with such a receipt must not be retried and is not reported to the vault,
+     * which is unreachable.
+     */
+    readonly fromKeptReceipt?: true;
+}
+export interface KeptReceiptState {
+    readonly active: boolean;
+    readonly since: number | null;
+}
+export interface ClaustrumRosterWatchOptions {
+    /**
+     * Run the host's own discovery (`custody.discover()`, then its roster
+     * commit). Called with the newest notice's view when that view differs from
+     * the last discovered one, when a notice shows a sequence gap or a new
+     * epoch, and on the first notice of a watch re-opened after a close (the
+     * time between two watches was not observed). One call runs at a time;
+     * notices that arrive meanwhile earn at most one more call, which runs only
+     * if the view still differs. A rejection goes to `onError`.
+     */
+    onView: (view: string) => unknown;
+    /**
+     * The view of the roster the host last committed. Defaults to the view of
+     * the last successful `custody.discover()` (outage probes excluded). Pass it
+     * when the host can commit a roster it did not list itself (a peer process
+     * held the discovery lease) or can fail after listing.
+     */
+    view?: () => string | undefined;
+    /**
+     * Called whenever the mode changes. The watch starts in `polling`. Keep the
+     * host's own list timer at its usual pace unless the mode is `watching`.
+     */
+    onMode?: (mode: WatchMode) => void;
+    /**
+     * The vault refused the watch, and its confirming `list_scoped` read it with
+     * this error (a revoked enrollment answers `not_found`). Custody has already
+     * applied it as it applies a refused discovery (`listFailed`: every kept
+     * receipt is dropped); handle it as the host handles that refusal.
+     */
+    onRefused?: (error: unknown) => void;
+    /** A failed `onView`, or a watch that could not be opened. */
+    onError?: (error: unknown) => void;
+}
+/** A vault watch held by a custody; see `ClaustrumScopedCustody.watchRoster`. */
+export interface ClaustrumRosterWatch {
+    /** How the host currently learns about changes. */
+    readonly mode: WatchMode;
+    /** Stop the watch and its timers. Safe to call more than once. */
+    close(): void;
 }
 /** Reads the provider identity a served token executes under, when the plugin can tell. */
 export type IdentityParser = (accessToken: string) => string | undefined;
@@ -151,13 +207,15 @@ export declare function decideScopedRetryAfter401(site: string, served: Claustru
  * so it cannot expire while a long request is still using it.
  */
 export declare const SERVING_MARGIN_MS = 300000;
+/** A kept receipt needs a minute of headroom, not the vault's refresh demand. */
+export declare const KEPT_RECEIPT_MARGIN_MS = 60000;
 /**
  * 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
- * deliberately no credential cache and no single-flight of credential reads:
- * each physical send is authorized by the vault, so a revoked enrollment or a
- * changed record takes effect on the next send. The enrollment token is
- * re-read per operation so an operator's reissue on disk is picked up.
+ * enrollment token as authorization. Used by every host of a plugin. Every
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
+ * reuse of the last validated receipt, in memory and bounded by its expiry.
+ * The enrollment token is re-read per operation so revocation and disconnect
+ * still take effect without a process restart.
  */
 export declare class ClaustrumScopedCustody {
     #private;
@@ -177,7 +235,13 @@ export declare class ClaustrumScopedCustody {
         requireAssertion?: boolean;
         now?: () => number;
         logger?: ClaustrumLogger;
+        setTimeoutImpl?: typeof setTimeout;
+        clearTimeoutImpl?: typeof clearTimeout;
     });
+    /** A watch losing its transport is the same outage as an unreachable read. */
+    transportLost(error?: unknown): void;
+    /** Any vault answer ends transport fallback, even when it refuses access. */
+    reachable(): void;
     /**
      * List this consumer's credentials. A record that cannot be used is skipped
      * and warned about rather than failing the whole list, so one bad record
@@ -186,15 +250,23 @@ export declare class ClaustrumScopedCustody {
      */
     discover(signal?: AbortSignal): Promise<VaultInventory>;
     /**
-     * Fetch the credential for one physical send and wrap it in a fresh receipt.
-     * The vault's served identity (or, without one, the plugin's parse of the
-     * token) must equal the roster's when both are present. Without
-     * `requireAssertion`, absence on either side proves nothing and does not
-     * refuse; the receipt records what the vault asserted separately from what
-     * the roster expected. With it, a reply that does not itself name the
-     * credential id and the expected account is refused.
+     * Apply a failed account listing: any answer from the vault (a refusal such
+     * as a revoked enrollment's `not_found`) drops every kept receipt, while an
+     * unreachable vault keeps them. A vault watch that ends with the same
+     * refusal calls this too, so both paths treat it alike.
      */
-    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    listFailed(error: unknown): void;
+    /** Discard bearer material when a route is removed, declined or rebound. */
+    forget(credentialId: string): void;
+    /** Apply an already-held roster; this never fetches credentials or writes it. */
+    retain(identities: readonly (ClaustrumScopedIdentity & {
+        enabled: boolean;
+        state: string;
+    })[]): void;
+    /** A frozen, non-secret summary for a plugin's status display. */
+    keptReceiptState(): KeptReceiptState;
+    /** Ask the vault while reachable; retain one validated receipt in memory only. */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal, routeId?: string): Promise<ClaustrumScopedAttempt>;
     /**
      * Report that a send this consumer actually made was rejected. Only a 401
      * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
@@ -203,5 +275,25 @@ export declare class ClaustrumScopedCustody {
      * custody did not issue is refused rather than reported.
      */
     reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    /**
+     * Watch this consumer's visible vault accounts instead of listing them on a
+     * short timer. Opens one `watchScoped` on this custody's client and calls
+     * `onView` when the host must run its discovery (see
+     * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
+     * (before 0.12.0) or a vault that answers `unknown_method` reports
+     * `fallback` and opens nothing. A watch that closes before any notice was
+     * never accepted: the client reads once to learn why, and the watch reports
+     * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
+     * loop. A watch that closes after notices is re-opened after
+     * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
+     * starts this custody's outage, exactly as an unreachable call does, and
+     * the first notice of a watch ends it. Timers are unreferenced; `close()`
+     * on the returned watch or on this custody stops it.
+     *
+     * The watch keeps no history, so the host still lists on a slow timer while
+     * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
+     * other mode the host keeps its usual list timer.
+     */
+    watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
     close(): void;
 }