claude-multiacc 2.0.57 → 2.0.59

package/README.md

@@ -59,6 +59,7 @@ MAC (source of truth)                      SERVER (mirror)
     server.token / .credentials.json
     (or the login lives in the macOS Keychain — see below)
   selection.log  sync.log  health.log      /usr/local/bin/claude -> repo shim
+  mcp-oauth.json (MCP OAuth, never synced)
 repo bin/ first on PATH (rc block + hook)  /root/claude-multiacc/  (addon repo)
 ```
 
@@ -297,6 +298,18 @@ account's `.credentials.json` (0600), or its macOS Keychain item.
 > identity checked out prunes every sibling; `remove` deletes every item.
 > `python3 lib/keychain.py prune <acct dir>` prunes by hand (only when the canonical item
 > is a live login; it never writes).
+> **A login, not any credentials document.** The same document (file or Keychain item) also
+> holds the client's MCP servers' OAuth state (`mcpOAuth`), and from ssh/tmux Claude Code
+> writes a `.credentials.json` holding only that once an OAuth MCP server is discovered. The
+> pool counts a document as a login only when it carries `claudeAiOauth`: one with MCP
+> state alone leaves the account to its Keychain login or `server.token` (`list` shows
+> `auth=token`, or `NO-LOGIN`), expiry is read from the login object alone, such a rewrite
+> never heals an `.expired` park, and every login multiacc writes (refresh, migration,
+> `import --creds`) lands INTO the document with its MCP state kept. The limits pass's
+> refresh and migration write under the client's own `<acct>/.storage-write.lock`, never
+> across the token request: a refresh that finds the lock held skips (the next pass
+> retries), and the rotated login waits for a client write in flight instead of being
+> rolled back by it.
 > Override: `CLAUDE_MULTIACC_KEYCHAIN=0` disables the lookup. This is what keeps idle accounts' telemetry fresh so they win
 selection over busy accounts; without it, stale telemetry ranks neutral and a truly-idle
 account would lose to a busy-but-fresh one. Refresh failures fail open and back off via
@@ -324,7 +337,10 @@ the session → account mapping comes from `<acct>/sessions/<pid>.json`, which t
 maintains only while a run is alive. The shim spawns a short detached poll before `exec`
 (the pid survives `exec`, so it knows the filename) that records the session id — with the
 session's own start time — in `<acct>/.sessions-index`; selection then tail-scans those
-transcripts.
+transcripts. The poll also records which credential the run carries, the portable token
+or the login, by PROCESS (`<acct>/.sessions-via/<pid>`, valid only while the registry's
+`startedAt` matches), so a session the client switches the run to (`/clear`, `/resume`
+inside the TUI) is charged to the same credential when it fails to authenticate.
 
 Fresh account seeding creates `~/.claude/projects` before linking each account, even
 if stock Claude has never run on that machine. For an existing pool with private
@@ -360,6 +376,12 @@ next selection. It has no automatic expiry; full `claude-accounts verify` must p
 access after the organization enables it. `.client-org-cleared` suppresses transcript
 errors recorded before that verification.
 
+An interactive `authentication_failed` parks the credential that run carried. The poll
+tags a session's index line `token` when the shim launched the run on the account's
+portable token, and only such a failure retires the token (`setup-token-invalid`); any
+other is the login's (`auth-error`) — a run that carried no token says nothing about it.
+The verification watermark above supersedes these records too, so a PASS sticks.
+
 The resulting usage marker is tagged `reason=client-rate-limit` and outlives a clean telemetry
 pass while its window is still open — first-hand evidence beats a usage payload that
 disagrees. A **weekly** rejection is absolute: nothing — neither a shim invocation nor the
@@ -441,7 +463,8 @@ Interactive sessions are not retried this way. They get auto-resume, described n
 ## Auto-resume
 
 An interactive `claude` or `codex` session in **tmux** can stop on a usage limit, a failed
-login, an API error or (claude) a crash. It is then **resumed automatically, same session
+login, an API error or (claude) a crash, or show Claude Code's "Critical memory usage"
+warning. It is then **resumed automatically, same session
 id**, on another pooled account with headroom. If a usage limit exhausts that provider's
 usable accounts, it can continue in the other provider with instructions to read the
 original conversation's history. There is no `/exit`, no `--resume` and no
@@ -479,9 +502,26 @@ touch ~/.codex-accounts/autoresume.off    # codex pool off
 CLAUDE_MULTIACC_AUTORESUME=0 claude       # one launch (CODEX_MULTIACC_AUTORESUME=0 codex)
 ```
 
+**Model and effort.** A relaunch keeps the session on the model and effort it last ran
+with, read from the session's own history, so a `/model` or `/effort` switch made after the
+launch counts. A continuation in the other provider starts on the model and effort of the
+same level. Both read the **model catalog**: the copy this release ships, merged with the
+model caches Claude Code and Codex keep in their account dirs, written to
+`<pool>/model-catalog.json`. It sends no request and reads no credential. Every install and
+`self-update` refreshes it in both pools, and each limits pass refreshes its own pool's copy
+once it is an hour old, so the matching follows new models between releases.
+
+```bash
+claude-accounts model-catalog show       # the merged catalog a relaunch matches with
+claude-accounts model-catalog refresh    # rewrite both pools' copies now
+```
+
+`CLAUDE_MULTIACC_MODEL_CATALOG=0` or `CODEX_MULTIACC_MODEL_CATALOG=0` stops the refresh of
+that pool's copy, and `MULTIACC_MODEL_CATALOG=0` stops both.
+
 See [auto-resume: error classes, gates, budgets, logs and limitations](docs/AUTORESUME.md).
 See [continuing between Codex and Claude](docs/AUTORESUME-HANDOFF.md) for history,
