claude-multiacc 2.0.32 → 2.0.34

package/README.md

@@ -59,7 +59,7 @@ MAC (source of truth)                      SERVER (mirror)
     server.token / .credentials.json
     (or the login lives in the macOS Keychain — see below)
   selection.log  sync.log  health.log      /usr/local/bin/claude -> repo shim
-repo bin/ first on PATH (rc-file block)    /root/claude-multiacc/  (addon repo)
+repo bin/ first on PATH (rc block + hook)  /root/claude-multiacc/  (addon repo)
 ```
 
 **Shim selection order** (identical file on both machines, `bin/claude`):
@@ -380,6 +380,16 @@ into its global bin directory, so account commands work in the current shell. Op
 new shell for the `claude` and `codex` shims. If auto-setup was skipped, run
 `claude-multiacc install` to initialize the pools and shell setup.
 
+The shims shadow the real binaries by PATH order alone, so the installer's rc block
+(`~/.zshenv`, `~/.zprofile`, `~/.zshrc`, `~/.profile` and the bash rc files when they
+exist) ends with a prompt hook that puts the shim dir back in front before every
+prompt: an rc file interrupted with Ctrl-C, or a tool that rewrites PATH, can no
+longer leave `~/.local/bin/claude` first — that launch would run on the machine's own
+`~/.claude` login and never reach the pool. `claude-accounts status` probes fresh
+`zsh`/`bash`/`sh` login shells with your rc files and prints `BYPASSED -> <path>` for
+any that still resolve something other than the shim; the weekly `health` check fails
+on it.
+
 See [installation, updates, removal, and command-not-found recovery](docs/INSTALLATION.md)
 for npm, npx, git checkout, and server instructions.
 

package/bin/claude-accounts

@@ -23,7 +23,8 @@ claude-accounts — multi-account pool manager for claude-multiacc
 
 USAGE
   claude-accounts list [--json]             brief account list (--json: machine-readable)
-  claude-accounts status [--json]           full health: auth, per-bucket limits, markers
+  claude-accounts status [--json]           full health: auth, per-bucket limits, markers,
+                                            and whether fresh login shells reach the shim
   claude-accounts add [email] [--token] [--force]
       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
@@ -85,7 +86,7 @@ USAGE
       persisted), so idle accounts keep fresh telemetry and stay selectable.
       Skips accounts fetched in the last 45s and honors 429/refresh backoff;
       --force ignores all three.
-  claude-accounts health                    limits + full verify; logs to health.log
+  claude-accounts health                    limits + full verify + shim-on-PATH probe; logs to health.log
   claude-accounts self-update               update this npm/git install; logs to update.log
   claude-accounts post-sync                 (server side) seed dirs, fix perms, quick verify
 
@@ -255,6 +256,18 @@ if dups:
 PYEOF
 }
 
+# A fresh login shell that never reaches the shim is the one failure the pool cannot
+# see from the inside — the launch simply happens elsewhere (my-mini 2026-09-17: an
+# interrupted ~/.zshrc, and every `bash -l`, resolved the real binary and opened on the
+# un-pooled ~/.claude login). lib/shim_path.py starts each login shell with this user's
+# rc files and asks. Off with CLAUDE_MULTIACC_PATH_PROBE=0 — the sandboxed suites run
+# under the operator's real HOME and must not depend on its rc files.
+shim_path_report() {
+  # The module honours the kill switch itself and says so in its output, so a status
+  # or health.log read with the probe off never looks like a probe that passed.
+  "$PYBIN" "$LIB_DIR/shim_path.py" "$REPO_DIR"
+}
+
 cmd_status() {
   require_manifest
   local json=0
@@ -482,6 +495,8 @@ elif verdict == 'degraded':
     print("  fix : claude-accounts limits --force   # then, if it still fails:")
     print("        claude-accounts login <acct-NN>  # per account, on THIS machine")
 PYEOF
+  echo
+  shim_path_report || true
 }
 
 cmd_add() {
@@ -2290,6 +2305,28 @@ for acct in manifest.get('accounts', []):
     maxp = max([b['percent'] for b in live] or [0])
     weeklyp = max(weekly) if weekly else None
     sessionp = max(session) if session else None
+    # ...but only the WEEKLY half of that rule is about a missing answer. The two kinds
+    # of bucket go silent for opposite reasons, and 2026-09-22 cost a day of picks to
+    # the difference. A weekly window always exists — it is a fixed calendar week,
+    # running whether or not the account is — so a weekly bucket with nothing to say is
+    # an endpoint that DECLINED, and inventing a number for it is the 2026-09-04 bug.
+    # The 5h SESSION window only exists while it is OPEN: leave an account alone for
+    # five hours and there is no window left to describe, so the endpoint answers
+    # `percent: 0, resets_at: null` — not silence but "nothing has been used". An
+    # exhausted session is never silent: a spent 5h bucket ALWAYS carries the window it
+    # resets in (the live pool on 2026-09-22 — every session bucket above 0% had a real
+    # resets_at, every silent one belonged to an idle account), so a silent session
+    # cannot be hiding a full one. Recording it as UNKNOWN is what broke selection:
+    # pick_best's quota_known rule needs BOTH readings, so an IDLE account — precisely
+    # the one with the most headroom — was scored weekly=100 and dropped out of the
+    # band, leaving only the busy accounts that still held an open 5h window. From
+    # selection.log at 2026-09-22T12:37:36Z: band-count=1, and that one band member was
+    # acct-17 at 95% weekly, while acct-13 and acct-14 sat at 0% and unrankable.
+    # So: a session bucket that said nothing inside a document that DID answer reads 0.
+    # A document where NOTHING answered still writes no signals at all (see below) —
+    # the 2026-09-04 all-zero shape stays unknown, which is the whole point.
+    if sessionp is None and live:
+        sessionp = 0
     # How long weekly_percent keeps meaning something. A weekly bucket only ever RISES
     # until its reset, so before that moment a stale percent is still a valid lower
     # bound and the shim can rank on it when nothing fresher exists; after it, the
@@ -2956,6 +2993,13 @@ cmd_health() {
   # verify first: its real claude runs refresh any expired OAuth creds, so the
   # limits pass that follows always has fresh bearers.
   out="$( { echo "== verify =="; cmd_verify; echo; echo "== limits =="; cmd_limits; } 2>&1 )" || rc=1
+  # The shim being reachable at all is part of the pool's health: a login shell that
+  # resolves the real binary hands every `claude` typed there to ~/.claude, whatever
+  # the accounts above say. Reported (and failed) here, where the weekly check pages.
+  local shim_out
+  shim_out="$( { echo; echo "== shim =="; shim_path_report; } 2>&1 )" || rc=1
+  out="$out
+$shim_out"
   printf '%s\n' "$out"
   printf '%s health rc=%s\n%s\n' "$(ts_utc)" "$rc" "$out" >> "$ACC_ROOT/health.log"
   if [ "$rc" -ne 0 ] && [ "$(machine_kind)" = "mac" ]; then

package/bin/codex-accounts

@@ -1585,6 +1585,22 @@ for acct in manifest.get('accounts', []):
     maxp = max([b['percent'] for b in live] or [0])
     weeklyp = max(weekly) if weekly else None
     sessionp = max(session) if session else None
+    # ...but only the WEEKLY half of that rule is about a missing answer — same
+    # asymmetry the claude writer documents, and codex feels it harder. A durable
+    # window always exists, so a silent one is an endpoint that DECLINED. A ~5h session
+    # window only exists while it is OPEN, and codex does not even keep a placeholder
+    # for a closed one: an idle account's payload carries the 7d window and NO session
+    # window whatsoever, so `session` here is empty for every quiet account. That made
+    # session_percent permanently absent across this pool, and pick_best's quota_known
+    # rule needs BOTH readings — so EVERY codex account scored unknown, bestw never left
+    # 101, and the band degenerated to the all-gated tie: codex has been picking
+    # uniformly at RANDOM rather than by headroom (selection.log: `session=?%` on every
+    # ranked line). A session window that is closed has nothing in it, and an exhausted
+    # one is never silent — it reports at/near 100% with the reset it is waiting on.
+    # So a missing or silent session reads 0 whenever the payload answered at all; a
+    # payload where NOTHING answered still writes no signals and stays unknown below.
+    if sessionp is None and live:
+        sessionp = 0
     try:
         reset_result, reset_view = refresh_reset_credits(d, aid, maxp, data, url, headers, say, int(now))
     except Exception as e:

package/docs/INSTALLATION.md

@@ -78,14 +78,23 @@ one layout that can NOT self-update — don't ship the addon that way.
 What install does (all reversible, nothing else):
 
 - **macOS:** marked PATH block at the END of `~/.zshenv`, `~/.zprofile`, `~/.zshrc`
-  (+ bash rc files if present) — end-of-file placement matters because those files
-  re-prepend `~/.local/bin`; launchd agents `com.claude-multiacc.limits` +
+  (+ `~/.profile` and the bash rc files when they exist) — end-of-file placement
+  matters because those files re-prepend `~/.local/bin`. Every copy of the block also
+  registers a prompt hook (zsh `precmd` / bash `PROMPT_COMMAND`) that puts the shim
+  dir back in front before each prompt, so an rc file interrupted with Ctrl-C or a
+  tool that rewrites PATH (conda, nvm, a venv) cannot leave the real binary first at
+  the next prompt. `~/.profile` is what `bash -l` / `sh -l` read when there is no
+  `~/.bash_profile`, so a launcher that runs `bash -lc claude` reaches the pool too;
+  it is created when absent (a stock macOS account has none), and the installer never
+  creates `~/.bash_profile` (that would stop bash reading `~/.profile`). launchd agents `com.claude-multiacc.limits` +
   `.codex-limits` (15m Claude / 5m Codex), `.health` + `.codex-health` (weekly Mon morning), and
   `.update` (daily 04:07). Notes when this Mac keeps Claude Code logins in the
   Keychain (the pool reads them; ssh sessions cannot — mint portable tokens for
   accounts that must work from everywhere).
-- **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`,
-  shim symlinks at `/usr/local/bin/claude` and `/usr/local/bin/codex` (shadow via
+- **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`
+  (+ `~/.profile`, created when absent — Debian's own `~/.profile` prepends
+  `~/.local/bin` after `/etc/profile.d` has run, so the block has to end that file
+  too), shim symlinks at `/usr/local/bin/claude` and `/usr/local/bin/codex` (shadow via
   PATH order — on the systemd default PATH too; the original binaries are untouched),
   cron entries for limits/health (both providers) + the daily auto-update.
 - Both: `~/.claude-accounts/` and `~/.codex-accounts/`, each with an `accounts.json` manifest.

package/docs/VERIFICATION.md

@@ -11,7 +11,8 @@ claude-accounts verify --quick # auth presence/expiry only, no inference
 codex-accounts verify         # real codex exec call per account
 codex-accounts verify --quick  # local Codex auth check, no inference
 claude-accounts limits        # live per-bucket usage incl. the Fable bucket
-claude-accounts health        # limits + full verify, logs to health.log, notifies on failure (Mac)
+claude-accounts health        # limits + full verify + shim-on-PATH probe, logs to health.log, notifies on failure (Mac)
+python3 lib/shim_path.py "$(npm root -g)/claude-multiacc"   # just the probe; exit 1 on a bypass
 ```
 
 Verified end-to-end on both machines (2026-07-13): full matrix PASS, 20-invocation shim
@@ -22,9 +23,17 @@ repointed via `CLAUDE_BIN=/usr/local/bin/claude` and restarted healthy.
 
 ## Troubleshooting
 
-- **`claude` resolves to the real binary, not the shim** — open a new shell, or check
-  that the marked block is the LAST PATH manipulation in your rc file
-  (`grep -A2 'claude-multiacc >>>' ~/.zshrc`).
+- **`claude` resolves to the real binary, not the shim** — the launch then never
+  reaches the pool: the real client starts on the machine's own `~/.claude` login, and
+  from ssh/tmux (where that login sits in a locked Keychain) it opens on
+  "Not logged in · Please run /login" (my-mini, 2026-09-17). `claude-accounts status`
+  and the weekly `health` probe every login shell mode (`zsh -li`/`-lc`, `bash -li`/`-lc`,
+  `sh -lc`) with your own rc files and report `BYPASSED -> <path>` for any that resolve
+  something other than the shim. Fix: `claude-multiacc install` rewrites the rc blocks
+  (`~/.zshenv`, `~/.zprofile`, `~/.zshrc`, `~/.profile`, bash rc files) — each carries
+  a prompt hook that re-asserts the shim dir before every prompt — then open a new
+  shell; an already-open shell keeps the PATH it has. To check one shell by hand:
+  `zsh -lic 'whence -p claude'` / `bash -lc 'type -P claude'`.
 - **An account never gets picked** — `claude-accounts status`: no auth on this machine,
   a dead login (`selectable: NO`, see `claude-accounts expired`), or an active `.limited`
   marker (shows bucket + minutes to reset).

package/lib/install_actions.sh

@@ -33,14 +33,48 @@ path_block_body() {
   printf 'export PATH="%s/bin:$PATH"\n' "$REPO_DIR"
 }
 
+path_guard_body() {
+  # The two lines above win only while they are the LAST thing to touch PATH. A later
+  # rc line, a tool that rewrites PATH (conda, nvm, a venv) or an rc file that was
+  # INTERRUPTED before reaching them (a Ctrl-C at a slow `conda` hook, my-mini
+  # 2026-09-17) leaves ~/.local/bin in front again — and the next `claude` typed at
+  # that prompt runs the real binary on the machine's own ~/.claude login (or on no
+  # login at all), never reaching the pool. Nothing inside the shim can notice a launch
+  # that never reached it, so the rc block also registers a prompt hook (zsh precmd /
+  # bash PROMPT_COMMAND) that puts the shim dir back in front before EVERY prompt.
+  # Fork-free while PATH is already right, registered once, inert once the addon is
+  # gone. The array syntax is wrapped in eval so sh/dash — which read ~/.profile and
+  # /etc/profile.d as well — can parse the block.
+  printf '_claude_multiacc_path_guard() {\n'
+  printf '  [ -x "%s/bin/claude" ] || return 0\n' "$REPO_DIR"
+  printf '  case ":$PATH:" in ":%s/bin:"*) return 0 ;; esac\n' "$REPO_DIR"
+  printf '  PATH="$(printf %%s ":$PATH:" | sed '\''s|:%s/bin:|:|g; s|^:||; s|:$||'\'')"\n' "$REPO_DIR"
+  printf '  export PATH="%s/bin:$PATH"\n' "$REPO_DIR"
+  printf '}\n'
+  # Registered LAST on purpose, in both shells: a hook that runs after this one and
+  # rewrites PATH (direnv's, a venv's) would otherwise have the final say at the
+  # prompt. zsh removes any earlier registration and re-appends, so the copy of this
+  # block at the END of ~/.zshrc outranks hooks that ~/.zshrc registered before it;
+  # the filter is IFS-independent. bash appends once — its rc block is the last thing
+  # sourced, so an append lands last.
+  printf 'if [ -n "${ZSH_VERSION:-}" ]; then\n'
+  printf '  eval '\''precmd_functions=(${precmd_functions:#_claude_multiacc_path_guard} _claude_multiacc_path_guard)'\''\n'
+  printf 'elif [ -n "${BASH_VERSION:-}" ]; then\n'
+  printf '  case ";${PROMPT_COMMAND:-};" in *";_claude_multiacc_path_guard;"*) ;; *) PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND;}_claude_multiacc_path_guard" ;; esac\n'
+  printf 'fi\n'
+}
+
+rc_block() { # the complete marked block, for every rc file and /etc/profile.d alike
+  printf '%s\n' "$MARK_BEGIN"
+  path_block_body
+  path_guard_body
+  printf '%s\n' "$MARK_END"
+}
+
 append_block() { # strip then append our PATH block to a file
   local f="$1"
   strip_block "$f" || return 1   # never create a second block next to a broken one
-  {
-    printf '%s\n' "$MARK_BEGIN"
-    path_block_body
-    printf '%s\n' "$MARK_END"
-  } >> "$f"
+  rc_block >> "$f"
 }
 
 do_uninstall() {
@@ -154,11 +188,33 @@ PYEOF
   fi
 }
 
+# bash and sh read ~/.profile for a LOGIN shell when ~/.bash_profile and ~/.bash_login
+# are absent — `bash -lc`, `sh -lc`, a tmux/ssh session whose login shell is bash. Left
+# without a block, such a shell ends its startup with whatever /etc/profile and its own
+# ~/.local/bin prepend put in front and never sees the shim (my-mini 2026-09-17: every
+# `bash -l` resolved the real binary). The file is CREATED when absent — a stock macOS
+# account has no ~/.profile at all, and without one the bash/sh modes stay bypassed and
+# the shim probe fails `health` with a remedy that changes nothing — exactly as the
+# installer already creates ~/.zshenv and ~/.zprofile. It never creates ~/.bash_profile:
+# that file's mere existence stops bash reading ~/.profile.
+install_profile_block() {
+  touch "$HOME/.profile" 2>/dev/null || {
+    echo "  WARNING: cannot create $HOME/.profile — bash/sh login shells will not see the shim" >&2
+    return 0
+  }
+  if append_block "$HOME/.profile"; then
+    echo "  PATH block: also at the end of ~/.profile (bash/sh login shells)"
+  else
+    echo "  WARNING: ~/.profile was NOT updated (see above) — bash/sh login shells will not see the shim" >&2
+  fi
+}
+
 install_mac_paths() {
   # .zshenv covers non-interactive zsh; the .zshrc block must be LAST so it wins
   # over ~/.local/bin re-prepends done earlier in .zshrc/.zprofile.
   # zsh reads: .zshenv always; .zprofile for login; .zshrc for interactive.
-  # The block must end each file that later re-prepends ~/.local/bin.
+  # The block must end each file that later re-prepends ~/.local/bin, and every copy
+  # also carries the prompt hook (path_guard_body) for the rc-interrupted case.
   if [ -z "$INSTANCE" ]; then
     touch "$HOME/.zshenv"
     append_block "$HOME/.zshenv"
@@ -168,7 +224,8 @@ install_mac_paths() {
     append_block "$HOME/.zshrc"
     [ -f "$HOME/.bash_profile" ] && append_block "$HOME/.bash_profile"
     [ -f "$HOME/.bashrc" ] && append_block "$HOME/.bashrc"
-    echo "  PATH block: end of ~/.zshenv, ~/.zprofile, ~/.zshrc (+ bash rc files if present)"
+    echo "  PATH block: end of ~/.zshenv, ~/.zprofile, ~/.zshrc (+ bash rc files if present), with a prompt hook that re-asserts it"
+    install_profile_block
   fi
 }
 
@@ -177,13 +234,10 @@ install_linux_paths() {
     touch "$HOME/.bashrc"
     append_block "$HOME/.bashrc"
     if [ -w /etc/profile.d ] 2>/dev/null || [ "$(id -u)" = "0" ]; then
-      {
-        printf '%s\n' "$MARK_BEGIN"
-        path_block_body
-        printf '%s\n' "$MARK_END"
-      } > "$PROFILED"
-      echo "  PATH block: ~/.bashrc + $PROFILED"
+      rc_block > "$PROFILED"
+      echo "  PATH block: ~/.bashrc + $PROFILED (with a prompt hook that re-asserts it)"
     fi
+    install_profile_block
   fi
   if [ -z "$INSTANCE" ] && [ "$(id -u)" = "0" ]; then
     if [ -e /usr/local/bin/claude ] && [ ! -L /usr/local/bin/claude ]; then

package/lib/shim_path.py

@@ -0,0 +1,306 @@
+"""Does a FRESH shell resolve `claude` / `codex` to this addon's shims?
+
+The shims shadow the real binaries by PATH ORDER, and the rc-file block that puts them
+first is only as good as the shell startup that runs it. Three ways it silently is not:
+a ~/.profile with no block (every `bash -l` / `sh -l` on my-mini resolved the real
+binary, 2026-09-17), an rc file interrupted half-way (a Ctrl-C at a slow `conda` hook
+left ~/.local/bin in front, and the next `claude` at that prompt opened on the
+un-pooled ~/.claude login: "Not logged in · Please run /login"), or a later
+`export PATH=` that re-prepends ~/.local/bin. Nothing inside the shim can notice a
+launch that never reached it, so this is checked from the OUTSIDE: start each login
+shell the way a terminal or a `bash -lc` launcher would — clean environment, the user's
+own rc files — and ask what the command names resolve to.
+
+Interactive modes (`-li`) are fed the probe on stdin, so the shell runs its prompt loop
+and the rc block's prompt hook (lib/install_actions.sh path_guard_body) gets its turn,
+exactly as it does for a person at a prompt. The `-lc` modes are what a launcher that
+runs `bash -lc claude` gets: rc order alone, no prompt hook.
+
+What is measured is the PATH search — `whence -p` / `type -P`, aliases and functions set
+aside — because the incident was a PATH-order failure and an `alias claude='claude
+--flags'` still resolves through PATH. A function or alias that names the real binary
+outright is not detected here; it is also not something an installer can fix.
+
+Every answer line carries a sentinel, the first answer per name wins, and a name the
+shell never answered for is an ERROR on that row, not a bypass: an rc file that reads a
+line of stdin (an update prompt, a `read`) can eat part of the fed script. Nothing
+touches the operator's shell history — the script disables it first thing.
+
+probe(repo_dir) -> [ {shell, mode, argv, results: {name: {resolved, ok}}, error} ... ]
+    ok is True for the shim, False for anything else (the real binary, or nothing on
+    PATH at all), None when the shell could not answer (timeout / no output).
+bypassed(rows) -> the (mode, name, resolved) triples with ok False.
+
+Run directly:  python3 lib/shim_path.py <repo-dir> [--json] [--timeout=SECONDS]
+Prints the report; exit 1 when any mode bypasses the shim, 2 on usage, else 0.
+CLAUDE_MULTIACC_PATH_PROBE=0 makes probe() return [] (the sandboxed suites run with the
+operator's real HOME and must not depend on its rc files).
+"""
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+from concurrent.futures import ThreadPoolExecutor
+
+NAMES = ('claude', 'codex')
+# The marker every shim carries in its header; lib/common.sh is_shim_file greps the
+# same word, so a /usr/local/bin/claude -> shim symlink (Linux) counts as the shim too.
+SHIM_MARK = 'multiacc-shim'
+DEFAULT_TIMEOUT = 25
+# (shell, flags, interactive) — a terminal is a login AND interactive shell; a
+# `bash -lc` launcher is login only; sh has no interactive rc worth probing.
+MODES = (
+    ('zsh', '-li', True), ('zsh', '-lc', False),
+    ('bash', '-li', True), ('bash', '-lc', False),
+    ('sh', '-lc', False),
+)
+# What resolves a NAME to the executable a shell would run, per shell, bypassing
+# aliases and functions (an interactive zsh answers `command -v claude` with the
+# user's alias text, which says nothing about the file). POSIX sh has only `command -v`,
+# which reports an alias or a function by name, so the sh script drops those first.
+_RESOLVERS = {'zsh': 'whence -p', 'bash': 'type -P', 'sh': 'command -v'}
+SENTINEL = '__claude_multiacc_probe__'
+# The PATH a login shell STARTS from before any rc file runs — what sshd/login/launchd
+# hand it. /usr/local/bin matters on Linux: the root install's /usr/local/bin/claude
+# symlink is how a shell with no rc block still reaches the shim, so leaving it out
+# would call a working server login a bypass. macOS's path_helper rebuilds PATH from
+# /etc/paths anyway.
+_SEED_PATH = {'darwin': '/usr/bin:/bin:/usr/sbin:/sbin'}
+_SEED_PATH_DEFAULT = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
+
+
+def enabled():
+    return os.environ.get('CLAUDE_MULTIACC_PATH_PROBE', '').strip().lower() \
+        not in ('0', 'false', 'no', 'off')
+
+
+def shell_path(name):
+    """The shell binary a terminal would start, or None when it is not installed."""
+    found = shutil.which(name, path='/bin:/usr/bin:/usr/local/bin:/opt/homebrew/bin')
+    if found:
+        return found
+    candidate = os.path.join('/bin', name)
+    return candidate if os.access(candidate, os.X_OK) else None
+
+
+def _script(shell, names):
+    resolver = _RESOLVERS[shell]
+    # First thing, before any answer: no history. The interactive shells would otherwise
+    # save these lines into the operator's real ~/.zsh_history / ~/.bash_history on exit
+    # (macOS /etc/zshrc sets HISTFILE unconditionally, so an env var is not enough — this
+    # runs AFTER the rc files and wins). bash honours `unset HISTFILE`; zsh honours
+    # SAVEHIST=0. The stderr redirect swallows "no such option" from the other shell.
+    # `set +o history` is bash-only: zsh's `set` rejects the option, and a NON-interactive
+    # zsh exits on a special-builtin error — the whole `-lc` row would read as "exited
+    # without answering". zsh needs nothing beyond SAVEHIST=0.
+    lines = ['unset HISTFILE 2>/dev/null; HISTFILE=/dev/null; SAVEHIST=0; HISTSIZE=0; '
+             '[ -z "${BASH_VERSION:-}" ] || set +o history; true']
+    if shell == 'sh':
+        # `command -v` answers with alias text or a bare function name; the PATH search
+        # is the question, so those go first (the shell is a throwaway).
+        lines.append('unalias -a 2>/dev/null; unset -f ' + ' '.join(names) + ' 2>/dev/null; true')
+    lines += [f'printf \'%s %s=%s\\n\' {SENTINEL} {n} "$({resolver} {n} 2>/dev/null)"'
+              for n in names]
+    # The interactive shells read this on stdin; without the exit an rc file that
+    # left the shell in a state where EOF is ignored (IGNOREEOF) would hang to timeout.
+    lines.append('exit 0')
+    return '\n'.join(lines) + '\n'
+
+
+def _env(home, user, shell):
+    # A TERM a terminal would set: rc files commonly bail out early on TERM=dumb (the
+    # Emacs TRAMP guard), which would judge a branch no person at a prompt ever sees.
+    return {'HOME': home, 'USER': user, 'LOGNAME': user, 'SHELL': shell,
+            'TERM': 'xterm-256color',
+            'PATH': _SEED_PATH.get(sys.platform, _SEED_PATH_DEFAULT),
+            'LANG': os.environ.get('LANG', 'C.UTF-8'),
+            'CLAUDE_MULTIACC_PATH_PROBE': '1'}
+
+
+def is_shim(path, repo_dir, name):
+    if not path:
+        return False
+    try:
+        if os.path.realpath(path) == os.path.realpath(os.path.join(repo_dir, 'bin', name)):
+            return True
+        with open(path, 'rb') as f:
+            return SHIM_MARK.encode() in f.read(300)
+    except OSError:
+        return False
+
+
+def _parse(text, names):
+    """First sentinel answer per name. Anything else the shell printed is ignored."""
+    answers = {}
+    for line in text.splitlines():
+        if not line.startswith(SENTINEL + ' '):
+            continue
+        body = line[len(SENTINEL) + 1:]
+        name, _sep, value = body.partition('=')
+        if name in names and name not in answers:
+            answers[name] = value.strip()
+    return answers
+
+
+def _run_mode(shell, flags, interactive, names, repo_dir, home, user, timeout):
+    exe = shell_path(shell)
+    mode = f'{shell} {flags}'
+    row = {'shell': shell, 'mode': mode, 'interactive': interactive, 'argv': None,
+           'results': {}, 'error': None}
+    if not exe:
+        row['error'] = 'shell not installed'
+        return row
+    script = _script(shell, names)
+    argv = [exe, flags] if interactive else [exe, flags, script]
+    row['argv'] = argv
+    try:
+        text, timed_out, returncode = _run_shell(argv, script if interactive else '',
+                                                 _env(home, user, exe), home, timeout)
+    except Exception as e:  # noqa: BLE001 — one mode must never take down the report
+        row['error'] = f'probe could not run: {e!r}'[:200]
+        return row
+    answers = _parse(text, names)
+    missing = [n for n in names if n not in answers]
+    if timed_out and missing:
+        row['error'] = f'no answer within {timeout}s (an rc file is hanging or prompting)'
+        return row
+    if not answers:
+        row['error'] = (f'shell exited {returncode} without answering '
+                        '(an rc file exec\'d something, exited early, or read the probe)')
+        return row
+    for n in names:
+        if n in answers:
+            resolved = answers[n] or None
+            row['results'][n] = {'resolved': resolved, 'ok': is_shim(resolved, repo_dir, n)}
+        else:
+            row['results'][n] = {'resolved': None, 'ok': None}
+    if missing:
+        row['error'] = (f'no answer for {", ".join(missing)} — an rc file consumed part of '
+                        'the probe (a prompt or `read` on stdin?)')
+    return row
+
+
+def _run_shell(argv, stdin_text, env, cwd, timeout):
+    """(stdout text, timed_out, returncode). stdout goes to a temp FILE, not a pipe:
+    a pipe only closes when every process holding it is gone, so an rc line that
+    backgrounds something (`ssh-agent`, `tmux new -d`, `cmd &`) would keep a pipe open
+    long after the shell answered and exited, and the whole answer would be lost to
+    the timeout. The shell gets its own session so a timeout can kill everything it
+    started. Whatever was written before a timeout is still returned."""
+    with tempfile.TemporaryFile() as out:
+        p = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=out, stderr=subprocess.DEVNULL,
+                             env=env, cwd=cwd if os.path.isdir(cwd) else None,
+                             start_new_session=True)
+        timed_out = False
+        try:
+            p.communicate(stdin_text.encode('utf-8'), timeout=timeout)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            try:
+                os.killpg(p.pid, signal.SIGKILL)
+            except OSError:
+                pass
+            try:
+                p.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                pass
+        out.seek(0)
+        text = out.read().decode('utf-8', errors='replace')
+    return text, timed_out, p.returncode
+
+
+def probe(repo_dir, home=None, user=None, names=NAMES, timeout=DEFAULT_TIMEOUT, modes=MODES):
+    if not enabled():
+        return []
+    home = home or os.path.expanduser('~')
+    try:
+        user = user or getpass.getuser()
+    except Exception:  # noqa: BLE001 — no passwd entry; the name only seeds $USER
+        user = os.environ.get('USER') or 'user'
+    with ThreadPoolExecutor(max_workers=len(modes)) as pool:
+        return list(pool.map(
+            lambda m: _run_mode(m[0], m[1], m[2], names, repo_dir, home, user, timeout), modes))
+
+
+def bypassed(rows):
+    out = []
+    for row in rows:
+        for name, r in row['results'].items():
+            if r['ok'] is False:
+                out.append((row['mode'], name, r['resolved']))
+    return out
+
+
+def render(rows):
+    """Operator-facing lines. The verdict line is the one that matters; the per-mode
+    lines say WHICH shell to open to reproduce it."""
+    lines = ['shim on PATH (fresh login shells, this user\'s rc files):']
+    if not rows:
+        lines.append('  (probe disabled: CLAUDE_MULTIACC_PATH_PROBE=0)')
+        return lines
+    for row in rows:
+        cell = f'  {row["mode"]:<8}'
+        if row['error']:
+            lines.append(f'{cell} ?  {row["error"]}')
+            continue
+        parts = []
+        for name, r in row['results'].items():
+            if r['ok'] is None:
+                parts.append(f'{name}: ?')
+            elif r['ok']:
+                parts.append(f'{name}: OK')
+            elif r['resolved']:
+                parts.append(f'{name}: BYPASSED -> {r["resolved"]}')
+            else:
+                parts.append(f'{name}: NOT ON PATH')
+        lines.append(f'{cell} {"   ".join(parts)}' + (f'   ({row["error"]})' if row['error'] else ''))
+    bad = bypassed(rows)
+    if bad:
+        modes = sorted({m for m, _n, _r in bad})
+        lines.append(f'  ** {len(modes)} shell mode(s) start `claude`/`codex` OUTSIDE the pool '
+                     f'({", ".join(modes)}): such a session runs the real binary on the '
+                     'machine\'s own ~/.claude login — or on no login at all ("Not logged '
+                     'in · Please run /login"). **')
+        lines.append('     fix: claude-multiacc install   # rewrites the rc blocks (~/.zshenv, '
+                     '~/.zprofile, ~/.zshrc, ~/.profile, bash rc files) with the prompt hook')
+        lines.append('     then open a new shell (or run: exec "$SHELL" -l) — an already-open '
+                     'shell keeps the PATH it has')
+    unanswered = [row['mode'] for row in rows
+                  if row['error'] and row['error'] != 'shell not installed' and not row['results']]
+    if unanswered:
+        lines.append(f'  note: {", ".join(unanswered)} could not be probed — open one by hand '
+                     'and run: command -v claude')
+    return lines
+
+
+def main(argv):
+    args = [a for a in argv[1:] if not a.startswith('--')]
+    flags = [a for a in argv[1:] if a.startswith('--')]
+    if len(args) != 1 or any(f not in ('--json',) and not f.startswith('--timeout=') for f in flags):
+        print('usage: shim_path.py <repo-dir> [--json] [--timeout=SECONDS]', file=sys.stderr)
+        return 2
+    timeout = DEFAULT_TIMEOUT
+    for f in flags:
+        if f.startswith('--timeout='):
+            try:
+                timeout = max(1, int(f.split('=', 1)[1]))
+            except ValueError:
+                print('usage: --timeout takes an integer number of seconds', file=sys.stderr)
+                return 2
+    rows = probe(args[0], timeout=timeout)
+    if '--json' in flags:
+        print(json.dumps({'repo_dir': args[0], 'enabled': enabled(), 'modes': rows,
+                          'bypassed': [list(b) for b in bypassed(rows)]}, indent=2))
+    else:
+        print('\n'.join(render(rows)))
+    return 1 if bypassed(rows) else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))