@modelprofile.com/authswitch 9.0.0 → 9.2.0

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.');
@@ -624,21 +678,28 @@ export class AuthSwitchAuthorityBroker {
     const capability = plugins.crypto.randomBytes(32).toString('base64url');
     const capabilityHash = idHash(capability);
     const updateId = plugins.crypto.randomUUID();
-    const updated = await this.database.changeBinding(updateId, id, input.accountId, input.loginId, (existing, account, grant) => {
+    const updated = await this.database.changeBinding(updateId, id, input.accountId, input.loginId, (_existing, account, grant, revision) => {
+      // 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,
-        incarnationId: input.incarnationId, revision: (existing?.revision ?? 0) + 1,
+        incarnationId: input.incarnationId, revision,
         grantAuthorizationGeneration: grant.authorizationGeneration, capabilityHash, updateId };
     });
     this.publish();
     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,
@@ -648,13 +709,37 @@ export class AuthSwitchAuthorityBroker {
   }
 
   public async releaseExternalBinding(bindingId: string, capability: string): Promise<'released' | 'inactive'> {
-    if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)) throw new Error('Invalid runtime binding release.');
+    if (!/^[A-Za-z0-9_-]{43}$/.test(capability)) throw new Error('Invalid runtime binding release.');
+    return this.releaseExternalCapability(bindingId, authSwitchBindingCapabilityHash(capability));
+  }
+
+  /** Releases a caller-held binding while it still carries exactly this capability, named by its hash. */
+  public async releaseExternalCapability(bindingId: string, capabilityHash: string): Promise<'released' | 'inactive'> {
+    if (!isId(bindingId) || !isId(capabilityHash)) throw new Error('Invalid runtime binding release.');
     const released = await this.database.releaseExternalBinding(plugins.crypto.randomUUID(), bindingId,
-      authSwitchBindingCapabilityHash(capability));
+      capabilityHash);
     if (released) this.publish();
     return released ? 'released' : 'inactive';
   }
 
+  /**
+   * The caller-held binding a holder names by the identity it bound under, while it is still exactly the
+   * incarnation and revision the holder read, or `null`. Its capability hash is what a release then fences
+   * and compares, so a successor bound after this read is never released in its place.
+   */
+  public async findHeldBinding(input: { runtime: Exclude<IAuthSwitchBinding['runtime'], 'codex'>; scopeId: string;
+    incarnationId: string; expectedRevision: number }): Promise<{ bindingId: string; capabilityHash: string } | null> {
+    if (!['flex', 'opencode', 'claude'].includes(input.runtime) || !safeScope(input.scopeId, 512)
+      || !safeScope(input.incarnationId, 256) || !validRevision(input.expectedRevision)) {
+      throw new Error('Invalid runtime binding release.');
+    }
+    const bindingId = idHash('authswitch-binding-v1', input.runtime, input.scopeId);
+    const binding = await this.database.readBinding(bindingId);
+    if (!binding || binding.runtime !== input.runtime || binding.scopeId !== input.scopeId
+      || binding.incarnationId !== input.incarnationId || binding.revision !== input.expectedRevision) return null;
+    return { bindingId, capabilityHash: binding.capabilityHash };
+  }
+
   public async resolveAccess(bindingId: string, capability: string, minValidityMs: number,
     rejectedGrantGeneration?: number): Promise<IAuthSwitchResolvedAccess> {
     if (!isId(bindingId) || !/^[A-Za-z0-9_-]{43}$/.test(capability)
@@ -710,13 +795,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 +809,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 +831,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 +851,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 +936,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 +946,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()));

package/ts/classes.authorityclient.ts

@@ -5,35 +5,43 @@ import type {
   IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation,
   IReq_AuthSwitchClaudeNativeHandoff, IReq_AuthSwitchClaudeNativeHandoffs,
   IReq_AuthSwitchSwitchClaudeNative, IReq_AuthSwitchEvents,
-  IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations, IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
+  IReq_AuthSwitchGetBinding, IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations,
+  IReq_AuthSwitchRemoveAccount, IReq_AuthSwitchRenameAccount,
   IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchSnapshot,
   IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage,
 } from './authority-contract.js';
 import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
-  IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+  IReq_AuthSwitchResolveAccess, IReq_AuthSwitchUnbind } from './authority-runtime-contract.js';
 import type { IReq_AuthSwitchImportInventory, IReq_AuthSwitchImportStatus,
   IReq_AuthSwitchImportSubmit } from './authority-import-contract.js';
 import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
   maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
 
