claude-multiacc 2.0.41 → 2.0.43

package/lib/common.sh

@@ -12,6 +12,19 @@
 # shellcheck disable=SC2034
 
 MULTIACC_PROVIDER="${MULTIACC_PROVIDER:-claude}"
+
+# Claude Code names its macOS Keychain item after $USER, and under Bun a client with no
+# USER calls the user "unknown": `claude-accounts login` run from an env without it
+# (app-robot's panel, 2026-09-24) filed the fresh login beside the old item, under a
+# name the next client never reads (lib/keychain.py). So every client these CLIs start
+# inherits a real name, whatever env the caller passed; bin/claude does the same.
+# Harmless for codex and on Linux.
+if [ -z "${USER:-}" ]; then
+  USER="$(id -un 2>/dev/null || true)"
+  if [ -n "$USER" ]; then export USER; else unset USER; fi
+fi
+if [ -z "${LOGNAME:-}" ] && [ -n "${USER:-}" ]; then export LOGNAME="$USER"; fi
+
 PYBIN="${CLAUDE_MULTIACC_PYTHON:-python3}"
 DEFAULT_SERVER="root@138.197.36.107"
 DEFAULT_SERVER_REPO="/root/claude-multiacc"
@@ -469,10 +482,20 @@ keychain_state() { # $1 = acct dir -> prints present|locked|absent|corrupt|unava
 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)
+keychain_forget() { # $1 = acct dir: drop every 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
 }
+keychain_prune() { # $1 = acct dir: drop the non-canonical items once the canonical one is a
+                   # live login (lib/keychain.py prune). Quiet, never fails; logs only a change.
+  [ "$MULTIACC_PROVIDER" = "codex" ] && return 0
+  local line
+  line="$("$PYBIN" "$LIB_DIR/keychain.py" prune "$1" 2>/dev/null)" || true
+  case "$line" in
+    pruned:*|failed:*) log_to ops.log "keychain prune $(basename "$1"): $line" ;;
+  esac
+  return 0
+}
 
 # ---- expired-login bookkeeping -------------------------------------------------
 # `.expired` is the persistent "this account cannot authenticate" marker the shim

package/lib/keychain.py

