claude-multiacc 2.0.3 → 2.0.4

package/bin/claude-accounts

@@ -28,7 +28,8 @@ USAGE
       login-FIRST: runs the full Claude Code login (`claude auth login` — the normal
       browser sign-in, no long-lived-token step-up), then registers only after the
       signed-in email is read back. Email is OPTIONAL (derived from the sign-in).
-      Stores auto-refreshing .credentials.json valid on THIS machine. Duplicates refused.
+      Stores an auto-refreshing login valid on THIS machine (.credentials.json, or
+      the macOS Keychain when the session can open it). Duplicates refused.
       --token instead mints a portable setup-token (works on Mac AND server; needs a
       recent sign-in — use it when you want the account usable on the server too).
   claude-accounts login <acct-NN> [--token] [--force]
@@ -215,12 +216,14 @@ if not accounts:
 for a in accounts:
     d = os.path.join(root, a['id'])
     auth = []
-    if os.path.isfile(os.path.join(d, '.credentials.json')):
+    st = audit_account(root, a, machine=machine)
+    if st.get('store') == 'file':
         auth.append('oauth')
+    elif st.get('store') == 'keychain':
+        auth.append('keychain' if st['state'] != 'locked' else 'keychain(locked)')
     if os.path.getsize(os.path.join(d, 'server.token')) > 0 if os.path.isfile(os.path.join(d, 'server.token')) else False:
         auth.append('token')
     limited = os.path.isfile(os.path.join(d, '.limited'))
-    st = audit_account(root, a, machine=machine)
     flags = []
     if st['state'] == 'expired':
         flags.append('EXPIRED-LOGIN')
@@ -228,6 +231,8 @@ for a in accounts:
         flags.append('ORG-BLOCKED')
     elif st['state'] == 'missing':
         flags.append('NO-LOGIN')
+    elif st['state'] == 'locked':
+        flags.append('KEYCHAIN-LOCKED-HERE')
     if limited:
         flags.append('LIMITED')
     print(f"{a['id']}  {a['email']:<28} home={a.get('home','?'):<7} "
@@ -264,7 +269,7 @@ import json, os, sys, time
 doc = json.load(open(sys.argv[1]))
 root = sys.argv[2]
 sys.path = [sys.argv[3]] + [p for p in sys.path if p not in ('', '.')]
-from audit import audit_account   # noqa: E402  (shared with the shim's rule)
+from audit import audit_account, oauth_login   # noqa: E402  (shared with the shim's rule)
 machine = sys.argv[4]
 now = time.time()
 # Must match the shim's window (bin/claude), or status would call data "fresh" that
@@ -320,20 +325,25 @@ for a in doc.get('accounts', []):
               'missing': '  ** NO LOGIN — claude-accounts relogin %s **' % aid,
               'expired': '  ** LOGIN EXPIRED — claude-accounts relogin %s **' % aid,
               'blocked': '  ** ORG BLOCKED — Claude Code disabled for this account **',
+              'locked': '  [login is in the macOS Keychain — locked for THIS session, fine from the Mac itself]',
               }[st['state']]
     print(f"{aid}  {a['email']}  [home={a.get('home','?')}]{banner}")
     print(f"  selectable  : {'yes' if st['state'] == 'ok' else 'NO — ' + st['reason']}")
     cpath = os.path.join(d, '.credentials.json')
-    if os.path.isfile(cpath):
+    login = oauth_login(d, now)
+    if login['store'] == 'file' or login['doc'] is not None:
         try:
-            c = json.load(open(cpath)).get('claudeAiOauth', {})
+            c = (login['doc'] or json.load(open(cpath))).get('claudeAiOauth', {})
             exp = c.get('expiresAt', 0) / 1000.0
             rexp = c.get('refreshTokenExpiresAt', 0) / 1000.0
             state = 'fresh' if exp > now else 'stale (auto-refreshes on use)'
             rstate = 'ok' if rexp > now else 'EXPIRED — re-login needed'
-            print(f"  oauth creds : {state}; refresh token {rstate} (until {time.strftime('%Y-%m-%d', time.gmtime(rexp)) if rexp else '?'})")
+            where = 'macOS Keychain' if login['store'] == 'keychain' else '.credentials.json'
+            print(f"  oauth creds : {state}; refresh token {rstate} (until {time.strftime('%Y-%m-%d', time.gmtime(rexp)) if rexp else '?'}) [{where}]")
         except Exception as e:
             print(f"  oauth creds : unreadable ({e})")