+/**
+ * One request on one connection, bounded by its own deadline alone.
+ *
+ * `TypedRequest.fire` turns each request's `timeoutMs` into the abort of `signal`, so the transport arms no
+ * timer of its own: an idle limit here would end a request that was allowed longer -- an import submit is
+ * allowed 120 s -- before its deadline. Every authority request carries one; a request without it is refused.
+ */
 const post = (path: string, payload: ITypedRequest, signal?: AbortSignal): Promise<ITypedRequest> => {
     return new Promise((resolve, reject) => {
-      if (signal?.aborted) { reject(signal.reason); return; }
+      if (!signal) { reject(new Error('Authswitch daemon requests need a deadline.')); return; }
+      if (signal.aborted) { reject(signal.reason); return; }
       const socket = plugins.net.createConnection(path);
       let settled = false;
       const frame = new AuthSwitchAuthorityFrameReader();
       const finish = (error?: unknown, response?: ITypedRequest): void => {
         if (settled) return;
         settled = true;
-        signal?.removeEventListener('abort', abort);
+        signal.removeEventListener('abort', abort);
         socket.destroy();
         if (error) reject(error);
         else if (response) resolve(response);
         else reject(new Error('Authswitch daemon returned no response.'));
       };
-      const abort = () => finish(signal?.reason ?? new Error('Account request was cancelled.'));
-      signal?.addEventListener('abort', abort, { once: true });
-      socket.setTimeout(35_000, () => finish(new Error('Authswitch daemon request timed out.')));
+      const abort = () => finish(signal.reason ?? new Error('Account request was cancelled.'));
+      signal.addEventListener('abort', abort, { once: true });
       socket.on('connect', () => {
         const raw = JSON.stringify(payload);
         if (authSwitchAuthorityFrameBytes(raw) > maxAuthSwitchAuthorityFrameBytes) { finish(new Error('Account request is too large.')); return; }
@@ -53,10 +61,36 @@ const post = (path: string, payload: ITypedRequest, signal?: AbortSignal): Promi
     });
 };
 
+/**
+ * The daemon answered with an older contract than this client reads: it runs an authswitch release from before
+ * this one and was not restarted after the upgrade. Restarting it onto the installed release is the repair.
+ */
+export class AuthSwitchDaemonOutdatedError extends Error {
+  constructor() {
+    super('The authswitch authority daemon runs an older release than this client. Restart it onto the '
+      + 'installed authswitch: authswitch authority service stop, then authswitch authority service start.');
+    this.name = 'AuthSwitchDaemonOutdatedError';
+  }
+}
+
+/**
+ * A snapshot page carries every member of this release's contract. `schemaVersion` is not bumped for an
+ * additive member, so an older daemon is told apart by the members its answer lacks.
+ */
+const assertCurrentSnapshot = (snapshot: IAuthSwitchSnapshot): IAuthSwitchSnapshot => {
+  const page: Partial<IAuthSwitchSnapshot> = snapshot;
+  if (!Array.isArray(page.nativeAssignments) || page.nextNativeAssignmentCursor === undefined) {
+    throw new AuthSwitchDaemonOutdatedError();
+  }
+  return snapshot;
+};
+
 /** A snapshot is usable only while state is current; lastVerifiedAt is the last successful daemon proof. */
 export interface IAuthSwitchSubscriptionStatus {
   state: 'current' | 'unavailable' | 'closed';
-  reason: 'initial' | 'snapshot' | 'event' | 'heartbeat' | 'disconnect' | 'resync' | 'abort' | 'consumer_error';
+  /** `daemon_outdated`: the daemon runs an older release; see `AuthSwitchDaemonOutdatedError`. */
+  reason: 'initial' | 'snapshot' | 'event' | 'heartbeat' | 'disconnect' | 'resync' | 'abort' | 'consumer_error'
+    | 'daemon_outdated';
   epoch: string | null;
   revision: number | null;
   lastVerifiedAt: string | null;
@@ -66,6 +100,8 @@ export interface IAuthSwitchSubscriptionOptions {
   onStatus?: (status: IAuthSwitchSubscriptionStatus) => void | Promise<void>;
   /** Bounded long-poll interval; defaults to 30 seconds. */
   heartbeatMs?: number;
+  /** Deliver snapshots that also carry removed accounts and logins; see `IReq_AuthSwitchSnapshot`. */
+  includeRemoved?: boolean;
 }
 
 /**
@@ -96,8 +132,10 @@ export class AuthSwitchClient {
       .fire(request, { timeoutMs, maxRetries: 0, abortSignal: signal });
   }
 
+  /** One snapshot page; an older daemon's answer fails with `AuthSwitchDaemonOutdatedError`. */
   public async snapshot(options: IReq_AuthSwitchSnapshot['request'] = {}, signal?: AbortSignal): Promise<IAuthSwitchSnapshot> {
-    return (await this.request<IReq_AuthSwitchSnapshot>('authswitch.authority.snapshot', options, 35_000, false, signal)).snapshot;
+    return assertCurrentSnapshot((await this.request<IReq_AuthSwitchSnapshot>('authswitch.authority.snapshot',
+      options, 35_000, false, signal)).snapshot);
   }
 
   /** One independently stamped diagnostic page; callers may continue with its independent cursors. */
@@ -132,30 +170,39 @@ export class AuthSwitchClient {
   }
 
   /** Assemble a consistent view from bounded database pages; restart if a writer changes the revision. */
-  public async snapshotAll(options: { limit?: number; signal?: AbortSignal } = {}): Promise<IAuthSwitchSnapshot> {
+  public async snapshotAll(options: { limit?: number; includeRemoved?: boolean; signal?: AbortSignal } = {}): Promise<IAuthSwitchSnapshot> {
     while (true) {
       if (options.signal?.aborted) throw options.signal.reason ?? new Error('Account snapshot cancelled.');
       let accountAfter: string | undefined;
       let loginAfter: string | undefined;
       let bindingAfter: string | undefined;
+      let nativeAssignmentAfter: string | undefined;
       let aggregate: IAuthSwitchSnapshot | undefined;
       let changed = false;
       while (true) {
-        const page = await this.snapshot({ accountAfter, loginAfter, bindingAfter, limit: options.limit }, options.signal);
-        if (!aggregate) aggregate = { ...page, accounts: [...page.accounts], logins: [...page.logins], bindings: [...page.bindings] };
-        else if (aggregate.epoch !== page.epoch || aggregate.revision !== page.revision) {
+        const page = await this.snapshot({ accountAfter, loginAfter, bindingAfter, nativeAssignmentAfter,
+          limit: options.limit, ...(options.includeRemoved ? { includeRemoved: true } : {}) }, options.signal);
+        if (!aggregate) {
+          aggregate = { ...page, accounts: [...page.accounts], logins: [...page.logins], bindings: [...page.bindings],
+            nativeAssignments: [...page.nativeAssignments] };
+        } else if (aggregate.epoch !== page.epoch || aggregate.revision !== page.revision) {
           changed = true;
           break;
         } else {
           aggregate.accounts.push(...page.accounts);
           aggregate.logins.push(...page.logins);
           aggregate.bindings.push(...page.bindings);
+          aggregate.nativeAssignments.push(...page.nativeAssignments);
         }
         accountAfter = page.nextAccountCursor ?? accountAfter ?? page.accounts.at(-1)?.id;
         loginAfter = page.nextLoginCursor ?? loginAfter ?? page.logins.at(-1)?.id;
         bindingAfter = page.nextBindingCursor ?? bindingAfter ?? page.bindings.at(-1)?.id;
-        if (!page.nextAccountCursor && !page.nextLoginCursor && !page.nextBindingCursor) {
-          return { ...aggregate, nextAccountCursor: null, nextLoginCursor: null, nextBindingCursor: null };
+        nativeAssignmentAfter = page.nextNativeAssignmentCursor ?? nativeAssignmentAfter
+          ?? page.nativeAssignments.at(-1)?.id;
+        if (!page.nextAccountCursor && !page.nextLoginCursor && !page.nextBindingCursor
+          && !page.nextNativeAssignmentCursor) {
+          return { ...aggregate, nextAccountCursor: null, nextLoginCursor: null, nextBindingCursor: null,
+            nextNativeAssignmentCursor: null };
         }
       }
       if (!changed) throw new Error('Authority snapshot could not complete.');
@@ -188,9 +235,9 @@ export class AuthSwitchClient {
      * full, and since it holds nothing, a process whose only remaining handle it is can exit inside it --
      * dropping the closing status this loop owes its consumer.
      */
-    const retry = () => new Promise<void>(resolve => {
+    const retry = (delayMs = 250) => new Promise<void>(resolve => {
       if (signal.aborted) { resolve(); return; }
-      const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, 250);
+      const timer = setTimeout(() => { signal.removeEventListener('abort', aborted); resolve(); }, delayMs);
       timer.unref();
       const aborted = () => { clearTimeout(timer); resolve(); };
       signal.addEventListener('abort', aborted, { once: true });
@@ -208,19 +255,34 @@ export class AuthSwitchClient {
       snapshot = undefined;
       if (available) { available = false; await status('unavailable', reason); }
     };
+    /**
+     * An older daemon answers every attempt the same way until it is restarted, so the consumer is told why once
+     * per outage, and the loop keeps trying at a slower pace: the restart that repairs it needs nothing else.
+     */
+    let outdatedReported = false;
+    const unreadable = async (error: unknown): Promise<boolean> => {
+      if (!(error instanceof AuthSwitchDaemonOutdatedError)) return false;
+      snapshot = undefined;
+      available = false;
+      if (!outdatedReported) { outdatedReported = true; await status('unavailable', 'daemon_outdated'); }
+      await retry(5_000);
+      return true;
+    };
     try {
       if (!signal.aborted) await status('unavailable', 'initial');
       while (!signal.aborted) {
         if (!snapshot) {
           let fresh: IAuthSwitchSnapshot;
-          try { fresh = await this.snapshotAll({ signal }); }
-          catch {
+          try { fresh = await this.snapshotAll({ signal, includeRemoved: options.includeRemoved }); }
+          catch (error) {
             if (signal.aborted) break;
+            if (await unreadable(error)) continue;
             await invalidate('disconnect');
             await retry();
             continue;
           }
           snapshot = fresh;
+          outdatedReported = false;
           await onSnapshot(fresh);
           available = true;
           lastEpoch = fresh.epoch;
@@ -243,9 +305,10 @@ export class AuthSwitchClient {
         }
         if (result.events.length) {
           let fresh: IAuthSwitchSnapshot;
-          try { fresh = await this.snapshotAll({ signal }); }
-          catch {
+          try { fresh = await this.snapshotAll({ signal, includeRemoved: options.includeRemoved }); }
+          catch (error) {
             if (signal.aborted) break;
+            if (await unreadable(error)) continue;
             await invalidate('disconnect');
             await retry();
             continue;
@@ -290,6 +353,16 @@ export class AuthSwitchClient {
     return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
       { operationId }, 35_000, false, signal)).operation;
   }
+  /**
+   * Waits up to `waitMs` for the sign-in to change past `afterRevision` and answers with it; a finished
+   * sign-in answers at once, and a timed-out wait with the unchanged operation. Follow a sign-in by passing
+   * each answer's `revision` back until its state is final.
+   */
+  public async watchOperation(operationId: string, afterRevision: number, waitMs = 30_000,
+    signal?: AbortSignal): Promise<IReq_AuthSwitchGetOperation['response']['operation']> {
+    return (await this.request<IReq_AuthSwitchGetOperation>('authswitch.authority.operation',
+      { operationId, afterRevision, waitMs }, waitMs + 5_000, false, signal)).operation;
+  }
   public async cancelOperation(operationId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchCancelOperation['response']['operation']> {
     return (await this.request<IReq_AuthSwitchCancelOperation>('authswitch.authority.cancel',
       { operationId }, 35_000, false, signal)).operation;
@@ -334,10 +407,23 @@ export class AuthSwitchClient {
     return this.request<IReq_AuthSwitchClaudeNativeHandoffs>('authswitch.authority.claude.handoffs',
       { after, limit }, 35_000, false, signal);
   }
+  /** The binding `bind` returned, credential-free, or null once this authority holds none by that id. */
+  public async getBinding(bindingId: string, signal?: AbortSignal): Promise<IReq_AuthSwitchGetBinding['response']['binding']> {
+    return (await this.request<IReq_AuthSwitchGetBinding>('authswitch.authority.binding',
+      { bindingId }, 35_000, false, signal)).binding;
+  }
   public bindAccount(input: IReq_AuthSwitchBindAccount['request'],
     signal?: AbortSignal): Promise<IReq_AuthSwitchBindAccount['response']> {
     return this.request<IReq_AuthSwitchBindAccount>('authswitch.authority.bind', input, 35_000, false, signal);
   }
+  /**
+   * Releases the holder's own binding by the runtime, scope, incarnation and revision it was bound under,
+   * without its capability and without a ready login; `inactive` when no binding matches all four.
+   */
+  public unbind(input: IReq_AuthSwitchUnbind['request'],
+    signal?: AbortSignal): Promise<IReq_AuthSwitchUnbind['response']> {
+    return this.request<IReq_AuthSwitchUnbind>('authswitch.authority.unbind', input, 35_000, false, signal);
+  }
   public resolveAccess(input: IReq_AuthSwitchResolveAccess['request'],
     signal?: AbortSignal): Promise<IReq_AuthSwitchResolveAccess['response']> {
     return this.request<IReq_AuthSwitchResolveAccess>('authswitch.authority.resolveAccess',