@@ -1,13 +1,11 @@
 """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.
+Claude Code on macOS keeps a config dir's OAuth credential in the login Keychain
+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 —
@@ -16,6 +14,49 @@ file is gone. Reading only ``.credentials.json`` then reports a perfectly workin
 login as "no credentials on this machine": the shim stops selecting it, telemetry
 goes dark, and every consumer of ``list --json`` shows it missing.
 
+The layout (read out of the Bun-compiled client, 2.1.281):
+  service  ``Claude Code-credentials-<sha256(CLAUDE_CONFIG_DIR)[:8]>``
+  account  the client's own name for the user: ``$USER``, else
+           ``os.userInfo().username``; a name outside ``[A-Za-z0-9._-]+`` (or a
+           lookup that throws) becomes ``claude-code-user``
+  read     ``find-generic-password -a <name> -s <svc> -w`` — ONLY its own name; exit
+           44 falls back to ``<config>/.credentials.json``
+  write    ``add-generic-password -U -a <name> -s <svc> -X <hex>``
+  logout   deletes ``-a <name>`` only
+
+Under Bun, ``os.userInfo().username`` is ``"unknown"`` when USER is unset. So a
+client started without USER — app-robot's panel ran ``claude-accounts login`` with an
+env that had none (2026-09-24) — files its fresh login under ``unknown`` BESIDE an
+older item under the real name, and ``security find-generic-password -s <svc>``
+without ``-a`` answers with the OLDEST item: the dead one. That is how a sign-in that
+worked read back as "no working credential landed". lib/common.sh and bin/claude now
+fill USER from ``id -un`` when the caller's env has none, so every client multiacc
+starts files and reads its login under :func:`canonical_account`.
+
+Hence the rules here:
+  - a lookup reads exactly the item a multiacc-launched client reads: ``-a <canonical>``,
+    ONE ``security`` call, the cost of the old no ``-a`` lookup. Exit 44 is "absent",
+    even when an item sits under another name: its client cannot read it, so audit,
+    report, verify and the marker checks must not count it (a fallback that did made
+    ``list --json`` advertise accounts the shim never picks, and made ``verify`` test a
+    token-backed account on a login its client could not see, then park it);
+  - ``probe(d, legacy=True)`` adds the old no ``-a`` first match when no canonical item
+    exists. Only the limits pass (which then moves such a login under the canonical
+    name) and ``dedupe`` (which must not throw away a stranded grant) ask for it; it
+    costs a second call when no canonical item exists;
+  - :func:`write` always targets the canonical name. Once the canonical item reads back
+    with the access token just written, it deletes each other item that is provably
+    spent: the same grant (the written refresh token, or the ``supersedes`` one a
+    refresh started from), a dead login, or not a credential at all. A LIVE other grant
+    stays — after a sign-in as the wrong account the client itself put the intruder's
+    grant under the canonical name, and the right account's login may be that sibling;
+  - :func:`delete` removes every item for the service, whatever its name;
+  - :func:`prune` deletes all non-canonical items, and ONLY when the canonical item is
+    present, readable and a live credential (audit.creds_doc_state 'ok'). It never
+    writes and never handles the secret beyond that read. The sign-in commands run it
+    once the ceremony's identity check has passed — never before, so a sign-in as the
+    wrong account cannot cost the right account its login.
+
 This module is the one place that knows the keychain layout. Everything else asks
 :func:`probe`, which never raises and never prints the secret.
 
@@ -28,20 +69,25 @@ States returned by :func:`probe`:
   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)
+``account`` is the name of the item that answered: the canonical one, or with
+``legacy=True`` whatever the fallback could name (None when it read a secret without
+the extra call it would take to name its item). ``canonical`` is the name a write
+targets.
 
 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>``.
+Run directly: ``python3 lib/keychain.py <probe|service|mtime|delete|prune> <config-dir>``.
 """
 from __future__ import annotations
 
-import getpass
+import calendar
 import hashlib
 import json
 import os
+import pwd
 import re
 import shutil
 import subprocess
@@ -53,9 +99,15 @@ SERVICE_PREFIX = 'Claude Code-credentials'
 EXIT_NOT_FOUND = 44        # errSecItemNotFound (-25300)
 EXIT_NO_INTERACTION = 36   # errSecInteractionNotAllowed (-25308): keychain locked here
 TIMEOUT_S = 8
+# The client's fallback name, and the one Bun's os.userInfo() reports without USER.
+FALLBACK_ACCOUNT = 'claude-code-user'
+BUN_UNSET_ACCOUNT = 'unknown'
+# `delete-generic-password -s` without -a removes one (the oldest) item per call.
+DELETE_SWEEP_CAP = 16
 
 _ATTR_ACCT = re.compile(r'"acct"<blob>="((?:[^"\\]|\\.)*)"')
 _ATTR_MDAT = re.compile(r'"mdat"<timedate>=0x[0-9A-Fa-f]+\s+"(\d{14})Z')
+_VALID_ACCOUNT = re.compile(r'[A-Za-z0-9._-]+')
 
 
 def enabled():
@@ -76,6 +128,17 @@ def service_name(config_dir):
     return f'{SERVICE_PREFIX}-{digest}'
 
 
+def canonical_account():
+    """The account name a client launched by multiacc files its login under: the
+    client's own rule (USER, else the user database) with the passwd entry standing in
+    for Bun's ``"unknown"`` — the name lib/common.sh and bin/claude fill USER with."""
+    try:
+        name = os.environ.get('USER') or pwd.getpwuid(os.getuid()).pw_name
+    except (KeyError, OSError):
+        return FALLBACK_ACCOUNT
+    return name if _VALID_ACCOUNT.fullmatch(name or '') else FALLBACK_ACCOUNT
+
+
 def _run(args, timeout=TIMEOUT_S):
     """(returncode, stdout, stderr); returncode None when the tool could not run."""
     try:
@@ -86,10 +149,16 @@ def _run(args, timeout=TIMEOUT_S):
     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])
