claude-multiacc 2.0.26 → 2.0.28

package/docs/INSTALLATION.md

@@ -0,0 +1,91 @@
+# Install / update / uninstall
+
+### npm (recommended)
+
+```bash
+npm install -g claude-multiacc     # postinstall wires up the shim, CLI, and scheduled jobs
+# or run it once without installing globally:
+npx claude-multiacc
+```
+
+`claude-multiacc` then wraps everything:
+
+```bash
+claude-multiacc                    # install or update the addon (idempotent)
+claude-multiacc self-update        # update the running installation + re-install
+claude-multiacc list               # Claude pool, via claude-accounts
+claude-multiacc codex list         # Codex pool, via codex-accounts
+claude-multiacc doctor             # status for both pools
+claude-multiacc install --help     # installer options
+claude-multiacc uninstall          # keep both account pools
+# To delete both pools as well: claude-multiacc uninstall --purge-data
+```
+
+After `claude-multiacc uninstall`, `npm uninstall -g claude-multiacc` also removes
+the npm package and its command links.
+
+npm links `claude-multiacc`, `claude-accounts`, `codex-accounts`, and `multiacc-select`
+into its global bin directory. If `claude-multiacc` works, both account commands work
+in that same shell, even when postinstall was skipped. The `claude` and `codex` shims
+still need the installer's PATH setup: open a new shell after installation.
+
+If an older installation says `codex-accounts: command not found`, update it:
+
+```bash
+npm install -g claude-multiacc@latest
+codex-accounts verify
+```
+
+Before updating, `claude-multiacc codex verify` runs the same verification through
+the existing npm wrapper. For git/npx installs, open a new shell or run the exact
+`export PATH=...` command printed by the installer. Run `claude-multiacc install`
+if auto-setup was skipped and the pool has no manifest yet.
+
+**Automatic updates:** a globally-installed package re-runs `install.sh` from its own
+postinstall, so `npm i -g claude-multiacc@latest` fully updates the shim, CLI, and jobs.
+A daily job (launchd on macOS, cron on Linux, 04:07) runs `claude-accounts self-update`
+to pull the latest release on its own — `npm i -g claude-multiacc@latest` for npm installs,
+`git pull && ./install.sh` for git checkouts; set `CLAUDE_MULTIACC_AUTOUPDATE=0` before install to
+opt out. `update-notifier` also prints a one-line nudge when a newer version is on npm.
+(Note: newer npm versions gate install scripts; if postinstall is blocked, just run
+`claude-multiacc install` once.)
+
+New versions publish to npm automatically from `main` via GitHub Actions
+(`.github/workflows/publish.yml`, OIDC Trusted Publishing — no long-lived token after the
+first bootstrap publish; `scripts/auto-version.mjs` bumps the patch above the last release).
+
+### From a git checkout
+
+```bash
+git clone https://github.com/gowalk-public/claude-multiacc.git
+cd claude-multiacc
+./install.sh                                           # macOS or Linux, idempotent
+./install.sh --server root@1.2.3.4                        # override sync target
+git pull && ./install.sh                                  # update (data untouched)
+./install.sh --uninstall                # restores stock behavior, keeps account data
+./install.sh --uninstall --purge-data   # also deletes both account pools
+```
+
+`self-update` auto-detects which of these you used (npm global vs git checkout).
+
+**Servers / machines without repo access:** install via **npm** — the registry is
+public, so the daily self-update needs no credentials at all (no rsync, no keys).
+A git checkout self-updates too, but only if `git pull` can authenticate; for a
+private repo on a server that means a read-only deploy key (the 138 server runs
+this way: `core.sshCommand` pinned to its deploy key). A plain copied tree is the
+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` +
+  `.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
+  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/UNIFIED_SELECTOR.md

@@ -13,6 +13,8 @@ multiacc-select --request-json - --response-json -
 
 The command reads one UTF-8 JSON object from stdin and writes one JSON object to
 stdout. `multiacc-select --version` reports the selector contract version.
+`multiacc-select --help` (or `-h`) prints usage and exits successfully without
+reading stdin. All three forms also work through `claude-multiacc select`.
 
 The request schema is `claude-multiacc/pool-selection.v2` and contains:
 

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/common.sh

@@ -588,12 +588,101 @@ os.replace(sys.argv[1] + '.tmp', sys.argv[1])
 PYEOF
 }
 
