claude-multiacc 2.0.3 → 2.0.4

package/lib/audit.py

@@ -7,11 +7,20 @@ States:
   expired  has auth material that CANNOT authenticate — needs `claude-accounts relogin`
   blocked  authenticates, but its organization has disabled Claude Code subscription
            access — a re-login cannot fix it, so it needs an admin (or removal)
+  locked   the OAuth login is in the macOS Keychain and THIS session cannot open it
+           (ssh/tmux/background) — it works from the Mac's own GUI session, so it is
+           neither dead nor missing; just not usable from here
   missing  no auth on this machine, and this machine is supposed to own the grant
   remote   no auth here, but the manifest says another machine owns it (informational)
 
 Only 'ok' accounts are selectable; everything else is excluded by the shim.
 
+An OAuth login lives either in `<acct>/.credentials.json` or — on macOS, whenever the
+client could open the login Keychain — in a Keychain item (lib/keychain.py). Both are
+the same document and the same machine-local class; the file is simply gone once the
+client has moved it into the Keychain, so a file-only reading calls a working login
+"missing" (that is exactly what happened to a whole pool on 2026-08-28).
+
 Run directly for a TSV dump:  python3 lib/audit.py <acc-root> [mac|linux]
 Columns: id, email, home, state, label, reason, fix
 """
@@ -22,6 +31,12 @@ import re
 import sys
 import time
 
+# This module is loaded both as a package sibling (`from audit import …` with lib/ on
+# sys.path) and by file path (importlib in lib/common.sh's creds_alive); the keychain
+# helper sits beside it either way.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import keychain  # noqa: E402
+
 VALID_ID = re.compile(r'acct-\d{2}')
 
 
@@ -71,6 +86,12 @@ def expired_marked(d, now=None):
             p = os.path.join(d, name)
             if os.path.isfile(p) and _mtime(p) > mt:
                 return False
+        # A login the client keeps in the Keychain is "written after the marker" in
+        # exactly the same sense — its modification stamp is readable even when this
+        # session cannot open the secret.
+        if not os.path.isfile(os.path.join(d, '.credentials.json')) \
+                and keychain.item_mtime(d) > mt:
+            return False
     m = re.search(r'soft_until=(\d+)', detail)
     if m and int(m.group(1)) <= now:
         return False
@@ -102,16 +123,31 @@ def _scrape(cpath):
             'has_refresh': bool(re.search(r'"refreshToken"\s*:\s*"[^"]', txt))}
 
 
+def creds_doc_state(doc, now):
+    """(state, reason) for a parsed credential document ({"claudeAiOauth": …}) —
+    the one rule for a file AND a Keychain item, so the two stores can never be
+    judged differently."""
+    o = doc.get('claudeAiOauth', {}) if isinstance(doc, dict) else None
+    if not isinstance(o, dict):
+        raise ValueError('claudeAiOauth is not an object')
+    exp, rexp = _ms(o.get('expiresAt')), _ms(o.get('refreshTokenExpiresAt'))
+    has_refresh = bool(o.get('refreshToken'))
+    if exp > now:
+        return 'ok', 'oauth credential valid'
+    if not has_refresh:
+        return 'expired', 'access token expired and there is no refresh token'
+    if rexp and rexp <= now:
+        days = max(0, int((now - rexp) / 86400))
+        when = time.strftime('%Y-%m-%d', time.gmtime(rexp))
+        return 'expired', f'refresh token expired {when} ({days}d ago)'
+    return 'ok', 'access token stale but auto-refreshes'
+
+
 def creds_state(cpath, now):
     """(state, reason) for an on-disk .credentials.json."""
     scraped = None
     try:
-        doc = json.load(open(cpath))
-        o = doc.get('claudeAiOauth', {})
-        if not isinstance(o, dict):
-            raise ValueError('claudeAiOauth is not an object')
-        exp, rexp = _ms(o.get('expiresAt')), _ms(o.get('refreshTokenExpiresAt'))
-        has_refresh = bool(o.get('refreshToken'))
+        return creds_doc_state(json.load(open(cpath)), now)
     except Exception as e:
         # Unparseable (truncated / mid-write): fall back to the shim's lenient scrape so
         # both sides agree. Only if that finds nothing usable is the account called dead.
@@ -122,18 +158,40 @@ def creds_state(cpath, now):
         if exp <= now and not (has_refresh and (not rexp or rexp > now)):
             return 'expired', f'credentials unreadable ({str(e)[:60]})'
         return 'ok', 'credentials unreadable but carry a live token — left in the pool'
-    if exp > now:
-        return 'ok', 'oauth credential valid'
-    if not has_refresh:
-        return 'expired', 'access token expired and there is no refresh token'
-    if rexp and rexp <= now:
-        days = max(0, int((now - rexp) / 86400))
-        when = time.strftime('%Y-%m-%d', time.gmtime(rexp))
-        return 'expired', f'refresh token expired {when} ({days}d ago)'
-    return 'ok', 'access token stale but auto-refreshes'
 
 
-LABELS = {'ok': 'OK', 'expired': 'EXPIRED', 'blocked': 'BLOCKED',
+def oauth_login(d, now):
+    """Where <d>'s OAuth login lives and whether it can authenticate.
+
+    Returns {'store': 'file'|'keychain'|None, 'state': 'ok'|'expired'|'locked'|None,
+             'reason': str, 'doc': dict|None}. The FILE wins when both exist: it is what
+    a session without keychain access (ssh) will use, and the client itself reads the
+    keychain first only when it can open it. 'locked' means the login exists in the
+    Keychain but this session cannot open it."""
+    cpath = os.path.join(d, '.credentials.json')
+    if _nonempty(cpath):
+        state, reason = creds_state(cpath, now)
+        return {'store': 'file', 'state': state, 'reason': reason, 'doc': None}
+    kc = keychain.probe(d)
+    if kc['state'] == 'present':
+        try:
+            state, reason = creds_doc_state(kc['doc'], now)
+        except ValueError as e:
+            state, reason = 'expired', f'keychain credential unreadable ({str(e)[:60]})'
+        return {'store': 'keychain', 'state': state, 'reason': f'{reason} (macOS Keychain)',
+                'doc': kc['doc']}
+    if kc['state'] == 'corrupt':
+        return {'store': 'keychain', 'state': 'expired',
+                'reason': 'keychain credential is not a credential document', 'doc': None}
+    if kc['state'] == 'locked':
+        return {'store': 'keychain', 'state': 'locked',
+                'reason': ('OAuth login is in the macOS Keychain, which this session '
+                           'cannot open (ssh/background) — it works from the Mac\'s own '
+                           'session'), 'doc': None}
+    return {'store': None, 'state': None, 'reason': '', 'doc': None}
+
+
+LABELS = {'ok': 'OK', 'expired': 'EXPIRED', 'blocked': 'BLOCKED', 'locked': 'KEYCHAIN LOCKED',
           'missing': 'NO LOGIN', 'remote': 'ELSEWHERE'}
 
 # `import --home` speaks mac|server; machine_kind() speaks mac|linux. Same two boxes,
@@ -164,6 +222,11 @@ def _fix_for(state, aid):
                 f'(if it stays BLOCKED, an admin must enable Claude Code for it)')
     if state in ('expired', 'missing'):
         return f'claude-accounts relogin {aid}'
+    if state == 'locked':
+        # Not a dead login: the Mac's own session can use it as it is. What an operator
+        # stuck in an ssh session CAN do is mint the portable token from here — the
+        # setup-token ceremony is a fresh browser grant and never reads the keychain.
+        return f'claude-accounts mint {aid}   (portable; or use it from the Mac\'s GUI session)'
     return ''
 
 
@@ -171,13 +234,11 @@ def audit_account(root, acct, now=None, machine=None):
     now = time.time() if now is None else now
     aid = acct.get('id', '')
     d = os.path.join(root, aid)
-    cpath = os.path.join(d, '.credentials.json')
     tpath = os.path.join(d, 'server.token')
-    has_creds = _nonempty(cpath)
     has_token = _nonempty(tpath)
     home = acct.get('home', '?')
     row = {'id': aid, 'email': acct.get('email', ''), 'home': home,
-           'state': 'ok', 'reason': ''}
+           'state': 'ok', 'reason': '', 'store': None}
 
     def done(r):
         r['label'] = LABELS.get(r['state'], r['state'].upper())
@@ -195,8 +256,10 @@ def audit_account(root, acct, now=None, machine=None):
             row['state'] = 'expired'
             row['reason'] = f'marked dead by the pool ({detail or "authentication failed"})'
         return done(row)
-    if has_creds:
-        state, reason = creds_state(cpath, now)
+    login = oauth_login(d, now)
+    row['store'] = login['store']
+    if login['state'] in ('ok', 'expired'):
+        state, reason = login['state'], login['reason']
         if state == 'ok' or has_token:
             # A portable token authenticates on its own, so a dead credential beside it
             # is not fatal — same rule the shim applies.
@@ -209,6 +272,9 @@ def audit_account(root, acct, now=None, machine=None):
         age = int((now - _mtime(tpath)) / 86400)
         row['reason'] = f'server.token present (minted ~{age}d ago)'
         return done(row)
+    if login['state'] == 'locked':
+        row['state'], row['reason'] = 'locked', login['reason']
+        return done(row)
     if machine and _elsewhere(home, machine):
         row['state'] = 'remote'
         row['reason'] = f'no auth here — the grant lives on the {home} machine'

package/lib/common.sh

@@ -117,6 +117,31 @@ find_real_bin() {
 find_real_claude() { find_real_bin claude "${1:-}"; }
 find_real_codex() { find_real_bin codex "${1:-}"; }
 
+# The version string of an installed copy (its package.json), '' when unreadable.
+# Shared because self-update must VERIFY the tree it wrote, in both CLIs.
+pkg_version_at() {
+  [ -f "$1/package.json" ] || return 0
+  sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1/package.json" | head -1
+}
+
+# The npm that owns THIS install, resolved without trusting the ambient PATH.
+# A launchd agent (and a bare cron) runs with PATH=/usr/bin:/bin:/usr/sbin:/sbin —
+# no homebrew, no nvm — so `command -v npm` fails there and the daily self-update
+# logged "npm not found; skipping" every night while announcing nothing was wrong.
+# Every Mac in the fleet sat frozen on a three-day-old build that way.
+# Order matters: the npm inside the prefix that holds the RUNNING copy is the one
+# whose global tree we must write (my-mini has two node installs, homebrew's and
+# nvm's, and updating the wrong one is the older bug this pairs with).
+find_npm() { # find_npm [prefix]; prints an npm path, or nothing
+  local prefix="${1:-}" cand
+  for cand in ${prefix:+"$prefix/bin/npm"} \
+              /opt/homebrew/bin/npm /usr/local/bin/npm /usr/bin/npm; do
+    [ -x "$cand" ] && { printf '%s\n' "$cand"; return 0; }
+  done
+  cand="$(command -v npm 2>/dev/null)" && [ -n "$cand" ] && { printf '%s\n' "$cand"; return 0; }
+  return 1
+}
+
 manifest_get() { # manifest_get <dot.path> [default]
   local val
   if [ -f "$MANIFEST" ]; then
@@ -423,10 +448,30 @@ has_local_auth() { # $1 = acct dir
   if [ "$MULTIACC_PROVIDER" = "codex" ]; then
     [ -s "$1/auth.json" ]
   else
-    [ -f "$1/.credentials.json" ] || [ -s "$1/server.token" ]
+    [ -f "$1/.credentials.json" ] || [ -s "$1/server.token" ] || keychain_has_login "$1"
   fi
 }
 
+# ---- macOS Keychain-held logins (claude only) ------------------------------------
+# Claude Code on macOS moves a config dir's OAuth login into the login Keychain the
+# first time a GUI-session process can write there, deleting .credentials.json as it
+# goes (lib/keychain.py has the whole story). These wrap that module so bash callers
+# never parse `security` output themselves. Each one is a no-op (absent) off macOS.
+keychain_state() { # $1 = acct dir -> prints present|locked|absent|corrupt|unavailable
+  local state
+  [ "$MULTIACC_PROVIDER" = "codex" ] && { echo absent; return 0; }
+  state="$("$PYBIN" "$LIB_DIR/keychain.py" probe "$1" 2>/dev/null \
+    | LC_ALL=C sed -n 's/.*"state": *"\([a-z]*\)".*/\1/p' | head -1)"
+  printf '%s\n' "${state:-unavailable}"
+}
+keychain_has_login() { # $1 = acct dir: an item EXISTS here (readable or locked)
+  case "$(keychain_state "$1")" in present|locked|corrupt) return 0 ;; *) return 1 ;; esac
+}
+keychain_forget() { # $1 = acct dir: drop the item (a removed account must not leave a grant behind)
+  [ "$MULTIACC_PROVIDER" = "codex" ] && return 0
+  "$PYBIN" "$LIB_DIR/keychain.py" delete "$1" >/dev/null 2>&1 || true
+}
+
 # ---- expired-login bookkeeping -------------------------------------------------
 # `.expired` is the persistent "this account cannot authenticate" marker the shim
 # honors (bin/claude: expired_marked). Two lines: marked-at epoch, then details.
@@ -487,15 +532,27 @@ accounts_needing_login() {
 # True when <acct dir>'s credential can authenticate right now (the audit module's
 # rule — audit.py for claude, codex_audit.py for codex; both expose creds_state).
 creds_alive() { # $1 = acct dir
-  local cred
-  if [ "$MULTIACC_PROVIDER" = "codex" ]; then cred="$1/auth.json"; else cred="$1/.credentials.json"; fi
-  [ -s "$cred" ] || return 1
-  "$PYBIN" - "$AUDIT_PY" "$cred" <<'PYEOF' 2>/dev/null
+  if [ "$MULTIACC_PROVIDER" = "codex" ]; then
+    [ -s "$1/auth.json" ] || return 1
+    "$PYBIN" - "$AUDIT_PY" "$1/auth.json" <<'PYEOF' 2>/dev/null
 import importlib.util, sys, time
 spec = importlib.util.spec_from_file_location('audit', sys.argv[1])
 mod = importlib.util.module_from_spec(spec)
 spec.loader.exec_module(mod)
 sys.exit(0 if mod.creds_state(sys.argv[2], time.time())[0] == 'ok' else 1)
+PYEOF
+    return $?
+  fi
+  # claude: the login is wherever the client put it — .credentials.json, or the macOS
+  # Keychain when the sign-in ran in a session that could open it. A ceremony that
+  # succeeded into the Keychain used to be reported as "login failed" and its
+  # half-made account dir deleted, stranding a live grant under an orphaned service.
+  "$PYBIN" - "$AUDIT_PY" "$1" <<'PYEOF' 2>/dev/null
+import importlib.util, sys, time
+spec = importlib.util.spec_from_file_location('audit', sys.argv[1])
+mod = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(mod)
+sys.exit(0 if mod.oauth_login(sys.argv[2], time.time())['state'] == 'ok' else 1)
 PYEOF
 }
 

package/lib/credential.py

@@ -220,8 +220,16 @@ def cmd_export(argv):
     cpath = os.path.join(d, '.credentials.json')
     has_token = os.path.isfile(tpath) and os.path.getsize(tpath) > 0
     if not has_token:
+        where = None
         if os.path.isfile(cpath) and os.path.getsize(cpath) > 0:
-            die(f'{aid} only has a MACHINE-LOCAL credential (.credentials.json) and cannot '
+            where = '.credentials.json'
+        else:
+            sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+            import keychain
+            if keychain.probe(d)['state'] in ('present', 'locked', 'corrupt'):
+                where = 'macOS Keychain'
+        if where:
+            die(f'{aid} only has a MACHINE-LOCAL credential ({where}) and cannot '
                 f'be exported.\n'
                 f'  Why: the OAuth grant\'s refresh token ROTATES on every refresh; a second\n'
                 f'  machine refreshing the same grant strands the first one.\n'

package/lib/keychain.py

@@ -0,0 +1,210 @@
+"""macOS Keychain-held Claude Code OAuth logins.
+
+Claude Code on macOS keeps a config dir's OAuth credential in the login Keychain —
+service ``Claude Code-credentials-<sha256(CLAUDE_CONFIG_DIR)[:8]>``, account = the
+macOS user name — whenever the keychain is writable, and DELETES the plaintext
+``.credentials.json`` the moment a keychain write lands (its store is "keychain with
+a plaintext fallback": the fallback file is removed once the primary holds the
+credential). Only sessions that cannot open the keychain — ssh, tmux, launchd
+background jobs, where ``security`` exits 36 "user interaction is not allowed" — keep
+using the file.
+
+So a per-dir login that was file-based when it was added (an ``add`` run over ssh)
+migrates into the Keychain the first time a GUI-session process refreshes its token —
+a launchd agent, a Terminal window, a runner-spawned ``claude`` — and from then on the
+file is gone. Reading only ``.credentials.json`` then reports a perfectly working
+login as "no credentials on this machine": the shim stops selecting it, telemetry
+goes dark, and every consumer of ``list --json`` shows it missing.
+
+This module is the one place that knows the keychain layout. Everything else asks
+:func:`probe`, which never raises and never prints the secret.
+
+States returned by :func:`probe`:
+  present      the item exists and this process could read it (``doc`` is the parsed
+               ``{"claudeAiOauth": …}`` document, identical in shape to the file)
+  locked       the item exists but this session cannot open the keychain (exit 36) —
+               a GUI-session process on this Mac CAN use it; an ssh session cannot
+  absent       no such item
+  corrupt      the item exists and was readable, but is not a credential document
+  unavailable  not macOS, no ``security`` tool, or it failed in a way that says
+               nothing about the item (timeout, crash)
+
+Override: ``CLAUDE_MULTIACC_KEYCHAIN=0`` turns the whole lookup off (every dir reads
+as ``absent``), ``=1`` forces it on (the test suite runs the real code path on Linux
+against a fake ``security``). Unset: on when running on macOS with ``security``
+available.
+
+Run directly: ``python3 lib/keychain.py <probe|service|mtime|delete> <config-dir>``.
+"""
+from __future__ import annotations
+
+import getpass
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+SERVICE_PREFIX = 'Claude Code-credentials'
+# `security` maps OSStatus to an exit code modulo 256.
+EXIT_NOT_FOUND = 44        # errSecItemNotFound (-25300)
+EXIT_NO_INTERACTION = 36   # errSecInteractionNotAllowed (-25308): keychain locked here
+TIMEOUT_S = 8
+
+_ATTR_ACCT = re.compile(r'"acct"<blob>="((?:[^"\\]|\\.)*)"')
+_ATTR_MDAT = re.compile(r'"mdat"<timedate>=0x[0-9A-Fa-f]+\s+"(\d{14})Z')
+
+
+def enabled():
+    """Whether keychain lookups run at all in this process (see module doc)."""
+    override = os.environ.get('CLAUDE_MULTIACC_KEYCHAIN', '').strip().lower()
+    if override in ('0', 'false', 'no', 'off'):
+        return False
+    if override in ('1', 'true', 'yes', 'on'):
+        return shutil.which('security') is not None
+    return sys.platform == 'darwin' and shutil.which('security') is not None
+
+
+def service_name(config_dir):
+    """The keychain service Claude Code uses for a CLAUDE_CONFIG_DIR — hashed from the
+    path string exactly as the client was given it (no realpath, no trailing slash
+    games), which is what the shim passes: ``$ACC_ROOT/acct-NN``."""
+    digest = hashlib.sha256(str(config_dir).encode('utf-8')).hexdigest()[:8]
+    return f'{SERVICE_PREFIX}-{digest}'
+
+
+def _run(args, timeout=TIMEOUT_S):
+    """(returncode, stdout, stderr); returncode None when the tool could not run."""
+    try:
+        p = subprocess.run(['security'] + list(args), capture_output=True, text=True,
+                           timeout=timeout, stdin=subprocess.DEVNULL)
+    except (OSError, subprocess.SubprocessError):
+        return None, '', ''
+    return p.returncode, p.stdout or '', p.stderr or ''
+
+
+def _attributes(service):
+    """(rc, account, modified_epoch). Attribute reads work on a LOCKED keychain — only
+    the secret needs it open — which is what tells 'locked' from 'absent'."""
+    rc, out, _err = _run(['find-generic-password', '-s', service])
+    if rc != 0:
+        return rc, None, None
+    acct = _ATTR_ACCT.search(out)
+    mdat = _ATTR_MDAT.search(out)
+    modified = None
+    if mdat:
+        try:
+            import calendar
+            modified = calendar.timegm(time.strptime(mdat.group(1), '%Y%m%d%H%M%S'))
+        except (ValueError, OverflowError):
+            modified = None
+    return rc, (acct.group(1) if acct else None), modified
+
+
+def probe(config_dir):
+    """Never raises, never logs the secret. See the module doc for the states."""
+    service = service_name(config_dir)
+    result = {'state': 'unavailable', 'service': service, 'doc': None,
+              'account': None, 'modified': None}
+    if not enabled():
+        result['state'] = 'absent' if os.environ.get('CLAUDE_MULTIACC_KEYCHAIN', '') \
+            .strip().lower() in ('0', 'false', 'no', 'off') else 'unavailable'
+        return result
+    rc, out, _err = _run(['find-generic-password', '-s', service, '-w'])
+    if rc == 0:
+        try:
+            doc = json.loads(out.strip())
+        except ValueError:
+            doc = None
+        if isinstance(doc, dict) and isinstance(doc.get('claudeAiOauth'), dict):
+            result.update(state='present', doc=doc)
+        else:
+            result['state'] = 'corrupt'
+        return result
+    if rc == EXIT_NOT_FOUND:
+        result['state'] = 'absent'
+        return result
+    if rc == EXIT_NO_INTERACTION:
+        arc, acct, modified = _attributes(service)
+        if arc == 0:
+            result.update(state='locked', account=acct, modified=modified)
+        elif arc == EXIT_NOT_FOUND:
+            result['state'] = 'absent'
+        return result
+    return result
+
+
+def item_mtime(config_dir):
+    """Epoch of the item's last modification (0 when absent/unknown). Readable even
+    when the keychain is locked, so a marker can still self-heal on a newer login."""
+    if not enabled():
+        return 0
+    rc, _acct, modified = _attributes(service_name(config_dir))
+    if rc != 0:
+        return 0
+    return modified or 0
+
+
+def write(config_dir, doc, account=None):
+    """Store ``doc`` the way Claude Code does (``add-generic-password -U``, hex
+    payload, same account name as the existing item so no duplicate is created).
+    True on success. The document is passed on argv — the same choice the client
+    makes when its payload does not fit `security -i`'s line limit; ``ps`` exposure
+    lasts milliseconds and is the same window `add-generic-password -w` always had."""
+    if not enabled():
+        return False
+    service = service_name(config_dir)
+    if not account:
+        _rc, existing, _m = _attributes(service)
+        account = existing or _current_user()
+    payload = json.dumps(doc, separators=(',', ':')).encode('utf-8').hex()
+    rc, _out, _err = _run(['add-generic-password', '-U', '-a', account, '-s', service,
+                           '-X', payload])
+    return rc == 0
+
+
+def delete(config_dir):
+    """Remove the item. True when it is gone (including when it never existed)."""
+    if not enabled():
+        return True
+    rc, _out, _err = _run(['delete-generic-password', '-s', service_name(config_dir)])
+    return rc in (0, EXIT_NOT_FOUND)
+
+
+def _current_user():
+    try:
+        return getpass.getuser()
+    except Exception:  # noqa: BLE001 — no passwd entry; the keychain item name is cosmetic
+        return os.environ.get('USER') or 'claude'
+
+
+def main(argv):
+    if len(argv) != 3 or argv[1] not in ('probe', 'service', 'mtime', 'delete'):
+        print('usage: keychain.py <probe|service|mtime|delete> <config-dir>', file=sys.stderr)
+        return 2
+    verb, config_dir = argv[1], argv[2]
+    if verb == 'service':
+        print(service_name(config_dir))
+        return 0
+    if verb == 'mtime':
+        print(item_mtime(config_dir))
+        return 0
+    if verb == 'delete':
+        return 0 if delete(config_dir) else 1
+    res = probe(config_dir)
+    # The secret itself never leaves this process on stdout: callers that need the
+    # document import the module. The CLI answers with the state and non-secret facts.
+    o = (res.get('doc') or {}).get('claudeAiOauth') or {}
+    print(json.dumps({'state': res['state'], 'service': res['service'],
+                      'account': res['account'], 'modified': res['modified'],
+                      'expires_at': o.get('expiresAt'),
+                      'refresh_token_expires_at': o.get('refreshTokenExpiresAt'),
+                      'has_refresh_token': bool(o.get('refreshToken'))}))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))

package/lib/report.py

@@ -23,14 +23,18 @@ Account status vocabulary (the panel's contract):
   limited   authenticates, but a >=threshold bucket is parked until limit_reset_at
   expired   has auth material that cannot authenticate — needs an interactive login
   blocked   authenticates, but the org/workspace disabled the CLI for it
+  locked    claude only: the OAuth login is in the macOS Keychain and the process
+            that built this report could not open it (ssh/background session) — the
+            Mac's own GUI session uses it fine; never reported by a launchd runner
   missing   no auth material on this machine (and this machine should own it)
   remote    no auth here on purpose — the manifest says another machine owns it
 
 Credential classes (what may be COPIED between machines):
   portable      claude setup-token (server.token) — safe to export/import anywhere
-  machine-local claude .credentials.json / codex auth.json — rotating refresh grant;
-                copying it makes two machines fight over one grant and breaks both
-  none          nothing on disk here
+  machine-local claude .credentials.json OR a macOS Keychain item (credentials.oauth_store
+                says which) / codex auth.json — rotating refresh grant; copying it makes
+                two machines fight over one grant and breaks both
+  none          nothing on disk (or in the Keychain) here
 """
 
 import json
