@modelprofile.com/authswitch 6.4.0 → 7.0.0

package/ts/classes.authoritydaemon.ts

@@ -1,51 +1,256 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import * as plugins from './plugins.js';
 import type {
+  IAuthSwitchDoctorPage, IReq_AuthSwitchDoctor,
   IReq_AuthSwitchBeginAdd, IReq_AuthSwitchBeginReauth, IReq_AuthSwitchCancelOperation,
-  IReq_AuthSwitchEvents, IReq_AuthSwitchGetOperation, IReq_AuthSwitchRemoveAccount,
+  IReq_AuthSwitchClaudeNativeHandoff, IReq_AuthSwitchClaudeNativeHandoffs, IReq_AuthSwitchSwitchClaudeNative,
+  IReq_AuthSwitchEvents, IReq_AuthSwitchGetOperation, IReq_AuthSwitchListOperations, IReq_AuthSwitchRemoveAccount,
   IReq_AuthSwitchRenameAccount, IReq_AuthSwitchSnapshot,
+  IReq_AuthSwitchCancelPreuse, IReq_AuthSwitchGetPreuse, IReq_AuthSwitchStartPreuse, IReq_AuthSwitchUsage,
 } from './authority-contract.js';
-import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
-import { AuthSwitchAuthorityBroker, type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
+import type { IReq_AuthSwitchBindAccount, IReq_AuthSwitchReleaseBinding,
+  IReq_AuthSwitchResolveAccess } from './authority-runtime-contract.js';
+import { authSwitchBindingCapabilityHash, AuthSwitchAuthorityBroker,
+  type IAuthSwitchAuthorityBrokerOptions } from './classes.authoritybroker.js';
 import { AuthSwitchAuthorityDatabase, type IAuthSwitchAuthorityDatabaseOptions } from './classes.authoritydatabase.js';
+import { ClaudeNativeAuthority, type IClaudeNativeAuthorityOptions } from './classes.claudeauthority.js';
+import { ClaudeAccountStatus } from './classes.claudestatus.js';
+import { AuthSwitchAuthorityUsage, type IAuthSwitchAuthorityUsageOptions } from './classes.authorityusage.js';
+import { AuthSwitchAuthorityPreuse, type IAuthSwitchAuthorityPreuseOptions } from './classes.authoritypreuse.js';
 import { AuthSwitchAuthorityFrameReader, authSwitchAuthorityFrameBytes,
   maxAuthSwitchAuthorityFrameBytes } from './classes.authorityframing.js';
+import { AuthSwitchManagedCodex, findManagedCodexProcess, observeManagedCodexProcesses,
+  type IAuthSwitchManagedCodexOptions } from './classes.codexmanaged.js';
 
 export interface IAuthSwitchAuthorityDaemonOptions extends IAuthSwitchAuthorityDatabaseOptions {
   authoritySocketPath: string;
   runtimeSocketPath: string;
   broker?: IAuthSwitchAuthorityBrokerOptions;
+  usage?: Partial<Pick<IAuthSwitchAuthorityUsageOptions, 'now' | 'currentMaxAgeMs' | 'maxStaleAgeMs'
+    | 'minAttemptIntervalMs' | 'retryBaseMs' | 'retryMaxMs' | 'providerTimeoutMs' | 'minAccessValidityMs'>>;
+  preuse?: IAuthSwitchAuthorityPreuseOptions;
+  claudeStatus?: ClaudeAccountStatus;
+  /** Activated only after a verified backend source receipt has registered the native home. */
+  claudeNative?: IClaudeNativeAuthorityOptions;
 }
 
 const hasKeys = (value: unknown, keys: readonly string[]): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value)
   && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
 const invalid = (): never => { throw new plugins.typedrequest.TypedResponseError('Invalid authswitch authority request.'); };
