@modelprofile.com/authswitch 6.5.0 → 7.0.0

package/readme.md

@@ -28,27 +28,53 @@ Node.js 24 or newer is required.
 
 The package also exports a typed client for a per-user authswitch authority daemon. Its
 SmartData registry stores account identity separately from sealed refresh grants, runtime
-bindings, Codex enrollment records, and native-handoff and migration journals. A daemon
+bindings, durable device-operation receipts, Codex enrollment records, and native-handoff and migration journals. A daemon
 owns OpenAI device login, targeted reauthentication, and proactive refresh for grants
-added through this API. Management snapshots and events contain no credentials.
+added through this API. Management snapshots expose separate account and login rows,
+including each login's purpose, owner, health, problem and available actions; neither
+snapshots nor events contain credentials.
 
 ```ts
+import { randomUUID } from 'node:crypto';
 import { AuthSwitchClient } from '@modelprofile.com/authswitch/authority-client';
 import { resolveAuthSwitchAuthorityPaths } from '@modelprofile.com/authswitch';
 
 const paths = resolveAuthSwitchAuthorityPaths();
 const client = new AuthSwitchClient(paths.authoritySocketPath, paths.runtimeSocketPath);
 const snapshot = await client.snapshotAll();
-const operation = await client.beginAddOpenAi();
+const operationId = randomUUID();
+const operation = await client.beginAddOpenAi(operationId);
+// Keep operation.id to discover its final result after navigation or reconnect.
+const receipt = await client.getOperation(operation.id);
 ```
 
 Browser code can import the credential-free DTOs from
 `@modelprofile.com/authswitch/authority-contract`. A backend binds an account to a
-runtime incarnation and keeps the returned capability private. The runtime-only socket
+runtime incarnation by exact account ID, login ID and purpose, and keeps the returned
+capability private. Targeted reauthentication likewise requires the exact login; an
+account's presentation default never selects a grant for either action. Completed and
+interrupted operations remain discoverable through `getOperation()` and paged
+`listOperations()`. A completed receipt and its account/grant change commit together, so
+the receipt resolves a lost response or an event that arrives first. Add and reauthentication
+callers supply one UUID for the logical start and reuse it after a lost response. Replaying that
+UUID returns the same matching receipt without starting another provider login; using it for a
+different target is rejected. Cancelling a durable `starting` receipt prevents a late provider
+handle from promoting or overwriting it. Aborting a client request only detaches that request and
+does not cancel the daemon-owned login. The runtime-only socket
 resolves that binding to a current access token; its directory can be mounted into a
 container without exposing the management socket. A provider that rejects a specific
 access-token generation can request a newer one through `rejectedGrantGeneration`; the
 authority coalesces concurrent rejection callbacks and never replays an uncertain refresh.
+After an external Flex or OpenCode runtime has fenced new work and drained its pending access
+resolutions and provider requests, it can release its exact binding capability through the
+runtime socket. Every bind receives a fresh random capability, so a stale release cannot fence
+or delete a successor even if the caller reused an incarnation label. Release waits for admitted
+server-side resolution handlers, but handler completion does not prove response delivery and
+cannot retract an access token already received or in use; the runtime owner therefore owns that
+drain. Generic release cannot revoke a managed Codex binding, whose daemon-owned stop still closes
+the runtime and clears its durable run before internal revocation. Binding release never transfers
+or changes ownership of the account grant. External-binding recovery after an owner crash remains
+a prerequisite for the full account-mutation cutover.
 
 `AuthSwitchClient.subscribe(onSnapshot, onEvent, signal, { onStatus })` reports `current`
 after a fresh snapshot or verified heartbeat, `unavailable` on disconnect or resync, and
@@ -57,6 +83,113 @@ Every change-event batch supplies a fresh snapshot before `onEvent`, so a consum
 not need to reconstruct account state from events. `lastVerifiedAt` records the last
 successful daemon response, including an empty heartbeat.
 