@@ -40,6 +44,9 @@ import socket
 import sys
 import time
 
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import keychain  # noqa: E402
+
 SCHEMA = 'claude-multiacc/pool.v1'
 
 # Must match the SHIM's ranking window, or this document calls data "fresh" that
@@ -152,20 +159,36 @@ def _sync_block(root, manifest):
 
 
 def _claude_credentials(d):
-    """(credential_class, credentials-detail) for a claude account dir."""
+    """(credential_class, credentials-detail) for a claude account dir.
+
+    The OAuth login is machine-local whether it sits in `.credentials.json` or in the
+    macOS Keychain (`oauth_store` says which; `keychain` says whether THIS process could
+    open it). A Keychain login this session cannot open is still a login on this Mac —
+    reporting it as `none` is what made a whole pool of working accounts read as
+    missing — so the class stays machine-local and the row's status says `locked`."""
     cpath = os.path.join(d, '.credentials.json')
     tpath = os.path.join(d, 'server.token')
     has_oauth = _size(cpath) > 0
     has_token = _size(tpath) > 0
-    detail = {'oauth': has_oauth, 'token': has_token,
+    detail = {'oauth': has_oauth, 'token': has_token, 'oauth_store': None, 'keychain': None,
               'oauth_expires_at': None, 'oauth_refresh_expires_at': None,
               'token_minted_at': None, 'token_age_days': None}
+    o = None
     if has_oauth:
+        detail['oauth_store'] = 'file'
         doc = _load_json(cpath) or {}
         o = doc.get('claudeAiOauth')
-        if isinstance(o, dict):
-            detail['oauth_expires_at'] = _iso_ms(o.get('expiresAt'))
-            detail['oauth_refresh_expires_at'] = _iso_ms(o.get('refreshTokenExpiresAt'))
+    else:
+        kc = keychain.probe(d)
+        if kc['state'] in ('present', 'corrupt', 'locked'):
+            has_oauth = True
+            detail['oauth'] = True
+            detail['oauth_store'] = 'keychain'
+            detail['keychain'] = 'locked' if kc['state'] == 'locked' else 'readable'
+            o = (kc['doc'] or {}).get('claudeAiOauth')
+    if isinstance(o, dict):
+        detail['oauth_expires_at'] = _iso_ms(o.get('expiresAt'))
+        detail['oauth_refresh_expires_at'] = _iso_ms(o.get('refreshTokenExpiresAt'))
     if has_token:
         mt = _mtime(tpath)
         detail['token_minted_at'] = _iso(mt)
@@ -318,6 +341,8 @@ def _account_row(root, a, aid, d, provider, jwt_claims, audit_account, now, kind
         'reason': st['reason'],
         'fix': st['fix'],
         'selectable': st['state'] == 'ok' and not limited,
+        # 'locked' is deliberately NOT a login worklist item: the login exists and works
+        # from the Mac's own session; only the reporting process could not open it.
         'needs_login': st['state'] in ('expired', 'blocked', 'missing'),
         'credential_class': cclass,
         'portable': cclass == 'portable',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {