@modelprofile.com/authswitch 9.0.0 → 9.1.0

package/readme.md

@@ -37,6 +37,18 @@ that tool -- `ownerTool` is `claude_code`, `codex` or `opencode`, and `null` exa
 native tool holds it, because the authority refreshes it or nothing does. The authority
 names it rather than leaving a consumer to derive it from the purpose, which would be wrong
 as soon as two purposes share a tool or one tool gains a second purpose.
+The snapshot also lists `nativeAssignments`: which account a vendor tool's own home on this host runs on,
+as `{ id, tool, accountId, loginId, state, revision }` with the home named by its hash. Only homes the
+authority itself switches are recorded -- Claude Code homes adopted by a verified import -- and `state` is
+`switching` while a handoff to another account is in flight and `quarantined` until one is resolved. A
+Codex or OpenCode store that its own tool still refreshes appears as its login instead, with
+`owner: 'legacy_native'` and its `ownerTool`, because the authority does not decide what that store holds.
+Every change of an assignment is an account event, so a subscriber sees it like any other change.
+A removed account is left out of the snapshot unless the caller asks with `includeRemoved` (on `snapshot`,
+`snapshotAll` and `subscribe`): it then appears with `removed: true` and its logins with `health: 'removed'`.
+An account label follows one published rule, `isAuthSwitchAccountLabel` (at most
+`authSwitchAccountLabelMaxLength` characters, no space at either end, no control character); a rename that
+breaks it is refused with `invalid_input`.
 
 ```ts
 import { randomUUID } from 'node:crypto';
@@ -50,6 +62,11 @@ 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);
+// Or follow it without polling: each answer comes when the operation changes.
+let current = operation;
+while (['starting', 'pending', 'committing'].includes(current.state)) {
+  current = await client.watchOperation(current.id, current.revision);
+}
 ```
 
 Browser code can import the credential-free DTOs from
@@ -64,7 +81,11 @@ never create one. A backend binds an account to a runtime incarnation by exact a
 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
+`listOperations()`. `watchOperation(id, afterRevision, waitMs = 30000)` is the same read as a long poll,
+the way `events` waits: it answers as soon as the operation's revision passes `afterRevision` -- a sign-in
+answers `starting` with no prompt, then `pending` with its device prompt, then its outcome -- at once for a
+finished operation, and with the unchanged operation once `waitMs` (at most 30000) runs out. Only a change
+of that operation answers it. 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
@@ -75,16 +96,29 @@ resolves that binding to a current access token; its directory can be mounted in
 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
+A ChatGPT login backs a Claude Code runtime too (`runtime: 'claude'`); a Claude account never binds,
+because it reaches Claude Code through the native switch. After an external Flex, OpenCode or Claude
+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.
+or changes ownership of the account grant. A holder that crashed and lost its capability recovers
+its binding without a new route: the snapshot (and `getBinding`) publishes each binding's runtime and
+scope, binding that runtime and scope again replaces the capability, and releasing the returned
+capability releases the binding. If binding again is refused because the account needs a new sign-in,
+reauthenticate it first.
+
+`getBinding(bindingId)` (`authswitch.authority.binding`) reads one binding by the id `bind` returned,
+credential-free, or `null` once the authority holds none by that id, so a backend checks its binding without
+reading the whole snapshot.
+
+Removing an account that still backs a Flex, OpenCode or Claude binding is refused with `account_busy`, naming
+those runtimes: their holder stops them and releases the bindings first, so a removal never strands a
+runtime whose next access would fail. Managed Codex bindings are the daemon's own; removal drains managed
+Codex as before and then takes them with the account.
 
 Every route on either socket answers in one of three ways: a result, a **refusal**, or a fault. A refusal
 is an answer -- the daemon completed its check, nothing was left half-done, and its message says what the
@@ -99,7 +133,8 @@ that marker: it answers `{ code, instruction }` for a refusal and `null` for a f
 closed `TAuthSwitchRefusalCode` set, which is what a client branches on without reading the text:
 `authority_closing`, `not_found`, `account_changed`, `account_busy`, `login_unavailable`,
 `binding_unauthorized`, `native_owner_holds_login`, `claude_home_unregistered`, `claude_handoff_pending`,
