@cortexkit/anthropic-auth-core 2.0.2 → 2.1.0

package/dist/internal-types/setup/detect.d.ts

@@ -0,0 +1,6 @@
+import type { SetupDetection, SetupFileSystem, SetupIO, SetupPlugin } from './types.js';
+export declare const defaultSetupFileSystem: SetupFileSystem;
+export declare function findExecutableOnPath(name: string, io?: SetupIO): string | null;
+export declare function openCodeDesktopMarkers(io?: SetupIO): string[];
+export declare function detectOpenCodeGeneration(io?: SetupIO): '1' | '2' | 'ambiguous';
+export declare function detectHosts(plugin: SetupPlugin, io?: SetupIO): Promise<SetupDetection>;

package/dist/internal-types/setup/index.d.ts

@@ -0,0 +1,6 @@
+export { AMBIGUOUS_OPENCODE_MESSAGE, runSetup } from './command.js';
+export { SetupCommandError, setupEnrollment } from './command-error.js';
+export { detectHosts, detectOpenCodeGeneration, findExecutableOnPath, openCodeDesktopMarkers, } from './detect.js';
+export { assertHostsStopped, createProcessFence, listSetupProcesses, ProcessFenceViolationError, ProcessInspectionError, type ProcessInspectionStep, } from './process-fence.js';
+export { type PlannedWrite, planOpenCodeRegistration, registerOpenCode, registerPi, updatePluginConfig, } from './register.js';
+export type { CommandResult, CommandRunner, HostDetection, OpenCodeGeneration, ProcessFence, SetupCallbackContext, SetupDetection, SetupEnrollmentOutcome, SetupEnvironment, SetupFileSystem, SetupHost, SetupHostEnrollment, SetupIO, SetupPlugin, SetupResult, } from './types.js';

package/dist/internal-types/setup/process-fence.d.ts

@@ -0,0 +1,43 @@
+import type { CommandRunner, ProcessFence, SetupEnvironment } from './types.js';
+export interface ProcessInspectionStep {
+    step: 'tasklist' | 'CIM' | 'ps';
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    timedOut: boolean;
+    durationMs: number;
+}
+export declare class ProcessInspectionError extends Error implements ProcessInspectionStep {
+    readonly code = "process-inspection-failed";
+    readonly step: ProcessInspectionStep['step'];
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly timedOut: boolean;
+    readonly durationMs: number;
+    constructor(details: ProcessInspectionStep);
+    get refusalText(): string;
+}
+export declare class ProcessFenceViolationError extends Error {
+    readonly activeHosts: Array<{
+        pid: number;
+        command: string;
+    }>;
+    constructor(activeHosts: Array<{
+        pid: number;
+        command: string;
+    }>);
+}
+/** List processes before filtering hosts; Windows PID 0 is a valid idle-process row. */
+export declare function listSetupProcesses(runner?: CommandRunner, options?: {
+    platform?: string;
+    env?: SetupEnvironment;
+    onStep?: (details: ProcessInspectionStep) => void;
+    /** False skips the Windows PowerShell query for Node and Bun command lines. */
+    inspectRuntimes?: boolean;
+}): Promise<Array<{
+    pid: number;
+    command: string;
+}>>;
+export declare function createProcessFence(runner?: CommandRunner, options?: {
+    platform?: string;
+}): ProcessFence;
+export declare function assertHostsStopped(fence: ProcessFence, env?: SetupEnvironment): Promise<void>;

package/dist/internal-types/setup/register.d.ts

@@ -0,0 +1,11 @@
+import type { OpenCodeGeneration, SetupIO, SetupPlugin } from './types.js';
+export interface PlannedWrite {
+    path: string;
+    content: string;
+    changed: boolean;
+}
+/** Edit only array entries so unrelated JSONC text, including comments, survives. */
+export declare function updatePluginConfig(text: string, key: 'plugin' | 'plugins', pkg: string, version: string): string;
+export declare function planOpenCodeRegistration(plugin: SetupPlugin, generation: OpenCodeGeneration, io?: SetupIO): PlannedWrite[];
+export declare function registerOpenCode(writes: readonly PlannedWrite[], beforeWrite?: () => Promise<void>): Promise<void>;
+export declare function registerPi(plugin: SetupPlugin, executable: string, io?: SetupIO): Promise<void>;

