@modelprofile.com/authswitch 6.4.0 → 7.0.0

package/ts/classes.claudenative.ts

@@ -0,0 +1,816 @@
+import * as plugins from './plugins.js';
+import { ClaudeCodeLockOutcomeUnknownError, ClaudeCodeLocks,
+  type IClaudeCodeLockLease } from './classes.claudecodelocks.js';
+import { claudeRequest } from './claudehttp.js';
+import { writeSecretFileAtomically } from './helpers.js';
+import { HarnessProcesses } from './classes.harnessprocesses.js';
+
+/** The private file and lock contract verified for this Claude Code release. */
+export const CLAUDE_NATIVE_HANDOFF_VERSION = '2.1.273';
+const MAX_NATIVE_FILE_BYTES = 4 * 1024 * 1024;
+const MAX_PROCESS_CONTEXT_BYTES = 1024 * 1024;
+const PROFILE_TIMEOUT_MS = 10_000;
+const ACCOUNT_CACHES = [
+  'additionalModelOptionsCache', 'additionalModelOptionsAnsweredAt', 'additionalModelCostsCache',
+  'modelAccessCache', 'orgModelDefaultCache', 'lastSeenOrgDefaultUpdatedAt', 'clientDataCache',
+  'clientDataCacheSlots', 'autoCompactWindowsCache', 'cachedUsageUtilization',
+] as const;
+const CREDENTIAL_OVERRIDES = [
+  'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR', 'ANTHROPIC_API_KEY',
+  'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_PROFILE', 'CLAUDE_CODE_USE_BEDROCK',
+  'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY', 'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_FEDERATION_RULE_ID', 'ANTHROPIC_ORGANIZATION_ID',
+  'ANTHROPIC_IDENTITY_TOKEN_FILE', 'ANTHROPIC_IDENTITY_TOKEN', 'ANTHROPIC_WORKSPACE_ID',
+  'ANTHROPIC_UNIX_SOCKET', 'CLAUDE_CODE_REMOTE', 'CLAUDE_CODE_SIMPLE',
+  'CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST', 'CLAUDE_CODE_HOST_AUTH_ENV_VAR',
+  'CLAUDE_CODE_HOST_CREDS_FILE', 'CLAUDE_CODE_SESSION_ACCESS_TOKEN',
+  'CLAUDE_CODE_OAUTH_REFRESH_TOKEN', 'CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR',
+  'CLAUDE_CODE_USE_GATEWAY',
+  'CLAUDE_CODE_GATEWAY_TOKEN_FILE_DESCRIPTOR', 'CLAUDE_CODE_HFI_BEARER_TOKEN',
+  'CLAUDE_BG_AUTH_SNAPSHOT_PATH',
+] as const;
+
+/** Refusal is distinct from a malformed login: Claude may use a different auth source. */
+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}).`);
+  }
+}
+
+export interface IClaudeNativeIdentity {
+  accountUuid: string;
+  organizationUuid: string;
+}
+
+/** Backend-only, secret-bearing source for sealing by the caller's authority journal. */
+export interface IClaudeNativeLogin {
+  claudeAiOauth: Record<string, unknown>;
+  oauthAccount: Record<string, unknown>;
+}
+
+export interface IClaudeNativeDigests {
+  credentialDigest: string | null;
+  configDigest: string | null;
+}
+
+export interface IClaudeNativeSnapshot extends IClaudeNativeDigests {
+  /** The stored native login, not an assertion about an already-running process. */
+  login: IClaudeNativeLogin | null;
+  identity: IClaudeNativeIdentity | null;
+  /** A scoped process's current effective source may change after /cd and cannot be proved externally. */
+  runningEffectiveAuth: 'no_scoped_sessions' | 'unsupported_effective_auth';
+}
+
+/** Provider UUID proof for the token stored in one native snapshot, not for a process's active request. */
+export interface IClaudeNativeProfileProof extends IClaudeNativeIdentity {
+  /** Binds this provider proof to the exact access token that was later written and read back. */
+  accessTokenDigest: string;
+}
+
+export type TClaudeNativeWriteResult =
+  | { kind: 'not_written'; reason: 'source_changed' | 'source_identity_mismatch' | 'source_unreadable'
+      | 'target_unverified' | 'target_oversized';
+      observed: IClaudeNativeDigests | null }
+  /** Exact native pair readback and target-token identity proof; runtimeEffectiveAuth remains separate. */
+  | { kind: 'written'; snapshot: IClaudeNativeSnapshot; profile: IClaudeNativeProfileProof }
+  | { kind: 'uncertain'; reason: 'native_write_or_readback_failed'; observed: IClaudeNativeDigests | null };
+
+/** Exact bytes and provider proof are retained privately by the locked session until the write. */
+export interface IClaudeNativePreparedWrite {
+  readonly before: IClaudeNativeDigests;
+  readonly after: IClaudeNativeDigests;
+  readonly sourceIdentity: IClaudeNativeIdentity | null;
+  readonly targetIdentity: IClaudeNativeIdentity;
+  readonly profile: IClaudeNativeProfileProof;
+}
+
+/** Caller-owned copies of the original native bytes before a prepared write. Null means absent. */
+export interface IClaudeNativePreparedSource {
+  readonly before: IClaudeNativeDigests;
+  readonly credentialBytes: Uint8Array | null;
+  readonly configBytes: Uint8Array | null;
+}
+
+export type TClaudeNativePrepareResult =
+  | { kind: 'prepared'; plan: IClaudeNativePreparedWrite }
+  | Extract<TClaudeNativeWriteResult, { kind: 'not_written' }>;
+
+export interface IClaudeNativeLockedSession {
+  readStable(): IClaudeNativeSnapshot;
+  verifyProfileIdentity(snapshot: IClaudeNativeSnapshot,
+    expected: IClaudeNativeIdentity): Promise<IClaudeNativeProfileProof>;
+  prepareWrite(input: {
+    expected: IClaudeNativeDigests;
+    expectedSourceIdentity: IClaudeNativeIdentity | null;
+    targetLogin: IClaudeNativeLogin;
+    expectedIdentity: IClaudeNativeIdentity;
+  }): Promise<TClaudeNativePrepareResult>;
+  exportPreparedSource(plan: IClaudeNativePreparedWrite): IClaudeNativePreparedSource;
+  writePreparedIfCurrent(plan: IClaudeNativePreparedWrite): TClaudeNativeWriteResult;
+  writeIfCurrent(input: {
+    expected: IClaudeNativeDigests;
+    expectedSourceIdentity: IClaudeNativeIdentity | null;
+    targetLogin: IClaudeNativeLogin;
+    expectedIdentity: IClaudeNativeIdentity;
+  }): Promise<TClaudeNativeWriteResult>;
+}
+
+export interface IClaudeNativeVersionProbe {
+  installedVersion(): string;
+  runningContexts(): readonly IClaudeNativeRunningContext[];
+}
+
+/** Only selector keys and paths, never a process's credential values, leave the /proc reader. */
+export interface IClaudeNativeRunningContext {
+  version: string | null;
+  env: NodeJS.ProcessEnv | null;
+  cwd: string | null;
+  hasSettingsOverride: boolean | null;
+  /** The selected native home as seen through this process's mount namespace. */
+  nativeHomeIdentity: IClaudeNativeDirectoryIdentity | null;
+  /** The directory containing the vendor `.claude.json` and its write lock. */
+  configParentIdentity: IClaudeNativeDirectoryIdentity | null;
+  /** Informational only; a different namespace can still bind the same native home. */
+  mountNamespace: string | null;
+  /** Used to inspect profile and project settings in the process's own namespace. */
+  processRoot: string | null;
+}
+
+export interface IClaudeNativeDirectoryIdentity {
+  device: bigint;
+  inode: bigint;
+}
+
+export interface IClaudeNativeAdapterOptions {
+  configDir: string;
+  configFile: string;
+  executable?: string;
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  settingsFiles?: readonly string[];
+  /** Internal test seam; production uses Claude's Linux managed-settings directory. */
+  managedSettingsDirectory?: string;
+  fetch?: typeof fetch;
+  versionProbe?: IClaudeNativeVersionProbe;
+  lockTimeoutMs?: number;
+}
+
+const hash = (value: string | Uint8Array): string => plugins.crypto.createHash('sha256').update(value).digest('hex');
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value: unknown): value is string => typeof value === 'string' && value.length > 0;
+const sameDigests = (left: IClaudeNativeDigests, right: IClaudeNativeDigests): boolean =>
+  left.credentialDigest === right.credentialDigest && left.configDigest === right.configDigest;
+const onlyDigests = (value: IClaudeNativeDigests): IClaudeNativeDigests => ({
+  credentialDigest: value.credentialDigest, configDigest: value.configDigest,
+});
+const preparedWrites = new WeakMap<IClaudeNativePreparedWrite, {
+  session: ClaudeNativeLockedSession; credentialRaw: string; configRaw: string;
+  originalConfigRaw: Buffer | null; targetAccessToken: string;
+}>();
+const sameIdentity = (left: IClaudeNativeIdentity, right: IClaudeNativeIdentity): boolean =>
+  left.accountUuid === right.accountUuid && left.organizationUuid === right.organizationUuid;
+
+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 => {
+  const descriptor = plugins.fs.openSync(file,
+    plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW | plugins.fs.constants.O_NONBLOCK);
+  try {
+    const buffer = Buffer.alloc(MAX_PROCESS_CONTEXT_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = plugins.fs.readSync(descriptor, buffer, length, buffer.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    if (length === buffer.length) throw new Error('Claude process context is too large to verify.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, length));
+  } finally { plugins.fs.closeSync(descriptor); }
+};
+
+const selectorEnvironment = (raw: string): NodeJS.ProcessEnv => {
+  const selected: NodeJS.ProcessEnv = {};
+  for (const entry of raw.split('\0')) {
+    const separator = entry.indexOf('=');
+    if (separator < 1) continue;
+    const key = entry.slice(0, separator);
+    if (!contextKeys.has(key)) continue;
+    if (Object.hasOwn(selected, key)) throw new Error('Claude process environment selector is ambiguous.');
+    // Presence is enough for credential selectors. Never retain their secret value.
+    selected[key] = pathEnvironment.includes(key as typeof pathEnvironment[number])
+      ? entry.slice(separator + 1) : entry.length > separator + 1 ? 'present' : '';
+  }
+  return selected;
+};
+
+const processViewPath = (absolutePath: string, processRoot?: string): string => {
+  if (!plugins.path.isAbsolute(absolutePath)
+    || plugins.path.normalize(absolutePath) !== absolutePath) {
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
+  }
+  return processRoot ? plugins.path.join(processRoot, absolutePath.slice(1)) : absolutePath;
+};
+
+/** 2.1.273's `le` / `dse` / `H` selector in the installed bundle, offset 190076222. */
+const assertNoKnownNativeLoginOverride = (env: NodeJS.ProcessEnv, processRoot?: string): void => {
+  for (const key of CREDENTIAL_OVERRIDES) {
+    if (env[key]) throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+  }
+  const configDir = env.ANTHROPIC_CONFIG_DIR?.trim()
+    || (env.XDG_CONFIG_HOME?.trim()
+      ? plugins.path.join(env.XDG_CONFIG_HOME.trim(), 'anthropic')
+      : env.HOME?.trim() ? plugins.path.join(env.HOME.trim(), '.config', 'anthropic') : null);
+  if (configDir === null) return;
+  if (!plugins.path.isAbsolute(configDir) || plugins.path.normalize(configDir) !== configDir) {
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('profile_unreadable');
+  }
+  let selected = 'default';
+  try {
+    selected = readNativeRaw(processViewPath(plugins.path.join(configDir, 'active_config'), processRoot))?.trim() || 'default';
+    // The vendor's profile resolver otherwise forms `configs/${selected}.json` directly.
+    if (!/^[A-Za-z0-9._-]+$/.test(selected) || selected === '.' || selected === '..') {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('profile_unreadable');
+    }
+    plugins.fs.lstatSync(processViewPath(plugins.path.join(configDir, 'configs', `${selected}.json`), processRoot));
+  } catch (error) {
+    if (error instanceof ClaudeNativeEffectiveAuthUnsupportedError) throw error;
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return;
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('profile_unreadable');
+  }
+  // Even an implicit user_oauth profile is refused: its credential source is outside this journal.
+  throw new ClaudeNativeEffectiveAuthUnsupportedError('profile');
+};
+
+const assertNativeHome = (env: NodeJS.ProcessEnv, configDir: string): void => {
+  const selected = env.CLAUDE_CONFIG_DIR?.trim()
+    || (env.HOME?.trim() ? plugins.path.join(env.HOME.trim(), '.claude') : null);
+  if (!selected || !plugins.path.isAbsolute(selected) || plugins.path.normalize(selected) !== configDir) {
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+  }
+};
+
+const selectedNativeConfigParent = (env: NodeJS.ProcessEnv): string | null =>
+  env.CLAUDE_CONFIG_DIR?.trim() || env.HOME?.trim() || null;
+
+const assertSettingsSelectNative = (file: string): void => {
+  let raw: string | null;
+  try { raw = readNativeRaw(file); }
+  catch { throw new ClaudeNativeEffectiveAuthUnsupportedError('settings'); }
+  if (raw === null) return;
+  let settings: Record<string, unknown>;
+  try { settings = document(raw); }
+  catch { throw new ClaudeNativeEffectiveAuthUnsupportedError('settings'); }
+  if (text(settings.apiKeyHelper) || settings.forceLoginMethod || settings.forceLoginGatewayUrl) {
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+  }
+  if (settings.env !== undefined) {
+    if (!isRecord(settings.env)) throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+    for (const key of contextKeys) {
+      if (settings.env[key]) throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+    }
+  }
+};
+
+const assertNoManagedAuthSource = (root: string): void => {
+  try {
+    plugins.fs.lstatSync(plugins.path.join(root, 'managed-settings.json'));
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+  } catch (error) {
+    if (error instanceof ClaudeNativeEffectiveAuthUnsupportedError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+    }
+  }
+  try {
+    if (plugins.fs.readdirSync(plugins.path.join(root, 'managed-settings.d'))
+      .some(name => !name.startsWith('.') && name.endsWith('.json'))) {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+    }
+  } catch (error) {
+    if (error instanceof ClaudeNativeEffectiveAuthUnsupportedError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('settings');
+    }
+  }
+};
+
+const assertProjectSettingsSelectNative = (cwd: string, processRoot?: string): void => {
+  for (let directory = cwd;; directory = plugins.path.dirname(directory)) {
+    for (const name of ['settings.json', 'settings.local.json']) {
+      assertSettingsSelectNative(processViewPath(plugins.path.join(directory, '.claude', name), processRoot));
+    }
+    if (plugins.path.dirname(directory) === directory) break;
+  }
+};
+
+/** Read native files without following a replacement symlink or accepting an unbounded/partial file. */
+const readNativeBytes = (file: string): Buffer | null => {
+  let descriptor: number | undefined;
+  try {
+    descriptor = plugins.fs.openSync(file,
+      plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NONBLOCK | plugins.fs.constants.O_NOFOLLOW);
+    const stat = plugins.fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > MAX_NATIVE_FILE_BYTES || stat.uid !== process.getuid?.()) {
+      throw new Error('Native Claude credential file is not a bounded owner-only regular file.');
+    }
+    const buffer = Buffer.alloc(MAX_NATIVE_FILE_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const count = plugins.fs.readSync(descriptor, buffer, length, buffer.length - length, null);
+      if (count === 0) break;
+      length += count;
+    }
+    if (length === buffer.length) throw new Error('Native Claude credential file exceeds the supported size.');
+    // Keep the original bytes: TextDecoder accepts a BOM but strips it from text.
+    const bytes = buffer.subarray(0, length);
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    return bytes;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error('Native Claude credential file is unreadable or changed; no new credential was written.');
+  } finally {
+    if (descriptor !== undefined) plugins.fs.closeSync(descriptor);
+  }
+};
+
+const decodeNativeRaw = (bytes: Uint8Array | null): string | null => bytes === null ? null
+  : new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+const readNativeRaw = (file: string): string | null => decodeNativeRaw(readNativeBytes(file));
+
+const document = (raw: Uint8Array | string | null): Record<string, unknown> => {
+  if (raw === null) return {};
+  try {
+    const value: unknown = JSON.parse(typeof raw === 'string' ? raw : decodeNativeRaw(raw)!);
+    if (isRecord(value)) return value;
+  } catch { /* Report one fixed, secret-free error. */ }
+  throw new Error('Native Claude credential file is incomplete or malformed.');
+};
+
+const validatedLogin = (credential: Record<string, unknown>, config: Record<string, unknown>): {
+  login: IClaudeNativeLogin | null; identity: IClaudeNativeIdentity | null;
+} => {
+  if (text(config.primaryApiKey)) {
+    // 2.1.273 `qh` / `lge` reads this /login-managed API key before subscriber OAuth.
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+  }
+  const oauthValue = credential.claudeAiOauth;
+  const accountValue = config.oauthAccount;
+  if (oauthValue === undefined && accountValue === undefined) return { login: null, identity: null };
+  if (!isRecord(oauthValue) || !isRecord(accountValue)
+    || !text(oauthValue.accessToken) || !text(oauthValue.refreshToken)
+    || typeof oauthValue.expiresAt !== 'number' || !Number.isFinite(oauthValue.expiresAt)
+    || !Array.isArray(oauthValue.scopes) || !oauthValue.scopes.every(scope => typeof scope === 'string')
+    || !text(accountValue.accountUuid) || !text(accountValue.organizationUuid)) {
+    throw new Error('Native Claude login or account metadata is incomplete.');
+  }
+  // `Sc` / `CO` and the full native subscription gate in 2.1.273 require these fields.
+  if (!oauthValue.scopes.includes('user:inference')
+    || (oauthValue.subscriptionType !== 'pro' && oauthValue.subscriptionType !== 'max')) {
+    throw new ClaudeNativeEffectiveAuthUnsupportedError('subscription');
+  }
+  return {
+    login: { claudeAiOauth: structuredClone(oauthValue), oauthAccount: structuredClone(accountValue) },
+    identity: { accountUuid: accountValue.accountUuid, organizationUuid: accountValue.organizationUuid },
+  };
+};
+
+const readPair = (credentialFile: string, configFile: string): {
+  credentialRaw: Buffer | null; configRaw: Buffer | null;
+} => ({ credentialRaw: readNativeBytes(credentialFile), configRaw: readNativeBytes(configFile) });
+
+const sameRaw = (left: Buffer | null, right: Buffer | null): boolean =>
+  left === null ? right === null : right !== null && left.equals(right);
+
+const samePair = (left: ReturnType<typeof readPair>, right: ReturnType<typeof readPair>): boolean =>
+  sameRaw(left.credentialRaw, right.credentialRaw) && sameRaw(left.configRaw, right.configRaw);
+
+const digests = (pair: ReturnType<typeof readPair>): IClaudeNativeDigests => ({
+  credentialDigest: pair.credentialRaw === null ? null : hash(pair.credentialRaw),
+  configDigest: pair.configRaw === null ? null : hash(pair.configRaw),
+});
+
+const directoryIdentity = (directory: string): IClaudeNativeDirectoryIdentity => {
+  const stat = plugins.fs.statSync(directory, { bigint: true });
+  if (!stat.isDirectory()) throw new Error('Claude native home is not a directory.');
+  return { device: stat.dev, inode: stat.ino };
+};
+
+const sameDirectory = (left: IClaudeNativeDirectoryIdentity, right: IClaudeNativeDirectoryIdentity): boolean =>
+  left.device === right.device && left.inode === right.inode;
+
+const processHasExited = (pid: number): boolean => {
+  try { process.kill(pid, 0); return false; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'ESRCH'; }
+};
+
+/** Default probe is conservative: every same-user Claude executable must prove the pinned release. */
+class ClaudeNativeVersionProbe implements IClaudeNativeVersionProbe {
+  constructor(private readonly executable: string) {}
+
+  public installedVersion(): string {
+    try {
+      const output = plugins.childProcess.execFileSync(this.executable, ['--version'], {
+        encoding: 'utf8', timeout: 5_000, maxBuffer: 1024, windowsHide: true,
+      }).trim();
+      const matched = /^(\d+\.\d+\.\d+) \(Claude Code\)$/.exec(output);
+      return matched?.[1] ?? 'unknown';
+    } catch { return 'unknown'; }
+  }
+
+  public runningContexts(): readonly IClaudeNativeRunningContext[] {
+    const contexts: IClaudeNativeRunningContext[] = [];
+    // Keep candidates from every mount namespace: a bind mount can expose the same inode.
+    const candidates = new HarnessProcesses('claude').list();
+    for (const running of candidates) {
+      let version: string | null = null;
+      let env: NodeJS.ProcessEnv | null = null;
+      let cwd: string | null = null;
+      let hasSettingsOverride: boolean | null = null;
+      let nativeHomeIdentity: IClaudeNativeDirectoryIdentity | null = null;
+      let configParentIdentity: IClaudeNativeDirectoryIdentity | null = null;
+      let mountNamespace: string | null = null;
+      let processRoot: string | null = null;
+      try {
+        const executable = plugins.fs.readlinkSync(`/proc/${running.pid}/exe`);
+        version = /(?:\/claude\/versions\/|\/remote\/ccd-cli\/)(\d+\.\d+\.\d+)$/.exec(executable)?.[1] ?? null;
+        mountNamespace = plugins.fs.readlinkSync(`/proc/${running.pid}/ns/mnt`);
+        env = selectorEnvironment(readProcessContext(`/proc/${running.pid}/environ`));
+        cwd = plugins.fs.readlinkSync(`/proc/${running.pid}/cwd`);
+        processRoot = `/proc/${running.pid}/root`;
+        if (!plugins.path.isAbsolute(cwd) || !sameDirectory(
+          directoryIdentity(`/proc/${running.pid}/cwd`),
+          directoryIdentity(processViewPath(cwd, processRoot)))) {
+          throw new Error('Claude process working directory cannot be resolved in its mount namespace.');
+        }
+        const selectedHome = env.CLAUDE_CONFIG_DIR?.trim()
+          || (env.HOME?.trim() ? plugins.path.join(env.HOME.trim(), '.claude') : null);
+        if (!selectedHome) throw new Error('Claude process native home is unknown.');
+        if (plugins.path.isAbsolute(selectedHome)
+          && plugins.path.normalize(selectedHome) !== selectedHome) {
+          throw new Error('Claude process native home path is ambiguous.');
+        }
+        const processHome = plugins.path.isAbsolute(selectedHome)
+          ? processViewPath(selectedHome, processRoot)
+          // Preserve the proc magic symlink before `..` is resolved by the target's VFS.
+          : `/proc/${running.pid}/cwd/${selectedHome}`;
+        nativeHomeIdentity = directoryIdentity(processHome);
+        const selectedConfigParent = selectedNativeConfigParent(env);
+        if (!selectedConfigParent) throw new Error('Claude process config parent is unknown.');
+        const processConfigParent = plugins.path.isAbsolute(selectedConfigParent)
+          ? processViewPath(selectedConfigParent, processRoot)
+          : `/proc/${running.pid}/cwd/${selectedConfigParent}`;
+        configParentIdentity = directoryIdentity(processConfigParent);
+        const argv = readProcessContext(`/proc/${running.pid}/cmdline`).split('\0').filter(Boolean);
+        hasSettingsOverride = argv.some(arg => ['--settings', '--managed-settings', '--setting-sources', '--bare'].some(
+          flag => arg === flag || arg.startsWith(`${flag}=`)));
+      } catch {
+        // A vanished process no longer owns a grant; an unreadable live candidate is ambiguous.
+        if (processHasExited(running.pid)) continue;
+      }
+      contexts.push({ version, env, cwd, hasSettingsOverride, nativeHomeIdentity,
+        configParentIdentity, mountNamespace, processRoot });
+    }
+    return contexts;
+  }
+}
+
+/** Explicitly limited to Claude Code's installed 2.1.273 Linux native-file contract. */
+export class ClaudeNativeAdapter {
+  private readonly credentialFile: string;
+  private readonly locks: ClaudeCodeLocks;
+  private readonly versionProbe: IClaudeNativeVersionProbe;
+  private readonly fetcher: typeof fetch;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly settingsFiles: readonly string[];
+  private readonly platform: NodeJS.Platform;
+
+  constructor(private readonly options: IClaudeNativeAdapterOptions) {
+    if (!plugins.path.isAbsolute(options.configDir) || !plugins.path.isAbsolute(options.configFile)
+      || plugins.path.normalize(options.configDir) !== options.configDir
+      || plugins.path.normalize(options.configFile) !== options.configFile) {
+      throw new Error('Native Claude paths must be normalized absolute paths.');
+    }
+    if (![plugins.path.join(options.configDir, '.claude.json'),
+      plugins.path.join(plugins.os.homedir(), '.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');
+    this.locks = new ClaudeCodeLocks(options.configDir, options.configFile,
+      { timeoutMs: options.lockTimeoutMs });
+    this.versionProbe = options.versionProbe ?? new ClaudeNativeVersionProbe(
+      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.platform = options.platform ?? process.platform;
+  }
+
+  private assertSupported(): number {
+    if (this.platform !== 'linux') throw new Error('Native Claude handoff requires the verified Linux file backend.');
+    const home = plugins.fs.lstatSync(this.options.configDir);
+    if (!home.isDirectory() || home.isSymbolicLink() || home.uid !== process.getuid?.()
+      || plugins.fs.realpathSync(this.options.configDir) !== this.options.configDir) {
+      throw new Error('Native Claude home must be a real directory owned by this user.');
+    }
+    const configParent = plugins.path.dirname(this.options.configFile);
+    const parent = plugins.fs.lstatSync(configParent);
+    if (!parent.isDirectory() || parent.isSymbolicLink() || parent.uid !== process.getuid?.()
+      || plugins.fs.realpathSync(configParent) !== configParent) {
+      throw new Error('Native Claude account metadata parent must be a real directory owned by this user.');
+    }
+    assertNoKnownNativeLoginOverride(this.env);
+    assertNativeHome(this.env, this.options.configDir);
+    const daemonConfigParent = selectedNativeConfigParent(this.env);
+    if (!daemonConfigParent || !plugins.path.isAbsolute(daemonConfigParent)
+      || plugins.path.join(daemonConfigParent, '.claude.json') !== this.options.configFile) {
+      throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+    }
+    assertNoManagedAuthSource(this.options.managedSettingsDirectory ?? '/etc/claude-code');
+    for (const file of this.settingsFiles) {
+      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.`);
+    }
+    let runningSessions = 0;
+    const nativeHomeIdentity = directoryIdentity(this.options.configDir);
+    const configParentIdentity = directoryIdentity(configParent);
+    for (const running of this.versionProbe.runningContexts()) {
+      if (!running.nativeHomeIdentity) {
+        throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
+      }
+      if (!sameDirectory(running.nativeHomeIdentity, nativeHomeIdentity)) continue;
+      if (!running.configParentIdentity
+        || !sameDirectory(running.configParentIdentity, configParentIdentity)) {
+        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.`);
+      }
+      if (!running.env || !running.cwd || running.hasSettingsOverride === null
+        || !running.mountNamespace || !running.processRoot) {
+        throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
+      }
+      if (running.hasSettingsOverride) throw new ClaudeNativeEffectiveAuthUnsupportedError('override');
+      assertNoKnownNativeLoginOverride(running.env, running.processRoot);
+      assertNoManagedAuthSource(processViewPath(
+        this.options.managedSettingsDirectory ?? '/etc/claude-code', running.processRoot));
+      assertProjectSettingsSelectNative(running.cwd, running.processRoot);
+      runningSessions++;
+    }
+    return runningSessions;
+  }
+
+  /** The caller keeps its SmartData journal and both ownership transactions inside this callback. */
+  public async withExclusiveHome<T>(action: (session: IClaudeNativeLockedSession) => Promise<T>): Promise<T> {
+    this.assertSupported();
+    return this.locks.holdAsync(async lease => {
+      this.assertSupported();
+      const session = new ClaudeNativeLockedSession(this.credentialFile, this.options.configFile,
+        this.fetcher, lease, () => this.assertSupported());
+      const firstSnapshot = session.readStable();
+      const result = await action(session);
+      try {
+        lease.assertHeld();
+        const afterRunningSessions = this.assertSupported();
+        if (firstSnapshot.runningEffectiveAuth === 'no_scoped_sessions' && afterRunningSessions > 0) {
+          throw new ClaudeNativeEffectiveAuthUnsupportedError('running_session');
+        }
+      } catch {
+        // The caller may already have committed a journal or changed one native file.
+        throw new ClaudeCodeLockOutcomeUnknownError(true);
+      }
+      return result;
+    });
+  }
+}
+
+class ClaudeNativeLockedSession implements IClaudeNativeLockedSession {
+  constructor(private readonly credentialFile: string, private readonly configFile: string,
+    private readonly fetcher: typeof fetch, private readonly lease: IClaudeCodeLockLease,
+    private readonly assertSupported: () => number) {}
+
+  private observation(): IClaudeNativeDigests | null {
+    try { return digests(readPair(this.credentialFile, this.configFile)); }
+    catch { return null; }
+  }
+
+  public readStable(): IClaudeNativeSnapshot {
+    this.lease.assertHeld();
+    const runningSessions = this.assertSupported();
+    let lastError: unknown;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        const before = readPair(this.credentialFile, this.configFile);
+        const credential = document(before.credentialRaw);
+        const config = document(before.configRaw);
+        const observed = validatedLogin(credential, config);
+        const after = readPair(this.credentialFile, this.configFile);
+        if (samePair(before, after)) {
+          this.lease.assertHeld();
+          return { ...digests(after), ...observed,
+            runningEffectiveAuth: runningSessions === 0 ? 'no_scoped_sessions' : 'unsupported_effective_auth' };
+        }
+      } catch (error) {
+        if (error instanceof ClaudeCodeLockOutcomeUnknownError) throw error;
+        lastError = error;
+      }
+      if (attempt < 4) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+    if (lastError instanceof ClaudeNativeEffectiveAuthUnsupportedError) throw lastError;
+    throw new Error(lastError instanceof Error ? lastError.message
+      : 'Native Claude files changed while being read; no credential was written.');
+  }
+
+  public async verifyProfileIdentity(snapshot: IClaudeNativeSnapshot,
+    expected: IClaudeNativeIdentity): Promise<IClaudeNativeProfileProof> {
+    this.lease.assertHeld();
+    this.assertSupported();
+    const token = snapshot.login?.claudeAiOauth.accessToken;
+    if (!text(token) || !snapshot.identity || !sameIdentity(snapshot.identity, expected)) {
+      throw new Error('Native Claude login identity differs from the selected account.');
+    }
+    const response = await claudeRequest(this.fetcher, {
+      url: 'https://api.anthropic.com/api/oauth/profile', method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', 'Cache-Control': 'no-cache' },
+      subject: 'Claude account', timeoutMs: PROFILE_TIMEOUT_MS, now: Date.now,
+    });
+    this.lease.assertHeld();
+    const current = this.observation();
+    if (!current || !sameDigests(current, snapshot)) {
+      throw new Error('Native Claude login changed during provider identity verification.');
+    }
+    if (response.status !== 200 || !isRecord(response.body)
+      || !isRecord(response.body.account) || !isRecord(response.body.organization)
+      || response.body.account.uuid !== expected.accountUuid
+      || response.body.organization.uuid !== expected.organizationUuid) {
+      throw new Error('Claude account profile did not verify the selected immutable identity.');
+    }
+    return { ...expected, accessTokenDigest: hash(token) };
+  }
+
+  public async prepareWrite(input: { expected: IClaudeNativeDigests;
+    expectedSourceIdentity: IClaudeNativeIdentity | null; targetLogin: IClaudeNativeLogin;
+    expectedIdentity: IClaudeNativeIdentity }): Promise<TClaudeNativePrepareResult> {
+    this.lease.assertHeld();
+    this.assertSupported();
+    let before: IClaudeNativeSnapshot;
+    try { before = this.readStable(); }
+    catch { return { kind: 'not_written', reason: 'source_unreadable', observed: this.observation() }; }
+    if (!sameDigests(before, input.expected)) {
+      return { kind: 'not_written', reason: 'source_changed', observed: onlyDigests(before) };
+    }
+    if (input.expectedSourceIdentity === null ? before.identity !== null
+      : before.identity === null || !sameIdentity(before.identity, input.expectedSourceIdentity)) {
+      return { kind: 'not_written', reason: 'source_identity_mismatch', observed: onlyDigests(before) };
+    }
+    let target: ReturnType<typeof validatedLogin>;
+    try {
+      target = validatedLogin({ claudeAiOauth: input.targetLogin.claudeAiOauth },
+        { oauthAccount: input.targetLogin.oauthAccount });
+    } catch {
+      return { kind: 'not_written', reason: 'target_unverified', observed: onlyDigests(before) };
+    }
+    if (!target.login || !target.identity || !sameIdentity(target.identity, input.expectedIdentity)) {
+      return { kind: 'not_written', reason: 'target_unverified', observed: onlyDigests(before) };
+    }
+    let profile: IClaudeNativeProfileProof;
+    try {
+      profile = await this.verifyProfileIdentity({ ...before, ...target }, input.expectedIdentity);
+    } catch {
+      this.lease.assertHeld();
+      this.assertSupported();
+      const observed = this.observation();
+      if (!observed) return { kind: 'not_written', reason: 'source_unreadable', observed: null };
+      if (!sameDigests(observed, input.expected)) {
+        return { kind: 'not_written', reason: 'source_changed', observed };
+      }
+      return { kind: 'not_written', reason: 'target_unverified', observed: onlyDigests(before) };
+    }
+    const current = this.observation();
+    if (!current || !sameDigests(current, input.expected)) {
+      return { kind: 'not_written', reason: 'source_changed', observed: current };
+    }
+    this.lease.assertHeld();
+    this.assertSupported();
+    let original: ReturnType<typeof readPair>;
+    try { original = readPair(this.credentialFile, this.configFile); }
+    catch { return { kind: 'not_written', reason: 'source_unreadable', observed: this.observation() }; }
+    if (!sameDigests(digests(original), input.expected)) {
+      return { kind: 'not_written', reason: 'source_changed', observed: digests(original) };
+    }
+    const credential = document(original.credentialRaw);
+    const config = document(original.configRaw);
+    const nextCredential = { ...credential, claudeAiOauth: target.login.claudeAiOauth };
+    const nextConfig: Record<string, unknown> = { ...config, oauthAccount: target.login.oauthAccount };
+    for (const key of ACCOUNT_CACHES) delete nextConfig[key];
+    const credentialRaw = JSON.stringify(nextCredential, null, 2) + '\n';
+    const configRaw = JSON.stringify(nextConfig, null, 2) + '\n';
+    if (Buffer.byteLength(credentialRaw) > MAX_NATIVE_FILE_BYTES
+      || Buffer.byteLength(configRaw) > MAX_NATIVE_FILE_BYTES) {
+      return { kind: 'not_written', reason: 'target_oversized', observed: onlyDigests(before) };
+    }
+    const plan: IClaudeNativePreparedWrite = Object.freeze({
+      before: Object.freeze(onlyDigests(input.expected)),
+      after: Object.freeze(digests({ credentialRaw: Buffer.from(credentialRaw), configRaw: Buffer.from(configRaw) })),
+      sourceIdentity: input.expectedSourceIdentity === null ? null : Object.freeze({ ...input.expectedSourceIdentity }),
+      targetIdentity: Object.freeze({ ...input.expectedIdentity }),
+      profile: Object.freeze({ ...profile }),
+    });
+    preparedWrites.set(plan, { session: this, credentialRaw, configRaw,
+      originalConfigRaw: original.configRaw, targetAccessToken: String(target.login.claudeAiOauth.accessToken) });
+    return { kind: 'prepared', plan };
+  }
+
+  public exportPreparedSource(plan: IClaudeNativePreparedWrite): IClaudeNativePreparedSource {
+    this.lease.assertHeld();
+    this.assertSupported();
+    const prepared = preparedWrites.get(plan);
+    if (!prepared || prepared.session !== this) throw new Error('Claude native write plan is not held by this lease.');
+    const stable = this.readStable();
+    if (!sameDigests(stable, plan.before)
+      || (plan.sourceIdentity === null ? stable.identity !== null
+        : stable.identity === null || !sameIdentity(stable.identity, plan.sourceIdentity))) {
+      throw new Error('Claude native source changed before backup export.');
+    }
+    const original = readPair(this.credentialFile, this.configFile);
+    if (!sameDigests(digests(original), plan.before)
+      || !sameRaw(original.configRaw, prepared.originalConfigRaw)) {
+      throw new Error('Claude native source changed before backup export.');
+    }
+    this.lease.assertHeld();
+    this.assertSupported();
+    return { before: Object.freeze({ ...plan.before }),
+      credentialBytes: original.credentialRaw === null ? null : Buffer.from(original.credentialRaw),
+      configBytes: original.configRaw === null ? null : Buffer.from(original.configRaw) };
+  }
+
+  public writePreparedIfCurrent(plan: IClaudeNativePreparedWrite): TClaudeNativeWriteResult {
+    this.lease.assertHeld();
+    this.assertSupported();
+    const prepared = preparedWrites.get(plan);
+    if (!prepared || prepared.session !== this) throw new Error('Claude native write plan is not held by this lease.');
+    preparedWrites.delete(plan);
+    let before: IClaudeNativeSnapshot;
+    try { before = this.readStable(); }
+    catch { return { kind: 'not_written', reason: 'source_unreadable', observed: this.observation() }; }
+    if (!sameDigests(before, plan.before)) {
+      return { kind: 'not_written', reason: 'source_changed', observed: onlyDigests(before) };
+    }
+    if (plan.sourceIdentity === null ? before.identity !== null
+      : before.identity === null || !sameIdentity(before.identity, plan.sourceIdentity)) {
+      return { kind: 'not_written', reason: 'source_identity_mismatch', observed: onlyDigests(before) };
+    }
+    let original: ReturnType<typeof readPair>;
+    try { original = readPair(this.credentialFile, this.configFile); }
+    catch { return { kind: 'not_written', reason: 'source_unreadable', observed: this.observation() }; }
+    if (!sameDigests(digests(original), plan.before)
+      || !sameRaw(original.configRaw, prepared.originalConfigRaw)) {
+      return { kind: 'not_written', reason: 'source_changed', observed: digests(original) };
+    }
+    // The first write is the uncertainty boundary; no automatic rollback can prove ownership after it.
+    try {
+      this.lease.assertHeld();
+      writeSecretFileAtomically(this.credentialFile, prepared.credentialRaw);
+      this.lease.assertHeld();
+      const middle = readPair(this.credentialFile, this.configFile);
+      if (!sameRaw(middle.credentialRaw, Buffer.from(prepared.credentialRaw))
+        || !sameRaw(middle.configRaw, original.configRaw)) {
+        return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: digests(middle) };
+      }
+      writeSecretFileAtomically(this.configFile, prepared.configRaw);
+      this.lease.assertHeld();
+      const after = readPair(this.credentialFile, this.configFile);
+      if (!sameRaw(after.credentialRaw, Buffer.from(prepared.credentialRaw))
+        || !sameRaw(after.configRaw, Buffer.from(prepared.configRaw))
+        || !sameDigests(digests(after), plan.after)) {
+        return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: digests(after) };
+      }
+      const snapshot = this.readStable();
+      if (!snapshot.login || !snapshot.identity || !sameIdentity(snapshot.identity, plan.targetIdentity)
+        || !sameDigests(snapshot, plan.after)
+        || snapshot.login.claudeAiOauth.accessToken !== prepared.targetAccessToken
+        || plan.profile.accessTokenDigest !== hash(String(snapshot.login.claudeAiOauth.accessToken))) {
+        return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: onlyDigests(snapshot) };
+      }
+      return { kind: 'written', snapshot, profile: plan.profile };
+    } catch {
+      return { kind: 'uncertain', reason: 'native_write_or_readback_failed', observed: this.observation() };
+    }
+  }
+
+  public async writeIfCurrent(input: { expected: IClaudeNativeDigests;
+    expectedSourceIdentity: IClaudeNativeIdentity | null; targetLogin: IClaudeNativeLogin;
+    expectedIdentity: IClaudeNativeIdentity }): Promise<TClaudeNativeWriteResult> {
+    const prepared = await this.prepareWrite(input);
+    return prepared.kind === 'prepared' ? this.writePreparedIfCurrent(prepared.plan) : prepared;
+  }
+}