claude-multiacc 2.0.57 → 2.0.59

package/tests/test_mcp_oauth.py

@@ -0,0 +1,1414 @@
+#!/usr/bin/env python3
+"""lib/mcp_oauth.py: an MCP server authenticated once in ANY pooled Claude account on this
+machine works in EVERY pooled Claude account on it.
+
+Runs everywhere: a fake `security` on PATH (tests/fake_security.sh, with
+CLAUDE_MULTIACC_KEYCHAIN=1) serves Keychain items from a temp dir, and a loopback
+http.server plays the authorization server. Nothing here can touch a real keychain, a
+real pool or the network: an entry that is due for a refresh names either the loopback
+server or a plain-http host the module refuses to send a token to. Every token is a fake
+value, and no output may contain one.
+"""
+
+from __future__ import annotations
+
+import base64
+import contextlib
+import http.server
+import importlib.util
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import unittest
+import urllib.parse
+
+REPO = Path(__file__).resolve().parents[1]
+LIB = REPO / 'lib'
+SHIM = REPO / 'bin' / 'claude'
+FAKE_SECURITY = (REPO / 'tests' / 'fake_security.sh').read_text()
+sys.path.insert(0, str(LIB))
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location('mcp_oauth', LIB / 'mcp_oauth.py')
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+M = _load()
+KEY = 'higgsfield|0a1b2c3d4e5f6a7b'
+OTHER_KEY = 'linear|1122334455667788'
+CLIENT_ID = 'https://claude.ai/oauth/claude-code-client-metadata'
+SERVER_URL = 'https://mcp.higgsfield.example/mcp'
+#: an authorization server the module refuses outright (plain http to another host): a
+#: due login naming it fails its refresh without a single packet leaving the machine
+NO_AS = 'http://auth.example.invalid'
+HOUR_MS = 3600 * 1000
+#: every environment knob this module or the fake reads — saved, then set per test (an
+#: ambient proxy would carry the loopback authorization server's traffic elsewhere)
+ENV_KEYS = ('PATH', 'USER', 'CLAUDE_MULTIACC_KEYCHAIN', 'FAKE_KEYCHAIN_DIR', 'FAKE_KEYCHAIN_LOCKED',
+            'FAKE_KEYCHAIN_MDAT', 'FAKE_SECURITY_LOG', 'CLAUDE_MULTIACC_MCP_OAUTH',
+            'CLAUDE_MULTIACC_MCP_OAUTH_REFRESH', 'CLAUDE_MULTIACC_MCP_OAUTH_REFRESH_AHEAD',
+            'http_proxy', 'https_proxy', 'all_proxy', 'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY')
+
+
+class AuthServer:
+    """A loopback OAuth authorization server: RFC 8414 metadata at ``meta_path`` and a
+    token endpoint whose answers a test scripts (default: rotate both tokens, 24 h).
+    Every token request is recorded — form fields and whether it carried Basic auth."""
+
+    def __init__(self, base_path='', meta_path=None, methods=None):
+        self.base_path = base_path
+        self.meta_path = meta_path or f'/.well-known/oauth-authorization-server{base_path}'
+        self.methods = methods
+        self.answers = []
+        self.requests = []
+        self.metadata_hits = []
+        self.issued = 0
+        self.lifetime = 86400
+        server = self
+
+        class Handler(http.server.BaseHTTPRequestHandler):
+            def log_message(self, *_args):
+                pass
+
+            def _send(self, status, doc):
+                body = json.dumps(doc).encode()
+                self.send_response(status)
+                self.send_header('Content-Type', 'application/json')
+                self.send_header('Content-Length', str(len(body)))
+                self.end_headers()
+                self.wfile.write(body)
+
+            def do_GET(self):  # noqa: N802 — http.server's naming
+                server.metadata_hits.append(self.path)
+                if self.path != server.meta_path:
+                    return self._send(404, {'error': 'not_found'})
+                doc = {'issuer': server.url, 'token_endpoint': f'{server.origin}/token',
+                       'authorization_endpoint': f'{server.origin}/authorize'}
+                if server.methods is not None:
+                    doc['token_endpoint_auth_methods_supported'] = server.methods
+                return self._send(200, doc)
+
+            def do_POST(self):  # noqa: N802
+                length = int(self.headers.get('Content-Length') or 0)
+                form = dict(urllib.parse.parse_qsl(self.rfile.read(length).decode()))
+                server.requests.append({'path': self.path, 'form': form,
+                                        'authorization': self.headers.get('Authorization')})
+                if server.answers:
+                    status, doc = server.answers.pop(0)
+                else:
+                    server.issued += 1
+                    status, doc = 200, {'access_token': f'fake-mcp-access-rotated-{server.issued}',
+                                        'refresh_token': f'fake-mcp-refresh-rotated-{server.issued}',
+                                        'expires_in': server.lifetime, 'token_type': 'Bearer'}
+                return self._send(status, doc)
+
+        self.httpd = http.server.ThreadingHTTPServer(('127.0.0.1', 0), Handler)
+        self.origin = f'http://127.0.0.1:{self.httpd.server_address[1]}'
+        self.url = f'{self.origin}{base_path}'
+        self.thread = threading.Thread(target=self.httpd.serve_forever, daemon=True)
+        self.thread.start()
+
+    def stop(self):
+        self.httpd.shutdown()
+        self.httpd.server_close()
+
+
+class Case(unittest.TestCase):
+    ACCOUNTS = ('acct-01', 'acct-02', 'acct-03')
+
+    def setUp(self):
+        self.work = tempfile.TemporaryDirectory()
+        self.addCleanup(self.work.cleanup)
+        work = Path(self.work.name)
+        self.fakebin = work / 'bin'
+        self.fakebin.mkdir()
+        tool = self.fakebin / 'security'
+        tool.write_text(FAKE_SECURITY)
+        tool.chmod(0o755)
+        self.kcdir = work / 'keychain'
+        self.calllog = work / 'security.log'
+        self.root = work / 'pool'
+        self.root.mkdir()
+        (self.root / 'accounts.json').write_text(json.dumps(
+            {'version': 1, 'accounts': [{'id': a} for a in self.ACCOUNTS]}))
+        for account in self.ACCOUNTS:
+            (self.root / account).mkdir()
+        saved = {k: os.environ.get(k) for k in ENV_KEYS}
+
+        def restore():
+            for k, v in saved.items():
+                if v is None:
+                    os.environ.pop(k, None)
+                else:
+                    os.environ[k] = v
+        self.addCleanup(restore)
+        for k in ENV_KEYS:
+            os.environ.pop(k, None)
+        os.environ.update({'PATH': f"{self.fakebin}:{saved['PATH'] or '/usr/bin:/bin'}",
+                           'USER': 'gas', 'CLAUDE_MULTIACC_KEYCHAIN': '1',
+                           'FAKE_KEYCHAIN_DIR': str(self.kcdir)})
+        self.now_ms = int(time.time() * 1000)
+        self.secrets = set()
+        self.server = None
+
+    def tearDown(self):
+        if self.server is not None:
+            self.server.stop()
+
+    # -- fixtures ---------------------------------------------------------------------
+    def d(self, account):
+        return str(self.root / account)
+
+    def entry(self, tag, hours=20.0, refresh=True, as_url='https://clerk.higgsfield.example',
+              **extra):
+        """An MCP entry shaped like the client's own (2.1.303). ``hours=None``: saved
+        without an expiry, as the client does when the token answer had no expires_in."""
+        e = {'serverName': 'higgsfield', 'serverUrl': SERVER_URL,
+             'accessToken': f'fake-mcp-access-{tag}', 'scope': 'openid offline_access',
+             'issuer': as_url, 'clientId': CLIENT_ID,
+             'redirectUri': 'http://localhost:53682/callback',
+             'discoveryState': {'authorizationServerUrl': as_url, 'oauthMetadataFound': True,
+                                'resourceMetadataUrl': f'{SERVER_URL}/.well-known/oauth-protected-resource'}}
+        if hours is not None:
+            e['expiresAt'] = self.now_ms + int(hours * HOUR_MS)
+        if refresh:
+            e['refreshToken'] = f'fake-mcp-refresh-{tag}'
+        e.update(extra)
+        self.secrets.update(v for k, v in e.items()
+                            if k in ('accessToken', 'refreshToken', 'clientSecret') and v)
+        return e
+
+    def stub(self, hours=None):
+        """What a discovery-only client leaves behind (2.1.304 saveDiscoveryState): no
+        token, and no expiry unless an earlier entry had one."""
+        e = {'serverName': 'higgsfield', 'serverUrl': SERVER_URL, 'accessToken': '',
+             'discoveryState': {'authorizationServerUrl': 'https://clerk.higgsfield.example'}}
+        if hours is not None:
+            e['expiresAt'] = self.now_ms + int(hours * HOUR_MS)
+        return e
+
+    def blanked(self, entry):
+        """What the client leaves after a refused refresh (invalidateCredentials 'tokens')."""
+        return dict({k: v for k, v in entry.items() if k != 'refreshToken'},
+                    accessToken='', expiresAt=0)
+
+    def login(self, n):
+        doc = {'accessToken': f'fake-claude-access-{n}', 'refreshToken': f'fake-claude-refresh-{n}',
+               'expiresAt': self.now_ms + 8 * HOUR_MS, 'scopes': ['user:inference', 'user:profile'],
+               'subscriptionType': 'max', 'rateLimitTier': 'default_claude_max_20x'}
+        self.secrets.update((doc['accessToken'], doc['refreshToken']))
+        return doc
+
+    def put_file(self, account, doc, mtime=None):
+        path = self.root / account / '.credentials.json'
+        path.write_text(json.dumps(doc, separators=(',', ':')))
+        path.chmod(0o600)
+        if mtime is not None:
+            os.utime(path, (mtime, mtime))
+        return path
+
+    def stub_files(self, *accounts):
+        """The file a tmux client writes once it meets the OAuth server (MCP state alone)."""
+        for account in accounts:
+            self.put_file(account, {'mcpOAuth': {KEY: self.stub()}})
+
+    def has_file(self, account):
+        return (self.root / account / '.credentials.json').exists()
+
+    def file_doc(self, account):
+        return json.loads((self.root / account / '.credentials.json').read_text())
+
+    def kc_service(self, account):
+        return M.keychain.service_name(self.d(account))
+
+    def kc_put(self, account, doc, name='gas'):
+        subprocess.run(['security', 'add-generic-password', '-U', '-a', name, '-s',
+                        self.kc_service(account), '-X', json.dumps(doc).encode().hex()],
+                       check=True)
+
+    def kc_raw(self, account, name='gas'):
+        path = self.kcdir / self.kc_service(account) / name / 'secret'
+        return path.read_bytes() if path.exists() else None
+
+    def kc_doc(self, account, name='gas'):
+        raw = self.kc_raw(account, name)
+        return json.loads(raw) if raw is not None else None
+
+    def store(self):
+        return json.loads((self.root / 'mcp-oauth.json').read_text())
+
+    def edit_store(self, fn):
+        """Change the store the way time would (an expiry coming due, an old beat)."""
+        path = self.root / 'mcp-oauth.json'
+        doc = json.loads(path.read_text()) if path.exists() else \
+            {'version': 1, 'entries': {}, 'forgotten': {}, 'holds': {}}
+        fn(doc)
+        path.write_text(json.dumps(doc))
+        path.chmod(0o600)
+
+    def beat(self, ago=0, refresh=True):
+        """The refresher's beat `ensure` shares behind, as a sync leaves it."""
+        def set_beat(doc):
+            doc['refresher'] = {'at': int(time.time() - ago), 'refresh': refresh}
+        self.edit_store(set_beat)
+
+    def run_cli(self, *argv):
+        out, err = io.StringIO(), io.StringIO()
+        with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+            rc = M.main([argv[0], '--root', str(self.root), *argv[1:]])
+        return rc, out.getvalue(), err.getvalue()
+
+    def sync(self, *extra):
+        rc, out, err = self.run_cli('sync', *extra)
+        self.assertEqual(rc, 0, err)
+        return out
+
+    def ensure(self, account):
+        rc, out, err = self.run_cli('ensure', '--account-dir', self.d(account), '--quiet')
+        self.assertEqual(rc, 0, err)
+        return out + err
+
+    def status_json(self):
+        rc, out, err = self.run_cli('status', '--json')
+        self.assertEqual(rc, 0, err)
+        return json.loads(out)
+
+    def security_calls(self, fn, *args):
+        self.calllog.write_text('')
+        os.environ['FAKE_SECURITY_LOG'] = str(self.calllog)
+        try:
+            result = fn(*args)
+        finally:
+            os.environ.pop('FAKE_SECURITY_LOG', None)
+        return result, self.calllog.read_text().splitlines()
+
+    def auth_server(self, **kwargs):
+        self.server = AuthServer(**kwargs)
+        return self.server
+
+
+# --------------------------------------------------------------------------- harvest
+
+class HarvestTests(Case):
+    def test_the_largest_expiry_wins_and_reaches_every_account(self):
+        old, new = self.entry('old', hours=2), self.entry('new', hours=20)
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {KEY: old}})
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.stub_files('acct-03')
+        out = self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry'], new)
+        self.assertEqual((rec['source'], rec['store']), ('acct-02', 'file'))
+        self.assertIn('harvested_at', rec)
+        self.assertEqual(rec['holders'], ['acct-01:file', 'acct-02:file', 'acct-03:file'])
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], new, account)
+        self.assertEqual(self.file_doc('acct-01')['claudeAiOauth'], self.login(1))
+        self.assertIn('login from acct-02 (file)', out)
+        self.assertEqual(os.stat(self.root / 'mcp-oauth.json').st_mode & 0o777, 0o600)
+
+    def test_stubs_never_win_and_never_overwrite(self):
+        real = self.entry('real', hours=5)
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.stub(hours=500)}})
+        self.put_file('acct-02', {'mcpOAuth': {KEY: real}})
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['entry'], real)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], real)   # the stub is replaced
+        # a key nobody holds a login for stays out of the store, and nothing is written
+        self.put_file('acct-03', {'mcpOAuth': {OTHER_KEY: self.stub()}})
+        before = (self.root / 'acct-01' / '.credentials.json').read_bytes()
+        self.sync()
+        self.assertNotIn(OTHER_KEY, self.store()['entries'])
+        self.assertEqual((self.root / 'acct-01' / '.credentials.json').read_bytes(), before)
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][OTHER_KEY], self.stub())
+
+    def test_ties_prefer_a_refresh_token_then_the_stores_own_copy(self):
+        with_rt = self.entry('rt', hours=10)
+        without = self.entry('nort', hours=10, refresh=False)
+        without['expiresAt'] = with_rt['expiresAt']
+        self.put_file('acct-01', {'mcpOAuth': {KEY: without}})
+        self.put_file('acct-02', {'mcpOAuth': {KEY: with_rt}})
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['entry'], with_rt)
+        # an equally ranked OTHER copy never displaces the store's: no flip-flopping
+        twin = dict(with_rt, accessToken='fake-mcp-access-twin')
+        self.secrets.add('fake-mcp-access-twin')
+        self.put_file('acct-03', {'mcpOAuth': {KEY: twin}})
+        stamp = self.store()['entries'][KEY]['harvested_at']
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual((rec['entry'], rec['harvested_at']), (with_rt, stamp))
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], twin)  # equal rank: left alone
+
+    def test_a_refused_login_loses_to_any_other_grant(self):
+        newest, older = self.entry('newest', hours=20), self.entry('older', hours=3)
+        self.put_file('acct-01', {'mcpOAuth': {KEY: newest}})
+        self.sync()
+        self.edit_store(lambda doc: doc['entries'][KEY].update(needs_reauth=True))
+        self.put_file('acct-02', {'mcpOAuth': {KEY: older}})
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry'], older)
+        self.assertNotIn('needs_reauth', rec)
+
+    def test_keychain_items_are_harvested_only_when_this_session_can_read_them(self):
+        held = self.entry('keychain', hours=30)
+        self.kc_put('acct-02', {'claudeAiOauth': self.login(2), 'mcpOAuth': {KEY: held}})
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.entry('file', hours=5)}})
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['source'], 'acct-01')
+        os.environ.pop('FAKE_KEYCHAIN_LOCKED')
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual((rec['entry'], rec['source'], rec['store']), (held, 'acct-02', 'keychain'))
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], held)
+        self.assertEqual(self.kc_doc('acct-02')['claudeAiOauth'], self.login(2))
+
+    def test_a_login_saved_without_an_expiry_is_never_older_than_every_copy(self):
+        # The client's saveTokens drops expiresAt when the token answer has no expires_in.
+        # Ranked as "no expiry = oldest", one sync put the other accounts' older copy back
+        # over the rotated grant — in the very account that held it.
+        old = self.entry('old', hours=0.5, as_url=NO_AS)
+        for account in self.ACCOUNTS:
+            self.put_file(account, {'mcpOAuth': {KEY: old}})
+        self.sync()
+        rotated = self.entry('rotated', hours=None, as_url=NO_AS)
+        self.put_file('acct-01', {'mcpOAuth': {KEY: rotated}})
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry']['refreshToken'], rotated['refreshToken'])
+        self.assertTrue(rec['expiry_assumed'])
+        self.assertAlmostEqual(rec['entry']['expiresAt'] / 1000, time.time() + 3600, delta=60)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], rotated)   # untouched
+        for account in ('acct-02', 'acct-03'):
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], rec['entry'], account)
+        # ...and a login of ANOTHER grant whose age the expiries cannot settle stays put
+        other = self.entry('other', hours=None, as_url=NO_AS)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: other}})
+        self.sync()
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], other)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], rotated)
+
+
+# ------------------------------------------------------------------------ distribute
+
+class DistributeTests(Case):
+    def test_a_merge_touches_one_key_and_keeps_everything_else_exactly(self):
+        mine = self.entry('mine', hours=1)
+        theirs = self.entry('theirs', hours=20)
+        unrelated = {'serverName': 'linear', 'accessToken': 'fake-mcp-access-linear',
+                     'expiresAt': self.now_ms + HOUR_MS}
+        self.secrets.add('fake-mcp-access-linear')
+        doc = {'claudeAiOauth': self.login(1), 'mcpOAuth': {OTHER_KEY: unrelated, KEY: mine},
+               'mcpOAuthClientConfig': {'higgsfield': {'clientId': CLIENT_ID}},
+               'somethingNew': [1, 2.5, None, {'ünïcode': '✓'}]}
+        path = self.put_file('acct-01', doc, mtime=time.time() - 3600)
+        before = os.stat(path)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: theirs}})
+        self.sync()
+        after = self.file_doc('acct-01')
+        self.assertEqual(list(after), list(doc))                      # same keys, same order
+        self.assertEqual(after['claudeAiOauth'], doc['claudeAiOauth'])
+        self.assertEqual(after['mcpOAuthClientConfig'], doc['mcpOAuthClientConfig'])
+        self.assertEqual(after['somethingNew'], doc['somethingNew'])
+        self.assertEqual(list(after['mcpOAuth']), [OTHER_KEY, KEY])
+        self.assertEqual(after['mcpOAuth'], {OTHER_KEY: unrelated, KEY: theirs})
+        st = os.stat(path)
+        self.assertEqual(st.st_mode & 0o777, 0o600)
+        # an MCP merge is not a login: bin/claude and lib/audit.py read a newer file as one
+        self.assertEqual(st.st_mtime_ns, before.st_mtime_ns)
+        self.assertEqual(sorted(os.listdir(self.root / 'acct-01')), ['.credentials.json',
+                                                                     '.mcp-oauth-applied'])
+
+    def test_a_credentials_file_is_created_for_a_setup_token_account_only(self):
+        # Every reader counts a document as a login only when it carries claudeAiOauth
+        # (bin/claude file_login, lib/audit.py file_has_login): MCP state alone beside a
+        # setup token costs it nothing, and is the very file that account's client writes
+        # itself once it meets an OAuth server from a session that cannot open the
+        # Keychain. An account with a Keychain login has a store of its own already.
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.kc_put('acct-03', {'claudeAiOauth': self.login(3)})
+        (self.root / 'acct-01' / 'server.token').write_text('fake-setup-token-01')
+        self.secrets.add('fake-setup-token-01')
+        self.beat()
+        self.ensure('acct-01')
+        path = self.root / 'acct-01' / '.credentials.json'
+        self.assertEqual(self.file_doc('acct-01'), {'mcpOAuth': {KEY: new}})
+        self.assertEqual(os.stat(path).st_mode & 0o777, 0o600)
+        self.assertTrue((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        self.assertEqual([n for n in os.listdir(self.root / 'acct-01') if n.endswith('.tmp')], [])
+        self.assertIn(f'acct-01 file: created with {KEY}', (self.root / 'ops.log').read_text())
+        self.ensure('acct-03')
+        out = self.sync()
+        self.assertFalse(self.has_file('acct-03'))
+        self.assertTrue((self.root / 'acct-03' / '.mcp-oauth-applied').exists())
+        self.assertEqual(self.kc_doc('acct-03')['mcpOAuth'][KEY], new)
+        self.assertEqual(self.kc_doc('acct-03')['claudeAiOauth'], self.login(3))
+        self.assertNotIn('acct-03 file', out)                # absent is not "not reached"
+        row = {r['key']: r for r in self.status_json()['keys']}[KEY]
+        self.assertEqual(row['accounts']['acct-01'], {'file': 'fresh', 'keychain': 'absent'})
+        self.assertEqual(row['accounts']['acct-03'], {'file': 'absent', 'keychain': 'fresh'})
+        self.assertIn('acct-01:file', self.store()['entries'][KEY]['holders'])
+        # a discovery stub the client wrote first is merged into, like any file
+        self.stub_files('acct-03')
+        self.ensure('acct-03')
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], new)
+
+    def test_no_file_is_created_where_it_could_cost_anything(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        for account in ('acct-01', 'acct-03'):
+            (self.root / account / 'server.token').write_text('fake-setup-token-x')
+        self.secrets.add('fake-setup-token-x')
+        # sharing paused (no refreshing sync behind this launch): nothing to share, no file
+        self.ensure('acct-01')
+        self.assertFalse(self.has_file('acct-01'))
+        (self.root / 'acct-01' / '.expired').write_text('reason=auth-error\n')   # parked
+        link = self.root / 'acct-03' / '.credentials.json'
+        link.symlink_to(Path(self.work.name) / 'gone.json')                      # a name taken
+        self.sync()
+        self.assertFalse(self.has_file('acct-01'))
+        self.assertTrue(link.is_symlink() and not link.exists())
+        # an empty token is no token; an adopted dir is ~/.claude itself
+        (self.root / 'acct-01' / '.expired').unlink()
+        (self.root / 'acct-01' / 'server.token').write_text('')
+        home = Path(self.work.name) / 'home-claude'
+        home.mkdir()
+        (home / 'server.token').write_text('fake-setup-token-x')
+        (self.root / 'acct-04').symlink_to(home)
+        (self.root / 'accounts.json').write_text(json.dumps(
+            {'version': 1, 'accounts': [{'id': a} for a in self.ACCOUNTS + ('acct-04',)]}))
+        self.sync()
+        self.assertFalse(self.has_file('acct-01'))
+        self.assertFalse((home / '.credentials.json').exists())
+        # once back in the pool with a token, the account gets its file
+        (self.root / 'acct-01' / 'server.token').write_text('fake-setup-token-x')
+        self.sync()
+        self.assertEqual(self.file_doc('acct-01'), {'mcpOAuth': {KEY: new}})
+
+    def test_a_file_the_client_writes_first_is_merged_into(self):
+        # The client takes the same lock, but a name that is free when the merge looks may
+        # not be free when the file lands: the new file appears only where none is, and a
+        # file the client wrote meanwhile is merged into instead, its own state kept.
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        (self.root / 'acct-01' / 'server.token').write_text('fake-setup-token-01')
+        self.secrets.add('fake-setup-token-01')
+        theirs = {'serverName': 'linear', 'accessToken': 'fake-mcp-access-linear',
+                  'expiresAt': self.now_ms + HOUR_MS}
+        self.secrets.add('fake-mcp-access-linear')
+        real_scratch = M._scratch
+        calls = []
+
+        def racing_scratch(directory, name, data, mode=0o600):
+            scratch = real_scratch(directory, name, data, mode)
+            if directory == str(self.root / 'acct-01') and not calls:
+                calls.append(1)
+                self.put_file('acct-01', {'mcpOAuth': {OTHER_KEY: theirs}})
+            return scratch
+
+        M._scratch = racing_scratch
+        self.addCleanup(setattr, M, '_scratch', real_scratch)
+        self.beat()
+        self.ensure('acct-01')
+        self.assertEqual(calls, [1])
+        self.assertEqual(self.file_doc('acct-01'), {'mcpOAuth': {OTHER_KEY: theirs, KEY: new}})
+        self.assertEqual([n for n in os.listdir(self.root / 'acct-01') if n.endswith('.tmp')], [])
+
+    def test_a_document_this_module_does_not_understand_is_never_rewritten(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('x')}})
+        (self.root / 'acct-01' / '.credentials.json').write_text('{"claudeAiOauth": {"accessT')
+        self.put_file('acct-03', {'claudeAiOauth': self.login(3), 'mcpOAuth': ['not', 'a', 'map']})
+        raw1 = (self.root / 'acct-01' / '.credentials.json').read_bytes()
+        raw3 = (self.root / 'acct-03' / '.credentials.json').read_bytes()
+        out = self.sync()
+        self.assertEqual((self.root / 'acct-01' / '.credentials.json').read_bytes(), raw1)
+        self.assertEqual((self.root / 'acct-03' / '.credentials.json').read_bytes(), raw3)
+        self.assertIn('acct-01 file (corrupt)', out)
+
+    def test_a_symlinked_credentials_file_keeps_its_link(self):
+        real = Path(self.work.name) / 'elsewhere.json'
+        real.write_text(json.dumps({'claudeAiOauth': self.login(1)}))
+        link = self.root / 'acct-01' / '.credentials.json'
+        link.symlink_to(real)
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.sync()
+        self.assertTrue(link.is_symlink())
+        self.assertEqual(json.loads(real.read_text())['mcpOAuth'][KEY], new)
+        self.assertEqual(json.loads(real.read_text())['claudeAiOauth'], self.login(1))
+
+    def test_a_parked_account_gets_no_keychain_write_until_it_is_back(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        (self.root / 'acct-01' / '.expired').write_text('reason=auth-error\n')
+        (self.root / 'acct-03' / '.expired').write_text('reason=auth-error\n')
+        path = self.put_file('acct-03', {'mcpOAuth': {}}, mtime=time.time() - 600)
+        before = os.stat(path).st_mtime_ns
+        self.kc_put('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {}})
+        raw_kc = self.kc_raw('acct-01')
+        out = self.sync()
+        self.assertFalse(self.has_file('acct-01'))
+        self.assertEqual(self.kc_raw('acct-01'), raw_kc)
+        # an existing file is merged — and keeps its mtime, so the park stays in force
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], new)
+        self.assertEqual(os.stat(path).st_mtime_ns, before)
+        self.assertFalse((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        self.assertIn('acct-01 keychain (parked)', out)
+        (self.root / 'acct-01' / '.expired').unlink()
+        self.sync()
+        self.assertEqual(self.kc_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertFalse(self.has_file('acct-01'))
+
+    def test_a_held_client_lock_is_waited_on(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1)})
+        lock = self.root / 'acct-01' / '.storage-write.lock'
+        lock.mkdir()
+        timer = threading.Timer(0.4, lock.rmdir)
+        timer.start()
+        self.addCleanup(timer.cancel)
+        self.sync()
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertFalse(lock.exists())
+
+    def test_a_lock_held_past_the_wait_leaves_the_account_for_the_next_run(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1)})
+        self.beat()
+        raw = (self.root / 'acct-01' / '.credentials.json').read_bytes()
+        lock = self.root / 'acct-01' / '.storage-write.lock'
+        lock.mkdir()
+        rc, _out, err = self.run_cli('ensure', '--account-dir', self.d('acct-01'))
+        self.assertEqual(rc, 0, err)
+        self.assertEqual((self.root / 'acct-01' / '.credentials.json').read_bytes(), raw)
+        self.assertTrue(lock.is_dir())                      # never ours to remove
+        self.assertFalse((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        lock.rmdir()
+        self.ensure('acct-01')
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertTrue((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+
+    def test_a_stale_client_lock_is_taken_over(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.stub_files('acct-01')
+        self.beat()
+        lock = self.root / 'acct-01' / '.storage-write.lock'
+        lock.mkdir()
+        old = time.time() - 60
+        os.utime(lock, (old, old))
+        self.ensure('acct-01')
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertFalse(lock.exists())
+
+    def test_a_file_rewritten_under_the_merge_is_merged_again(self):
+        # The limits pass rotates a login WITHOUT the client's lock: a merge that read the
+        # file before that write must not put the old login back.
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        path = self.put_file('acct-01', {'claudeAiOauth': self.login(1)})
+        rotated = self.login(11)
+        real_scratch = M._scratch
+        calls = []
+
+        def racing_scratch(directory, name, data, mode=0o600):
+            scratch = real_scratch(directory, name, data, mode)
+            if directory == str(self.root / 'acct-01') and not calls:
+                calls.append(1)
+                path.write_text(json.dumps({'claudeAiOauth': rotated}))
+            return scratch
+
+        M._scratch = racing_scratch
+        self.addCleanup(setattr, M, '_scratch', real_scratch)
+        self.sync()
+        after = self.file_doc('acct-01')
+        self.assertEqual(after['claudeAiOauth'], rotated)
+        self.assertEqual(after['mcpOAuth'][KEY], new)
+        self.assertEqual(calls, [1])
+        leftovers = [n for n in os.listdir(self.root / 'acct-01') if n.endswith('.tmp')]
+        self.assertEqual(leftovers, [])
+
+    def test_a_file_holding_a_login_waits_out_a_running_limits_pass(self):
+        # ...and a merge must not land between that pass's read and its write either.
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1)})
+        self.stub_files('acct-03')
+        (self.root / '.locks' / 'limits').mkdir(parents=True)
+        raw = (self.root / 'acct-01' / '.credentials.json').read_bytes()
+        out = self.sync()
+        self.assertEqual((self.root / 'acct-01' / '.credentials.json').read_bytes(), raw)
+        self.assertIn('acct-01 file (deferred)', out)
+        self.assertFalse((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], new)  # MCP state alone
+        (self.root / '.locks' / 'limits').rmdir()
+        self.sync()
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+
+
+# -------------------------------------------------------------------------- keychain
+
+class KeychainTests(Case):
+    def test_an_item_is_merged_through_stdin_and_read_back(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        doc = {'claudeAiOauth': self.login(1), 'mcpOAuth': {KEY: self.stub()}}
+        self.kc_put('acct-01', doc)
+        _, calls = self.security_calls(self.sync)
+        back = self.kc_doc('acct-01')
+        self.assertEqual(back['claudeAiOauth'], doc['claudeAiOauth'])
+        self.assertEqual(back['mcpOAuth'][KEY], new)
+        writes = [c for c in calls if c.startswith('add-generic-password')]
+        self.assertEqual(writes, ['add-generic-password a=gas w=0 via=stdin'])
+        # ...and NO file beside it: the limits pass and the audit would take a file for
+        # the login, and the Keychain login would go dark (KeychainStore: never copied out)
+        self.assertFalse(self.has_file('acct-01'))
+
+    def test_a_secret_printed_as_hex_still_reads_as_the_document(self):
+        # `find-generic-password -w` prints a secret it cannot show as text in hex.
+        doc = {'claudeAiOauth': {'accessToken': 'fake-claude-access-ü'}, 'mcpOAuth': {}}
+        self.secrets.add('fake-claude-access-ü')
+        text = json.dumps(doc, ensure_ascii=False).encode('utf-8').hex()
+        self.assertEqual(M.keychain._json_object(text + '\n'), doc)
+        self.assertIsNone(M.keychain._json_object('7b22'))          # hex, but not JSON
+        self.assertIsNone(M.keychain._json_object('[1, 2]'))        # JSON, not an object
+
+    def test_a_document_too_long_for_the_stdin_buffer_goes_on_argv(self):
+        big = self.entry('big', padding='x' * 3000)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: big}})
+        self.kc_put('acct-01', {'claudeAiOauth': self.login(1)})
+        _, calls = self.security_calls(self.sync)
+        self.assertIn('add-generic-password a=gas w=0', calls)
+        self.assertNotIn('add-generic-password a=gas w=0 via=stdin', calls)
+        self.assertEqual(self.kc_doc('acct-01')['mcpOAuth'][KEY], big)
+
+    def test_a_locked_keychain_means_file_only(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.kc_put('acct-01', {'claudeAiOauth': self.login(1)})
+        self.stub_files('acct-01')          # what the client writes when it cannot open it
+        raw = self.kc_raw('acct-01')
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        _, calls = self.security_calls(self.sync)
+        self.assertEqual(self.kc_raw('acct-01'), raw)
+        self.assertFalse([c for c in calls if c.startswith('add-generic-password')])
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+
+    def test_an_absent_item_is_never_created(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        _, calls = self.security_calls(self.sync)
+        self.assertFalse([c for c in calls if c.startswith('add-generic-password')])
+        self.assertFalse(self.kcdir.exists() and any(self.kcdir.iterdir()))
+        self.assertFalse(self.has_file('acct-01') or self.has_file('acct-03'))
+
+    def test_a_read_back_mismatch_holds_the_item(self):
+        # A `security` that answers 0 to a write and stores nothing.
+        tool = self.fakebin / 'security'
+        tool.rename(self.fakebin / 'security-real')
+        tool.write_text('#!/usr/bin/env bash\n'
+                        '[ "$1" = "-i" ] && { cat >/dev/null; exit 0; }\n'
+                        f'exec "{self.fakebin}/security-real" "$@"\n')
+        tool.chmod(0o755)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        self.kc_put('acct-01', {'claudeAiOauth': self.login(1)})
+        out = self.sync()
+        holds = self.store()['holds']
+        self.assertEqual(list(holds), ['acct-01'])
+        self.assertIn('acct-01 keychain (mismatch)', out)
+        _, calls = self.security_calls(self.sync)
+        self.assertFalse([c for c in calls if c.startswith('add-generic-password')])
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('hold: acct-01 keychain', status)
+
+    def test_a_running_limits_pass_defers_an_item_holding_a_login(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.kc_put('acct-01', {'claudeAiOauth': self.login(1)})
+        (self.root / '.locks' / 'limits').mkdir(parents=True)
+        raw = self.kc_raw('acct-01')
+        out = self.sync()
+        self.assertEqual(self.kc_raw('acct-01'), raw)
+        self.assertIn('acct-01 keychain (deferred)', out)
+        self.assertFalse(self.has_file('acct-01'))
+        self.assertFalse((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        (self.root / '.locks' / 'limits').rmdir()
+        self.sync()
+        self.assertEqual(self.kc_doc('acct-01')['mcpOAuth'][KEY], new)
+
+
+# --------------------------------------------------------------------------- refresh
+
+class RefreshTests(Case):
+    def setUp(self):
+        super().setUp()
+        self.as_ = self.auth_server()
+
+    def due(self, tag='due', **extra):
+        return self.entry(tag, hours=1, as_url=self.as_.url, **extra)
+
+    def test_a_due_login_is_refreshed_and_reaches_every_account(self):
+        old = self.due()
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {KEY: old}})
+        self.stub_files('acct-02', 'acct-03')
+        out = self.sync()
+        self.assertEqual(len(self.as_.requests), 1)
+        form = self.as_.requests[0]['form']
+        self.assertEqual(form, {'grant_type': 'refresh_token', 'refresh_token': old['refreshToken'],
+                                'client_id': CLIENT_ID, 'resource': SERVER_URL})
+        self.assertIsNone(self.as_.requests[0]['authorization'])
+        rec = self.store()['entries'][KEY]
+        self.secrets.update(('fake-mcp-access-rotated-1', 'fake-mcp-refresh-rotated-1'))
+        self.assertEqual(rec['entry']['accessToken'], 'fake-mcp-access-rotated-1')
+        self.assertEqual(rec['entry']['refreshToken'], 'fake-mcp-refresh-rotated-1')
+        self.assertAlmostEqual(rec['entry']['expiresAt'] / 1000, time.time() + 86400, delta=60)
+        self.assertEqual(rec['lifetime_s'], 86400)
+        self.assertIn('refreshed_at', rec)
+        self.assertEqual(rec['source'], 'acct-01')
+        self.assertEqual(len(rec['superseded']), 2)          # both old tokens, as digests
+        self.assertNotIn('fake-mcp', json.dumps(rec['superseded']))
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], rec['entry'], account)
+        self.assertEqual(rec['holders'], ['acct-01:file', 'acct-02:file', 'acct-03:file'])
+        self.assertEqual(self.file_doc('acct-01')['claudeAiOauth'], self.login(1))
+        self.assertIn('refreshed now', out)
+        self.sync()
+        self.assertEqual(len(self.as_.requests), 1)        # fresh for 24 h: nothing due
+
+    def test_a_refresh_without_a_new_refresh_token_keeps_the_old_one(self):
+        old = self.due()
+        self.put_file('acct-01', {'mcpOAuth': {KEY: old}})
+        self.as_.answers.append((200, {'access_token': 'fake-mcp-access-only', 'scope': 'openid'}))
+        self.secrets.add('fake-mcp-access-only')
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        entry = rec['entry']
+        self.assertEqual(entry['accessToken'], 'fake-mcp-access-only')
+        self.assertEqual(entry['refreshToken'], old['refreshToken'])
+        self.assertEqual(entry['scope'], 'openid')
+        # no expires_in: an assumed hour, as refresh_oauth does — never no expiry at all
+        self.assertAlmostEqual(entry['expiresAt'] / 1000, time.time() + 3600, delta=60)
+        self.assertTrue(rec['expiry_assumed'])
+        self.assertEqual(len(rec['superseded']), 1)          # the access token alone
+
+    def test_a_rotated_login_without_expires_in_stays_the_winner_everywhere(self):
+        # Probe A: dropping the expiry ranked the rotated grant below every old copy — it
+        # was shared nowhere, then replaced from the accounts, and the old (rotated-away)
+        # refresh token was posted again.
+        old = self.due()
+        for account in self.ACCOUNTS:
+            self.put_file(account, {'mcpOAuth': {KEY: old}})
+        self.as_.answers.append((200, {'access_token': 'fake-mcp-access-r2',
+                                       'refresh_token': 'fake-mcp-refresh-r2'}))
+        self.secrets.update(('fake-mcp-access-r2', 'fake-mcp-refresh-r2'))
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry']['refreshToken'], 'fake-mcp-refresh-r2')
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], rec['entry'], account)
+        # an old copy surfacing from a store the run could not reach changes nothing
+        self.put_file('acct-03', {'mcpOAuth': {KEY: old}})
+        for _ in range(3):
+            self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['entry'], rec['entry'])
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], rec['entry'])
+        posted = [r['form']['refresh_token'] for r in self.as_.requests]
+        self.assertEqual(posted, [old['refreshToken']])
+
+    def test_a_short_lived_login_is_refreshed_at_half_life_not_on_every_pass(self):
+        self.as_.lifetime = 3600
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.due()}})
+        self.sync()
+        self.assertEqual(len(self.as_.requests), 1)
+        clock = os.stat(self.root / 'mcp-oauth.json').st_mtime
+        for _ in range(3):
+            self.sync()
+        self.assertEqual(len(self.as_.requests), 1)        # 1 h left of 1 h: not due yet
+        self.assertEqual(os.stat(self.root / 'mcp-oauth.json').st_mtime, clock)
+
+        def age(minutes_left, refreshed_ago):
+            def edit(doc):
+                rec = doc['entries'][KEY]
+                rec['entry']['expiresAt'] = int((time.time() + minutes_left * 60) * 1000)
+                rec['refreshed_at'] = M._now_iso(time.time() - refreshed_ago * 60)
+            self.edit_store(edit)
+        age(20, 10)                                          # due, but refreshed 10 min ago
+        self.sync()
+        self.assertEqual(len(self.as_.requests), 1)
+        age(25, 35)                                          # inside half its lifetime: due
+        self.sync()
+        self.assertEqual(len(self.as_.requests), 2)
+
+    def test_a_login_that_is_not_due_sends_nothing(self):
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.entry('fresh', hours=20,
+                                                               as_url=self.as_.url)}})
+        self.sync()
+        self.assertEqual((self.as_.requests, self.as_.metadata_hits), ([], []))
+
+    def test_a_failed_refresh_backs_off_and_changes_nothing(self):
+        old = self.due()
+        self.put_file('acct-01', {'mcpOAuth': {KEY: old}})
+        self.stub_files('acct-02', 'acct-03')
+        self.as_.answers.append((503, {'error': 'temporarily_unavailable'}))
+        out = self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry'], old)
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], old)   # still in time
+        self.assertEqual(rec['refresh']['failures'], 1)
+        self.assertEqual(rec['refresh']['last_error'], 'http 503 temporarily_unavailable')
+        self.assertAlmostEqual(rec['refresh']['next_at'], time.time() + 900, delta=30)
+        self.assertIn('refresh failed (http 503', out)
+        self.sync()                                          # still backing off
+        self.assertEqual(len(self.as_.requests), 1)
+        self.as_.answers.append((502, {}))
+        self.sync('--force')
+        rec = self.store()['entries'][KEY]
+        self.assertEqual((len(self.as_.requests), rec['refresh']['failures']), (2, 2))
+        self.assertAlmostEqual(rec['refresh']['next_at'], time.time() + 1800, delta=30)
+
+    def test_a_refresh_failing_too_close_to_expiry_stops_sharing(self):
+        # The next try would come after the clients' own 5-minute window: they refresh it
+        # themselves then, each under its own config dir's lock — one grant, many refreshers.
+        old = self.entry('late', hours=25 / 60, as_url=self.as_.url)
+        self.put_file('acct-01', {'mcpOAuth': {KEY: old}})
+        self.stub_files('acct-02')
+        self.as_.answers.append((503, {'error': 'temporarily_unavailable'}))
+        out = self.sync()
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], self.stub())
+        self.assertIn('NOT shared: its refresh keeps failing', out)
+        row = {r['key']: r for r in self.status_json()['keys']}[KEY]
+        self.assertFalse(row['shared'])
+        self.sync('--force')                                 # a refresh that lands: shared
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY],
+                         self.store()['entries'][KEY]['entry'])
+        self.secrets.update(('fake-mcp-access-rotated-1', 'fake-mcp-refresh-rotated-1'))
+
+    def test_invalid_grant_marks_the_login_needs_reauth(self):
+        old = self.due()
+        self.put_file('acct-01', {'mcpOAuth': {KEY: old}})
+        self.stub_files('acct-02')
+        self.as_.answers.append((400, {'error': 'invalid_grant', 'error_description': 'revoked'}))
+        out = self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertTrue(rec['needs_reauth'])
+        self.assertEqual(rec['entry'], old)                 # left in place...
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], self.stub())  # ...unshared
+        self.assertIn('NEEDS RE-AUTH', out)
+        self.sync('--force')
+        self.assertEqual(len(self.as_.requests), 1)         # never retried with a dead grant
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('NEEDS RE-AUTH', status)
+        # a NEW sign-in anywhere replaces it and clears the verdict
+        fresh = self.entry('relogin', hours=20, as_url=self.as_.url)
+        self.put_file('acct-03', {'mcpOAuth': {KEY: fresh}})
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry'], fresh)
+        self.assertNotIn('needs_reauth', rec)
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], fresh)
+
+    def test_a_copy_in_a_keychain_item_this_run_cannot_open_defers_the_refresh(self):
+        # Rotating it would leave that item's client — a GUI session — with a dead refresh
+        # token. A run that can open the item refreshes it, until expiry is close.
+        grant = self.entry('kc', hours=3, as_url=self.as_.url)
+        self.put_file('acct-01', {'mcpOAuth': {KEY: grant}})
+        self.kc_put('acct-02', {'claudeAiOauth': self.login(2), 'mcpOAuth': {}})
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['holders'], ['acct-01:file', 'acct-02:keychain'])
+
+        def left(minutes):
+            self.edit_store(lambda doc: doc['entries'][KEY]['entry'].update(
+                expiresAt=int((time.time() + minutes * 60) * 1000)))
+        left(60)
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        out = self.sync()
+        self.assertEqual(self.as_.requests, [])
+        self.assertIn('refresh deferred (a copy sits in acct-02 keychain', out)
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('deferred: a copy sits in acct-02 keychain', status)
+        os.environ.pop('FAKE_KEYCHAIN_LOCKED')
+        self.sync()                                          # this run can open it
+        self.assertEqual(len(self.as_.requests), 1)
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(self.kc_doc('acct-02')['mcpOAuth'][KEY], rec['entry'])
+        self.assertNotIn('deferred', rec)
+        self.secrets.update(('fake-mcp-access-rotated-1', 'fake-mcp-refresh-rotated-1'))
+        # close to expiry, a run that cannot open it refreshes anyway: every client would
+        # otherwise refresh the one grant on its own
+        left(10)
+        self.edit_store(lambda doc: doc['entries'][KEY].update(
+            refreshed_at=M._now_iso(time.time() - 86400 + 600)))
+        os.environ['FAKE_KEYCHAIN_LOCKED'] = '1'
+        self.sync()
+        self.assertEqual(len(self.as_.requests), 2)
+        self.secrets.update(('fake-mcp-access-rotated-2', 'fake-mcp-refresh-rotated-2'))
+
+    def test_a_client_secret_goes_in_the_body_unless_the_server_takes_basic_only(self):
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.due(clientSecret='fake-client-secret')}})
+        self.sync()
+        form = self.as_.requests[0]['form']
+        self.assertEqual((form['client_id'], form['client_secret']), (CLIENT_ID, 'fake-client-secret'))
+        self.as_.stop()
+        self.server = self.as_ = AuthServer(methods=['client_secret_basic'])
+        self.put_file('acct-02', {'mcpOAuth': {OTHER_KEY: self.entry(
+            'basic', hours=1, as_url=self.as_.url, clientSecret='fake-client-secret')}})
+        self.sync()
+        request = self.as_.requests[0]
+        self.assertNotIn('client_secret', request['form'])
+        self.assertNotIn('client_id', request['form'])
+        pair = base64.b64decode(request['authorization'].split(' ', 1)[1]).decode()
+        self.assertEqual(pair, f"{urllib.parse.quote(CLIENT_ID, safe='')}:fake-client-secret")
+
+    def test_metadata_is_found_by_path_insertion_or_at_the_discovered_url(self):
+        self.as_.stop()
+        self.server = self.as_ = AuthServer(base_path='/tenant-a')
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.due()}})
+        self.sync()
+        self.assertEqual(self.as_.metadata_hits, ['/.well-known/oauth-authorization-server/tenant-a'])
+        self.assertEqual(len(self.as_.requests), 1)
+        self.as_.stop()
+        self.server = self.as_ = AuthServer(meta_path='/custom/metadata')
+        entry = self.due('custom')
+        entry['discoveryState']['authServerMetadataUrl'] = f'{self.as_.origin}/custom/metadata'
+        self.put_file('acct-02', {'mcpOAuth': {OTHER_KEY: entry}})
+        self.sync()
+        self.assertEqual(self.as_.metadata_hits, ['/custom/metadata'])
+        self.assertEqual(len(self.as_.requests), 1)
+
+    def test_a_refresh_token_never_travels_over_plain_http_to_another_host(self):
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.entry('remote', hours=1, as_url=NO_AS)}})
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['refresh']['last_error'], 'no usable authorization server URL')
+        self.assertEqual(self.as_.requests, [])
+
+
+# ---------------------------------------------------------------- cleared in an account
+
+class ClearTests(Case):
+    """/mcp "Clear authentication", `claude mcp login` and a refused refresh revoke or
+    refuse the login AT THE SERVER before the client drops it — and under the pool that
+    login is every account's. It is retired everywhere, never merged back."""
+
+    def shared(self):
+        grant = self.entry('g')
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {KEY: grant}})
+        self.stub_files('acct-02', 'acct-03')
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['holders'],
+                         ['acct-01:file', 'acct-02:file', 'acct-03:file'])
+        return grant
+
+    def test_a_login_cleared_in_one_account_is_retired_in_every_account(self):
+        self.shared()
+        self.put_file('acct-02', {'mcpOAuth': {}})          # Clear authentication: key gone
+        out = self.sync()
+        store = self.store()
+        self.assertNotIn(KEY, store['entries'])
+        self.assertEqual(store['forgotten'][KEY]['reason'], 'cleared in acct-02 file')
+        self.assertIn('login retired (cleared in acct-02 file)', out)
+        for account in self.ACCOUNTS:
+            self.assertNotIn(KEY, self.file_doc(account)['mcpOAuth'], account)
+        self.assertEqual(self.file_doc('acct-01')['claudeAiOauth'], self.login(1))
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('login: none — retired', status)
+        self.assertNotIn('valid until', status)
+        self.assertIn('the login was cleared in acct-02 file', (self.root / 'ops.log').read_text())
+        # one new sign-in anywhere is shared again
+        fresh = self.entry('fresh')
+        self.put_file('acct-03', {'mcpOAuth': {KEY: fresh}})
+        self.sync()
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'].get(KEY), fresh, account)
+
+    def test_a_blanked_login_is_retired_at_the_next_launch(self):
+        grant = self.shared()
+        self.put_file('acct-03', {'mcpOAuth': {KEY: self.blanked(grant)}})   # refused refresh
+        self.ensure('acct-02')                               # no network, no sync
+        self.assertNotIn(KEY, self.store()['entries'])
+        self.assertNotIn(KEY, self.file_doc('acct-02')['mcpOAuth'])
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], self.blanked(grant))
+
+    def test_a_stub_that_never_held_the_login_is_filled_not_retired(self):
+        grant = self.entry('g')
+        self.put_file('acct-01', {'mcpOAuth': {KEY: grant}})
+        self.sync()                                          # acct-02 had no file yet
+        self.stub_files('acct-02')                           # its client meets the server
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['entry'], grant)
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], grant)
+
+    def test_a_store_gone_or_rewritten_without_mcp_state_says_nothing(self):
+        grant = self.shared()
+        (self.root / 'acct-02' / '.credentials.json').unlink()
+        self.put_file('acct-03', {'claudeAiOauth': self.login(3)})   # a re-login, say
+        self.sync()
+        rec = self.store()['entries'][KEY]
+        self.assertEqual(rec['entry'], grant)
+        self.assertEqual(rec['holders'], ['acct-01:file', 'acct-03:file'])
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], grant)
+        self.assertFalse(self.has_file('acct-02'))
+
+    def test_a_holder_whose_client_rotated_the_login_is_no_clear(self):
+        self.shared()
+        newer = self.entry('newer', hours=24)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: newer}})
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['entry'], newer)
+        for account in self.ACCOUNTS:
+            self.assertEqual(self.file_doc(account)['mcpOAuth'][KEY], newer, account)
+
+
+# ---------------------------------------------------------------------- kill switches
+
+class SwitchTests(Case):
+    def test_the_kill_switch_stops_ensure_and_sync(self):
+        os.environ['CLAUDE_MULTIACC_MCP_OAUTH'] = '0'
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        self.ensure('acct-01')
+        out = self.sync()
+        self.assertIn('off (CLAUDE_MULTIACC_MCP_OAUTH=0)', out)
+        self.assertFalse((self.root / 'mcp-oauth.json').exists())
+        self.assertFalse((self.root / 'acct-01' / '.credentials.json').exists())
+        rc, status, _ = self.run_cli('status')
+        self.assertEqual(rc, 0)
+        self.assertIn('sharing OFF', status)
+
+    def test_the_refresh_switch_never_refreshes_and_so_never_shares(self):
+        # One shared login needs ONE refresher: without the pool's, every account holding
+        # it would refresh it on its own.
+        as_ = self.auth_server()
+        os.environ['CLAUDE_MULTIACC_MCP_OAUTH_REFRESH'] = '0'
+        due = self.entry('due', hours=1, as_url=as_.url)
+        self.put_file('acct-02', {'mcpOAuth': {KEY: due}})
+        self.stub_files('acct-01')
+        out = self.sync()
+        self.assertEqual(as_.requests, [])
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], self.stub())
+        self.assertIn('NOT shared: refresh is off', out)
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('refresh OFF', status)
+        # a launch with refresh on still shares nothing behind a sync that had it off
+        os.environ.pop('CLAUDE_MULTIACC_MCP_OAUTH_REFRESH')
+        self.ensure('acct-01')
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], self.stub())
+
+    def test_ensure_shares_only_behind_a_recent_refreshing_sync(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.stub_files('acct-01', 'acct-03')
+        self.ensure('acct-01')                               # no sync ever: nothing shared
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], self.stub())
+        self.assertTrue((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        rc, status, _ = self.run_cli('status')
+        self.assertIn('sharing paused: no refreshing sync in the last hour (none yet)', status)
+        self.beat(ago=2 * 3600)                              # one long ago: still nothing
+        self.ensure('acct-03')
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], self.stub())
+        self.beat()
+        self.ensure('acct-03')
+        self.assertEqual(self.file_doc('acct-03')['mcpOAuth'][KEY], new)
+
+
+# ---------------------------------------------------------------------------- ensure
+
+class EnsureTests(Case):
+    def test_ensure_shares_into_its_own_account_only_and_stamps_it(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}})
+        self.stub_files('acct-01')
+        self.put_file('acct-03', {'claudeAiOauth': self.login(3)})
+        self.beat()
+        self.ensure('acct-01')
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertNotIn('mcpOAuth', self.file_doc('acct-03'))
+        store = os.stat(self.root / 'mcp-oauth.json')
+        stamp = os.stat(self.root / 'acct-01' / '.mcp-oauth-applied')
+        self.assertEqual(int(stamp.st_mtime), int(store.st_mtime))
+        self.assertTrue((self.root / '.mcp-oauth-seen').exists())
+        self.assertFalse((self.root / 'acct-03' / '.mcp-oauth-applied').exists())
+
+    def test_ensure_reads_only_its_own_keychain_item(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        _, calls = self.security_calls(self.ensure, 'acct-01')
+        self.assertEqual(calls, ['find-generic-password a=gas w=1'])
+
+    def test_a_pool_without_mcp_oauth_state_gets_nothing_written(self):
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1)})
+        raw = (self.root / 'acct-01' / '.credentials.json').read_bytes()
+        self.ensure('acct-01')
+        out = self.sync()
+        self.assertIn('no MCP OAuth state in any account yet', out)
+        for name in ('mcp-oauth.json', '.mcp-oauth-seen', 'ops.log'):
+            self.assertFalse((self.root / name).exists(), name)
+        self.assertFalse((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        self.assertEqual((self.root / 'acct-01' / '.credentials.json').read_bytes(), raw)
+
+    def test_an_account_outside_the_manifest_is_left_alone(self):
+        stray = self.root / 'acct-77'
+        stray.mkdir()
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        rc, _out, err = self.run_cli('ensure', '--account-dir', str(stray))
+        self.assertEqual(rc, 0, err)
+        self.assertFalse((stray / '.credentials.json').exists())
+
+    def test_the_store_clock_moves_a_whole_second_per_change(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('a', hours=5)}})
+        self.sync()
+        first = os.stat(self.root / 'mcp-oauth.json').st_mtime
+        self.put_file('acct-03', {'mcpOAuth': {KEY: self.entry('b', hours=9)}})
+        self.sync()
+        second = os.stat(self.root / 'mcp-oauth.json').st_mtime
+        self.assertGreaterEqual(second, first + 1)
+        self.assertEqual(second, int(second))
+        # bookkeeping is no change for the accounts: the beat, the holders a merge adds
+        self.stub_files('acct-01')
+        self.sync()
+        self.assertEqual(self.store()['entries'][KEY]['holders'],
+                         ['acct-01:file', 'acct-02:file', 'acct-03:file'])
+        self.sync()
+        self.assertEqual(os.stat(self.root / 'mcp-oauth.json').st_mtime, second)
+
+    def test_the_watermark_never_hides_a_write_in_the_current_second(self):
+        # A newest mtime in the current second (or later — a clock that ran ahead) is set
+        # a second early. In the future here, so the case cannot straddle a second.
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('a')}}, mtime=time.time() + 30)
+        self.stub_files('acct-01')
+        self.sync()
+        seen = os.stat(self.root / '.mcp-oauth-seen').st_mtime
+        newest = os.stat(self.root / 'acct-02' / '.credentials.json').st_mtime
+        self.assertLess(int(seen), int(newest))     # one second early: `test -nt` still fires
+        old = time.time() - 120
+        for account in ('acct-01', 'acct-02'):
+            os.utime(self.root / account / '.credentials.json', (old, old))
+        self.sync()
+        self.assertEqual(int(os.stat(self.root / '.mcp-oauth-seen').st_mtime), int(old))
+
+
+class ShimGateTests(Case):
+    """The bash gate in bin/claude: python runs only when something changed."""
+
+    def setUp(self):
+        super().setUp()
+        work = Path(self.work.name)
+        self.realbin = work / 'realbin'
+        self.realbin.mkdir()
+        fake = self.realbin / 'claude'
+        fake.write_text('#!/bin/sh\necho "CFG=${CLAUDE_CONFIG_DIR##*/} ARGS=$*"\n')
+        fake.chmod(0o755)
+        self.pylog = work / 'py.log'
+        wrapper = work / 'pylog.sh'
+        wrapper.write_text(f'#!/bin/sh\nprintf "PY %s\\n" "$*" >> "{self.pylog}"\n'
+                           f'exec "{sys.executable}" "$@"\n')
+        wrapper.chmod(0o755)
+        self.wrapper = wrapper
+        self.home = work / 'home'
+        self.home.mkdir()
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1)}, mtime=time.time() - 300)
+
+    def launch(self, **extra):
+        # A scrubbed env, built from nothing: this suite may itself run inside a pooled
+        # session, whose CLAUDE_CONFIG_DIR / CLAUDE_SHIM_ACTIVE would turn the launch into
+        # a passthrough — and whose pool roots are the REAL ones.
+        env = {'PATH': f'{self.realbin}:/usr/bin:/bin:/usr/sbin:/sbin', 'HOME': str(self.home),
+               'USER': 'gas', 'LC_ALL': 'C', 'CLAUDE_ACCOUNTS_ROOT': str(self.root),
+               'CLAUDE_ACCOUNT': 'acct-01', 'CLAUDE_MULTIACC_PYTHON': str(self.wrapper),
+               'CLAUDE_MULTIACC_KEYCHAIN': '0', 'CLAUDE_MULTIACC_AUTORESUME': '0',
+               'CLAUDE_MULTIACC_CLIENT_LIMITS': '0', 'CLAUDE_MULTIACC_PATH_PROBE': '0',
+               'CLAUDE_MULTIACC_MODEL_CATALOG': '0'}
+        env.update(extra)
+        if self.pylog.exists():
+            self.pylog.unlink()
+        p = subprocess.run([str(SHIM), '--version'], env=env, capture_output=True, text=True,
+                           timeout=60, stdin=subprocess.DEVNULL)
+        ran = self.pylog.read_text() if self.pylog.exists() else ''
+        return p, ran
+
+    def test_python_runs_only_when_something_changed(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}}, mtime=time.time() - 200)
+        self.beat()
+        p, ran = self.launch()
+        self.assertEqual((p.returncode, p.stdout.strip()), (0, 'CFG=acct-01 ARGS=--version'))
+        self.assertIn('mcp_oauth.py ensure', ran)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], new)
+        self.assertEqual(self.file_doc('acct-01')['claudeAiOauth'], self.login(1))
+        self.assertTrue((self.root / 'acct-01' / '.mcp-oauth-applied').exists())
+        # nothing changed since: no python start-up at all
+        p, ran = self.launch()
+        self.assertEqual((p.returncode, ran), (0, ''))
+        # a client in another account saves a newer login: the next launch picks it up
+        newer = self.entry('newer', hours=30)
+        self.put_file('acct-03', {'mcpOAuth': {KEY: newer}})
+        p, ran = self.launch()
+        self.assertIn('mcp_oauth.py ensure', ran)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], newer)
+        # the store changed since acct-02 last got it: its first launch runs once
+        p, ran = self.launch(CLAUDE_ACCOUNT='acct-02')
+        self.assertIn('mcp_oauth.py ensure', ran)
+        self.assertEqual(self.file_doc('acct-02')['mcpOAuth'][KEY], newer)
+
+    def test_a_launch_creates_no_credentials_file_for_an_account_without_a_token(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}}, mtime=time.time() - 200)
+        self.beat()
+        for _ in range(2):
+            p, _ran = self.launch(CLAUDE_ACCOUNT='acct-03')
+            self.assertEqual((p.returncode, p.stdout.strip()), (0, 'CFG=acct-03 ARGS=--version'))
+        self.assertFalse(self.has_file('acct-03'))
+
+    def test_a_setup_token_accounts_launch_gets_its_file_and_the_gate_settles(self):
+        new = self.entry('n')
+        self.put_file('acct-02', {'mcpOAuth': {KEY: new}}, mtime=time.time() - 200)
+        (self.root / 'acct-03' / 'server.token').write_text('fake-setup-token-03')
+        self.secrets.add('fake-setup-token-03')
+        self.beat()
+        p, ran = self.launch(CLAUDE_ACCOUNT='acct-03')
+        self.assertEqual((p.returncode, p.stdout.strip()), (0, 'CFG=acct-03 ARGS=--version'))
+        self.assertIn('mcp_oauth.py ensure', ran)
+        self.assertEqual(self.file_doc('acct-03'), {'mcpOAuth': {KEY: new}})   # before exec
+        time.sleep(1.1)              # out of the second the file was created in
+        self.launch(CLAUDE_ACCOUNT='acct-03')   # the harvest sees the new file once...
+        p, ran = self.launch(CLAUDE_ACCOUNT='acct-03')
+        self.assertEqual(p.returncode, 0)
+        self.assertNotIn('mcp_oauth.py', ran)   # ...and then the gate starts it no more
+        # (a pinned token account's own token checks are the shim's, not this gate's)
+
+    def test_a_pool_without_mcp_oauth_state_never_starts_python(self):
+        p, ran = self.launch()
+        self.assertEqual((p.returncode, ran), (0, ''))
+        self.assertFalse((self.root / 'mcp-oauth.json').exists())
+
+    def test_a_torn_file_that_mentions_mcp_oauth_costs_one_python_start_only(self):
+        torn = self.root / 'acct-02' / '.credentials.json'
+        torn.write_text('{"mcpOAuth": {"higgsfield|0a1b2c3d4e5f6a7b": {"accessTo')
+        old = time.time() - 100
+        os.utime(torn, (old, old))
+        p, ran = self.launch()
+        self.assertEqual(p.returncode, 0)
+        self.assertIn('mcp_oauth.py ensure', ran)
+        self.assertFalse((self.root / 'mcp-oauth.json').exists())
+        p, ran = self.launch()
+        self.assertEqual((p.returncode, ran), (0, ''))
+
+    def test_the_kill_switch_and_a_missing_python_never_break_a_launch(self):
+        self.put_file('acct-02', {'mcpOAuth': {KEY: self.entry('n')}})
+        p, ran = self.launch(CLAUDE_MULTIACC_MCP_OAUTH='0')
+        self.assertEqual((p.returncode, p.stdout.strip(), ran), (0, 'CFG=acct-01 ARGS=--version', ''))
+        self.assertNotIn('mcpOAuth', self.file_doc('acct-01'))
+        p, _ran = self.launch(CLAUDE_MULTIACC_PYTHON='/nonexistent/python3')
+        self.assertEqual((p.returncode, p.stdout.strip(), p.stderr), (0, 'CFG=acct-01 ARGS=--version', ''))
+
+
+# ---------------------------------------------------------------------------- forget
+
+class ForgetTests(Case):
+    def test_forget_clears_every_store_and_a_straggler_stays_forgotten(self):
+        grant = self.entry('g')
+        keep = {'serverName': 'linear', 'accessToken': 'fake-mcp-access-linear'}
+        self.secrets.add('fake-mcp-access-linear')
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {KEY: grant, OTHER_KEY: keep}})
+        self.kc_put('acct-02', {'claudeAiOauth': self.login(2), 'mcpOAuth': {KEY: grant}})
+        self.stub_files('acct-03')
+        self.sync()
+        rc, out, err = self.run_cli('forget', 'higgsfield')
+        self.assertEqual(rc, 0, err)
+        self.assertIn('forgot higgsfield: 1 key(s)', out)
+        store = self.store()
+        self.assertNotIn(KEY, store['entries'])
+        self.assertEqual(store['forgotten'][KEY]['reason'], 'auth-forget')
+        for account in ('acct-01', 'acct-03'):
+            self.assertNotIn(KEY, self.file_doc(account)['mcpOAuth'], account)
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][OTHER_KEY], keep)
+        self.assertEqual(self.file_doc('acct-01')['claudeAiOauth'], self.login(1))
+        self.assertNotIn(KEY, self.kc_doc('acct-02')['mcpOAuth'])
+        self.assertEqual(self.kc_doc('acct-02')['claudeAiOauth'], self.login(2))
+        self.assertFalse(self.has_file('acct-02'))
+        # a copy a forget could not reach (a locked item, say) never comes back...
+        self.put_file('acct-03', {'mcpOAuth': {KEY: grant}})
+        self.sync()
+        self.assertNotIn(KEY, self.store()['entries'])
+        self.assertNotIn(KEY, self.file_doc('acct-03')['mcpOAuth'])   # ...and is cleared
+        # a NEW sign-in is a new login, shared as usual
+        fresh = self.entry('fresh')
+        self.put_file('acct-03', {'mcpOAuth': {KEY: fresh}})
+        self.sync()
+        self.assertEqual(self.file_doc('acct-01')['mcpOAuth'][KEY], fresh)
+        self.assertNotIn('fake-mcp', json.dumps(self.store()['forgotten']))
+
+    def test_forgetting_an_unknown_server_says_so(self):
+        rc, _out, err = self.run_cli('forget', 'nothing-here')
+        self.assertEqual(rc, 1)
+        self.assertIn('no MCP OAuth state for nothing-here', err)
+
+
+# ---------------------------------------------------------------------------- output
+
+class OutputTests(Case):
+    def test_no_output_and_no_log_line_ever_contains_a_token(self):
+        as_ = self.auth_server()
+        self.put_file('acct-01', {'claudeAiOauth': self.login(1), 'mcpOAuth': {
+            KEY: self.entry('due', hours=1, as_url=as_.url, clientSecret='fake-client-secret')}})
+        self.put_file('acct-02', {'mcpOAuth': {OTHER_KEY: self.entry('other', hours=1, as_url=NO_AS)}})
+        self.kc_put('acct-03', {'claudeAiOauth': self.login(3)})
+        self.secrets.update(('fake-mcp-access-rotated-1', 'fake-mcp-refresh-rotated-1'))
+        outputs = []
+        for argv in (('sync',), ('status',), ('status', '--json'),
+                     ('ensure', '--account-dir', self.d('acct-02')), ('forget', 'linear'),
+                     ('status',)):
+            rc, out, err = self.run_cli(*argv)
+            outputs.append(out + err)
+        self.put_file('acct-02', {'mcpOAuth': {}})          # a clear: the login is retired
+        for argv in (('sync',), ('status',), ('status', '--json')):
+            rc, out, err = self.run_cli(*argv)
+            outputs.append(out + err)
+        log = (self.root / 'ops.log').read_text()
+        self.assertIn('refresh', log)
+        self.assertIn('retired in every account', log)
+        for secret in self.secrets:
+            for text in outputs + [log]:
+                self.assertNotIn(secret, text)
+
+    def test_status_json_names_every_key_and_every_account_store(self):
+        self.put_file('acct-01', {'mcpOAuth': {KEY: self.entry('a', hours=5)}})
+        self.put_file('acct-02', {'mcpOAuth': {OTHER_KEY: self.stub()}})
+        self.kc_put('acct-03', {'claudeAiOauth': self.login(3)})
+        self.sync()
+        doc = self.status_json()
+        rows = {row['key']: row for row in doc['keys']}
+        self.assertEqual(sorted(rows), sorted([KEY, OTHER_KEY]))
+        row = rows[KEY]
+        self.assertTrue(row['login'])
+        self.assertTrue(row['shared'])
+        self.assertIsNone(doc['sharing_paused'])
+        self.assertEqual((row['server_name'], row['server_url'], row['source']),
+                         ('higgsfield', SERVER_URL, 'acct-01'))
+        self.assertEqual(row['accounts']['acct-02'], {'file': 'fresh', 'keychain': 'absent'})
+        self.assertEqual(row['accounts']['acct-03'], {'file': 'absent', 'keychain': 'fresh'})
+        self.assertFalse(rows[OTHER_KEY]['login'])
+        self.assertEqual(rows[OTHER_KEY]['accounts']['acct-02']['file'], 'stub')
+
+    def test_the_store_is_never_pushed_anywhere(self):
+        # sync and the limits fan-out push explicit file lists; none may name the store.
+        for name in ('bin/claude-accounts', 'bin/codex-accounts', 'lib/common.sh'):
+            for line in (REPO / name).read_text().splitlines():
+                code = line.split('#', 1)[0]
+                if 'rsync' in code or "printf '" in code:
+                    self.assertNotIn('mcp-oauth', code, f'{name}: {line.strip()}')
+
+
+if __name__ == '__main__':
+    unittest.main()