+def _target(service, account):
+    """``-a <account> -s <service>``, or the no ``-a`` first (oldest) match."""
+    return (['-a', account] if account is not None else []) + ['-s', service]
+
+
+def _attributes(service, account=None):
+    """(rc, account, modified_epoch) of one item — the oldest when ``account`` is None.
+    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'] + _target(service, account))
     if rc != 0:
         return rc, None, None
     acct = _ATTR_ACCT.search(out)
@@ -97,93 +166,234 @@ def _attributes(service):
     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
+    return rc, (acct.group(1) if acct else account), modified
+
 
+def _names(service, skip=()):
+    """(ok, names) — the account names holding an item for ``service``: the oldest
+    item's (whatever it is called) plus each name the client can produce, minus
+    ``skip``. Several ``security`` calls, so only write/delete/prune enumerate — never
+    a lookup. ``ok`` is False when the tool failed in a way that says nothing about the
+    items (the list is then what was found before the failure)."""
+    rc, first, _m = _attributes(service)
+    if rc == EXIT_NOT_FOUND:
+        return True, []
+    if rc != 0:
+        return False, []
+    names = [first] if first is not None and first not in skip else []
+    for name in (canonical_account(), BUN_UNSET_ACCOUNT, FALLBACK_ACCOUNT):
+        if name == first or name in skip or name in names:
+            continue
+        rc, _acct, _m = _attributes(service, name)
+        if rc == EXIT_NOT_FOUND:
+            continue
+        if rc != 0:
+            return False, names
+        names.append(name)
+    return True, names
+
+
+def _credential(text):
+    try:
+        doc = json.loads(text.strip())
+    except ValueError:
+        return None
+    if isinstance(doc, dict) and isinstance(doc.get('claudeAiOauth'), dict):
+        return doc
+    return None
 
-def probe(config_dir):
-    """Never raises, never logs the secret. See the module doc for the states."""
+
+def _doc_state(doc):
+    """audit.creds_doc_state's verdict ('ok' / 'expired') on a parsed credential — the
+    one rule for "can this login work", imported lazily because audit imports this
+    module."""
+    here = os.path.dirname(os.path.abspath(__file__))
+    if here not in sys.path:
+        sys.path.insert(0, here)
+    from audit import creds_doc_state
+    try:
+        return creds_doc_state(doc, time.time())
+    except ValueError as e:
+        return 'expired', str(e)[:60]
+
+
+def _legacy_probe(service, result):
+    """The lookup as it was before canonical names: the no ``-a`` first match. Only
+    ``probe(legacy=True)`` asks for it, and only when no canonical item exists."""
+    rc, out, _err = _run(['find-generic-password', '-s', service, '-w'])
+    if rc == 0:
+        doc = _credential(out)
+        result.update(state='present' if doc is not None else 'corrupt', doc=doc)
+    elif rc == EXIT_NOT_FOUND:
+        result['state'] = 'absent'
+    elif 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
+
+
+def probe(config_dir, legacy=False):
+    """Never raises, never logs the secret. See the module doc for the states. Reads
+    the item under :func:`canonical_account` — the one a multiacc-launched client reads
+    — in ONE ``security`` call (two only for a locked keychain, to tell it from an
+    absent item). ``legacy=True`` falls back to the old no ``-a`` first match when no
+    canonical item exists (a second call); only a caller that migrates such an item or
+    must not discard it asks for that."""
     service = service_name(config_dir)
+    canonical = canonical_account()
     result = {'state': 'unavailable', 'service': service, 'doc': None,
-              'account': None, 'modified': None}
+              'account': None, 'modified': None, 'canonical': canonical}
     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'])
+    rc, out, _err = _run(['find-generic-password', '-a', canonical, '-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'
+        doc = _credential(out)
+        result.update(state='present' if doc is not None else 'corrupt', doc=doc,
+                      account=canonical)
         return result
     if rc == EXIT_NO_INTERACTION:
-        arc, acct, modified = _attributes(service)
+        arc, _acct, modified = _attributes(service, canonical)
         if arc == 0:
-            result.update(state='locked', account=acct, modified=modified)
-        elif arc == EXIT_NOT_FOUND:
-            result['state'] = 'absent'
-        return result
+            result.update(state='locked', account=canonical, modified=modified)
+            return result
+        if arc != EXIT_NOT_FOUND:
+            return result
+        rc = EXIT_NOT_FOUND          # no canonical item: the secret read said nothing
+    if rc == EXIT_NOT_FOUND:
+        if legacy:
+            return _legacy_probe(service, result)
+        result['state'] = 'absent'
     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."""
