claude-multiacc 2.0.27 → 2.0.29

package/docs/VERIFICATION.md

@@ -0,0 +1,68 @@
+# Verification and troubleshooting
+
+## Verification
+
+```bash
+tests/run-tests.sh            # sandboxed compatibility tests, no quota
+python3 tests/test_selector.py # unified selector contract
+npm run test:commands         # packed npm commands; run npm install --ignore-scripts first
+claude-accounts verify        # real matrix: `claude -p "reply OK"` per authed account
+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)
+```
+
+Verified end-to-end on both machines (2026-07-13): full matrix PASS, 20-invocation shim
+spread clean, real project `-p` through the shim OK on Mac (`~/pipeline`) and server
+(`/opt/inapp-onboarding`), uninstall→stock→reinstall roundtrip byte-identical, three
+server systemd services (`vpn-server-management`, `inapp-onboarding`, `vpn-seo-panel`)
+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`).
+- **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).
+- **"Failed to authenticate: OAuth session expired and could not be refreshed"** — the
+  login behind that run is dead. Run `claude-accounts expired` to see which, then
+  `claude-accounts relogin`. Accounts in that state are excluded from selection
+  automatically, so this only surfaces when *every* account needs a re-login (the shim
+  then falls back to the machine's own `~/.claude` login) or when it was pinned with
+  `CLAUDE_ACCOUNT`.
+- **"Please run /login · API Error: 401 OAuth access token is invalid"** — the portable
+  setup-token is rejected even though its presence and `claude auth status` look healthy.
+  The shim now runs a private first-use inference, parks a rejected token, and reselects
+  before direct, TUI, or `--resume` work sees the 401. Run `claude-accounts verify` to
+  check every token immediately; `claude-accounts expired` reports token-only accounts
+  as `UNVERIFIED` until that proof exists.
+- **Everything marked limited** — the shim still runs: the still-serving limited accounts
+  go through the same two cuts (session gate, then strict best-weekly) and one is handed
+  out anyway; check `selection.log` for `all-limited fallback=` lines.
+- **Sync fails** — `tail ~/.claude-accounts/sync.log`; it's ssh/rsync to the manifest's
+  `server` (BatchMode — needs key auth).
+- **A service bypasses the shim** — it spawns an absolute path. Point its env
+  (`CLAUDE_BIN` etc.) at `/usr/local/bin/claude`. Docker-internal `claude` installs
+  (e.g. openclaw live-test containers) are out of scope for a host shim.
+- **`add` sign-in says "Sign in again to continue"** — that's Claude's step-up
+  authentication, not a tool error: granting a long-lived token needs a *recent* sign-in.
+  Open a fresh incognito window, sign in to the target account at claude.ai **first**,
+  then paste the link and approve. The approval scope is `user:inference`
+  (*"Contribute to your Claude subscription usage"*) — that's correct and minimal.
+- **Limits look stale** — launchd: `launchctl list | grep claude-multiacc`;
+  cron: `crontab -l | grep claude-multiacc`. The shim also kicks a refresh when data
+  is >3 min old.
+
+## Security notes & known risks
+
+- Tokens and credentials live as 0600 files under `~/.claude-accounts` (and
+  `/root/.claude-accounts` on the server). Server compromise = account access.
+- `selection.log` records timestamps/account/cwd only — never prompt text.
+- Rotating multiple subscriptions to spread usage may be flagged by anti-abuse systems;
+  accounts can be banned for limit circumvention. Known and accepted by the operator.
+- The usage endpoint is the internal one `/usage` consumes; if it changes shape, limit
+  tracking fails open (accounts stay available, error-retry is the backstop).

package/install.sh

@@ -20,6 +20,7 @@ set -u
 REPO_DIR="$(cd "$(dirname "$0")" && pwd -P)"
 # shellcheck source=lib/common.sh
 . "$REPO_DIR/lib/common.sh"
+. "$REPO_DIR/lib/install_actions.sh"
 # common.sh is sourced in claude mode (ACC_ROOT = the claude pool); the codex pool
 # root is needed here too for the codex agents and uninstall/purge messaging.
 CODEX_ACC_ROOT="${CODEX_ACCOUNTS_ROOT:-${CODEX_ACCOUNTS_DIR:-$HOME/.codex-accounts}}"
@@ -31,6 +32,7 @@ NO_SCHEDULE=0
 INSTANCE_OVERRIDE=""
 while [ $# -gt 0 ]; do
   case "$1" in
+    --help|-h) cat "$REPO_DIR/lib/install-help.txt"; exit 0 ;;
     --uninstall) UNINSTALL=1; shift ;;
     --purge-data) PURGE=1; shift ;;
     --server) SERVER_OVERRIDE="${2:?--server requires a value}"; shift 2 ;;
@@ -127,50 +129,9 @@ cron_env_prefix() {
   printf "CLAUDE_ACCOUNTS_ROOT='%s' CODEX_ACCOUNTS_ROOT='%s' " "$ACC_ROOT" "$CODEX_ACC_ROOT"
 }
 
-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"
-}
-
 mac_schedule_install() {
   mkdir -p "$HOME/Library/LaunchAgents"
+  . "$REPO_DIR/lib/install_calendar.sh"
   cat > "$PLIST_LIMITS" <<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">
@@ -183,52 +144,12 @@ mac_schedule_install() {
   </array>
 $(plist_env_block)  <key>StartInterval</key><integer>900</integer>
   <key>RunAtLoad</key><true/>
-  <!-- The pass hands its readings to the peers from a detached push; launchd
-       must not kill that push with the job's process group. -->
+  <!-- Preserve the detached telemetry push after this job exits. -->
   <key>AbandonProcessGroup</key><true/>
   <key>StandardOutPath</key><string>/dev/null</string>
   <key>StandardErrorPath</key><string>/dev/null</string>
 </dict></plist>
 EOF
-  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
-  # Daily auto-update (04:07). No-op unless this is an npm or git install.
-  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
-  # Codex pool: its own limits/health agents, so either provider's telemetry can
-  # fail or be removed without touching the other's.
   cat > "$PLIST_CODEX_LIMITS" <<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">
@@ -246,30 +167,11 @@ $(plist_env_block)  <key>StartInterval</key><integer>300</integer>
   <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
-  launchctl unload "$PLIST_LIMITS" 2>/dev/null || true
-  launchctl unload "$PLIST_HEALTH" 2>/dev/null || true
-  launchctl unload "$PLIST_UPDATE" 2>/dev/null || true
-  launchctl unload "$PLIST_CODEX_LIMITS" 2>/dev/null || true
-  launchctl unload "$PLIST_CODEX_HEALTH" 2>/dev/null || true
-  launchctl load -w "$PLIST_LIMITS" 2>/dev/null || echo "  (launchctl load limits agent failed — limits refresh will rely on the shim's opportunistic kick)"
+  local plist
+  for plist in "$PLIST_LIMITS" "$PLIST_HEALTH" "$PLIST_UPDATE" "$PLIST_CODEX_LIMITS" "$PLIST_CODEX_HEALTH"; do
+    launchctl unload "$plist" 2>/dev/null || true
+  done
+  launchctl load -w "$PLIST_LIMITS" 2>/dev/null || echo "  (limits agent failed — the shim will refresh on demand)"
   launchctl load -w "$PLIST_HEALTH" 2>/dev/null || true
   launchctl load -w "$PLIST_CODEX_LIMITS" 2>/dev/null || true
   launchctl load -w "$PLIST_CODEX_HEALTH" 2>/dev/null || true
@@ -317,183 +219,6 @@ linux_schedule_remove() {
   rm -f "$tmp"
 }
 
-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.
-  # Removing them here would disable the operator's shim while only one instance was
-  # being uninstalled, so an instance removes exactly its own agents.
-  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"
-}
-
-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
-
-  [ -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 yet — install Claude Code first (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 — the codex pool stays idle until Codex CLI is installed (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
-
-  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
-
-  # 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
-    # .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
-    [ "$NO_SCHEDULE" = "1" ] || mac_schedule_install
-  else
-    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 [ "$(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
-    [ "$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 | codex-accounts status    # auth + limits detail"
-}
-
 if [ "$UNINSTALL" = "1" ]; then
   do_uninstall
 else

package/lib/install-help.txt

@@ -0,0 +1,20 @@
+USAGE
+  claude-multiacc install [options]
+  ./install.sh [options]
+  claude-multiacc uninstall [--purge-data]
+  ./install.sh --uninstall [--purge-data]
+
+OPTIONS
+  --server user@host   set the sync target
+  --no-server          use local-only pools
+  --instance NAME      label this instance's scheduled jobs
+  --no-schedule        install without scheduled jobs
+  --uninstall          remove shell setup and jobs; keep account data
+  --purge-data         also delete both account pools when uninstalling
+  -h, --help           show this help without installing or uninstalling
+
+Use CLAUDE_ACCOUNTS_ROOT and CODEX_ACCOUNTS_ROOT to select isolated pools.
+After npm install -g claude-multiacc, both claude-accounts and codex-accounts
+are available alongside claude-multiacc in npm's bin directory immediately.
+Git/npx installs add the package's bin directory through shell startup files;
+open a new shell or use the export PATH command printed by the installer.