+`AuthSwitchClient.doctorPage()` reads credential-free diagnostic evidence without unsealing
+a grant, refreshing a token or contacting a provider. Each bounded page separately stamps
+the database observation, daemon state and managed-Codex process observation. Stored account
+and login rows explicitly report `liveCheck: not_checked`; a ready daemon therefore does not
+claim that a stored grant or provider is healthy. Native homes and journals omit paths,
+digests and sealed values, while managed Codex reports durable, in-memory and observed-process
+state independently with fixed problem categories. Continue each independent cursor to inspect
+the complete inventory. Pages are later observations rather than one atomic global snapshot,
+and the authority metadata revision is not a change clock for every native-home record. If the
+management socket is unavailable, an offline caller must leave database and admission state
+unknown instead of starting the database to inspect it.
+
+The authority CLI uses that daemon surface without constructing the legacy native harness adapters:
+
+```bash
+authswitch account list [--json]
+authswitch account add openai [--json]
+authswitch account reauth <account-id> <login-id> [--json]
+authswitch account operation get <operation-id> [--json]
+authswitch account operation cancel <operation-id> [--json]
+authswitch account operation resume <operation-id> [--json]
+authswitch account preuse <account-id> <login-id> [--prompt <text>] [--model <id>] [--json]
+authswitch account preuse --all [--prompt <text>] [--model <id>] [--json]
+authswitch account preuse operation get <operation-id> [--json]
+authswitch account preuse operation cancel <operation-id> [--json]
+authswitch account preuse operation resume <operation-id> [--json]
+authswitch authority doctor [--json]
+```
+
+`account list --json` prints the complete, consistent credential-free authority snapshot.
+Its human form labels login health as stored state and does not imply a live provider check.
+`account add openai` starts one standalone OpenAI device login. `account reauth` starts one
+device login for the exact account and managed login IDs; it never chooses a presentation
+default. Both commands print the durable operation ID, verification URL, user code and changed
+receipts until completion. `account operation resume` polls only the supplied durable ID, while
+`get` performs one read and `cancel` performs one explicit cancellation. Ctrl-C or the local
+15-minute deadline detaches the CLI and leaves the daemon-owned operation running. If a start
+response is lost, the fixed diagnostic reports the caller-generated operation ID and exact resume
+command; the CLI does not replay the start request.
+
+`account preuse` sends one quota-consuming prompt through the exact managed OpenAI account and
+login IDs. The default prompt is `Write 2000 words about strawberries.`; `--prompt` replaces it
+and `--model` requests one exact model. `--all` freezes one consistent authority snapshot, walks
+its canonical daemon-owned OpenAI managed logins in snapshot order, and starts one fresh durable
+operation per login whose stored `canPreuse` capability is true. It does not infer readiness from
+plan, usage, token expiry or binding capability. A login whose snapshot capability is false is
+reported as skipped with the snapshot revision, login revision, stored health, problem and
+observation time; no request or operation ID is created for that skip.
+
+Preuse operations run sequentially and are never retried automatically. Every terminal receipt
+advances an `--all` run, including `not_sent` and `outcome_unknown`, while any attempted operation
+that does not complete makes the final exit status nonzero. Snapshot-ineligible skips alone do not
+make an otherwise successful batch fail. Running `--all` again is a new quota-consuming run with
+new operation IDs. Use `account preuse operation resume` to continue observing an existing receipt.
+Only the explicit `cancel` command asks the daemon to cancel one.
+
+For `account add`, `account reauth` and `account operation resume`, `--json` writes JSON Lines:
+each line is one complete operation receipt, and unchanged revisions are omitted. `account
+operation get --json` and `account operation cancel --json` each write one JSON object followed by
+a newline. Human output includes the resume command on every unfinished receipt. These device
+commands do not switch the active native login.
+
+For one preuse start or resume, `--json` likewise writes each complete changed receipt as one raw
+JSON Line; preuse get and cancel write one raw JSON object. A preuse `--all --json` stream tags each
+line as `operation` or `skipped`. Operation lines contain the complete durable receipt. Skip lines
+contain the exact account and login IDs plus the stored snapshot evidence described above. A lost
+start response, transport or output failure, Ctrl-C, or the local 15-minute observation deadline
+stops the batch before another login starts and reports the current operation ID and resume command.
+It detaches without replaying or implicitly cancelling the daemon operation.
+
+`authority doctor --json` incrementally writes one JSON document. Its `pages` array contains
+every independently stamped bounded page; `observationSpan` is written only after all cursors
+complete, and `globallyAtomic` is false. A failure during paging returns nonzero and leaves the
+document incomplete rather than presenting partial evidence as a successful observation span.
+The doctor command imposes no inventory cap. Account listing and doctor do not contact a provider,
+unseal a grant, mutate authority state, start the service, open the database offline or fall back
+to a legacy credential store.
+If the daemon is unavailable before the first response, it fails with a fixed diagnostic on
+stderr and leaves stdout empty. The older native-store commands documented below still coexist until the coordinated
+major-version migration and removal; these authority routes never use them.
+
+`AuthSwitchClient.getUsage(accountId, loginId)` reads OpenAI managed limits or a Claude
+host login's profile and usage through the management socket. The tagged, credential-free
+reading preserves Claude's labelled five-hour, weekly and model windows, plan provenance,
+extra usage facts and explicit partial availability. Missing values never become zero.
+The daemon caches one result in SmartData for a bounded current and stale period; a new
+reading emits one account event without changing the account row revision. Concurrent
+reads and rejected-token refresh share the existing provider and authority owners; usage
+adds no polling timer. Native Claude reads hold the qualified vendor-home lease through
+both status requests and publication, and revalidate the exact credential and config
+source even when serving a cached result. Native grants are never refreshed by the daemon.
+Pending, quarantined, setup-token-without-profile-scope and other unsupported contexts
+return explicit unavailable status without a provider request. Production native home
+adoption still requires the separate verified migration and backup cutover.
+
+`AuthSwitchClient.startPreuse()` accepts one client-generated operation UUID and one exact
+OpenAI account/login/purpose. The daemon resolves an access-only grant, optionally reads the
+model catalog, then commits `request_may_have_started` immediately before FlexHarness sends one
+inference with retries disabled. Reusing the UUID with the same request returns its durable receipt; changing
+the target, prompt or requested model is rejected. A crash, cancellation or shutdown after the
+marker remains `outcome_unknown` and is never replayed. Before-marker refusals are `not_sent`.
+Only the request hash, selected model, timing and safe token counts are stored; the prompt,
+generated prose and credentials are absent from persistence and management responses. Account
+removal and targeted reauthentication refuse while that account has an active preuse request.
+Historical restore marks every unresolved preuse receipt `outcome_unknown`, including snapshots
+captured before the marker, because the original authority may have sent after snapshot capture.
+
 A trusted in-process daemon host can call `AuthSwitchAuthorityDaemon.startManagedCodex()`
 for a bound account and workspace. It owns a private Codex 0.155.1 app-server, passes only
 the authority's current access token through Codex's external-token login, answers its
