@cortexkit/anthropic-auth-core 2.0.1 → 2.0.3

package/dist/internal-types/routing/sticky.d.ts

@@ -0,0 +1,158 @@
+import { type ProjectedQuota } from '../quota/projection.js';
+import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type RoutingRow, type WindowRef } from './admission.js';
+import { type StickyPin } from './pins.js';
+export declare const QUOTA_STALENESS_MS: number;
+export declare const MIN_RESET_HOURS: number;
+export declare const MIN_WEIGHT = 0.000001;
+/** The projection's time, else the caller's cache-entry time. */
+export declare function snapshotCheckedAt(quota: ProjectedQuota | null | undefined, entryCheckedAt?: number): number | undefined;
+export type StickyBreakDecision = {
+    action: 'retain';
+    reason: 'unknown' | 'stale' | 'healthy' | 'transient';
+} | {
+    action: 'migrate';
+    reason: 'exhausted' | 'permanent' | 'killswitch';
+    /** The exhausted limit, named by its (scope, label), not its position. */
+    window?: WindowRef;
+    resetsAt?: string;
+};
+/**
+ * How the adapter reads a failed response's HTTP status for the break
+ * decision. `permanent` moves the session off its row before any quota is
+ * consulted; `transient` and `healthy` keep it unless the quota says the row
+ * is spent. A missing status means the request failed without a response.
+ */
+export type StickyStatusClass = 'permanent' | 'transient' | 'healthy';
+export type StickyStatusClassifier = (status: number | undefined) => StickyStatusClass;
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export declare function defaultStickyStatusClass(status: number | undefined): StickyStatusClass;
+/** Classifies whether a pinned session should leave its row after a failure. */
+export declare function decideStickyBreak(input: {
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    status?: number;
+    now: number;
+    killswitchPasses?: boolean;
+    /** Defaults to `defaultStickyStatusClass`. */
+    classifyStatus?: StickyStatusClassifier;
+}): StickyBreakDecision;
+export declare function sustainableWindowWeight(window: {
+    remainingPercent: number;
+    resetsAt?: string;
+}, reservePercent: number, now: number): number;
+export interface StickySelectionCandidate {
+    accountId: string;
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    /** Reserve percent per window label; a missing label reserves nothing. */
+    reservePercent: Readonly<Record<string, number>>;
+    configuredOrder: number;
+    resetCreditsApplicable?: number;
+    /** `false` excludes the candidate from weighted and fallback placement. */
+    killswitchPasses?: boolean;
+}
+export interface StickySelectionInput {
+    candidates: readonly StickySelectionCandidate[];
+    pendingBytes: ReadonlyMap<string, number>;
+    requestBytes: number;
+    now: number;
+    onEmptyWeightedSet?: () => void;
+}
+export interface StickySelection {
+    accountId: string;
+    quotaCheckedAt?: number;
+    source: 'weighted' | 'mode-fallback';
+}
+/**
+ * Places a session: the lowest projected pressure among candidates with a
+ * fresh positive weight, else (`mode-fallback`) the first candidate in
+ * configured order, preferring one with an applicable reset credit.
+ */
+export declare function selectStickyCandidate(input: StickySelectionInput): StickySelection | undefined;
+/** Reserve percent per window label; a missing label reserves nothing. */
+export type ReservePercent = Readonly<Record<string, number>>;
+/**
+ * Reserve percentages per row: a map keyed by row id, or a function of the
+ * row. A row the map lacks, or for which the function returns undefined,
+ * takes the shared `reservePercent`.
+ */
+export type RowReservePercent = ReadonlyMap<string, ReservePercent> | ((row: RoutingRow) => ReservePercent | undefined);
+/**
+ * What a valid pin does when its row is not dispatched.
+ *
+ * `keep`: the pin is retained whatever kept its row from this request.
+ *
+ * `move-on-confirmed-exhaustion`: the pin moves to the row this request is
+ * dispatched to when its own row was refused as confirmed exhausted (a spent
+ * window with a future reset, or a spent credit budget) or killed by the
+ * killswitch. A refusal for unknown quota (no reading yet, a missing window,
+ * an exhausted reading without a usable reset) and an exclusion (rate-limit
+ * mark, refresh backoff) keep the pin while this request is served elsewhere.
+ * With no admissible row the pin is retained either way.
+ */
+export type RefusedPinPolicy = 'keep' | 'move-on-confirmed-exhaustion';
+export interface StickyRouteInput extends AdmissionInput {
+    requestBytes: number;
+    /** Bytes already committed per row, for example from other sessions' pins. */
+    pendingBytes?: ReadonlyMap<string, number>;
+    /** Killswitch verdict per row; a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+    /** Reserve percent per window label, for every row without its own. */
+    reservePercent?: ReservePercent;
+    /** Per-row reserves, which replace `reservePercent` for the rows they cover. */
+    rowReservePercent?: RowReservePercent;
+    /** Defaults to `keep`. */
+    refusedPinPolicy?: RefusedPinPolicy;
+    resetCreditsApplicable?: ReadonlyMap<string, number>;
+    /** The session's current pin, if it has one. */
+    pin?: StickyPin;
+    /** Each row's recorded wire identity; missing means unknown. */
+    identities?: ReadonlyMap<string, string | undefined>;
+    onEmptyWeightedSet?: () => void;
+}
+/**
+ * What the caller does with the session's pin: keep it, replace it with
+ * `pin`, or drop it. Under the default `keep` policy a valid pin is always
+ * kept, even when this request was routed elsewhere because its row was
+ * refused, excluded or killed; `refusedPinPolicy` can move it instead.
+ */
+export type PinAction = {
+    action: 'retain';
+} | {
+    action: 'assign';
+    pin: StickyPin;
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export type StickyRoute = {
+    outcome: 'dispatch';
+    accountId: string;
+    source: 'pin' | 'weighted' | 'mode-fallback';
+    quotaCheckedAt?: number;
+    pin: PinAction;
+    /** Rows that selection chose and admission then refused, in selection order. */
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+} | {
+    outcome: 'no-admissible-account';
+    pin: PinAction;
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+};
+/**
+ * Routes one request in `sticky-balanced` mode. A valid pin whose row is
+ * admitted, not excluded and not killed is dispatched as is. Otherwise
+ * selection runs over the non-excluded rows; each selected row admission
+ * refused is removed and selection re-runs, so the loop ends either on an
+ * admitted row or with no admissible account.
+ */
+export declare function routeSticky(input: StickyRouteInput): StickyRoute;

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

@@ -0,0 +1,17 @@
+/**
+ * Keeps the Pi install refusal message stable while exposing safe process details.
+ * A clipped tail can start inside a credential, so discard its first line—or
+ * the whole tail if it has no newline—before redacting.
+ */
+export declare class SetupCommandError extends Error {
+    readonly step = "pi-install";
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stderrTail: string;
+    constructor(details: {
+        exitCode: number | null;
+        signal: string | null;
+        stderrTail: string;
+        stderrTruncated?: boolean;
+    });
+}

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

@@ -0,0 +1,3 @@
+import type { SetupIO, SetupPlugin, SetupResult } from './types.js';
+export declare const AMBIGUOUS_OPENCODE_MESSAGE = "Multiple OpenCode generations found. Choose --opencode=1|2|both before running noninteractive setup.";
+export declare function runSetup(plugin: SetupPlugin, argv?: readonly string[], io?: SetupIO): Promise<SetupResult>;

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 } 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, SetupEnvironment, SetupFileSystem, SetupHost, 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,138 @@
+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 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/internal-types/store/schema.d.ts

