@modelprofile.com/authswitch 2.3.0 → 3.1.0

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.`);
-};

package/ts/classes.fileharness.ts

@@ -1,5 +1,5 @@
-import type { IAuthHarness, IHarnessAccountStatus, IHarnessOutcome, IHarnessState } from './interfaces.harness.js';
-import { CredentialStore, type IStoredCredential } from './classes.credentialstore.js';
+import type { IAuthHarness, IHarnessAccountStatus, IHarnessCredentialDrift, IHarnessOutcome, IHarnessProcessControl, IHarnessState } from './interfaces.harness.js';
+import { credentialHash, CredentialStore, type IStoredCredential, type ISwitchRecord } from './classes.credentialstore.js';
 import { pauseSynchronously } from './helpers.js';
 import { plainText } from './formatting.js';
 
@@ -23,8 +23,8 @@ export abstract class FileHarness implements IAuthHarness {
   protected abstract readonly store: CredentialStore;
   protected abstract snapshot(): IFileHarnessSnapshot;
   protected abstract apply(slotId: string, previous: IFileAccount | undefined, target: IFileAccount | undefined): void;
-  /** Guards the operations that write a native credential file. Reads must not depend on it. */
-  protected abstract beforeMutation(): void;
+  /** The harness's own running instances. Detection informs the caller; it never blocks a write. */
+  public abstract readonly processes: IHarnessProcessControl;
   /** Raw bytes of the native files a snapshot's credentials are taken from, in a fixed order. */
   protected abstract nativeSources(): (string | null)[];
   protected abstract inspect(credential: Record<string, unknown>, slotId: string): IFileAccount;
@@ -76,7 +76,66 @@ export abstract class FileHarness implements IAuthHarness {
     for (const account of accounts) {
       if (accounts.some(other => other.id !== account.id && other.label === account.label)) account.details.push(`Account ID: ${account.id}`);
     }
-    return { accounts, saveUnavailableReason: snapshot.unavailable };
+    return { accounts, saveUnavailableReason: snapshot.unavailable, credentialDrift: snapshot.unavailable ? [] : this.credentialDrift(snapshot) };
+  }
+
+  /**
+   * Credential slots that no longer hold the account the last switch wrote.
+   *
+   * A running harness refreshes its login on its own schedule and writes the result to the same
+   * file, so a switch performed underneath one can be undone minutes later without any error. The
+   * recorded hash detects that the file changed at all; comparing the account distinguishes the
+   * benign case -- the switched-in account rotating its own token -- from the previous login coming
+   * back. Detection is advisory and never turns a read into a failure.
+   */
+  private credentialDrift(snapshotArg: IFileHarnessSnapshot): IHarnessCredentialDrift[] {
+    let records: ISwitchRecord[];
+    try { records = this.store.switchRecords(); } catch { return []; }
+    const drift: IHarnessCredentialDrift[] = [];
+    for (const record of records) {
+      try {
+        const active = snapshotArg.accounts.find(account => account.slotId === record.slotId);
+        if (active && credentialHash(JSON.stringify(active.credential)) === record.credentialHash) continue;
+        const currentAccountId = active ? this.store.id(active.slotId, active.identity) : null;
+        if (currentAccountId !== null && currentAccountId === record.accountId) continue;
+        drift.push({
+          slotId: record.slotId, expectedAccountId: record.accountId, expectedLabel: this.savedLabel(record.accountId),
+          currentAccountId, currentLabel: active?.label ?? null,
+          currentIsSaved: currentAccountId !== null && this.savedLabel(currentAccountId) !== null,
+          switchedAt: record.switchedAt,
+        });
+      } catch { /* One unreadable record must not hide the rest of the state. */ }
+    }
+    return drift;
+  }
+  private savedLabel(accountIdArg: string): string | null {
+    try { return this.store.read(accountIdArg).label; } catch { return null; }
+  }
+  /** Instances that keep a replaced or cleared login in memory until they are restarted. */
+  private runningCaveat(kindArg: 'replaced' | 'cleared'): string[] {
+    let count: number;
+    try { count = this.processes.list().length; }
+    catch { return [`Could not check for running ${this.label} processes. If any are running, restart them: an unrestarted instance can write its previous login back.`]; }
+    if (!count) return [];
+    return [`${count} ${this.label} process(es) are still running. They keep the previous login in memory until they are restarted, and a token refresh by one of them can `
+      + `${kindArg === 'replaced' ? 'overwrite the credential file with the previous account' : 'write the cleared login back into the credential file'}. `
+      + `Restart them, then check authswitch ${this.id} active.`];
+  }
+  /**
+   * Record what the credential file holds now, so a later overwrite is detectable.
+   *
+   * The hash is taken from the file after the write, not from the incoming credential, so it is
+   * exactly what a later read computes. A recording failure never invalidates a completed switch.
+   */
+  private recordActivation(slotIdArg: string, accountIdArg: string): string[] {
+    try {
+      const active = this.snapshot().accounts.find(account => account.slotId === slotIdArg);
+      if (!active || this.store.id(active.slotId, active.identity) !== accountIdArg) {
+        return [`The credential file does not hold the expected account after this operation; check authswitch ${this.id} active.`];
+      }
+      this.store.recordSwitch({ slotId: slotIdArg, accountId: accountIdArg, credentialHash: credentialHash(JSON.stringify(active.credential)) });
+      return [];
+    } catch { return [`The login was written, but this switch could not be recorded for later credential checks.`]; }
   }
   protected readCredential(id: string): IFileAccount {
     const active = this.snapshot().accounts.find(account => this.store.id(account.slotId, account.identity) === id);
@@ -89,14 +148,14 @@ export abstract class FileHarness implements IAuthHarness {
   /** Backend-only login handoff. Preserve the outgoing credential before replacing its slot. */
   public activateCredential(slotId: string, credential: Record<string, unknown>): IHarnessOutcome {
     return this.outcome(() => {
-      this.beforeMutation();
       const target = this.inspect(credential, slotId);
       const snapshot = this.snapshot();
       if (snapshot.unavailable) throw new Error(snapshot.unavailable);
       const previous = snapshot.accounts.find(account => account.slotId === slotId);
       if (previous) this.store.save(previous);
       this.apply(slotId, previous, target);
-      return `Activated ${plainText(target.label)} (${plainText(slotId)}).`;
+      return [`Activated ${plainText(target.label)} (${plainText(slotId)}).`,
+        ...this.recordActivation(slotId, this.store.id(slotId, target.identity)), ...this.runningCaveat('replaced')];
     });
   }
   public resolveAccount(reference: string): { id: string } | { candidates: string[] } {
@@ -106,36 +165,41 @@ export abstract class FileHarness implements IAuthHarness {
     const matches = exact.length ? exact : accounts.filter(account => account.label.toLowerCase().startsWith(reference.toLowerCase()));
     return matches.length === 1 ? { id: matches[0].id } : { candidates: matches.map(account => `${account.slotId}:${account.label} (${account.id})`) };
   }
-  private outcome(action: () => string): IHarnessOutcome {
-    try { return this.store.locked(() => ({ lines: [action()], problems: [] })); }
+  private outcome(action: () => string | string[]): IHarnessOutcome {
+    try { return this.store.locked(() => { const lines = action(); return { lines: Array.isArray(lines) ? lines : [lines], problems: [] }; }); }
     catch (error) { return { lines: [], problems: [error instanceof Error ? error.message : 'Credential operation failed.'] }; }
   }
   public saveCurrent(options: { keepActive: boolean; accountId?: string }): IHarnessOutcome {
     return this.outcome(() => {
-      // Keeping the login in place only reads the native files, so a running harness is no reason to refuse.
-      if (!options.keepActive) this.beforeMutation();
       const snapshot = this.stableSnapshot();
       if (snapshot.unavailable) throw new Error(snapshot.unavailable);
       const matches = snapshot.accounts.filter(account => !options.accountId || this.store.id(account.slotId, account.identity) === options.accountId || account.slotId === options.accountId || account.label === options.accountId);
       if (matches.length !== 1) throw new Error(matches.length ? 'Several logins are active. Select the account or provider to save.' : 'No matching active login to save.');
       const active = matches[0];
       this.store.save(active);
-      if (!options.keepActive) this.apply(active.slotId, active, undefined);
-      return `Saved ${plainText(active.label)} (${plainText(active.slotId)})${options.keepActive ? '; login remains in place.' : `. Start ${this.label} to log in again.`}`;
+      if (options.keepActive) return `Saved ${plainText(active.label)} (${plainText(active.slotId)}); login remains in place.`;
+      this.apply(active.slotId, active, undefined);
+      const cleared: string[] = [];
+      try { this.store.clearSwitch(active.slotId); }
+      catch { cleared.push('The login was cleared, but its switch record could not be removed.'); }
+      return [`Saved ${plainText(active.label)} (${plainText(active.slotId)}). Start ${this.label} to log in again.`, ...cleared, ...this.runningCaveat('cleared')];
     });
   }
   public switchAccount(id: string): IHarnessOutcome {
     return this.outcome(() => {
-      this.beforeMutation();
       const target = this.saved(this.store.read(id));
       const snapshot = this.snapshot();
       if (snapshot.unavailable) throw new Error(snapshot.unavailable);
       const previous = snapshot.accounts.find(account => account.slotId === target.slotId);
       // Refresh the outgoing stash even when this account was already saved.
       if (previous) this.store.save(previous);
-      if (previous?.identity === target.identity) return `${plainText(target.label)} is already active; its latest credential is saved.`;
+      // Re-running a switch for the active account re-arms drift detection against its newest bytes.
+      if (previous?.identity === target.identity) {
+        return [`${plainText(target.label)} is already active; its latest credential is saved.`, ...this.recordActivation(target.slotId, id)];
+      }
       this.apply(target.slotId, previous, target);
-      return `Activated ${plainText(target.label)} (${plainText(target.slotId)}). Start ${this.label} to use it.`;
+      return [`Activated ${plainText(target.label)} (${plainText(target.slotId)}). Start ${this.label} to use it.`,
+        ...this.recordActivation(target.slotId, id), ...this.runningCaveat('replaced')];
     });
   }
   public removeAccount(id: string): IHarnessOutcome {

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;
+};