@@ -67,10 +200,16 @@ Callers supply a private, durable `codexHomeDirectory` for Codex's own configura
 conversation state. SmartData binds that home immutably to one account and scope, and the
 daemon records its active process/socket identity before launching it. Admission refuses
 an existing nonempty native home or a surviving app-server owner; a fresh empty home is
-created on first use. Account removal drains its managed Codex processes before the
-grant is removed, and targeted reauthentication holds new admissions until the device
-operation settles. Only the private socket directory is removed on close. Codex's
+created on first use. Account removal and reauthentication refuse while an in-memory or
+durably recorded managed Codex process for that account may still be running, including
+after daemon restart. A recorded run is cleared only when its exact process is proven
+gone; an uncertain launch remains blocked. Callers must explicitly stop owned processes
+after their work finishes. Once reauthentication starts, it holds new admissions until the
+device operation settles. Only the private socket directory is removed on close. Codex's
 credential store remains ephemeral and does not read or write `auth.json` in that home.
+Managed-Codex process ownership observation is qualified on Linux and reads exact argument
+boundaries from `/proc`; on other hosts doctor reports the process observation as unknown,
+and authority actions that require survivor proof refuse instead of guessing.
 Codex 0.155.1 does not persist an unused thread created by `thread/start`; resume applies
 after Codex has committed a rollout. The existing CLI has not yet been moved to this path.
 
