@modelprofile.com/authswitch 2.3.0 → 3.1.0

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
@@ -149,7 +188,21 @@ the local file login, so launch-time flags, managed policies and credentials sup
 by embedding applications remain under Claude Code's control.
 
 Claude's direct OAuth profile and usage lookups report the plan, weekly and five-hour
-usage, model-specific windows, and available extra-usage budget information.
+usage, per-model and per-surface windows, and available extra-usage budget information.
+The usage response's `limits[]` rows are the authoritative window list: which
+meters apply, their scope, the service's `severity` (`normal`, `warning`,
+`critical`) and its headline pick are Claude's, so a new per-model weekly limit
+such as **Fable weekly** appears without an authswitch release. `list --json` keeps
+the rows in the service's order; the tables and `limits --json` order them as
+described under **Condensed views**. Rows are classified on their
+kind and reset group exactly as sent. Labels combine the service's model or surface
+name with the window period, and such a scoped row is treated as a feature limit.
+Rows in a reset group authswitch cannot represent (anything but the five-hour
+session and the weekly window) are not shown; one **Unsupported limits**
+availability fact names them. A malformed row, or a `limits` value that is not a
+list, makes the whole usage lookup unavailable rather than partially guessed.
+Responses without `limits[]` rows fall back to the older keyed weekly, five-hour
+and model windows.
 These endpoints require the `user:profile` scope and may reject expired or restricted
 logins. A null reset timestamp is shown as **Not scheduled**. Billing renewal and
 cancellation dates and earned reset credits are unavailable from these endpoints;
@@ -201,7 +254,8 @@ an uncertain request. `--json` remains a list-only option.
 ### Management dashboard
 
 `authswitch --tui` opens a resizable account table with subscription, usage and
-reset availability, usage bars, scrollable account details and an activity log.
+reset availability, usage bars for the lead window and the next general window,
+scrollable account details and an activity log.
 With multiple registered adapters, a harness selector switches the view; account
 selection and mutations always belong to the displayed harness. Status loads
 incrementally through each account's read-only API, without activating it.
@@ -283,17 +337,25 @@ output to Codex. Each section includes saved accounts and an identifiable active
 login even if it has never been saved. `*` marks the active account, and the saved
 marker checks the credential itself rather than just the existence of metadata.
 
