@modelprofile.com/authswitch 8.1.0 → 9.0.0

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/classes.cli.ts

@@ -4,7 +4,7 @@ import { CodexHarness } from './classes.codexharness.js';
 import { OpenCodeHarness } from './classes.opencodeharness.js';
 import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
 import { AuthSwitchTui } from './classes.tui.js';
-import { AglAuthSwitchCoordinator, AuthSwitchOperations, authSwitchMutationReplacesLogin, type TAuthSwitchCoordinator, type TAuthSwitchMutation } from './classes.operations.js';
+import { AglAuthSwitchCoordinator, AuthSwitchOperations, authSwitchHostLegacyFence, authSwitchMutationReplacesLogin, type TAuthSwitchCoordinator, type TAuthSwitchLegacyFence, type TAuthSwitchMutation } from './classes.operations.js';
 import { readAccountList } from './classes.accountlist.js';
 import { AccountListRenderer } from './classes.listrenderer.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
@@ -98,9 +98,20 @@ export class AuthSwitchCli {
   private readonly operations: AuthSwitchOperations;
   private get out(): plugins.smartconsole.SmartConsole { return this.console ??= new plugins.smartconsole.SmartConsole(); }
 
-  constructor(harnessesArg?: IAuthHarness[] | CodexSwitcher, coordinatorArg?: TAuthSwitchCoordinator) {
+  /**
+   * `legacyFenceArg` states which authority fences the mutations of injected harnesses.
+   *
+   * With no harnesses this command line is this host's, exactly as its default harnesses and its AGL
+   * coordinator are, and it is fenced by this host's authority. Injected harnesses write whatever stores
+   * their caller chose, so -- like the coordinator -- nothing of this host is assumed for them: they are
+   * fenced only by what the caller states, and by nothing when it states nothing.
+   */
+  constructor(harnessesArg?: IAuthHarness[] | CodexSwitcher, coordinatorArg?: TAuthSwitchCoordinator,
+    legacyFenceArg?: TAuthSwitchLegacyFence) {
     const coordinator = new AglAuthSwitchCoordinator();
-    this.operations = new AuthSwitchOperations(coordinatorArg ?? (harnessesArg === undefined ? request => coordinator.coordinate(request) : undefined));
+    this.operations = new AuthSwitchOperations(
+      coordinatorArg ?? (harnessesArg === undefined ? request => coordinator.coordinate(request) : undefined),
+      legacyFenceArg ?? (harnessesArg === undefined ? authSwitchHostLegacyFence() : 'none'));
     harnessesArg ??= [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()];
     // Preserve the published single-Codex constructor at the composition boundary.
     const harnesses = Array.isArray(harnessesArg) ? harnessesArg : [new CodexHarness(harnessesArg)];

package/ts/classes.codexmanaged.ts

@@ -28,6 +28,15 @@ export interface IAuthSwitchCodexInteractiveCommand {
   env: NodeJS.ProcessEnv;
 }
 
+/**
+ * The one Codex release whose app-server contract managed Codex was verified against: the
+ * external-token login and its refresh callback, thread/turn start and resume, `--listen` and
+ * how it publishes that socket, `--strict-config`, the ephemeral credential store and
+ * `--remote`. Both the CLI and the app-server it serves must report exactly this release;
+ * any other is refused unverified.
+ */
+export const MANAGED_CODEX_VERSION = '0.157.0';
+
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
 const isAlive = (child: plugins.childProcess.ChildProcess): boolean => child.exitCode === null && child.signalCode === null;
@@ -162,7 +171,9 @@ export class AuthSwitchManagedCodex {
         else resolve(stdout.trim());
       });
     });
