claude-multiacc 2.0.58 → 2.0.59

package/lib/mcp_oauth.py

@@ -0,0 +1,1748 @@
+#!/usr/bin/env python3
+"""MCP OAuth logins, shared by every pooled Claude account on this machine.
+
+WHY (2026-10-19). Claude Code keeps an MCP server's OAuth login in the config dir's
+credential store, next to its own login: ONE JSON document holding `claudeAiOauth` (the
+Claude login) and `mcpOAuth` (MCP servers' OAuth state, keyed
+`<serverName>|<sha256(JSON.stringify({type,url,headers}))[:16]>`). Under the pool every
+launch runs in another config dir, so a server authenticated in one account said "needs
+authentication" under every other account the shim picked: five separate higgsfield
+grants sat in five accounts, and the rest held discovery-only stubs (`accessToken: ""`).
+
+The client's store (Claude Code 2.1.303/2.1.304, read out of the binary):
+  * macOS: the login Keychain item `Claude Code-credentials-<sha256(dir)[:8]>` under
+    `$USER` (lib/keychain.py), with `<dir>/.credentials.json` (0600) as the fallback.
+    read() is the Keychain document when there is one, else the file. A session that
+    cannot open the keychain — ssh, tmux, background, `security` exit 36 — reads and
+    writes the FILE, and every session on the operator's Mac is one: there the file holds
+    `mcpOAuth` alone (the Claude login is the shim's setup token). Elsewhere: the file.
+  * every write takes a proper-lockfile lock — the DIRECTORY `<dir>/.storage-write.lock`,
+    stale after 15 s, its mtime refreshed by the holder — then re-reads, applies its one
+    change and writes the whole document back.
+  * an MCP entry: serverName, serverUrl, accessToken, refreshToken, expiresAt (epoch ms,
+    now + expires_in on every save — and NO expiresAt when the answer had no
+    expires_in), scope, issuer, clientId, clientSecret?, redirectUri, discoveryState
+    {authorizationServerUrl, authServerMetadataUrl, …}, stepUpScope?. tokens() re-reads
+    the store on every call and refreshes once the access token has 300 s or less left,
+    under a lock of ITS OWN config dir (`mcp-refresh-<key>.lock`); a refresh answered
+    without a refresh token keeps the old one.
+  * a refresh refused with invalid_grant blanks the entry (tokens gone, expiresAt 0) —
+    only while the store still holds the tokens that client was using. /mcp "Clear
+    authentication" and `claude mcp login` REVOKE the stored tokens at the authorization
+    server (RFC 7009, when its metadata names a revocation_endpoint), then delete or
+    blank the entry; a re-authentication revokes the tokens it replaced.
+
+So the pool keeps one MACHINE-LOCAL store, ROOT/mcp-oauth.json (0600, NEVER synced or
+fanned out: a grant belongs to this machine, and two machines refreshing one rotating
+grant strand one of them — the codex auth.json rule), and four verbs work on it:
+
+  harvest     every account's `mcpOAuth`, from its file and from its Keychain item when
+              this session can read it. An entry is a LOGIN when its access or refresh
+              token is a non-empty string. Per key the winner is the largest expiresAt
+              (the latest save) — a login saved without one ranks, and is kept, as if it
+              lived ASSUMED_LIFETIME_S from the harvest — ties going to one with a
+              refresh token, then to the store's own copy; a login the store marked
+              needs_reauth loses to any OTHER grant. Stubs never overwrite anything, and
+              tokens the pool's own refreshes replaced, or that `forget` or a clear
+              retired, are ignored wherever they turn up.
+  distribute  the winner, into each account store that exists and lacks the key, holds a
+              stub, or holds a provably older login (an earlier expiresAt, or tokens the
+              pool replaced) — a login of another grant whose age cannot be compared
+              stays. Under the client's own lock, re-reading first, touching that one key
+              and nothing else — `claudeAiOauth` above all. A .credentials.json is
+              CREATED, holding `mcpOAuth` alone, only for an account that runs on its
+              portable token (a non-empty server.token, no `.expired` park, not a
+              symlinked dir) and has no file or link of that name: every reader counts a
+              document as a login only when it carries `claudeAiOauth` (bin/claude
+              file_login, lib/audit.py file_has_login), so that file costs the token
+              nothing — it is the very file the client writes itself once it meets an
+              OAuth server from a session that cannot open the Keychain — and it is all
+              such a client has to read MCP logins from. Every other account has a store
+              of its own already, or nothing to run on. A Keychain item is written only
+              when it EXISTS and this session can read it, then read back; an absent item
+              is never created (the client reads the file then, and a new item would hide
+              the file from every session that can open the keychain). A merged file
+              keeps its mtime: bin/claude and lib/audit.py read a .credentials.json that
+              carries a login and is newer than an `.expired` park as a fresh login and
+              lift the park, and an MCP merge is not one — so a parked account gets no
+              Keychain write (and no created file) either until it is back in the pool.
+              A login is shared only while the pool is its ONE refresher, ahead of every
+              client: clients refresh under their own config dir's lock, so accounts
+              holding one rotating grant would otherwise refresh it at once and strand
+              one (a server that detects reuse revokes the whole grant). So nothing is
+              shared with refresh off, without a refreshing `sync` in the last hour,
+              or for a login within the clients' own 5-minute window, refused by its
+              server, or failing to refresh so often that the next try comes too late.
+  refresh     (sync only — one writer, under the pool lock) a winner with a refresh token
+              whose access token expires within its window — REFRESH_AHEAD (2 h), or half
+              its lifetime when that is shorter (never under 10 min, never twice in one
+              half-lifetime) — is refreshed at its authorization server, long before any
+              client's own 5-minute window. The rotated login is saved before anything
+              else, the tokens it replaced are remembered (digests) as superseded, and it
+              is distributed everywhere. A login with a copy in a Keychain item this run
+              cannot open is left to a run that can, until it is close to expiry.
+  forget      a deliberate logout: the server's login leaves the store and every account
+              store, and the retired grants are remembered (digests — never tokens) so a
+              copy in a store this run could not reach is ignored and cleared later.
+              A store that held the pool's login and now shows the key gone or blanked
+              was cleared by its client — a revocation or a refusal at the server — so
+              that login is retired the same way, never merged back.
+
+The shim (bin/claude mcp_oauth_ensure) runs `ensure` — harvest the files plus the picked
+account's own Keychain item, distribute to that one account, no network — only when some
+acct-*/.credentials.json is newer than ROOT/.mcp-oauth-seen (the harvest watermark) and
+either the store exists or a file carries `mcpOAuth`, or when the store is newer than the
+account's <dir>/.mcp-oauth-applied stamp. The store's mtime moves only when what the
+accounts are given does (the logins and the retired grants — never bookkeeping), a whole
+second at a time, and stamps copy it; the watermark is the newest file mtime the last
+harvest saw, set a second early when that is the current second — so a write right behind
+a harvest is never hidden from a one-second `test -nt` (bash 3.2).
+
+Kill switches: CLAUDE_MULTIACC_MCP_OAUTH=0 (ensure and sync do nothing) and
+CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0 (sync never refreshes — and so nothing is shared:
+one shared login needs one refresher). status and forget are explicit operator commands
+and always run. Nothing here prints or logs a token.
+
+Run: mcp_oauth.py ensure --root R --account-dir D [--quiet] | sync --root R [--quiet]
+[--force] | status --root R [--json] | forget --root R NAME [--quiet]
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import calendar
+import contextlib
+import copy
+import errno
+import fcntl
+import glob
+import hashlib
+import http.client
+import json
+import os
+import re
+import signal
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+# The install tree may be root-owned, read-only or an npm prefix: no __pycache__ in it.
+sys.dont_write_bytecode = True
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import keychain  # noqa: E402  (the one place that knows the Keychain layout)
+
+STORE_FILE = 'mcp-oauth.json'
+SEEN_FILE = '.mcp-oauth-seen'
+STAMP_FILE = '.mcp-oauth-applied'
+POOL_LOCK = os.path.join('.locks', 'mcp-oauth.lock')
+LIMITS_LOCK = os.path.join('.locks', 'limits')
+CREDENTIALS_FILE = '.credentials.json'
+CLIENT_LOCK = '.storage-write.lock'
+CLIENT_LOCK_STALE_S = 15          # proper-lockfile's `stale`, as the client sets it
+LIMITS_LOCK_FRESH_S = 120         # cmd_limits breaks an older one
+REFRESH_AHEAD_S = 7200
+MIN_WINDOW_S = 600                # a short-lived login is still refreshed this far ahead
+CLIENT_REFRESH_S = 300            # the client refreshes on its own inside this window
+SYNC_PERIOD_S = 900               # the scheduled claude limits pass that runs `sync`
+URGENT_S = CLIENT_REFRESH_S + SYNC_PERIOD_S   # the last sync before the clients' window
+REFRESHER_FRESH_S = 3600          # ensure shares only behind a sync this recent
+ASSUMED_LIFETIME_S = 3600         # a token answer without expires_in (as refresh_oauth)
+SUPERSEDED_KEEP = 16
+BACKOFF_FIRST_S = 900
+BACKOFF_MAX_S = 21600
+HTTP_TIMEOUT_S = 10
+KEYCHAIN_HOLD_S = 21600
+FORGOTTEN_KEEP_S = 90 * 86400
+MAX_DOC_BYTES = 4 << 20
+MAX_BODY_BYTES = 1 << 20
+ENSURE_BUDGET_S = 5               # the shim's hot path: a backstop, never the normal case
+ENSURE_SECURITY_TIMEOUT_S = 2
+ENSURE_LOCK_WAIT_S = 0.5          # a busy lock costs this launch the merge, never a second
+SYNC_BUDGET_S = 240
+REFRESH_MIN_LEFT_S = 60           # never start a refresh the budget could cut in half
+ACCT_ID = re.compile(r'^acct-\d{2,4}$')
+OAUTH_ERROR = re.compile(r'^[a-z_]{1,64}$')
+#: outcomes that leave an account to be retried at its next launch (no stamp)
+TRANSIENT = frozenset({'busy', 'deferred', 'failed', 'error', 'parked'})
+#: outcomes `sync` and `forget` report as "not reached"
+UNREACHED = ('busy', 'deferred', 'failed', 'error', 'mismatch', 'held', 'corrupt',
+             'unreadable', 'parked', 'locked')
+USER_AGENT = 'claude-multiacc-mcp-oauth'
+
+
+class _Budget(BaseException):
+    """The run's time budget ran out (a BaseException, so no `except Exception` eats it)."""
+
+
+def _flag(name):
+    return os.environ.get(name, '1').strip().lower() not in ('0', 'false', 'no', 'off')
+
+
+def enabled():
+    return _flag('CLAUDE_MULTIACC_MCP_OAUTH')
+
+
+def refresh_enabled():
+    return _flag('CLAUDE_MULTIACC_MCP_OAUTH_REFRESH')
+
+
+def refresh_ahead():
+    try:
+        value = int(os.environ.get('CLAUDE_MULTIACC_MCP_OAUTH_REFRESH_AHEAD', REFRESH_AHEAD_S))
+    except ValueError:
+        return REFRESH_AHEAD_S
+    return max(0, min(value, 7 * 86400))
+
+
+# --------------------------------------------------------------------------- io
+
+def _now_iso(t=None):
+    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(time.time() if t is None else t))
+
+
+def _epoch(iso):
+    """The epoch an _now_iso() stamp names, or None."""
+    try:
+        return calendar.timegm(time.strptime(iso, '%Y-%m-%dT%H:%M:%SZ'))
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _log(root, message):
+    try:
+        with open(os.path.join(root, 'ops.log'), 'a', encoding='utf-8') as handle:
+            handle.write(f'{_now_iso()} mcp-oauth {message}\n')
+    except OSError:
+        pass
+
+
+def _scratch(directory, name, data, mode=0o600):
+    """A fsynced temp file beside ``name`` holding ``data`` (bytes): its path."""
+    handle, path = tempfile.mkstemp(prefix=f".{name.lstrip('.')}.", suffix='.tmp', dir=directory)
+    try:
+        with os.fdopen(handle, 'wb') as stream:
+            os.fchmod(stream.fileno(), mode)
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(path)
+        raise
+    return path
+
+
+def _write_atomic(path, text, mode=0o600):
+    scratch = _scratch(os.path.dirname(path) or '.', os.path.basename(path),
+                       text.encode('utf-8'), mode)
+    try:
+        os.replace(scratch, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(scratch)
+        raise
+
+
+def _refuse_constant(name):
+    raise ValueError(f'{name} is not JSON')
+
+
+def _parse_doc(raw):
+    """The credential document in ``raw`` (bytes), or None when it is not a JSON object.
+    NaN/Infinity are refused: the client's JSON.parse refuses them too."""
+    if raw is None or len(raw) > MAX_DOC_BYTES:
+        return None
+    try:
+        doc = json.loads(raw.decode('utf-8'), parse_constant=_refuse_constant)
+    except ValueError:
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+def _mcp_map(doc):
+    """The document's `mcpOAuth` map ({} when absent), or None when it holds something
+    else — a store this module does not understand is never written."""
+    value = doc.get('mcpOAuth', {})
+    return value if isinstance(value, dict) else None
+
+
+def _read_bytes(path):
+    """('ok', bytes) / ('absent', None) / ('error', None)."""
+    try:
+        with open(path, 'rb') as handle:
+            return 'ok', handle.read(MAX_DOC_BYTES + 1)
+    except FileNotFoundError:
+        return 'absent', None
+    except OSError:
+        return 'error', None
+
+
+# ---------------------------------------------------------------------- entries
+
+def is_login(entry):
+    """An MCP entry that can authenticate: an access or a refresh token is present."""
+    return isinstance(entry, dict) and any(
+        isinstance(entry.get(name), str) and entry.get(name)
+        for name in ('accessToken', 'refreshToken'))
+
+
+def _number(value):
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, str):
+        try:
+            value = float(value)
+        except ValueError:
+            return None
+    if isinstance(value, (int, float)) and value == value and abs(value) != float('inf'):
+        return value
+    return None
+
+
+def _expires_ms(entry):
+    return _number(entry.get('expiresAt')) if isinstance(entry, dict) else None
+
+
+def _has_refresh(entry):
+    token = entry.get('refreshToken') if isinstance(entry, dict) else None
+    return isinstance(token, str) and bool(token)
+
+
+def _rank(entry):
+    expires = _expires_ms(entry)
+    return (expires if expires is not None else -1, _has_refresh(entry))
+
+
+def _token(entry, name):
+    value = entry.get(name) if isinstance(entry, dict) else None
+    return value if isinstance(value, str) and value else None
+
+
+def _same_tokens(a, b):
+    """Both logins carry exactly the same tokens: one save, wherever it sits (the store's
+    copy may add the expiry the client's lacked)."""
+    return is_login(a) and is_login(b) and all(
+        _token(a, name) == _token(b, name) for name in ('accessToken', 'refreshToken'))
+
+
+def _same_grant(a, b):
+    if not isinstance(a, dict) or not isinstance(b, dict):
+        return False
+    if _has_refresh(a) and _has_refresh(b):
+        return a['refreshToken'] == b['refreshToken']
+    token = a.get('accessToken')
+    return isinstance(token, str) and bool(token) and token == b.get('accessToken')
+
+
+def _digests(entry):
+    """Short sha256 digests of an entry's tokens: how the store remembers a token it
+    retired or replaced without keeping it."""
+    out = set()
+    for name in ('accessToken', 'refreshToken'):
+        value = entry.get(name) if isinstance(entry, dict) else None
+        if isinstance(value, str) and value:
+            out.add(hashlib.sha256(value.encode('utf-8')).hexdigest()[:24])
+    return out
+
+
+def _superseded(rec, entry):
+    """``entry`` carries a token one of the pool's own refreshes replaced: an older copy
+    of ``rec``'s login, whatever its expiry says."""
+    return bool(rec) and bool(_digests(entry) & set(rec.get('superseded') or ()))
+
+
+def _provably_older(have, entry):
+    """``have`` is a login older than ``entry`` by their expiries — never when one of
+    them has none: a login saved without an expiry may well be the newest."""
+    return _expires_ms(have) is not None and _expires_ms(entry) is not None \
+        and _rank(entry) > _rank(have)
+
+
+def _server_name(key, entry):
+    name = entry.get('serverName') if isinstance(entry, dict) else None
+    return name if isinstance(name, str) and name else key.split('|', 1)[0]
+
+
+def _sharing_off(rec, now):
+    """Why the pool must not share this login now, or None. A login shared into many
+    accounts needs ONE refresher — the pool, ahead of every client — or the clients,
+    each under its own config dir's lock, refresh one rotating grant at once."""
+    if rec.get('needs_reauth'):
+        return 'its authorization server refused the refresh token'
+    expires = _expires_ms(rec['entry'])
+    if expires is None:
+        return 'no expiry to refresh it ahead of'
+    if expires / 1000.0 - now <= CLIENT_REFRESH_S:
+        return 'expiring: the clients refresh it themselves now'
+    backoff = rec.get('refresh') or {}
+    if backoff.get('failures') and (_number(backoff.get('next_at')) or 0) + SYNC_PERIOD_S \
+            >= expires / 1000.0 - CLIENT_REFRESH_S:
+        return 'its refresh keeps failing and the next try comes too late'
+    return None
+
+
+# ------------------------------------------------------------------------ store
+
+class Store:
+    """ROOT/mcp-oauth.json: {"version": 1, "entries": {key: {"entry": <the client's
+    entry, its expiresAt stamped when it had none>, "source": acct, "store":
+    file|keychain, "harvested_at", "refreshed_at"?, "lifetime_s"?, "expiry_assumed"?,
+    "refresh"?: {failures, next_at, last_error, last_attempt_at}, "deferred"?,
+    "needs_reauth"?, "holders"?: ["acct-NN:file"|"acct-NN:keychain", …] (the stores
+    known to hold this very login), "superseded"?: [token digests its refreshes
+    replaced]}}, "forgotten": {key: {"at", "digests", "reason"}}, "holds": {acct:
+    {"until", "reason", "at"}}, "refresher": {"at", "refresh"} (the last sync's beat)}.
+    Its mtime is the shim's "the store changed" clock (see :meth:`save`)."""
+
+    def __init__(self, root):
+        self.root = root
+        self.path = os.path.join(root, STORE_FILE)
+        self.doc = {'version': 1, 'entries': {}, 'forgotten': {}, 'holds': {}}
+        self.exists = False
+        self.dirty = False
+        self.clock = 0
+        self.signature = None
+
+    @property
+    def entries(self):
+        return self.doc['entries']
+
+    @property
+    def forgotten(self):
+        return self.doc['forgotten']
+
+    def load(self, readonly=False):
+        try:
+            st = os.stat(self.path)
+            with open(self.path, encoding='utf-8') as handle:
+                doc = json.load(handle)
+        except FileNotFoundError:
+            return self
+        except ValueError:
+            if not readonly:
+                # A store this module cannot read is a cache it can rebuild from the
+                # accounts: keep the bad copy for a human and start over.
+                with contextlib.suppress(OSError):
+                    os.replace(self.path, self.path + '.corrupt')
+                _log(self.root, f'{STORE_FILE} was not JSON; moved aside to {STORE_FILE}.corrupt')
+                self.dirty = True
+            return self
+        self.exists, self.clock = True, int(st.st_mtime)
+        if not isinstance(doc, dict):
+            self.dirty = True
+            return self
+        entries = doc.get('entries')
+        for key, rec in (entries.items() if isinstance(entries, dict) else ()):
+            if isinstance(key, str) and isinstance(rec, dict) and is_login(rec.get('entry')):
+                self.entries[key] = rec
+            else:
+                self.dirty = True
+        for name in ('forgotten', 'holds'):
+            value = doc.get(name)
+            if isinstance(value, dict):
+                self.doc[name] = {k: v for k, v in value.items()
+                                  if isinstance(k, str) and isinstance(v, dict)}
+        if isinstance(doc.get('refresher'), dict):
+            self.doc['refresher'] = doc['refresher']
+        self.signature = self._signature()
+        return self
+
+    def _signature(self):
+        """What the accounts are given: the logins and the retired grants. Only its change
+        moves the store's clock — holders, backoff, holds and the refresher's beat are
+        bookkeeping no account has to act on."""
+        doc = {'entries': {k: r.get('entry') for k, r in self.entries.items()},
+               'forgotten': {k: sorted(v.get('digests') or ()) for k, v in self.forgotten.items()}}
+        return hashlib.sha256(json.dumps(doc, sort_keys=True).encode('utf-8')).hexdigest()
+
+    def forgotten_match(self, key, entry):
+        tomb = self.forgotten.get(key)
+        return bool(tomb) and bool(_digests(entry) & set(tomb.get('digests') or ()))
+
+    def held(self, account, now):
+        hold = self.doc['holds'].get(account)
+        return bool(hold) and (_number(hold.get('until')) or 0) > now
+
+    def hold(self, account, reason, now):
+        self.doc['holds'][account] = {'until': int(now + KEYCHAIN_HOLD_S), 'reason': reason,
+                                      'at': _now_iso(now)}
+        self.dirty = True
+
+    def beat(self, now):
+        """`sync` is running: the refresher record that `ensure` shares behind."""
+        self.doc['refresher'] = {'at': int(now), 'refresh': refresh_enabled()}
+        self.dirty = True
+
+    def refresher_ok(self, now):
+        """A sync with refresh on ran within REFRESHER_FRESH_S: every due login will be
+        refreshed ahead of the clients, so `ensure` may share."""
+        beat = self.doc.get('refresher') or {}
+        at = _number(beat.get('at'))
+        return beat.get('refresh') is True and at is not None \
+            and -CLIENT_REFRESH_S <= now - at < REFRESHER_FRESH_S
+
+    def retire(self, key, reason, now, digests=()):
+        """Drop ``key``'s login and remember its tokens — and the older ones its
+        refreshes replaced — so no copy of it is ever shared again, and every copy is
+        cleared wherever a later run reaches it."""
+        rec = self.entries.pop(key, None)
+        digests = set(digests)
+        if rec:
+            digests |= _digests(rec['entry']) | set(rec.get('superseded') or ())
+        old = self.forgotten.get(key) or {}
+        self.forgotten[key] = {'at': _now_iso(now), 'reason': reason,
+                               'digests': sorted(digests | set(old.get('digests') or ()))}
+        self.dirty = True
+
+    def save(self):
+        """Write the store (0600, atomic). Its mtime is the shim's "the store changed"
+        clock: it moves — at least one whole second past the previous one, so a
+        one-second `test -nt` against the accounts' stamps still sees every change — only
+        when what the accounts are given changed; a bookkeeping save keeps it."""
+        now = time.time()
+        self.doc['holds'] = {k: v for k, v in self.doc['holds'].items()
+                             if (_number(v.get('until')) or 0) > now}
+        self.doc['forgotten'] = {k: v for k, v in self.forgotten.items()
+                                 if (now - (_epoch(v.get('at')) or now)) < FORGOTTEN_KEEP_S}
+        self.doc['version'] = 1
+        self.doc['updated_at'] = _now_iso(now)
+        signature = self._signature()
+        _write_atomic(self.path, json.dumps(self.doc, indent=2) + '\n')
+        if self.exists and self.clock and signature == self.signature:
+            clock = self.clock
+        else:
+            clock = max(int(now), self.clock + 1)
+        os.utime(self.path, (clock, clock))
+        self.exists, self.dirty, self.clock, self.signature = True, False, clock, signature
+        return clock
+
+
+class PoolLock:
+    """flock on ROOT/.locks/mcp-oauth.lock: one writer of the store at a time — and with
+    it ONE refresher. Released when the process exits, however it exits."""
+
+    def __init__(self, root, wait):
+        self.path = os.path.join(root, POOL_LOCK)
+        self.wait = wait
+        self.fd = None
+        self.held = False
+
+    def __enter__(self):
+        try:
+            os.makedirs(os.path.dirname(self.path), exist_ok=True)
+            self.fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o600)
+        except OSError:
+            return self
+        deadline = time.monotonic() + self.wait
+        while True:
+            try:
+                fcntl.flock(self.fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                self.held = True
+                return self
+            except OSError as exc:
+                if exc.errno not in (errno.EWOULDBLOCK, errno.EAGAIN, errno.EACCES) \
+                        or time.monotonic() >= deadline:
+                    return self
+                time.sleep(0.05)
+
+    def __exit__(self, *_exc):
+        if self.fd is not None:
+            with contextlib.suppress(OSError):
+                os.close(self.fd)
+            self.fd = None
+        self.held = False
+        return False
+
+
+class ClientLock:
+    """The client's own write lock, in proper-lockfile's layout: the DIRECTORY
+    <dir>/.storage-write.lock, stale once its mtime is CLIENT_LOCK_STALE_S old (a live
+    holder refreshes it well inside that). A held lock is waited on for ``wait`` seconds,
+    then the account is left for the next run; a stale one is taken over."""
+
+    def __init__(self, account_dir, wait):
+        self.path = os.path.join(account_dir, CLIENT_LOCK)
+        self.wait = wait
+        self.held = False
+
+    def acquire(self):
+        deadline = time.monotonic() + self.wait
+        while True:
+            try:
+                os.mkdir(self.path)
+                self.held = True
+                return True
+            except FileExistsError:
+                pass
+            except OSError:
+                return False
+            try:
+                stale = time.time() - os.stat(self.path).st_mtime > CLIENT_LOCK_STALE_S
+            except FileNotFoundError:
+                continue                 # released just now: take it
+            except OSError:
+                return False
+            if stale:
+                try:
+                    os.rmdir(self.path)  # its holder is gone
+                    continue
+                except FileNotFoundError:
+                    continue
+                except OSError:
+                    pass                 # cannot clear it: wait like for any held lock
+            if time.monotonic() >= deadline:
+                return False
+            time.sleep(0.05)
+
+    def touch(self):
+        if self.held:
+            with contextlib.suppress(OSError):
+                os.utime(self.path)
+
+    def release(self):
+        if self.held:
+            with contextlib.suppress(OSError):
+                os.rmdir(self.path)
+            self.held = False
+
+
+@contextlib.contextmanager
+def _budget(seconds):
+    """Bound the whole run (the shim waits for `ensure`): past ``seconds`` it unwinds —
+    locks released by their own `finally` — and the caller exits 0."""
+    usable = seconds and hasattr(signal, 'setitimer') \
+        and threading.current_thread() is threading.main_thread()
+    if not usable:
+        yield
+        return
+
+    def on_alarm(_signum, _frame):
+        raise _Budget()
+
+    previous = signal.signal(signal.SIGALRM, on_alarm)
+    signal.setitimer(signal.ITIMER_REAL, seconds)
+    try:
+        yield
+    finally:
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, previous)
+
+
+def _limits_running(root):
+    """A `claude-accounts limits` pass holds its lock: it may be rotating a login right
+    now, and it writes without the client's lock."""
+    try:
+        return time.time() - os.stat(os.path.join(root, LIMITS_LOCK)).st_mtime \
+            < LIMITS_LOCK_FRESH_S
+    except OSError:
+        return False
+
+
+# ---------------------------------------------------------------------- accounts
+
+def account_dirs(root):
+    """[(id, dir)] of every manifest account whose dir exists, in id order — the accounts
+    the shim can pick. An unreadable manifest is no accounts (fail-open)."""
+    try:
+        with open(os.path.join(root, 'accounts.json'), encoding='utf-8') as handle:
+            doc = json.load(handle)
+    except (OSError, ValueError):
+        return []
+    listed = doc.get('accounts') if isinstance(doc, dict) else None
+    out = set()
+    for account in listed if isinstance(listed, list) else ():
+        aid = account.get('id') if isinstance(account, dict) else None
+        if isinstance(aid, str) and ACCT_ID.match(aid) and os.path.isdir(os.path.join(root, aid)):
+            out.add((aid, os.path.join(root, aid)))
+    return sorted(out)
+
+
+def _read_file_store(account_dir):
+    status, raw = _read_bytes(os.path.join(account_dir, CREDENTIALS_FILE))
+    if status == 'absent':
+        return {'state': 'absent', 'doc': None, 'map': {}}
+    if status != 'ok':
+        return {'state': 'unreadable', 'doc': None, 'map': {}}
+    doc = _parse_doc(raw)
+    mapping = _mcp_map(doc) if doc is not None else None
+    if mapping is None:
+        # `mentions`: what the shim's grep sees in a file no JSON parser can read
+        return {'state': 'corrupt', 'doc': None, 'map': {}, 'mentions': b'"mcpOAuth"' in raw}
+    return {'state': 'ok', 'doc': doc, 'map': mapping}
+
+
+def _read_keychain_store(keychain_dir, timeout):
+    state, doc = keychain.read_doc(keychain_dir, timeout=timeout)
+    if state != 'present':
+        return {'state': state, 'doc': None, 'map': {}}
+    mapping = _mcp_map(doc)
+    if mapping is None:
+        return {'state': 'corrupt', 'doc': None, 'map': {}}
+    return {'state': 'ok', 'doc': doc, 'map': mapping}
+
+
+def _harvest(root, accounts, keychain_dirs, timeout):
+    """({id: {'file': seen, 'keychain': seen or None}}, {path: mtime_ns}). The mtimes are
+    of EVERY acct-*/.credentials.json (the shim's glob, retired dirs included) and are
+    taken BEFORE anything is read: a write that lands after the stat can only make the
+    next gate fire again, never hide."""
+    stats = {}
+    for path in glob.glob(os.path.join(glob.escape(root), 'acct-*', CREDENTIALS_FILE)):
+        with contextlib.suppress(OSError):
+            stats[path] = os.stat(path).st_mtime_ns
+    seen = {}
+    for aid, account_dir in accounts:
+        kdir = keychain_dirs.get(aid)
+        seen[aid] = {'file': _read_file_store(account_dir),
+                     'keychain': _read_keychain_store(kdir, timeout) if kdir else None}
+    return seen, stats
+
+
+def _in_play(seen):
+    """Some account's client has written MCP OAuth state: the store is worth keeping."""
+    return any(s and s['state'] == 'ok' and 'mcpOAuth' in s['doc']
+               for stores in seen.values() for s in stores.values())
+
+
+def _choose(store, seen, now):
+    """Fold the harvested logins into the store. Returns the keys whose winner changed."""
+    candidates = {}
+    for aid in sorted(seen):
+        for kind in ('file', 'keychain'):
+            s = seen[aid].get(kind)
+            if not s or s['state'] != 'ok':
+                continue
+            for key, entry in s['map'].items():
+                if isinstance(key, str) and key and is_login(entry) \
+                        and not store.forgotten_match(key, entry) \
+                        and not _superseded(store.entries.get(key), entry):
+                    candidates.setdefault(key, []).append((entry, aid, kind))
+    # A login saved without an expiry (a token answer with no expires_in) is ranked — and
+    # kept — as if it lived ASSUMED_LIFETIME_S from now: never as older than every copy
+    # that has one, which put the old grant back over a rotated one.
+    stamp = int(now * 1000 + ASSUMED_LIFETIME_S * 1000)
+    changed = []
+    for key in sorted(candidates):
+        rec = store.entries.get(key)
+        current = rec['entry'] if rec else None
+        known_bad = bool(rec and rec.get('needs_reauth'))
+
+        def order(item, current=current, known_bad=known_bad):
+            entry, _aid, _kind, is_current, _assumed = item
+            refused = known_bad and _same_grant(entry, current)
+            return (not refused, _rank(entry), is_current)
+
+        items = []
+        for entry, aid, kind in candidates[key]:
+            if _same_tokens(entry, current):
+                continue                 # the store's own login, wherever it sits
+            assumed = _expires_ms(entry) is None
+            items.append((dict(entry, expiresAt=stamp) if assumed else entry,
+                          aid, kind, False, assumed))
+        if current is not None:
+            items.append((current, None, None, True, False))
+        best = max(items, key=order)        # the first of equals: lowest account id
+        if best[3]:
+            continue
+        new = {'entry': copy.deepcopy(best[0]), 'source': best[1], 'store': best[2],
+               'harvested_at': _now_iso(now)}
+        if best[4]:
+            new['expiry_assumed'] = True
+        if rec and rec.get('superseded'):
+            new['superseded'] = rec['superseded']       # those tokens stay dead
+        store.entries[key] = new
+        store.dirty = True
+        changed.append(key)
+    return changed
+
+
+def _note_holders(store, seen, now):
+    """Bookkeeping after a harvest: the stores holding each record's very login. A store
+    the record knew as a holder that now holds no login for the key — gone from a map it
+    still has, or blanked — was cleared by its own client: a refused refresh, /mcp "Clear
+    authentication", `claude mcp login`, each revoking or refused at the server first. So
+    that login is retired everywhere, as `forget` does — merging it back would only hand
+    every account a dead grant. Returns the retired keys."""
+    retired = []
+    for key in sorted(store.entries):
+        rec = store.entries[key]
+        before = set(rec.get('holders') or ())
+        holders = {h for h in before if h.split(':', 1)[0] in seen}
+        dropped = None
+        for aid in sorted(seen):
+            for kind in ('file', 'keychain'):
+                s = seen[aid].get(kind)
+                name = f'{aid}:{kind}'
+                if s is None or s['state'] not in ('ok', 'absent'):
+                    continue                 # cannot tell from here: keep what we knew
+                have = s['map'].get(key)
+                if _same_tokens(have, rec['entry']):
+                    holders.add(name)
+                elif name in holders:
+                    holders.discard(name)
+                    # a store that is gone, or rewritten without any MCP state, says
+                    # nothing about the login
+                    if s['state'] == 'ok' and 'mcpOAuth' in s['doc'] and not is_login(have):
+                        dropped = dropped or name
+        if dropped:
+            store.retire(key, f'cleared in {dropped.replace(":", " ")}', now)
+            _log(store.root, f'{key}: the login was cleared in {dropped.replace(":", " ")} '
+                             '(revoked or refused there) — retired in every account')
+            retired.append(key)
+        elif holders != before:
+            rec['holders'] = sorted(holders)
+            store.dirty = True
+    return retired
+
+
+def _hold(store, aid, res):
+    """After a merge: the stores now holding a record's login."""
+    for kind, keys in res['held'].items():
+        for key in keys:
+            rec = store.entries.get(key)
+            if rec is not None:
+                holders = set(rec.get('holders') or ()) | {f'{aid}:{kind}'}
+                if holders != set(rec.get('holders') or ()):
+                    rec['holders'] = sorted(holders)
+                    store.dirty = True
+
+
+def _plan(store, now, sharing):
+    """account map -> {key: entry to write, or None to drop}: what this account store
+    needs from the store. Retired logins are always dropped; logins are shared only with
+    ``sharing`` (this process may: the refresher runs) and while :func:`_sharing_off`
+    has no objection."""
+    def plan(mapping):
+        out = {}
+        for key, rec in store.entries.items():
+            entry = rec['entry']
+            have = mapping.get(key)
+            if not sharing or _sharing_off(rec, now) or _same_tokens(have, entry):
+                continue
+            if not is_login(have) or store.forgotten_match(key, have) \
+                    or _superseded(rec, have) or _provably_older(have, entry):
+                out[key] = entry
+        for key in store.forgotten:
+            have = mapping.get(key)
+            if key not in out and is_login(have) and store.forgotten_match(key, have):
+                out[key] = None
+        return out
+    return plan
+
+
+def _apply(doc, mapping, changes):
+    """``doc`` with ``changes`` merged into its `mcpOAuth` map; every other key — the
+    Claude login above all — exactly as it was, in its place."""
+    merged = dict(mapping)
+    for key, entry in changes.items():
+        if entry is None:
+            merged.pop(key, None)
+        else:
+            merged[key] = copy.deepcopy(entry)
+    out = dict(doc)
+    out['mcpOAuth'] = merged
+    return out
+
+
+def _landed(mapping, changes):
+    return all((key not in mapping) if entry is None else (mapping.get(key) == entry)
+               for key, entry in changes.items())
+
+
+def _may_create(account_dir):
+    """Whether a .credentials.json holding MCP state alone may be CREATED here: only for an
+    account that runs on its portable token (a non-empty server.token) — that client has
+    no other store to read MCP logins from in a session that cannot open the Keychain,
+    and writes this very file itself once it meets an OAuth server — never one parked
+    (`.expired`), an adopted dir (a symlink: ~/.claude itself), or a name that is taken,
+    a dangling link included. Every reader counts a document as a login only when it
+    carries `claudeAiOauth` (bin/claude file_login, lib/audit.py file_has_login), so the
+    file costs the token nothing; an account with a login has a store already, and one
+    with no credential at all gains nothing (`adopt` refuses a dir holding the file)."""
+    path = os.path.join(account_dir, CREDENTIALS_FILE)
+    try:
+        if os.path.islink(account_dir) or os.path.lexists(path) \
+                or os.path.lexists(os.path.join(account_dir, '.expired')):
+            return False
+        return os.path.getsize(os.path.join(account_dir, 'server.token')) > 0
+    except OSError:
+        return False
+
+
+def _create_file(target, plan):
+    """The file a token account's client would write (MCP state alone), 0600, appearing
+    whole and only if the name is still free: (outcome, changes) — ('taken', {}) when a
+    client wrote one meanwhile (the caller merges into that instead)."""
+    changes = {k: v for k, v in plan({}).items() if v is not None}
+    if not changes:
+        return 'absent', {}
+    text = json.dumps(_apply({}, {}, changes), ensure_ascii=False, separators=(',', ':'))
+    scratch = _scratch(os.path.dirname(target), os.path.basename(target), text.encode('utf-8'))
+    try:
+        os.link(scratch, target)
+    except FileExistsError:
+        return 'taken', {}
+    except OSError:
+        return 'error', {}
+    finally:
+        with contextlib.suppress(OSError):
+            os.unlink(scratch)
+    return 'created', changes
+
+
+def _merge_file(root, account_dir, plan, create=False):
+    """Under the client lock: (outcome, changes written). Into a file that exists; or,
+    with ``create`` (_may_create), a new one holding MCP state alone. Re-reads, merges,
+    writes a temp beside the file, checks the file did not change under it, replaces it,
+    and puts the old mtime back — the merge is not a login. A file holding a login is left
+    alone while a limits pass runs (defence in depth: its refresher writes under the
+    client's lock and re-reads first)."""
+    path = os.path.join(account_dir, CREDENTIALS_FILE)
+    target = os.path.realpath(path) if os.path.islink(path) else path
+
+    def snapshot():
+        status, raw = _read_bytes(target)
+        try:
+            st = os.stat(target) if status == 'ok' else None
+        except OSError:
+            return 'error', None, None
+        return status, raw, st
+
+    for _attempt in range(3):
+        status, raw, before = snapshot()
+        if status == 'absent':
+            if not create:
+                return 'absent', {}
+            outcome, changes = _create_file(target, plan)
+            if outcome == 'taken':
+                continue                 # the client wrote one meanwhile: merge into it
+            return outcome, changes
+        if status == 'error':
+            return 'unreadable', {}
+        doc = _parse_doc(raw)
+        mapping = _mcp_map(doc) if doc is not None else None
+        if mapping is None:
+            return 'corrupt', {}
+        changes = plan(mapping)
+        if not changes:
+            return 'current', {}
+        if 'claudeAiOauth' in doc and _limits_running(root):
+            return 'deferred', {}
+        text = json.dumps(_apply(doc, mapping, changes), ensure_ascii=False,
+                          separators=(',', ':'))
+        scratch = _scratch(os.path.dirname(target), os.path.basename(target),
+                           text.encode('utf-8'))
+        try:
+            now_status, now_raw, now_st = snapshot()
+            if (now_status, now_raw) != (status, raw) or now_st is None \
+                    or now_st.st_mtime_ns != before.st_mtime_ns:
+                continue                 # changed under us: merge again from the new text
+            os.replace(scratch, target)
+            scratch = None
+        finally:
+            if scratch:
+                with contextlib.suppress(OSError):
+                    os.unlink(scratch)
+        with contextlib.suppress(OSError):
+            os.utime(target, ns=(before.st_atime_ns, before.st_mtime_ns))
+        return 'written', changes
+    return 'busy', {}
+
+
+def _merge_keychain(root, account_dir, plan, parked, timeout):
+    """Under the client lock: (outcome, changes written). Only an item that exists and
+    this session can read; written the client's way and read back — the Claude login must
+    be exactly what it was and every change must have landed, or it is a 'mismatch'."""
+    if parked:
+        return 'parked', {}
+    state, doc = keychain.read_doc(account_dir, timeout=timeout)
+    if state != 'present':
+        return state, {}                 # absent: never created; locked: not ours to open
+    mapping = _mcp_map(doc)
+    if mapping is None:
+        return 'corrupt', {}
+    changes = plan(mapping)
+    if not changes:
+        return 'current', {}
+    if 'claudeAiOauth' in doc and _limits_running(root):
+        return 'deferred', {}
+    if not keychain.write_doc(account_dir, _apply(doc, mapping, changes), timeout=timeout):
+        return 'failed', {}
+    state, back = keychain.read_doc(account_dir, timeout=timeout)
+    back_map = _mcp_map(back) if state == 'present' else None
+    if back_map is None or back.get('claudeAiOauth') != doc.get('claudeAiOauth') \
+            or not _landed(back_map, changes):
+        return 'mismatch', {}
+    return 'written', changes
+
+
+def _distribute(root, store, aid, account_dir, seen, keychain_dir, plan, now,
+                wait, timeout):
+    """Merge into one account's stores: {'file', 'keychain', 'keys', 'held'} — the
+    outcome per store, the keys written to it and the ones it now holds a login for."""
+    out = {'file': 'current', 'keychain': None, 'keys': {}, 'held': {}}
+    # A Keychain write moves the item's stamp, and bin/claude lifts an `.expired` park on
+    # a Keychain login written after it: a parked account gets none.
+    parked = os.path.exists(os.path.join(account_dir, '.expired'))
+    fs, ks = seen['file'], seen.get('keychain')
+    file_todo = create = False
+    if fs['state'] == 'ok':
+        file_todo = bool(plan(fs['map']))
+    else:
+        out['file'] = fs['state']
+        # absent: created for a token account alone, and only with a login to share
+        if fs['state'] == 'absent' and _may_create(account_dir):
+            create = file_todo = any(v is not None for v in plan({}).values())
+    kc_todo = False
+    if ks is not None:
+        out['keychain'] = 'current' if ks['state'] == 'ok' else ks['state']
+        if ks['state'] == 'ok' and plan(ks['map']):
+            if store.held(aid, now):
+                out['keychain'] = 'held'
+            else:
+                kc_todo = True
+    if not file_todo and not kc_todo:
+        return out
+    lock = ClientLock(account_dir, wait)
+    if not lock.acquire():
+        if file_todo:
+            out['file'] = 'busy'
+        if kc_todo:
+            out['keychain'] = 'busy'
+        return out
+    written = {}
+    try:
+        if file_todo:
+            out['file'], written['file'] = _merge_file(root, account_dir, plan, create)
+        lock.touch()
+        if kc_todo:
+            out['keychain'], written['keychain'] = _merge_keychain(root, keychain_dir, plan,
+                                                                   parked, timeout)
+    except OSError:
+        if file_todo and out['file'] in ('current', 'absent'):
+            out['file'] = 'error'
+    finally:
+        lock.release()
+    for kind, changes in written.items():
+        if changes:
+            out['keys'][kind] = sorted(changes)
+            out['held'][kind] = sorted(k for k, v in changes.items() if v is not None)
+    if out['keychain'] == 'mismatch':
+        # Stop touching that item: whatever answered is not what was written.
+        store.hold(aid, 'read-back mismatch', now)
+        _log(root, f'{aid} keychain: read-back mismatch — left alone for {KEYCHAIN_HOLD_S // 3600}h')
+    for kind in ('file', 'keychain'):
+        if out['keys'].get(kind):
+            verb = 'created with' if out[kind] == 'created' else 'merged'
+            _log(root, f"{aid} {kind}: {verb} {','.join(out['keys'][kind])}")
+        elif out[kind] in ('busy', 'deferred', 'failed', 'error'):
+            _log(root, f'{aid} {kind}: not merged ({out[kind]}); the next run retries')
+    return out
+
+
+def _stamp(account_dir, clock):
+    path = os.path.join(account_dir, STAMP_FILE)
+    try:
+        if int(os.stat(path).st_mtime) == clock:
+            return                       # already says so: no write every pass
+    except OSError:
+        pass
+    try:
+        with open(path, 'w', encoding='utf-8') as handle:
+            handle.write(f'{clock}\n')
+        os.utime(path, (clock, clock))
+    except OSError:
+        pass
+
+
+def _set_watermark(root, stats):
+    """ROOT/.mcp-oauth-seen gets the newest .credentials.json mtime this run saw (merges
+    keep a file's mtime) — a second early when that is the current second, so the next
+    write cannot hide behind it."""
+    ns = max(stats.values()) if stats else time.time_ns()
+    if ns // 10**9 >= int(time.time()):
+        ns = (ns // 10**9) * 10**9 - 10**6
+    path = os.path.join(root, SEEN_FILE)
+    try:
+        with open(path, 'a', encoding='utf-8'):
+            pass
+        os.utime(path, ns=(ns, ns))
+    except OSError:
+        pass
+
+
+# ----------------------------------------------------------------------- refresh
+
+def _url_ok(url):
+    """https, or http to this machine (the test suite's loopback stub): a refresh token
+    never travels in clear text across a network."""
+    try:
+        parts = urllib.parse.urlsplit(url)
+    except ValueError:
+        return False
+    if parts.scheme == 'https' and parts.netloc:
+        return True
+    return parts.scheme == 'http' and (parts.hostname or '') in ('localhost', '127.0.0.1', '::1')
+
+
+def _metadata_urls(as_url, explicit=None):
+    """RFC 8414 metadata (path inserted after the well-known prefix), then OpenID
+    discovery — the order the MCP SDK tries them in; the discovered URL first."""
+    urls = [explicit] if isinstance(explicit, str) and _url_ok(explicit) else []
+    parts = urllib.parse.urlsplit(as_url)
+    base = f'{parts.scheme}://{parts.netloc}'
+    path = parts.path.rstrip('/')
+    if path:
+        urls += [f'{base}/.well-known/oauth-authorization-server{path}',
+                 f'{base}/.well-known/openid-configuration{path}',
+                 f'{base}{path}/.well-known/openid-configuration']
+    else:
+        urls += [f'{base}/.well-known/oauth-authorization-server',
+                 f'{base}/.well-known/openid-configuration']
+    return list(dict.fromkeys(urls))
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *_args, **_kwargs):
+        return None                      # a refresh token is never re-sent anywhere
+
+
+def _http(url, data=None, headers=None, follow=True):
+    request = urllib.request.Request(url, data=data, method='POST' if data else 'GET',
+                                     headers=dict({'Accept': 'application/json',
+                                                   'User-Agent': USER_AGENT}, **(headers or {})))
+    opener = urllib.request.build_opener() if follow else urllib.request.build_opener(_NoRedirect)
+    try:
+        with opener.open(request, timeout=HTTP_TIMEOUT_S) as response:
+            return response.status, response.read(MAX_BODY_BYTES)
+    except urllib.error.HTTPError as exc:
+        try:
+            body = exc.read(MAX_BODY_BYTES)
+        except Exception:  # noqa: BLE001 — an error body is a nicety
+            body = b''
+        return exc.code, body
+
+
+def _json_body(body):
+    try:
+        doc = json.loads((body or b'').decode('utf-8'))
+    except ValueError:
+        return None
+    return doc if isinstance(doc, dict) else None
+
+
+def _as_metadata(as_url, explicit):
+    """(metadata, None) or (None, error word)."""
+    error = 'no authorization server metadata'
+    for url in _metadata_urls(as_url, explicit):
+        try:
+            status, body = _http(url)
+        except (OSError, ValueError, http.client.HTTPException) as exc:
+            error = f'network ({type(exc).__name__})'
+            continue
+        doc = _json_body(body) if status == 200 else None
+        if doc is not None and isinstance(doc.get('token_endpoint'), str):
+            return doc, None
+    return None, error
+
+
+def _refresh_entry(entry):
+    """POST the refresh grant for ``entry``: (new entry, lifetime_s, None, False) on
+    success, else (None, None, error, refused) — ``refused`` when the server rejected the
+    grant itself (invalid_grant). The error is a short phrase, never a token. An answer
+    without expires_in is given ASSUMED_LIFETIME_S (lifetime_s None): with no expiry the
+    pool could never refresh it ahead of the clients, and would rank it below the very
+    copies it replaced."""
+    ds = entry.get('discoveryState') if isinstance(entry.get('discoveryState'), dict) else {}
+    as_url = ds.get('authorizationServerUrl') or entry.get('issuer')
+    if not isinstance(as_url, str) or not _url_ok(as_url):
+        return None, None, 'no usable authorization server URL', False
+    client_id = entry.get('clientId')
+    if not isinstance(client_id, str) or not client_id:
+        return None, None, 'no client id', False
+    meta, error = _as_metadata(as_url, ds.get('authServerMetadataUrl'))
+    if meta is None:
+        return None, None, error, False
+    token_url = meta['token_endpoint']
+    if not _url_ok(token_url):
+        return None, None, 'token endpoint is not https', False
+    form = {'grant_type': 'refresh_token', 'refresh_token': entry['refreshToken']}
+    headers = {'Content-Type': 'application/x-www-form-urlencoded'}
+    secret = entry.get('clientSecret')
+    methods = meta.get('token_endpoint_auth_methods_supported')
+    methods = [m for m in methods if isinstance(m, str)] if isinstance(methods, list) else []
+    if isinstance(secret, str) and secret and 'client_secret_basic' in methods \
+            and 'client_secret_post' not in methods:
+        pair = f"{urllib.parse.quote(client_id, safe='')}:{urllib.parse.quote(secret, safe='')}"
+        headers['Authorization'] = 'Basic ' + base64.b64encode(pair.encode('utf-8')).decode('ascii')
+    else:
+        form['client_id'] = client_id
+        if isinstance(secret, str) and secret:
+            form['client_secret'] = secret
+    resource = entry.get('serverUrl')
+    if isinstance(resource, str) and resource:
+        form['resource'] = resource      # RFC 8707, as the MCP SDK sends it
+    try:
+        status, body = _http(token_url, urllib.parse.urlencode(form).encode('ascii'), headers,
+                             follow=False)
+    except (OSError, ValueError, http.client.HTTPException) as exc:
+        return None, None, f'network ({type(exc).__name__})', False
+    doc = _json_body(body)
+    if status != 200:
+        code = doc.get('error') if doc else None
+        code = code if isinstance(code, str) and OAUTH_ERROR.match(code) else ''
+        return None, None, f'http {status}' + (f' {code}' if code else ''), code == 'invalid_grant'
+    token = doc.get('access_token') if doc else None
+    if not isinstance(token, str) or not token:
+        return None, None, 'no access token in the answer', False
+    new = copy.deepcopy(entry)
+    new['accessToken'] = token
+    rotated = doc.get('refresh_token')
+    if isinstance(rotated, str) and rotated:
+        new['refreshToken'] = rotated
+    lifetime = _number(doc.get('expires_in'))
+    reported = lifetime if lifetime is not None and lifetime > 0 else None
+    new['expiresAt'] = int(time.time() * 1000 + (reported or ASSUMED_LIFETIME_S) * 1000)
+    if isinstance(doc.get('scope'), str):
+        new['scope'] = doc['scope']
+    return new, reported, None, False
+
+
+def _refresh_window(rec, ahead):
+    """How far ahead of its expiry a login is refreshed: ``ahead``, or half the
+    lifetime its last refresh reported when that is shorter (never under MIN_WINDOW_S) —
+    a 2 h window over a 1 h token refreshed it on every pass."""
+    lifetime = _number(rec.get('lifetime_s'))
+    if lifetime is None or lifetime <= 0:
+        return ahead
+    return min(ahead, max(MIN_WINDOW_S, lifetime / 2.0))
+
+
+def _refresh_due(rec, now, ahead, force):
+    entry = rec['entry']
+    if rec.get('needs_reauth') or not _has_refresh(entry):
+        return False
+    expires = _expires_ms(entry)
+    if expires is None or expires / 1000.0 - now > _refresh_window(rec, ahead):
+        return False
+    lifetime = _number(rec.get('lifetime_s'))
+    refreshed = _epoch(rec.get('refreshed_at'))
+    if lifetime and refreshed is not None and 0 <= now - refreshed < lifetime / 2.0:
+        return False                     # refreshed this half-lifetime already
+    return force or (_number((rec.get('refresh') or {}).get('next_at')) or 0) <= now
+
+
+def _blind_holders(rec, seen):
+    """The Keychain items known to hold ``rec``'s login that this run cannot open."""
+    out = []
+    for holder in rec.get('holders') or ():
+        aid, _, kind = holder.partition(':')
+        s = (seen.get(aid) or {}).get(kind) if kind == 'keychain' else None
+        if kind == 'keychain' and (s is None or s['state'] != 'ok'):
+            out.append(aid)
+    return out
+
+
+def _refresh_all(root, store, seen, force, deadline):
+    """Refresh every due login, saving the store after EACH answer: a rotated refresh
+    token exists nowhere else until it is saved. {key: 'refreshed' | error | deferral}."""
+    out = {}
+    ahead = refresh_ahead()
+    for key in sorted(store.entries):
+        rec = store.entries[key]
+        if not _refresh_due(rec, time.time(), ahead, force):
+            continue
+        # A copy in a Keychain item this run cannot open keeps the old refresh token, and
+        # its client (a GUI session) would present it once rotated away: invalid_grant —
+        # or, on a server that detects reuse, the whole grant revoked. A run that can
+        # open the item (the scheduled pass) refreshes it and updates the item, until the
+        # login is close enough to expiry that every client would refresh on its own.
+        blind = _blind_holders(rec, seen)
+        left = _expires_ms(rec['entry']) / 1000.0 - time.time()
+        if blind and left > URGENT_S:
+            why = f"a copy sits in {', '.join(blind)} keychain, which this run cannot open"
+            if rec.get('deferred') != why:
+                rec['deferred'] = why
+                store.dirty = True
+                _log(root, f'refresh {key}: deferred — {why}')
+            out[key] = 'deferred'
+            continue
+        if deadline - time.monotonic() < REFRESH_MIN_LEFT_S:
+            break
+        old = rec['entry']
+        new, lifetime, error, refused = _refresh_entry(old)
+        now = time.time()
+        rec.pop('deferred', None)
+        if new is not None:
+            replaced = sorted(_digests(old) - _digests(new))
+            rec['superseded'] = (replaced + [d for d in rec.get('superseded') or ()
+                                             if d not in replaced])[:SUPERSEDED_KEEP]
+            rec['entry'] = new
+            rec['refreshed_at'] = _now_iso(now)
+            rec['lifetime_s'] = int(lifetime or ASSUMED_LIFETIME_S)
+            if lifetime is None:
+                rec['expiry_assumed'] = True
+            else:
+                rec.pop('expiry_assumed', None)
+            rec['holders'] = []           # nothing holds the new login until it is shared
+            rec.pop('refresh', None)
+            rec.pop('needs_reauth', None)
+            out[key] = 'refreshed'
+            _log(root, f'refresh {key}: ok' + (' (no expires_in: assumed 1h)' if lifetime is None else ''))
+        else:
+            state = rec.setdefault('refresh', {})
+            failures = int(_number(state.get('failures')) or 0) + 1
+            state.update(failures=failures, last_error=error, last_attempt_at=_now_iso(now),
+                         next_at=int(now + min(BACKOFF_FIRST_S * 2 ** (failures - 1),
+                                               BACKOFF_MAX_S)))
+            if refused:
+                rec['needs_reauth'] = True
+                _log(root, f'refresh {key}: {error} — needs a new sign-in')
+            else:
+                _log(root, f"refresh {key}: {error}; retry after {_now_iso(state['next_at'])}")
+            out[key] = error
+        store.dirty = True
+        store.save()
+    return out
+
+
+# -------------------------------------------------------------------------- report
+
+def _fmt_ms(ms):
+    return time.strftime('%Y-%m-%d %H:%MZ', time.gmtime(ms / 1000.0))
+
+
+def _fmt_span(seconds):
+    seconds = int(abs(seconds))
+    days, rest = divmod(seconds, 86400)
+    hours, rest = divmod(rest, 3600)
+    minutes = rest // 60
+    if days:
+        return f'{days}d {hours}h'
+    return f'{hours}h {minutes}m' if hours else f'{minutes}m'
+
+
+def _validity(entry, now):
+    expires = _expires_ms(entry)
+    if expires is None:
+        return 'expiry unknown'
+    left = expires / 1000.0 - now
+    if left >= 0:
+        return f'valid until {_fmt_ms(expires)} (in {_fmt_span(left)})'
+    return f'access token EXPIRED {_fmt_span(left)} ago'
+
+
+def _account_state(store, key, s, kind):
+    """One account store's view of one key, for status: missing / stub / fresh / stale /
+    own / forgotten — or, for a store that is not there or could not be read, its own
+    state ('absent': nothing to share into — a file is created for a setup-token account
+    alone, a Keychain item never)."""
+    if s['state'] != 'ok':
+        return s['state']
+    have = s['map'].get(key)
+    if have is None:
+        return 'missing'
+    if not is_login(have):
+        return 'stub'
+    if store.forgotten_match(key, have):
+        return 'forgotten'
+    rec = store.entries.get(key)
+    if rec is None or _same_tokens(have, rec['entry']):
+        return 'fresh'
+    if _superseded(rec, have) or _provably_older(have, rec['entry']):
+        return 'stale'
+    # another grant whose age the expiries cannot settle (or a newer one the next
+    # harvest takes): the pool leaves it where it is
+    return 'fresh' if _provably_older(rec['entry'], have) else 'own'
+
+
+def _status_doc(root, store, seen, now, paused):
+    """``paused``: why no launch on this machine shares any login right now, or None."""
+    keys = set(store.entries) | set(store.forgotten)
+    for stores in seen.values():
+        for s in stores.values():
+            if s and s['state'] == 'ok':
+                keys.update(k for k in s['map'] if isinstance(k, str) and k)
+    rows = []
+    for key in sorted(keys):
+        rec = store.entries.get(key)
+        entry = rec['entry'] if rec else None
+        if entry is None:
+            entry = next((s['map'][key] for stores in seen.values() for s in stores.values()
+                          if s and s['state'] == 'ok' and isinstance(s['map'].get(key), dict)),
+                         {})
+        backoff = (rec or {}).get('refresh') or {}
+        expires = _expires_ms(entry) if rec else None
+        accounts = {}
+        for aid in sorted(seen):
+            states = {}
+            for kind in ('file', 'keychain'):
+                s = seen[aid].get(kind)
+                if s is not None:
+                    states[kind] = _account_state(store, key, s, kind)
+            accounts[aid] = states
+        due_at = None
+        if rec and _has_refresh(entry) and expires is not None and not rec.get('needs_reauth'):
+            due_at = int(max(expires / 1000.0 - _refresh_window(rec, refresh_ahead()),
+                             _number(backoff.get('next_at')) or 0))
+        tomb = store.forgotten.get(key) or {}
+        rows.append({
+            'key': key, 'server_name': _server_name(key, entry),
+            'server_url': entry.get('serverUrl') if isinstance(entry.get('serverUrl'), str) else None,
+            'login': rec is not None,
+            'expires_at': int(expires) if expires is not None else None,
+            'expires_in_s': int(expires / 1000.0 - now) if expires is not None else None,
+            'expiry_assumed': bool((rec or {}).get('expiry_assumed')),
+            'lifetime_s': (rec or {}).get('lifetime_s'),
+            'has_refresh_token': bool(rec) and _has_refresh(entry),
+            'source': (rec or {}).get('source'), 'source_store': (rec or {}).get('store'),
+            'harvested_at': (rec or {}).get('harvested_at'),
+            'refreshed_at': (rec or {}).get('refreshed_at'),
+            'needs_reauth': bool((rec or {}).get('needs_reauth')),
+            'refresh_due_at': due_at,
+            'refresh_deferred': (rec or {}).get('deferred'),
+            'shared': bool(rec) and not paused and _sharing_off(rec, now) is None,
+            'not_shared_because': (paused or _sharing_off(rec, now)) if rec else None,
+            'retired': ({'at': tomb.get('at'), 'reason': tomb.get('reason')}
+                        if tomb and rec is None else None),
+            'backoff': {'failures': int(_number(backoff.get('failures')) or 0),
+                        'next_at': _number(backoff.get('next_at')),
+                        'last_error': backoff.get('last_error')},
+            'accounts': accounts})
+    beat = store.doc.get('refresher') or {}
+    return {'store': store.path, 'store_exists': store.exists, 'enabled': enabled(),
+            'refresh_enabled': refresh_enabled(), 'refresh_ahead_s': refresh_ahead(),
+            'keychain': keychain.enabled(), 'sharing_paused': paused,
+            'refresher': {'at': _number(beat.get('at')), 'refresh': beat.get('refresh')},
+            'keys': rows,
+            'forgotten': [{'key': k, 'at': v.get('at'), 'reason': v.get('reason')}
+                          for k, v in sorted(store.forgotten.items())],
+            'holds': [{'account': k, 'until': v.get('until'), 'reason': v.get('reason')}
+                      for k, v in sorted(store.doc['holds'].items())]}
+
+
+def _group(accounts, kind):
+    groups = {}
+    for aid, states in accounts.items():
+        state = states.get(kind)
+        if state is not None:
+            groups.setdefault(state, []).append(aid)
+    order = ('fresh', 'stale', 'own', 'stub', 'missing', 'forgotten', 'locked', 'absent')
+    return ' · '.join(f"{state} {' '.join(ids)}" for state, ids in
+                      sorted(groups.items(), key=lambda kv: (order.index(kv[0])
+                                                             if kv[0] in order else 99, kv[0])))
+
+
+def _print_status(doc, now):
+    print(f"MCP OAuth logins shared on this machine — {doc['store']}"
+          + ('' if doc['enabled'] else '  [sharing OFF: CLAUDE_MULTIACC_MCP_OAUTH=0]')
+          + ('' if doc['refresh_enabled'] else
+             '  [refresh OFF: CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0 — nothing is shared]'))
+    if doc['sharing_paused'] and doc['enabled'] and doc['refresh_enabled'] and doc['keys']:
+        print(f"  sharing paused: {doc['sharing_paused']} — every claude limits pass runs "
+              'one; claude-accounts mcp auth-sync runs one now')
+    if not doc['keys']:
+        print('  no MCP OAuth state in any account yet')
+    for row in doc['keys']:
+        print(f"{row['server_name']}  {row['server_url'] or ''}  [{row['key']}]".rstrip())
+        if not row['login']:
+            if row['retired']:
+                print(f"  login: none — retired {row['retired']['at']} ({row['retired']['reason']}); "
+                      'sign in once in any account (/mcp) and every account gets it')
+            else:
+                print('  login: none yet — authenticate it once in any account (/mcp) and every '
+                      'account gets it')
+        else:
+            entry = {'expiresAt': row['expires_at']}
+            source = f"{row['source'] or '?'} ({row['source_store'] or '?'})"
+            print(f"  login: {_validity(entry, now)}"
+                  + (' [expiry assumed: the server sent none]' if row['expiry_assumed'] else '')
+                  + f" · refresh token: {'yes' if row['has_refresh_token'] else 'no'} · from {source} "
+                  f"{row['harvested_at'] or ''}".rstrip()
+                  + (f" · refreshed {row['refreshed_at']}" if row['refreshed_at'] else ''))
+            back = row['backoff']
+            if row['needs_reauth']:
+                print(f"  refresh: NEEDS RE-AUTH ({back['last_error'] or 'refused'}) — sign in "
+                      'once in any account (/mcp)')
+            elif back['failures']:
+                print(f"  refresh: {back['failures']} failure(s), last {back['last_error']}; "
+                      f"retry after {_now_iso(back['next_at'] or now)}")
+            elif row['refresh_due_at'] is not None:
+                print(f"  refresh: due {_now_iso(row['refresh_due_at'])}"
+                      + (f" — deferred: {row['refresh_deferred']}" if row['refresh_deferred'] else ''))
+            if row['not_shared_because']:
+                print(f"  NOT shared: {row['not_shared_because']} (each account keeps what it holds)")
+        for kind, label in (('file', 'files'), ('keychain', 'keychain')):
+            line = _group(row['accounts'], kind)
+            if line:
+                print(f'  {label}: {line}')
+    for hold in doc['holds']:
+        print(f"hold: {hold['account']} keychain left alone until {_now_iso(hold['until'] or now)} "
+              f"({hold['reason']})")
+    live = {row['key'] for row in doc['keys'] if row['login']}
+    for tomb in doc['forgotten']:
+        if tomb['key'] in live:          # an older grant retired, a new login since
+            print(f"forgotten: an older login of {tomb['key']} at {tomb['at']}"
+                  + (f" ({tomb['reason']})" if tomb.get('reason') else ''))
+
+
+# -------------------------------------------------------------------------- verbs
+
+def cmd_ensure(args):
+    if not enabled():
+        return 0
+    account_dir = args.account_dir
+    accounts = account_dirs(args.root)
+    match = [aid for aid, d in accounts if os.path.normpath(d) == os.path.normpath(account_dir)]
+    if not match:
+        return 0
+    aid = match[0]
+    with _budget(ENSURE_BUDGET_S), PoolLock(args.root, wait=ENSURE_LOCK_WAIT_S) as lock:
+        if not lock.held:
+            return 0
+        store = Store(args.root).load()
+        # The Keychain item under the dir string the shim hands the client: its hash is
+        # the item's name.
+        kdirs = {aid: account_dir} if keychain.enabled() else {}
+        seen, stats = _harvest(args.root, accounts, kdirs, ENSURE_SECURITY_TIMEOUT_S)
+        if not store.exists and not _in_play(seen):
+            # The shim's grep matched text no document holds (a torn file): note the look,
+            # or every launch would start python again until some file changes.
+            if any(stores['file'].get('mentions') for stores in seen.values()):
+                _set_watermark(args.root, stats)
+            return 0
+        now = time.time()
+        _choose(store, seen, now)
+        _note_holders(store, seen, now)
+        if store.dirty or not store.exists:
+            store.save()
+        # Shared only behind a refreshing sync: this process never refreshes.
+        sharing = refresh_enabled() and store.refresher_ok(now)
+        res = _distribute(args.root, store, aid, account_dir, seen[aid], kdirs.get(aid),
+                          _plan(store, now, sharing), now, wait=ENSURE_LOCK_WAIT_S,
+                          timeout=ENSURE_SECURITY_TIMEOUT_S)
+        _hold(store, aid, res)
+        if store.dirty:
+            store.save()
+        if res['file'] not in TRANSIENT and res['keychain'] not in TRANSIENT:
+            _stamp(account_dir, store.clock)
+        _set_watermark(args.root, stats)
+    return 0
+
+
+def cmd_sync(args):
+    quiet = args.quiet
+    if not enabled():
+        if not quiet:
+            print('MCP OAuth sharing is off (CLAUDE_MULTIACC_MCP_OAUTH=0)')
+        return 0
+    deadline = time.monotonic() + SYNC_BUDGET_S
+    with _budget(SYNC_BUDGET_S), PoolLock(args.root, wait=30.0) as lock:
+        if not lock.held:
+            if not quiet:
+                print('another MCP OAuth sync holds the pool lock — skipped')
+            return 0
+        store = Store(args.root).load()
+        accounts = account_dirs(args.root)
+        kdirs = dict(accounts) if keychain.enabled() else {}
+        seen, stats = _harvest(args.root, accounts, kdirs, keychain.TIMEOUT_S)
+        if not store.exists and not _in_play(seen):
+            if not quiet:
+                print('no MCP OAuth state in any account yet — nothing to share')
+            return 0
+        now = time.time()
+        store.beat(now)
+        for key in _choose(store, seen, now):
+            rec = store.entries[key]
+            _log(args.root, f"{key}: login from {rec['source']} ({rec['store']})")
+        retired = _note_holders(store, seen, now)
+        if store.dirty or not store.exists:
+            store.save()
+        refreshed = {}
+        if refresh_enabled():
+            refreshed = _refresh_all(args.root, store, seen, args.force, deadline)
+        now = time.time()
+        plan = _plan(store, now, refresh_enabled())
+        results = {}
+        for aid, account_dir in accounts:
+            results[aid] = _distribute(args.root, store, aid, account_dir, seen[aid],
+                                       kdirs.get(aid), plan, now, wait=3.0,
+                                       timeout=keychain.TIMEOUT_S)
+            _hold(store, aid, results[aid])
+        if store.dirty:
+            store.save()
+        for aid, account_dir in accounts:
+            res = results[aid]
+            if res['file'] not in TRANSIENT and res['keychain'] not in TRANSIENT:
+                _stamp(account_dir, store.clock)
+        _set_watermark(args.root, stats)
+        if not quiet:
+            _print_sync(store, results, refreshed, retired, now)
+    return 0
+
+
+def _print_sync(store, results, refreshed, retired, now):
+    if not store.entries and not retired:
+        print('no MCP OAuth login in any account yet — authenticate a server once in any '
+              'account (/mcp) and every account gets it')
+    for key in sorted(retired):
+        tomb = store.forgotten.get(key) or {}
+        print(f"{key.split('|', 1)[0]} [{key}]: login retired ({tomb.get('reason')}) — "
+              'sign in once in any account (/mcp) and every account gets the new one')
+    for key in sorted(store.entries):
+        rec = store.entries[key]
+        written = sum(1 for r in results.values() for keys in r['held'].values() if key in keys)
+        words = [f"login from {rec.get('source') or '?'} ({rec.get('store') or '?'}), "
+                 f"{_validity(rec['entry'], now)}"]
+        outcome = refreshed.get(key)
+        if outcome == 'refreshed':
+            words.append('refreshed now')
+        elif outcome == 'deferred':
+            words.append(f"refresh deferred ({rec.get('deferred')})")
+        elif outcome:
+            words.append(f'refresh failed ({outcome})')
+        if rec.get('needs_reauth'):
+            words.append('NEEDS RE-AUTH — sign in once in any account (/mcp)')
+        why = _sharing_off(rec, now) or (None if refresh_enabled() else
+                                         'refresh is off (CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0)')
+        words.append(f'NOT shared: {why}' if why else f'{written} account store(s) updated')
+        print(f"{_server_name(key, rec['entry'])} [{key}]: {'; '.join(words)}")
+    missed = []
+    for aid in sorted(results):
+        for kind in ('file', 'keychain'):
+            state = results[aid][kind]
+            if state in UNREACHED:
+                missed.append(f'{aid} {kind} ({state})')
+    if missed:
+        print(f"not reached: {', '.join(missed)}")
+
+
+def cmd_status(args):
+    store = Store(args.root).load(readonly=True)
+    accounts = account_dirs(args.root)
+    kdirs = dict(accounts) if keychain.enabled() else {}
+    seen, _stats = _harvest(args.root, accounts, kdirs, keychain.TIMEOUT_S)
+    now = time.time()
+    # What a launch would do now: share only behind a refreshing sync.
+    beat = store.doc.get('refresher') or {}
+    if not enabled():
+        paused = 'sharing is off (CLAUDE_MULTIACC_MCP_OAUTH=0)'
+    elif not refresh_enabled():
+        paused = 'refresh is off (CLAUDE_MULTIACC_MCP_OAUTH_REFRESH=0)'
+    elif not store.refresher_ok(now):
+        last = _number(beat.get('at'))
+        paused = ('no refreshing sync in the last hour ('
+                  + (f"last {_now_iso(last)}" + ('' if beat.get('refresh') else ', refresh off')
+                     if last else 'none yet') + ')')
+    else:
+        paused = None
+    doc = _status_doc(args.root, store, seen, now, paused)
+    if args.json:
+        print(json.dumps(doc, indent=2))
+    else:
+        _print_status(doc, now)
+    return 0
+
+
+def cmd_forget(args):
+    name = args.name
+    with PoolLock(args.root, wait=30.0) as lock:
+        if not lock.held:
+            print('another MCP OAuth sync holds the pool lock — try again', file=sys.stderr)
+            return 1
+        store = Store(args.root).load()
+        accounts = account_dirs(args.root)
+        kdirs = dict(accounts) if keychain.enabled() else {}
+        seen, _stats = _harvest(args.root, accounts, kdirs, keychain.TIMEOUT_S)
+        keys = {k for k, rec in store.entries.items() if _server_name(k, rec['entry']) == name}
+        for stores in seen.values():
+            for s in stores.values():
+                if s and s['state'] == 'ok':
+                    keys.update(k for k, e in s['map'].items()
+                                if isinstance(k, str) and _server_name(k, e) == name)
+        if not keys:
+            print(f'no MCP OAuth state for {name} on this machine', file=sys.stderr)
+            return 1
+        now = time.time()
+        for key in sorted(keys):
+            digests = set()
+            for stores in seen.values():
+                for s in stores.values():
+                    if s and s['state'] == 'ok':
+                        digests |= _digests(s['map'].get(key))
+            store.retire(key, 'auth-forget', now, digests)
+        store.save()
+        _log(args.root, f"forget {name}: {','.join(sorted(keys))}")
+
+        def plan(mapping):
+            return {key: None for key in keys if key in mapping}
+
+        cleared, missed = 0, []
+        for aid, account_dir in accounts:
+            res = _distribute(args.root, store, aid, account_dir, seen[aid], kdirs.get(aid),
+                              plan, now, wait=3.0, timeout=keychain.TIMEOUT_S)
+            cleared += len(res['keys'])
+            for kind in ('file', 'keychain'):
+                if res[kind] in UNREACHED:
+                    missed.append(f'{aid} {kind} ({res[kind]})')
+        if store.dirty:
+            store.save()
+    if not args.quiet:
+        print(f"forgot {name}: {len(keys)} key(s); cleared from {cleared} account store(s)")
+        if missed:
+            print(f"not reached: {', '.join(missed)} — the retired login is ignored there "
+                  'and cleared by a later sync that can reach it')
+    return 0
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog='mcp_oauth.py', description=__doc__.split('\n\n')[0])
+    modes = parser.add_subparsers(dest='mode')
+    p = modes.add_parser('ensure', help='shim: share into one account before exec')
+    p.add_argument('--root', required=True)
+    p.add_argument('--account-dir', required=True)
+    p.add_argument('--quiet', action='store_true')
+    p = modes.add_parser('sync', help='harvest, refresh what is due, share into every account')
+    p.add_argument('--root', required=True)
+    p.add_argument('--quiet', action='store_true')
+    p.add_argument('--force', action='store_true', help='retry a refresh that is backing off')
+    p = modes.add_parser('status', help='what the pool holds (no secrets)')
+    p.add_argument('--root', required=True)
+    p.add_argument('--json', action='store_true')
+    p = modes.add_parser('forget', help="log a server out of every account on this machine")
+    p.add_argument('--root', required=True)
+    p.add_argument('name')
+    p.add_argument('--quiet', action='store_true')
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.mode:
+        parser.error('a mode is required (ensure, sync, status, forget)')
+    if not os.path.isdir(args.root):
+        print(f'mcp-oauth: pool root {args.root} does not exist', file=sys.stderr)
+        return 1
+    verb = {'ensure': cmd_ensure, 'sync': cmd_sync, 'status': cmd_status,
+            'forget': cmd_forget}[args.mode]
+    try:
+        return verb(args)
+    except _Budget:
+        _log(args.root, f'{args.mode}: time budget ran out — the next run carries on')
+        return 0
+
+
+if __name__ == '__main__':
+    fail_open = len(sys.argv) > 1 and sys.argv[1] in ('ensure', 'sync')
+    try:
+        sys.exit(main())
+    except Exception as error:  # noqa: BLE001 — a traceback is never the shim's problem
+        # The type only: a message could quote a path or a server answer, never a token,
+        # but nothing here is worth that risk.
+        print(f'mcp-oauth: {type(error).__name__}', file=sys.stderr)
+        sys.exit(0 if fail_open else 1)