@modelprofile.com/authswitch 2.2.0 → 3.0.0

package/ts/classes.harnessprocesses.ts

@@ -0,0 +1,225 @@
+import * as plugins from './plugins.js';
+import type { IHarnessProcess, IHarnessProcessControl, IHarnessStopOutcome } from './interfaces.harness.js';
+import { plainText } from './formatting.js';
+
+export type THarnessBinary = 'opencode' | 'claude';
+/** A raw same-user process row. The enumerator never filters; identity matching belongs here. */
+export interface IEnumeratedProcess {
+  pid: number;
+  parentPid: number | null;
+  /** Executable name as the platform reports it. Truncated by the platform on Linux. */
+  command: string;
+  /** argv[0] as the process reports it; a native installer may run a version-named file. */
+  executable: string;
+  commandLine: string;
+  startedAt: string | null;
+}
+
+export interface IHarnessProcessesOptions {
+  /** Same-user process table. Injected by tests and by hosts that own their own inspection. */
+  enumerate?: () => IEnumeratedProcess[];
+  /** Signal delivery, restricted by this class to pids it enumerated itself. */
+  signal?: (pidArg: number, signalArg: 'SIGTERM' | 'SIGKILL') => void;
+  /** Liveness probe for a pid that was signalled. */
+  alive?: (pidArg: number) => boolean;
+  sleep?: (millisecondsArg: number) => Promise<void>;
+  /** Default bounded wait for a graceful stop. Callers may shorten it per operation. */
+  timeoutMs?: number;
+  platform?: NodeJS.Platform;
+  /** This command's own pid, for the ancestor chain that must never be signalled. */
+  selfPid?: number;
+}
+
+/**
+ * How a harness binary is recognised in a process table.
+ *
+ * `comm` is not enough. Claude Code's native installer runs the CLI from a file named after its
+ * version (`~/.local/share/claude/versions/2.1.273`) and its remote agent from
+ * `~/.claude/remote/ccd-cli/<version>`, so the kernel reports a version number as the command name
+ * while argv[0] carries the real identity. Matching argv[0] and its install path finds the
+ * processes that actually hold a login; matching only `comm` finds the launcher and misses every
+ * session. Verified against Claude Code 2.1.260-2.1.273 and OpenCode 1.18.15 on Linux.
+ */
+const executablePatterns: Record<THarnessBinary, RegExp[]> = {
+  claude: [/(?:^|[/\\])claude(?:\.exe)?$/i, /[/\\]claude[/\\]versions[/\\][^/\\]+$/, /[/\\]\.claude[/\\]remote[/\\]ccd-cli[/\\][^/\\]+$/],
+  opencode: [/(?:^|[/\\])opencode(?:\.exe)?$/i],
+};
+
+const MAX_COMMAND_LINE = 200;
+const POSIX_FIELDS = 'pid=,ppid=,uid=,lstart=,comm=,args=';
+
+/** A bounded read of the current user's process table. Never a pattern-based kill list. */
+const enumeratePosix = (): IEnumeratedProcess[] => {
+  const uid = process.getuid!();
+  const output = plugins.childProcess.execFileSync('ps', ['-u', String(uid), '-o', POSIX_FIELDS], {
+    encoding: 'utf8', timeout: 5000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' }, windowsHide: true,
+  });
+  const processes: IEnumeratedProcess[] = [];
+  for (const line of output.split('\n')) {
+    // pid ppid uid, then the five fixed tokens of lstart, then comm and the full argument vector.
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 9) continue;
+    const [pid, parentPid, owner] = parts.slice(0, 3).map(Number);
+    if (!Number.isInteger(pid) || pid <= 0 || owner !== uid) continue;
+    const started = Date.parse(parts.slice(3, 8).join(' '));
+    const args = parts.slice(9);
+    processes.push({
+      pid, parentPid: Number.isInteger(parentPid) ? parentPid : null, command: parts[8],
+      executable: args[0] ?? parts[8], commandLine: (args.length ? args.join(' ') : parts[8]).slice(0, MAX_COMMAND_LINE),
+      startedAt: Number.isFinite(started) ? new Date(started).toISOString() : null,
+    });
+  }
+  return processes;
+};
+
+/** Windows reports an image name and a pid, with no owner, parent or start time in this view. */
+const enumerateWindows = (): IEnumeratedProcess[] => {
+  const output = plugins.childProcess.execFileSync('tasklist', ['/FO', 'CSV', '/NH'], {
+    encoding: 'utf8', timeout: 5000, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
+  });
+  const processes: IEnumeratedProcess[] = [];
+  for (const line of output.split('\n')) {
+    const columns = line.trim().replace(/^"/, '').replace(/"$/, '').split('","');
+    const pid = Number(columns[1]);
+    if (columns.length < 2 || !Number.isInteger(pid) || pid <= 0) continue;
+    processes.push({ pid, parentPid: null, command: columns[0], executable: columns[0], commandLine: columns[0], startedAt: null });
+  }
+  return processes;
+};
+
+/**
+ * Running instances of one harness binary, and a bounded, consent-driven way to stop them.
+ *
+ * Every signal target is a pid this class enumerated for the current user in this operation, and
+ * the ancestors of the running command are never signalled: stopping the session that invoked
+ * authswitch would kill the switch itself. `SIGKILL` is only ever sent after an explicit force
+ * request, and only to a pid re-verified against a fresh listing, so a recycled pid cannot inherit
+ * a kill meant for the process that already exited.
+ */
+export class HarnessProcesses implements IHarnessProcessControl {
+  private readonly enumerate: () => IEnumeratedProcess[];
+  private readonly signal: (pidArg: number, signalArg: 'SIGTERM' | 'SIGKILL') => void;
+  private readonly alive: (pidArg: number) => boolean;
+  private readonly sleep: (millisecondsArg: number) => Promise<void>;
+  private readonly platform: NodeJS.Platform;
+  private readonly selfPid: number;
+  private readonly defaultTimeout: number;
+
+  constructor(public readonly binary: THarnessBinary, optionsArg: IHarnessProcessesOptions = {}) {
+    this.platform = optionsArg.platform ?? process.platform;
+    this.enumerate = optionsArg.enumerate ?? (this.platform === 'win32' ? enumerateWindows : enumeratePosix);
+    this.signal = optionsArg.signal ?? ((pid, signal) => { process.kill(pid, signal); });
+    this.alive = optionsArg.alive ?? (pid => {
+      try { process.kill(pid, 0); return true; }
+      // EPERM means the process exists but is not ours; it is then never a stop target either.
+      catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM'; }
+    });
+    this.sleep = optionsArg.sleep ?? (milliseconds => new Promise<void>(resolve => { setTimeout(resolve, milliseconds); }));
+    this.selfPid = optionsArg.selfPid ?? process.pid;
+    this.defaultTimeout = optionsArg.timeoutMs ?? 10_000;
+  }
+
+  /** Windows' process list carries no owner, so an enumerated pid cannot be proven to be ours. */
+  public get stopUnavailableReason(): string | null {
+    return this.platform === 'win32'
+      ? 'On Windows authswitch lists running instances but does not stop them: the process list does not identify their owner. Close them yourself.'
+      : null;
+  }
+
+  public list(): IHarnessProcess[] {
+    const table = this.enumerate();
+    const ancestors = this.ancestorPids(table);
+    const patterns = executablePatterns[this.binary];
+    return table
+      .filter(item => patterns.some(pattern => pattern.test(item.executable) || pattern.test(item.command)))
+      .filter(item => item.pid !== this.selfPid)
+      .map(item => ({
+        pid: item.pid, command: plugins.path.basename(item.command), commandLine: plainText(item.commandLine),
+        startedAt: item.startedAt, isAncestor: ancestors.has(item.pid),
+      }))
+      .sort((left, right) => left.pid - right.pid);
+  }
+
+  /** The chain from this command up to init, which owns the terminal this command is running in. */
+  private ancestorPids(tableArg: IEnumeratedProcess[]): Set<number> {
+    const parents = new Map(tableArg.map(item => [item.pid, item.parentPid]));
+    const ancestors = new Set<number>();
+    let current = parents.get(this.selfPid) ?? (this.selfPid === process.pid ? process.ppid : null);
+    // The table is finite and each step moves to a distinct pid, so the walk terminates.
+    while (current !== null && current !== undefined && current > 1 && !ancestors.has(current)) {
+      ancestors.add(current);
+      current = parents.get(current) ?? null;
+    }
+    return ancestors;
+  }
+
+  public async stop(processesArg: readonly IHarnessProcess[], optionsArg: { force?: boolean; timeoutMs?: number } = {}): Promise<IHarnessStopOutcome> {
+    const force = optionsArg.force === true;
+    const timeout = Math.max(0, Math.min(optionsArg.timeoutMs ?? this.defaultTimeout, 120_000));
+    if (this.stopUnavailableReason) return { stopped: [], survivors: [...processesArg], forced: [] };
+    const listed = new Map(this.list().map(item => [item.pid, item]));
+    // Only a pid enumerated in this operation, still present, still not an ancestor, is a target.
+    const targets = processesArg.filter(item => {
+      const current = listed.get(item.pid);
+      return current !== undefined && !current.isAncestor && current.startedAt === item.startedAt;
+    });
+    // Anything the caller passed that is not a valid target is reported, never signalled.
+    const skipped = processesArg.filter(item => !targets.includes(item) && this.alive(item.pid));
+    let remaining = this.deliver(targets, 'SIGTERM');
+    remaining = await this.awaitExit(remaining, timeout);
+    const forced: IHarnessProcess[] = [];
+    if (force && remaining.length) {
+      // Re-verify against a fresh listing: a pid that exited may already belong to another process.
+      const fresh = new Map(this.list().map(item => [item.pid, item]));
+      const verified = remaining.filter(item => fresh.get(item.pid)?.startedAt === item.startedAt && !fresh.get(item.pid)!.isAncestor);
+      forced.push(...verified);
+      remaining = [...this.deliver(verified, 'SIGKILL'), ...remaining.filter(item => !verified.includes(item))];
+      remaining = await this.awaitExit(remaining, Math.min(timeout, 2000));
+    }
+    return {
+      stopped: processesArg.filter(item => !remaining.includes(item) && !skipped.includes(item)),
+      survivors: [...remaining, ...skipped],
+      forced,
+    };
+  }
+
+  private deliver(targetsArg: readonly IHarnessProcess[], signalArg: 'SIGTERM' | 'SIGKILL'): IHarnessProcess[] {
+    const remaining: IHarnessProcess[] = [];
+    for (const target of targetsArg) {
+      try { this.signal(target.pid, signalArg); remaining.push(target); }
+      catch (error) {
+        // ESRCH is the process we wanted gone; anything else stays reported as still running.
+        if ((error as NodeJS.ErrnoException).code !== 'ESRCH') remaining.push(target);
+      }
+    }
+    return remaining;
+  }
+
+  private async awaitExit(processesArg: IHarnessProcess[], timeoutArg: number): Promise<IHarnessProcess[]> {
+    let remaining = processesArg.filter(item => this.alive(item.pid));
+    const deadline = Date.now() + timeoutArg;
+    while (remaining.length && Date.now() < deadline) {
+      await this.sleep(Math.min(250, Math.max(1, deadline - Date.now())));
+      remaining = remaining.filter(item => this.alive(item.pid));
+    }
+    return remaining;
+  }
+}
+
+const started = (processArg: IHarnessProcess): string =>
+  processArg.startedAt === null ? 'start time unavailable' : `started ${processArg.startedAt.replace('T', ' ').slice(0, 16)} UTC`;
+
+/** Plain-text description of the instances found, for a terminal, a TUI log or a confirmation. */
+export const describeHarnessProcesses = (labelArg: string, processesArg: readonly IHarnessProcess[]): string[] => [
+  `${processesArg.length} ${plainText(labelArg)} process(es) are running:`,
+  ...processesArg.map(item => `  pid ${item.pid}  ${started(item)}  ${item.commandLine}`
+    + (item.isAncestor ? '  [runs this command; it is never stopped from inside itself]' : '')),
+];
+
+/** Plain-text report of what a stop achieved, including every instance that survived it. */
+export const describeStopOutcome = (labelArg: string, outcomeArg: IHarnessStopOutcome): string[] => {
+  const lines: string[] = [];
+  if (outcomeArg.stopped.length) lines.push(`Stopped ${outcomeArg.stopped.length} ${plainText(labelArg)} process(es)${outcomeArg.forced.length ? `, ${outcomeArg.forced.length} of them with SIGKILL` : ''}.`);
+  for (const survivor of outcomeArg.survivors) lines.push(`pid ${survivor.pid} did not exit and is still running: ${survivor.commandLine}`);
+  return lines;
+};