package/dist/internal-types/setup/types.d.ts

@@ -0,0 +1,150 @@
+import type { MenuTerminal } from '../auth-menu/terminal.js';
+import type { ClaustrumEnrollmentConnection, hostEnrollmentPaths } from '../claustrum/index.js';
+export type SetupHost = 'opencode' | 'pi';
+export type OpenCodeGeneration = '1' | '2' | 'both';
+export type SetupEnvironment = Record<string, string | undefined>;
+/**
+ * What a setup run recorded about one host's vault enrollment when it failed:
+ * `enrolled` once approval landed and the token was written, `not-enrolled`
+ * when the host was never asked or its enrollment was refused or gave up
+ * waiting, and `unknown` when setup failed while the enrollment was still in
+ * flight and the host's token file could not settle it.
+ */
+export type SetupEnrollmentOutcome = 'enrolled' | 'not-enrolled' | 'unknown';
+export interface SetupHostEnrollment {
+    host: SetupHost;
+    outcome: SetupEnrollmentOutcome;
+}
+/**
+ * What setup decided before calling a plugin callback. The OpenCode generation
+ * is the one being registered, after `--opencode` or the interactive choice, so
+ * a plugin can sign in the way that generation expects (OpenCode 2 does not
+ * read OpenCode 1's login file).
+ */
+export interface SetupCallbackContext {
+    opencodeGeneration: OpenCodeGeneration;
+    mode: 'local' | 'claustrum';
+    /**
+     * Every host this run sets up, in order, so the first `beforeSignIn` can
+     * check conditions across all of them (for example that their storage paths
+     * do not overlap) before any host is changed.
+     */
+    hosts: readonly SetupHost[];
+    /**
+     * Pi's agent folder, resolved the way Pi itself does (`PI_CODING_AGENT_DIR`,
+     * with `~` expanded, else `~/.pi/agent`). Pi's own `auth.json` lives here;
+     * use it rather than a plugin path setting, which can point elsewhere.
+     */
+    piAgentDir: string;
+}
+/** Provider login, credential migration and vault activation stay in plugin callbacks. */
+export interface SetupPlugin {
+    packages: {
+        opencode: string;
+        pi: string;
+    };
+    version: string;
+    displayName: string;
+    slashCommand: string;
+    vault: {
+        connectionFile: string;
+        hosts: Record<SetupHost, {
+            name: string;
+            paths: Parameters<typeof hostEnrollmentPaths>[0];
+        }>;
+    };
+    /**
+     * Runs for each host on a real run after the host, mode and generation are
+     * chosen and before the vault ceremony or `signInLocal`, while nothing has
+     * changed yet. Rejecting stops setup for that host, so a plugin can ask for
+     * consent or check preconditions before any credential or authority change.
+     */
+    beforeSignIn?(host: SetupHost, context: SetupCallbackContext): Promise<void>;
+    signInLocal(host: SetupHost, context: SetupCallbackContext): Promise<void>;
+    migrate(host: SetupHost, context: SetupCallbackContext): Promise<void>;
+    /** Reject mixed local/vault credentials and activate provider-specific vault access before registration. */
+    beforeRegister?(host: SetupHost, mode: 'local' | 'claustrum', context: SetupCallbackContext): Promise<void>;
+}
+export interface CommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    spawnError?: boolean;
+    stderrTruncated?: boolean;
+    signal?: NodeJS.Signals | null;
+    timedOut?: boolean;
+    durationMs?: number;
+}
+export interface CommandRunner {
+    run(file: string, args: readonly string[], options?: {
+        env?: SetupEnvironment;
+        timeoutMs?: number;
+        windowsVerbatimArguments?: boolean;
+    }): Promise<CommandResult>;
+}
+export interface SetupFileSystem {
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    isFile(path: string): boolean;
+    isExecutable(path: string): boolean;
+    readText(path: string): string;
+    realpath(path: string): string;
+}
+export interface ProcessFence {
+    listRunningHosts(env?: SetupEnvironment): Promise<Array<{
+        pid: number;
+        command: string;
+    }>>;
+    /**
+     * For a dry run, which must change nothing: the hosts found without starting
+     * any program that writes files. On Windows that skips the PowerShell query
+     * for Node and Bun command lines (PowerShell writes a startup cache into the
+     * user's profile), so Node or Bun processes are only counted. A fence without
+     * it is previewed with `listRunningHosts`.
+     */
+    previewRunningHosts?(env?: SetupEnvironment): Promise<{
+        hosts: Array<{
+            pid: number;
+            command: string;
+        }>;
+        uncheckedRuntimes: number;
+    }>;
+}
+/** Defaults use the process terminal and environment; overrides are test seams. */
+export interface SetupIO {
+    terminal?: MenuTerminal;
+    env?: SetupEnvironment;
+    platform?: string;
+    home?: string;
+    cwd?: string;
+    fs?: SetupFileSystem;
+    runner?: CommandRunner;
+    fence?: ProcessFence;
+    connect?: (options: {
+        connectionFile: string;
+        handshakeTimeoutMs: number;
+    }) => Promise<ClaustrumEnrollmentConnection>;
+    wait?: (ms: number) => Promise<void>;
+}
+export interface HostDetection {
+    installed: boolean;
+    executable: string | null;
+    version: string | null;
+    directory: string;
+}
+export interface SetupDetection {
+    opencode: HostDetection & {
+        generation: '1' | '2' | 'ambiguous';
+    };
+    pi: HostDetection;
+    claustrum: {
+        available: boolean;
+        executable: string | null;
+    };
+}
+export interface SetupResult {
+    hosts: SetupHost[];
+    dryRun: boolean;
+    mode: 'local' | 'claustrum';
+    detection: SetupDetection;
+}

