claude-multiacc 2.0.2 → 2.0.4

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.2",
+  "version": "2.0.4",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {

package/tests/run-tests.sh

@@ -56,6 +56,16 @@ if [ "${1:-}" = "auth" ] && [ "${2:-}" = "status" ]; then
 fi
 if [ "${1:-}" = "auth" ] && [ "${2:-}" = "login" ]; then
   [ -n "${FAKE_LOGIN_FAIL:-}" ] && { echo "login aborted" >&2; exit 1; }
+  if [ -n "${FAKE_LOGIN_KEYCHAIN:-}" ] && [ -n "${CLAUDE_CONFIG_DIR:-}" ]; then
+    # simulate the macOS client in a keychain-capable session: the login lands in the
+    # keychain (via the fake `security` on PATH) and NO .credentials.json is written
+    h="$(printf '%s' "$CLAUDE_CONFIG_DIR" | { shasum -a 256 2>/dev/null || sha256sum; } | cut -c1-8)"
+    hex="$(printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-login","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999,"scopes":["user:inference"],"subscriptionType":"max"}}' \
+      | python3 -c 'import sys;print(sys.stdin.buffer.read().hex())')"
+    security add-generic-password -U -a tester -s "Claude Code-credentials-$h" -X "$hex"
+    echo "Logged in."
+    exit 0
+  fi
   # simulate a completed full-scope login: write auto-refreshing creds to the config dir
   printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-login","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999,"scopes":["user:inference"],"subscriptionType":"max"}}' > "${CLAUDE_CONFIG_DIR:-/dev/null}/.credentials.json"
   echo "Logged in."
@@ -134,6 +144,65 @@ echo "CFG=$acct TOK=${CLAUDE_CODE_OAUTH_TOKEN:-none} ARGS=$*"
 EOF
 chmod +x "$FAKEBIN/claude"
 
+# Fake macOS `security` (generic-password verbs only): items live as files under
+# $FAKE_KEYCHAIN_DIR/<service> (content = the secret) + <service>.acct (account name).
+# FAKE_KEYCHAIN_LOCKED=1 simulates a session that cannot open the keychain — secret
+# reads and every write exit 36 while ATTRIBUTE reads still answer, exactly the split
+# the real tool exhibits over ssh. Shadows any real /usr/bin/security via PATH, so a
+# macOS dev run of this suite can never touch the developer's actual keychain.
+cat > "$FAKEBIN/security" <<'EOF'
+#!/usr/bin/env bash
+KC="${FAKE_KEYCHAIN_DIR:-/nonexistent-keychain}"
+cmd="${1:-}"; shift || true
+svc=""; acct=""; want_pw=0; hexdata=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -s) svc="$2"; shift 2 ;;
+    -a) acct="$2"; shift 2 ;;
+    -w) want_pw=1; shift ;;
+    -X) hexdata="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+# The modification stamp is RECORDED AT WRITE TIME in a sidecar rather than derived
+# from the item file's mtime: `stat`/`date` flags differ between BSD and GNU (on Linux
+# `stat -f %m` even "succeeds" with garbage), and this fake must behave identically on
+# a developer's Mac and on Linux CI.
+item_mdat() { cat "$KC/$svc.mdat" 2>/dev/null || echo 00000000000000; }
+case "$cmd" in
+  show-keychain-info)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    exit 0 ;;
+  find-generic-password)
+    [ -f "$KC/$svc" ] || exit 44
+    if [ "$want_pw" = "1" ]; then
+      [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+      cat "$KC/$svc"
+      exit 0
+    fi
+    a="tester"; [ -f "$KC/$svc.acct" ] && a="$(cat "$KC/$svc.acct")"
+    printf 'keychain: "login.keychain-db"\nclass: "genp"\nattributes:\n'
+    printf '    "acct"<blob>="%s"\n' "$a"
+    printf '    "mdat"<timedate>=0x00  "%sZ\\000"\n' "$(item_mdat)"
+    printf '    "svce"<blob>="%s"\n' "$svc"
+    exit 0 ;;
+  add-generic-password)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    mkdir -p "$KC"
+    printf '%s' "$hexdata" | python3 -c 'import sys;sys.stdout.buffer.write(bytes.fromhex(sys.stdin.read().strip()))' > "$KC/$svc"
+    printf '%s' "${acct:-tester}" > "$KC/$svc.acct"
+    date -u +%Y%m%d%H%M%S > "$KC/$svc.mdat"
+    exit 0 ;;
+  delete-generic-password)
+    [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ] && exit 36
+    [ -f "$KC/$svc" ] || exit 44
+    rm -f "$KC/$svc" "$KC/$svc.acct" "$KC/$svc.mdat"
+    exit 0 ;;
+  *) exit 1 ;;
+esac
+EOF
+chmod +x "$FAKEBIN/security"
+
 export PATH="$REPO_DIR/bin:$FAKEBIN:$PATH"
 export FAKE_CTL="$WORK/ctl"
 # Neutralize any ambient state from the invoking environment.