package/ts/classes.limits.ts

@@ -0,0 +1,209 @@
+import * as plugins from './plugins.js';
+import { compactSince, compactUntil, credentialDriftNote, orderedUsageWindows } from './accounts.js';
+import { consoleHeading, consoleTable } from './classes.accountlist.js';
+import type { IAccountList, IAccountLimitRow, IAccountLimits, IActiveAccountDrift, IActiveAccountRow, IActiveAccounts, IHarnessAccountList } from './interfaces.list.js';
+import type { IHarnessCredentialDrift } from './interfaces.harness.js';
+import { dim, plainText } from './formatting.js';
+
+type TListedAccount = IHarnessAccountList['accounts'][number];
+
+const UNAVAILABLE = 'n/a';
+const NONE = 'none';
+
+/**
+ * Provider naming stays data-driven.
+ *
+ * A harness that owns exactly one credential slot is its own provider; one that owns several (an
+ * OpenCode installation with an OpenAI and an Anthropic login) has to say which slot a row is about.
+ */
+const providerName = (harnessArg: IHarnessAccountList, accountArg?: TListedAccount): string => {
+  const slots = new Set(harnessArg.accounts.map(account => account.slotId).filter((slot): slot is string => slot !== undefined));
+  return accountArg?.slotId !== undefined && slots.size > 1
+    ? `${plainText(harnessArg.label)} / ${plainText(accountArg.slotId)}`
+    : plainText(harnessArg.label);
+};
+
+/**
+ * Why an account contributes no numbers.
+ *
+ * The provider's own explanation is preferred over ours, and a failed lookup is never presented as a
+ * missing capability: the two have different fixes.
+ */
+const missingLimitReason = (accountArg: TListedAccount): string => {
+  if (accountArg.status.problems.length) return accountArg.status.problems.map(plainText).join(' ');
+  const availability = accountArg.status.facts.filter(fact => fact.section === 'Availability').map(fact => plainText(fact.value));
+  if (accountArg.status.summary?.usageWindows === undefined) {
+    return availability[0] ?? 'This login does not expose a usage or quota API.';
+  }
+  return 'The provider reported no usage window for this account.';
+};
+
+const accountKeys = (harnessArg: IHarnessAccountList, accountArg: TListedAccount) => ({
+  harnessId: harnessArg.id,
+  provider: providerName(harnessArg, accountArg),
+  account: plainText(accountArg.label),
+  accountId: accountArg.id,
+  ...(accountArg.slotId === undefined ? {} : { slotId: plainText(accountArg.slotId) }),
+});
+
+const harnessProblem = (harnessArg: IHarnessAccountList): string | null =>
+  harnessArg.problems.length ? harnessArg.problems.map(plainText).join(' ') : null;
+
+/** Provider then account, keeping each account's windows in the order the adapter ranked them. */
+const byProviderThenAccount = <TRow extends { provider: string; account: string | null }>(rowsArg: TRow[]): TRow[] =>
+  [...rowsArg].sort((left, right) => left.provider.localeCompare(right.provider)
+    || (left.account ?? '').localeCompare(right.account ?? ''));
+
+const noteFor = (rowArg: { provider: string; account: string | null; unavailableReason: string | null }): string | null =>
+  rowArg.unavailableReason === null ? null
+    : `${rowArg.provider}${rowArg.account === null ? '' : ` · ${rowArg.account}`}: ${rowArg.unavailableReason}`;
+
+const collectNotes = (rowsArg: { provider: string; account: string | null; unavailableReason: string | null }[]): string[] =>
+  [...new Set(rowsArg.map(noteFor).filter((note): note is string => note !== null))];
+
+/** The drift a switch record proves, carried into the row document with both accounts named. */
+const activeDrift = (harnessArg: IHarnessAccountList, driftArg: IHarnessCredentialDrift): IActiveAccountDrift => ({
+  expectedAccountId: driftArg.expectedAccountId, expectedAccount: driftArg.expectedLabel === null ? null : plainText(driftArg.expectedLabel),
+  currentAccountId: driftArg.currentAccountId, currentAccount: driftArg.currentLabel === null ? null : plainText(driftArg.currentLabel),
+  currentIsSaved: driftArg.currentIsSaved, switchedAt: driftArg.switchedAt, reason: credentialDriftNote(harnessArg.id, driftArg),
+});
+
+/**
+ * One row per account and limit type, projected from the account list.
+ *
+ * Nothing here talks to a provider: the list is already the read-only, per-account-isolated lookup,
+ * so a single failing account costs its own rows a number and nothing else.
+ */
+export const accountLimits = (listArg: IAccountList): IAccountLimits => {
+  const now = Date.parse(listArg.generatedAt);
+  const rows: IAccountLimitRow[] = [];
+  for (const harness of listArg.harnesses) {
+    const problem = harnessProblem(harness);
+    const empty = {
+      limitType: null, scope: null, windowSeconds: null, usedPercent: null, resetAt: null, resetsIn: UNAVAILABLE,
+    } as const;
+    if (problem !== null) {
+      rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, isActive: false, ...empty, unavailableReason: problem });
+      continue;
+    }
+    if (!harness.accounts.length) {
+      rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, isActive: false, ...empty,
+        unavailableReason: harness.saveUnavailableReason === null ? 'No accounts are known for this harness.' : plainText(harness.saveUnavailableReason) });
+      continue;
+    }
+    for (const account of harness.accounts) {
+      const windows = orderedUsageWindows(account.status.summary?.usageWindows);
+      if (!windows.length) {
+        rows.push({ ...accountKeys(harness, account), isActive: account.isActive, ...empty, unavailableReason: missingLimitReason(account) });
+        continue;
+      }
+      for (const window of windows) {
+        rows.push({
+          ...accountKeys(harness, account), isActive: account.isActive,
+          limitType: plainText(window.label), scope: window.scope ?? 'account', windowSeconds: window.durationSeconds,
+          usedPercent: window.usedPercent, resetAt: window.resetAt, resetsIn: compactUntil(window.resetAt, now, UNAVAILABLE),
+          unavailableReason: null,
+        });
+      }
+    }
+  }
+  const limits = byProviderThenAccount(rows);
+  return { schemaVersion: 1, generatedAt: listArg.generatedAt, complete: listArg.complete, limits, notes: collectNotes(limits) };
+};
+
+/**
+ * One row per active credential slot.
+ *
+ * A harness with no active login still gets a row: "nothing is active here" is an answer, and
+ * silently dropping the provider would read as "this provider does not exist".
+ */
+export const activeAccounts = (listArg: IAccountList): IActiveAccounts => {
+  const now = Date.parse(listArg.generatedAt);
+  const rows: IActiveAccountRow[] = [];
+  const unattached: string[] = [];
+  for (const harness of listArg.harnesses) {
+    const problem = harnessProblem(harness);
+    const drifts = [...harness.credentialDrift];
+    const driftFor = (slotIdArg?: string): IActiveAccountDrift | null => {
+      const index = drifts.findIndex(item => item.slotId === slotIdArg);
+      return index < 0 ? null : activeDrift(harness, drifts.splice(index, 1)[0]);
+    };
+    if (problem !== null) {
+      rows.push({ harnessId: harness.id, provider: providerName(harness), account: null, accountId: null, savedAt: null, savedAgo: UNAVAILABLE, source: 'none', unavailableReason: problem, drift: null });
+      continue;
+    }
+    const active = harness.accounts.filter(account => account.isActive);
+    if (!active.length) {
+      const stashed = harness.accounts.filter(account => account.isStashed);
+      rows.push({
+        harnessId: harness.id, provider: providerName(harness), account: null, accountId: null,
+        savedAt: null, savedAgo: UNAVAILABLE, source: stashed.length ? 'stash only' : 'none',
+        unavailableReason: harness.saveUnavailableReason !== null ? plainText(harness.saveUnavailableReason)
+          : stashed.length ? `No login is active; ${stashed.length} saved account(s) can be activated with authswitch ${plainText(harness.id)} use.`
+            : `No login is active and none is saved. ${plainText(harness.loginHint)}`,
+        drift: drifts.length ? activeDrift(harness, drifts.shift()!) : null,
+      });
+    } else {
+      for (const account of active) {
+        rows.push({
+          ...accountKeys(harness, account),
+          savedAt: account.savedAt, savedAgo: compactSince(account.savedAt, now, UNAVAILABLE),
+          source: 'credential file',
+          unavailableReason: account.isStashed ? null : 'This active login is not saved yet; authswitch cannot restore it after a switch.',
+          drift: driftFor(account.slotId),
+        });
+      }
+    }
+    // A drifted slot with no row of its own still has to be reported, not dropped.
+    for (const drift of drifts) unattached.push(`${providerName(harness)}${drift.slotId === undefined ? '' : ` / ${plainText(drift.slotId)}`}: ${credentialDriftNote(harness.id, drift)}`);
+  }
+  const active = byProviderThenAccount(rows);
+  const driftNotes = active.filter(row => row.drift !== null)
+    .map(row => `${row.provider}${row.account === null ? '' : ` · ${row.account}`}: ${row.drift!.reason}`);
+  return { schemaVersion: 1, generatedAt: listArg.generatedAt, complete: listArg.complete, active, notes: [...collectNotes(active), ...driftNotes, ...unattached] };
+};
+
+const percent = (rowArg: IAccountLimitRow): string => rowArg.usedPercent === null ? UNAVAILABLE : `${rowArg.usedPercent}%`;
+
+/** Condensed presentation for `authswitch limits` and `authswitch active`. */
+export class CondensedRenderer {
+  constructor(private readonly out: plugins.smartconsole.SmartConsole) {}
+
+  private notes(notesArg: string[], prefixArg: string): void {
+    if (!notesArg.length) return;
+    process.stdout.write('\n');
+    for (const note of notesArg) process.stdout.write(`${dim(`${prefixArg}${note}`)}\n`);
+  }
+
+  public async renderLimits(limitsArg: IAccountLimits): Promise<void> {
+    consoleHeading('Account limits');
+    if (!limitsArg.limits.length) { process.stdout.write(`${dim('No harnesses registered.')}\n`); return; }
+    await consoleTable(this.out, limitsArg.limits, [
+      { key: 'provider', title: 'Provider', value: row => row.provider },
+      { key: 'account', title: 'Account', value: row => row.account ?? UNAVAILABLE, style: row => ({ bold: row.isActive }) },
+      { key: 'limit', title: 'Limit type', value: row => row.limitType ?? UNAVAILABLE },
+      { key: 'used', title: 'Used %', value: percent, align: 'right',
+        style: row => ({ foreground: row.usedPercent === null ? 'orange' : row.usedPercent >= 100 ? 'red' : undefined }) },
+      { key: 'reset', title: 'Resets in', value: row => row.resetsIn, align: 'right' },
+    ]);
+    this.notes(limitsArg.notes, 'n/a — ');
+  }
+
+  public async renderActive(activeArg: IActiveAccounts): Promise<void> {
+    consoleHeading('Active accounts');
+    if (!activeArg.active.length) { process.stdout.write(`${dim('No harnesses registered.')}\n`); return; }
+    await consoleTable(this.out, activeArg.active, [
+      { key: 'provider', title: 'Provider', value: row => row.provider },
+      { key: 'account', title: 'Account', value: row => row.account ?? NONE,
+        style: row => ({ bold: row.account !== null, foreground: row.account === null ? 'orange' : undefined }) },
+      // The absolute timestamp stays in --json; one screen is worth more here than one more column.
+      // "ago" belongs to a duration only; the unavailable marker is not one.
+      { key: 'saved', title: 'Saved', value: row => row.savedAt === null ? (row.account === null ? UNAVAILABLE : 'not saved')
+        : row.savedAgo === UNAVAILABLE ? UNAVAILABLE : `${row.savedAgo} ago`, align: 'right',
+        style: row => ({ foreground: row.savedAt === null && row.account !== null ? 'orange' : undefined }) },
+      { key: 'source', title: 'Source', value: row => row.drift === null ? row.source : `${row.source} (changed)`,
+        style: row => ({ foreground: row.drift !== null ? 'red' : row.source === 'credential file' ? 'green' : 'orange' }) },
+    ]);
+    this.notes(activeArg.notes, 'note — ');
+  }
+}