-    if (output !== 'codex-cli 0.155.1') throw new Error('Managed Codex requires verified codex-cli 0.155.1.');
+    if (output !== `codex-cli ${MANAGED_CODEX_VERSION}`) {
+      throw new Error(`Managed Codex requires verified codex-cli ${MANAGED_CODEX_VERSION}.`);
+    }
   }
 
   public start(): Promise<void> {
@@ -202,6 +213,9 @@ export class AuthSwitchManagedCodex {
       if (this.closed) throw new Error('Managed Codex startup was cancelled.');
       this.workspaceId = initial.accountId;
       this.grantedGeneration = initial.grantGeneration;
+      // Codex binds the socket elsewhere and publishes this path as an alias; deriving where
+      // proves the host can verify that alias before any run is recorded or process started.
+      await plugins.crossharness.codexUnixSocketTarget(this.socketPath);
       await this.options.onPreparedRun(this.socketPath);
       if (this.closed) throw new Error('Managed Codex startup was cancelled.');
       const child = plugins.childProcess.spawn(this.options.executable ?? 'codex', [
@@ -226,11 +240,7 @@ export class AuthSwitchManagedCodex {
       while (true) {
         if (this.closed) throw new Error('Managed Codex startup was cancelled.');
         if (!isAlive(child)) throw new Error('Managed Codex app-server exited before accepting connections.');
-        try {
-          if ((await plugins.fs.promises.lstat(this.socketPath)).isSocket()) break;
-        } catch (error) {
-          if (!isRecord(error) || error.code !== 'ENOENT') throw error;
-        }
+        if (await plugins.crossharness.observeCodexUnixSocket(this.socketPath) === 'published') break;
         if (Date.now() >= deadline) throw new Error('Managed Codex app-server socket startup timed out.');
         await wait(25);
       }
@@ -248,7 +258,8 @@ export class AuthSwitchManagedCodex {
       });
       this.client = client;
       await client.connect();
-      if (client.serverVersion !== '0.155.1') throw new Error('Managed Codex app-server version changed.');
+      // The executable can be replaced between the version probe and the spawn (Codex updates itself).
+      if (client.serverVersion !== MANAGED_CODEX_VERSION) throw new Error('Managed Codex app-server version changed.');
       const login: unknown = await client.request('account/login/start', {
         type: 'chatgptAuthTokens', accessToken: initial.accessToken, chatgptAccountId: initial.accountId,
       }, 5_000);

package/ts/classes.legacyfence.ts

@@ -0,0 +1,219 @@
+import * as plugins from './plugins.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
+import { authSwitchAuthoritySocketPaths, authSwitchAuthorityUnitDirectory,
+  authSwitchAuthorityUnitName } from './authority-paths.js';
+import { AuthSwitchClient } from './classes.authorityclient.js';
+import { StashStore } from './classes.stashstore.js';
+import { legacyHash, legacySourceId,
+  resolveLegacySourceLocations } from './ts_migration/legacysources/shared.js';
+import type { TAuthSwitchMutation } from './mutation.js';
+import type { IAuthHarness } from './interfaces.harness.js';
+
+/**
+ * The gate between the legacy credential commands and an account the authority has taken over.
+ *
+ * An import is a transfer of ownership, not a copy: the moment the authority refreshes an adopted login,
+ * the legacy saved copy holds a refresh token the provider has already rotated away. Writing that copy back
+ * into a native store -- which is what the legacy `save` and `switch` do -- would hand a tool a credential
+ * that is dead, and the owner would learn it from the tool rather than from here. This is the one place
+ * that stops it, and it stops it for the hosted service too, because `runAuthSwitchMutation` is the
+ * chokepoint both the command line and `AuthSwitchService` pass through.
+ *
+ * An authority that answers decides from its migration ledger alone. The ledger names a source by the hash
+ * of its own path, which is exactly what the legacy side can compute for the record it is about to touch, so
+ * no account identity has to be mapped between the two worlds: the legacy account id names a file, the file
+ * names a row, and the row says whether the authority took it. One that does not answer is decided by
+ * whether its service unit is installed (`authorityUnitInstalled`).
+ */
+
+/** Where a fence looks: this host's legacy stores and this host's authority, both stated by the caller. */
+export interface IAuthSwitchLegacyFenceLocations {
+  env: NodeJS.ProcessEnv;
+  homeDirectory: string;
+}
+
+/**
+ * What a caller states, exactly as a daemon states where it reads the legacy stores.
+ *
+ * `'none'` is for a caller that is not this host's own credential tooling -- a fixture, or a harness test
+ * that owns no authority -- and it is stated rather than defaulted, because a fence that silently pointed
+ * at `process.env` from inside a test would read whichever host ran it.
+ */
+export type TAuthSwitchLegacyFence = IAuthSwitchLegacyFenceLocations | 'none';
+
+/**
+ * This host's own locations, for a caller whose harnesses are this host's own.
+ *
+ * `AuthSwitchCli` and `AuthSwitchService` use it when they compose their harnesses from this process's
+ * environment, and a host that composes them the same way -- AGL -- states it explicitly. A fence that named
+ * anything else would be fencing other stores than the ones those harnesses write. Everything below them --
+ * `AuthSwitchOperations`, `runAuthSwitchMutation` -- takes it as an argument, so no library path can pick
+ * up a host it was never given.
+ */
+export const authSwitchHostLegacyFence = (): IAuthSwitchLegacyFenceLocations =>
+  ({ env: process.env, homeDirectory: plugins.os.homedir() });
+
+const fenceRequired = 'An authswitch account mutation requires stated legacy fence locations: pass an env '
+  + 'and an absolute homeDirectory, or "none" for a caller that owns no authority.';
+
+/** The same check for a caller with types and one without. */
+export function assertStatedLegacyFence(value: unknown): asserts value is TAuthSwitchLegacyFence {
+  if (value === 'none') return;
+  if (value === null || typeof value !== 'object'
+    || typeof (value as { env?: unknown }).env !== 'object' || (value as { env?: unknown }).env === null
+    || typeof (value as { homeDirectory?: unknown }).homeDirectory !== 'string'
+    || !plugins.path.isAbsolute((value as { homeDirectory: string }).homeDirectory)) {
+    throw new Error(fenceRequired);
+  }
+}
+
+/**
+ * What the owner is told. Neither names a path, an id or a host; each names the command that helps.
+ *
+ * There is no authority command that activates a login in a native store, and that is the point: a login
+ * the authority holds is used by binding a runtime to it, which is what AGL does, so the instruction names
+ * the read that shows it rather than inventing a replacement for `switch`.
+ */
+const authorityHoldsLogin = 'The account authority holds this login now: its legacy saved copy is stale, '
+  + 'so the legacy save and switch no longer apply to it. "authswitch account list" shows the account; a '
+  + 'runtime uses it by binding to it through the authority.';
+const authorityUnavailable = 'This host has an account authority and it is not answering, so whether it '
+  + 'holds this login cannot be known. Start it with "authswitch authority service start" and run this '
+  + 'again.';
+
+/** A settled row is one whose source was taken over. Both statuses mean the legacy copy is finished. */
+const settled = new Set(['verified', 'complete']);
+
+/** How long the gate may wait on the authority before a mutation is refused rather than delayed. */
+const ASK_TIMEOUT_MS = 4_000;
+
+/**
+ * The legacy store paths one mutation would read or write, as the migration readers name them.
+ *
+ * Codex keeps a stash directory per account, Claude and OpenCode a record file per account, and the reader
+ * of each derives its ledger row from that exact path (`ts_migration/legacysources/authswitchstores.ts`).
+ * Only the account the mutation names is looked up: a switch also re-saves the outgoing login, but writing
+ * a record rotates nothing, while activating one is the write this fence exists for.
+ */
+const mutationSourcePaths = (root: string, harnessId: string, accountId: string): string[] => {
+  if (harnessId === 'codex') {
+    try { return [new StashStore('codex', root).entryDir(accountId)]; }
+    // An account id no stash name can be derived from names no stash, and therefore no ledger row.
+    catch { return []; }
+  }
+  if (harnessId === 'claude' || harnessId === 'opencode') {
+    return /^[a-f0-9]{64}$/.test(accountId)
+      ? [plugins.path.join(root, harnessId, `${accountId}.json`)] : [];
+  }
+  // A harness this package never wrote a legacy store for has no legacy copy to strand.
+  return [];
+};
+
+/** Which account a mutation touches. A save without one saves whatever login is active right now. */
+const mutationAccountId = async (harness: IAuthHarness,
+  mutation: TAuthSwitchMutation): Promise<string | null> => {
+  if (mutation.accountId !== undefined) return mutation.accountId;
+  if (mutation.action !== 'save') return null;
+  const state = await harness.readState();
+  return state.accounts.find(account => account.isActive)?.id ?? null;
+};
+
+/** What the legacy source a mutation names looks like to an authority that answers. */
+type TLedgerAnswer = 'settled' | 'not_settled' | 'no_answer';
+
+/**
+ * One bounded, paged read of the ledger over the management socket: credential-free, and it reaches no
+ * legacy store. Anything but a complete answer -- no runtime directory, no socket, a socket that never
+ * answers within the bound, a daemon that serves no import status -- is `no_answer`, never "nothing held".
+ */
+const askLedger = async (env: NodeJS.ProcessEnv, sourceIds: ReadonlySet<string>): Promise<TLedgerAnswer> => {
+  // Only the stated environment names a socket, and nothing else decides which one: the full path resolver
+  // defaults an absent directory to this process's own and reads this process's home and XDG_DATA_HOME for
+  // the store, so a value there would silence an authority that answers.
+  if (!env.XDG_RUNTIME_DIR) return 'no_answer';
+  let client: AuthSwitchClient;
+  try {
+    const paths = authSwitchAuthoritySocketPaths(env.XDG_RUNTIME_DIR);
+    client = new AuthSwitchClient(paths.authoritySocketPath, paths.runtimeSocketPath);
+  } catch { return 'no_answer'; }
+  const deadline = AbortSignal.timeout(ASK_TIMEOUT_MS);
+  let after: string | undefined;
+  try {
+    while (true) {
+      const page = await client.importStatus({ after, limit: 128 }, deadline);
+      if (page.entries.some(entry => sourceIds.has(entry.sourceId) && settled.has(entry.status))) return 'settled';
+      if (!page.nextCursor) return 'not_settled';
+      after = page.nextCursor;
+    }
+  } catch { return 'no_answer'; }
+};
+
+const unitUnreadable = 'The authswitch authority service unit could not be inspected, so whether an account '
+  + 'authority is installed here cannot be known; the legacy save and switch refuse until it can.';
+
+/**
+ * Whether this user has the authority's service unit installed: the durable evidence that an authority
+ * exists here even while it is not running.
+ *
+ * The unit is what `authswitch authority service install` writes, in the directory
+ * `authSwitchAuthorityUnitDirectory` derives from the caller's stated locations, and it survives a reboot --
+ * the management socket does not: it lives on tmpfs and is absent after every boot until the service
+ * starts. It is read through smartdaemon's own `SystemdUnitFile.inspect()`, which checks the exact file the
+ * installer writes and reads nothing else; its content is a service definition, never a credential.
+ *
+ * The read needs no login session. `inspect()` reads only the unit directory, so the fence hands smartdaemon
+ * no runtime directory: the stated one belongs to the ledger ask above, and passing it here would let a value
+ * this read never uses refuse the command. The answer therefore depends on the stated unit directory alone,
+ * and a cron job or a plain ssh command -- no `XDG_RUNTIME_DIR` at all -- is decided exactly like a session.
+ *
+ * smartdaemon agrees: with an explicit unit directory it validates only that directory at construction, and
+ * `inspect()` never reads this process's `XDG_RUNTIME_DIR`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME` or home, so
+ * none of them can change the answer.
+ *
+ * systemd is the only installer this package has, so on another platform no unit can be installed. Any
+ * failure to inspect it -- an unsafe or changed file, a directory another user can write -- is not an answer,
+ * and refuses. So does a stated unit directory that cannot be derived or that smartdaemon refuses to
+ * construct the read from (a relative or malformed stated `XDG_DATA_HOME`): the stated locations then name no
+ * directory to look in, an installer running with well-formed locations may have written the unit elsewhere,
+ * and reading that as "no authority here" would be a guess.
+ */
+const authorityUnitInstalled = async (fence: IAuthSwitchLegacyFenceLocations): Promise<boolean> => {
+  if (process.platform !== 'linux') return false;
+  // One catch covers derivation, construction and inspection: each failure leaves the same question open.
+  try {
+    const unitFile = new plugins.smartdaemon.SystemdUnitFile({ unitName: authSwitchAuthorityUnitName,
+      scope: 'user', unitDirectory: authSwitchAuthorityUnitDirectory(fence.env, fence.homeDirectory) });
+    return await unitFile.inspect() !== null;
+  } catch { throw new Error(unitUnreadable); }
+};
+
+/**
+ * The gate itself: allow, or refuse with the reason.
+ *
+ * An authority that answers decides, whether or not its unit is installed: its ledger is the only record
+ * of what it took over. One that does not answer is unknown -- and unknown is never idle -- but only where
+ * an authority is installed at all; a host without the unit is known to hold nothing, and it is every host
+ * before the cutover. The evidence cannot tell which stores an installed authority imports from, so while it
+ * is stopped it refuses the legacy save and switch of every store, until it runs again.
+ */
+export const assertAuthSwitchMutationAllowed = async (fence: TAuthSwitchLegacyFence,
+  harness: IAuthHarness, mutation: TAuthSwitchMutation): Promise<void> => {
+  assertStatedLegacyFence(fence);
+  if (fence === 'none') return;
+  // A remove deletes a saved copy and writes no credential, which is why the legacy `drop` command is
+  // deliberately unfenced as well: for an adopted account that copy already holds a rotated-away token.
+  if (mutation.action !== 'save' && mutation.action !== 'switch') return;
+
+  const root = resolveLegacySourceLocations(fence.env, fence.homeDirectory).authSwitchHome;
+  const accountId = await mutationAccountId(harness, mutation);
+  const paths = accountId === null ? [] : mutationSourcePaths(root, harness.id, accountId);
+  // A mutation that names no legacy record the importer reads can never have been imported, so there is
+  // nothing to ask about, and the answer must not depend on whether an authority is up.
+  if (paths.length === 0) return;
+
+  const answer = await askLedger(fence.env,
+    new Set(paths.map(path => legacySourceId('authswitch_stash', legacyHash(path)))));
+  if (answer === 'settled') throw new AuthSwitchRefusal('authority_holds_login', authorityHoldsLogin);
+  if (answer === 'not_settled') return;
+  if (await authorityUnitInstalled(fence)) throw new AuthSwitchRefusal('authority_unavailable', authorityUnavailable);
+};

package/ts/classes.operations.ts

@@ -1,6 +1,8 @@
 import * as plugins from './plugins.js';
 import { authSwitchHome } from './classes.credentialstore.js';
 import { assertAuthSwitchMutation, type TAuthSwitchMutation } from './mutation.js';
+import { assertAuthSwitchMutationAllowed, assertStatedLegacyFence,
+  type TAuthSwitchLegacyFence } from './classes.legacyfence.js';
 import type { IAuthHarness, IHarnessOutcome } from './interfaces.harness.js';
 
 /**
@@ -8,6 +10,8 @@ import type { IAuthHarness, IHarnessOutcome } from './interfaces.harness.js';
  * through `@modelprofile.com/authswitch/mutation`; they stay exported here for every Node caller.
  */
 export { assertAuthSwitchMutation, authSwitchMutationReplacesLogin, type TAuthSwitchMutation } from './mutation.js';
+export { authSwitchHostLegacyFence, type TAuthSwitchLegacyFence,
+  type IAuthSwitchLegacyFenceLocations } from './classes.legacyfence.js';
 
 export interface IAuthSwitchCoordinationRequest {
   protocolVersion: 1;
@@ -41,9 +45,19 @@ export const authSwitchEnvironmentId = (env: NodeJS.ProcessEnv = process.env): s
   openCodeOverride: env.OPENCODE_AUTH_CONTENT !== undefined,
 })).digest('hex');
 
-export const runAuthSwitchMutation = async (harness: IAuthHarness, mutation: TAuthSwitchMutation): Promise<IHarnessOutcome> => {
+/**
+ * The one mutation chokepoint, and therefore the one place the legacy fence can sit.
+ *
+ * `AuthSwitchOperations.run` delegates here and the AGL-hosted `AuthSwitchService` calls it directly, so a
+ * fence inside the class would leave the hosted path open. Where it looks is stated by the caller rather
+ * than defaulted, for the reason the authority states its own legacy locations: a fence that reached for
+ * `process.env` from inside a test would read whichever host ran it.
+ */
+export const runAuthSwitchMutation = async (harness: IAuthHarness, mutation: TAuthSwitchMutation,
+  legacyFence: TAuthSwitchLegacyFence): Promise<IHarnessOutcome> => {
   assertAuthSwitchMutation(mutation);
   if (harness.id !== mutation.harnessId) throw new Error('Account operation targets a different harness.');
+  await assertAuthSwitchMutationAllowed(legacyFence, harness, mutation);
   switch (mutation.action) {
     case 'save': return harness.saveCurrent({ keepActive: mutation.keepActive, accountId: mutation.accountId });
     case 'switch': return harness.switchAccount(mutation.accountId);
@@ -53,10 +67,15 @@ export const runAuthSwitchMutation = async (harness: IAuthHarness, mutation: TAu
 
 /** One mutation path for command, guide and TUI. Supervisors own their complete restart transaction. */
 export class AuthSwitchOperations {
-  constructor(private readonly coordinator?: TAuthSwitchCoordinator) {}
+  /** `legacyFence` is stated, never defaulted: see `runAuthSwitchMutation`. */
+  constructor(private readonly coordinator: TAuthSwitchCoordinator | undefined,
+    private readonly legacyFence: TAuthSwitchLegacyFence) { assertStatedLegacyFence(legacyFence); }
   public async run(harness: IAuthHarness, mutation: TAuthSwitchMutation, confirm?: TAuthSwitchConfirmation, prepareLocal?: TAuthSwitchLocalPreparation): Promise<IHarnessOutcome> {
     assertAuthSwitchMutation(mutation);
     if (harness.id !== mutation.harnessId) throw new Error('Account operation targets a different harness.');
+    // Asked before AGL is, so a coordinated mutation is refused here rather than carried out by a host that
+    // may not fence it; `runAuthSwitchMutation` asks again, because the answer can change while it waits.
+    await assertAuthSwitchMutationAllowed(this.legacyFence, harness, mutation);
     if (this.coordinator && mutation.action !== 'remove') {
       const request: IAuthSwitchCoordinationRequest = { protocolVersion: 1, contextId: authSwitchEnvironmentId(), mutation, waitForIdle: false };
       let result = await this.coordinator(request);
@@ -68,7 +87,7 @@ export class AuthSwitchOperations {
       if (result.status === 'busy') return { lines: [], problems: [result.message] };
     }
     if (prepareLocal) await prepareLocal();
-    return runAuthSwitchMutation(harness, mutation);
+    return runAuthSwitchMutation(harness, mutation, this.legacyFence);
   }
 }
 

package/ts/classes.service.ts

@@ -4,6 +4,9 @@ import { OpenCodeHarness } from './classes.opencodeharness.js';
 import { ClaudeCodeHarness } from './classes.claudecodeharness.js';
 import { readAccountList } from './classes.accountlist.js';
 import { assertAuthSwitchMutation, authSwitchEnvironmentId, runAuthSwitchMutation, type IAuthSwitchCoordinationRequest, type TAuthSwitchCoordinationResult, type TAuthSwitchCoordinator } from './classes.operations.js';
+import { AuthSwitchRefusal } from './authority-contract.js';
+import { assertAuthSwitchMutationAllowed, assertStatedLegacyFence, authSwitchHostLegacyFence,
+  type TAuthSwitchLegacyFence } from './classes.legacyfence.js';
 import type { IAuthHarness, IHarnessLoginHandle, IHarnessLoginOptions, IHarnessLoginProvider, IHarnessLoginResult, IHarnessOutcome } from './interfaces.harness.js';
 import type { IAccountList } from './interfaces.list.js';
 import type { TAuthLoginPrompt } from './classes.login.js';
@@ -67,15 +70,51 @@ export const assertAuthSwitchServiceRequest: (value: unknown) => asserts value i
 export class AuthSwitchService {
   private readonly operations = new Map<string, IOperation>();
   private closed = false;
-  constructor(
-    private readonly harnesses: IAuthHarness[] = [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()],
-    private readonly coordinator?: TAuthSwitchCoordinator,
-  ) {}
+  private readonly harnesses: IAuthHarness[];
+  private readonly legacyFence: TAuthSwitchLegacyFence;
+  /**
+   * With no harnesses, the service composes this host's own and fences them with this host's authority.
+   *
+   * A host that injects its harnesses -- AGL does -- also states the fence for them: only it knows which
+   * stores they write, and a default would fence whichever host this process happens to run on.
+   */
+  constructor();
+  constructor(harnesses: IAuthHarness[], coordinator: TAuthSwitchCoordinator | undefined,
+    legacyFence: TAuthSwitchLegacyFence);
+  constructor(harnessesArg?: IAuthHarness[], private readonly coordinator?: TAuthSwitchCoordinator,
+    legacyFenceArg?: TAuthSwitchLegacyFence) {
+    this.harnesses = harnessesArg ?? [new CodexHarness(), new OpenCodeHarness(), new ClaudeCodeHarness()];
+    const legacyFence: unknown = harnessesArg === undefined ? authSwitchHostLegacyFence() : legacyFenceArg;
+    assertStatedLegacyFence(legacyFence);
+    this.legacyFence = legacyFence;
+  }
   private harness(id: string): IAuthHarness {
     const harness = this.harnesses.find(item => item.id === id);
     if (!harness) throw new Error('Unknown harness.');
     return harness;
   }
+  /**
+   * One hosted mutation: fenced, then coordinated, then -- when no supervisor carries it out -- run here.
+   *
+   * The fence is asked before the coordinator, as `AuthSwitchOperations` asks it: a refused mutation must not
+   * first have its host stop the runtimes it would restart. The local run asks again, because the answer can
+   * change while coordination waits. A refusal is reported as the outcome's problem: it is an answer the owner
+   * acts on, exactly like the credential-location mismatch `request` reports, and it wrote nothing; letting it
+   * fall into the operation's generic failure would hide the one sentence that says what to do instead.
+   */
+  private async mutate(harness: IAuthHarness,
+    coordination: IAuthSwitchCoordinationRequest): Promise<TAuthSwitchCoordinationResult> {
+    try {
+      await assertAuthSwitchMutationAllowed(this.legacyFence, harness, coordination.mutation);
+      const coordinated = this.coordinator ? await this.coordinator(coordination) : { status: 'unavailable' } as const;
+      if (coordinated.status !== 'unavailable') return coordinated;
+      return { status: 'complete',
+        outcome: await runAuthSwitchMutation(harness, coordination.mutation, this.legacyFence) };
+    } catch (error) {
+      if (error instanceof AuthSwitchRefusal) return { status: 'complete', outcome: { lines: [], problems: [error.message] } };
+      throw error;
+    }
+  }
   private snapshot(operation: IOperation): IAuthSwitchServiceOperation { return structuredClone(operation.status); }
   public async request(request: TAuthSwitchServiceRequest): Promise<IAuthSwitchServiceOperation> {
     assertAuthSwitchServiceRequest(request);
@@ -111,10 +150,8 @@ export class AuthSwitchService {
             operation.status.result = { status: 'complete', outcome: { lines: [], problems: ['AGL and authswitch use different credential locations. Use matching credential environment settings before switching.'] } };
             break;
           }
-          const harness = this.harness(request.coordination.mutation.harnessId);
-          const coordinated = this.coordinator ? await this.coordinator(request.coordination) : { status: 'unavailable' } as const;
-          operation.status.result = publicResult(coordinated.status === 'unavailable'
-            ? { status: 'complete', outcome: await runAuthSwitchMutation(harness, request.coordination.mutation) } : coordinated);
+          operation.status.result = publicResult(
+            await this.mutate(this.harness(request.coordination.mutation.harnessId), request.coordination));
           break;
         }
         case 'login': {

package/ts/classes.tui.ts

@@ -13,7 +13,9 @@ const preuseResultLine = (resultArg: TPreuseAccountResult): string => resultArg.
 
 /** Owns account-management actions; terminal rendering and interaction belong to smartconsole. */
 export class AuthSwitchTui {
-  constructor(private readonly harnesses: readonly IAuthHarness[], private readonly out: plugins.smartconsole.SmartConsole, private readonly operations = new AuthSwitchOperations()) {}
+  /** The guide is reached through `AuthSwitchCli`, and mutates through that command line's own operations and fence. */
+  constructor(private readonly harnesses: readonly IAuthHarness[], private readonly out: plugins.smartconsole.SmartConsole,
+    private readonly operations: AuthSwitchOperations) {}
 
   public async run(preferredArg?: IAuthHarness): Promise<number> {
     let harness = preferredArg ?? this.harnesses[0];