+# ---- one index for the shared session tree -----------------------------------------
+# codex refuses to start until its rollout index (state_<schema>.sqlite) has been
+# backfilled from every rollout under $CODEX_HOME/sessions. The codex layout shares that
+# tree across accounts (<acct>/sessions -> ~/.codex/sessions), so the index is shared
+# the same way: <acct>/state_N.sqlite -> ~/.codex/state_N.sqlite. Otherwise every new
+# account re-reads the whole tree (10 GB on a busy Mac) before its first launch, and a
+# launch that meets another process's unfinished scan dies after 30 s with the CLI's
+# "local database appears to be damaged" message. bin/codex applies the same at every
+# launch (and pre-links the name the installed binary will create); seeding covers a
+# CODEX_HOME handed straight to the real binary. The two CORE functions below are
+# byte-identical with bin/codex — tests/run-tests.sh diffs them.
+# CORE — byte-identical in bin/codex; tests diff them.
+state_index_names() { # $1 acct dir, $2 home dir -> the index file names either side holds
+  local f name seen=" "
+  for f in "$2"/state_[0-9]*.sqlite "$1"/state_[0-9]*.sqlite; do
+    [ -e "$f" ] || [ -L "$f" ] || continue          # an unmatched glob is the pattern itself
+    name="${f##*/}"
+    case "$seen" in *" $name "*) continue ;; esac
+    seen="$seen$name "
+    printf '%s\n' "$name"
+  done
+}
+
+# CORE — byte-identical in bin/codex; tests diff them.
+shared_index_rejected() { # $1 acct dir, $2 index name, $3 shared target
+  # True when codex's own corruption recovery moved THIS account's link out of the way:
+  # it renames the database it judged damaged (and its -wal/-shm) into
+  # <CODEX_HOME>/db-backups/sqlite-<ts>-<n>/ and rebuilds, and under a link that renames
+  # the LINK. A link sitting in there pointing at the shared file is codex's verdict on
+  # that file, so this account keeps the index codex rebuilt for it and this name is
+  # left alone — handing the link back would hand the damage back.
+  local marker
+  for marker in "$1"/db-backups/*/"$2"; do
+    [ -L "$marker" ] || continue
+    [ "$(readlink "$marker" 2>/dev/null)" = "$3" ] && return 0
+  done
+  return 1
+}
+
+# CORE — byte-identical in bin/codex; tests diff them.
+share_state_index_links() { # $1 acct dir, $2 home dir, $3 extra index name ('' for none)
+  local d="$1" home="$2" name names target link retired n
+  [ -L "$d" ] && return 0                              # adopted: the dir IS the home
+  [ -L "$d/sessions" ] || return 0                     # a private tree keeps its private index
+  [ "$(readlink "$d/sessions" 2>/dev/null)" = "$home/sessions" ] || return 0
+  [ -d "$home" ] || return 0
+  names="$(state_index_names "$d" "$home")"
+  case "${3:-}" in ''|*[!A-Za-z0-9_.]*) ;; *) names="$names $3" ;; esac
+  for name in $names; do
+    target="$home/$name"; link="$d/$name"
+    [ -L "$link" ] && continue                         # already shared (or pointed elsewhere on purpose)
+    shared_index_rejected "$d" "$name" "$target" && continue
+    if [ ! -e "$link" ]; then
+      ln -s "$target" "$link" 2>/dev/null || true      # a new account: the whole point
+      continue
+    fi
+    # This account has an index of its own, and MOVING one that a process can still open
+    # is unsafe. codex holds the state database through an sqlx pool that opens its
+    # connections lazily and BY PATH (max_connections(5), create_if_missing(true) —
+    # codex-rs/state/src/sqlite.rs open_read_write_pool), so a rename under a live holder
+    # leaves connection 1 on the old inode while every connection the pool opens
+    # afterwards follows the new link: one process, two databases. A -wal or a -shm beside
+    # the file is that proof. A codex killed mid-write leaves them behind too, and the
+    # next clean session on the account removes them, so this heals itself in time.
+    { [ -e "$link-wal" ] || [ -e "$link-shm" ]; } && continue
+    if [ -e "$target" ]; then
+      retired="$link.private"; n=0                     # never overwrite an earlier copy
+      while [ -e "$retired" ] && [ "$n" -lt 100 ]; do n=$((n+1)); retired="$link.private.$n"; done
+      [ -e "$retired" ] && continue
+      mv "$link" "$retired" 2>/dev/null || continue
+    else
+      # Atomic or nothing: link(2) refuses an existing target, so two shims racing to be
+      # the first to promote cannot rename one's fresh symlink onto the file the other
+      # just promoted — which is how a self-referential shared index (ELOOP, and every
+      # account on the Mac unable to start) could appear. A cross-device link simply
+      # fails and this account keeps its own index.
+      ln "$link" "$target" 2>/dev/null || continue
+      [ -L "$link" ] || rm -f "$link"
+    fi
+    ln -s "$target" "$link" 2>/dev/null || true
+  done
+  return 0
+}
+
+codex_share_state_index() { # $1 acct dir — seed time: whatever index names exist already
+  share_state_index_links "$1" "${HOME:-/nonexistent}/.codex" ""
+}
+
 # Seed an account config dir so headless runs never prompt.
 #   claude: stripped .claude.json, copied settings.json, shared projects/ symlink
 #           (shared history => --continue/--resume work regardless of picked account).
 #   codex:  copied config.toml (carries project trust + settings, no identity),
-#           shared sessions/ symlink (=> `codex resume` finds every session), and a
-#           shared AGENTS.md symlink so global instructions apply under any account.
+#           shared sessions/ symlink (=> `codex resume` finds every session) with the
+#           shared rollout index that tree needs, and a shared AGENTS.md symlink so
+#           global instructions apply under any account.
 seed_account_dir() { # $1 = acct dir
   local d="$1"
   mkdir -p "$d"
@@ -608,6 +697,7 @@ seed_account_dir() { # $1 = acct dir
     if [ ! -e "$d/AGENTS.md" ] && [ -f "$HOME/.codex/AGENTS.md" ]; then
       ln -s "$HOME/.codex/AGENTS.md" "$d/AGENTS.md" 2>/dev/null || true
     fi
+    codex_share_state_index "$d"
     return 0
   fi
   if [ ! -f "$d/.claude.json" ] && [ -f "$HOME/.claude.json" ]; then

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.