package/dist/internal-types/store/pool.d.ts

@@ -42,7 +42,7 @@ export interface OpenPoolStoreOptions {
     requireCredentialStamps?: boolean;
     /** Require an exact secret fingerprint for every roster-publication removal. */
     requireRemovedFingerprint?: boolean;
-    /** Injected clock for leases, refresh stamps and `addedAt`. */
+    /** Logical clock for refresh stamps and `addedAt`; filesystem leases always use wall time. */
     now?: () => number;
     /**
      * Ordered store-lock list held across every read-modify-write. Defaults to

package/dist/internal-types/store/refresh-lock.d.ts

@@ -24,7 +24,6 @@ export type LockEvent = {
     path: string;
 };
 export interface LockEnvironment {
-    now: () => number;
     onLockEvent?: (event: LockEvent) => void;
     onLockStep?: (lock: {
         name: string;

package/dist/logging.d.ts

@@ -12,8 +12,10 @@ export type LoggingCommandAction = {
 export declare function parseLoggingCommandAction(argumentsText: string): LoggingCommandAction;
 export declare function buildLoggingStatusSummary(input?: {
     level?: LogLevel;
+    settingsPath?: string;
 }): string;
 export declare function executeLoggingCommand(input: {
     argumentsText: string;
     level?: LogLevel;
+    settingsPath?: string;
 }): string;

package/dist/mid-conversation-output-config.d.ts

@@ -1,4 +1,9 @@
-export declare const MID_CONVERSATION_OUTPUT_CONFIG_BETA = "mid-conversation-output-config-2026-07-01";
+/**
+ * Per-turn control beta that Claude Code sends on Opus 5.5, Sonnet 5.5,
+ * Fable 5.1 and Haiku 5.5. It enables effort changes carried by empty
+ * `role: "system"` messages on the eligible models below.
+ */
+export declare const PER_TURN_CONTROL_BETA = "per-turn-control-2026-07-01";
 export type AdaptiveEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export type MidConversationEffortTransition = {
     /** Number of assistant messages preceding the user boundary for this effort. */
@@ -6,7 +11,34 @@ export type MidConversationEffortTransition = {
     effort: AdaptiveEffort;
 };
 export declare function normalizeAdaptiveEffort(value: unknown): AdaptiveEffort | undefined;
-export declare function usesMidConversationOutputConfig(body: Record<string, unknown>): boolean;
+/**
+ * Models that require adaptive thinking for per-message effort: Opus 5.5
+ * and Sonnet 5.5, including dated and `[1m]` context-window ids. Header
+ * eligibility is separate; `sendsPerTurnControlBeta` follows Claude Code.
+ */
+export declare function usesPerTurnControl(model: unknown): boolean;
+/**
+ * Models whose OAuth requests carry `PER_TURN_CONTROL_BETA`: Opus 5.5 and
+ * Sonnet 5.5, plus Fable 5.1 and Haiku 5.5, which Claude Code 2.1.302 also
+ * sends it on. Sending the beta does not by itself make a model eligible for
+ * effort markers; `supportsPerMessageEffort` decides that.
+ */
+export declare function sendsPerTurnControlBeta(model: unknown): boolean;
+/**
+ * Whether a request may move effort changes into empty system messages.
+ *
+ * Fable 5.1 is always eligible, whatever its thinking field says. Opus 5.5
+ * and Sonnet 5.5 qualify only with adaptive thinking: Anthropic rejects a
+ * differing per-message effort with HTTP 400 on Sonnet 5.5 `between_tools`,
+ * and asks callers to use adaptive thinking to vary effort.
+ */
+export declare function supportsPerMessageEffort(body: Record<string, unknown>): boolean;
+/**
+ * The effort Anthropic applies when a request sets no `output_config.effort`:
+ * `medium` on Opus 5.5 and Haiku 5.5, `high` on the other models.
+ * A history entry without a recognized effort level uses this value.
+ */
+export declare function defaultAdaptiveEffort(model: unknown): AdaptiveEffort;
 export declare function applyMidConversationOutputConfig(body: Record<string, unknown>, transitions: readonly MidConversationEffortTransition[]): {
     applied: boolean;
     inserted: number;

package/dist/migration-source.d.ts

@@ -1,3 +1,4 @@
+import { type OwnerOnlyOptions } from './owner-only.ts';
 export type NativeMigrationSourceRole = 'config' | 'state' | 'hostAuth' | 'routing' | 'journal';
 export interface NativeMigrationSourceSnapshot {
     readonly role: NativeMigrationSourceRole;
@@ -20,6 +21,7 @@ export declare class NativeMigrationSourceError extends Error {
 }
 interface SourceReadHooks {
     onOpened?: () => Promise<void>;
+    ownership?: OwnerOnlyOptions;
 }
 /**
  * Capture exact import bytes without the legacy loader's missing-entry recovery.

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

@@ -5,12 +5,13 @@ import { type NativeAccountMetadataPatch, type NativeAccountSnapshot, type Nativ
 import { type NativeCustodyReceipt } from './native-custody.ts';
 import { type NativeLocalCredentialServiceOptions } from './native-local-credential-service.ts';
 import type { NativeLocalExternalPolicy } from './native-local-runtime-readers.ts';
+import { type NativeQuotaObservations } from './native-quota-observations.ts';
 import type { NativeKnownCredentialSubject, NativeRefreshResult, NativeRefreshSubject } from './native-refresh-coordinator.ts';
-import { type NativeDisplayProfile, type NativeVaultRuntime, type NativeVaultRuntimeOptions } from './native-vault-runtime.ts';
+import { type NativeDisplayProfile, type NativeVaultQuotaPurpose, type NativeVaultRuntime, type NativeVaultRuntimeOptions } from './native-vault-runtime.ts';
 import { type NativeLocalPoolBinding } from './pool-binding.ts';
-import type { NativePoolPaths } from './pool-paths.ts';
+import { type NativePoolPaths } from './pool-paths.ts';
 import type { QuotaRequestDispatch } from './quota-manager.ts';
-import type { RelayConfig } from './relay.ts';
+import { type RelayConfig } from './relay.ts';
 export type { NativeAccountMetadataPatch, NativeAccountSnapshot, NativeAccountView, } from './native-account-view.ts';
 export interface NativeAccountRuntimeOptions {
     paths: NativePoolPaths;
@@ -45,6 +46,8 @@ export type NativeRelayUpdate = Partial<Omit<RelayConfig, 'token'>> & {
 };
 export interface NativeAccountRuntime {
     readonly vault: NativeVaultRuntime;
+    readonly quotaObservations: NativeQuotaObservations;
+    drainQuotaPublications(): Promise<void>;
     /** Fresh private relay authorization for transport only; never include it in a status snapshot. */
     getRelayConfig(): Promise<RelayConfig | null>;
     updateRelay(patch: NativeRelayUpdate): Promise<void>;
@@ -103,11 +106,13 @@ export interface NativeAccountRuntime {
     resetBackoff(routeId: string, fence: NativeRefreshSubject | NativeCustodyReceipt, kind?: 'refresh' | 'quota' | 'all'): Promise<boolean>;
     getOrCreateAuthLineage(routeId: string, fence: NativeKnownCredentialSubject | NativeCustodyReceipt): Promise<string | undefined>;
     incrementPrimeUsage(routeId: string, fence: NativeKnownCredentialSubject | NativeCustodyReceipt, delta?: PrimeUsageDelta): Promise<boolean>;
-    fetchQuota(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal, dispatch?: QuotaRequestDispatch): Promise<OAuthQuotaSnapshot>;
+    /** `purpose` applies to vault accounts only; local accounts always poll. */
+    fetchQuota(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal, dispatch?: QuotaRequestDispatch, purpose?: NativeVaultQuotaPurpose): Promise<OAuthQuotaSnapshot>;
     fetchProfile(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<OAuthAccountProfile>;
     /** Like fetchProfile, but returns before the profile is saved; see NativeDisplayProfile. */
     fetchProfileForDisplay(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<NativeDisplayProfile>;
     close(): void;
+    getSettingsPath(): Promise<string>;
 }
 /** Host instances own leases, while stores and the vault connection live until the last release. */
 export declare function acquireNativeAccountRuntime(options: NativeAccountRuntimeOptions): NativeAccountRuntime;

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

@@ -10,6 +10,7 @@ export interface NativeAccountView {
     id: string;
     type: 'oauth' | 'api';
     source: 'local' | 'vault';
+    /** User setting, not serving eligibility; use nativeAccountCanServe for runtime work. */
     enabled: boolean;
     label?: string;
     addedAt?: number;
@@ -30,14 +31,29 @@ export interface NativeAccountView {
     baseURL?: string;
     authHeader?: 'authorization-bearer' | 'x-api-key';
 }
+/**
+ * Serving requires the user's permission and an active vault credential.
+ * Native views name their source; roster rows use credentialId and token-free
+ * policy rows use claustrumScopedCredentialId. Local policy rows default to on
+ * when the optional enabled setting is absent.
+ */
+export declare function nativeAccountCanServe(account: {
+    enabled?: boolean;
+    source?: NativeAccountView['source'];
+    state?: string;
+    credentialId?: string;
+    claustrumScopedCredentialId?: string;
+    claustrumScopedState?: string;
+} | null | undefined): boolean;
 /**
  * One-line status text for an account's state, shared by host status
  * displays. A local account in 'unsupported-access' holds a saved access value
  * that is not a Claude OAuth access token; it is never sent to Claude or
- * refreshed, so the text names the remedy. Other states, such as vault
- * credential states, are shown as recorded. Returns '' when there is no state.
+ * refreshed, so the text names the remedy. Vault states describe why an
+ * account cannot serve without changing the user's enabled setting.
+ * Returns '' when there is no state.
  */
-export declare function formatNativeAccountState(view: Pick<NativeAccountView, 'state'>): string;
+export declare function formatNativeAccountState(view: Pick<NativeAccountView, 'state'> & Partial<Pick<NativeAccountView, 'source' | 'enabled'>>): string;
 export interface NativeAccountSnapshot {
     mode: 'local' | 'claustrum';
     settings: Record<string, unknown>;

package/dist/native-custody-activation.d.ts

@@ -3,7 +3,7 @@ import { type NativeHostAuthWriteHooks } from './native-host-auth-write.ts';
 import { type NativeMigrationJournal } from './pool-authority.ts';
 import type { NativePoolPaths } from './pool-paths.ts';
 import { createNativePoolStore } from './pool-store.ts';
-export type NativeCustodyActivationErrorCode = 'migration-required' | 'invalid-state' | 'primary-missing' | 'primary-mismatch' | 'primary-unverified' | 'primary-conflict' | 'row-unverified' | 'unenrolled-local-row' | 'vault-ambiguous' | 'roster-conflict' | 'runtime-conflict' | 'settings-conflict' | 'credential-changed' | 'host-auth-changed' | 'consent-required' | 'migration-busy' | 'ownership-lost' | 'auth-content-refused' | 'process-fence-refused' | 'migration-proof-changed';
+export type NativeCustodyActivationErrorCode = 'migration-required' | 'invalid-journal' | 'invalid-state' | 'primary-missing' | 'primary-mismatch' | 'primary-unverified' | 'primary-conflict' | 'row-unverified' | 'unenrolled-local-row' | 'vault-ambiguous' | 'roster-conflict' | 'runtime-conflict' | 'settings-conflict' | 'credential-changed' | 'host-auth-changed' | 'consent-required' | 'migration-busy' | 'ownership-lost' | 'auth-content-refused' | 'process-fence-refused' | 'migration-proof-changed';
 export declare class NativeCustodyActivationError extends Error {
     readonly code: NativeCustodyActivationErrorCode;
     constructor(code: NativeCustodyActivationErrorCode);

package/dist/native-custody.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Reads insula's quota cache from the vault daemon. Declared here with the
+ * same shape as common-auth's InsulaUsageTransport so this module's published
+ * declarations do not depend on common-auth.
+ */
+export interface NativeInsulaUsageTransport {
+    connectionFile: string;
+    getUsage(): Promise<unknown>;
+}
 /** Claustrum IPC operations for listing accounts, reading tokens, reporting rejection, and closing the connection. */
 export interface NativeCustodyClient {
     listScoped: (enrollmentToken?: string) => Promise<{
@@ -18,6 +27,16 @@ export interface NativeCustodyClient {
             readonly email?: string;
             readonly orgName?: string;
         }[];
+        /**
+         * How many grants this enrollment holds, and which. Undefined when the
+         * vault is too old to send them: unknown, never zero.
+         */
+        readonly grants: number | undefined;
+        readonly grantTuples: readonly {
+            readonly selectorKind: string;
+            readonly selector: string;
+            readonly operation: string;
+        }[] | undefined;
     }>;
     getScoped: (input: {
         credentialId: string;
@@ -41,6 +60,79 @@ export interface NativeCustodyClient {
         reporterSource: NativeCustodyReporterSource;
     }) => Promise<void>;
     close: () => void;
+    /**
+     * Open one vault watch that announces changes to the accounts this
+     * enrollment can see. Present from claustrum-client 0.12.0; without it the
+     * host keeps listing on its own timer.
+     */
+    watchScoped?(onNotice: (notice: NativeScopedWatchNotice) => void, options?: {
+        enrollmentToken?: string;
+    }): NativeScopedWatchHandle;
+    /**
+     * How to read insula's background quota cache on the same daemon. Present
+     * when the connection was made with connectClaustrumScopedClient; reading
+     * it opens a separate short-lived socket and never uses this connection.
+     */
+    insula?: NativeInsulaUsageTransport;
+}
+/**
+ * A vault watch notice. `view` is the same digest `listScoped` returns, so
+ * only a different view means the visible accounts changed. Declared here,
+ * like the rest of this client shape, so published declarations do not
+ * depend on claustrum-client or common-auth.
+ */
+export interface NativeScopedWatchNotice {
+    readonly kind: string;
+    readonly epoch: string;
+    readonly seq: number;
+    readonly view: string;
+}
+/**
+ * How a vault watch ended. `refused` carries the vault's refusal of the
+ * confirming account listing (a revoked enrollment answers `not_found`);
+ * `unsupported` means the vault does not know the watch method.
+ */
+export type NativeScopedWatchEnd = {
+    readonly kind: 'refused';
+    readonly error: unknown;
+} | {
+    readonly kind: 'transport_lost';
+    readonly error: unknown;
+} | {
+    readonly kind: 'ended' | 'not_accepting' | 'unsupported' | 'stopped';
+};
+export interface NativeScopedWatchHandle {
+    stop(): void;
+    readonly closed: Promise<NativeScopedWatchEnd>;
+}
+/**
+ * How the host currently learns about account changes. `watching`: a vault
+ * watch is open, so the host's list timer only needs to run as a slow safety
+ * net. `polling` and `fallback`: no watch is open, so the host lists at its
+ * usual pace.
+ */
+export type NativeRosterWatchMode = 'watching' | 'polling' | 'fallback';
+export interface NativeRosterWatchOptions {
+    /**
+     * Run the host's discovery and roster publication. Called when a notice
+     * shows the visible accounts changed since the roster the host holds; one
+     * call at a time, and notices that arrive meanwhile earn at most one more.
+     */
+    onView: (view: string) => unknown;
+    /** The view of the roster the host currently holds, if any. */
+    view?: () => string | undefined;
+    onMode?: (mode: NativeRosterWatchMode) => void;
+    /**
+     * The vault refused the watch and its confirming listing. Kept receipts are
+     * already dropped, as a refused listing drops them.
+     */
+    onRefused?: (error: unknown) => void;
+    onError?: (error: unknown) => void;
+}
+export interface NativeRosterWatch {
+    readonly mode: NativeRosterWatchMode;
+    /** Stop the watch and its timers. Safe to call more than once. */
+    close(): void;
 }
 export type NativeCustodyReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
 export interface NativeCustodyLogger {
@@ -57,6 +149,12 @@ export interface NativeCustodyOptions {
     env?: NodeJS.ProcessEnv;
     now?: () => number;
     logger?: NativeCustodyLogger;
+    /**
+     * Timer functions for the 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;
 }
 export interface NativeCustodyIdentity {
     readonly credentialId: string;
@@ -74,6 +172,7 @@ export interface NativeCustodyReceipt {
     readonly recordVersion: number;
     readonly expiresAtMs: number | null;
     readonly accessToken: string;
+    readonly fromKeptReceipt?: true;
 }
 export interface NativeCustodyInventory {
     readonly view: string;
@@ -89,6 +188,20 @@ export interface NativeCustodyInventory {
         readonly credentialId?: string;
         readonly reason: 'empty credential id' | 'duplicate credential id' | 'blank account identity' | 'empty state';
     }[];
+    /**
+     * What this host's enrollment is granted, as the vault's list reply named
+     * it. It explains an empty listing: `grants === 0` means no grant at all,
+     * while `grants > 0` means a grant that reaches no credential. Undefined
+     * means unknown (the vault predates these fields), never zero grants.
+     */
+    readonly grantReach?: {
+        readonly grants: number;
+        readonly tuples: readonly {
+            readonly selectorKind: string;
+            readonly selector: string;
+            readonly operation: string;
+        }[];
+    };
 }
 export type NativeCustodyErrorCode = 'closed' | 'not-enrolled' | 'invalid-token' | 'unavailable' | 'identity-changed' | 'identity-unasserted' | 'insufficient-validity' | 'invalid-material' | 'not-active' | 'route-unavailable' | 'route-declined' | 'no-receipt' | 'unsafe-file' | 'invalid-state' | 'wrong-consumer' | 'roster-busy' | 'host-slot-login' | 'host-slot-placeholder' | 'placeholder-refresh';
 export declare class NativeCustodyError extends Error {
@@ -108,6 +221,23 @@ export interface NativeCustody {
     authorize: (identity: NativeCustodyIdentity, signal?: AbortSignal) => Promise<NativeCustodyReceipt>;
     reportFailure: (receipt: NativeCustodyReceipt, status: number, reporterSource: NativeCustodyReporterSource) => Promise<void>;
     prepareRetry: (served: NativeCustodyReceipt, signal?: AbortSignal) => Promise<NativeCustodyRetry>;
+    /** The shared connection's insula transport, connecting first if needed; undefined when the client has none. */
+    insulaTransport: () => Promise<NativeInsulaUsageTransport | undefined>;
+    retain: (rows: readonly (NativeCustodyIdentity & {
+        enabled: boolean;
+        state: string;
+    })[]) => void;
+    forget: (credentialId: string) => void;
+    keptReceiptState: () => Readonly<{
+        active: boolean;
+        since: number | null;
+    }>;
+    /**
+     * Watch the vault for account changes over the shared connection instead
+     * of relying on the host's list timer alone. A client or vault without the
+     * watch reports `fallback`. Closing the custody closes every watch.
+     */
+    watchRoster: (options: NativeRosterWatchOptions) => NativeRosterWatch;
     close: () => void;
 }
 /** Share a lazy Claustrum connection; each authorize call reads a fresh enrollment token and OAuth receipt. */

package/dist/native-enrollment-authority.d.ts

@@ -1,2 +1,6 @@
+import { enrollmentAuthority, readClaustrumEnrollmentStatus } from "./internal-types/claustrum/index.js";
 /** Enrollment files, not account settings, choose the host's credential source. */
-export declare function readNativeEnrollmentMode(host: 'opencode' | 'pi', env?: NodeJS.ProcessEnv): Promise<'local' | 'claustrum'>;
+export declare function readNativeEnrollmentMode(host: 'opencode' | 'pi', env?: NodeJS.ProcessEnv, dependencies?: {
+    enrollmentAuthority: typeof enrollmentAuthority;
+    readClaustrumEnrollmentStatus: typeof readClaustrumEnrollmentStatus;
+}): Promise<'local' | 'claustrum'>;

package/dist/native-host-auth-read.d.ts

@@ -1,3 +1,4 @@
 import { type NativeHostAuthEntryInspection } from './native-host-auth.ts';
+import { type OwnerOnlyOptions } from './owner-only.ts';
 /** Read only the host's login classification; credentials and source fingerprints never leave this boundary. */
-export declare function readNativeHostAuthKind(host: 'opencode' | 'pi', path: string): Promise<NativeHostAuthEntryInspection['kind']>;
+export declare function readNativeHostAuthKind(host: 'opencode' | 'pi', path: string, ownership?: OwnerOnlyOptions): Promise<NativeHostAuthEntryInspection['kind']>;

package/dist/native-host-auth-write.d.ts

@@ -1,3 +1,4 @@
+import { type PublicationOptions } from './publication-rename.ts';
 export interface NativeHostAuthWriteInput {
     readonly host: 'opencode' | 'pi';
     /**
@@ -16,6 +17,7 @@ export interface NativeHostAuthWriteInput {
     readonly processFence: () => Promise<void>;
 }
 export interface NativeHostAuthWriteHooks {
+    readonly publication?: PublicationOptions;
     readonly beforeRecheck?: () => Promise<void>;
     readonly beforeRename?: () => Promise<void>;
     readonly afterRename?: () => Promise<void>;

package/dist/native-menu-executor.d.ts

@@ -212,7 +212,7 @@ export type NativeMenuExecutionResult = {
      */
     readonly status: 'failed';
     readonly action: NativeMenuDispatchActionId | 'vault-disconnect';
-    readonly code: 'execution-failed' | 'invalid-outcome';
+    readonly code: 'execution-failed' | 'invalid-outcome' | 'disconnect-unsafe-file' | 'disconnect-wrong-consumer' | 'disconnect-pi-recovery' | 'disconnect-conflict' | 'disconnect-busy' | 'disconnect-io';
 } | {
     /** The host's disconnect capability ran and reported this result. */
     readonly status: 'disconnect';