-permission handling and the cross-provider opt-out.
+permission handling, model matching and the cross-provider opt-out.
 
 ## MCP servers for every account
 
@@ -562,6 +602,74 @@ claude-accounts mcp apply                        # re-apply now (repair drift)
   seed and launch and the shim's mirror; `claude-accounts mcp …`, sync and the fan-out still
   work.
 
+### MCP OAuth logins: sign in once, every account has it
+
+A server that signs in with OAuth (higgsfield, say) keeps its login in the account's
+**credential store** — `mcpOAuth` in `<acct>/.credentials.json`, or in the account's
+Keychain item — not in `.claude.json`, so the registry cannot carry it. Under the pool a
+server authenticated in one account said *needs authentication* under every other account
+the shim picked (2026-10-19: five separate higgsfield grants in five accounts,
+discovery-only stubs in the rest). The claude pool now shares those logins **on this
+machine**:
+
+```bash
+claude-accounts mcp auth-status              # per server: the pool's login; per account: fresh, stale, own, stub, missing or absent
+claude-accounts mcp auth-status --json
+claude-accounts mcp auth-sync                # harvest, refresh what is due, share into every account, now
+claude-accounts mcp auth-forget higgsfield   # log it out of EVERY account on this machine
+```
+
+- **Harvest**: every account's MCP logins — its file, and its Keychain item when this
+  session can open it — are folded into `<pool>/mcp-oauth.json` (0600). Per server the
+  latest save wins (the largest `expiresAt`: the client stamps it on every save; a login
+  saved without one counts as expiring an hour after it was found, never as the oldest); a
+  discovery-only stub (`accessToken: ""`) never overwrites anything.
+- **Share**: the shim merges the newest login into the picked account right before exec —
+  no network, and python only when an account's credential file or the store changed since
+  that account last looked — and every claude `limits` pass shares into all accounts. A
+  merge goes into a store that exists; a `.credentials.json` is **created** — holding the
+  MCP logins alone, 0600 — only for an account that runs on its setup token (no `.expired`
+  park, not an adopted dir), whose client has nowhere else to read them from in an ssh/tmux
+  session. That file costs the token nothing: a document without `claudeAiOauth` is no
+  Claude login to the shim, the limits pass, the audit or verify (`list` shows `auth=token`),
+  and it is the file the client writes itself once it meets an OAuth server. An account
+  with a Keychain login gets its item updated instead and never a file. A merge takes the
+  client's own lock (`<acct>/.storage-write.lock`), re-reads, changes that one `mcpOAuth` key
+  and nothing else (the Claude login beside it is never rewritten), and keeps the file's
+  mtime. A Keychain item is updated only when it already exists and this session can open
+  it, then read back; one is never created. An account parked with `.expired` gets no
+  Keychain write and no new file until it is back in the pool. A login the account holds of
+  another grant is replaced only when it is provably older.
+- **Refresh**: the limits pass is the only refresher — one login in many accounts must have
+  ONE, because each client refreshes under its own config dir's lock and refresh tokens
+  rotate. A login is refreshed at its authorization server (RFC 8414 metadata, the refresh
+  grant with `resource` = the server URL) two hours before it expires, or at half its
+  lifetime when that is shorter (never twice per half-lifetime), long before a client's own
+  5-minute window, then shared everywhere. A failure backs off 15 min, doubling to 6 h (`mcp
+  auth-sync --force` retries now); a refused refresh token (`invalid_grant`) shows as **NEEDS
+  RE-AUTH**: sign in once in any account (`/mcp`) and that new login replaces it everywhere.
+  A login with a copy in a Keychain item this session cannot open is left to a pass that
+  can (a Terminal on the Mac, the scheduled agent) until 20 minutes before it expires.
+- **Nothing is shared without that refresher**: not with
+  `CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0`, not by a launch when no refreshing limits pass ran in
+  the last hour, and not a login within the clients' own 5-minute window, refused by its
+  server, or whose failing refresh would next try too late. Each account keeps what it holds;
+  `auth-status` says why (`NOT shared: …`, `sharing paused: …`).
+- **Machine-local**: `mcp-oauth.json` is never synced or fanned out — a grant belongs to the
+  machine it was issued on, so each Mac signs in once.
+- **Logging out**: a `/mcp` "Clear authentication", `claude mcp login <server>` or a
+  re-authentication in ANY one account revokes the stored login at the server (when it
+  supports revocation — higgsfield does) — and under the pool that login is every account's.
+  So the pool retires it everywhere the moment it sees the key gone or blanked in an account
+  that held it; sign in once in any account and the new login is shared again. `mcp
+  auth-forget NAME` is the same logout from the operator's side: it drops the login from the
+  pool and every account store, and a copy it could not reach (a Keychain item this session
+  cannot open) stays ignored and is cleared by a later pass.
+- **Kill switches**: `CLAUDE_MULTIACC_MCP_OAUTH=0` stops sharing (the shim's merge and the
+  limits pass's sync); `CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0` never refreshes — and so shares
+  nothing. `auth-status` and `auth-forget` always run. Claude pool only: Codex keeps MCP
+  OAuth in its own store, and `codex-accounts mcp auth-…` says so.
+
 app-robot tasks are different: the panel launches Claude with `--strict-mcp-config` and a
 merged MCP document (`agent_mcp.servers_for`) and Codex with the same document as `-c`
 overrides, so a server every task must see is added there — never with `claude mcp add` on a