@modelprofile.com/authswitch 8.0.0 → 8.2.0

package/ts/classes.authoritymodels.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import type { TAuthSwitchLoginPrompt } from './authority-contract.js';
+import type { TAuthSwitchClaudeProofFailure, TAuthSwitchLoginPrompt } from './authority-contract.js';
 import type { IAuthSwitchStoredUsage } from './classes.authorityusage.js';
 
 export interface IStoredAuthorityMeta {
@@ -51,6 +51,27 @@ export interface IStoredAuthorityGrant {
   updateId: string;
 }
 
+/**
+ * Whether a change of grant owner hands the refresher from one live owner to another.
+ *
+ * `daemon`, `legacy_native` and `claude_native` each refresh the grant they own, so moving between any two
+ * of them is a transfer and needs a verified handoff: doing it in one write would leave two owners believing
+ * they may send the same rotating refresh token. `none` is not an owner but the absence of one -- a grant
+ * that needs re-authentication has no refresher, and a device login gives it one -- so every transition to
+ * or from `none` is an ordinary lifecycle step, not a transfer.
+ */
+export const transfersGrantRefresher = (previous: IStoredAuthorityGrant['owner'],
+  next: IStoredAuthorityGrant['owner']): boolean =>
+  previous !== next && previous !== 'none' && next !== 'none';
+
+/** The refusal that names the direction of a transfer, so a caller learns which handoff it needs. */
+export const grantRefresherTransferRefusal = (previous: IStoredAuthorityGrant['owner'],
+  next: IStoredAuthorityGrant['owner']): string => next === 'daemon'
+  ? 'Native ownership requires a verified handoff.'
+  : previous === 'daemon'
+    ? 'Daemon ownership is released by a verified handoff.'
+    : 'Native ownership moves between native owners by a verified handoff.';
+
 /** Credential-free provider usage cached for one exact account/login pair. */
 export interface IStoredAuthorityUsage extends IAuthSwitchStoredUsage {
   id: string;
@@ -134,6 +155,8 @@ export interface IStoredAuthorityClaudeHandoff {
   sealedOutgoing: string | null;
   runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth' | null;
   problem: 'none' | 'native_uncertain' | 'foreign_or_torn' | 'unsupported_effective_auth' | 'database_uncertain';
+  /** Which condition of the native-login proof failed; stored, so a lost answer stays diagnosable. */
+  proofFailure: TAuthSwitchClaudeProofFailure | null;
   startedAt: string;
   updatedAt: string;
   revision: number;
@@ -481,7 +504,7 @@ export const assertStoredAuthorityClaudeHandoff: (value: unknown) => asserts val
   if (!object(value) || !exactKeys(value, ['id', 'homeId', 'outgoingAccountId', 'outgoingGrantId',
     'incomingAccountId', 'incomingGrantId', 'phase', 'before', 'after', 'sourceIdentity',
     'targetIdentity', 'sourceAccessDigest', 'targetAccessDigest', 'sealedOutgoing',
-    'runningEffectiveAuth', 'problem', 'startedAt', 'updatedAt', 'revision', 'updateId'])
+    'runningEffectiveAuth', 'problem', 'proofFailure', 'startedAt', 'updatedAt', 'revision', 'updateId'])
     || !uuid(value.id) || !hash(value.homeId) || !hash(value.outgoingAccountId)
     || !hash(value.outgoingGrantId) || !hash(value.incomingAccountId) || !hash(value.incomingGrantId)
     || value.outgoingAccountId === value.incomingAccountId || value.outgoingGrantId === value.incomingGrantId
@@ -493,8 +516,14 @@ export const assertStoredAuthorityClaudeHandoff: (value: unknown) => asserts val
     || !ciphertext(value.sealedOutgoing)
     || ![null, 'no_scoped_sessions', 'unsupported_effective_auth'].includes(value.runningEffectiveAuth as null)
     || !['none', 'native_uncertain', 'foreign_or_torn', 'unsupported_effective_auth', 'database_uncertain'].includes(String(value.problem))
+    || ![null, 'unsupported_release', 'override', 'profile', 'profile_unreadable', 'settings',
+      'subscription', 'running_session'].includes(value.proofFailure as null)
     || !iso(value.startedAt) || !iso(value.updatedAt) || !revision(value.revision)
     || value.revision === 0 || !uuid(value.updateId)) throw new Error('Invalid Claude native handoff.');
+  // The detail belongs to exactly the problem it explains, so a client can trust one without the other.
+  if (value.proofFailure !== null && value.problem !== 'unsupported_effective_auth') {
+    throw new Error('Claude handoff names a proof failure without the problem it explains.');
+  }
   const hasProof = value.before !== null && value.after !== null
     && value.sourceAccessDigest !== null && value.targetAccessDigest !== null;
   const hasNoProof = value.before === null && value.after === null
@@ -817,6 +846,7 @@ export class AuthSwitchAuthorityClaudeHandoffModel extends plugins.nosqldb.Smart
   @plugins.nosqldb.svDb() public sealedOutgoing!: string | null;
   @plugins.nosqldb.svDb() public runningEffectiveAuth!: IStoredAuthorityClaudeHandoff['runningEffectiveAuth'];
   @plugins.nosqldb.svDb() public problem!: IStoredAuthorityClaudeHandoff['problem'];
+  @plugins.nosqldb.svDb() public proofFailure!: IStoredAuthorityClaudeHandoff['proofFailure'];
   @plugins.nosqldb.svDb() public startedAt!: string;
   @plugins.nosqldb.svDb() public updatedAt!: string;
   @plugins.nosqldb.svDb() public revision!: number;

package/ts/classes.authorityservice.ts

@@ -1,5 +1,8 @@
 import * as plugins from './plugins.js';
 import { AuthSwitchAuthorityDaemon } from './classes.authoritydaemon.js';
+import type { IClaudeNativeAuthorityOptions } from './classes.claudeauthority.js';
+import { ClaudeNativeAdapter, claudeNativeUserSettingsFiles,
+  resolveClaudeNativeHome } from './classes.claudenative.js';
 
 export interface IAuthSwitchAuthorityPaths {
   runtimeDirectory: string;
@@ -60,12 +63,36 @@ export class AuthSwitchAuthorityService {
   public stop(): Promise<plugins.smartdaemon.ISystemdUnitState> { return this.unit.stop(); }
 }
 
+/**
+ * The Claude native authority this user's daemon serves.
+ *
+ * It is wired whether or not Claude Code is installed: nothing here touches the filesystem, and every
+ * operation that needs the native home refuses until a verified import receipt has registered it. An
+ * environment that names a home this daemon cannot resolve is a named startup failure rather than a
+ * silently missing capability, because the same environment also decides which file the import reads.
+ */
+export const resolveAuthSwitchClaudeNativeAuthority = (env: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = plugins.os.homedir()): IClaudeNativeAuthorityOptions => {
+  const resolution = resolveClaudeNativeHome(env, homeDirectory);
+  if (resolution.kind === 'unusable') {
+    throw new Error(`Authswitch authority cannot locate Claude Code's native home: ${resolution.defect.problem}.`);
+  }
+  const { configDir, configFile, homeId } = resolution.home;
+  // The adapter re-derives which home Claude Code itself selects; it must read the environment this
+  // home was resolved from, or the two could disagree about the same host. Its settings sources are
+  // stated from that same home: this daemon's working directory is the service unit's own (the package
+  // root, see `AuthSwitchAuthorityService`), so a project settings file beside it selects nothing.
+  return { homeId, adapter: new ClaudeNativeAdapter({ configDir, configFile, env,
+    settingsFiles: claudeNativeUserSettingsFiles(configDir) }) };
+};
+
 export const runAuthSwitchAuthorityDaemon = async (paths = resolveAuthSwitchAuthorityPaths()): Promise<void> => {
   const daemon = new AuthSwitchAuthorityDaemon({
     dataDirectory: paths.dataDirectory,
     socketPath: paths.databaseSocketPath,
     authoritySocketPath: paths.authoritySocketPath,
     runtimeSocketPath: paths.runtimeSocketPath,
+    claudeNative: resolveAuthSwitchClaudeNativeAuthority(),
   });
   await daemon.start();
   await new Promise<void>((resolve, reject) => {

package/ts/classes.claudeauthority.ts

@@ -1,9 +1,11 @@
 import * as plugins from './plugins.js';
 import type { IAuthSwitchClaudeNativeHandoff } from './authority-contract.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
 import { AuthSwitchAuthorityDatabase } from './classes.authoritydatabase.js';
 import type { IStoredAuthorityAccount, IStoredAuthorityClaudeHandoff, IStoredAuthorityClaudeHome,
   IStoredAuthorityGrant, IStoredAuthorityNativePair } from './classes.authoritymodels.js';
-import { ClaudeNativeAdapter, type IClaudeNativeIdentity, type IClaudeNativeLogin,
+import { ClaudeNativeAdapter, ClaudeNativeEffectiveAuthUnsupportedError,
+  type IClaudeNativeIdentity, type IClaudeNativeLogin,
   type IClaudeNativeLockedSession, type IClaudeNativeSnapshot } from './classes.claudenative.js';
 import { ClaudeTokenRefresh } from './classes.claudetokenrefresh.js';
 import { AuthSwitchTpmSecretCodec, type IAuthSwitchSecretCodec } from './classes.authoritysecrets.js';
@@ -34,6 +36,7 @@ const publicHandoff = (handoff: IStoredAuthorityClaudeHandoff): IAuthSwitchClaud
   id: handoff.id, homeId: handoff.homeId, outgoingAccountId: handoff.outgoingAccountId,
   incomingAccountId: handoff.incomingAccountId, phase: handoff.phase, problem: handoff.problem,
   runningEffectiveAuth: handoff.runningEffectiveAuth, updatedAt: handoff.updatedAt,
+  ...(handoff.proofFailure === null ? {} : { proofFailure: handoff.proofFailure }),
 });
 
 /** Daemon-owned Claude refresh and a journaled transfer of one native home between two grants. */
@@ -137,7 +140,7 @@ export class ClaudeNativeAuthority {
     const account = await this.database.readAccount(grant.accountId);
     if (!account || account.removed) return;
     if (!(await this.database.hasVerifiedClaudeGrantReceipt(account.id, grant.id))) {
-      throw new Error('Claude refresh requires a verified import receipt.');
+      throw new AuthSwitchRefusal('claude_receipt_missing', 'Claude refresh requires a verified import receipt.');
     }
     const login = await this.unsealLogin(account, grant);
     if (rejectedGrantGeneration !== undefined && rejectedGrantGeneration > grant.grantGeneration) {
@@ -229,7 +232,7 @@ export class ClaudeNativeAuthority {
         throw new Error('Inactive Claude status authority changed.');
       }
       if (!(await this.database.hasVerifiedClaudeGrantReceipt(view.account.id, view.grant.id))) {
-        throw new Error('Claude status requires a verified import receipt.');
+        throw new AuthSwitchRefusal('claude_receipt_missing', 'Claude status requires a verified import receipt.');
       }
       const currentLogin = this.statusLogin(view.account, await this.unsealLogin(view.account, view.grant));
       if (!currentLogin.scopes.includes('user:profile')) {
@@ -342,7 +345,7 @@ export class ClaudeNativeAuthority {
         incomingAccountId: incoming.accountId, incomingGrantId: incoming.id, phase: 'reserved',
         before: null, after: null, sourceIdentity: identityFor(outgoingAccount),
         targetIdentity: identityFor(incomingAccount), sourceAccessDigest: null, targetAccessDigest: null,
-        sealedOutgoing: null, runningEffectiveAuth: null, problem: 'none', startedAt: now,
+        sealedOutgoing: null, runningEffectiveAuth: null, problem: 'none', proofFailure: null, startedAt: now,
         updatedAt: now, revision: 1, updateId,
       };
       return { home: this.homeStep(home, updateId, { pendingOperationId: operationId }), handoff,
@@ -369,7 +372,8 @@ export class ClaudeNativeAuthority {
 
   private async settle(operationId: string, phase: 'committed' | 'aborted' | 'quarantined',
     runningEffectiveAuth: IClaudeNativeSnapshot['runningEffectiveAuth'] | null,
-    problem: IStoredAuthorityClaudeHandoff['problem'] = 'none'): Promise<IAuthSwitchClaudeNativeHandoff> {
+    problem: IStoredAuthorityClaudeHandoff['problem'] = 'none',
+    proofFailure: IStoredAuthorityClaudeHandoff['proofFailure'] = null): Promise<IAuthSwitchClaudeNativeHandoff> {
     const context = await this.database.readClaudeHandoffContext(operationId);
     if (!context) throw new Error('Claude handoff operation is missing.');
     if (['committed', 'aborted', 'quarantined'].includes(context.handoff.phase)) return publicHandoff(context.handoff);
@@ -395,7 +399,7 @@ export class ClaudeNativeAuthority {
           : quarantined ? { status: 'quarantined' }
             : { pendingOperationId: null, status: 'ready' }),
         handoff: { ...handoff, phase, sealedOutgoing: quarantined ? handoff.sealedOutgoing : null,
-          runningEffectiveAuth, problem, updatedAt: now, revision: handoff.revision + 1, updateId },
+          runningEffectiveAuth, problem, proofFailure, updatedAt: now, revision: handoff.revision + 1, updateId },
         outgoing: this.grantStep(outgoing, updateId, now, committed
           ? { state: 'ready', owner: 'daemon', ciphertext: handoff.sealedOutgoing,
               accessExpiresAt: outgoingExpiry, problem: 'none',
@@ -448,8 +452,11 @@ export class ClaudeNativeAuthority {
     if (['committed', 'aborted', 'quarantined'].includes(context.handoff.phase)) return publicHandoff(context.handoff);
     try {
       return await this.options.adapter.withExclusiveHome(session => this.classify(operationId, session));
-    } catch {
-      return this.settle(operationId, 'quarantined', null, 'unsupported_effective_auth');
+    } catch (error) {
+      // Which condition of the proof failed is the one thing an owner can act on, so it is journaled
+      // rather than collapsed into the problem it explains.
+      return this.settle(operationId, 'quarantined', null, 'unsupported_effective_auth',
+        error instanceof ClaudeNativeEffectiveAuthUnsupportedError ? error.reason : null);
     }
   }
 
@@ -479,8 +486,13 @@ export class ClaudeNativeAuthority {
 
   private async performSwitch(accountId: string, loginId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
     const home = await this.database.readClaudeHome(this.options.homeId);
+    // Two different answers for the owner: there is no adopted home yet, or one move is already running.
+    if (home && home.status === 'ready' && home.pendingOperationId !== null) {
+      throw new AuthSwitchRefusal('claude_handoff_pending',
+        'A Claude handoff is already running for this home; wait for it to finish, then switch again.');
+    }
     if (!home || home.status !== 'ready' || home.pendingOperationId !== null) {
-      throw new Error('Verified Claude native home is unavailable or has a pending handoff.');
+      throw new AuthSwitchRefusal('claude_home_unregistered', 'Verified Claude native home is unavailable or has a pending handoff.');
     }
     await this.refreshInactiveGrant(loginId);
     const operationId = plugins.crypto.randomUUID();
@@ -517,7 +529,7 @@ export class ClaudeNativeAuthority {
 
   public async getHandoff(operationId: string): Promise<IAuthSwitchClaudeNativeHandoff> {
     const handoff = await this.database.readClaudeHandoff(operationId);
-    if (!handoff || handoff.homeId !== this.options.homeId) throw new Error('Claude handoff operation was not found.');
+    if (!handoff || handoff.homeId !== this.options.homeId) throw new AuthSwitchRefusal('not_found', 'Claude handoff operation was not found.');
     return publicHandoff(handoff);
   }
 

package/ts/classes.claudenative.ts

@@ -1,4 +1,5 @@
 import * as plugins from './plugins.js';
+import type { TAuthSwitchClaudeProofFailure } from './authority-contract.js';
 import { ClaudeCodeLockOutcomeUnknownError, ClaudeCodeLocks,
   type IClaudeCodeLockLease } from './classes.claudecodelocks.js';
 import { claudeRequest } from './claudehttp.js';
@@ -34,9 +35,10 @@ const CREDENTIAL_OVERRIDES = [
 export class ClaudeNativeEffectiveAuthUnsupportedError extends Error {
   public readonly code = 'unsupported_effective_auth';
 
-  constructor(public readonly reason: 'override' | 'profile' | 'profile_unreadable' | 'settings'
-    | 'subscription' | 'running_session') {
-    super(`Cannot prove that Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} uses its native claude.ai login (${reason}).`);
+  constructor(public readonly reason: TAuthSwitchClaudeProofFailure) {
+    super(reason === 'unsupported_release'
+      ? `Native Claude handoff requires Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} for every active session.`
+      : `Cannot prove that Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} uses its native claude.ai login (${reason}).`);
   }
 }
 
@@ -142,7 +144,15 @@ export interface IClaudeNativeAdapterOptions {
   executable?: string;
   platform?: NodeJS.Platform;
   env?: NodeJS.ProcessEnv;
-  settingsFiles?: readonly string[];
+  /**
+   * The settings sources this proof reads, stated by the caller because only it knows which they are.
+   *
+   * There is no default: this adapter runs inside the daemon, whose working directory is the service
+   * unit's and never a Claude session's project, so a list derived from `process.cwd()` would prove a
+   * directory nobody selected. `claudeNativeUserSettingsFiles` is the daemon's list; the settings a
+   * running session selected are proven from that session's own working directory instead.
+   */
+  settingsFiles: readonly string[];
   /** Internal test seam; production uses Claude's Linux managed-settings directory. */
   managedSettingsDirectory?: string;
   fetch?: typeof fetch;
@@ -166,6 +176,87 @@ const preparedWrites = new WeakMap<IClaudeNativePreparedWrite, {
 const sameIdentity = (left: IClaudeNativeIdentity, right: IClaudeNativeIdentity): boolean =>
   left.accountUuid === right.accountUuid && left.organizationUuid === right.organizationUuid;
 
+/** Claude Code's own paths on this host, and the authority's id for that one native home. */
+export interface IClaudeNativeHome {
+  configDir: string;
+  configFile: string;
+  credentialFile: string;
+  homeId: string;
+}
+
+/**
+ * A home this host cannot have: the location it was pointed at, and why it is not usable.
+ *
+ * The inventory reports such a source with its defect rather than skipping it or reading a guessed
+ * location, so `declaredCredentialFile` names what the environment asked for, unresolved.
+ */
+export interface IClaudeNativeHomeDefect {
+  declaredCredentialFile: string;
+  problem: string;
+}
+
+export type TClaudeNativeHomeResolution =
+  | { kind: 'resolved'; home: IClaudeNativeHome }
+  | { kind: 'unusable'; defect: IClaudeNativeHomeDefect };
+
+/**
+ * The authority's id for one native Claude home: the hash of the credential file Claude Code owns.
+ *
+ * The import ledger publishes the same value as a source's `sourcePathHash`, and
+ * `registerClaudeHomeFromReceipt` adopts a home only when the two are equal, so both sides must derive it
+ * here and nowhere else.
+ */
+export const claudeNativeHomeId = (credentialFile: string): string => hash(credentialFile);
+
+/** An absolute, normalized directory without a trailing separator, or null for anything else. */
+const canonicalDirectory = (value: string): string | null => {
+  if (!plugins.path.isAbsolute(value)) return null;
+  const normalized = plugins.path.normalize(value);
+  return normalized.length > 1 && normalized.endsWith(plugins.path.sep)
+    ? normalized.slice(0, -1) : normalized;
+};
+
+/**
+ * Where Claude Code keeps this user's login, resolved once for the daemon and the import inventory alike.
+ *
+ * `CLAUDE_CONFIG_DIR` selects the home; Claude Code keeps its account metadata beside the home directory
+ * unless that variable moves it. A relative directory is never resolved against the current working
+ * directory: a daemon and a CLI run from different places, so guessing would make them disagree about
+ * which file is the login.
+ */
+export const resolveClaudeNativeHome = (env: NodeJS.ProcessEnv,
+  homeDirectory: string): TClaudeNativeHomeResolution => {
+  const declared = env.CLAUDE_CONFIG_DIR ? canonicalDirectory(env.CLAUDE_CONFIG_DIR) : null;
+  if (env.CLAUDE_CONFIG_DIR && declared === null) {
+    return { kind: 'unusable', defect: {
+      declaredCredentialFile: plugins.path.join(env.CLAUDE_CONFIG_DIR, '.credentials.json'),
+      problem: 'CLAUDE_CONFIG_DIR is not an absolute path, so Claude Code\'s own login cannot be located' } };
+  }
+  const home = canonicalDirectory(homeDirectory);
+  if (home === null) {
+    return { kind: 'unusable', defect: {
+      declaredCredentialFile: plugins.path.join(homeDirectory, '.claude', '.credentials.json'),
+      problem: 'the home directory is not an absolute path, so Claude Code\'s own login cannot be located' } };
+  }
+  const configDir = declared ?? plugins.path.join(home, '.claude');
+  const credentialFile = plugins.path.join(configDir, '.credentials.json');
+  return { kind: 'resolved', home: { configDir,
+    configFile: plugins.path.join(declared ?? home, '.claude.json'),
+    credentialFile, homeId: claudeNativeHomeId(credentialFile) } };
+};
+
+/**
+ * The settings sources Claude Code reads at user scope for one resolved home.
+ *
+ * This is what a host-wide owner -- the daemon -- may prove: the user settings file beside the credential
+ * file the home owns. Claude Code's other two scopes are proven where they are selected: the managed
+ * settings directory is checked on its own, and a project's `.claude/settings.json` and
+ * `.claude/settings.local.json` belong to the working directory of a running session, which is read from
+ * that session rather than from this process.
+ */
+export const claudeNativeUserSettingsFiles = (configDir: string): readonly string[] =>
+  [plugins.path.join(configDir, 'settings.json')];
+
 const pathEnvironment = ['HOME', 'XDG_CONFIG_HOME', 'ANTHROPIC_CONFIG_DIR', 'CLAUDE_CONFIG_DIR'] as const;
 const contextKeys = new Set<string>([...CREDENTIAL_OVERRIDES, ...pathEnvironment]);
 const readProcessContext = (file: string): string => {
@@ -486,8 +577,13 @@ export class ClaudeNativeAdapter {
       || plugins.path.normalize(options.configFile) !== options.configFile) {
       throw new Error('Native Claude paths must be normalized absolute paths.');
     }
+    // Claude Code keeps its account metadata inside a configured home and beside an unconfigured one.
+    // Which home that is follows from the environment this adapter was given, the same environment
+    // `assertSupported` re-checks before every operation, never from the running process's own account.
+    const configParent = selectedNativeConfigParent(options.env ?? process.env);
     if (![plugins.path.join(options.configDir, '.claude.json'),
-      plugins.path.join(plugins.os.homedir(), '.claude.json')].includes(options.configFile)) {
+      ...(configParent === null ? [] : [plugins.path.join(configParent, '.claude.json')]),
+    ].includes(options.configFile)) {
       throw new Error('Native Claude account metadata must use its vendor config file.');
     }
     this.credentialFile = plugins.path.join(options.configDir, '.credentials.json');
@@ -497,9 +593,7 @@ export class ClaudeNativeAdapter {
       options.executable ?? 'claude');
     this.fetcher = options.fetch ?? globalThis.fetch;
     this.env = options.env ?? process.env;
-    this.settingsFiles = options.settingsFiles ?? [plugins.path.join(options.configDir, 'settings.json'),
-      plugins.path.join(process.cwd(), '.claude/settings.json'),
-      plugins.path.join(process.cwd(), '.claude/settings.local.json')];
+    this.settingsFiles = options.settingsFiles;
     this.platform = options.platform ?? process.platform;
   }
 
@@ -528,7 +622,7 @@ export class ClaudeNativeAdapter {
       assertSettingsSelectNative(file);
     }
     if (this.versionProbe.installedVersion() !== CLAUDE_NATIVE_HANDOFF_VERSION) {
-      throw new Error(`Native Claude handoff requires Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} for every active session.`);
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
     }
     let runningSessions = 0;
     const nativeHomeIdentity = directoryIdentity(this.options.configDir);
@@ -543,7 +637,7 @@ export class ClaudeNativeAdapter {
         throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
       }
       if (running.version !== CLAUDE_NATIVE_HANDOFF_VERSION) {
-        throw new Error(`Native Claude handoff requires Claude Code ${CLAUDE_NATIVE_HANDOFF_VERSION} for every active session.`);
+        throw new ClaudeNativeEffectiveAuthUnsupportedError('unsupported_release');
       }
       if (!running.env || !running.cwd || running.hasSettingsOverride === null
         || !running.mountNamespace || !running.processRoot) {

package/ts/index.ts

@@ -26,6 +26,7 @@ export * from './watchpolicy.js';
 export * from './classes.authorityclient.js';
 export * from './classes.authoritycli.js';
 export * from './classes.authoritydaemon.js';
+export * from './classes.authorityimport.js';
 export * from './classes.authorityservice.js';
 
 import { AuthSwitchCli } from './classes.cli.js';
@@ -33,7 +34,8 @@ import { runAuthSwitchAuthorityCli } from './classes.authoritycli.js';
 import { AuthSwitchAuthorityService, resolveAuthSwitchAuthorityPaths, runAuthSwitchAuthorityDaemon } from './classes.authorityservice.js';
 
 export const runCli = async (argvArg: string[] = process.argv.slice(2)): Promise<void> => {
-  if (argvArg[0] === 'account' || (argvArg[0] === 'authority' && argvArg[1] === 'doctor')) {
+  if (argvArg[0] === 'account'
+    || (argvArg[0] === 'authority' && (argvArg[1] === 'doctor' || argvArg[1] === 'import'))) {
     process.exitCode = await runAuthSwitchAuthorityCli(argvArg);
     return;
   }
@@ -57,7 +59,8 @@ export const runCli = async (argvArg: string[] = process.argv.slice(2)): Promise
         return;
       }
     }
-    throw new Error('Usage: authswitch authority daemon | service install|status|enable|start|stop');
+    throw new Error('Usage: authswitch authority daemon | service install|status|enable|start|stop '
+      + '| doctor | import inventory');
   }
   const exitCode = await new AuthSwitchCli().run(argvArg);
   process.exitCode = exitCode;

package/ts/ts_migration/0003_claude_handoff_proof.ts

@@ -0,0 +1,19 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Gives every Claude native handoff journalled before 8.2.0 its `proofFailure` field.
+ *
+ * The handoff record is exact-persistence: a document with a key the shape does not declare, or without one
+ * it does, is refused rather than read loosely. A published release therefore cannot gain a field by
+ * declaring it -- the rows that already exist have to carry it too, and this is where that happens.
+ *
+ * Only the absence is filled, with `null`: no release before this one could say which condition of the
+ * native-login proof failed, so there is nothing to infer and nothing to overwrite. A row that already has
+ * the field is left exactly as it is, which is what makes an interrupted run safe to repeat.
+ */
+export const addClaudeHandoffProofFailure = async (db: plugins.nosqldb.SmartdataDb): Promise<void> => {
+  const handoffs = db.mongoDb.collection('authswitch_authority_claude_handoffs');
+  const missing = { proofFailure: { $exists: false } };
+  if (!await handoffs.findOne(missing)) return;
+  await handoffs.updateMany(missing, { $set: { proofFailure: null } });
+};

package/ts/ts_migration/index.ts

@@ -1,6 +1,7 @@
 import * as plugins from '../plugins.js';
 import { migrateAuthorityMeta } from './0001_authority_meta.js';
 import { removeAuthorityBackupRecords } from './0002_remove_backup_records.js';
+import { addClaudeHandoffProofFailure } from './0003_claude_handoff_proof.js';
 
 /**
  * Runs on every start of an existing store, in this fixed order. Each module recognises the published shapes it
@@ -9,4 +10,5 @@ import { removeAuthorityBackupRecords } from './0002_remove_backup_records.js';
 export const runAuthorityMigrations = async (db: plugins.nosqldb.SmartdataDb): Promise<void> => {
   await migrateAuthorityMeta(db);
   await removeAuthorityBackupRecords(db);
+  await addClaudeHandoffProofFailure(db);
 };