@@ -49,6 +49,8 @@ export type StoredCredential = (OAuthCredential & {
 /** Quota codec supplied by `/quota`: the store never interprets the map itself. */
 export interface QuotaCodec {
     validate(value: unknown): boolean;
+    /** Normalize persisted quota before validation, when the codec supports it. */
+    decode?(value: unknown): unknown;
     merge(stored: unknown | undefined, observation: unknown): unknown;
 }
 /**

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,11 @@
+/** Per-message effort beta sent with every OAuth Fable 5.1 request. */
 export declare const MID_CONVERSATION_OUTPUT_CONFIG_BETA = "mid-conversation-output-config-2026-07-01";
+/**
+ * Per-turn control beta that Claude Code sends on every Opus 5.5 and Sonnet
+ * 5.5 request. It enables effort changes carried by an empty `role: "system"`
+ * message on those two models.
+ */
+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 +13,35 @@ export type MidConversationEffortTransition = {
     effort: AdaptiveEffort;
 };
 export declare function normalizeAdaptiveEffort(value: unknown): AdaptiveEffort | undefined;
+/**
+ * Whether an OAuth request for this model carries the Fable 5.1 per-message
+ * effort beta (`MID_CONVERSATION_OUTPUT_CONFIG_BETA`). Opus 5.5 and Sonnet
+ * 5.5 use `PER_TURN_CONTROL_BETA` instead.
+ */
 export declare function usesMidConversationOutputConfig(body: Record<string, unknown>): boolean;
+/**
+ * Opus 5.5 and Sonnet 5.5, including dated and `[1m]` context-window ids.
+ * Their OAuth requests always carry `PER_TURN_CONTROL_BETA`, as Claude Code's
+ * do. Anthropic also documents per-message effort for Mythos 5.1, Opus 5 and
+ * Haiku 5.5, but without a Claude Code capture to match, those models keep
+ * sending requests without the beta or effort markers.
+ */
+export declare function usesPerTurnControl(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/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 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>;
@@ -108,6 +111,7 @@ export interface NativeAccountRuntime {
     /** 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,20 +31,37 @@ 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>;
     accounts: NativeAccountView[];
-    /** Vault session-to-account assignments use this separate file. Local mode keeps the assignment file at the destination recorded by migration. */
+    /** Vault storage, or the local destination recorded by the authorized migration journal. */
     routingPath?: string;
+    /** Distinct pre-migration routing file that OpenCode local serving may have recreated. */
+    routingRecoveryPath?: string;
     routingSeed?: NativeVaultRoutingSeed;
     /** AccountStorage-shaped input for pure policy predicates, never a credential or persistence authority. */
     policyStorage: AccountStorage;

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-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';

package/dist/native-migration.d.ts

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