@@ -83,6 +222,32 @@ remain vendor-owned; a container setup-token grant is a separate grant under the
 account. The one-time migration and deletion of authswitch's old stores are separate
 cutover steps.
 
+The backend-only Claude native handoff journals an exact two-file write and transfers
+ownership between two account grants in one SmartData transaction. An inactive Claude
+grant is refreshed by the daemon only after a durable pre-send marker; pending, native,
+and quarantined grants cannot enter that exchange. A native home and incoming grant
+require source-mapped migration receipts with backup metadata. The ledger field does
+not itself verify a SmartBucket backup, so the default daemon does not configure a
+Claude native home or run this path against real credentials. One-time migration and
+backup verification must precede production activation. Handoff receipts are queryable
+after a lost response. `runningEffectiveAuth: unsupported_effective_auth` means the
+native store changed, while an already-running Claude process's effective login cannot
+be proven externally; qualified live native-store switching still works.
+
+The authority database uses one versioned collection registry for startup preparation,
+ordered backup capture and exact restore readback. Startup rejects unknown collections,
+unknown metadata schemas and an incomplete restored database. Published 6.4/6.5 metadata
+is upgraded in place while account IDs, sealed grants, enrollments and uncertain states
+remain intact. A restored database keeps a durable closed-admission marker across restart;
+the daemon refuses provider and runtime work until a separate ownership-reconciliation
+step can prove it safe to open. Backup capture pins its paged records in one SmartData
+transaction and stages each retry anew before any SmartBucket publication. The closed
+restore rehearsal runs in a separate package-owned child, keeps its temporary source and
+record stream encrypted, restores metadata closed before any other record, then stops and
+reopens the same disposable database for exact stored readback. A receipt is issued only
+after the child has closed and its temporary root has been removed. This rehearsal does
+not perform a production restore or authorize a new authority instance to take ownership.
+
 ## Usage
 
 Run `authswitch`, `authswitch -i`, or `authswitch --interactive` for an interactive guide. Use the arrow keys and
@@ -975,7 +1140,7 @@ arguments to these commands exit with 2.
 
 `limits --json` emits `IAccountLimits` and `active --json` emits `IActiveAccounts`:
 the same rows as the tables, plus the machine-readable fields the tables condense —
-`accountId`, `slotId`, `accountType` (`{ plan, source }` with the adapter's plan
+`accountId`, `providerAccountId`, `slotId`, `accountType` (`{ plan, source }` with the adapter's plan
 name, such as `max` or `pro`, sanitised but not display-formatted, and `source` `live`
 or `stored`; null when no type is known or the row names no account; both documents
 carry it), the limits rows' `billing` (the account's reported `hasActiveSubscription`,
@@ -986,18 +1151,20 @@ it gave none) and `headline` (true for the window the provider picks for a
 single-value summary), the ISO `savedAt` beside the human `savedAgo`, the per-row
 `unavailableReason` that the footnotes summarise, and `drift`, which carries the
 expected and current account ids, their labels, whether the current one is saved,
-the ISO `switchedAt` of the switch that was undone, and the same sentence as `reason`. Both carry `schemaVersion: 1`, the
+the ISO `switchedAt` of the switch that was undone, and the same sentence as `reason`. `accountId` remains the opaque
+authswitch identifier used for harness operations; `providerAccountId` is the exact provider-native identifier, or null
+when the credential reports none. Both documents carry `schemaVersion: 2`, the
 shared `generatedAt` snapshot every countdown is relative to, and `complete`, which
 is false when any account or harness could not be read.
 
 The exported `IAccountList` contract contains:
 
-- `schemaVersion: 2`, `generatedAt` (ISO UTC), and `complete`.
+- `schemaVersion: 3`, `generatedAt` (ISO UTC), and `complete`.
 - `harnesses[]`: `id`, `label`, `loginHint`, `saveUnavailableReason`, `accounts`,
   `credentialDrift` (slots whose file no longer holds the account the last switch
   wrote), and harness-level `problems` (distinguishing failed discovery from an
   empty list).
