claude-multiacc 2.0.27 → 2.0.29

package/lib/install_actions.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# Installer actions, sourced by install.sh. Bash 3.2 compatible.
+
+is_pool_root() { # true when $1 is safe to delete as an account pool
+  case "$1" in
+    ''|/|"$HOME") return 1 ;;
+    */.claude-accounts|*/.codex-accounts) return 0 ;;
+    /*) [ -f "$1/accounts.json" ] ;;
+    *) return 1 ;;
+  esac
+}
+
+strip_block() { # remove our marked block from a file (portable, no sed -i)
+  local f="$1"
+  [ -f "$f" ] || return 0
+  # Unmatched begin marker (end line hand-deleted): stripping would eat the rest
+  # of the rc file. Leave it alone and say so.
+  if grep -qF "$MARK_BEGIN" "$f" && ! grep -qF "$MARK_END" "$f"; then
+    echo "  WARNING: $f has an unterminated claude-multiacc block — fix it by hand; not touching this file" >&2
+    return 1
+  fi
+  awk -v b="$MARK_BEGIN" -v e="$MARK_END" '
+    $0 == b { skip = 1; next }
+    $0 == e { skip = 0; next }
+    !skip { print }
+  ' "$f" > "$f.claude-multiacc.tmp" && mv "$f.claude-multiacc.tmp" "$f"
+}
+
+path_block_body() {
+  # Move (not just add) the shim dir to the front: later rc lines prepend
+  # ~/.local/bin, so a plain add-once guard would leave the real binary first.
+  printf 'PATH="$(printf %%s ":$PATH:" | sed '\''s|:%s/bin:|:|g; s|^:||; s|:$||'\'')"\n' "$REPO_DIR"
+  printf 'export PATH="%s/bin:$PATH"\n' "$REPO_DIR"
+}
+
+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"
+}
+
+do_uninstall() {
+  echo "claude-multiacc: uninstalling (restoring stock behavior)"
+  # An instance install never wrote a shell rc block, a /etc/profile.d file or the
+  # /usr/local/bin shims — those belong to the DEFAULT install and are shared with it.
+  if [ -n "$INSTANCE" ]; then
+    echo "  instance $INSTANCE: removing its agents only (PATH block and shims belong to the default install)"
+  else
+    strip_block "$HOME/.zshenv"
+    strip_block "$HOME/.zprofile"
+    strip_block "$HOME/.zshrc"
+    strip_block "$HOME/.bashrc"
+    strip_block "$HOME/.bash_profile"
+    strip_block "$HOME/.profile"
+  fi
+  if [ "$(machine_kind)" = "mac" ]; then
+    mac_schedule_remove
+  else
+    linux_schedule_remove
+    if [ -z "$INSTANCE" ]; then
+      [ -f "$PROFILED" ] && rm -f "$PROFILED"
+      if [ -L /usr/local/bin/claude ] \
+        && [ "$(canon_path /usr/local/bin/claude)" = "$(canon_path "$REPO_DIR/bin/claude")" ]; then
+        rm -f /usr/local/bin/claude
+        echo "  removed /usr/local/bin/claude shim symlink"
+      fi
+      if [ -L /usr/local/bin/codex ] \
+        && [ "$(canon_path /usr/local/bin/codex)" = "$(canon_path "$REPO_DIR/bin/codex")" ]; then
+        rm -f /usr/local/bin/codex
+        echo "  removed /usr/local/bin/codex shim symlink"
+      fi
+    fi
+  fi
+  local root
+  for root in "$ACC_ROOT" "$CODEX_ACC_ROOT"; do
+    if [ "$PURGE" = "1" ]; then
+      # Either the conventional location, or a directory that is provably a pool (it
+      # holds a manifest) — an instance root lives anywhere, so the manifest is what
+      # makes `rm -rf` safe. Anything else is left alone.
+      if is_pool_root "$root"; then
+        rm -rf "$root"; echo "  purged $root"
+      else
+        echo "  refusing to purge unusual accounts root: $root" >&2
+      fi
+    fi
+  done
+  if [ "$PURGE" != "1" ]; then
+    echo "  account data kept at $ACC_ROOT and $CODEX_ACC_ROOT (use --purge-data to remove)"
+  fi
+  echo "uninstall complete — stock claude behavior restored"
+}
+
+install_binaries() {
+  [ -x "$REPO_DIR/bin/claude" ] || chmod +x "$REPO_DIR/bin/claude" 2>/dev/null || true
+  [ -x "$REPO_DIR/bin/claude-accounts" ] || chmod +x "$REPO_DIR/bin/claude-accounts" 2>/dev/null || true
+  [ -x "$REPO_DIR/bin/codex" ] || chmod +x "$REPO_DIR/bin/codex" 2>/dev/null || true
+  [ -x "$REPO_DIR/bin/codex-accounts" ] || chmod +x "$REPO_DIR/bin/codex-accounts" 2>/dev/null || true
+
+  local real
+  if real="$(find_real_claude "$REPO_DIR/bin/claude")"; then
+    echo "  real claude binary: $real ($("$real" --version 2>/dev/null | head -1 || echo 'version unknown'))"
+  else
+    echo "  WARNING: no real claude binary found — install Claude Code (https://claude.com/claude-code)" >&2
+  fi
+  local real_codex
+  if real_codex="$(find_real_codex "$REPO_DIR/bin/codex")"; then
+    echo "  real codex binary: $real_codex"
+    "$real_codex" --version 2>/dev/null | head -1 || echo '  version unknown'
+  else
+    echo "  note: no codex binary found — install Codex CLI with: npm i -g @openai/codex"
+  fi
+
+  # 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 "  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
+}
+
+install_pools() {
+  manifest_init "${SERVER_OVERRIDE:-$DEFAULT_SERVER}"
+  if [ -n "$SERVER_OVERRIDE" ]; then
+    "$PYBIN" - "$MANIFEST" "$SERVER_OVERRIDE" <<'PYEOF'
+import json, os, sys
+doc = json.load(open(sys.argv[1]))
+doc['server'] = sys.argv[2]
+with open(sys.argv[1] + '.tmp', 'w') as f:
+    json.dump(doc, f, indent=2)
+    f.write('\n')
+os.replace(sys.argv[1] + '.tmp', sys.argv[1])
+PYEOF
+  fi
+  if sync_target_is_local "$(sync_target)"; then
+    echo "  account pool: $ACC_ROOT (manifest ready; sync target: none — local-only)"
+  else
+    echo "  account pool: $ACC_ROOT (manifest ready; sync target: $(sync_target))"
+  fi
+  # The codex pool gets its own skeleton + manifest (same schema, separate root).
+  if ! "$REPO_DIR/bin/codex-accounts" init-pool "${SERVER_OVERRIDE:-}" >/dev/null 2>&1; then
+    echo "  WARNING: codex pool init failed (codex-accounts init-pool)" >&2
+  else
+    echo "  codex account pool: $CODEX_ACC_ROOT (manifest ready)"
+  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.
+  if [ -z "$INSTANCE" ]; then
+    touch "$HOME/.zshenv"
+    append_block "$HOME/.zshenv"
+    touch "$HOME/.zprofile"
+    append_block "$HOME/.zprofile"
+    touch "$HOME/.zshrc"
+    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)"
+  fi
+}
+
+install_linux_paths() {
+  if [ -z "$INSTANCE" ]; then
+    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"
+    fi
+  fi
+  if [ -z "$INSTANCE" ] && [ "$(id -u)" = "0" ]; then
+    if [ -e /usr/local/bin/claude ] && [ ! -L /usr/local/bin/claude ]; then
+      echo "  WARNING: /usr/local/bin/claude exists and is a real file — NOT overwriting." >&2
+    else
+      ln -sfn "$REPO_DIR/bin/claude" /usr/local/bin/claude
+      echo "  shim: /usr/local/bin/claude -> $REPO_DIR/bin/claude (systemd-PATH compatible)"
+    fi
+    if [ -e /usr/local/bin/codex ] && [ ! -L /usr/local/bin/codex ]; then
+      echo "  WARNING: /usr/local/bin/codex exists and is a real file — NOT overwriting." >&2
+    else
+      ln -sfn "$REPO_DIR/bin/codex" /usr/local/bin/codex
+      echo "  shim: /usr/local/bin/codex -> $REPO_DIR/bin/codex (systemd-PATH compatible)"
+    fi
+  fi
+}
+
+do_install() {
+  local kind
+  kind="$(machine_kind)"
+  echo "claude-multiacc: installing (mode: $kind, repo: $REPO_DIR)"
+  if [ -n "$INSTANCE" ]; then
+    echo "  instance: $INSTANCE (agents labelled $LABEL.*, pools $ACC_ROOT + $CODEX_ACC_ROOT)"
+  fi
+
+  install_binaries
+  install_pools
+
+  # An INSTANCE install never rewrites the shell rc blocks: one interactive PATH
+  # cannot serve two pools, and clobbering the default install's block would point
+  # the operator's shell at an instance pool. Its agents (below) carry the roots
+  # instead, and the runner daemon invokes the shims by absolute path.
+  if [ -n "$INSTANCE" ]; then
+    echo "  PATH block: skipped (instance install) — for a shell against this pool:"
+    echo "    export CLAUDE_ACCOUNTS_ROOT='$ACC_ROOT' CODEX_ACCOUNTS_ROOT='$CODEX_ACC_ROOT'"
+    echo "    export PATH=\"$REPO_DIR/bin:\$PATH\""
+  fi
+  if [ "$kind" = "mac" ]; then
+    install_mac_paths
+    [ "$NO_SCHEDULE" = "1" ] || mac_schedule_install
+  else
+    install_linux_paths
+    [ "$NO_SCHEDULE" = "1" ] || linux_schedule_install
+  fi
+
+  echo
+  echo "install complete. Open a new shell (or 'export PATH=\"$REPO_DIR/bin:\$PATH\"'), then:"
+  echo "  claude-accounts list      # the Claude Code pool"
+  echo "  codex-accounts list       # the Codex pool"
+  echo "  claude-accounts status   # Claude auth + limits detail"
+  echo "  codex-accounts status    # Codex auth + limits detail"
+}

package/lib/install_calendar.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Calendar job templates, sourced only by mac_schedule_install in install.sh.
+
+  cat > "$PLIST_HEALTH" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>$LABEL.health</string>
+  <key>ProgramArguments</key><array>
+    <string>$REPO_DIR/bin/claude-accounts</string>
+    <string>health</string>
+  </array>
+$(plist_env_block)  <key>StartCalendarInterval</key><dict>
+    <key>Weekday</key><integer>1</integer>
+    <key>Hour</key><integer>9</integer>
+    <key>Minute</key><integer>17</integer>
+  </dict>
+  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>/dev/null</string>
+</dict></plist>
+EOF
+
+  cat > "$PLIST_UPDATE" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>$LABEL.update</string>
+  <key>ProgramArguments</key><array>
+    <string>$REPO_DIR/bin/claude-accounts</string>
+    <string>self-update</string>
+    <string>--quiet</string>
+  </array>
+$(plist_env_block)  <key>StartCalendarInterval</key><dict>
+    <key>Hour</key><integer>4</integer>
+    <key>Minute</key><integer>7</integer>
+  </dict>
+  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>/dev/null</string>
+</dict></plist>
+EOF
+
+  cat > "$PLIST_CODEX_HEALTH" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>$LABEL.codex-health</string>
+  <key>ProgramArguments</key><array>
+    <string>$REPO_DIR/bin/codex-accounts</string>
+    <string>health</string>
+  </array>
+$(plist_env_block)  <key>StartCalendarInterval</key><dict>
+    <key>Weekday</key><integer>1</integer>
+    <key>Hour</key><integer>9</integer>
+    <key>Minute</key><integer>37</integer>
+  </dict>
+  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>/dev/null</string>
+</dict></plist>
+EOF

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.27",
+  "version": "2.0.29",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {
     "claude-multiacc": "bin/cli.mjs",
+    "claude-accounts": "bin/claude-accounts",
+    "codex-accounts": "bin/codex-accounts",
     "multiacc-select": "bin/multiacc-select"
   },
   "files": [
@@ -53,7 +55,8 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "bash tests/run-tests.sh && python3 tests/test_selector.py"
+    "test": "bash tests/run-tests.sh && python3 tests/test_selector.py && npm run test:commands",
+    "test:commands": "python3 tests/test_packaged_commands.py"
   },
   "dependencies": {
     "update-notifier": "^7.3.1"

package/tests/packaged_command_support.py

@@ -0,0 +1,81 @@
+"""Offline npm installation and isolated command execution for the CLI contract."""
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def run(args, env, cwd, **kwargs):
+    return subprocess.run(args, env=env, cwd=cwd, text=True, capture_output=True, timeout=90, **kwargs)
+
+
+def install_package(test):
+    scratch = tempfile.TemporaryDirectory(prefix="multiacc-packaged-commands-")
+    test.addClassCleanup(scratch.cleanup)
+    test.work = Path(scratch.name).resolve()
+    test.prefix = test.work / "npm prefix"
+    test.home = test.work / "home"
+    test.home.mkdir()
+    npm = shutil.which("npm")
+    cache = subprocess.check_output([npm, "config", "get", "cache"], text=True).strip()
+    paths = [str(Path(shutil.which(name)).parent) for name in ("node", "python3", "npm")]
+    test.env = {
+        "HOME": str(test.home), "PATH": os.pathsep.join(dict.fromkeys(paths + ["/usr/bin", "/bin"])),
+        "CI": "1", "NO_UPDATE_NOTIFIER": "1", "PYTHONDONTWRITEBYTECODE": "1",
+        "CLAUDE_MULTIACC_KEYCHAIN": "0", "CLAUDE_MULTIACC_NO_SYNC": "1", "CODEX_MULTIACC_NO_SYNC": "1",
+        "CLAUDE_ACCOUNTS_ROOT": str(test.home / ".claude-accounts"),
+        "CODEX_ACCOUNTS_ROOT": str(test.home / ".codex-accounts"),
+        "npm_config_cache": cache, "npm_config_update_notifier": "false",
+        "npm_config_prefix": str(test.prefix), "npm_config_offline": "true",
+        "npm_config_ignore_scripts": "true",
+    }
+    packed = run([npm, "pack", "--ignore-scripts", "--pack-destination", str(test.work)],
+                 test.env, ROOT)
+    if packed.returncode:
+        raise RuntimeError(packed.stderr)
+    # npm 11 emits a JSON array; npm 12 keys it by package name. Test the artifact
+    # itself so npm's presentation format cannot strand an otherwise valid release.
+    archives = list(test.work.glob("*.tgz"))
+    if len(archives) != 1:
+        raise RuntimeError(f"Expected one packed archive, found {len(archives)}")
+    archive = archives[0]
+    installed = run([npm, "install", "-g", "--prefix", str(test.prefix), "--ignore-scripts", "--offline",
+                     "--no-audit", "--no-fund", str(archive)], test.env, test.work)
+    if installed.returncode:
+        raise RuntimeError("Offline install failed; run npm install --ignore-scripts to warm dependencies.\n"
+                           + installed.stderr)
+    test.package = test.prefix / "lib/node_modules/claude-multiacc"
+    test.env["PATH"] = str(test.prefix / "bin") + os.pathsep + test.env["PATH"]
+    guard = test.prefix / "bin/npm"
+    guard.write_text('#!/usr/bin/env bash\necho "unexpected npm invocation" >&2\nexit 89\n')
+    guard.chmod(0o755)
+    for name in ("claude", "codex", "security", "launchctl", "crontab", "ln"):
+        guard = test.prefix / "bin" / name
+        guard.write_text('#!/usr/bin/env bash\n'
+                         'printf "%s\\n" "$0 $*" >> "$HOME/tool-calls"\nexit 1\n')
+        guard.chmod(0o755)
+
+
+def seed_pools(test):
+    for provider in ("claude", "codex"):
+        pool = Path(test.env[f"{provider.upper()}_ACCOUNTS_ROOT"])
+        account = pool / "acct-01"
+        account.mkdir(parents=True)
+        (pool / "accounts.json").write_text(json.dumps({
+            "version": 1, "server": "none", "threshold": 90,
+            "accounts": [{"id": "acct-01", "email": f"{provider}@example.test",
+                          "home": "mac" if os.uname().sysname == "Darwin" else "server"}],
+        }))
+        credential = ({"tokens": {"access_token": "fixture", "refresh_token": "fixture"}}
+                      if provider == "codex" else {"claudeAiOauth": {
+                          "accessToken": "fixture", "refreshToken": "fixture", "expiresAt": 9999999999999}})
+        filename = "auth.json" if provider == "codex" else ".credentials.json"
+        (account / filename).write_text(json.dumps(credential))
+        fake = test.prefix / "bin" / provider
+        fake.write_text('#!/usr/bin/env bash\nprintf "OK\\n"\n')
+        fake.chmod(0o755)

package/tests/run-tests.sh

@@ -136,6 +136,15 @@ case "${CLAUDE_CODE_OAUTH_TOKEN:-}" in
       *) echo "Failed to authenticate. API Error: 401 OAuth access token is invalid." >&2; exit 1 ;;
     esac ;;
 esac
+if [ -f "$ctl" ] && grep -qx "brokencli:$acct" "$ctl" 2>/dev/null; then
+  # An infrastructure fault, not a login verdict: the CLI never reached the API.
+  # Verbatim from my-mini, 2026-09-10. Note it carries no auth vocabulary at all
+  # — the danger is that AUTH_ERR matches a bare `401`, and a node stack frame
+  # or a version string can contain one.
+  echo "Error: Missing optional dependency @openai/codex-darwin-arm64. Reinstall Codex: npm install -g @openai/codex@latest" >&2
+  echo "    at findCodexExecutable (file:///opt/homebrew/lib/node_modules/@openai/codex/bin/codex.js:107:9)" >&2
+  exit 1
+fi
 case " $* " in
   *" -p --output-format text --max-turns 1 "*) echo "OK"; exit 0 ;;
 esac
@@ -3898,6 +3907,27 @@ check "import rejects an API key as token" "not a subscription setup-token" "$ou
 out="$(printf 'sk-ant-api03-ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ' | claude-accounts mint acct-01 --paste 2>&1)"
 check "mint --paste rejects an API key" "not a subscription setup-token" "$out"
 
+# ---- 17a2. a CLI that cannot run is not a dead login ----------------------------------
+# health.log 2026-08-24T06:37:02Z: all four accounts FAIL rc=127
+# err='env: node: No such file or directory'. One broken PATH reddened the whole
+# verify matrix, and it escaped parking only because that string happens not to
+# match AUTH_ERR — which matches a bare `401`, so a node stack frame carrying one
+# is enough. `mark_expired` writes no soft stamp, so such a park is permanent,
+# and the panel then refuses to re-import the token until its fingerprint changes.
+rm -f "$ACC/acct-01/.expired"
+printf 'brokencli:acct-01\n' > "$WORK/ctl-brokencli"
+out="$(FAKE_CTL="$WORK/ctl-brokencli" claude-accounts verify 2>&1)"
+check "a broken CLI is reported as a machine fault" "cannot run on this machine" "$out"
+check "a broken CLI still fails the account" "acct-01" "$out"
+[ ! -f "$ACC/acct-01/.expired" ] \
+  && t_ok "a broken CLI never parks a live login" \
+  || t_fail "broken CLI parking" "verify parked an account over an infrastructure fault"
+case "$out" in
+  *"login is dead"*) t_fail "broken CLI wording" "verify blamed the login for a machine fault" ;;
+  *) t_ok "a broken CLI is not called a dead login" ;;
+esac
+rm -f "$WORK/ctl-brokencli"
+
 # ---- 17b. verify authenticates the way the SHIM would ---------------------------------
 # A dead credential next to a live portable token: the shim runs that account with the
 # TOKEN, so verify must too — testing it with the dead credential would fail a healthy

package/tests/test_packaged_commands.py

@@ -0,0 +1,170 @@
+"""Exercise documented commands from npm's actual bin links, without shell rc files."""
+
+import json
+from pathlib import Path
+import plistlib
+import re
+import shlex
+import shutil
+import unittest
+
+from packaged_command_support import ROOT, install_package, run, seed_pools
+
+
+@unittest.skipUnless(shutil.which("node") and shutil.which("npm"), "Node/npm required")
+class PackagedCommandsTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        install_package(cls)
+
+    def test_global_commands_work_without_postinstall_or_shell_rc(self):
+        for command in ("claude-multiacc", "claude-accounts", "codex-accounts", "multiacc-select"):
+            with self.subTest(command=command):
+                resolved = shutil.which(command, path=self.env["PATH"])
+                self.assertEqual(resolved, str(self.prefix / "bin" / command))
+                flag = "--version" if command == "multiacc-select" else "--help"
+                result = run([command, flag], self.env, self.work)
+                self.assertEqual(result.returncode, 0, result.stderr)
+        for shell in ("bash", "zsh"):
+            if not shutil.which(shell):
+                continue
+            result = run([shell, "-fc", "codex-accounts verify --help"], self.env, self.work)
+            self.assertEqual(result.returncode, 0, result.stderr)
+        for command in ("claude-accounts", "codex-accounts"):
+            result = run([command, "list"], self.env, self.work)
+            self.assertNotEqual(result.returncode, 0)
+            self.assertIn("run claude-multiacc install first", result.stderr)
+
+    def test_every_account_help_command_dispatches_directly_and_via_wrapper(self):
+        for provider in ("claude", "codex"):
+            direct = f"{provider}-accounts"
+            help_result = run([str(self.package / "bin" / direct), "--help"], self.env, self.work)
+            verbs = set(re.findall(rf"^  {direct} ([a-z-]+)", help_result.stdout, re.MULTILINE))
+            self.assertGreaterEqual(len(verbs), 18)
+            wrapper = ["claude-multiacc"] + (["codex"] if provider == "codex" else [])
+            for prefix in ([direct], wrapper):
+                for verb in sorted(verbs):
+                    with self.subTest(prefix=prefix, verb=verb):
+                        result = run(prefix + [verb, "--help"], self.env, self.work)
+                        self.assertEqual(result.returncode, 0, result.stderr)
+                        self.assertIn(f"{direct} {verb}", result.stdout)
+                result = run(prefix + ["not-a-command", "--help"], self.env, self.work)
+                self.assertNotEqual(result.returncode, 0)
+
+    def test_wrapper_and_installer_help_have_no_side_effects(self):
+        before = sorted(str(path) for path in self.home.rglob("*"))
+        for verb in ("help", "install", "update", "uninstall", "doctor", "self-update", "codex", "select"):
+            with self.subTest(verb=verb):
+                result = run(["claude-multiacc", verb, "--help"], self.env, self.work)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertRegex(result.stdout, r"(?i)usage")
+        result = run([str(self.package / "install.sh"), "--help"], self.env, self.work)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(before, sorted(str(path) for path in self.home.rglob("*")))
+
+    def test_verify_and_json_reports_use_the_correct_pool(self):
+        seed_pools(self)
+        for provider in ("claude", "codex"):
+            wrapper = ["claude-multiacc"] + (["codex"] if provider == "codex" else [])
+            for prefix in ([f"{provider}-accounts"], wrapper):
+                for verb in ("list", "status"):
+                    result = run(prefix + [verb, "--json"], self.env, self.work)
+                    self.assertEqual(result.returncode, 0, result.stderr)
+                    self.assertEqual(json.loads(result.stdout)["provider"], provider)
+                for flags, expected in ((["--quick"], ": OK"), ([], ": PASS")):
+                    result = run(prefix + ["verify"] + flags, self.env, self.work)
+                    self.assertEqual(result.returncode, 0, result.stderr)
+                    self.assertIn(f"{provider}@example.test{expected}", result.stdout)
+
+    def test_self_update_uses_the_running_install_prefix(self):
+        fake_npm = self.prefix / "bin/npm"
+        original = fake_npm.read_text()
+        fake_npm.write_text('#!/usr/bin/env bash\n'
+                            'if [ "$1" = view ]; then echo 999.0.0; exit 0; fi\n'
+                            'printf "%s\\n" "$@" > "$HOME/update-args"\nexit 42\n')
+        fake_npm.chmod(0o755)
+        try:
+            result = run(["claude-multiacc", "self-update"], self.env, self.work)
+            self.assertNotEqual(result.returncode, 0)
+            args = (self.home / "update-args").read_text().splitlines()
+            self.assertEqual(args, ["install", "-g", "--prefix", str(self.prefix), "claude-multiacc@latest"])
+        finally:
+            fake_npm.write_text(original)
+
+    def test_git_and_npx_path_entrypoint_matches_npm(self):
+        entrypoint = self.package / "bin/claude-multiacc"
+        self.assertTrue(entrypoint.is_file())
+        result = run([str(entrypoint), "--version"], self.env, self.work)
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertEqual(result.stdout.strip(), json.loads((self.package / "package.json").read_text())["version"])
+
+    def test_installer_is_idempotent_and_instances_leave_system_commands_alone(self):
+        uname = self.prefix / "bin/uname"
+        identity = self.prefix / "bin/id"
+        uname.write_text('#!/usr/bin/env bash\necho Darwin\n')
+        identity.write_text('#!/usr/bin/env bash\necho 0\n')
+        uname.chmod(0o755)
+        identity.chmod(0o755)
+        try:
+            for _ in range(2):
+                result = run(["claude-multiacc", "install", "--no-server", "--no-schedule"], self.env, self.work)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                self.assertNotIn("status |", result.stdout)
+            for rc in (".zshenv", ".zprofile", ".zshrc"):
+                self.assertEqual((self.home / rc).read_text().count("# >>> claude-multiacc >>>"), 1)
+            calls = (self.home / "tool-calls").read_text()
+            self.assertNotRegex(calls, r"/(launchctl|crontab|ln) ")
+            script = 'source "$0" --no-server --no-schedule; mac_schedule_install'
+            result = run(["bash", "-c", script, str(self.package / "install.sh")], self.env, self.work)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            plists = list((self.home / "Library/LaunchAgents").glob("*.plist"))
+            self.assertEqual(len(plists), 5)
+            for path in plists:
+                job = plistlib.loads(path.read_bytes())
+                self.assertIn("PATH", job["EnvironmentVariables"])
+                self.assertTrue(Path(job["ProgramArguments"][0]).is_file())
+            result = run(["claude-multiacc", "uninstall"], self.env, self.work)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertNotIn("claude-multiacc", (self.home / ".zshrc").read_text())
+            self.assertTrue((self.home / ".codex-accounts/accounts.json").exists())
+            uname.write_text('#!/usr/bin/env bash\necho Linux\n')
+            (self.home / "tool-calls").write_text("")
+            args = ["install", "--instance", "sandbox", "--no-server", "--no-schedule"]
+            result = run(["claude-multiacc"] + args, self.env, self.work)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertNotIn("/ln ", (self.home / "tool-calls").read_text())
+        finally:
+            uname.unlink()
+            identity.unlink()
+
+    def test_selector_transport_and_version_match_across_entrypoints(self):
+        expected = None
+        for prefix in (["multiacc-select"], ["claude-multiacc", "select"]):
+            version = run(prefix + ["--version"], self.env, self.work)
+            self.assertEqual(version.returncode, 0, version.stderr)
+            result = run(prefix + ["--request-json", "-", "--response-json", "-"], self.env, self.work, input="{}")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            response = json.loads(result.stdout)
+            self.assertEqual(response["selector_version"], version.stdout.strip())
+            self.assertEqual(response["error_code"], "invalid_request")
+            if expected is not None:
+                self.assertEqual(response, expected)
+            expected = response
+
+    def test_documented_shell_examples_parse_and_command_names_exist(self):
+        documents = [ROOT / "README.md", *sorted((ROOT / "docs").glob("*.md"))]
+        for document in documents:
+            for block in re.findall(r"```(?:bash|sh)\n(.*?)```", document.read_text(), re.DOTALL):
+                result = run(["bash", "-n"], self.env, self.work, input=block)
+                self.assertEqual(result.returncode, 0, f"{document.name}: {result.stderr}")
+                for line in block.splitlines():
+                    tokens = shlex.split(line, comments=True)
+                    if not tokens or tokens[0] not in ("claude-accounts", "codex-accounts", "claude-multiacc"):
+                        continue
+                    self.assertNotIn("|", tokens, f"{document.name}: alternatives must be separate commands")
+                    self.assertIsNone(re.search(r"--[a-z-]+#", line), line)
+                    self.assertIsNotNone(shutil.which(tokens[0], path=self.env["PATH"]), line)
+
+
+if __name__ == "__main__":
+    unittest.main()