-`claude_receipt_missing` and `import_refusal`, plus the two the legacy commands answer with on this side of
+`claude_receipt_missing`, `import_refusal`, `codex_unsupported`, `invalid_input`, `login_needs_reauth` and
+`access_not_fresh`, plus the two the legacy commands answer with on this side of
 the socket, `authority_holds_login` and `authority_unavailable` (see "The legacy fence" below). The
 instruction is authored for the owner and contains no path, credential or digest; only an importer refusal
 may name the process the owner has to stop. The set is producer-owned: a consumer branches on the codes it
@@ -112,10 +147,12 @@ credential was being resolved. Those are one answer on purpose: an absent bindin
 compared against the same zero hash, so nothing distinguishes them, and the repair is the same either way --
 bind again. A binding whose account has since been reauthorized reads `login_unavailable` instead, because
 binding again cannot help until that account holds a login again. A device sign-in or preuse operation this
-authority does not hold reads `not_found`, from whichever route met it. Two things stay unmarked faults on
-purpose. What the shared managed-access loop refuses is one: it serves a bound runtime and the
-credential-free usage reader alike, and those two repair differently. Binding an *account* this authority
-does not hold at all is the other: the storage layer throws `Account is not available for this runtime.`,
+authority does not hold reads `not_found`, from whichever route met it. What the access loop decides about
+the login itself is marked as well: `login_needs_reauth` when only a new device sign-in brings the login back
+(after which a bound runtime binds again), and `access_not_fresh` when the login is intact but the provider
+could not renew its access yet, so the same request can succeed later. A changed identity or a view that
+keeps moving during resolution stays an unmarked fault, because nobody decided it. Binding an *account* this
+authority does not hold at all stays one too: the storage layer throws `Account is not available for this runtime.`,
 which a socket caller reads as `Internal server error`, because naming it is a decision about which layer
 authors owner instructions rather than a wording fix.
 
@@ -128,6 +165,15 @@ and the ledger row it wrote says where that source stands -- while an unmarked f
 unknown, and that source must then be read with `authswitch.authority.import.status` rather than
 submitted again.
 
+A daemon that is shutting down admits no new request -- every route answers `authority_closing` -- and
+settles the requests it already admitted before it closes its store: a waiting `events` or
+`watchOperation` read answers normally from the open store instead of failing.
+
+A client reading a daemon that runs an older release -- one not restarted after an upgrade -- fails with
+`AuthSwitchDaemonOutdatedError`, which names the restart (`authswitch authority service stop`, then
+`start`), and a subscription reports `unavailable` with the reason `daemon_outdated` once and retries every
+five seconds until the daemon is restarted.
+
 `AuthSwitchClient.subscribe(onSnapshot, onEvent, signal, { onStatus })` reports `current`
 after a fresh snapshot or verified heartbeat, `unavailable` on disconnect or resync, and
 `closed` on abort. Keep cached account actions disabled while status is not `current`.
@@ -293,7 +339,9 @@ that refusal nor "already imported" ever clears: no route forgets a row or re-po
 
 `import status` reads the migration ledger, the grants and the handoffs -- never the host -- and reports, per
 source, where it stands, which owner refreshes its login now, and what to do next: nothing, submit the same
-source again, or sign in to that account again. Submitting a source again is how an interrupted run resumes,
+source again, or sign in to that account again. Each entry also carries the source's `sourcePathHash`, so a
+backend that submitted an external source finds its own record by `sourceKind` and that hash -- also after a
+submit whose outcome it never learned -- without deriving the ledger row id. Submitting a source again is how an interrupted run resumes,
 and the answer comes from the same durable record the daemon decides on: a source whose sign-in was in
 flight when the run died is reported as needing a device sign-in, not as resumable, because a rotating
 refresh token is never sent a second time. Sources that were never submitted have no ledger row and appear
@@ -339,7 +387,7 @@ generated prose and credentials are absent from persistence and management respo
 removal and targeted reauthentication refuse while that account has an active preuse request.
 
 A trusted in-process daemon host can call `AuthSwitchAuthorityDaemon.startManagedCodex()`
-for a bound account and workspace. It owns a private Codex 0.157.0 app-server, passes only
+for a bound account and workspace. It owns a private Codex app-server, passes only
 the authority's current access token through Codex's external-token login, answers its
 unauthorized callback through the authority, and revokes the binding on stop. The returned
 runtime exposes an interactive `codex --remote unix://…` launch descriptor and native