+    elif login['store'] == 'keychain':
+        print(f"  oauth creds : in the macOS Keychain — {login['reason']}")
     else:
         print("  oauth creds : none on this machine")
     tpath = os.path.join(d, 'server.token')
@@ -499,7 +509,8 @@ cmd_add() {
     got="$(token_email "$CEREMONY_TOKEN")"
   else
     # Default: full Claude Code login (full scopes, no long-lived-token step-up).
-    # Writes auto-refreshing .credentials.json, valid on THIS machine.
+    # Leaves an auto-refreshing login valid on THIS machine — .credentials.json, or
+    # the macOS Keychain when this session can open it (see lib/keychain.py).
     echo "Preparing $id for $elabel — NOTHING is registered until login completes."
     run_login_ceremony "$d" "$email" || die "login failed or aborted — nothing was created"
     got="$(config_dir_email "$d")"
@@ -627,16 +638,25 @@ cmd_import() {
 # then the lowest id) and list the rest. Empty output => pool is already clean.
 dup_ids_to_remove() {
   [ -f "$MANIFEST" ] || return 0
-  "$PYBIN" - "$MANIFEST" "$ACC_ROOT" <<'PYEOF' 2>/dev/null
+  "$PYBIN" - "$MANIFEST" "$ACC_ROOT" "$LIB_DIR" <<'PYEOF' 2>/dev/null
 import json, os, re, sys
 manifest, root = sys.argv[1], sys.argv[2]
+sys.path = [sys.argv[3]] + [p for p in sys.path if p not in ('', '.')]
+import keychain  # noqa: E402  (macOS Keychain-held logins; a no-op elsewhere)
 accts = [a for a in json.load(open(manifest)).get('accounts', [])
          if isinstance(a, dict) and re.fullmatch(r'acct-\d{2}', str(a.get('id', '')))]
 def has_auth(aid):
     d = os.path.join(root, aid)
     c = os.path.join(d, '.credentials.json')
     t = os.path.join(d, 'server.token')
-    return (os.path.isfile(c) and os.path.getsize(c) > 0) or (os.path.isfile(t) and os.path.getsize(t) > 0)
+    if (os.path.isfile(c) and os.path.getsize(c) > 0) or (os.path.isfile(t) and os.path.getsize(t) > 0):
+        return True
+    # A login the client moved into the macOS Keychain still counts — deduping must
+    # not throw away the one duplicate that actually holds the grant.
+    try:
+        return keychain.probe(d)['state'] in ('present', 'locked', 'corrupt')
+    except Exception:
+        return False
 by_email = {}
 for a in accts:
     by_email.setdefault(a.get('email', '').lower(), []).append(a['id'])
@@ -678,7 +698,13 @@ PYEOF
     case "$ans" in y|Y|yes) ;; *) echo "aborted"; return 1 ;; esac
   fi
   for id in $dups; do
-    if [ -L "$ACC_ROOT/$id" ]; then rm -f "${ACC_ROOT:?}/${id:?}"; else rm -rf "${ACC_ROOT:?}/${id:?}"; fi
+    if [ -L "$ACC_ROOT/$id" ]; then
+      rm -f "${ACC_ROOT:?}/${id:?}"
+    else
+      # Same rule as cmd_remove: a removed dir's Keychain login must go with it.
+      keychain_forget "$ACC_ROOT/$id"
+      rm -rf "${ACC_ROOT:?}/${id:?}"
+    fi
     manifest_del_account "$id"
     log_to ops.log "dedupe removed $id"
   done
@@ -738,6 +764,10 @@ cmd_remove() {
   if [ -L "$ACC_ROOT/$id" ]; then
     rm -f "${ACC_ROOT:?}/${id:?}"   # adopted account: remove the symlink, never the target
   else
+    # The client may hold this dir's login in the macOS Keychain (keyed by the dir
+    # path): drop it with the dir, or a removed account leaves a live grant behind
+    # that the next account to reuse this id would silently inherit.
+    keychain_forget "$ACC_ROOT/$id"
     rm -rf "${ACC_ROOT:?}/${id:?}"
   fi
   manifest_del_account "$id"
@@ -847,8 +877,10 @@ except Exception:
 
 # Full subscription login: `claude auth login --claudeai`, the SAME flow the
 # interactive app uses (claude.com/cai/oauth/authorize, full Claude Code scopes,
-# normal sign-in — no long-lived-token step-up wall). Writes <dir>/.credentials.json
-# (auto-refreshing). Returns success iff the credential landed. $2 = optional email hint.
+# normal sign-in — no long-lived-token step-up wall). Leaves an auto-refreshing login
+# in <dir>/.credentials.json — or, on macOS from a session that can open the login
+# Keychain, in a Keychain item (lib/keychain.py). Returns success iff a credential
+# that can authenticate landed in either place. $2 = optional email hint.
 run_login_ceremony() { # $1 = config dir, $2 = email hint
   local d="$1" hint="${2:-}" real
   real="$(find_real_claude "$_self")" || { warn "real claude binary not found"; return 1; }
@@ -859,19 +891,21 @@ paste it after the "Paste code here" prompt and press Enter. This is the normal
 login — it draws on the subscription, no API keys, and refreshes itself over time.
 TIP
   # Run claude auth login DIRECTLY on the user's terminal (no `script` PTY wrapper):
-  # we capture nothing here (the credential is written to .credentials.json), and a
-  # PTY layer can suppress the echo of the pasted code. Direct invocation behaves
+  # we capture nothing here (the client stores the credential itself), and a PTY
+  # layer can suppress the echo of the pasted code. Direct invocation behaves
   # exactly like running `claude auth login` yourself, so the code you paste is shown.
   if [ -n "$hint" ]; then
     CLAUDE_CONFIG_DIR="$d" CLAUDE_SHIM_ACTIVE=1 "$real" auth login --claudeai --email "$hint" || true
   else
     CLAUDE_CONFIG_DIR="$d" CLAUDE_SHIM_ACTIVE=1 "$real" auth login --claudeai || true
   fi
-  # Success is a credential that can AUTHENTICATE — not merely a file that exists.
-  # Re-login targets already have a (dead) .credentials.json on disk, so a bare
-  # existence test would call an aborted sign-in a success, clear the dead-auth
-  # marker, and hand the account straight back to the pool.
-  [ -f "$d/.credentials.json" ] || return 1
+  # Success is a credential that can AUTHENTICATE — not merely one that exists.
+  # Re-login targets already have a (dead) credential in place, so a bare existence
+  # test would call an aborted sign-in a success, clear the dead-auth marker, and
+  # hand the account straight back to the pool. creds_alive looks in both places
+  # the client writes to (.credentials.json, macOS Keychain): demanding the FILE
+  # here turned every Keychain-backed sign-in into "login failed", deleted the
+  # reserved dir, and left the fresh grant orphaned in the Keychain.
   creds_alive "$d"
 }
 
@@ -930,8 +964,8 @@ cmd_mint() {
 
 cmd_login() {
   # Complete (or refresh) auth for an EXISTING account. Default: full Claude Code login
-  # (auto-refreshing .credentials.json, this machine). --token: portable setup-token
-  # (Mac + server). Verifies the signed-in email matches the manifest.
+  # (auto-refreshing, this machine — .credentials.json or the macOS Keychain). --token:
+  # portable setup-token (Mac + server). Verifies the signed-in email matches the manifest.
   require_manifest
   local id="" force=0 token=0
   while [ $# -gt 0 ]; do
@@ -971,7 +1005,11 @@ cmd_login() {
       die "signed in, but the account identity could not be read back — refusing to call $id fixed (retry, or pass --force)"
     fi
     clear_auth_markers "$d"
-    echo "$id login saved (.credentials.json, this machine, auto-refreshing)."
+    if [ -s "$d/.credentials.json" ]; then
+      echo "$id login saved (.credentials.json, this machine, auto-refreshing)."
+    else
+      echo "$id login saved (macOS Keychain, this machine, auto-refreshing — sessions without keychain access, e.g. ssh, cannot use it)."
+    fi
   fi
   log_to ops.log "login $id verified=${got:-unverified} mode=$([ "$token" = 1 ] && echo token || echo login)"
   auto_sync
@@ -1231,8 +1269,10 @@ cmd_limits() {
   case "$threshold" in ''|*[!0-9]*) threshold=90 ;; esac
   [ "$threshold" -gt 90 ] && threshold=90
   [ "$threshold" -lt 1 ] && threshold=90
-  "$PYBIN" - "$ACC_ROOT" "$threshold" "$quiet" "$USAGE_URL" "$force" <<'PYEOF' 2>>"$ACC_ROOT/limits.log"
+  "$PYBIN" - "$ACC_ROOT" "$threshold" "$quiet" "$USAGE_URL" "$force" "$LIB_DIR" <<'PYEOF' 2>>"$ACC_ROOT/limits.log"
 import hashlib, json, os, sys, time, urllib.request
+sys.path = [sys.argv[6]] + [p for p in sys.path if p not in ('', '.')]
+import keychain  # noqa: E402  (macOS Keychain-held logins; a no-op elsewhere)
 
 root, threshold, quiet, url, force = sys.argv[1], int(sys.argv[2]), sys.argv[3] == '1', sys.argv[4], sys.argv[5] == '1'
 now = time.time()
@@ -1354,15 +1394,72 @@ def park_dead_grant(aid, d, slug, detail):
     say(f'{aid}: {detail} — re-login needed (claude-accounts relogin {aid})')
 
 
-def refresh_oauth(aid, d, cpath):
+class FileStore:
+    """The OAuth credential as `.credentials.json`: atomic 0600 writes."""
+    kind = 'file'
+
+    def __init__(self, path):
+        self.path = path
+
+    def read(self):
+        return json.load(open(self.path))
+
+    def write(self, doc):
+        fd = os.open(self.path + '.tmp', os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, 'w') as f:
+            json.dump(doc, f)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(self.path + '.tmp', self.path)
+
+
+class KeychainStore:
+    """The same credential, held in the macOS Keychain by the client itself (see
+    lib/keychain.py). Read and written in place — NEVER copied out to a file: a file
+    beside a Keychain item is a second copy of a ROTATING refresh grant, and the
+    client reads the Keychain first, so the two would drift apart and strand one."""
+    kind = 'keychain'
+
+    def __init__(self, d, probe):
+        self.d = d
+        self.account = probe.get('account')
+
+    def read(self):
+        p = keychain.probe(self.d)
+        if p['state'] != 'present':
+            raise ValueError(f'keychain credential {p["state"]}')
+        return p['doc']
+
+    def write(self, doc):
+        if not keychain.write(self.d, doc, account=self.account):
+            raise OSError('keychain write refused')
+
+
+def oauth_store(d):
+    """Where <d>'s OAuth login lives for THIS process: a FileStore, a KeychainStore,
+    the string 'locked' (Keychain item exists but this session cannot open it), or
+    None. The file wins when both exist — same rule as lib/audit.oauth_login."""
+    cpath = os.path.join(d, '.credentials.json')
+    if os.path.isfile(cpath):
+        return FileStore(cpath)
+    p = keychain.probe(d)
+    if p['state'] == 'present':
+        return KeychainStore(d, p)
+    if p['state'] == 'locked':
+        return 'locked'
+    return None
+
+
+def refresh_oauth(aid, d, store):
     """Refresh a long-expired OAuth access token via the refresh-token grant and
-    persist the ROTATED credential atomically (0600). Returns the new bearer, or
-    None (fail open: the on-disk credential is never touched on failure).
-    Failures back off via <dir>/.oauth-refresh.json — a side file, NOT limits.json,
-    because telemetry state must only ever reflect real usage fetches."""
+    persist the ROTATED credential atomically (0600 file, or the Keychain item it
+    came from). Returns the new bearer, or None (fail open: the stored credential
+    is never touched on failure). Failures back off via <dir>/.oauth-refresh.json —
+    a side file, NOT limits.json, because telemetry state must only ever reflect
+    real usage fetches."""
     spath = os.path.join(d, '.oauth-refresh.json')
     try:
-        doc = json.load(open(cpath))
+        doc = store.read()
         o = doc.get('claudeAiOauth', {})
         # Present-but-null/non-object claudeAiOauth (interrupted or reset credential
         # write) must degrade THIS account only, like every other malformed input.
@@ -1472,21 +1569,15 @@ def refresh_oauth(aid, d, cpath):
     # on-disk refresh token is no longer the one this grant was issued against, the
     # other writer won: keep its result, discard ours.
     try:
-        with open(cpath) as f:
-            disk = json.load(f).get('claudeAiOauth', {})
+        disk = store.read().get('claudeAiOauth', {})
         if isinstance(disk, dict) and disk.get('refreshToken') != started_with:
             say(f'{aid}: credential was refreshed by something else mid-flight — '
-                f'keeping the newer one on disk')
+                f'keeping the newer one in the {store.kind}')
             return None
     except Exception:
         pass
     try:
-        fd = os.open(cpath + '.tmp', os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-        with os.fdopen(fd, 'w') as f:
-            json.dump(doc, f)
-            f.flush()
-            os.fsync(f.fileno())
-        os.replace(cpath + '.tmp', cpath)
+        store.write(doc)
     except Exception as e:
         say(f'{aid}: token refreshed but credentials NOT persisted ({e}) — re-login may be needed')
         return None
@@ -1552,20 +1643,30 @@ for acct in manifest.get('accounts', []):
     # it. OAuth first, refresh second, token only as a genuine last resort.
     bearer = None
     source = None
-    cpath = os.path.join(d, '.credentials.json')
     tpath = os.path.join(d, 'server.token')
-    if os.path.isfile(cpath):
+    # The login may sit in .credentials.json or in the macOS Keychain (the client
+    # moves it there from any session that can open the keychain — a launchd agent
+    # like the one running this probe can, an ssh session cannot).
+    try:
+        store = oauth_store(d)
+    except Exception as e:
+        say(f'{aid}: could not locate the oauth credential ({str(e)[:120]}); failing open')
+        store = None
+    locked = store == 'locked'
+    if locked:
+        store = None
+    if store is not None:
         try:
-            c = json.load(open(cpath)).get('claudeAiOauth', {})
+            c = store.read().get('claudeAiOauth', {})
             if c.get('accessToken') and c.get('expiresAt', 0) / 1000.0 > now + 60:
                 bearer, source = c['accessToken'], 'oauth'
         except Exception:
             pass
-    if not bearer and os.path.isfile(cpath):
+    if not bearer and store is not None:
         # Hard fail-open guard: NOTHING a single account's refresh does may abort
         # the loop — every account after it would silently starve of telemetry.
         try:
-            tok = refresh_oauth(aid, d, cpath)
+            tok = refresh_oauth(aid, d, store)
         except Exception as e:
             say(f'{aid}: oauth refresh failed unexpectedly ({str(e)[:200]}); failing open')
             tok = None
@@ -1592,7 +1693,12 @@ for acct in manifest.get('accounts', []):
             bearer, source = t, 'token'
     if not bearer:
         # Fail OPEN: no usable bearer => leave existing state; never block work on telemetry.
-        say(f'{aid}: no fresh bearer (expired oauth and/or no token); limits left as-is')
+        if locked:
+            say(f'{aid}: oauth login is in the macOS Keychain, which this session cannot '
+                f'open (ssh/background) — its telemetry comes from the Mac\'s own launchd '
+                f'probe; limits left as-is')
+        else:
+            say(f'{aid}: no fresh bearer (expired oauth and/or no token); limits left as-is')
         continue
 
     req = urllib.request.Request(url, headers={
@@ -1870,7 +1976,8 @@ import json, os, re, subprocess, sys, time
 
 root, quick, real = sys.argv[1], sys.argv[2] == '1', sys.argv[3]
 sys.path = [sys.argv[4]] + [p for p in sys.path if p not in ('', '.')]
-from audit import audit_account, creds_state   # noqa: E402  (shared with the shim's rule)
+from audit import audit_account, creds_state, creds_doc_state   # noqa: E402  (shared with the shim's rule)
+import keychain  # noqa: E402
 machine = sys.argv[5]
 now = time.time()
 manifest = json.load(open(os.path.join(root, 'accounts.json')))
@@ -1914,13 +2021,28 @@ for acct in manifest.get('accounts', []):
     tpath = os.path.join(d, 'server.token')
     has_creds = os.path.isfile(cpath)
     has_token = os.path.isfile(tpath) and os.path.getsize(tpath) > 0
+    cred_doc = None
+    cred_state = None
+    if not has_creds:
+        # The login may be in the macOS Keychain (lib/keychain.py). A Keychain this
+        # session cannot open is not a failure of the ACCOUNT: the real call below
+        # would fail for the session, not the grant, so it is a skip with a reason.
+        kc = keychain.probe(d)
+        if kc['state'] == 'present':
+            has_creds, cred_doc = True, kc['doc']
+        elif kc['state'] == 'locked' and not has_token:
+            print(f'{aid} {acct["email"]}: SKIP (login is in the macOS Keychain, locked '
+                  f'for this session — run verify from the Mac\'s own session)')
+            continue
     if not has_creds and not has_token:
         print(f'{aid} {acct["email"]}: SKIP (no auth on this machine)')
         continue
     tested += 1
     if has_creds:
         try:
-            c = json.load(open(cpath)).get('claudeAiOauth', {})
+            c = (cred_doc or json.load(open(cpath))).get('claudeAiOauth', {})
+            cred_state = creds_doc_state(cred_doc, now)[0] if cred_doc is not None \
+                else creds_state(cpath, now)[0]
             rexp = c.get('refreshTokenExpiresAt', 0) / 1000.0
             if rexp and rexp < now and not has_token:
                 mark_expired(d, 'refresh-token-expired',
@@ -1954,7 +2076,7 @@ for acct in manifest.get('accounts', []):
     # Mirror the shim's acct_token(): a portable token is what actually authenticates
     # whenever there is no credential OR the credential beside it is dead. Testing such
     # an account with the dead credential would fail it — and park a healthy account.
-    if has_token and (not has_creds or creds_state(cpath, now)[0] != 'ok'):
+    if has_token and (not has_creds or cred_state != 'ok'):
         env['CLAUDE_CODE_OAUTH_TOKEN'] = open(tpath).read().strip()
     t0 = time.time()
     try:
@@ -2208,23 +2330,27 @@ cmd_post_sync() {
 
 # Version of the copy at $1, read from its package.json on disk — the only answer
 # that describes what will actually execute.
-pkg_version_at() {
-  [ -f "$1/package.json" ] || return 0
-  sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1/package.json" | head -1
-}
-
 cmd_self_update() {
   # Update the addon in place. npm global install => npm i -g @latest (its postinstall
   # re-runs install.sh). git checkout => git pull + ./install.sh. Anything else is a
   # no-op with a hint. Best-effort and fully logged; never disrupts a running claude.
   local quiet=0
   [ "${1:-}" = "--quiet" ] && quiet=1
+  # The update log is appended to with a plain redirect below, so the pool root has to
+  # exist: on a machine where this provider's pool was never initialised the redirect
+  # itself failed, and the update was reported as "npm update FAILED" with nothing in
+  # the log to say why.
+  mkdir -p "$ACC_ROOT" 2>/dev/null || true
   rotate_log update.log
   ulog() { log_to update.log "$*"; [ "$quiet" = "1" ] || echo "$*"; }
   case "$REPO_DIR" in
     */node_modules/claude-multiacc|*/node_modules/claude-multiacc/*)
-      command -v npm >/dev/null 2>&1 || { ulog "self-update: npm not found; skipping"; return 0; }
-      local cur lat prefix after
+      local cur lat prefix after npm_bin
+      prefix="${REPO_DIR%/lib/node_modules/*}"
+      npm_bin="$(find_npm "$prefix")" || {
+        ulog "self-update: no npm found (looked in $prefix/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin, PATH); skipping"
+        return 0
+      }
       # Update THE COPY THAT IS RUNNING, not whichever one the ambient npm prefix
       # happens to point at. my-mini had two global installs — homebrew's on PATH and
       # nvm's under `npm root -g` — and self-update kept upgrading the nvm one and
@@ -2232,15 +2358,14 @@ cmd_self_update() {
       # It sat eleven versions behind for weeks and said "already latest" throughout.
       # A deploy nobody runs is not a deploy, and one that announces success is worse
       # than one that fails.
-      prefix="${REPO_DIR%/lib/node_modules/claude-multiacc*}"
       cur="$(pkg_version_at "$REPO_DIR")"
-      lat="$(npm view claude-multiacc version 2>/dev/null)"
+      lat="$("$npm_bin" view claude-multiacc version 2>/dev/null)"
       if [ -n "$lat" ] && [ "$cur" = "$lat" ]; then
         ulog "self-update: already latest ($cur)"
         return 0
       fi
-      ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix)"
-      if npm install -g --prefix "$prefix" claude-multiacc@latest \
+      ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix, npm $npm_bin)"
+      if "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
            >>"$ACC_ROOT/update.log" 2>&1; then
         # Verify by re-reading the file on disk. npm reporting success says nothing
         # about which tree it wrote to.

package/bin/codex-accounts

@@ -1882,21 +1882,38 @@ cmd_self_update() {
   # no-op with a hint. Best-effort and fully logged; never disrupts a running codex.
   local quiet=0
   [ "${1:-}" = "--quiet" ] && quiet=1
+  # The update log is appended to with a plain redirect below, so the pool root has to
+  # exist: on a machine where this provider's pool was never initialised the redirect
+  # itself failed, and the update was reported as "npm update FAILED" with nothing in
+  # the log to say why.
+  mkdir -p "$ACC_ROOT" 2>/dev/null || true
   rotate_log update.log
   ulog() { log_to update.log "$*"; [ "$quiet" = "1" ] || echo "$*"; }
   case "$REPO_DIR" in
     */node_modules/claude-multiacc|*/node_modules/claude-multiacc/*)
-      command -v npm >/dev/null 2>&1 || { ulog "self-update: npm not found; skipping"; return 0; }
-      local cur lat
-      cur="$(npm ls -g --depth=0 claude-multiacc 2>/dev/null | sed -n 's/.*claude-multiacc@//p' | head -1)"
-      lat="$(npm view claude-multiacc version 2>/dev/null)"
+      local cur lat prefix npm_bin after
+      # Same resolution and same prefix discipline as claude-accounts: a launchd/cron
+      # PATH has no npm, and the npm that must run is the one owning the RUNNING copy.
+      prefix="${REPO_DIR%/lib/node_modules/*}"
+      npm_bin="$(find_npm "$prefix")" || {
+        ulog "self-update: no npm found (looked in $prefix/bin, /opt/homebrew/bin, /usr/local/bin, /usr/bin, PATH); skipping"
+        return 0
+      }
+      cur="$(pkg_version_at "$REPO_DIR")"
+      lat="$("$npm_bin" view claude-multiacc version 2>/dev/null)"
       if [ -n "$lat" ] && [ "$cur" = "$lat" ]; then
         ulog "self-update: already latest ($cur)"
         return 0
       fi
-      ulog "self-update: npm $cur -> ${lat:-latest}"
-      if npm install -g claude-multiacc@latest >>"$ACC_ROOT/update.log" 2>&1; then
-        ulog "self-update: npm update ok"
+      ulog "self-update: npm $cur -> ${lat:-latest} (prefix $prefix, npm $npm_bin)"
+      if "$npm_bin" install -g --prefix "$prefix" claude-multiacc@latest \
+           >>"$ACC_ROOT/update.log" 2>&1; then
+        after="$(pkg_version_at "$REPO_DIR")"
+        if [ -n "$lat" ] && [ "$after" != "$lat" ]; then
+          ulog "self-update: npm reported success but $REPO_DIR is still $after, not $lat — this install is NOT being updated"
+          return 1
+        fi
+        ulog "self-update: npm update ok ($after)"
       else
         ulog "self-update: npm update FAILED (see update.log)"
         return 1

package/docs/ACCOUNT_OPERATIONS.md

@@ -69,7 +69,11 @@ subscription — never API keys.
 
 Using the full login on purpose: it does **not** hit the *"Sign in again to continue"*
 step-up wall that the narrow long-lived-token grant triggers, and it stores an
-auto-refreshing `.credentials.json`. That credential is **machine-local** (never synced),
+auto-refreshing login — `.credentials.json`, or on macOS the login Keychain whenever
+the session can open it (Claude Code migrates the file into the Keychain on the first
+refresh from a keychain-capable session; ssh sessions then see the account as
+`KEYCHAIN LOCKED` and cannot run it, while the Mac's own session uses it normally).
+That credential is **machine-local** (never synced),
 which is what keeps two machines from invalidating each other's refresh token — so an
 account you `add` on the Mac runs on the Mac, and you `add` it on the server (over SSH) if
 you want it there too. The account is registered **only after the signed-in email is read
@@ -244,7 +248,7 @@ whose reset time has passed does not count, an unreadable one does.
 | Credential | Where it lives | Class | Can it be copied to another machine? |
 | --- | --- | --- | --- |
 | claude setup-token | `<acct>/server.token` | **portable** | **Yes**; the fleet-distributed credential |
-| claude OAuth login | `<acct>/.credentials.json` | machine-local | **No**; refresh tokens rotate |
+| claude OAuth login | `<acct>/.credentials.json`, or a macOS Keychain item | machine-local | **No**; refresh tokens rotate |
 | codex ChatGPT login | `<acct>/auth.json` | machine-local | **No**; Codex has no portable credential |
 
 Non-portable accounts are not a dead end: they show up as `credential_class:

package/install.sh

@@ -103,13 +103,23 @@ PLIST_CODEX_LIMITS="$HOME/Library/LaunchAgents/$LABEL.codex-limits.plist"
 PLIST_CODEX_HEALTH="$HOME/Library/LaunchAgents/$LABEL.codex-health.plist"
 PROFILED="/etc/profile.d/claude-multiacc.sh"
 
-# Pool roots (and any sync override) for a scheduled agent, so it refreshes THIS
-# instance's pool. Empty for a default install — nothing changes there.
+# Environment for a scheduled agent: a usable PATH always, plus this instance's pool
+# roots when the install is instance-scoped.
+#
+# launchd hands an agent PATH=/usr/bin:/bin:/usr/sbin:/sbin — no /opt/homebrew, no
+# nvm — so `npm`, `node` and a homebrew `git` are all absent from a plain agent run.
+# The daily self-update agent logged "npm not found; skipping" every night for days
+# while reporting nothing wrong, and every Mac's npm copy silently froze. The code
+# now resolves npm by absolute path too (lib/common.sh find_npm), but an agent whose
+# environment cannot even find node is a trap waiting for the next tool we add.
 plist_env_block() {
-  [ -n "$INSTANCE" ] || return 0
   printf '  <key>EnvironmentVariables</key><dict>\n'
-  printf '    <key>CLAUDE_ACCOUNTS_ROOT</key><string>%s</string>\n' "$ACC_ROOT"
-  printf '    <key>CODEX_ACCOUNTS_ROOT</key><string>%s</string>\n' "$CODEX_ACC_ROOT"
+  printf '    <key>PATH</key><string>%s</string>\n' \
+    "/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+  if [ -n "$INSTANCE" ]; then
+    printf '    <key>CLAUDE_ACCOUNTS_ROOT</key><string>%s</string>\n' "$ACC_ROOT"
+    printf '    <key>CODEX_ACCOUNTS_ROOT</key><string>%s</string>\n' "$CODEX_ACC_ROOT"
+  fi
   printf '  </dict>\n'
 }
 cron_env_prefix() {
@@ -380,11 +390,17 @@ do_install() {
     echo "  note: no codex binary found — the codex pool stays idle until Codex CLI is installed (npm i -g @openai/codex)"
   fi
 
-  # Keychain-mode detection: per-dir /login isolation needs file-based credentials.
+  # Keychain-mode note: Claude Code keeps per-config-dir logins in the login Keychain
+  # (one item per dir) whenever the session can open it, and only sessions without
+  # keychain access (ssh, launchd background jobs) fall back to .credentials.json. The
+  # pool reads both (lib/keychain.py); what an operator has to know is that a login
+  # made from a GUI session is invisible to their ssh sessions — mint a portable
+  # token for anything that must work from everywhere.
   if [ "$kind" = "mac" ] && [ ! -f "$HOME/.claude/.credentials.json" ] \
     && security find-generic-password -s "Claude Code-credentials" >/dev/null 2>&1; then
-    echo "  WARNING: this Mac stores Claude Code credentials in the Keychain, not files." >&2
-    echo "  Per-directory logins may not isolate; use token-based accounts (claude-accounts mint/import --token-file)." >&2
+    echo "  note: this Mac keeps Claude Code logins in the Keychain. Per-dir logins made here"
+    echo "  are read from it; ssh/background sessions cannot open it (they see 'locked') —"
+    echo "  use 'claude-accounts mint <acct-NN>' for accounts that must work from everywhere."
   fi
 
   manifest_init "${SERVER_OVERRIDE:-$DEFAULT_SERVER}"