package/ts/classes.opencodeharness.ts

@@ -1,9 +1,10 @@
 import * as plugins from './plugins.js';
 import { FileHarness, type IFileAccount, type IFileHarnessSnapshot } from './classes.fileharness.js';
-import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw, requireHarnessStopped } from './classes.credentialstore.js';
+import { CredentialStore, credentialHash, credentialRecord, credentialText, readCredentialDocument, readCredentialRaw } from './classes.credentialstore.js';
+import { HarnessProcesses } from './classes.harnessprocesses.js';
 import { CodexAccountStatus } from './classes.codexstatus.js';
 import { writeSecretFileAtomically } from './helpers.js';
-import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider } from './interfaces.harness.js';
+import type { IHarnessAccountStatus, IHarnessLoginOptions, IHarnessLoginProvider, IHarnessProcessControl } from './interfaces.harness.js';
 import { beginSavedOpenAiLogin, openCodeCredentialFromLogin } from './classes.login.js';
 import { plainText } from './formatting.js';
 
@@ -12,8 +13,8 @@ export interface IOpenCodeHarnessOptions {
   stashRoot?: string;
   env?: NodeJS.ProcessEnv;
   fetch?: typeof fetch;
-  /** Process inspection dependency, injectable for isolated installations and tests. */
-  checkStopped?: () => void;
+  /** Running-instance inspection, injectable for isolated installations and tests. */
+  processes?: IHarnessProcessControl;
 }
 
 /** OpenCode owns one login per provider. Replacing a slot never replaces the whole provider set. */