+const validBindingId = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const validBindingCapability = (value: unknown): value is string => typeof value === 'string'
+  && /^[A-Za-z0-9_-]{43}$/.test(value);
+
+interface IPreuseAccountReservation {
+  operationId: string;
+}
 
 /** TypedRequest handlers over a private one-request-per-connection Unix socket. */
 export class AuthSwitchAuthorityDaemon {
   public readonly database: AuthSwitchAuthorityDatabase;
   public readonly broker: AuthSwitchAuthorityBroker;
+  public readonly usage: AuthSwitchAuthorityUsage;
+  public readonly preuse: AuthSwitchAuthorityPreuse;
+  public readonly claudeNative?: ClaudeNativeAuthority;
   private readonly managementRouter = new plugins.typedrequest.TypedRouter();
   private readonly runtimeRouter = new plugins.typedrequest.TypedRouter();
   private managementServer?: plugins.net.Server;
   private runtimeServer?: plugins.net.Server;
   private readonly sockets = new Set<plugins.net.Socket>();
+  private readonly managedCodex = new Map<string, Promise<{ runtime: AuthSwitchManagedCodex; bindingId: string;
+    capability: string; homeId: string; runId: string }>>();
+  private readonly managedCodexHomes = new Set<string>();
+  private readonly managedCodexAccountIds = new Map<string, string>();
+  private readonly managedCodexStates = new Map<string, IAuthSwitchDoctorPage['managedCodex'][number]['daemon']['state']>();
+  private readonly drainingAccounts = new Set<string>();
+  private readonly deviceDrainOwners = new Map<string, string>();
+  private readonly preuseAccounts = new Map<string, IPreuseAccountReservation>();
+  private readonly managedCodexStops = new Map<string, Promise<void>>();
+  private readonly managedCodexFailures: unknown[] = [];
+  private readonly runtimeBindingActivity = new Map<string, { active: number; waiters: Set<() => void> }>();
+  private readonly runtimeBindingReleaseFences = new Set<string>();
+  private readonly runtimeBindingReleases = new Map<string, Promise<IReq_AuthSwitchReleaseBinding['response']>>();
+  private closing = false;
 
   constructor(private readonly options: IAuthSwitchAuthorityDaemonOptions) {
     this.database = new AuthSwitchAuthorityDatabase(options);
-    this.broker = new AuthSwitchAuthorityBroker(this.database, options.broker);
+    const provider = options.broker?.provider ?? new plugins.flexAccounts.OpenAiProviderAdapter();
+    this.broker = new AuthSwitchAuthorityBroker(this.database, { ...options.broker, provider });
+    this.usage = new AuthSwitchAuthorityUsage({
+      ...options.usage,
+      readContext: async (accountId, loginId) => {
+        await this.database.assertOpenAdmission();
+        return this.database.readUsageContext(accountId, loginId);
+      },
+      resolveAccess: (context, rejectedGrantGeneration, minValidityMs) =>
+        this.broker.resolveUsageAccess(context, rejectedGrantGeneration, minValidityMs),
+      resolveClaudeLogin: (context, rejectedGrantGeneration, minValidityMs) => {
+        if (!this.claudeNative) throw new Error('Claude status authority is unavailable.');
+        return this.claudeNative.resolveInactiveStatusLogin(context, rejectedGrantGeneration, minValidityMs);
+      },
+      withNativeSource: (context, action) => {
+        if (!this.claudeNative) throw new Error('Claude native status authority is unavailable.');
+        return this.claudeNative.withNativeUsageSource(context, action);
+      },
+      claudeStatus: options.claudeStatus ?? new ClaudeAccountStatus(),
+      store: {
+        read: (accountId, loginId) => this.database.readUsage(accountId, loginId),
+        publishIfCurrent: async (context, previousUpdateId, next) => {
+          const published = await this.database.publishUsageIfCurrent(context, previousUpdateId, next);
+          if (published) this.broker.notifyChanged();
+          return published;
+        },
+      },
+      provider,
+    });
+    this.preuse = new AuthSwitchAuthorityPreuse(this.database, this.broker, options.preuse);
+    if (options.claudeNative) {
+      this.claudeNative = new ClaudeNativeAuthority(this.database, {
+        ...options.claudeNative, onChanged: () => this.broker.notifyChanged(),
+      });
+      this.broker.setClaudeRefresher(grantId => this.claudeNative!.refreshInactiveGrant(grantId));
+    }
     this.register();
   }
 
+  private runtimeBindingKey(bindingId: string, capability: string): string {
+    return `${bindingId}:${authSwitchBindingCapabilityHash(capability)}`;
+  }
+
+  private beginRuntimeBindingAccess(key: string): () => void {
+    if (this.runtimeBindingReleaseFences.has(key)) throw new Error('Runtime binding release is in progress.');
+    const activity = this.runtimeBindingActivity.get(key) ?? { active: 0, waiters: new Set<() => void>() };
+    activity.active++;
+    this.runtimeBindingActivity.set(key, activity);
+    let finished = false;
+    return () => {
+      if (finished) return;
+      finished = true;
+      activity.active--;
+      if (activity.active !== 0) return;
+      this.runtimeBindingActivity.delete(key);
+      for (const resolve of activity.waiters) resolve();
+      activity.waiters.clear();
+    };
+  }
+
+  private waitForRuntimeBindingAccess(key: string): Promise<void> {
+    const activity = this.runtimeBindingActivity.get(key);
+    if (!activity || activity.active === 0) return Promise.resolve();
+    return new Promise(resolve => activity.waiters.add(resolve));
+  }
+
+  private releaseRuntimeBinding(bindingId: string,
+    capability: string): Promise<IReq_AuthSwitchReleaseBinding['response']> {
+    const key = this.runtimeBindingKey(bindingId, capability);
+    const existing = this.runtimeBindingReleases.get(key);
+    if (existing) return existing;
+    // Capabilities are freshly random for every bind, including a successor that reuses the
+    // same caller label. A stale release therefore fences only its own unusable capability.
+    this.runtimeBindingReleaseFences.add(key);
+    const task = (async (): Promise<IReq_AuthSwitchReleaseBinding['response']> => {
+      await this.waitForRuntimeBindingAccess(key);
+      const state = await this.broker.releaseExternalBinding(bindingId, capability);
+      this.runtimeBindingReleaseFences.delete(key);
+      return { state };
+    })();
+    this.runtimeBindingReleases.set(key, task);
+    void task.finally(() => {
+      if (this.runtimeBindingReleases.get(key) === task) this.runtimeBindingReleases.delete(key);
+      // A rejected release keeps only this exact key fenced until a retry reconciles database truth.
+    }).catch(() => {});
+    return task;
+  }
+
+  private releaseDeviceDrain(accountId: string, operationId: string): void {
+    if (this.deviceDrainOwners.get(accountId) !== operationId) return;
+    this.deviceDrainOwners.delete(accountId);
+    this.drainingAccounts.delete(accountId);
+  }
+
+  private beginReauthOpenAi(request: IReq_AuthSwitchBeginReauth['request']): Promise<IReq_AuthSwitchBeginReauth['response']['operation']> {
+    let ownsReservation = false;
+    const prepare = async (): Promise<void> => {
+      if (this.closing || this.drainingAccounts.has(request.accountId)
+        || this.preuseAccounts.has(request.accountId)) {
+        throw new Error('Account runtime drain is already in progress.');
+      }
+      this.drainingAccounts.add(request.accountId);
+      this.deviceDrainOwners.set(request.accountId, request.operationId);
+      ownsReservation = true;
+      try { await this.drainManagedCodexAccount(request.accountId); }
+      catch (error) {
+        this.releaseDeviceDrain(request.accountId, request.operationId);
+        throw error;
+      }
+    };
+    const started = this.broker.beginReauthOpenAi(request.operationId, request.accountId,
+      request.loginId, request.purpose, prepare);
+    return started.then(operation => {
+      if (!ownsReservation) return operation;
+      if (['starting', 'pending', 'committing'].includes(operation.state)) {
+        void this.broker.waitOperation(operation.id).finally(() => {
+          this.releaseDeviceDrain(request.accountId, request.operationId);
+        }).catch(() => {});
+      } else this.releaseDeviceDrain(request.accountId, request.operationId);
+      return operation;
+    }, error => {
+      if (ownsReservation) this.releaseDeviceDrain(request.accountId, request.operationId);
+      throw error;
+    });
+  }
+
   private register(): void {
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchUsage>(
+      'authswitch.authority.usage', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || !Object.hasOwn(request, 'accountId') || !Object.hasOwn(request, 'loginId')
+          || Object.keys(request).some(key => !['accountId', 'loginId', 'force'].includes(key))
+          || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
+          || (request.force !== undefined && typeof request.force !== 'boolean')) invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        return { usage: await this.usage.get(request.accountId, request.loginId, request.force ?? false) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchSwitchClaudeNative>(
+      'authswitch.authority.claude.switch', async request => {
+        if (!hasKeys(request, ['accountId', 'loginId', 'purpose'])
+          || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
+          || request.purpose !== 'claude_host_native') invalid();
+        if (this.closing || !this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        return { handoff: await this.claudeNative.switchTo(request.accountId, request.loginId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchClaudeNativeHandoff>(
+      'authswitch.authority.claude.handoff', async request => {
+        if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
+        if (!this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        return { handoff: await this.claudeNative.getHandoff(request.operationId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchClaudeNativeHandoffs>(
+      'authswitch.authority.claude.handoffs', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || Object.keys(request).some(key => !['after', 'limit'].includes(key))) invalid();
+        if (!this.claudeNative) throw new Error('Claude native handoff is unavailable.');
+        return this.claudeNative.listHandoffs(request.after ?? null, request.limit ?? 128);
+      }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchSnapshot>(
       'authswitch.authority.snapshot', async request => {
         if (request === null || typeof request !== 'object' || Array.isArray(request)) invalid();
         const keys = Object.keys(request);
-        if (keys.some(key => !['accountAfter', 'bindingAfter', 'limit'].includes(key))) invalid();
+        if (keys.some(key => !['accountAfter', 'loginAfter', 'bindingAfter', 'limit'].includes(key))) invalid();
         return { snapshot: await this.broker.snapshot(request) };
       }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchDoctor>(
+      'authswitch.authority.doctor', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)) invalid();
+        const cursorKeys = ['accountAfter', 'loginAfter', 'codexHomeAfter', 'claudeHomeAfter',
+          'claudeHandoffAfter', 'nativeHandoffAfter', 'migrationAfter'] as const;
+        if (Object.keys(request).some(key => ![...cursorKeys, 'limit'].includes(key as typeof cursorKeys[number] | 'limit'))
+          || cursorKeys.some(key => request[key] !== undefined && typeof request[key] !== 'string')
+          || (request.limit !== undefined && (!Number.isSafeInteger(request.limit)
+            || request.limit < 1 || request.limit > 128))) invalid();
+        return { page: await this.doctorPage(request) };
+      }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchEvents>(
       'authswitch.authority.events', async (request, tools) => {
         if (!hasKeys(request, ['epoch', 'afterRevision', 'waitMs'])) invalid();
@@ -53,24 +258,82 @@ export class AuthSwitchAuthorityDaemon {
       }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginAdd>(
       'authswitch.authority.add', async request => {
-        if (!hasKeys(request, ['providerId', 'flow']) || request.providerId !== 'openai' || request.flow !== 'device') invalid();
-        return { operation: await this.broker.beginAddOpenAi() };
+        if (!hasKeys(request, ['operationId', 'providerId', 'flow']) || typeof request.operationId !== 'string'
+          || request.providerId !== 'openai' || request.flow !== 'device') invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        return { operation: await this.broker.beginAddOpenAi(request.operationId) };
       }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBeginReauth>(
       'authswitch.authority.reauth', async request => {
-        if (!hasKeys(request, ['accountId', 'flow']) || request.flow !== 'device' || typeof request.accountId !== 'string') invalid();
-        return { operation: await this.broker.beginReauthOpenAi(request.accountId) };
+        if (!hasKeys(request, ['operationId', 'accountId', 'loginId', 'purpose', 'flow']) || request.flow !== 'device'
+          || typeof request.operationId !== 'string'
+          || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
+          || request.purpose !== 'openai_managed') invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        return { operation: await this.beginReauthOpenAi(request) };
       }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchGetOperation>(
       'authswitch.authority.operation', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
-        return { operation: this.broker.getOperation(request.operationId) };
+        return { operation: await this.broker.getOperation(request.operationId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchListOperations>(
+      'authswitch.authority.operations', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || Object.keys(request).some(key => !['after', 'limit'].includes(key))) invalid();
+        return this.broker.listOperations(request.after ?? null, request.limit ?? 128);
       }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchCancelOperation>(
       'authswitch.authority.cancel', async request => {
         if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
         return { operation: await this.broker.cancelOperation(request.operationId) };
       }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchStartPreuse>(
+      'authswitch.authority.preuse.start', async request => {
+        if (request === null || typeof request !== 'object' || Array.isArray(request)
+          || !['operationId', 'accountId', 'loginId', 'purpose', 'prompt'].every(key => Object.hasOwn(request, key))
+          || Object.keys(request).some(key => !['operationId', 'accountId', 'loginId', 'purpose', 'prompt', 'model'].includes(key))
+          || typeof request.operationId !== 'string' || typeof request.accountId !== 'string'
+          || typeof request.loginId !== 'string' || request.purpose !== 'openai_managed'
+          || typeof request.prompt !== 'string'
+          || (request.model !== undefined && typeof request.model !== 'string')) invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        const reservation: IPreuseAccountReservation = { operationId: request.operationId };
+        let ownsReservation = false;
+        const release = (): void => {
+          if (this.preuseAccounts.get(request.accountId) !== reservation) return;
+          this.preuseAccounts.delete(request.accountId);
+        };
+        try {
+          const operation = await this.preuse.begin(request, () => {
+            const owner = this.preuseAccounts.get(request.accountId);
+            if (this.drainingAccounts.has(request.accountId)
+              || (owner && owner.operationId !== request.operationId)) return 'account_busy';
+            if (!owner) {
+              this.preuseAccounts.set(request.accountId, reservation);
+              ownsReservation = true;
+            }
+            return 'admitted';
+          });
+          if (ownsReservation && this.preuse.hasActive(request.operationId)) {
+            void this.preuse.wait(request.operationId).finally(release).catch(() => {});
+          } else if (ownsReservation) release();
+          return { operation };
+        } catch (error) {
+          if (ownsReservation) release();
+          throw error;
+        }
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchGetPreuse>(
+      'authswitch.authority.preuse.operation', async request => {
+        if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
+        return { operation: await this.preuse.get(request.operationId) };
+      }));
+    this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchCancelPreuse>(
+      'authswitch.authority.preuse.cancel', async request => {
+        if (!hasKeys(request, ['operationId']) || typeof request.operationId !== 'string') invalid();
+        return { operation: await this.preuse.cancel(request.operationId) };
+      }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchRenameAccount>(
       'authswitch.authority.rename', async request => {
         if (!hasKeys(request, ['accountId', 'expectedRevision', 'label']) || typeof request.accountId !== 'string'
@@ -81,29 +344,157 @@ export class AuthSwitchAuthorityDaemon {
       'authswitch.authority.remove', async request => {
         if (!hasKeys(request, ['accountId', 'expectedRevision']) || typeof request.accountId !== 'string'
           || typeof request.expectedRevision !== 'number') invalid();
-        return { account: await this.broker.removeAccount(request.accountId, request.expectedRevision) };
+        if (this.drainingAccounts.has(request.accountId) || this.preuseAccounts.has(request.accountId)) {
+          throw new Error('Account runtime drain is already in progress.');
+        }
+        this.drainingAccounts.add(request.accountId);
+        try {
+          await this.drainManagedCodexAccount(request.accountId);
+          return { account: await this.broker.removeAccount(request.accountId, request.expectedRevision) };
+        } finally { this.drainingAccounts.delete(request.accountId); }
       }));
     this.managementRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchBindAccount>(
       'authswitch.authority.bind', async request => {
-        if (!hasKeys(request, ['accountId', 'runtime', 'scopeId', 'incarnationId'])
-          || typeof request.accountId !== 'string' || typeof request.scopeId !== 'string'
+        if (!hasKeys(request, ['accountId', 'loginId', 'purpose', 'runtime', 'scopeId', 'incarnationId'])
+          || typeof request.accountId !== 'string' || typeof request.loginId !== 'string'
+          || request.purpose !== 'openai_managed' || typeof request.scopeId !== 'string'
           || typeof request.incarnationId !== 'string') invalid();
         return this.broker.bindAccount(request);
       }));
     this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchResolveAccess>(
       'authswitch.authority.resolveAccess', async request => {
-        if (!hasKeys(request, ['bindingId', 'capability', 'minValidityMs'])
-          || typeof request.bindingId !== 'string' || typeof request.capability !== 'string'
-          || typeof request.minValidityMs !== 'number') invalid();
-        return this.broker.resolveAccess(request.bindingId, request.capability, request.minValidityMs);
+        if ((typeof request !== 'object' || request === null || Array.isArray(request))
+          || !['bindingId', 'capability', 'minValidityMs'].every(key => Object.hasOwn(request, key))
+          || Object.keys(request).some(key => !['bindingId', 'capability', 'minValidityMs',
+            'rejectedGrantGeneration'].includes(key))
+          || !validBindingId(request.bindingId) || !validBindingCapability(request.capability)
+          || typeof request.minValidityMs !== 'number'
+          || (request.rejectedGrantGeneration !== undefined && typeof request.rejectedGrantGeneration !== 'number')) invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        const finish = this.beginRuntimeBindingAccess(this.runtimeBindingKey(request.bindingId, request.capability));
+        try {
+          return await this.broker.resolveAccess(request.bindingId, request.capability, request.minValidityMs,
+            request.rejectedGrantGeneration);
+        } finally { finish(); }
+      }));
+    this.runtimeRouter.addTypedHandler(new plugins.typedrequest.TypedHandler<IReq_AuthSwitchReleaseBinding>(
+      'authswitch.authority.release', async request => {
+        if (!hasKeys(request, ['bindingId', 'capability'])
+          || !validBindingId(request.bindingId) || !validBindingCapability(request.capability)) invalid();
+        if (this.closing) throw new Error('Authswitch authority is closing.');
+        return this.releaseRuntimeBinding(request.bindingId, request.capability);
       }));
   }
 
+  private async doctorPage(request: IReq_AuthSwitchDoctor['request']): Promise<IAuthSwitchDoctorPage> {
+    const stored = await this.database.doctorPage({
+      accountAfter: request.accountAfter ?? null,
+      loginAfter: request.loginAfter ?? null,
+      codexHomeAfter: request.codexHomeAfter ?? null,
+      claudeHomeAfter: request.claudeHomeAfter ?? null,
+      claudeHandoffAfter: request.claudeHandoffAfter ?? null,
+      nativeHandoffAfter: request.nativeHandoffAfter ?? null,
+      migrationAfter: request.migrationAfter ?? null,
+    }, request.limit ?? 128);
+    const socketPaths = stored.codexHomes.flatMap(home => home.activeRun ? [home.activeRun.socketPath] : []);
+    let processInspection: Awaited<ReturnType<typeof observeManagedCodexProcesses>> | null = null;
+    try { processInspection = await observeManagedCodexProcesses(socketPaths); }
+    catch { /* A fixed diagnostic category is safer than exposing a host-process error. */ }
+    const processObservedAt = new Date().toISOString();
+    const managedCodex = stored.codexHomes.map(home => {
+      const activeRun = home.activeRun;
+      const durable: IAuthSwitchDoctorPage['managedCodex'][number]['durable'] = activeRun === null
+        ? { state: 'idle', runId: null, pid: null, startedAt: null }
+        : { state: activeRun.pid === null || activeRun.startedAt === null ? 'launch_prepared' : 'registered',
+            runId: activeRun.id, pid: activeRun.pid, startedAt: activeRun.startedAt };
+      const daemonState = this.managedCodexStates.get(home.scopeId) ?? 'untracked';
+      const assignment = daemonState === 'untracked'
+        ? 'untracked' as const
+        : this.managedCodexAccountIds.get(home.scopeId) === home.accountId && this.managedCodexHomes.has(home.id)
+          ? 'matches' as const : 'mismatch' as const;
+      let process: IAuthSwitchDoctorPage['managedCodex'][number]['process'];
+      if (!activeRun) {
+        process = { state: 'not_expected', identity: 'not_applicable', pid: null, startedAt: null,
+          observedAt: processObservedAt, problem: 'none' };
+      } else if (!processInspection) {
+        process = { state: 'unknown', identity: 'unknown', pid: null, startedAt: null,
+          observedAt: processObservedAt, problem: 'inspection_failed' };
+      } else {
+        const observed = processInspection.get(activeRun.socketPath);
+        if (!observed || observed.state === 'absent') {
+          process = { state: 'absent', identity: 'not_applicable', pid: null, startedAt: null,
+            observedAt: processObservedAt, problem: 'none' };
+        } else if (observed.state === 'multiple_claimants') {
+          process = { state: 'unknown', identity: 'unknown', pid: null, startedAt: null,
+            observedAt: processObservedAt, problem: 'multiple_claimants' };
+        } else {
+          const identity = activeRun.pid === null || activeRun.startedAt === null
+            ? 'unregistered' as const
+            : activeRun.pid === observed.pid && activeRun.startedAt === observed.startedAt
+              ? 'matches' as const : 'mismatch' as const;
+          process = { state: 'observed', identity, pid: observed.pid, startedAt: observed.startedAt,
+            observedAt: processObservedAt, problem: 'none' };
+        }
+      }
+      const health = process.state === 'unknown'
+        ? 'unknown' as const
+        : daemonState === 'degraded' || assignment === 'mismatch'
+          || (activeRun !== null && (daemonState === 'untracked' || process.state === 'absent'
+            || process.identity === 'mismatch'))
+          ? 'degraded' as const : 'healthy' as const;
+      return { homeId: home.id, accountId: home.accountId, loginId: home.grantId, scopeId: home.scopeId,
+        health, durable, daemon: { state: daemonState, assignment }, process };
+    });
+    const observedAt = new Date().toISOString();
+    return {
+      observedAt,
+      daemon: { state: this.closing ? 'closing' : 'ready',
+        claudeNativeAuthority: this.claudeNative ? 'configured' : 'not_configured', observedAt },
+      database: { state: 'available', observedAt: stored.observedAt, schemaVersion: stored.meta.schemaVersion,
+        admission: stored.meta.admission, epoch: stored.meta.epoch, revision: stored.meta.revision },
+      accounts: stored.accounts.map(account => ({ id: account.id, providerId: account.providerId,
+        removed: account.removed, statusObservedAt: account.statusObservedAt,
+        evidence: 'stored', liveCheck: 'not_checked' })),
+      logins: stored.logins.map(login => ({ id: login.id, accountId: login.accountId,
+        providerId: login.providerId, purpose: login.purpose, owner: login.owner, state: login.state,
+        problem: login.problem, grantGeneration: login.grantGeneration,
+        authorizationGeneration: login.authorizationGeneration, accessExpiresAt: login.accessExpiresAt,
+        retryAt: login.retryAt, statusObservedAt: login.statusObservedAt,
+        evidence: 'stored', liveCheck: 'not_checked' })),
+      managedCodex,
+      claudeHomes: stored.claudeHomes.map(home => ({ id: home.id, activeAccountId: home.activeAccountId,
+        activeLoginId: home.activeGrantId, pendingOperationId: home.pendingOperationId, status: home.status,
+        revision: home.revision, createdAt: home.createdAt })),
+      claudeHandoffs: stored.claudeHandoffs.map(handoff => ({ id: handoff.id, homeId: handoff.homeId,
+        outgoingAccountId: handoff.outgoingAccountId, outgoingLoginId: handoff.outgoingGrantId,
+        incomingAccountId: handoff.incomingAccountId, incomingLoginId: handoff.incomingGrantId,
+        phase: handoff.phase, problem: handoff.problem, runningEffectiveAuth: handoff.runningEffectiveAuth,
+        startedAt: handoff.startedAt, updatedAt: handoff.updatedAt, revision: handoff.revision })),
+      nativeHandoffs: stored.nativeHandoffs.map(handoff => ({ id: handoff.id, accountId: handoff.accountId,
+        loginId: handoff.grantId, nativeHomeId: handoff.nativeHomeId, direction: handoff.direction,
+        phase: handoff.phase, operationId: handoff.operationId, revision: handoff.revision,
+        statusObservedAt: handoff.statusObservedAt })),
+      migrations: stored.migrations.map(migration => ({ id: migration.id, sourceKind: migration.sourceKind,
+        status: migration.status, accountId: migration.accountId, loginId: migration.grantId,
+        revision: migration.revision, statusObservedAt: migration.statusObservedAt })),
+      nextAccountCursor: stored.nextAccountCursor,
+      nextLoginCursor: stored.nextLoginCursor,
+      nextCodexHomeCursor: stored.nextCodexHomeCursor,
+      nextClaudeHomeCursor: stored.nextClaudeHomeCursor,
+      nextClaudeHandoffCursor: stored.nextClaudeHandoffCursor,
+      nextNativeHandoffCursor: stored.nextNativeHandoffCursor,
+      nextMigrationCursor: stored.nextMigrationCursor,
+    };
+  }
+
   public async start(): Promise<void> {
     if (this.managementServer || this.runtimeServer) throw new Error('Authswitch authority daemon is already started.');
     await this.database.start();
     try {
+      await this.database.assertOpenAdmission();
       await this.broker.start();
+      await this.preuse.start();
+      if (this.claudeNative) await this.claudeNative.start();
       const managementDirectory = plugins.path.dirname(this.options.authoritySocketPath);
       const runtimeDirectory = plugins.path.dirname(this.options.runtimeSocketPath);
       const databaseDirectory = plugins.path.dirname(this.options.socketPath);
@@ -122,6 +513,198 @@ export class AuthSwitchAuthorityDaemon {
     }
   }
 
+  /** The account fence excludes new admissions while durable detached runs are checked. */
+  private async drainManagedCodexAccount(accountId: string): Promise<void> {
+    const scopes = [...this.managedCodexAccountIds]
+      .filter(([, assignedAccountId]) => assignedAccountId === accountId).map(([scopeId]) => scopeId);
+    if (scopes.length) throw new Error('Managed Codex may still have active work; stop it explicitly after work finishes before changing this account.');
+    let after: string | null = null;
+    while (true) {
+      const homes = await this.database.codexHomesForAccount(accountId, after);
+      for (const home of homes) {
+        const run = home.activeRun;
+        if (!run) continue;
+        const survivor = await findManagedCodexProcess(run.socketPath);
+        if (survivor) throw new Error('A managed Codex app-server still owns this account; stop its work before changing the account.');
+        if (run.pid === null || run.startedAt === null) {
+          throw new Error('A managed Codex launch has uncertain process ownership; reconcile it before changing the account.');
+        }
+        try {
+          process.kill(run.pid, 0);
+          throw new Error('A managed Codex process identity is still present; reconcile it before changing the account.');
+        } catch (error) {
+          if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ESRCH')) throw error;
+        }
+        await this.database.changeCodexRun(home.id, run.id, null, plugins.crypto.randomUUID());
+      }
+      if (homes.length < 128) break;
+      after = homes.at(-1)!.id;
+    }
+  }
+
+  public async startManagedCodex(input: { accountId: string; loginId: string; purpose: 'openai_managed';
+    scopeId: string; workspaceDirectory: string;
+    codexHomeDirectory: string;
+    executable?: string; onNotification?: IAuthSwitchManagedCodexOptions['onNotification'];
+    onServerRequest?: IAuthSwitchManagedCodexOptions['onServerRequest'] }): Promise<AuthSwitchManagedCodex> {
+    if (!plugins.path.isAbsolute(input.codexHomeDirectory)
+      || plugins.path.normalize(input.codexHomeDirectory) !== input.codexHomeDirectory) {
+      throw new Error('Managed Codex requires a normalized absolute state home.');
+    }
+    const homeId = plugins.crypto.createHash('sha256').update(JSON.stringify(['authswitch-codex-home-v1', input.codexHomeDirectory])).digest('hex');
+    if (this.closing || !this.managementServer || !this.runtimeServer
+      || this.managedCodex.has(input.scopeId) || this.managedCodexStops.has(input.scopeId)
+      || this.managedCodexHomes.has(homeId) || this.drainingAccounts.has(input.accountId)) {
+      throw new Error('Managed Codex scope is unavailable.');
+    }
+    this.managedCodexHomes.add(homeId);
+    this.managedCodexAccountIds.set(input.scopeId, input.accountId);
+    this.managedCodexStates.set(input.scopeId, 'starting');
+    const runId = plugins.crypto.randomUUID();
+    const task = (async () => {
+      let bound: Awaited<ReturnType<typeof this.broker.bindAccount>> | undefined;
+      let runtime: AuthSwitchManagedCodex | undefined;
+      let claimed = false;
+      try {
+        await this.database.assertOpenAdmission();
+        const home = input.codexHomeDirectory;
+        const parent = plugins.path.dirname(home);
+        const parentStat = await plugins.fs.promises.lstat(parent);
+        if (!parentStat.isDirectory() || parentStat.isSymbolicLink() || parentStat.uid !== process.getuid?.()
+          || (parentStat.mode & 0o077) !== 0 || await plugins.fs.promises.realpath(parent) !== parent) {
+          throw new Error('Managed Codex home parent must be private and owned by this user.');
+        }
+        const nativeHomes = [plugins.path.join(plugins.os.homedir(), '.codex'), process.env.CODEX_HOME]
+          .filter((value): value is string => typeof value === 'string' && plugins.path.isAbsolute(value));
+        if (nativeHomes.some(native => home === native || home.startsWith(native + plugins.path.sep)
+          || native.startsWith(home + plugins.path.sep))) {
+          throw new Error('Managed Codex cannot adopt an active native Codex home.');
+        }
+        const existing = await this.database.readCodexHome(homeId);
+        if (existing && (existing.accountId !== input.accountId || existing.grantId !== input.loginId
+          || existing.scopeId !== input.scopeId)) {
+          throw new Error('Managed Codex home already belongs to another account or scope.');
+        }
+        let homeExists = false;
+        try {
+          const stat = await plugins.fs.promises.lstat(home);
+          if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()
+            || (stat.mode & 0o077) !== 0 || await plugins.fs.promises.realpath(home) !== home) {
+            throw new Error('Managed Codex home is not a private owned directory.');
+          }
+          homeExists = true;
+        } catch (error) {
+          if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')) throw error;
+        }
+        if (!existing && homeExists && (await plugins.fs.promises.readdir(home)).length) {
+          throw new Error('An existing Codex home needs explicit native-owner handoff before enrollment.');
+        }
+        await this.database.reserveCodexHome(input.accountId, input.loginId, input.scopeId, homeId, plugins.crypto.randomUUID());
+        if (!homeExists) await plugins.fs.promises.mkdir(home, { mode: 0o700 });
+        bound = await this.broker.bindAccount({ accountId: input.accountId, loginId: input.loginId,
+          purpose: input.purpose, runtime: 'codex',
+          scopeId: input.scopeId, incarnationId: plugins.crypto.randomUUID() });
+        runtime = new AuthSwitchManagedCodex({
+          runtimeDirectory: plugins.path.join(plugins.path.dirname(plugins.path.dirname(this.options.authoritySocketPath)), 'managed-codex'),
+          codexHomeDirectory: home, workspaceDirectory: input.workspaceDirectory, executable: input.executable,
+          onNotification: input.onNotification, onServerRequest: input.onServerRequest,
+          broker: this.broker, bindingId: bound.binding.id, capability: bound.capability,
+          onPreparedRun: async socketPath => {
+            const assigned = await this.database.readCodexHome(homeId);
+            if (!assigned || assigned.accountId !== input.accountId || assigned.grantId !== input.loginId
+              || assigned.scopeId !== input.scopeId) {
+              throw new Error('Managed Codex home assignment changed.');
+            }
+            if (assigned.activeRun) {
+              const survivor = await findManagedCodexProcess(assigned.activeRun.socketPath);
+              if (survivor) throw new Error('Managed Codex home still has a live app-server owner.');
+              await this.database.changeCodexRun(homeId, assigned.activeRun.id, null, plugins.crypto.randomUUID());
+            }
+            await this.database.changeCodexRun(homeId, null,
+              { id: runId, socketPath, pid: null, startedAt: null }, plugins.crypto.randomUUID());
+            claimed = true;
+          },
+          onChildSpawned: async (pid, startedAt) => {
+            const assigned = await this.database.readCodexHome(homeId);
+            if (assigned?.activeRun?.id !== runId || assigned.activeRun.pid !== null) {
+              throw new Error('Managed Codex run registration changed before process verification.');
+            }
+            await this.database.changeCodexRun(homeId, runId,
+              { ...assigned.activeRun, pid, startedAt }, plugins.crypto.randomUUID());
+          },
+          onUnavailable: () => {
+            void this.stopManagedCodex(input.scopeId).catch(error => {
+              this.managedCodexFailures.push(error);
+              process.stderr.write('Managed Codex cleanup failed after its control connection closed.\n');
+            });
+          },
+        });
+        await runtime.start();
+        if (this.closing) throw new Error('Managed Codex admission closed during startup.');
+        if (this.managedCodexStates.get(input.scopeId) !== 'stopping') {
+          this.managedCodexStates.set(input.scopeId, 'ready');
+        }
+        return { runtime, bindingId: bound.binding.id, capability: bound.capability, homeId, runId };
+      } catch (error) {
+        const cleanupErrors: unknown[] = [];
+        if (runtime) try { await runtime.close(); } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (claimed && cleanupErrors.length === 0) try {
+          await this.database.changeCodexRun(homeId, runId, null, plugins.crypto.randomUUID());
+        } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (bound) try { await this.broker.revokeBinding(bound.binding.id, bound.capability); }
+        catch (cleanupError) { cleanupErrors.push(cleanupError); }
+        if (cleanupErrors.length === 0) {
+          this.managedCodexHomes.delete(homeId);
+          this.managedCodexAccountIds.delete(input.scopeId);
+          this.managedCodexStates.delete(input.scopeId);
+        }
+        if (cleanupErrors.length) {
+          this.managedCodexStates.set(input.scopeId, 'degraded');
+          throw new AggregateError([error, ...cleanupErrors], 'Managed Codex admission cleanup failed.');
+        }
+        throw error;
+      }
+    })();
+    this.managedCodex.set(input.scopeId, task);
+    try { return (await task).runtime; }
+    catch (error) { this.managedCodex.delete(input.scopeId); throw error; }
+  }
+
+  public stopManagedCodex(scopeId: string): Promise<void> {
+    const existing = this.managedCodexStops.get(scopeId);
+    if (existing) return existing;
+    const task = this.managedCodex.get(scopeId);
+    if (!task) return Promise.resolve();
+    this.managedCodex.delete(scopeId);
+    this.managedCodexStates.set(scopeId, 'stopping');
+    const stopping = (async () => {
+      let entry: Awaited<typeof task>;
+      try { entry = await task; }
+      catch {
+        /* Failed admission already closed its process and revoked its binding. */
+        if (this.managedCodexStates.get(scopeId) !== 'degraded') this.managedCodexStates.delete(scopeId);
+        return;
+      }
+      const { runtime, bindingId, capability, homeId, runId } = entry;
+      const errors: unknown[] = [];
+      try { await runtime.close(); } catch (error) { errors.push(error); }
+      if (errors.length === 0) try {
+        await this.database.changeCodexRun(homeId, runId, null, plugins.crypto.randomUUID());
+        this.managedCodexHomes.delete(homeId);
+        this.managedCodexAccountIds.delete(scopeId);
+        this.managedCodexStates.delete(scopeId);
+      } catch (error) { errors.push(error); }
+      try { await this.broker.revokeBinding(bindingId, capability); } catch (error) { errors.push(error); }
+      if (errors.length) {
+        this.managedCodexStates.set(scopeId, 'degraded');
+        throw new AggregateError(errors, 'Managed Codex shutdown was incomplete.');
+      }
+    })();
+    this.managedCodexStops.set(scopeId, stopping);
+    void stopping.finally(() => { if (this.managedCodexStops.get(scopeId) === stopping) this.managedCodexStops.delete(scopeId); }).catch(() => {});
+    return stopping;
+  }
+
   private async listen(path: string, router: plugins.typedrequest.TypedRouter): Promise<plugins.net.Server> {
     const directory = plugins.path.dirname(path);
     await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
@@ -201,8 +784,22 @@ export class AuthSwitchAuthorityDaemon {
   }
 
   public async close(): Promise<void> {
+    this.closing = true;
     const errors: unknown[] = [];
+    try { await this.preuse.close(); } catch (error) { errors.push(error); }
+    for (const scopeId of [...this.managedCodex.keys()]) {
+      try { await this.stopManagedCodex(scopeId); } catch (error) { errors.push(error); }
+    }
+    for (const stopping of [...this.managedCodexStops.values()]) {
+      try { await stopping; } catch (error) { errors.push(error); }
+    }
+    for (const release of [...this.runtimeBindingReleases.values()]) {
+      try { await release; } catch (error) { errors.push(error); }
+    }
+    errors.push(...this.managedCodexFailures);
+    try { await this.usage.close(); } catch (error) { errors.push(error); }
     try { await this.broker.close(); } catch (error) { errors.push(error); }
+    if (this.claudeNative) try { await this.claudeNative.close(); } catch (error) { errors.push(error); }
     const management = this.managementServer;
     const runtime = this.runtimeServer;
     this.managementServer = undefined;