@@ -363,13 +411,23 @@ directory other users cannot rewrite, and the socket behind it is the user's own
 directory of the user's; anything else fails the start with that package's error. Codex keeps a
 zero-byte startup lock in that directory for each socket path it has served; the file is
 Codex's own and authswitch does not remove it.
-Managed Codex runs only the verified Codex release: a `codex` that reports any other
-version is refused before it starts, so an automatic Codex update stops new managed
-sessions until authswitch has verified that release.
+Managed Codex runs Codex 0.156.0 or newer -- the floor `@modelprofile.com/mcp-crossharness`'s
+`requireCodexVersion` checks, the first release that publishes the socket alias -- and checks the
+contract at every start instead of pinning one release. Before anything is recorded or started, the
+`codex` it will run must report a readable version at or above the floor, and its own protocol
+description (`codex app-server generate-json-schema`) must still offer every surface managed Codex uses:
+the requests `account/login/start`, `thread/start`, `thread/resume` and `turn/start`; the external
+ChatGPT token login with the fields it sends; the `account/chatgptAuthTokens/refresh` callback with the
+`unauthorized` reason and the reply it gives; and the thread and turn parameters it sends. After
+connecting, the app-server must report exactly the version that was checked, because Codex can replace
+itself between the check and the start. Each failure is the `codex_unsupported` refusal naming the
+version or the missing surface, so a Codex update that drops something managed Codex relies on stops new
+managed sessions by name instead of failing one later. A prerelease above the floor runs; a prerelease of
+0.156.0 itself is below it.
 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.157.0 does not persist an unused thread created by `thread/start`; resume applies
+Codex (verified through 0.157) 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.
 
 This SDK is additive at this stage. The commands documented below still use the existing

package/ts/00_commitinfo_data.ts

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

package/ts/authority-contract.ts

@@ -25,7 +25,15 @@ export type TAuthSwitchRefusalCode =
   | 'claude_home_unregistered'
   | 'claude_handoff_pending'
   | 'claude_receipt_missing'
-  | 'import_refusal';
+  | 'import_refusal'
+  /** The Codex on this host is older than managed Codex runs, or no longer offers a surface it uses. */
+  | 'codex_unsupported'
+  /** A value the owner typed breaks a rule the instruction states, such as an account label. */
+  | 'invalid_input'
+  /** The account's login has ended and only a new device sign-in brings it back. */
+  | 'login_needs_reauth'
+  /** The login is intact, but the provider could not renew its access yet; the same request can succeed later. */
+  | 'access_not_fresh';
 
 /** The marker the importer has published since 8.1.0; it keeps its own value on the wire. */
 export const authSwitchImportRefusalMarker = 'authswitch_import_refusal';
@@ -50,7 +58,8 @@ const refusalCodes: ReadonlySet<string> = new Set<TAuthSwitchRefusalCode>([
   'authority_closing', 'not_found', 'account_changed', 'account_busy',
   'login_unavailable', 'binding_unauthorized', 'native_owner_holds_login', 'claude_home_unregistered',
   'claude_handoff_pending', 'claude_receipt_missing', 'import_refusal',
-  'authority_holds_login', 'authority_unavailable',
+  'authority_holds_login', 'authority_unavailable', 'codex_unsupported', 'invalid_input',
+  'login_needs_reauth', 'access_not_fresh',
 ]);
 
 const isRefusalCode = (value: unknown): value is TAuthSwitchRefusalCode =>
@@ -102,6 +111,18 @@ export const asAuthSwitchRefusal = (error: unknown): IAuthSwitchRefusal | null =
   return { code, instruction };
 };
 
+/** The longest account label, in UTF-16 code units. */
+export const authSwitchAccountLabelMaxLength = 128;
+
+/**
+ * The account label rule, the one the authority applies to a rename: one to `authSwitchAccountLabelMaxLength`
+ * characters, no space at either end, no control character. A consumer validates with this rather than
+ * restating it; the authority answers a label that breaks it with the `invalid_input` refusal.
+ */
+export const isAuthSwitchAccountLabel = (value: unknown): value is string => typeof value === 'string'
+  && value.trim() === value && value.length > 0 && value.length <= authSwitchAccountLabelMaxLength
+  && !/[\u0000-\u001f\u007f]/.test(value);
+
 /** Credential-free account management contract. Safe to import in browser code. */
 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';