+    """Epoch of the canonical item's last modification (0 when absent/unknown) — the
+    item the client reads, as the shim's kc_mtime reads it. Readable even when the
+    keychain is locked, so a marker can still self-heal on a newer login. One call."""
     if not enabled():
         return 0
-    rc, _acct, modified = _attributes(service_name(config_dir))
+    rc, _acct, modified = _attributes(service_name(config_dir), canonical_account())
     if rc != 0:
         return 0
     return modified or 0
 
 
-def write(config_dir, doc, account=None):
+def write(config_dir, doc, account=None, supersedes=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."""
+    payload) under :func:`canonical_account` — ``account`` is accepted for old callers
+    and IGNORED: the canonical name is the one item a multiacc-launched client reads.
+    True when the add succeeded.
+
+    Once the canonical item reads back with the access token just written, each other
+    item for the service is read and deleted when it is provably spent: it holds the
+    same grant (the written refresh token, or ``supersedes`` — the refresh token a
+    refresh started from, so a legacy item the refresh came from goes with it), a dead
+    login, or no credential at all. A live OTHER grant is kept: a sign-in as the wrong
+    account puts the intruder's grant under the canonical name, and a refresh of it must
+    not destroy the right account's login beside it — only a sign-in whose identity
+    checked out may (:func:`prune`). Those reads cost calls on a write only.
+
+    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."""
+    del account
     if not enabled():
         return False
     service = service_name(config_dir)
-    if not account:
-        _rc, existing, _m = _attributes(service)
-        account = existing or _current_user()
+    canonical = canonical_account()
     payload = json.dumps(doc, separators=(',', ':')).encode('utf-8').hex()
-    rc, _out, _err = _run(['add-generic-password', '-U', '-a', account, '-s', service,
+    rc, _out, _err = _run(['add-generic-password', '-U', '-a', canonical, '-s', service,
                            '-X', payload])
-    return rc == 0
+    if rc != 0:
+        return False
+    rc, out, _err = _run(['find-generic-password', '-a', canonical, '-s', service, '-w'])
+    back = _credential(out) if rc == 0 else None
+    wrote = doc.get('claudeAiOauth') if isinstance(doc, dict) else None
+    if back is None or not isinstance(wrote, dict) \
+            or back['claudeAiOauth'].get('accessToken') != wrote.get('accessToken'):
+        return True
+    spent = {t for t in (wrote.get('refreshToken'), supersedes) if isinstance(t, str) and t}
+    _ok, siblings = _names(service, skip=(canonical,))
+    for name in siblings:
+        rc, out, _err = _run(['find-generic-password', '-a', name, '-s', service, '-w'])
+        if rc != 0:
+            continue                 # gone, or cannot be judged: leave it
+        other = _credential(out)
+        grant = other['claudeAiOauth'].get('refreshToken') if other is not None else None
+        if other is not None and not (isinstance(grant, str) and grant in spent) \
+                and _doc_state(other)[0] == 'ok':
+            continue                 # a live grant of its own
+        _run(['delete-generic-password', '-a', name, '-s', service])
+    return True
 
 
 def delete(config_dir):
-    """Remove the item. True when it is gone (including when it never existed)."""
+    """Remove every item for the dir, whatever name it sits under. True when none is
+    left (including when none ever 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)
+    service = service_name(config_dir)
+    _ok, names = _names(service)
+    for name in names:
+        _run(['delete-generic-password', '-a', name, '-s', service])
+    # Names this module does not enumerate (a user renamed since): each call without
+    # -a removes the oldest remaining item.
+    for _ in range(DELETE_SWEEP_CAP):
+        rc, _out, _err = _run(['delete-generic-password', '-s', service])
+        if rc != 0:
+            break
+    rc, _out, _err = _run(['find-generic-password', '-s', service])
+    return rc == 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 prune(config_dir):
+    """Delete the items for the dir that sit under any name but the canonical one —
+    only when the canonical item is present, readable and a live credential by the
+    audit's own rule. Never writes; a no-op in every other case. Returns (ok, one-line
+    status); the status names accounts and states only, never the secret."""
+    if not enabled():
+        return True, 'skip: keychain lookups are off'
+    service = service_name(config_dir)
+    canonical = canonical_account()
+    rc, out, _err = _run(['find-generic-password', '-a', canonical, '-s', service, '-w'])
+    if rc == EXIT_NOT_FOUND:
+        return True, f'skip: no item under {canonical}'
+    if rc == EXIT_NO_INTERACTION:
+        return True, 'skip: keychain locked for this session'
+    if rc != 0:
+        return True, 'skip: keychain unavailable'
+    doc = _credential(out)
+    if doc is None:
+        return True, f'skip: the item under {canonical} is not a credential'
+    state, reason = _doc_state(doc)
+    if state != 'ok':
+        return True, f'skip: the login under {canonical} is {state} ({reason})'
+    ok, siblings = _names(service, skip=(canonical,))
+    removed, left = [], []
+    for name in siblings:
+        rc, _out, _err = _run(['delete-generic-password', '-a', name, '-s', service])
+        (removed if rc in (0, EXIT_NOT_FOUND) else left).append(name)
+    if left or not ok:
+        return False, (f"failed: kept {canonical}, removed {','.join(removed) or '-'}, "
+                       f"left {','.join(left) or '-'}"
+                       + ('' if ok else ' (could not list every item)'))
+    if removed:
+        return True, f"pruned: kept {canonical}, removed {','.join(removed)}"
+    return True, f'ok: one item, under {canonical}'
 
 
 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)
+    verbs = ('probe', 'service', 'mtime', 'delete', 'prune')
+    if len(argv) != 3 or argv[1] not in verbs:
+        print(f"usage: keychain.py <{'|'.join(verbs)}> <config-dir>", file=sys.stderr)
         return 2
     verb, config_dir = argv[1], argv[2]
     if verb == 'service':
@@ -194,12 +404,17 @@ def main(argv):
         return 0
     if verb == 'delete':
         return 0 if delete(config_dir) else 1
+    if verb == 'prune':
+        ok, line = prune(config_dir)
+        print(line)
+        return 0 if ok 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'],
+                      'canonical': res['canonical'],
                       'expires_at': o.get('expiresAt'),
                       'refresh_token_expires_at': o.get('refreshTokenExpiresAt'),
                       'has_refresh_token': bool(o.get('refreshToken'))}))

package/package.json

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

package/tests/fake_security.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Fake macOS `security` (generic-password verbs only), shared by tests/run-tests.sh and
+# tests/test_keychain.py. Installed on PATH as `security`, it shadows any real
+# /usr/bin/security, so a macOS dev run can never touch the developer's keychain.
+#
+# It models what the real tool does with SEVERAL items per service (verified on
+# my-mini, 2026-09-24), which is what lib/keychain.py and bin/claude stand on:
+#   - an item is keyed by (service, account); `-a` selects exactly that item;
+#   - without `-a`, find/delete act on the OLDEST-created item for the service;
+#   - `add -U` updates the (service, account) item in place or creates it; `add`
+#     without -U on an existing item exits 45 (errSecDuplicateItem);
+#   - attribute reads answer on a locked keychain; secret reads and writes exit 36.
+#
+# Items live as $FAKE_KEYCHAIN_DIR/<service>/<account>/{secret,mdat,seq}: `seq` is the
+# creation order, `mdat` the 14-digit UTC modification stamp — recorded at write time
+# (FAKE_KEYCHAIN_MDAT overrides it) rather than derived from a file mtime, because
+# `stat`/`date` flags differ between BSD and GNU and this fake must behave identically
+# on a developer's Mac and on Linux CI. FAKE_KEYCHAIN_LOCKED=1 simulates a session that
+# cannot open the keychain (ssh/tmux/background). FAKE_SECURITY_LOG=<file> appends one
+# line per call — verb, -a name ("-" without -a), whether the secret was asked for —
+# so a test can count calls; the secret and the -X payload are never logged.
+KC="${FAKE_KEYCHAIN_DIR:-/nonexistent-keychain}"
+cmd="${1:-}"; shift || true
+svc=""; acct=""; have_acct=0; want_pw=0; update=0; hexdata=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -s) svc="${2:-}"; shift 2 ;;
+    -a) acct="${2:-}"; have_acct=1; shift 2 ;;
+    -w) want_pw=1; shift ;;
+    -U) update=1; shift ;;
+    -X) hexdata="${2:-}"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+[ -n "${FAKE_SECURITY_LOG:-}" ] && printf '%s a=%s w=%s\n' "$cmd" \
+  "$([ "$have_acct" = "1" ] && printf '%s' "$acct" || printf -- '-')" "$want_pw" >> "$FAKE_SECURITY_LOG"
+locked() { [ -n "${FAKE_KEYCHAIN_LOCKED:-}" ]; }
+item_dir() { # the item a lookup names: -a picks its own, no -a picks the oldest
+  local d best="" bestseq="" s
+  if [ "$have_acct" = "1" ]; then
+    [ -n "$acct" ] && [ -d "$KC/$svc/$acct" ] && { printf '%s\n' "$KC/$svc/$acct"; return 0; }
+    return 1
+  fi
+  for d in "$KC/$svc"/*/; do
+    [ -d "$d" ] || continue
+    s="$(cat "$d/seq" 2>/dev/null || echo 0)"
+    if [ -z "$bestseq" ] || [ "$s" -lt "$bestseq" ]; then best="${d%/}"; bestseq="$s"; fi
+  done
+  [ -n "$best" ] && { printf '%s\n' "$best"; return 0; }
+  return 1
+}
+case "$cmd" in
+  show-keychain-info)
+    locked && exit 36
+    exit 0 ;;
+  find-generic-password)
+    it="$(item_dir)" || exit 44
+    if [ "$want_pw" = "1" ]; then
+      locked && exit 36
+      cat "$it/secret"; echo
+      exit 0
+    fi
+    printf 'keychain: "login.keychain-db"\nclass: "genp"\nattributes:\n'
+    printf '    "acct"<blob>="%s"\n' "$(basename "$it")"
+    printf '    "mdat"<timedate>=0x00  "%sZ\\000"\n' "$(cat "$it/mdat" 2>/dev/null || echo 00000000000000)"
+    printf '    "svce"<blob>="%s"\n' "$svc"
+    exit 0 ;;
+  add-generic-password)
+    locked && exit 36
+    [ "$have_acct" = "1" ] && [ -n "$acct" ] && [ -n "$svc" ] || exit 2
+    it="$KC/$svc/$acct"
+    if [ -d "$it" ]; then
+      [ "$update" = "1" ] || exit 45
+    else
+      mkdir -p "$it" || exit 1
+      n="$(cat "$KC/.seq" 2>/dev/null || echo 0)"; n=$((n + 1))
+      printf '%s\n' "$n" > "$KC/.seq"
+      printf '%s\n' "$n" > "$it/seq"
+    fi
+    printf '%s' "$hexdata" | python3 -c 'import sys;sys.stdout.buffer.write(bytes.fromhex(sys.stdin.read().strip()))' > "$it/secret"
+    printf '%s\n' "${FAKE_KEYCHAIN_MDAT:-$(date -u +%Y%m%d%H%M%S)}" > "$it/mdat"
+    exit 0 ;;
+  delete-generic-password)
+    locked && exit 36
+    it="$(item_dir)" || exit 44
+    rm -rf "$it"
+    rmdir "$KC/$svc" 2>/dev/null
+    exit 0 ;;
+  *) exit 1 ;;
+esac