@modelprofile.com/authswitch 2.3.0 → 3.0.0

package/dist_ts/interfaces.list.d.ts

@@ -1,4 +1,4 @@
-import type { IHarnessAccount, IHarnessAccountStatus } from './interfaces.harness.js';
+import type { IHarnessAccount, IHarnessAccountStatus, IHarnessCredentialDrift } from './interfaces.harness.js';
 /** Credential-free, versioned output of list --json. Missing status fields stay omitted. */
 export interface IAccountList {
     schemaVersion: 2;
@@ -14,6 +14,8 @@ export interface IHarnessAccountList {
     accounts: (IHarnessAccount & {
         status: IHarnessAccountStatus;
     })[];
+    /** Slots whose credential file no longer holds the account the last switch wrote. */
+    credentialDrift: IHarnessCredentialDrift[];
     /** A state lookup failure is distinct from an empty account list. */
     problems: string[];
 }
@@ -67,4 +69,17 @@ export interface IActiveAccountRow {
     /** Where the shown account comes from. Whether it is also saved is the `savedAt` field's answer. */
     source: 'credential file' | 'stash only' | 'none';
     unavailableReason: string | null;
+    /** Set when the credential file no longer holds the account the last switch wrote. */
+    drift: IActiveAccountDrift | null;
+}
+/** A credential file that changed underneath a switch, with both accounts named where known. */
+export interface IActiveAccountDrift {
+    expectedAccountId: string;
+    expectedAccount: string | null;
+    currentAccountId: string | null;
+    currentAccount: string | null;
+    currentIsSaved: boolean;
+    switchedAt: string;
+    /** The sentence the table footnotes, for consumers that display one string. */
+    reason: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/authswitch",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "private": false,
   "description": "Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status",
   "main": "dist_ts/index.js",

package/readme.md

@@ -58,6 +58,8 @@ authswitch active                 # which account each provider is using right n
 authswitch codex stash            # save the active credential under its account email
 authswitch codex list             # Codex accounts, including an unsaved active login, with live status
 authswitch codex use [email]      # activate one; prompts when no email is given
+authswitch claude use [email] --stop        # stop running Claude Code instances first
+authswitch claude use [email] --keep-running  # switch without stopping anything
 authswitch codex preuse <email>   # send the default prompt without activating the account
 authswitch codex current          # print the account currently in use
 authswitch codex drop <email>     # forget a stash
@@ -79,16 +81,53 @@ the management TUI and human/JSON lists. With an AGL installation that supports
 authswitch coordination, the CLI delegates credential changes to AGL. AGL owns
 stopping and restarting its OpenCode runtime. Idle changes need no additional
 restart confirmation; active work requires consent to wait for it to finish.
-Unmanaged native processes must still be exited manually: a terminal session
-cannot safely be reconstructed from its PID. `stash --keep` is the exception --
-it only reads the native credential files and writes to authswitch's own store,
-so it works while OpenCode or Claude Code is running, and it is refused only if
-those files keep changing while they are read. The operations that replace a
-native login -- `stash` without `--keep`, `use`, and backend activation --
-still require the harness stopped, because a running one holds the outgoing
-token in memory and would write it back over the incoming login at its next
-refresh. Status lookups remain read-only and work while harnesses are running.
-`preuse` remains a Codex capability.
+Every operation, including `use` and `stash`, now works while OpenCode or Claude
+Code is running: the credential file is written atomically, the outgoing login is
+re-saved from disk first, and a write that races a native rewrite is detected and
+refused rather than half-applied. Status lookups remain read-only. `preuse`
+remains a Codex capability.
+
+#### Running instances during a switch
+
+A harness that keeps running through a switch still costs something: it holds the
+previous login in memory and can write it back at its next OAuth token refresh.
+So before `use` and before `stash` without `--keep`, authswitch lists that
+harness's own running instances -- pid, start time and command line -- and offers
+to stop them:
+
+```
+2 Claude Code process(es) are running:
+  pid 4821  started 2026-09-16 14:02 UTC  claude --session-id 9f2c
+  pid 5533  started 2026-09-16 14:02 UTC  claude agents
+? Stop these 2 Claude Code process(es) first? (y/N)
+```
+
+Answering yes sends `SIGTERM` to exactly those pids and waits up to ten seconds;
+an instance that survives is reported by pid and the switch continues. Three flags
+decide the same thing without a prompt:
+
+| Flag | Effect |
+| --- | --- |
+| `--stop` | stop the listed instances gracefully, then switch |
+| `--force-stop` | the same, then `SIGKILL` the ones that ignored `SIGTERM` |
+| `--keep-running` | switch without stopping anything |
+
+Without a terminal and without a flag, nothing is ever signalled: the instances are
+listed, the switch proceeds, and the command says which flag would have changed that.
+`SIGKILL` is only ever sent for `--force-stop`. Only pids authswitch enumerated for
+the current user in that operation are signalled -- never a name or pattern match,
+never another user's process -- and a pid is re-verified against a fresh listing
+before a forced kill, so a recycled pid cannot inherit it. The session that is
+running the command is listed but never stopped: stopping it would kill the switch.
+On Windows the instances are listed but not stopped, because its process list does
+not identify their owner. `stash --keep` needs none of this: it writes no native
+file and is guarded by proving the native sources unchanged around the read.
+
+After a switch that left instances running, the command says so explicitly, because
+one of them refreshing its token can put the previous account back. A backend
+activation through `AuthSwitchService` gets that same caveat in its outcome, but no
+listing and no offer: a host has no terminal to consent with, and a supervisor that
+completed the mutation itself owns its own runtime's lifecycle.
 
 `authswitch codex login` and `authswitch opencode login openai` use the shared
 OpenAI device login flow. They display a verification link and code, then save
@@ -369,6 +408,22 @@ exist, `none` means neither. **Saved** is how long ago `authswitch` last saved t
 login, or `not saved` — which is also the warning that a switch could not bring it
 back. A harness with no active login keeps its row and explains itself in a note.
 
+**Source** also answers whether the file still holds what the last switch wrote.
+When authswitch switches a login it records that account and the hash of the
+credential it wrote, in its own store, never in the harness file. If a later read
+finds a different account in that slot, the row's source reads
+`credential file (changed)` and a note explains it:
+
+```
+note — Claude Code · bob@example.test: The credential file changed since the last
+switch (likely a running instance refreshed the previous login). It now holds
+bob@example.test, which is saved. Run authswitch claude use alice@example.test again.
+```
+
+`authswitch <harness> current` prints the same sentence. The same account with a
+rotated token is that account refreshing itself and is not reported; re-running the
+switch re-arms the check against the file's current contents.
+
 Both commands accept a harness qualifier (`authswitch claude limits`) and `--json`.
 Both are read-only: they never activate, save or clear a login, they need no harness
 stopped, and every provider lookup is bounded by the same 10-second timeout and
@@ -385,16 +440,20 @@ arguments to these commands exit with 2.
 `limits --json` emits `IAccountLimits` and `active --json` emits `IActiveAccounts`:
 the same rows as the tables, plus the machine-readable fields the tables condense —
 `accountId`, `slotId`, `scope`, `windowSeconds`, the ISO `resetAt` beside the human
-`resetsIn`, the ISO `savedAt` beside the human `savedAgo`, and the per-row
-`unavailableReason` that the footnotes summarise. Both carry `schemaVersion: 1`, the
+`resetsIn`, the ISO `savedAt` beside the human `savedAgo`, the per-row
+`unavailableReason` that the footnotes summarise, and `drift`, which carries the
+expected and current account ids, their labels, whether the current one is saved,
+the ISO `switchedAt` of the switch that was undone, and the same sentence as `reason`. Both carry `schemaVersion: 1`, the
 shared `generatedAt` snapshot every countdown is relative to, and `complete`, which
 is false when any account or harness could not be read.
 
 The exported `IAccountList` contract contains:
 
 - `schemaVersion: 2`, `generatedAt` (ISO UTC), and `complete`.
-- `harnesses[]`: `id`, `label`, `loginHint`, `saveUnavailableReason`, `accounts`, and
-  harness-level `problems` (distinguishing failed discovery from an empty list).
+- `harnesses[]`: `id`, `label`, `loginHint`, `saveUnavailableReason`, `accounts`,
+  `credentialDrift` (slots whose file no longer holds the account the last switch
+  wrote), and harness-level `problems` (distinguishing failed discovery from an
+  empty list).
 - Each account's opaque `id`, `label`, `isActive`, verified `isStashed`, `savedAt`,
   `details`, and `status` containing all labelled `facts`, `problems`, and optional
   typed `summary` fields. Missing fields remain omitted, not replaced by zero.
@@ -529,6 +588,8 @@ scripts must qualify them. Account references never resolve across harnesses.
 | What | Where |
 | --- | --- |
 | Stashed credentials | `~/.authswitch/codex/<email>/auth.json` (mode 0600, in a 0700 directory) |
+| Saved OpenCode/Claude logins | `~/.authswitch/<harness>/<id>.json` (mode 0600, in a 0700 directory) |
+| Last switch per credential slot | `~/.authswitch/<harness>/switches.json` (account ids, credential hashes and timestamps; no credentials) |
 | Stash metadata and enrollments | `~/.authswitch/codex/<email>/stash.json` |
 | Codex' active credential | `$CODEX_HOME/auth.json`, default `~/.codex/auth.json` |
 | Codex' remote-control enrollments | the `remote_control_enrollments` table in `$CODEX_HOME/state_<n>.sqlite` |
@@ -543,6 +604,8 @@ Account identity comes from the `id_token` inside the credential — the email c
 
 **Other Codex clients keep running.** Stopping the managed app-server does not stop an editor extension that spawned its own. Close it, or expect it to keep using the credential it already loaded.
 
+**A running OpenCode or Claude Code can undo a switch.** It holds the previous login in memory and rewrites the credential file at its next token refresh. Authswitch lists those instances, offers to stop them, warns when any keep running, and detects the overwrite afterwards — but it cannot prevent it while they run. Restart them after a switch.
+
 **The Codex stash is keyed by email.** Two Codex workspaces with the same email
 cannot both be saved under that key. Their account IDs are distinguished during
 listing and identity checks, and a collision refuses to overwrite either login.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/authswitch',
-  version: '2.3.0',
+  version: '3.0.0',
   description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
 }

package/ts/accounts.ts

@@ -1,4 +1,4 @@
-import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessState, IHarnessStatusSummary } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessAccountStatus, IHarnessCredentialDrift, IHarnessState, IHarnessStatusSummary } from './interfaces.harness.js';
 import { plainText } from './formatting.js';
 
 export interface IAccountRow {
@@ -41,13 +41,33 @@ export const compactUntil = (timestampArg: string | null, nowArg: number, unavai
   if (remaining <= 0) return 'due';
   return remaining < 60000 ? '<1m' : twoUnits(remaining);
 };
-/** The same two-unit form for a past timestamp, for "saved 3d 4h ago". */
+/**
+ * The same two-unit form for a past timestamp, for "saved 3d 4h ago".
+ *
+ * The result is always a bare duration or the caller's unavailable marker, never a phrase: callers
+ * suffix it ("... ago"), and a phrase would read as "just now ago". A span under a minute is `<1m`,
+ * exactly as `compactUntil` reports one.
+ */
 export const compactSince = (timestampArg: string | null, nowArg: number, unavailableArg = 'n/a'): string => {
   if (timestampArg === null) return unavailableArg;
   const elapsed = nowArg - Date.parse(timestampArg);
   if (!Number.isFinite(elapsed)) return unavailableArg;
-  return elapsed < 60000 ? 'just now' : twoUnits(elapsed);
+  return elapsed < 60000 ? '<1m' : twoUnits(elapsed);
 };
+/**
+ * One sentence for a credential file that no longer holds the account the last switch wrote.
+ *
+ * It names what the file holds now and how to put the intended account back, because the usual
+ * cause -- a harness instance that kept running through the switch and then refreshed its
+ * in-memory login -- leaves no other trace.
+ */
+export const credentialDriftNote = (harnessIdArg: string, driftArg: IHarnessCredentialDrift): string =>
+  'The credential file changed since the last switch (likely a running instance refreshed the previous login). '
+  + (driftArg.currentLabel === null ? 'No login is active in that slot now. '
+    : `It now holds ${plainText(driftArg.currentLabel)}${driftArg.currentIsSaved ? ', which is saved' : ', which is not saved'}. `)
+  + (driftArg.expectedLabel === null ? 'Switch to the intended account again.'
+    : `Run authswitch ${plainText(harnessIdArg)} use ${plainText(driftArg.expectedLabel)} again.`);
+
 export const accountPlan = (rowArg: IAccountRow): string => {
   const subscription = rowArg.status?.summary?.subscription;
   return subscription ? `${plainText(subscription.plan)}${subscription.source === 'stored' ? ' (stored; unverified)' : ' (live)'}` : rowArg.status ? 'Unavailable' : 'Loading';

package/ts/classes.accountlist.ts

@@ -28,10 +28,11 @@ const publicStatus = (statusArg: IHarnessAccountStatus): IHarnessAccountStatus =
 export const readAccountList = async (harnessesArg: IAuthHarness[]): Promise<IAccountList> => {
   const harnesses: IHarnessAccountList[] = [];
   for (const harness of harnessesArg) {
-    const result: IHarnessAccountList = { id: harness.id, label: harness.label, loginHint: harness.loginHint, saveUnavailableReason: null, accounts: [], problems: [] };
+    const result: IHarnessAccountList = { id: harness.id, label: harness.label, loginHint: harness.loginHint, saveUnavailableReason: null, accounts: [], credentialDrift: [], problems: [] };
     try {
       const { state, rows } = await readAccountRows(harness);
       result.saveUnavailableReason = state.saveUnavailableReason;
+      result.credentialDrift = state.credentialDrift ?? [];
       result.accounts = rows.map(({ account, status }) => ({
         id: account.id, label: account.label, isActive: account.isActive, isStashed: account.isStashed,
         savedAt: account.savedAt, details: [...account.details], ...(account.slotId === undefined ? {} : { slotId: account.slotId }),

package/ts/classes.claudecodeharness.ts

@@ -1,9 +1,10 @@
 import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
-import { CredentialStore, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw, requireHarnessStopped } from './classes.credentialstore.js';
+import { CredentialStore, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
+import { HarnessProcesses } from './classes.harnessprocesses.js';
 import { ClaudeAccountStatus } from './classes.claudestatus.js';
 import { writeSecretFileAtomically } from './helpers.js';
-import type { IHarnessAccountStatus } from './interfaces.harness.js';
+import type { IHarnessAccountStatus, IHarnessProcessControl } from './interfaces.harness.js';
 
 export interface IClaudeCodeHarnessOptions {
   configDir?: string;
@@ -12,7 +13,8 @@ export interface IClaudeCodeHarnessOptions {
   env?: NodeJS.ProcessEnv;
   platform?: NodeJS.Platform;
   fetch?: typeof fetch;
-  checkStopped?: () => void;
+  /** Running-instance inspection, injectable for isolated installations and tests. */
+  processes?: IHarnessProcessControl;
   /** Local settings sources to inspect for credential overrides, in increasing precedence. */
   settingsFiles?: string[];
 }
@@ -30,7 +32,7 @@ export class ClaudeCodeHarness extends FileHarness {
   private readonly env: NodeJS.ProcessEnv;
   private readonly platform: NodeJS.Platform;
   private readonly status: ClaudeAccountStatus;
-  private readonly checkStopped: () => void;
+  public readonly processes: IHarnessProcessControl;
   private readonly settingsFiles: string[];
 
   constructor(options: IClaudeCodeHarnessOptions = {}) {
@@ -43,11 +45,10 @@ export class ClaudeCodeHarness extends FileHarness {
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.platform = options.platform ?? process.platform;
     this.status = new ClaudeAccountStatus(options.fetch);
-    this.checkStopped = options.checkStopped ?? (() => requireHarnessStopped('claude'));
+    this.processes = options.processes ?? new HarnessProcesses('claude', { platform: this.platform });
     this.settingsFiles = options.settingsFiles ?? [plugins.path.join(dir, 'settings.json'),
       plugins.path.join(process.cwd(), '.claude/settings.json'), plugins.path.join(process.cwd(), '.claude/settings.local.json')];
   }
-  protected beforeMutation(): void { this.checkStopped(); }
   /** One record holds the credential and its matching metadata, so both files must be proven stable. */
   protected nativeSources(): (string | null)[] { return [readCredentialRaw(this.file), readCredentialRaw(this.configFile)]; }
   protected inspect(credential: Record<string, unknown>, slotId: string): IFileAccount {

package/ts/classes.cli.ts

@@ -7,15 +7,21 @@ import { AuthSwitchTui } from './classes.tui.js';
 import { AglAuthSwitchCoordinator, AuthSwitchOperations, type TAuthSwitchCoordinator, type TAuthSwitchMutation } from './classes.operations.js';
 import { AccountListRenderer, readAccountList } from './classes.accountlist.js';
 import { accountLimits, activeAccounts, CondensedRenderer } from './classes.limits.js';
-import { duration, orderedUsageWindows, until } from './accounts.js';
+import { credentialDriftNote, duration, orderedUsageWindows, until } from './accounts.js';
+import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 import { defaultPreusePrompt, PreuseError, validatePreuseOptions } from './preuse.js';
 import type { CodexSwitcher } from './classes.codexswitcher.js';
-import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessState, IHarnessPreuseResult } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome, IHarnessPreuseResult } from './interfaces.harness.js';
 import { bold, dim, green, orange, plainText, red } from './formatting.js';
 
 const canPrompt = (): boolean =>
   process.stdin.isTTY === true && process.stdout.isTTY === true && !process.env.CI;
 const COMMANDS = ['login', 'stash', 'list', 'ls', 'limits', 'active', 'use', 'preuse', 'current', 'drop', 'rm', 'doctor'];
+/** What to do about the harness's own running instances before a credential file is rewritten. */
+export type TStopMode = 'stop' | 'force-stop' | 'keep-running';
+const STOP_FLAGS = ['--stop', '--force-stop', '--keep-running'];
+/** Commands that replace or clear a native login, and therefore offer to stop its instances. */
+const STOP_COMMANDS = ['use', 'stash'];
 /** Read-only overviews that work across every registered harness and support --json. */
 const OVERVIEW_COMMANDS = ['list', 'ls', 'limits', 'active'];
 
@@ -57,7 +63,8 @@ ${bold('Usage')}
                                     send one prompt through that account without switching
   authswitch <harness> stash [account/provider] [--keep]
                                     save one active login; --keep leaves it active
-  authswitch <harness> use [account]   activate a saved account; prompts when omitted
+  authswitch <harness> use [account] [--stop|--force-stop|--keep-running]
+                                    activate a saved account; prompts when omitted
   authswitch <harness> current        show the active account
   authswitch <harness> login [provider]
                                     sign in and save a new account without switching
@@ -74,6 +81,13 @@ ${bold('Options')}
   -i, --interactive                  open the guided account manager
   --tui                             open the terminal management dashboard
   --json                            JSON output for list / ls / limits / active only
+  --stop                            stop this harness's running instances before the switch
+  --force-stop                      the same, then kill instances that ignore SIGTERM
+  --keep-running                    switch without stopping anything
+
+A switch works while OpenCode or Claude Code is running. Instances that keep running hold
+the previous login in memory and can write it back at their next token refresh, so the
+switch offers to stop them first; without a terminal it leaves them running and says so.
 
 Preuse consumes the selected account's quota. Its default prompt is:
   "${defaultPreusePrompt}"
@@ -107,6 +121,18 @@ ${bold('Environment')}
           return 2;
         }
       }
+      const stopFlags = args.filter(value => STOP_FLAGS.includes(value));
+      if (stopFlags.length > 1) { process.stderr.write(`Use only one of ${STOP_FLAGS.join(', ')}.\n`); return 2; }
+      const stopMode = stopFlags.length ? stopFlags[0].slice(2) as TStopMode : undefined;
+      if (stopMode !== undefined) {
+        args.splice(args.indexOf(stopFlags[0]), 1);
+        const route = [...args];
+        if (this.harnesses.has(route[0])) route.shift();
+        if (!STOP_COMMANDS.includes(route[0]) || (route[0] === 'stash' && args.includes('--keep'))) {
+          process.stderr.write(`${STOP_FLAGS.join(', ')} apply to use and to stash without --keep; a save that keeps the login needs no stopped instance.\n`);
+          return 2;
+        }
+      }
       if (['-h', '--help', 'help'].includes(args[0]) || (args.length === 0 && !canPrompt())) {
         process.stdout.write(`${this.usage()}\n`);
         return 0;
@@ -154,9 +180,9 @@ ${bold('Environment')}
           const references = args.filter(value => value !== '--keep');
           if (references.length > 1 || references.some(value => value.startsWith('-'))) { process.stderr.write('stash accepts one active account or provider and --keep.\n'); return 2; }
           const account = await this.selectActive(harness, references[0]);
-          return account ? this.reportOutcome(await this.mutate(harness, { harnessId: harness.id, action: 'save', keepActive: args.includes('--keep'), accountId: account.id })) : 1;
+          return account ? this.reportOutcome(await this.mutate(harness, { harnessId: harness.id, action: 'save', keepActive: args.includes('--keep'), accountId: account.id }, stopMode)) : 1;
         }
-        case 'use': return await this.commandUse(harness, args[0]);
+        case 'use': return await this.commandUse(harness, args[0], false, stopMode);
         case 'current': this.printCurrent(harness, await harness.readState()); return 0;
         case 'drop':
         case 'rm': {
@@ -185,10 +211,51 @@ ${bold('Environment')}
     return new AuthSwitchTui([...this.harnesses.values()], this.out, this.operations).run(harnessArg);
   }
 
-  private mutate(harness: IAuthHarness, mutation: TAuthSwitchMutation): Promise<IHarnessOutcome> {
+  private mutate(harness: IAuthHarness, mutation: TAuthSwitchMutation, stopModeArg?: TStopMode): Promise<IHarnessOutcome> {
+    const replacesNativeLogin = mutation.action === 'switch' || (mutation.action === 'save' && !mutation.keepActive);
     return this.operations.run(harness, mutation, canPrompt() ? async message => await this.out.prompts.ask({
       name: 'waitForIdle', type: 'confirm', message, default: false,
-    }) === true : undefined);
+    }) === true : undefined, replacesNativeLogin ? () => this.settleRunningInstances(harness, stopModeArg) : undefined);
+  }
+
+  /**
+   * Decide what happens to the harness's own running instances before its credential file changes.
+   *
+   * The switch itself no longer depends on this: it writes atomically and re-saves the outgoing
+   * login either way. What a running instance still costs is durability -- it holds the previous
+   * login in memory and can write it back at its next refresh -- so the instances are named and
+   * stopping them is offered, never assumed. Without a terminal and without a flag nothing is
+   * signalled, and only pids enumerated here for this user are ever signalled at all.
+   */
+  private async settleRunningInstances(harnessArg: IAuthHarness, modeArg?: TStopMode): Promise<void> {
+    const control = harnessArg.processes;
+    if (!control) return;
+    let running: IHarnessProcess[];
+    try { running = control.list(); }
+    catch { process.stdout.write(`${orange(`Could not check for running ${plainText(harnessArg.label)} processes; continuing with the switch.`)}\n`); return; }
+    if (!running.length) return;
+    for (const line of describeHarnessProcesses(harnessArg.label, running)) process.stdout.write(`${line}\n`);
+    if (control.stopUnavailableReason !== null) { process.stdout.write(`${dim(control.stopUnavailableReason)}\n`); return; }
+    const stoppable = running.filter(item => !item.isAncestor);
+    if (!stoppable.length || modeArg === 'keep-running') return;
+    let stop = modeArg === 'stop' || modeArg === 'force-stop';
+    if (modeArg === undefined) {
+      if (!canPrompt()) { process.stdout.write(`${dim('Leaving them running. Use --stop, --force-stop or --keep-running to decide this without a terminal.')}\n`); return; }
+      stop = await this.out.prompts.ask({
+        name: 'stopHarnessProcesses', type: 'confirm',
+        message: `Stop these ${stoppable.length} ${harnessArg.label} process(es) first?`, default: false,
+      }) === true;
+    }
+    if (!stop) return;
+    let outcome: IHarnessStopOutcome;
+    // Stopping re-reads the process table; if that read fails now, the switch is still the safe part.
+    try { outcome = await control.stop(stoppable, { force: modeArg === 'force-stop' }); }
+    catch (error) {
+      // The reason ends the line so its own punctuation is not doubled.
+      process.stdout.write(`${orange(`Could not stop the running ${plainText(harnessArg.label)} process(es); leaving them running: ${plainText(error instanceof Error ? error.message : 'the process list could not be read.')}`)}\n`);
+      return;
+    }
+    for (const line of describeStopOutcome(harnessArg.label, outcome)) process.stdout.write(`${line}\n`);
   }
 
   private async commandLogin(harness: IAuthHarness, providerId?: string): Promise<number> {
@@ -415,6 +482,7 @@ ${bold('Environment')}
       process.stdout.write(`${dim('no account is currently active')}\n`);
     }
     if (stateArg.saveUnavailableReason) process.stdout.write(`${dim(stateArg.saveUnavailableReason)}\n`);
+    for (const drift of stateArg.credentialDrift ?? []) process.stdout.write(`${orange(credentialDriftNote(harnessArg.id, drift))}\n`);
   }
 
   private async selectActive(harness: IAuthHarness, reference?: string): Promise<IHarnessAccount | undefined> {
@@ -470,7 +538,7 @@ ${bold('Environment')}
     return null;
   }
 
-  private async commandUse(harnessArg: IAuthHarness, referenceArg?: string, allowBackArg = false): Promise<number> {
+  private async commandUse(harnessArg: IAuthHarness, referenceArg?: string, allowBackArg = false, stopModeArg?: TStopMode): Promise<number> {
     let id: string | null = null;
     if (referenceArg) {
       id = await this.resolveAccount(harnessArg, referenceArg);
@@ -482,7 +550,7 @@ ${bold('Environment')}
     }
     id ??= await this.promptForAccount(harnessArg, `Which ${harnessArg.label} account should be active?`, allowBackArg);
     if (id === null) return allowBackArg ? 0 : 1;
-    return this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'switch', accountId: id }));
+    return this.reportOutcome(await this.mutate(harnessArg, { harnessId: harnessArg.id, action: 'switch', accountId: id }, stopModeArg));
   }
 
   private async promptForAccount(harnessArg: IAuthHarness, messageArg: string, allowBackArg: boolean, includeIncompleteArg = false): Promise<string | null> {

package/ts/classes.credentialstore.ts

@@ -38,6 +38,21 @@ export const readCredentialDocument = (file: string): { raw: string | null; data
   catch { throw new Error('Credential file is unreadable, malformed, or too large; no changes were made.'); }
 };
 
+/**
+ * What the last switch wrote into a native credential slot.
+ *
+ * This is authswitch's own state, never part of the harness file: it records the account and the
+ * hash of the credential that was activated, so a later read can tell a credential file that still
+ * holds that account from one a running instance has overwritten with a different login. It carries
+ * hashes and timestamps only, never a credential.
+ */
+export interface ISwitchRecord {
+  slotId: string;
+  accountId: string;
+  credentialHash: string;
+  switchedAt: string;
+}
+
 export interface IStoredCredential {
   schemaVersion: 1;
   id: string;
@@ -83,6 +98,32 @@ export class CredentialStore {
     return this.read(record.id);
   }
   public remove(id: string): void { this.read(id); plugins.fs.unlinkSync(this.file(id)); }
+  private get switchFile(): string { return plugins.path.join(this.dir, 'switches.json'); }
+  /** Advisory state: an absent, malformed or partial record reports no switch, never an error. */
+  public switchRecords(): ISwitchRecord[] {
+    let data: Record<string, unknown>;
+    try { data = readCredentialDocument(this.switchFile).data; } catch { return []; }
+    if (data.schemaVersion !== 1 || !Array.isArray(data.switches)) return [];
+    return data.switches.filter((item: unknown): item is ISwitchRecord => {
+      if (!item || typeof item !== 'object' || Array.isArray(item)) return false;
+      const record = item as Record<string, unknown>;
+      return !!credentialText(record.slotId) && /^[a-f0-9]{64}$/.test(String(record.accountId))
+        && /^[a-f0-9]{64}$/.test(String(record.credentialHash))
+        && typeof record.switchedAt === 'string' && Number.isFinite(Date.parse(record.switchedAt));
+    });
+  }
+  public recordSwitch(entry: Omit<ISwitchRecord, 'switchedAt'>): void {
+    this.writeSwitchRecords([...this.switchRecords().filter(item => item.slotId !== entry.slotId), { ...entry, switchedAt: new Date().toISOString() }]);
+  }
+  public clearSwitch(slotId: string): void {
+    const remaining = this.switchRecords().filter(item => item.slotId !== slotId);
+    if (remaining.length) this.writeSwitchRecords(remaining);
+    else plugins.fs.rmSync(this.switchFile, { force: true });
+  }
+  private writeSwitchRecords(records: ISwitchRecord[]): void {
+    plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    writeSecretFileAtomically(this.switchFile, JSON.stringify({ schemaVersion: 1, switches: records }, null, 2) + '\n');
+  }
   public locked<T>(action: () => T): T {
     plugins.fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
     const file = plugins.path.join(this.dir, '.lock');
@@ -93,21 +134,3 @@ export class CredentialStore {
     finally { plugins.fs.closeSync(fd); plugins.fs.unlinkSync(file); }
   }
 }
-
-/**
- * Native harnesses hold their login in memory and rewrite it on their own refresh schedule, so a
- * credential written underneath a running one is destroyed by the next refresh. Operations that
- * replace a native login therefore require it stopped. Reading for a save that keeps the login in
- * place writes nothing native and is guarded by content stability instead (see FileHarness).
- */
-export const requireHarnessStopped = (binary: 'opencode' | 'claude'): void => {
-  let names: string[];
-  try {
-    if (process.platform === 'win32') {
-      names = plugins.childProcess.execFileSync('tasklist', ['/FO', 'CSV', '/NH'], { encoding: 'utf8', timeout: 5000 }).split('\n').map(line => line.split('",')[0].replace(/^"/, ''));
-    } else {
-      names = plugins.childProcess.execFileSync('ps', ['-u', String(process.getuid!()), '-o', 'comm='], { encoding: 'utf8', timeout: 5000 }).split('\n').map(line => plugins.path.basename(line.trim()));
-    }
-  } catch { throw new Error(`Could not verify that ${binary} is stopped. No login was changed.`); }
-  if (names.some(name => name === binary || name === `${binary}.exe`)) throw new Error(`Exit running ${binary} processes before replacing or clearing its login, then start ${binary} again. Saving with --keep does not need this.`);
-};