@@ -26,7 +27,7 @@ export class OpenCodeHarness extends FileHarness {
   private readonly file: string;
   private readonly env: NodeJS.ProcessEnv;
   private readonly status: CodexAccountStatus;
-  private readonly checkStopped: () => void;
+  public readonly processes: IHarnessProcessControl;
   private readonly fetcher?: typeof fetch;
 
   constructor(options: IOpenCodeHarnessOptions = {}) {
@@ -36,9 +37,8 @@ export class OpenCodeHarness extends FileHarness {
     this.store = new CredentialStore(this.id, options.stashRoot);
     this.status = new CodexAccountStatus(options.fetch);
     this.fetcher = options.fetch;
-    this.checkStopped = options.checkStopped ?? (() => requireHarnessStopped('opencode'));
+    this.processes = options.processes ?? new HarnessProcesses('opencode');
   }
-  protected beforeMutation(): void { this.checkStopped(); }
   /** Every provider entry lives in one file, so its bytes are the whole stability proof. */
   protected nativeSources(): (string | null)[] { return [readCredentialRaw(this.file)]; }
   /** Public identity only, for reconciling a host's OpenAI association after native refresh/restart. */

package/ts/classes.operations.ts

@@ -19,6 +19,14 @@ export type TAuthSwitchCoordinationResult =
   | { status: 'complete'; outcome: IHarnessOutcome };
 export type TAuthSwitchCoordinator = (request: IAuthSwitchCoordinationRequest) => Promise<TAuthSwitchCoordinationResult>;
 export type TAuthSwitchConfirmation = (message: string) => Promise<boolean>;
+/**
+ * Runs immediately before a mutation this process performs itself.
+ *
+ * It never runs when a supervisor completed the mutation: a client must not stop a process whose
+ * lifecycle another manager owns, and stopping it after that manager already restarted it would
+ * split one transaction across two owners.
+ */
+export type TAuthSwitchLocalPreparation = () => Promise<void>;
 
 export const authSwitchEnvironmentId = (env: NodeJS.ProcessEnv = process.env): string => plugins.crypto.createHash('sha256').update(JSON.stringify({
   home: plugins.os.homedir(),
@@ -56,7 +64,7 @@ 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) {}
-  public async run(harness: IAuthHarness, mutation: TAuthSwitchMutation, confirm?: TAuthSwitchConfirmation): Promise<IHarnessOutcome> {
+  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.');
     if (this.coordinator && mutation.action !== 'remove') {
@@ -69,6 +77,7 @@ export class AuthSwitchOperations {
       if (result.status === 'complete') return result.outcome;
       if (result.status === 'busy') return { lines: [], problems: [result.message] };
     }
+    if (prepareLocal) await prepareLocal();
     return runAuthSwitchMutation(harness, mutation);
   }
 }

package/ts/classes.tui.ts

@@ -1,8 +1,9 @@
 import * as plugins from './plugins.js';
-import type { IAuthHarness, IHarnessOutcome, IHarnessState } from './interfaces.harness.js';
+import type { IAuthHarness, IHarnessOutcome, IHarnessProcess, IHarnessState, IHarnessStopOutcome } from './interfaces.harness.js';
 import { accountDetails, accountPlan, accountQuotaSummary, accountResets, accountState, accountUsageWindows, usagePeriod, until, readAccountRows, type IAccountRow } from './accounts.js';
 import { plainText } from './formatting.js';
 import { AuthSwitchOperations } from './classes.operations.js';
+import { describeHarnessProcesses, describeStopOutcome } from './classes.harnessprocesses.js';
 
 /** Owns account-management actions; terminal rendering and interaction belong to smartconsole. */
 export class AuthSwitchTui {
@@ -59,6 +60,34 @@ export class AuthSwitchTui {
       catch { footer.setText(`Operation failed. Run authswitch ${harness.id} doctor for diagnostics.`); }
       updateDetails();
     };
+    /**
+     * Name the harness's running instances before a credential write, and stop them only on consent.
+     *
+     * The dashboard makes the same offer the command line does, with the same rule: only pids
+     * enumerated for this user are signalled, the session running this dashboard is never one of
+     * them, and declining still performs the switch.
+     */
+    const settleInstances = (screen: plugins.smartconsole.ITuiContext) => async (): Promise<void> => {
+      const control = harness.processes;
+      if (!control) return;
+      let running: IHarnessProcess[];
+      try { running = control.list(); }
+      catch { ui.logs.append(`Could not check for running ${plainText(harness.label)} processes.`); return; }
+      if (!running.length) return;
+      for (const line of describeHarnessProcesses(harness.label, running)) ui.logs.append(line);
+      if (control.stopUnavailableReason !== null) { ui.logs.append(control.stopUnavailableReason); return; }
+      const stoppable = running.filter(item => !item.isAncestor);
+      if (!stoppable.length || screen.signal.aborted) return;
+      if (!await screen.confirm(`Stop these ${stoppable.length} ${plainText(harness.label)} process(es) first?`, { confirmLabel: 'Stop them' })) 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); }
+      catch (error) {
+        ui.logs.append(`Could not stop the running ${plainText(harness.label)} process(es); leaving them running: ${plainText(error instanceof Error ? error.message : 'the process list could not be read.')}`);
+        return;
+      }
+      for (const line of describeStopOutcome(harness.label, outcome)) ui.logs.append(line);
+    };
     const save = async (screen: plugins.smartconsole.ITuiContext, keepActiveArg: boolean): Promise<void> => {
       const latest = await harness.readState();
       const activeAccounts = latest.accounts.filter(account => account.isActive);
@@ -67,7 +96,8 @@ export class AuthSwitchTui {
       if (!active || latest.saveUnavailableReason) { footer.setText(latest.saveUnavailableReason ?? 'No active login to save.'); return; }
       if (!await screen.confirm(`Save ${plainText(active.label)}${keepActiveArg ? ' and keep it active' : ' and clear the active login'}?`)) return;
       if (screen.signal.aborted) return;
-      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: keepActiveArg, accountId: active.id }, message => screen.confirm(message));
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'save', keepActive: keepActiveArg, accountId: active.id },
+        message => screen.confirm(message), keepActiveArg ? undefined : settleInstances(screen));
       await refresh(screen); showOutcome(outcome);
     };
     const switchSelected = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {
@@ -87,7 +117,8 @@ export class AuthSwitchTui {
       }
       if (!await screen.confirm(`Switch ${plainText(harness.label)} to ${plainText(target.label)}?`, { confirmLabel: 'Switch' })) return;
       if (screen.signal.aborted) return;
-      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.id }, message => screen.confirm(message));
+      const outcome = await this.operations.run(harness, { harnessId: harness.id, action: 'switch', accountId: target.id },
+        message => screen.confirm(message), settleInstances(screen));
       await refresh(screen); showOutcome(outcome);
     };
     const remove = async (screen: plugins.smartconsole.ITuiContext): Promise<void> => {

package/ts/index.ts

@@ -4,6 +4,7 @@ export * from './interfaces.list.js';
 export * from './classes.codexharness.js';
 export * from './classes.opencodeharness.js';
 export * from './classes.claudecodeharness.js';
+export * from './classes.harnessprocesses.js';
 export * from './classes.claudestatus.js';
 export * from './classes.codexstatus.js';
 export * from './classes.codexpreuse.js';