@@ -155,6 +224,10 @@ export CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-endpoint-missing.json"
 # throttle keeps those background kicks from racing explicit limits runs.
 export CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-endpoint-missing.json"
 : > "$ACC/.limits-kick"
+# Keychain lookups are OFF for the legacy sections (their pools are file-based and the
+# extra `security` process per account would only slow them down); section 17 turns
+# them on explicitly against the fake `security` above.
+export CLAUDE_MULTIACC_KEYCHAIN=0
 
 now="$(date +%s)"
 
@@ -2366,6 +2439,61 @@ if command -v node >/dev/null 2>&1; then
   esac
   case "$out" in *"update manually"*|*"already latest"*|*"git pull"*) t_ok "self-update reports its path" ;;
     *) t_fail "self-update message" "unexpected: $out" ;; esac
+
+  # ---- 19a. an npm install updates itself with NO npm on PATH -----------------------
+  # launchd hands an agent PATH=/usr/bin:/bin:/usr/sbin:/sbin, so `command -v npm` finds
+  # nothing and the nightly self-update logged "npm not found; skipping" for days while
+  # every Mac's copy silently froze. npm must be resolved by path — and specifically the
+  # one inside the prefix that owns the RUNNING copy, never whatever a stray PATH offers.
+  for _cli in claude-accounts codex-accounts; do
+    PFX="$WORK/pfx-$_cli"
+    NPMROOT="$PFX/lib/node_modules/claude-multiacc"
+    mkdir -p "$NPMROOT" "$PFX/bin"
+    cp -R "$REPO_DIR/bin" "$REPO_DIR/lib" "$REPO_DIR/package.json" "$NPMROOT/"
+    # A fake npm that records how it was called and "installs" by bumping package.json.
+    cat > "$PFX/bin/npm" <<NPMEOF
+#!/usr/bin/env bash
+echo "npm \$*" >> "$WORK/npm-calls-$_cli.log"
+case "\${1:-}" in
+  view) echo 9.9.9 ;;
+  install) python3 - "$NPMROOT/package.json" <<'PY'
+import json, sys
+p = sys.argv[1]
+doc = json.load(open(p)); doc['version'] = '9.9.9'
+json.dump(doc, open(p, 'w'))
+PY
+    ;;
+esac
+exit 0
+NPMEOF
+    chmod +x "$PFX/bin/npm"
+    # A DIFFERENT npm earlier on PATH must not win: the running copy's prefix owns it.
+    mkdir -p "$WORK/wrongbin"
+    printf '#!/usr/bin/env bash\necho "WRONG-NPM \$*" >> "%s"\nexit 0\n' "$WORK/npm-calls-$_cli.log" > "$WORK/wrongbin/npm"
+    chmod +x "$WORK/wrongbin/npm"
+    : > "$WORK/npm-calls-$_cli.log"
+    out="$(env -i HOME="$HOME" PATH="$WORK/wrongbin:/usr/bin:/bin:/usr/sbin:/sbin" \
+      CLAUDE_ACCOUNTS_DIR="$ACC" CODEX_ACCOUNTS_DIR="$WORK/codex-accounts" \
+      "$NPMROOT/bin/$_cli" self-update 2>&1)"
+    rc=$?
+    [ "$rc" = "0" ] && t_ok "$_cli: self-update exits 0 with no npm on PATH" \
+      || t_fail "$_cli self-update rc" "rc=$rc: $(printf '%s' "$out" | head -c 200)"
+    printf '%s' "$out" | grep -q "npm not found" \
+      && t_fail "$_cli self-update npm lookup" "still reports 'npm not found' with an npm in its own prefix" \
+      || t_ok "$_cli: npm resolved without PATH"
+    grep -q "^npm install " "$WORK/npm-calls-$_cli.log" \
+      && t_ok "$_cli: the prefix's own npm performed the install" \
+      || t_fail "$_cli npm install" "calls: $(cat "$WORK/npm-calls-$_cli.log" | head -3)"
+    grep -q "WRONG-NPM" "$WORK/npm-calls-$_cli.log" \
+      && t_fail "$_cli npm choice" "used the npm from PATH instead of the running prefix's" \
+      || t_ok "$_cli: a stray npm on PATH never wins over the running prefix's"
+    check "$_cli: self-update verifies the tree it wrote" "npm update ok (9.9.9)" "$out"
+  done
+  # The agents install.sh writes must carry a PATH for the same reason (a future tool
+  # that is not resolved by absolute path would hit exactly this again).
+  grep -q '<key>PATH</key>' "$REPO_DIR/install.sh" \
+    && t_ok "install.sh gives its launchd agents a PATH" \
+    || t_fail "agent PATH" "plist_env_block writes no PATH — launchd agents get /usr/bin:/bin only"
   # postinstall must SKIP for a non-global install and never fail
   out="$(node "$REPO_DIR/scripts/postinstall.mjs" 2>&1)"
   rc=$?
