claude-multiacc 2.0.31 → 2.0.33

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() {
@@ -2956,6 +2971,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/docs/CODEX.md

@@ -88,16 +88,19 @@ The addon does not choose delegation policy by default. To manage the concurrent
 subagent ceiling across one Codex pool, explicitly configure it (Python 3.11+):
 
 ```bash
-codex-accounts configure --max-subagents 8 --include-global --json
-codex-accounts configure --max-subagents 8 --include-global --check --json
+codex-accounts configure --max-subagents 7 --include-global --json
+codex-accounts configure --max-subagents 7 --include-global --check --json
 ```
 
 An explicitly selected modern Python is preserved. If the shell resolves an older
 system Python, this command tries already installed Python 3.11+ executables on
 PATH and in standard Homebrew locations, with bounded probes and no downloads.
 
-The first command sets `agents.max_concurrent_threads_per_session` in every manifest
+The first command sets `features.multi_agent_v2.max_concurrent_threads_per_session`
+and the compatible `agents.max_concurrent_threads_per_session` in every manifest
 account's `config.toml`, migrating its legacy `agents.max_threads` key when present.
+An existing boolean `multi_agent_v2` becomes a table with the same `enabled` value;
+an existing feature cap is updated along with the agents cap.
 `--include-global` also updates the machine's `~/.codex/config.toml`; without it,
 the global file is untouched. Unrelated models, instructions, MCP servers, project
 trust and custom agents remain intact. Retired directories outside the manifest
@@ -112,16 +115,16 @@ fails sync instead of reporting success. Remote sync does not change the target'
 global config. Without the policy file, existing settings keep their usual
 copy-only-if-missing behavior and no new remote command runs.
 
-`--check` never writes; it checks the requested value against the persisted policy
-and selected configs, returning exit 1 on drift. Without `--max-subagents`, the
-command only reads the current pool policy and configuration. JSON reports contain
+`--check` never writes; it checks both caps against the persisted policy
+and requested value in selected configs, returning exit 1 on drift. Without
+`--max-subagents`, the command only reads the current pool policy and configuration. JSON reports contain
 the installed `plugin_version`, `max_subagents`, `policy_max_subagents`,
 `accounts_total`, `accounts_configured`, `global_configured`, `mismatch_count` and
 `verified`, without account identities, paths, credentials or arbitrary config.
 
-Conflicting profile or `features.multi_agent_v2` object overrides are rejected.
+Conflicting profile overrides are rejected.
 Unusual inline-table layouts are also rejected before configuration changes;
-use an ordinary `[agents]` table for the managed setting. All target configs are
-validated before writes, each replacement is atomic, and repeating the command
+use ordinary `[agents]` and `[features.multi_agent_v2]` tables for the managed settings.
+All target configs are validated before writes, each replacement is atomic, and repeating the command
 repairs an interrupted write. Existing running sessions retain the settings they
 loaded; the policy applies to subsequent sessions.

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/codex_config_edit.py

@@ -8,7 +8,6 @@ except ImportError:
     raise SystemExit("Codex settings configuration requires Python 3.11 or newer") from None
 
 KEY = "max_concurrent_threads_per_session"
-ALIASES = (KEY, "max_threads")
 
 
 def limits(document):
@@ -33,39 +32,61 @@ def validate_overrides(document, value):
             raise ValueError(f"{name}: profile overrides the requested subagent limit")
 
 
+def dotted_pattern(parts):
+    return r'\s*\.\s*'.join(r'(?:' + re.escape(part) + r'|"' + re.escape(part)
+                            + r'"|\x27' + re.escape(part) + r'\x27)' for part in parts)
+
+
+def edit_setting(source, table, key, literal, aliases=()):
+    """Edit table/dotted assignments, or remove one when literal is None."""
+    headers = [re.compile(r'^\s*\[\s*' + dotted_pattern(table[:depth]) + r'\s*\]\s*(?:#.*)?$')
+               for depth in range(1, len(table) + 1)]
+    assignments = [re.compile(r'^\s*(?:' + '|'.join(dotted_pattern((*table[depth:], name))
+                                                 for name in (key, *aliases)) + r')\s*=')
+                   for depth in range(len(table) + 1)]
+    section, output, inserted = 0, [], False
+    for line in source.splitlines(keepends=True):
+        if line.lstrip().startswith("["):
+            section = next((depth for depth, header in enumerate(headers, 1)
+                            if header.match(line.rstrip("\r\n"))), None)
+            if section == len(table) and literal is not None and not inserted:
+                output.extend([line.rstrip("\r\n") + "\n", f"{key} = {literal}\n"])
+                inserted = True
+                continue
+        if section is not None and assignments[section].match(line):
+            if literal is not None and not inserted:
+                output.append(f"{'.'.join((*table[section:], key))} = {literal}\n")
+                inserted = True
+            continue
+        output.append(line)
+    if literal is not None and not inserted:
+        output.extend([f"\n[{'.'.join(table)}]\n", f"{key} = {literal}\n"])
+    return "".join(output)
+
+
 def updated_config(source, value):
-    """Edit ordinary [agents] or dotted keys, then prove no unrelated TOML value changed."""
+    """Set the v2 feature cap and agents fallback, preserving enablement and unrelated values."""
     original = tomllib.loads(source)
-    validate_overrides(original, value)
+    validate_overrides({"profiles": original.get("profiles", {})}, value)
     expected = copy.deepcopy(original)
     agents = expected.setdefault("agents", {})
     agents.pop("max_threads", None)
     agents[KEY] = value
-    lines, section, output, inserted = source.splitlines(keepends=True), "", [], False
-    header = re.compile(r'^\s*\[\s*(?:agents|"agents"|\x27agents\x27)\s*\]\s*(?:#.*)?$')
-    assignment = re.compile(r'^\s*(?:"|\x27)?(?:' + '|'.join(ALIASES) + r')(?:"|\x27)?\s*=')
-    dotted = re.compile(r'^\s*agents\s*\.\s*(?:' + '|'.join(ALIASES) + r')\s*=')
-    for line in lines:
-        if header.match(line.rstrip("\r\n")):
-            section = "agents"
-            output.extend([line.rstrip("\r\n") + "\n", f"{KEY} = {value}\n"])
-            inserted = True
-            continue
-        if line.lstrip().startswith("["):
-            section = "other"
-        if (section == "agents" and assignment.match(line)) or (not section and dotted.match(line)):
-            continue
-        output.append(line)
-    if not inserted:
-        if any(dotted.match(line) for line in lines):
-            output.insert(0, f"agents.{KEY} = {value}\n")
-        else:
-            output.extend(["\n[agents]\n", f"{KEY} = {value}\n"])
-    result = "".join(output)
+    features = expected.setdefault("features", {})
+    feature = features.get("multi_agent_v2")
+    result = edit_setting(source, ("agents",), KEY, value, ("max_threads",))
+    if isinstance(feature, bool):
+        result = edit_setting(result, ("features",), "multi_agent_v2", None)
+        result = edit_setting(result, ("features", "multi_agent_v2"), "enabled", str(feature).lower())
+        features["multi_agent_v2"] = {"enabled": feature}
+    elif feature is None:
+        features["multi_agent_v2"] = {}
+    features["multi_agent_v2"][KEY] = value
+    result = edit_setting(result, ("features", "multi_agent_v2"), KEY, value)
     try:
         unchanged = tomllib.loads(result) == expected
     except tomllib.TOMLDecodeError:
         unchanged = False
     if not unchanged:
-        raise ValueError("unsupported agents TOML layout; use a normal [agents] table before configuring")
+        raise ValueError("unsupported Codex TOML layout; use normal [agents] and [features.multi_agent_v2] tables")
     return result

package/lib/codex_settings.py

@@ -92,7 +92,9 @@ def readback(paths, value):
     result = {}
     for path in paths:
         document = tomllib.loads(path.read_text()) if path.exists() else {}
-        matches = limits(document)["effective"] == value if value is not None else True
+        current = limits(document)
+        matches = (all(current[key] == value for key in ("configured", "feature_override"))
+                   if value is not None else True)
         try:
             validate_overrides(document, value)
         except ValueError:

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