@@ -149,12 +170,35 @@ export interface IAuthSwitchLogin {
 export interface IAuthSwitchBinding {
   id: string;
   accountId: string;
+  /**
+   * The runtime an OpenAI (ChatGPT) login backs. `flex`, `opencode` and `claude` bindings are held and
+   * released by their caller over the runtime socket; `codex` is the daemon's own managed Codex. A Claude
+   * account never binds: it reaches Claude Code through the native switch.
+   */
   runtime: 'flex' | 'codex' | 'opencode' | 'claude';
   scopeId: string;
   incarnationId: string;
   revision: number;
 }
 
+/**
+ * Which account a vendor tool's own home on this host runs on. Credential-free: the home is named by the
+ * hash the authority registered it under, never by its path.
+ *
+ * Only homes the authority itself switches are recorded: Claude Code homes adopted by a verified import.
+ * A Codex or OpenCode store that a native tool still refreshes appears as its login instead, with
+ * `owner: 'legacy_native'` and its `ownerTool`, because the authority does not decide what that store holds.
+ */
+export interface IAuthSwitchNativeAssignment {
+  id: string;
+  tool: TAuthSwitchLoginOwnerTool;
+  accountId: string;
+  loginId: string;
+  /** `switching` while a handoff to another account is in flight; `quarantined` until it is resolved. */
+  state: 'ready' | 'switching' | 'quarantined';
+  revision: number;
+}
+
 export interface IAuthSwitchSnapshot {
   schemaVersion: 2;
   epoch: string;
@@ -163,9 +207,11 @@ export interface IAuthSwitchSnapshot {
   accounts: IAuthSwitchAccount[];
   logins: IAuthSwitchLogin[];
   bindings: IAuthSwitchBinding[];
+  nativeAssignments: IAuthSwitchNativeAssignment[];
   nextAccountCursor: string | null;
   nextLoginCursor: string | null;
   nextBindingCursor: string | null;
+  nextNativeAssignmentCursor: string | null;
 }
 
 /** Persisted account evidence. No provider request is made while collecting diagnostics. */
@@ -391,7 +437,13 @@ export interface IReq_AuthSwitchClaudeNativeHandoffs extends ITypedRequest {
 
 export interface IReq_AuthSwitchSnapshot extends ITypedRequest {
   method: 'authswitch.authority.snapshot';
-  request: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number };
+  request: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; nativeAssignmentAfter?: string;
+    limit?: number;
+    /**
+     * Also publish removed accounts (`removed: true`) and their removed logins (`health: 'removed'`), so a
+     * consumer can show them apart. Absent or false keeps the snapshot to what is live.
+     */
+    includeRemoved?: boolean };
   response: { snapshot: IAuthSwitchSnapshot };
 }
 
@@ -441,9 +493,14 @@ export interface IReq_AuthSwitchListOperations extends ITypedRequest {
   response: { operations: IAuthSwitchOperation[]; nextCursor: string | null };
 }
 
+/**
+ * One device sign-in. `afterRevision` and `waitMs` come together or not at all: with them the read is a long
+ * poll that answers once the operation's revision passes `afterRevision`, at once for a finished sign-in, or
+ * with the unchanged operation after `waitMs` (at most 30000).
+ */
 export interface IReq_AuthSwitchGetOperation extends ITypedRequest {
   method: 'authswitch.authority.operation';
-  request: { operationId: string };
+  request: { operationId: string; afterRevision?: number; waitMs?: number };
   response: { operation: IAuthSwitchOperation };
 }
 
@@ -478,6 +535,16 @@ export interface IReq_AuthSwitchRenameAccount extends ITypedRequest {
   response: { account: IAuthSwitchAccount };
 }
 
+/**
+ * One binding by the id `bind` returned, credential-free, or `null` when this authority holds no binding by
+ * that id. A backend checks that its binding still stands without reading the whole snapshot.
+ */
+export interface IReq_AuthSwitchGetBinding extends ITypedRequest {
+  method: 'authswitch.authority.binding';
+  request: { bindingId: string };
+  response: { binding: IAuthSwitchBinding | null };
+}
+
 export interface IReq_AuthSwitchRemoveAccount extends ITypedRequest {
   method: 'authswitch.authority.remove';
   request: { accountId: string; expectedRevision: number };

package/ts/authority-import-contract.ts

@@ -173,6 +173,12 @@ export const isAuthSwitchImportRefusal = (error: unknown): boolean =>
 export interface IAuthSwitchImportStatusEntry {
   sourceId: string;
   sourceKind: TAuthSwitchImportSourceKind;
+  /**
+   * The source location as a hash, exactly as it was submitted or inventoried. A backend that submits an
+   * external source finds its own record here by `sourceKind` and this hash, including after a submit whose
+   * outcome it never learned.
+   */
+  sourcePathHash: string;
   status: TAuthSwitchImportLedgerStatus;
   accountId: string | null;
   loginId: string | null;

package/ts/classes.authoritybroker.ts

@@ -1,9 +1,10 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchAccount, IAuthSwitchAccountEvent, IAuthSwitchBinding, IAuthSwitchLogin,
-  IAuthSwitchOperation, IAuthSwitchSnapshot, TAuthSwitchLoginOwnerTool } from './authority-contract.js';
-import { AuthSwitchRefusal } from './authority-contract.js';
+  IAuthSwitchNativeAssignment, IAuthSwitchOperation, IAuthSwitchSnapshot, IReq_AuthSwitchSnapshot,
+  TAuthSwitchLoginOwnerTool } from './authority-contract.js';
+import { AuthSwitchRefusal, isAuthSwitchAccountLabel } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
-import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityGrant,
+import type { IStoredAuthorityAccount, IStoredAuthorityBinding, IStoredAuthorityClaudeHome, IStoredAuthorityGrant,
   IStoredAuthorityDeviceOperation } from './classes.authoritymodels.js';
 import type { IAuthSwitchUsageContext } from './classes.authorityusage.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
@@ -41,8 +42,6 @@ const sameUsageAuthority = (left: IAuthSwitchUsageContext, right: IAuthSwitchUsa
 const isUuid = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value);
 const deviceOperationTerminal = (operation: IStoredAuthorityDeviceOperation): boolean =>
   !['starting', 'pending', 'committing'].includes(operation.state);
-const safeLabel = (value: unknown): value is string => typeof value === 'string' && value.trim() === value
-  && value.length > 0 && value.length <= 128 && !/[\u0000-\u001f\u007f]/.test(value);
 const safeScope = (value: unknown, maximum: number): value is string => typeof value === 'string'
   && value.length > 0 && value.length <= maximum && !/[\u0000-\u001f\u007f]/.test(value);
 const validRevision = (value: unknown): value is number => Number.isSafeInteger(value) && Number(value) >= 0;
@@ -70,6 +69,10 @@ const bindingMoved = 'This runtime binding changed while its credential was bein
   + 'account again.';
 const bindingNeedsReauth = 'The account no longer holds the login this binding was authorized for. '
   + 'Reauthenticate the account, then bind it again.';
+const loginNeedsReauth = 'This account\'s sign-in has ended. Reauthenticate the account with a new device '
+  + 'sign-in; a runtime bound to it binds again afterwards.';
+const accessNotFresh = 'The provider could not renew this account\'s access yet. Try the request again '
+  + 'shortly; the authority keeps retrying the renewal.';
 const publicAccount = (account: IStoredAuthorityAccount): IAuthSwitchAccount => ({
   id: account.id, providerId: account.providerId, label: account.label, email: account.email,
   plan: account.plan, removed: account.removed, revision: account.revision,
@@ -133,6 +136,12 @@ const publicBinding = (binding: IStoredAuthorityBinding): IAuthSwitchBinding =>
   scopeId: binding.scopeId, incarnationId: binding.incarnationId, revision: binding.revision,
 });
 
+const publicClaudeAssignment = (home: IStoredAuthorityClaudeHome): IAuthSwitchNativeAssignment => ({
+  id: home.id, tool: 'claude_code', accountId: home.activeAccountId, loginId: home.activeGrantId,
+  state: home.status === 'quarantined' ? 'quarantined' : home.pendingOperationId !== null ? 'switching' : 'ready',
+  revision: home.revision,
+});
+
 interface IManagedOperation {
   id: string;
   handle: plugins.flexAccounts.ISmartAiProviderLoginHandle;
@@ -154,6 +163,8 @@ export class AuthSwitchAuthorityBroker {
   private readonly operations = new Map<string, IManagedOperation>();
   private readonly refreshes = new Map<string, Promise<void>>();
   private readonly listeners = new Set<() => void>();
+  /** Operation long polls; woken by their operation's own changes, and all of them on close. */
+  private readonly operationWaiters = new Set<() => void>();
   private claudeRefresh?: (grantId: string) => Promise<void>;
   private maintenance?: Promise<void>;
   private timer?: NodeJS.Timeout;
@@ -267,19 +278,23 @@ export class AuthSwitchAuthorityBroker {
     for (const listener of this.listeners) listener();
   }
 
-  public async snapshot(options: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number } = {}): Promise<IAuthSwitchSnapshot> {
+  public async snapshot(options: IReq_AuthSwitchSnapshot['request'] = {}): Promise<IAuthSwitchSnapshot> {
     if ((options.accountAfter !== undefined && !isId(options.accountAfter))
       || (options.loginAfter !== undefined && !isId(options.loginAfter))
-      || (options.bindingAfter !== undefined && !isId(options.bindingAfter))) throw new Error('Invalid account snapshot cursor.');
+      || (options.bindingAfter !== undefined && !isId(options.bindingAfter))
+      || (options.nativeAssignmentAfter !== undefined && !isId(options.nativeAssignmentAfter))) {
+      throw new Error('Invalid account snapshot cursor.');
+    }
     const page = await this.database.page(options.accountAfter ?? null, options.loginAfter ?? null,
-      options.bindingAfter ?? null, options.limit ?? 128);
+      options.bindingAfter ?? null, options.nativeAssignmentAfter ?? null, options.limit ?? 128);
     return { schemaVersion: 2, epoch: page.meta.epoch, revision: page.meta.revision,
       generatedAt: new Date(this.now()).toISOString(),
-      accounts: page.accounts.filter(account => !account.removed).map(publicAccount),
-      logins: page.grants.filter(grant => grant.state !== 'removed').map(publicLogin),
+      accounts: page.accounts.filter(account => options.includeRemoved || !account.removed).map(publicAccount),
+      logins: page.grants.filter(grant => options.includeRemoved || grant.state !== 'removed').map(publicLogin),
       bindings: page.bindings.map(publicBinding),
+      nativeAssignments: page.claudeHomes.map(publicClaudeAssignment),
       nextAccountCursor: page.nextAccountCursor, nextLoginCursor: page.nextGrantCursor,
-      nextBindingCursor: page.nextBindingCursor };
+      nextBindingCursor: page.nextBindingCursor, nextNativeAssignmentCursor: page.nextClaudeHomeCursor };
   }
 
   public async events(epoch: string, afterRevision: number, waitMs: number, signal?: AbortSignal): Promise<{
@@ -554,11 +569,46 @@ export class AuthSwitchAuthorityBroker {
     return publicOperation(pending);
   }
 
-  public async getOperation(operationId: string): Promise<IAuthSwitchOperation> {
+  /**
+   * One device sign-in. With `wait`, the read is a long poll, the way `events` waits: it answers at once when
+   * the operation's revision is past `afterRevision` or the sign-in has finished, and otherwise when the
+   * operation next changes or `waitMs` runs out, whichever is first -- so a caller follows the prompt and
+   * the outcome without polling. A timed-out wait answers with the unchanged operation.
+   */
+  public async getOperation(operationId: string, wait?: { afterRevision: number; waitMs: number },
+    signal?: AbortSignal): Promise<IAuthSwitchOperation> {
     if (!isUuid(operationId)) throw new Error('Invalid operation ID.');
-    const operation = await this.database.readOperation(operationId);
-    if (!operation || operation.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
-    return publicOperation(operation);
+    if (wait !== undefined && (!validRevision(wait.afterRevision) || !Number.isSafeInteger(wait.waitMs)
+      || wait.waitMs < 0 || wait.waitMs > 30_000)) throw new Error('Invalid operation wait.');
+    const read = async (): Promise<IStoredAuthorityDeviceOperation> => {
+      const operation = await this.database.readOperation(operationId);
+      if (!operation || operation.kind === 'preuse_openai') throw new AuthSwitchRefusal('not_found', unknownOperation);
+      return operation;
+    };
+    const answers = (operation: IStoredAuthorityDeviceOperation): boolean => wait === undefined
+      || operation.revision > wait.afterRevision || deviceOperationTerminal(operation);
+    const immediate = await read();
+    if (answers(immediate) || wait!.waitMs === 0 || this.closed || signal?.aborted) return publicOperation(immediate);
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      const settle = (outcome: () => void) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timer);
+        unobserve();
+        this.operationWaiters.delete(wake);
+        signal?.removeEventListener('abort', wake);
+        outcome();
+      };
+      const wake = () => settle(() => { void read().then(operation => resolve(publicOperation(operation)), reject); });
+      const timer = setTimeout(wake, wait!.waitMs);
+      const unobserve = this.database.observeDeviceOperations(changed => { if (changed === operationId) wake(); });
+      this.operationWaiters.add(wake);
+      signal?.addEventListener('abort', wake, { once: true });
+      // Close the read/register race without holding a database session for the wait.
+      void read().then(operation => { if (answers(operation)) wake(); },
+        error => settle(() => reject(error)));
+    });
   }
 
   public async listOperations(after: string | null, limit = 128): Promise<{ operations: IAuthSwitchOperation[]; nextCursor: string | null }> {
@@ -595,7 +645,11 @@ export class AuthSwitchAuthorityBroker {
   }
 
   public async renameAccount(accountId: string, expectedRevision: number, label: string): Promise<IAuthSwitchAccount> {
-    if (!isId(accountId) || !validRevision(expectedRevision) || !safeLabel(label)) throw new Error('Invalid account change.');
+    if (!isId(accountId) || !validRevision(expectedRevision)) throw new Error('Invalid account change.');
+    if (!isAuthSwitchAccountLabel(label)) {
+      throw new AuthSwitchRefusal('invalid_input', 'An account label has between one and one hundred and twenty-eight '
+        + 'characters, with no space at either end and no control character. Choose another label.');
+    }
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeAccount(updateId, accountId, account => {
       if (!account || account.removed || account.revision !== expectedRevision) throw new AuthSwitchRefusal('account_changed', 'Account changed; refresh before editing.');
@@ -625,10 +679,11 @@ export class AuthSwitchAuthorityBroker {
     const capabilityHash = idHash(capability);
     const updateId = plugins.crypto.randomUUID();
     const updated = await this.database.changeBinding(updateId, id, input.accountId, input.loginId, (existing, account, grant) => {
+      // A ChatGPT login backs every runtime, Claude Code included; a Claude account reaches Claude Code
+      // through its native switch instead, so it never binds (its provider is not OpenAI).
       if (account.removed || grant?.state !== 'ready' || grant.id !== account.primaryGrantId
         || grant.owner !== 'daemon'
-        || grant.purpose !== input.purpose || account.providerId !== 'openai'
-        || input.runtime === 'claude') {
+        || grant.purpose !== input.purpose || account.providerId !== 'openai') {
         throw new AuthSwitchRefusal('login_unavailable', loginNotBindable);
       }
       return { id, accountId: input.accountId, grantId: grant.id, runtime: input.runtime, scopeId: input.scopeId,
@@ -639,6 +694,12 @@ export class AuthSwitchAuthorityBroker {
     return { binding: publicBinding(updated.binding), capability };
   }
 
+  public async getBinding(bindingId: string): Promise<IAuthSwitchBinding | null> {
+    if (!isId(bindingId)) throw new Error('Invalid runtime binding.');
+    const binding = await this.database.readBinding(bindingId);
+    return binding ? publicBinding(binding) : null;
+  }
+
   public async revokeBinding(bindingId: string, capability: string): Promise<boolean> {
     if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)) throw new Error('Invalid runtime binding revocation.');
     const revoked = await this.database.revokeBinding(plugins.crypto.randomUUID(), bindingId,
@@ -710,13 +771,12 @@ export class AuthSwitchAuthorityBroker {
   }
 
   /**
-   * The shared managed-access loop, whose refusals are deliberately still unmarked faults.
-   *
-   * Its two callers repair differently: a runtime holding a binding binds again, while the usage reader has
-   * no binding at all and collapses everything into one usage problem. Naming a code here would either say
-   * "binding" to a caller that has none, or invent a second meaning for one that does, so the decision waits
-   * for the slice that gives the usage answer its own vocabulary. What a bound runtime can act on is decided
-   * before this point, in the view `resolveAccess` supplies.
+   * The shared managed-access loop. What it decides about the login itself is a marked refusal both callers
+   * read the same way: `login_needs_reauth` when only a new sign-in brings the login back, `access_not_fresh`
+   * when the login is intact and the provider could not renew it yet. The usage reader still folds either
+   * into its own problem; a bound runtime shows the instruction. What only concerns a binding is decided
+   * before this point, in the view `resolveAccess` supplies, and a changed identity or a view that keeps
+   * moving stays an unmarked fault, because nobody decided it.
    */
   private async resolveManagedAccess(readView: () => Promise<{
     account: IStoredAuthorityAccount; grant: IStoredAuthorityGrant;
@@ -725,20 +785,20 @@ export class AuthSwitchAuthorityBroker {
       const { account, grant } = await readView();
       if (account.removed || grant.accountId !== account.id || grant.id !== account.primaryGrantId
         || account.providerId !== 'openai' || grant.providerId !== 'openai') {
-        throw new Error('Account needs reauthentication.');
+        throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
       }
       if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
         throw new Error('Provider rejected a future account grant generation.');
       }
       if (grant.state === 'exchange_may_have_been_sent') {
         const inFlight = this.refreshes.get(account.id);
-        if (!inFlight) throw new Error('Account refresh is unresolved; reauthentication is required.');
+        if (!inFlight) throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
         await inFlight;
         continue;
       }
       if (grant.owner !== 'daemon' || grant.purpose !== 'openai_managed'
         || !['ready', 'retry_wait'].includes(grant.state)) {
-        throw new Error('Account needs reauthentication.');
+        throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
       }
       const rejectedCurrent = rejectedGrantGeneration === grant.grantGeneration;
       if (this.isDue(grant, minValidityMs) || rejectedCurrent) {
@@ -747,9 +807,9 @@ export class AuthSwitchAuthorityBroker {
             rejectedCurrent ? rejectedGrantGeneration : undefined);
           continue;
         }
-        throw new Error('Account access credential is not fresh enough.');
+        throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       }
-      if (!grant.accessExpiresAt) throw new Error('Account access credential is not fresh enough.');
+      if (!grant.accessExpiresAt) throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       const credential = await this.unsealCredential(account, grant);
       const info = plugins.flexAuth.parseOpenAiChatGptTokenInfo(credential.accessToken);
       if (info.chatgptAccountId !== account.workspaceId || info.chatgptUserId !== account.subject) {
@@ -767,7 +827,7 @@ export class AuthSwitchAuthorityBroker {
         || latest.grant.state === 'exchange_may_have_been_sent') continue;
       if (!['ready', 'retry_wait'].includes(latest.grant.state) || this.isDue(latest.grant, minValidityMs)
         || (rejectedGrantGeneration !== undefined && latest.grant.grantGeneration === rejectedGrantGeneration)) {
-        throw new Error('Account access credential is not fresh enough.');
+        throw new AuthSwitchRefusal('access_not_fresh', accessNotFresh);
       }
       return { accessToken: credential.accessToken, accountId: account.workspaceId,
         isFedrampAccount: info.chatgptAccountIsFedramp, expiresAt: grant.accessExpiresAt,
@@ -852,7 +912,8 @@ export class AuthSwitchAuthorityBroker {
         });
         this.publish();
       } catch { /* A persisted attempt marker forces needs_reauth on daemon restart. */ }
-      throw new Error('Refresh result is uncertain. Reauthenticate this account; its old grant will not be replayed.');
+      // The grant is now `needs_reauth`: an uncertain rotation is never replayed, so only a sign-in repairs it.
+      throw new AuthSwitchRefusal('login_needs_reauth', loginNeedsReauth);
     }
   }
 
@@ -861,6 +922,7 @@ export class AuthSwitchAuthorityBroker {
     this.closed = true;
     if (this.timer) clearTimeout(this.timer);
     for (const wake of this.listeners) wake();
+    for (const wake of this.operationWaiters) wake();
     this.closing = (async () => {
       if (this.maintenance) await this.maintenance;
       await Promise.allSettled([...this.operations.values()].map(item => item.handle.cancel()));