@@ -2399,6 +2527,7 @@ unset CODEX_HOME CODEX_ACCOUNT CODEX_SHIM_ACTIVE 2>/dev/null || true
 export CODEX_MULTIACC_NO_SYNC=1
 export CODEX_MULTIACC_MIN_FETCH=0
 export CODEX_MULTIACC_CLIENT_SCAN_TTL=0
+export CODEX_MULTIACC_AUTO_RESET=0
 export CODEX_MULTIACC_TOKEN_URL="file://$WORK/cx-token-endpoint-missing.json"
 # Default usage URL is an offline missing fixture: the SHIM's opportunistic
 # background `limits --quiet` kick must never reach a real endpoint from tests
@@ -4071,6 +4200,164 @@ for _bin in claude-accounts codex-accounts; do
     || t_fail "$_bin unknown verb --help" "exited 0 — the probe would accept a verb that does not exist"
 done
 
+# ---- 17. macOS Keychain-held logins --------------------------------------------------
+# Claude Code on macOS moves a per-dir OAuth login into the login Keychain (service
+# "Claude Code-credentials-<sha256(dir)[:8]>") from any keychain-capable session and
+# deletes .credentials.json — the 2026-08-28 incident read five working accounts as
+# "missing". The fake `security` above serves items from $FAKE_KEYCHAIN_DIR so the real
+# lookup code runs on Linux too. Own pool root: the main pool's manifest has been
+# through a dozen mutations by this point in the suite.
+KCP="$WORK/kcpool"
+export FAKE_KEYCHAIN_DIR="$WORK/keychain"
+mkdir -p "$KCP/tmp" "$KCP/acct-01" "$KCP/acct-02" "$FAKE_KEYCHAIN_DIR"
+: > "$KCP/.limits-kick"
+cat > "$KCP/accounts.json" <<EOF
+{ "version": 1, "server": "root@203.0.113.1", "server_root": "/root/.claude-accounts",
+  "server_repo": "/root/claude-multiacc", "threshold": 90,
+  "accounts": [
+    {"id": "acct-01", "email": "kfile@test", "home": "mac", "added_at": "2026-08-28T00:00:00Z"},
+    {"id": "acct-02", "email": "kchain@test", "home": "mac", "added_at": "2026-08-28T00:00:00Z"}
+  ] }
+EOF
+printf '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kfile","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}' > "$KCP/acct-01/.credentials.json"
+kc_hash() { printf '%s' "$1" | { shasum -a 256 2>/dev/null || sha256sum; } | cut -c1-8; }
+kc_svc_file() { printf '%s/Claude Code-credentials-%s' "$FAKE_KEYCHAIN_DIR" "$(kc_hash "$1")"; }
+kc_put() { # kc_put <acct dir> <credential json> — store it the way the client would
+  security add-generic-password -U -a tester -s "Claude Code-credentials-$(kc_hash "$1")" \
+    -X "$(printf '%s' "$2" | python3 -c 'import sys;print(sys.stdin.buffer.read().hex())')"
+}
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kchain","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+export CLAUDE_MULTIACC_KEYCHAIN=1
+
+# 17a. the keychain login reads as a working machine-local OAuth login
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list --json 2>&1)"
+python3 - "$out" <<'EOF'
+import json, sys
+doc = json.loads(sys.argv[1])
+rows = {a['id']: a for a in doc['accounts']}
+a2 = rows['acct-02']
+assert a2['status'] == 'active', a2['status']
+assert a2['credential_class'] == 'machine-local', a2['credential_class']
+assert a2['credentials']['oauth_store'] == 'keychain', a2['credentials']
+assert a2['credentials']['keychain'] == 'readable', a2['credentials']
+assert a2['selectable'] is True, a2
+assert rows['acct-01']['credentials']['oauth_store'] == 'file', rows['acct-01']['credentials']
+assert doc['summary']['selectable'] == 2, doc['summary']
+EOF
+[ $? -eq 0 ] && t_ok "keychain login is active machine-local in list --json" \
+  || t_fail "keychain list --json" "see assertions above"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list 2>&1)"
+check "keychain login shown in the plain list" "auth=keychain" "$out"
+
+# 17b. the shim runs under a keychain-only account (file account parked by a limit)
+printf '%s\nbucket=weekly_scoped:Fable percent=95 reason=limits\n' "$((now+3600))" > "$KCP/acct-01/.limited"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude 2>&1)"
+check "shim selects the keychain-only account" "CFG=acct-02" "$out"
+
+# 17c. locked keychain (ssh session): 'locked', never 'missing'; excluded HERE only
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts list --json 2>&1)"
+python3 - "$out" <<'EOF'
+import json, sys
+doc = json.loads(sys.argv[1])
+a2 = {a['id']: a for a in doc['accounts']}['acct-02']
+assert a2['status'] == 'locked', a2['status']
+assert a2['credential_class'] == 'machine-local', a2['credential_class']
+assert a2['credentials']['keychain'] == 'locked', a2['credentials']
+assert a2['selectable'] is False, a2
+assert a2['needs_login'] is False, 'locked must not join the re-login worklist'
+EOF
+[ $? -eq 0 ] && t_ok "locked keychain reads as 'locked' machine-local, not missing" \
+  || t_fail "keychain locked state" "see assertions above"
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts expired --quiet 2>&1)"; rc=$?
+[ "$rc" = "0" ] && t_ok "a locked keychain login is not a relogin worklist item" \
+  || t_fail "locked vs expired" "rc=$rc out=$out"
+out="$(FAKE_KEYCHAIN_LOCKED=1 CLAUDE_ACCOUNTS_DIR="$KCP" claude 2>&1)"
+check "shim never selects a keychain login it cannot read" "CFG=acct-01" "$out"
+rm -f "$KCP/acct-01/.limited"
+
+# 17d. limits: the probe takes its bearer from the keychain
+rm -f "$KCP/acct-02/limits.json"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits 2>&1)"
+check "limits fetches with a keychain bearer" "acct-02: ok" "$out"
+python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); assert d.get("source")=="oauth", d' \
+  "$KCP/acct-02/limits.json" 2>/dev/null \
+  && t_ok "keychain-backed telemetry records source=oauth" \
+  || t_fail "keychain limits source" "limits.json missing or wrong source"
+
+# 17e. refresh: an expired keychain credential refreshes via the grant and is written
+# BACK to the keychain — never copied out into a .credentials.json
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kold","refreshToken":"sk-ant-ort01-kc","expiresAt":1000000,"refreshTokenExpiresAt":9999999999999}}'
+rm -f "$KCP/acct-02/limits.json" "$KCP/acct-02/.oauth-refresh.json"
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" CLAUDE_MULTIACC_TOKEN_URL="file://$WORK/token-ok.json" CLAUDE_MULTIACC_USAGE_URL="file://$WORK/usage-low.json" claude-accounts limits --force 2>&1)"
+check "keychain credential refreshes via the grant" "acct-02: oauth access token refreshed" "$out"
+grep -q 'sk-ant-oat01-refreshednew' "$(kc_svc_file "$KCP/acct-02")" \
+  && t_ok "rotated credential written back to the keychain" \
+  || t_fail "keychain write-back" "item not updated"
+[ ! -f "$KCP/acct-02/.credentials.json" ] \
+  && t_ok "refresh never copies the keychain credential to a file" \
+  || t_fail "keychain leak to file" ".credentials.json appeared beside a keychain login"
+
+# 17f. .expired self-heals on a keychain login written after the marker
+printf '%s\nreason=auth-error marked_at=t detail=test\n' "$now" > "$KCP/acct-02/.expired"
+touch -t 202001010000 "$KCP/acct-02/.expired"
+kc_put "$KCP/acct-02" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-knew","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+CLAUDE_ACCOUNTS_DIR="$KCP" claude >/dev/null 2>&1
+[ ! -f "$KCP/acct-02/.expired" ] \
+  && t_ok ".expired self-heals on a newer keychain credential" \
+  || t_fail "keychain .expired self-heal" "marker survived a newer keychain login"
+
+# 17g. a login ceremony that lands in the keychain registers instead of dying
+out="$(CLAUDE_MULTIACC_FORCE_TTY=1 FAKE_LOGIN_KEYCHAIN=1 FAKE_EMAIL=kc3@test CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts add kc3@test 2>&1)"
+check "add registers a keychain-backed sign-in" "Registered acct-03 for kc3@test" "$out"
+[ ! -f "$KCP/acct-03/.credentials.json" ] \
+  && t_ok "keychain add leaves no plaintext credential" \
+  || t_fail "keychain add" "unexpected .credentials.json"
+[ -f "$(kc_svc_file "$KCP/acct-03")" ] && t_ok "the sign-in landed in the keychain" \
+  || t_fail "keychain add item" "no keychain item for acct-03"
+
+# 17h. export refuses a keychain-held machine-local credential, naming the store
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts export-credential acct-03 --out "$WORK/kc-export.json" 2>&1)"; rc=$?
+[ "$rc" = "3" ] && t_ok "export-credential refuses a keychain login (exit 3)" \
+  || t_fail "keychain export rc" "rc=$rc: $(printf '%s' "$out" | head -c 160)"
+check "export names the keychain as the machine-local store" "macOS Keychain" "$out"
+
+# 17i. remove deletes the keychain item with the account
+CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts remove acct-03 --yes >/dev/null 2>&1
+[ ! -f "$(kc_svc_file "$KCP/acct-03")" ] && t_ok "remove drops the keychain item" \
+  || t_fail "keychain remove" "the item survived removal"
+
+# 17j. dedupe keeps the duplicate that actually holds the (keychain) login. The
+# keychain holder gets the HIGHER id on purpose: with keychain auth invisible, the
+# lowest-id tiebreak would keep credential-less acct-04 and throw the grant away.
+python3 - "$KCP/accounts.json" <<'EOF'
+import json, sys
+doc = json.load(open(sys.argv[1]))
+doc['accounts'] += [
+    {'id': 'acct-04', 'email': 'kdup@test', 'home': 'mac', 'added_at': '2026-08-28T00:00:00Z'},
+    {'id': 'acct-05', 'email': 'kdup@test', 'home': 'mac', 'added_at': '2026-08-28T00:00:00Z'}]
+json.dump(doc, open(sys.argv[1], 'w'))
+EOF
+mkdir -p "$KCP/acct-04" "$KCP/acct-05"
+kc_put "$KCP/acct-05" '{"claudeAiOauth":{"accessToken":"sk-ant-oat01-kdup","refreshToken":"r","expiresAt":9999999999999,"refreshTokenExpiresAt":9999999999999}}'
+out="$(CLAUDE_ACCOUNTS_DIR="$KCP" claude-accounts dedupe --yes 2>&1)"
+check "dedupe removes the credential-less duplicate, not the keychain one" "will remove acct-04 (kdup@test)" "$out"
+[ -f "$(kc_svc_file "$KCP/acct-05")" ] && t_ok "the keychain-authed duplicate survives dedupe" \
+  || t_fail "dedupe keychain keep" "acct-05's keychain item is gone"
+grep -q '"acct-04"' "$KCP/accounts.json" \
+  && t_fail "dedupe manifest" "acct-04 still registered" \
+  || t_ok "the credential-less duplicate left the manifest"
+
+export CLAUDE_MULTIACC_KEYCHAIN=0
+unset FAKE_KEYCHAIN_DIR
+
+# The reset-credit contract is easier to prove against a stateful local HTTP server
+# than file:// fixtures: it pins thresholding, credit ordering and idempotent POST retry.
+if CODEX_MULTIACC_AUTO_RESET=1 python3 "$REPO_DIR/tests/test_codex_reset.py"; then
+  t_ok "codex: automatic earned-reset integration suite"
+else
+  t_fail "codex automatic reset suite" "see unittest output above"
+fi
+
 # ---- summary ---------------------------------------------------------------------
 echo
 echo "passed: $PASS  failed: $FAIL"