-The overview compares login state, plan provenance, weekly usage, earned resets and
-the weekly reset countdown. Countdowns use days, hours and minutes, such as
+The overview compares login state, plan provenance, lead-window usage (the
+provider's headline window, otherwise weekly), earned resets and that window's
+reset countdown. Countdowns use days, hours and minutes, such as
 `7d 5h 6min`;
 `<1min` means less than a minute remains and `due` means the reported deadline has
 passed, without claiming the service has refreshed the quota. All countdowns share
 the same snapshot time.
-Usage and countdown refer to the same general account window, preferring weekly.
-If no weekly window is reported, the longest general window is shown with its
-actual duration. Other exhausted general windows retain their own reset warning.
-Feature limits such as Spark and code review have a separate table and never
-determine the general summary. The TUI uses the same weekly-first selection.
+Usage and countdown refer to the same window. When the provider picks a headline
+window (Claude does, for example its Fable weekly limit), that window leads.
+Otherwise the
+general account window leads, preferring weekly; if no weekly window is reported,
+the longest general window is shown with its actual duration. Other exhausted
+general windows retain their own reset warning. A general window is named by its
+period (`Weekly`, `5h`) unless another shown general window has the same period; a
+feature limit, or a general window sharing its period, is named by its label
+(`Fable weekly: 100% used`, `Claude weekly (weekly_oauth) exhausted`). Feature
+limits such as Spark and code review have a separate table and determine the
+summary only when the provider picks one as its headline. The TUI uses the same
+selection and names.
 Window durations come from the provider, not from the plan name or
 primary/secondary position; a Pro account with only a general weekly window gets
 no invented 5-hour limit.
@@ -319,9 +381,9 @@ Account limits
 ┌──────────────────────┬─────────────────────────┬───────────────────────┬────────┬───────────────┐
 │ Provider             │ Account                 │ Limit type            │ Used % │     Resets in │
 ├──────────────────────┼─────────────────────────┼───────────────────────┼────────┼───────────────┤
-│ Claude Code          │ phil@example.com        │ Claude weekly         │    88% │         4d 3h │
-│ Claude Code          │ phil@example.com        │ Claude five-hour      │    63% │         1h 2m │
-│ Claude Code          │ phil@example.com        │ Opus weekly           │   100% │         4d 3h │
+│ Claude Code          │ phil@example.com        │ Claude weekly         │    75% │         4d 3h │
+│ Claude Code          │ phil@example.com        │ Claude five-hour      │    12% │         1h 2m │
+│ Claude Code          │ phil@example.com        │ Fable weekly          │    88% │         2d 5h │
 │ Codex                │ alice@example.com       │ Codex secondary       │    12% │         3d 4h │
 │ Codex                │ alice@example.com       │ Codex primary         │    37% │        2h 13m │
 │ Codex                │ alice@example.com       │ Code review secondary │   100% │        3h 59m │
@@ -343,9 +405,18 @@ account never blanks another's numbers. `not scheduled` means the provider repor
 usage without a reset deadline; it is not the same as `n/a`.
 
 Limit types are the provider's own window names, ordered general-before-feature and
-weekly-first within an account. The provider column names the harness, qualified by
+weekly-first within an account. Claude's per-model and per-surface limits carry the
+service's name (`Fable weekly`); an unscoped Claude meter other than the five-hour
+session and the weekly total keeps its kind in parentheses
+(`Claude weekly (weekly_oauth)`). The provider column names the harness, qualified by
 the credential slot when a harness owns several (`OpenCode / openai`).
 
+**Used %** is coloured by the provider's own reading when it reports one: orange for
+`warning`, red for `critical`, uncoloured for `normal`. Without a reading, `n/a` is
+orange and an exhausted window (100% or more) is red. Colour is omitted when
+`NO_COLOR` is set, output is not a terminal, or the terminal is narrower than 40
+columns.
+
 `authswitch active` answers "what am I logged in as" for every harness at once:
 
 ```
@@ -369,6 +440,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,19 +472,27 @@ 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 provider's `severity` (`normal`, `warning`, `critical`, or null when
+it gave none) and `headline` (true for the window the provider picks for a
+single-value summary), 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.
+  typed `summary` fields. Missing fields remain omitted, not replaced by zero;
+  `summary.usageWindows[]` carries `severity` and `headline` only when the provider
+  reported them.
 
 JSON retains full fact strings and absolute ISO reset/expiry timestamps. It exports
 the credential-free adapter contract, never credentials, raw HTTP responses or
@@ -502,11 +597,18 @@ explicit zeroes remain zero. A successful reset-detail lookup supplies the summa
 count; if it fails, the limits response can still supply availability.
 
 Each usage window may set `scope: 'account' | 'feature'` (default `account`).
-Adapters mark model-specific or feature-specific quotas as `feature` so those
-quotas remain available in JSON and details without distorting the general
-account summary. Weekly windows are identified by `durationSeconds: 604800`;
+Adapters mark model-specific or feature-specific quotas as `feature`; those quotas
+appear in the feature tables, JSON and details and lead the account summary only
+when the provider marks one as its headline (see below). Weekly windows are identified by `durationSeconds: 604800`;
 neither window labels nor plan names are parsed to infer limits.
 
+A window may also carry the provider's own reading: `severity?: TUsageSeverity`
+(`'normal' | 'warning' | 'critical'`) and `headline?: true` for the window the
+provider picks for a single-value summary. Adapters set them only when the provider
+reports them, never from local thresholds. A headline window leads the account
+summary whatever its scope; the first one in the adapter's order wins if several are
+marked.
+
 Optional `summary.billing` contains provider-reported `hasActiveSubscription`,
 `autoRenew`, `renewsAt`, `cancelsAt`, and `expiresAt`, independent of the plan name.
 Dates are ISO UTC and omitted
@@ -529,6 +631,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 +647,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.1.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, IHarnessUsageWindow } from './interfaces.harness.js';
 import { plainText } from './formatting.js';
 
 export interface IAccountRow {
@@ -41,31 +41,65 @@ 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';
 };
-type TUsageWindow = NonNullable<IHarnessStatusSummary['usageWindows']>[number];
 type TAccountStatusRow = Pick<IAccountRow, 'status'>;
-export const usagePeriod = (windowArg: TUsageWindow): string => windowArg.durationSeconds === 604800 ? 'Weekly' : duration(windowArg.durationSeconds);
+/**
+ * How a single-value summary names a window among the windows it shows. An account window is named by
+ * its period while it is the only shown account window of that period; a feature window, or an account
+ * window sharing its period with another, is named by its own label, so no meter reads as another's.
+ */
+export const usageWindowName = (windowArg: IHarnessUsageWindow, shownArg: readonly IHarnessUsageWindow[]): string =>
+  windowArg.scope === 'feature' || shownArg.some(other => other !== windowArg && other.scope !== 'feature' && other.durationSeconds === windowArg.durationSeconds)
+    ? plainText(windowArg.label)
+    : windowArg.durationSeconds === 604800 ? 'Weekly' : duration(windowArg.durationSeconds);
 /** Order by scope and actual duration: a provider's primary slot need not be five hours. */
-export const orderedUsageWindows = (windowsArg: readonly TUsageWindow[] = []): TUsageWindow[] => [...windowsArg].sort((left, right) =>
+export const orderedUsageWindows = (windowsArg: readonly IHarnessUsageWindow[] = []): IHarnessUsageWindow[] => [...windowsArg].sort((left, right) =>
   Number(left.scope === 'feature') - Number(right.scope === 'feature') ||
   Number(left.durationSeconds !== 604800) - Number(right.durationSeconds !== 604800) || right.durationSeconds - left.durationSeconds);
-export const accountUsageWindows = (rowArg: TAccountStatusRow): TUsageWindow[] | undefined => {
+/**
+ * The windows a single-value summary shows, lead window first: the provider's headline pick, whatever
+ * its scope, then the account windows in display order. Other feature quotas never lead a summary.
+ */
+export const accountUsageWindows = (rowArg: TAccountStatusRow): IHarnessUsageWindow[] | undefined => {
   const windows = rowArg.status?.summary?.usageWindows;
-  return windows === undefined ? undefined : orderedUsageWindows(windows.filter(window => window.scope !== 'feature'));
+  if (windows === undefined) return undefined;
+  const headline = windows.find(window => window.headline === true);
+  const accountWindows = orderedUsageWindows(windows.filter(window => window !== headline && window.scope !== 'feature'));
+  return headline === undefined ? accountWindows : [headline, ...accountWindows];
 };
 export const accountUsage = (rowArg: TAccountStatusRow): string => {
   const windows = accountUsageWindows(rowArg);
-  return windows?.length ? `${usagePeriod(windows[0])}: ${windows[0].usedPercent}% used` : windows ? 'None reported' : rowArg.status ? 'Unavailable' : 'Loading';
+  return windows?.length ? `${usageWindowName(windows[0], windows)}: ${windows[0].usedPercent}% used` : windows ? 'None reported' : rowArg.status ? 'Unavailable' : 'Loading';
 };
 export const accountResets = (rowArg: IAccountRow): string => rowArg.status?.summary?.resets === undefined ? rowArg.status ? 'Unavailable' : 'Loading' : String(rowArg.status.summary.resets.available);
 export const accountNextReset = (rowArg: TAccountStatusRow, nowArg = Date.now()): string => {
@@ -76,7 +110,7 @@ export const accountQuotaSummary = (rowArg: TAccountStatusRow, nowArg: number):
   const windows = accountUsageWindows(rowArg);
   return [accountUsage(rowArg), ...(windows?.length ? [
     `Reset in: ${accountNextReset(rowArg, nowArg)}`,
-    ...windows.slice(1).filter(window => window.usedPercent >= 100).map(window => `${usagePeriod(window)} exhausted\nResets in: ${until(window.resetAt, nowArg)}`),
+    ...windows.slice(1).filter(window => window.usedPercent >= 100).map(window => `${usageWindowName(window, windows)} exhausted\nResets in: ${until(window.resetAt, nowArg)}`),
   ] : [])].join('\n');
 };
 export const accountState = (rowArg: IAccountRow): string => `${rowArg.account.isActive ? '* active, ' : ''}${rowArg.account.isStashed ? 'saved' : 'not saved'}`;

package/ts/classes.accountlist.ts

@@ -16,7 +16,7 @@ const publicStatus = (statusArg: IHarnessAccountStatus): IHarnessAccountStatus =
     ...(summary === undefined ? {} : { summary: {
       ...(summary.subscription === undefined ? {} : { subscription: { plan: summary.subscription.plan, source: summary.subscription.source } }),
       ...(summary.billing === undefined ? {} : { billing: { hasActiveSubscription: summary.billing.hasActiveSubscription, autoRenew: summary.billing.autoRenew, renewsAt: summary.billing.renewsAt, cancelsAt: summary.billing.cancelsAt, expiresAt: summary.billing.expiresAt } }),
-      ...(summary.usageWindows === undefined ? {} : { usageWindows: summary.usageWindows.map(({ label, scope, durationSeconds, usedPercent, resetAt }) => ({ label, scope, durationSeconds, usedPercent, resetAt })) }),
+      ...(summary.usageWindows === undefined ? {} : { usageWindows: summary.usageWindows.map(({ label, scope, durationSeconds, usedPercent, resetAt, severity, headline }) => ({ label, scope, durationSeconds, usedPercent, resetAt, severity, headline })) }),
       ...(summary.resets === undefined ? {} : { resets: {
         available: summary.resets.available,
         ...(summary.resets.details === undefined ? {} : { details: summary.resets.details.map(({ status, kind, expiresAt }) => ({ status, kind, expiresAt })) }),
@@ -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.claudestatus.ts

@@ -1,8 +1,107 @@
 import { credentialRecord, credentialText } from './classes.credentialstore.js';
-import type { IHarnessAccountStatus, IHarnessStatusSummary } from './interfaces.harness.js';
+import { plainText } from './formatting.js';
+import type { IHarnessAccountStatus, IHarnessUsageWindow, TUsageSeverity } from './interfaces.harness.js';
 
 class ClaudeStatusError extends Error {}
 
+interface IClaudeUsageWindows {
+  windows: IHarnessUsageWindow[];
+  /** Server rows whose reset group the window model cannot represent, named by kind and group. */
+  unsupported: string[];
+}
+
+/** Reset times are normalised to ISO 8601 UTC; an unparsable one rejects the whole usage response. */
+const resetTimestamp = (value: unknown): string | null => value == null ? null : new Date(String(value)).toISOString();
+
+const SERVER_NAME_LENGTH = 64;
+
+/** A server-supplied name becomes label text: no control characters, bounded by code points, and never blank. */
+const serverName = (value: unknown): string => {
+  const name = typeof value === 'string' ? Array.from(plainText(value).trim()).slice(0, SERVER_NAME_LENGTH).join('').trimEnd() : '';
+  if (!name) throw new Error('Unsupported Claude usage name.');
+  return name;
+};
+
+/** Keyed windows, read only from a usage body that carries no limits[] rows. */
+const KEYED_WINDOWS = [
+  ['five_hour', 'Claude five-hour', 18000, 'account'], ['seven_day', 'Claude weekly', 604800, 'account'],
+  ['seven_day_oauth_apps', 'OAuth apps weekly', 604800, 'feature'], ['seven_day_opus', 'Opus weekly', 604800, 'feature'], ['seven_day_sonnet', 'Sonnet weekly', 604800, 'feature'],
+] as const;
+
+const keyedWindows = (usage: Record<string, unknown>): IHarnessUsageWindow[] => {
+  const windows: IHarnessUsageWindow[] = [];
+  for (const [key, label, durationSeconds, scope] of KEYED_WINDOWS) {
+    if (usage[key] == null) continue;
+    const window = credentialRecord(usage[key]);
+    if (window.utilization == null) continue;
+    if (typeof window.utilization !== 'number' || !Number.isFinite(window.utilization) || window.utilization < 0) throw new Error('Unsupported Claude usage utilization.');
+    windows.push({ label, durationSeconds, scope, usedPercent: window.utilization, resetAt: resetTimestamp(window.resets_at) });
+  }
+  return windows;
+};
+
+/**
+ * The limits[] row groups the window model represents: each group's duration, the period word its
+ * labels use, and the kind of the group's unscoped account meter, which keeps the plain label.
+ */
+const LIMIT_GROUPS: ReadonlyMap<string, { durationSeconds: number; period: string; accountKind: string }> = new Map([
+  ['session', { durationSeconds: 18000, period: 'five-hour', accountKind: 'session' }],
+  ['weekly', { durationSeconds: 604800, period: 'weekly', accountKind: 'weekly_all' }],
+]);
+
+const isUsageSeverity = (value: unknown): value is TUsageSeverity => value === 'normal' || value === 'warning' || value === 'critical';
+
+/** A scope part is absent (null or omitted) or names the model or surface a row is for. */
+const scopeSubject = (value: unknown): string | undefined => value == null ? undefined : serverName(credentialRecord(value).display_name);
+
+/**
+ * The server's usage rows, in the server's order. An unscoped row is an account meter; a model- or
+ * surface-scoped row is a feature quota named by the server's own label. Rows are classified on the
+ * kind and group exactly as sent; only the text shown to users is sanitised. Every row is validated
+ * before a row in an unrepresentable group is set aside, so a malformed row can never hide behind one.
+ */
+const limitWindows = (rows: readonly unknown[]): IClaudeUsageWindows => {
+  const windows: IHarnessUsageWindow[] = [];
+  const unsupported = new Set<string>();
+  for (const value of rows) {
+    const row = credentialRecord(value);
+    const { kind, group } = row;
+    if (typeof kind !== 'string' || typeof group !== 'string') throw new Error('Unsupported Claude usage meter.');
+    const kindName = serverName(kind);
+    const groupName = serverName(group);
+    const usedPercent = row.percent;
+    if (typeof usedPercent !== 'number' || !Number.isFinite(usedPercent) || usedPercent < 0) throw new Error('Unsupported Claude usage percentage.');
+    const resetAt = resetTimestamp(row.resets_at);
+    const scope: Record<string, unknown> = row.scope == null ? {} : credentialRecord(row.scope);
+    const model = scopeSubject(scope.model);
+    const surface = scopeSubject(scope.surface);
+    const subject = model ?? surface;
+    const meter = LIMIT_GROUPS.get(group);
+    if (!meter) {
+      unsupported.add(`${kindName} in group ${groupName}`);
+      continue;
+    }
+    const severity = row.severity;
+    windows.push({
+      label: subject === undefined ? `Claude ${meter.period}${kind === meter.accountKind ? '' : ` (${kindName})`}` : `${subject} ${meter.period}`,
+      durationSeconds: meter.durationSeconds, scope: subject === undefined ? 'account' : 'feature', usedPercent, resetAt,
+      ...(isUsageSeverity(severity) ? { severity } : {}),
+      ...(row.is_active === true ? { headline: true as const } : {}),
+    });
+  }
+  return { windows, unsupported: [...unsupported] };
+};
+
+/**
+ * A usage body's windows. Its limits[] rows are authoritative whenever the server sends any; the keyed
+ * fields describe the same meters and are read only from a body without rows.
+ */
+const claudeUsageWindows = (usage: Record<string, unknown>): IClaudeUsageWindows => {
+  const limits = usage.limits;
+  if (limits != null && !Array.isArray(limits)) throw new Error('Unsupported Claude usage limits.');
+  return Array.isArray(limits) && limits.length ? limitWindows(limits) : { windows: keyedWindows(usage), unsupported: [] };
+};
+
 /** Read-only Claude Code OAuth account endpoints. No refresh, inference, or browser session is used. */
 export class ClaudeAccountStatus {
   constructor(private readonly fetcher: typeof fetch = globalThis.fetch) {}
@@ -64,18 +163,7 @@ export class ClaudeAccountStatus {
     } else result.problems.push(`Profile: ${profile.reason instanceof ClaudeStatusError ? profile.reason.message : 'Lookup failed.'}`);
     if (usage.status === 'fulfilled') {
       try {
-        const windows: NonNullable<IHarnessStatusSummary['usageWindows']> = [];
-        for (const [key, label, durationSeconds, scope] of [
-          ['five_hour', 'Claude five-hour', 18000, 'account'], ['seven_day', 'Claude weekly', 604800, 'account'],
-          ['seven_day_oauth_apps', 'OAuth apps weekly', 604800, 'feature'], ['seven_day_opus', 'Opus weekly', 604800, 'feature'], ['seven_day_sonnet', 'Sonnet weekly', 604800, 'feature'],
-        ] as const) {
-          if (usage.value[key] == null) continue;
-          const window = credentialRecord(usage.value[key]);
-          if (window.utilization == null) continue;
-          if (typeof window.utilization !== 'number' || !Number.isFinite(window.utilization) || window.utilization < 0) throw new Error();
-          const resetAt = window.resets_at == null ? null : new Date(String(window.resets_at)).toISOString();
-          windows.push({ label, durationSeconds, scope, usedPercent: window.utilization, resetAt });
-        }
+        const { windows, unsupported } = claudeUsageWindows(usage.value);
         result.summary = { ...result.summary, usageWindows: windows };
         for (const window of windows) result.facts.push({ section: 'Usage', summaryKey: 'usageWindows', label: window.label, value: `${window.usedPercent}% used; ${window.resetAt ? 'resets ' + window.resetAt : 'reset not scheduled'}` });
         if (usage.value.extra_usage != null) {
@@ -90,7 +178,7 @@ export class ClaudeAccountStatus {
           }
           if (limit !== undefined && limit > 0 && used !== undefined) result.facts.push({ section: 'Extra usage', label: 'Monthly budget used', value: `${Math.round(used / limit * 10000) / 100}%` });
         }
-        if (Array.isArray(usage.value.limits) && usage.value.limits.length) result.facts.push({ section: 'Availability', label: 'Additional limits', value: 'The service also returned limits without a supported reset-window contract.' });
+        if (unsupported.length) result.facts.push({ section: 'Availability', label: 'Unsupported limits', value: `The service returned limits without a supported reset window, which are not shown: ${unsupported.join(', ')}.` });
       } catch { result.problems.push('Claude usage response is unsupported; missing values were not inferred.'); }
     } else result.problems.push(`Usage: ${usage.reason instanceof ClaudeStatusError ? usage.reason.message : 'Lookup failed.'}`);
     result.facts.push({ section: 'Availability', label: 'Billing dates and earned resets', value: 'Renewal dates, cancellation dates and earned reset credits are not exposed by these Claude Code endpoints.' });