-- Each account's opaque `id`, `label`, `isActive`, verified `isStashed`, `savedAt`,
+- Each account's opaque `id`, exact provider-native `providerAccountId` (or null), `label`, `isActive`, verified `isStashed`, `savedAt`,
   `details`, and `status` containing all labelled `facts`, `problems`, and optional
   typed `summary` fields. Missing fields remain omitted, not replaced by zero;
   `summary.usageWindows[]` carries `severity` and `headline` only when the provider
@@ -1009,9 +1176,9 @@ harness internals. A partial result still produces valid JSON and exits with 1;
 successful and empty results exit with 0. `complete` describes lookup success,
 not whether the provider exposes every possible metric.
 
-Version 2 of this JSON schema allows `usageWindows[].resetAt` to be null and adds
-optional account `slotId` fields. Consumers migrating from authswitch 1.x must
-accept schema version 2 and handle null reset timestamps. Scripts should qualify
+Version 3 adds `providerAccountId` without changing the opaque `id` used by mutation commands. Version 2 allowed
+`usageWindows[].resetAt` to be null and added optional account `slotId` fields. Consumers must
+accept schema version 3, preserve the two identifiers' distinct meanings and handle null provider IDs and reset timestamps. Scripts should qualify
 mutation commands with `codex`, `opencode` or `claude`, since all three now register
 by default. Saved Codex credentials retain their existing format.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/authswitch',
-  version: '6.5.0',
+  version: '7.0.0',
   description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
 }

package/ts/authority-contract.ts

@@ -1,7 +1,10 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
+import type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
+export type { IAuthSwitchUsageSnapshot } from './classes.authorityusage.js';
 
 /** Credential-free account management contract. Safe to import in browser code. */
-export type TAuthSwitchAccountHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'native' | 'legacy_native_pending' | 'removed';
+export type TAuthSwitchLoginPurpose = 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native';
+export type TAuthSwitchLoginHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'unverified' | 'pending_handoff' | 'handoff_quarantined' | 'removed';
 
 export interface IAuthSwitchAccount {
   id: string;
@@ -9,14 +12,26 @@ export interface IAuthSwitchAccount {
   label: string;
   email: string | null;
   plan: string | null;
-  health: TAuthSwitchAccountHealth;
+  removed: boolean;
+  revision: number;
+  statusObservedAt: string;
+}
+
+/** One independently owned login. Native ownership does not imply observed health. */
+export interface IAuthSwitchLogin {
+  id: string;
+  accountId: string;
+  providerId: string;
+  purpose: TAuthSwitchLoginPurpose;
   owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none';
+  health: TAuthSwitchLoginHealth;
+  problem: 'none' | 'provider_unavailable' | 'exchange_uncertain' | 'provider_rejected' | 'native_owner';
   grantGeneration: number;
   revision: number;
   accessExpiresAt: string | null;
   retryAt: string | null;
-  problem: 'none' | 'provider_unavailable' | 'exchange_uncertain' | 'provider_rejected' | 'native_owner';
   statusObservedAt: string;
+  capabilities: { canReauthenticate: boolean; canBind: boolean; canPreuse: boolean };
 }
 
 export interface IAuthSwitchBinding {
@@ -29,16 +44,152 @@ export interface IAuthSwitchBinding {
 }
 
 export interface IAuthSwitchSnapshot {
-  schemaVersion: 1;
+  schemaVersion: 2;
   epoch: string;
   revision: number;
   generatedAt: string;
   accounts: IAuthSwitchAccount[];
+  logins: IAuthSwitchLogin[];
   bindings: IAuthSwitchBinding[];
   nextAccountCursor: string | null;
+  nextLoginCursor: string | null;
   nextBindingCursor: string | null;
 }
 
+/** Persisted account evidence. No provider request is made while collecting diagnostics. */
+export interface IAuthSwitchDoctorAccountEvidence {
+  id: string;
+  providerId: string;
+  removed: boolean;
+  statusObservedAt: string;
+  evidence: 'stored';
+  liveCheck: 'not_checked';
+}
+
+/** Persisted login evidence. Stored readiness is not a live provider-health claim. */
+export interface IAuthSwitchDoctorLoginEvidence {
+  id: string;
+  accountId: string;
+  providerId: string;
+  purpose: TAuthSwitchLoginPurpose;
+  owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none';
+  state: 'ready' | 'exchange_may_have_been_sent' | 'retry_wait' | 'needs_reauth' | 'native'
+    | 'legacy_native_pending' | 'handoff_pending' | 'handoff_quarantined' | 'removed';
+  problem: 'none' | 'provider_unavailable' | 'exchange_uncertain' | 'provider_rejected' | 'native_owner';
+  grantGeneration: number;
+  authorizationGeneration: number;
+  accessExpiresAt: string | null;
+  retryAt: string | null;
+  statusObservedAt: string;
+  evidence: 'stored';
+  liveCheck: 'not_checked';
+}
+
+export interface IAuthSwitchDoctorManagedCodex {
+  homeId: string;
+  accountId: string;
+  loginId: string;
+  scopeId: string;
+  health: 'healthy' | 'degraded' | 'unknown';
+  durable: {
+    state: 'idle' | 'launch_prepared' | 'registered';
+    runId: string | null;
+    pid: number | null;
+    startedAt: string | null;
+  };
+  daemon: {
+    state: 'untracked' | 'starting' | 'ready' | 'stopping' | 'degraded';
+    assignment: 'untracked' | 'matches' | 'mismatch';
+  };
+  process: {
+    state: 'not_expected' | 'absent' | 'observed' | 'unknown';
+    identity: 'not_applicable' | 'unregistered' | 'matches' | 'mismatch' | 'unknown';
+    pid: number | null;
+    startedAt: string | null;
+    observedAt: string;
+    problem: 'none' | 'inspection_failed' | 'multiple_claimants';
+  };
+}
+
+export interface IAuthSwitchDoctorClaudeHome {
+  id: string;
+  activeAccountId: string;
+  activeLoginId: string;
+  pendingOperationId: string | null;
+  status: 'ready' | 'quarantined';
+  revision: number;
+  createdAt: string;
+}
+
+export interface IAuthSwitchDoctorClaudeHandoff {
+  id: string;
+  homeId: string;
+  outgoingAccountId: string;
+  outgoingLoginId: string;
+  incomingAccountId: string;
+  incomingLoginId: string;
+  phase: 'reserved' | 'prepared' | 'committed' | 'aborted' | 'quarantined';
+  problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
+  runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
+  startedAt: string;
+  updatedAt: string;
+  revision: number;
+}
+
+export interface IAuthSwitchDoctorNativeHandoff {
+  id: string;
+  accountId: string;
+  loginId: string;
+  nativeHomeId: string;
+  direction: 'to_native' | 'to_daemon';
+  phase: 'prepared' | 'source_stopped' | 'target_written' | 'verified' | 'committed' | 'needs_reauth' | 'aborted';
+  operationId: string;
+  revision: number;
+  statusObservedAt: string;
+}
+
+export interface IAuthSwitchDoctorMigration {
+  id: string;
+  sourceKind: 'authswitch_stash' | 'authswitch_backup' | 'agl_flex' | 'codex_native' | 'opencode_native' | 'claude_native';
+  status: 'pending_native_owner' | 'prepared' | 'verified' | 'complete' | 'quarantined';
+  accountId: string | null;
+  loginId: string | null;
+  revision: number;
+  statusObservedAt: string;
+}
+
+/** One independently observed diagnostic page. Separate pages are not one atomic global snapshot. */
+export interface IAuthSwitchDoctorPage {
+  observedAt: string;
+  daemon: {
+    state: 'ready' | 'closing';
+    claudeNativeAuthority: 'configured' | 'not_configured';
+    observedAt: string;
+  };
+  database: {
+    state: 'available';
+    observedAt: string;
+    schemaVersion: 2;
+    admission: 'open' | 'closed_restored';
+    epoch: string;
+    revision: number;
+  };
+  accounts: IAuthSwitchDoctorAccountEvidence[];
+  logins: IAuthSwitchDoctorLoginEvidence[];
+  managedCodex: IAuthSwitchDoctorManagedCodex[];
+  claudeHomes: IAuthSwitchDoctorClaudeHome[];
+  claudeHandoffs: IAuthSwitchDoctorClaudeHandoff[];
+  nativeHandoffs: IAuthSwitchDoctorNativeHandoff[];
+  migrations: IAuthSwitchDoctorMigration[];
+  nextAccountCursor: string | null;
+  nextLoginCursor: string | null;
+  nextCodexHomeCursor: string | null;
+  nextClaudeHomeCursor: string | null;
+  nextClaudeHandoffCursor: string | null;
+  nextNativeHandoffCursor: string | null;
+  nextMigrationCursor: string | null;
+}
+
 export interface IAuthSwitchAccountEvent {
   epoch: string;
   revision: number;
@@ -52,18 +203,97 @@ export type TAuthSwitchLoginPrompt =
 
 export interface IAuthSwitchOperation {
   id: string;
-  state: 'pending' | 'complete' | 'failed' | 'cancelled';
+  kind: 'add_openai' | 'reauth_openai';
+  purpose: 'openai_managed';
+  targetAccountId: string | null;
+  targetLoginId: string | null;
+  state: 'starting' | 'pending' | 'committing' | 'complete' | 'failed' | 'cancelled' | 'interrupted' | 'outcome_unknown';
   prompt: TAuthSwitchLoginPrompt | null;
-  account: IAuthSwitchAccount | null;
+  result: { accountId: string; loginId: string; accountRevision: number; loginGeneration: number } | null;
   error: string | null;
+  createdAt: string;
+  updatedAt: string;
+  finishedAt: string | null;
+  revision: number;
+}
+
+/** Credential-free receipt for one exact, never-replayed quota-consuming request. */
+export interface IAuthSwitchPreuseOperation {
+  id: string;
+  accountId: string;
+  loginId: string;
+  purpose: 'openai_managed';
+  requestedModel: string | null;
+  model: string | null;
+  state: 'preparing' | 'request_may_have_started' | 'complete' | 'not_sent' | 'outcome_unknown';
+  result: { inputTokens: number | null; outputTokens: number | null; totalTokens: number | null } | null;
+  problem: 'none' | 'target_unavailable' | 'access_unavailable' | 'catalog_unavailable'
+    | 'account_busy' | 'cancelled' | 'authority_closing' | 'interrupted'
+    | 'request_uncertain' | 'restored_history_uncertain';
+  createdAt: string;
+  updatedAt: string;
+  finishedAt: string | null;
+  revision: number;
+}
+
+/** Credential-free native file ownership result. It makes no claim about a running session's active request. */
+export interface IAuthSwitchClaudeNativeHandoff {
+  id: string;
+  homeId: string;
+  outgoingAccountId: string;
+  incomingAccountId: string;
+  phase: 'reserved' | 'prepared' | 'committed' | 'aborted' | 'quarantined';
+  problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
+  runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
+  updatedAt: string;
+}
+
+export interface IReq_AuthSwitchSwitchClaudeNative extends ITypedRequest {
+  method: 'authswitch.authority.claude.switch';
+  request: { accountId: string; loginId: string; purpose: 'claude_host_native' };
+  response: { handoff: IAuthSwitchClaudeNativeHandoff };
+}
+
+export interface IReq_AuthSwitchClaudeNativeHandoff extends ITypedRequest {
+  method: 'authswitch.authority.claude.handoff';
+  request: { operationId: string };
+  response: { handoff: IAuthSwitchClaudeNativeHandoff };
+}
+
+export interface IReq_AuthSwitchClaudeNativeHandoffs extends ITypedRequest {
+  method: 'authswitch.authority.claude.handoffs';
+  request: { after?: string; limit?: number };
+  response: { handoffs: IAuthSwitchClaudeNativeHandoff[]; nextCursor: string | null };
 }
 
 export interface IReq_AuthSwitchSnapshot extends ITypedRequest {
   method: 'authswitch.authority.snapshot';
-  request: { accountAfter?: string; bindingAfter?: string; limit?: number };
+  request: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number };
   response: { snapshot: IAuthSwitchSnapshot };
 }
 
+export interface IReq_AuthSwitchDoctor extends ITypedRequest {
+  method: 'authswitch.authority.doctor';
+  request: {
+    accountAfter?: string;
+    loginAfter?: string;
+    codexHomeAfter?: string;
+    claudeHomeAfter?: string;
+    claudeHandoffAfter?: string;
+    nativeHandoffAfter?: string;
+    migrationAfter?: string;
+    limit?: number;
+  };
+  response: { page: IAuthSwitchDoctorPage };
+}
+
+/** Management-only usage read. The DTO contains no access or refresh credential. */
+export interface IReq_AuthSwitchUsage extends ITypedRequest {
+  method: 'authswitch.authority.usage';
+  request: { accountId: string; loginId: string; force?: boolean };
+  response: { usage: IAuthSwitchUsageSnapshot };
+}
+
 export interface IReq_AuthSwitchEvents extends ITypedRequest {
   method: 'authswitch.authority.events';
   request: { epoch: string; afterRevision: number; waitMs: number };
@@ -72,16 +302,22 @@ export interface IReq_AuthSwitchEvents extends ITypedRequest {
 
 export interface IReq_AuthSwitchBeginAdd extends ITypedRequest {
   method: 'authswitch.authority.add';
-  request: { providerId: 'openai'; flow: 'device' };
+  request: { operationId: string; providerId: 'openai'; flow: 'device' };
   response: { operation: IAuthSwitchOperation };
 }
 
 export interface IReq_AuthSwitchBeginReauth extends ITypedRequest {
   method: 'authswitch.authority.reauth';
-  request: { accountId: string; flow: 'device' };
+  request: { operationId: string; accountId: string; loginId: string; purpose: 'openai_managed'; flow: 'device' };
   response: { operation: IAuthSwitchOperation };
 }
 
+export interface IReq_AuthSwitchListOperations extends ITypedRequest {
+  method: 'authswitch.authority.operations';
+  request: { after?: string; limit?: number };
+  response: { operations: IAuthSwitchOperation[]; nextCursor: string | null };
+}
+
 export interface IReq_AuthSwitchGetOperation extends ITypedRequest {
   method: 'authswitch.authority.operation';
   request: { operationId: string };
@@ -94,6 +330,25 @@ export interface IReq_AuthSwitchCancelOperation extends ITypedRequest {
   response: { operation: IAuthSwitchOperation };
 }
 
+export interface IReq_AuthSwitchStartPreuse extends ITypedRequest {
+  method: 'authswitch.authority.preuse.start';
+  request: { operationId: string; accountId: string; loginId: string; purpose: 'openai_managed';
+    prompt: string; model?: string };
+  response: { operation: IAuthSwitchPreuseOperation };
+}
+
+export interface IReq_AuthSwitchGetPreuse extends ITypedRequest {
+  method: 'authswitch.authority.preuse.operation';
+  request: { operationId: string };
+  response: { operation: IAuthSwitchPreuseOperation };
+}
+
+export interface IReq_AuthSwitchCancelPreuse extends ITypedRequest {
+  method: 'authswitch.authority.preuse.cancel';
+  request: { operationId: string };
+  response: { operation: IAuthSwitchPreuseOperation };
+}
+
 export interface IReq_AuthSwitchRenameAccount extends ITypedRequest {
   method: 'authswitch.authority.rename';
   request: { accountId: string; expectedRevision: number; label: string };

package/ts/authority-runtime-contract.ts

@@ -6,6 +6,8 @@ export interface IReq_AuthSwitchBindAccount extends ITypedRequest {
   method: 'authswitch.authority.bind';
   request: {
     accountId: string;
+    loginId: string;
+    purpose: 'openai_managed';
     runtime: IAuthSwitchBinding['runtime'];
     scopeId: string;
     incarnationId: string;
@@ -31,3 +33,15 @@ export interface IReq_AuthSwitchResolveAccess extends ITypedRequest {
     grantGeneration: number;
   };
 }
+
+/** Backend-only release for one exact external runtime capability. */
+export interface IReq_AuthSwitchReleaseBinding extends ITypedRequest {
+  method: 'authswitch.authority.release';
+  request: {
+    bindingId: string;
+    capability: string;
+  };
+  response: {
+    state: 'released' | 'inactive';
+  };
+}