claude-multiacc 1.0.0

package/CLAUDE_ACCS_TASK.md

@@ -0,0 +1,236 @@
+# claude-multiacc — Multi-Account Claude Code Addon (random account + server sync)
+
+**Goal:** every `claude` / `claude -p` invocation runs under a randomly picked account
+(~10 Claude **subscription** accounts — no API keys, ever). Account set mirrors
+automatically to the deploy server `root@138.197.36.107` on every add/remove.
+`claude -p` must work in 100% of cases on both machines.
+
+**Packaging requirement (added 2026-07-13):** ship as an **installable addon from this
+git repo** for macOS + Linux that **never touches the original Claude Code app**, so the
+app keeps working and updating exactly as-is.
+
+**Limit-aware selection requirement (added 2026-07-13):** the shim must be smart about
+usage limits — pick only accounts that still have limit headroom; when ANY limit bucket
+of an account reaches **≥90% utilization**, the account gets marked and excluded from the
+random pool until that bucket resets. **Fable model limits must be tracked as their own
+bucket** (not just the 5-hour session limit): a Fable weekly bucket at ≥90% marks the
+account even if session limit is fine. Subscription accounts only — limits are read via
+each account's own OAuth usage endpoint, never via API keys.
+
+**Status:** IMPLEMENTED & VERIFIED 2026-07-13 — all phases complete on both machines.
+See README.md (tested reality). Deltas from plan, decided during implementation:
+- **Account discovery result:** exactly 2 unique accounts exist across the fleet —
+  support@gowalkae.com (Mac default login) and hasan@gowalkqa.com (server default
+  login, found in /root/.claude). No dead credentials found anywhere.
+- **`adopt` mechanism (new):** an existing machine login joins the pool as a dir
+  symlink to ~/.claude — single credential file, zero grant-fork/refresh-race risk.
+  Used for acct-01 (Mac) and acct-02 (server).
+- **Asymmetric pools:** each machine's pool = accounts valid on THAT machine. Adding a
+  fresh account (`claude-accounts add`) now shows a sign-in link and captures a
+  subscription setup-token that works on BOTH machines, so new accounts are symmetric;
+  the two adopted accounts stay home-bound by design.
+- **Auto-retry decision:** ON by default for -p, gated to finite stdin (tty/regular
+  file//dev/null) so service-spawned pipes can never hang; CLAUDE_SHIM_RETRY=0 disables.
+- **Server call sites fixed:** CLAUDE_BIN=/usr/local/bin/claude in
+  vpn-server-management, inapp-onboarding, vpn-seo (.env backups kept), services
+  restarted healthy. /root/poll.sh pgrep kept working (shim execs the symlink path).
+- Adversarially reviewed (11-agent workflow): fail-open on unset HOME, sync
+  mass-delete guards, atomic manifest writes, cooldown persistence all fixed + tested.
+
+Original plan below. Verified facts from planning:
+- This Mac stores Claude Code credentials per-config-dir in files (`.credentials.json`),
+  NOT in macOS Keychain (tested 2026-07-13, Claude Code 2.1.207) → per-dir logins coexist.
+- `CLAUDE_CONFIG_DIR` isolation confirmed working on this Mac (isolated dir = "Not logged in").
+- Real binary: `~/.local/bin/claude`. Interactive `claude` is a zsh alias adding
+  `--dangerously-skip-permissions` (kept; it composes with the shim via PATH).
+- Current login: support@gowalkae.com (Claude Max) → becomes `acct-01`.
+
+---
+
+## Addon requirement — analysis & design decisions
+
+**Feasibility:** clean. The whole mechanism uses only documented, version-stable
+interfaces — PATH resolution, `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_OAUTH_TOKEN` — so the
+addon needs zero modifications to the app and is agnostic to Claude Code versions.
+
+**Non-invasive guarantees (hard rules):**
+1. Never writes to the Claude Code binary, its install dir, npm/native update machinery,
+   or the contents of `~/.claude` app files. (Exception: the shared-history design
+   symlinks *into* `~/.claude/projects` — user data, not app files.)
+2. Shim resolves the real binary **dynamically at exec time** (next `claude` on PATH
+   after itself; fallback to known locations `~/.local/bin/claude`,
+   `/usr/local/bin/claude.real-candidates`) → survives `claude update`, reinstalls, and
+   install-location changes. No hardcoded paths baked at install time.
+3. Everything the addon creates lives in exactly three places, all reversible:
+   - the cloned repo itself (code)
+   - `~/.claude-accounts/` (account data: manifest, per-acct config dirs, tokens, logs)
+   - one marked PATH block in shell rc (`~/.zshenv` on macOS, `~/.bashrc` +
+     `/etc/profile.d/claude-multiacc.sh` on Linux) and, on Linux servers,
+     a shim at `/usr/local/bin/claude` (shadows via PATH order; original untouched)
+4. `install.sh --uninstall` removes all of the above (accounts dir only with
+   `--purge-data`), restoring stock behavior byte-for-byte.
+
+**Install / update UX:**
+```
+git clone <repo> && cd claude-multiacc && ./install.sh     # macOS or Linux, idempotent
+git pull && ./install.sh                                    # addon update (data untouched)
+./install.sh --uninstall [--purge-data]                     # full removal
+```
+
+**Portability:** shim + CLI written for bash 3.2 (macOS stock) and bash 4+ (Linux);
+no GNU-only flags; server mode auto-detected (root/Linux → /usr/local/bin shim,
+systemd-compatible PATH placement).
+
+## Repo layout
+
+```
+claude-multiacc/
+  install.sh            idempotent installer/uninstaller, macOS + Linux
+  bin/claude            the shim (PATH-shadows the real binary, never replaces it)
+  bin/claude-accounts   helper CLI: list|status|add|import|remove|mint|sync|verify|limits
+  lib/common.sh         shared functions (account discovery, manifest, rsync filters)
+  CLAUDE_ACCS_TASK.md   this plan
+  README.md             REQUIRED DELIVERABLE — written when implementation completes
+```
+
+## Architecture
+
+```
+MAC (source of truth)                      SERVER 138.197.36.107 (mirror)
+~/.claude-accounts/                        /root/.claude-accounts/
+  accounts.json  <- manifest                 accounts.json          (synced)
+  acct-01/ .. acct-NN/                       acct-NN/server.token   (synced, 600)
+    .credentials.json  (per-dir /login)      acct-NN/               (= CLAUDE_CONFIG_DIR, own history)
+    .claude.json, settings.json (seeded)   /usr/local/bin/claude -> repo shim
+    server.token       (setup-token)       /root/claude-multiacc/  (addon repo, git pull to update)
+    projects/ -> ~/.claude/projects
+  selection.log, sync.log
+```
+
+- **Mac auth:** normal `/login` per config dir (subscription OAuth; files coexist per-dir,
+  auto-refresh). NO API keys anywhere.
+- **Server auth:** per-account long-lived token from `claude setup-token` (subscription
+  feature, headless-safe, no refresh rotation → no token races between machines;
+  inference-only — fine, server only runs `claude -p`). We deliberately do NOT copy
+  `.credentials.json` to the server: two machines refreshing one OAuth refresh token can
+  invalidate each other → violates the 100% rule.
+- **Sync:** one-way Mac → server (Mac = source of truth): rsync `accounts.json` +
+  `acct-*/server.token` with delete-propagation, fired automatically at the end of
+  `claude-accounts add|remove` (and runnable manually via `claude-accounts sync`).
+  Addon code on the server updates via `git pull`, not via sync.
+
+## Shim selection logic (identical file on both machines)
+
+1. `CLAUDE_CONFIG_DIR` already set → pass straight through (scripts can pin).
+2. `CLAUDE_ACCOUNT=acct-03` set → use that account (even if limit-marked — explicit wins).
+3. Else pick uniformly at random among accounts with valid auth
+   (`.credentials.json` on Mac; `server.token` on server → also exports
+   `CLAUDE_CODE_OAUTH_TOKEN`) **that are not limit-marked** (no `.limited` marker).
+   If EVERY account is marked, fall back to the least-utilized account and log a warning —
+   degraded service beats a hard failure (the 100% rule).
+4. Append `timestamp account cwd` to `selection.log` (never prompt text); print NOTHING;
+   `exec` the dynamically-resolved real binary — stdin/stdout/exit codes pass through
+   byte-identically → `-p` pipe-safe.
+
+## Limit-aware selection (smart marking)
+
+- `claude-accounts limits` refreshes per-account usage by calling the account's OAuth
+  usage endpoint with that account's own subscription token (the same data `/usage`
+  shows: 5-hour session bucket, weekly bucket, and per-model-tier weekly buckets —
+  **Fable tracked as its own bucket**). Results cached in `acct-NN/limits.json`
+  (utilization % + reset time per bucket).
+- Marking rule: any bucket ≥ **90%** → create `acct-NN/.limited` (contains reason bucket
+  + reset timestamp). Marker auto-clears when the bucket's reset time passes or a refresh
+  shows utilization back under threshold.
+- Refresh cadence: cron/launchd every **1 min** on both machines (each machine queries
+  independently — usage is per-account global, so both see the same numbers), plus
+  opportunistic refresh when the shim notices a stale (>3 min) limits.json.
+- The usage endpoint is the one Claude Code itself uses for `/usage` (undocumented,
+  subscription-OAuth only — no API keys involved). It must be captured and validated
+  during implementation; if it ever breaks, the shim degrades gracefully: no fresh limit
+  data → treat account as available, rely on error-retry instead (never block work on
+  missing telemetry).
+
+## Phases
+
+### Phase 0 — Audit call sites (Mac + server)
+- Mac: grep all projects for `claude` invocations (shell scripts, package.json, Makefiles,
+  cron, launchd plists). Fix absolute-path calls and bare-`sh` minimal-PATH contexts to
+  resolve the shim. IDE/desktop integrations spawn the binary directly → list them
+  (they'll use the default account).
+- Server: same audit over /root, systemd units, crontabs, deploy scripts. Check whether
+  Claude Code is installed; if not, install it (official installer — the addon never
+  bundles or patches the app).
+
+### Phase 1 — Build the addon (this repo)
+Shim, `claude-accounts` CLI, `install.sh` (+ uninstall), lib. Bash 3.2-compatible.
+Commit to the repo; this repo IS the distribution artifact.
+
+### Phase 2 — Install on Mac + discover existing accounts
+- `./install.sh` → PATH block, `~/.claude-accounts/` skeleton, acct-01 = existing login.
+- **Local account discovery:** search for every credential this Mac has ever held —
+  `~/.claude/backups/`, `~/.claude.json*` (oauthAccount history), any `.credentials.json`
+  on disk, stray `CLAUDE_CONFIG_DIR` dirs. Dedupe by account email keeping the **latest**
+  auth per unique account; `claude-accounts import` each; validate each with
+  `claude auth status` + minimal `-p "reply OK"`. Report accounts found-but-dead
+  (need re-login) separately.
+- Seed each acct dir: copy current `.claude.json` (strip `oauthAccount`) + `settings.json`
+  → preserves project trust/onboarding so headless mode never prompts; symlink
+  `projects/` → `~/.claude/projects` (shared history/memory; `--continue`/`--resume`
+  work regardless of picked account).
+
+### Phase 3 — Auth ceremony (user, ~3-4 min per account, one-time)
+Per account, in ONE incognito browser window signed into that claude.ai account:
+1. `CLAUDE_ACCOUNT=acct-NN claude` → `/login` (press `c` to copy URL into incognito) →
+   `/status` confirms email.
+2. `claude-accounts mint acct-NN` (wraps `claude setup-token`) → second OAuth click →
+   token saved to `acct-NN/server.token` (600). This is the server credential.
+3. CLI verifies and records the email in `accounts.json`.
+
+### Phase 4 — Server bootstrap + sync
+- On server: `git clone` this repo → `./install.sh` (detects Linux/root → shim at
+  `/usr/local/bin/claude`, which precedes the real binary in login-shell AND systemd
+  default PATH; original binary untouched).
+- Mac: `claude-accounts sync` pushes manifest + tokens; add/remove auto-sync
+  (removals propagate). All syncs log to `sync.log`; non-zero exit = loud failure.
+- Post-sync hook re-runs the server verification matrix automatically.
+
+### Phase 5 — Verification (the 100% requirement)
+- Mac matrix: per acct dir → `claude auth status` + `claude -p "reply OK"` all pass.
+- Server matrix: per token → `claude -p "reply OK"` all pass.
+- Shim spread: ~20 invocations per machine → all accounts hit, zero failures.
+- Real-world: run one actual project `-p` command through the shim on each machine.
+- Non-invasiveness check: `claude update` / version check still works; uninstall on a
+  scratch account restores stock behavior.
+
+### Phase 6 — Ops + documentation
+- `claude-accounts status`: per-account email, Mac auth health, server token presence/age,
+  last-picked time.
+- Weekly health check (launchd on Mac, cron on server): full auth matrix; alert on any
+  failure so a dead account can't silently eat ~10% of `-p` calls.
+- Limits refresh every 1 min (launchd/cron) → `.limited` markers per the 90% rule;
+  `claude-accounts status` shows per-bucket utilization incl. the Fable bucket.
+- OAuth logins auto-refresh on use; `setup-token` tokens live ~1 year → health check
+  warns ahead; renewal = re-run `claude-accounts mint` for that account.
+- **README.md (required, written only once everything above is implemented AND tested):**
+  what it is, install (macOS/Linux), auth ceremony walkthrough, adding/removing accounts,
+  pinning (`CLAUDE_ACCOUNT`), server sync setup, verification commands, uninstall,
+  troubleshooting. README must reflect tested reality, not the plan.
+
+## Open decisions
+- [ ] **Auto-retry** (recommended): for `-p` invocations only, on auth/rate-limit error
+      patterns, retry once with a different random account; legit non-zero exits pass
+      through. Default on/off TBD (`CLAUDE_SHIM_RETRY`).
+- [ ] Final account count/names (user adds ~10 subscription accounts).
+- [ ] Server: does anything call `claude` on it today? (Phase 0 answers.)
+
+## Risks
+- Rotating ~10 subscriptions to spread usage is a pattern Anthropic anti-abuse may flag;
+  accounts can be banned for limit circumvention. Raised with user 2026-07-13.
+- Tokens on server are plain files under /root (600/700) — server compromise = account access.
+- `setup-token` tokens are inference-only (no Remote Control) — acceptable for `-p` usage.
+- macOS installs that store creds in Keychain (not this Mac) would break per-dir `/login`
+  isolation; the addon must detect this at install time and warn (token-based fallback).
+- The usage/limits endpoint is internal (what `/usage` consumes) and may change without
+  notice; limit tracking must fail OPEN (account treated available, retry logic as backstop)
+  so limits telemetry can never break the 100% `-p` guarantee.

package/README.md

@@ -0,0 +1,263 @@
+# claude-multiacc
+
+Multi-account addon for Claude Code: every `claude` / `claude -p` invocation runs under a
+randomly picked **subscription** account with limit headroom (no API keys, ever). The
+account set mirrors automatically from the Mac (source of truth) to the deploy server.
+
+Installs as a PATH shim + helper CLI from this repo. **Never touches the Claude Code app**:
+no binary edits, no install-dir writes, survives `claude update` — the real binary is
+resolved dynamically at exec time.
+
+Tested on: macOS (bash 3.2, zsh, Claude Code 2.1.207) and Ubuntu 24.04
+(bash 5.2, Claude Code 2.1.201). Test suite: `tests/run-tests.sh` (35 sandboxed tests,
+no network / no quota — passes on both platforms).
+
+---
+
+## How it works
+
+```
+MAC (source of truth)                      SERVER (mirror)
+~/.claude-accounts/                        /root/.claude-accounts/
+  accounts.json  <- manifest                 accounts.json          (synced)
+  acct-01 -> ~/.claude   ("adopted")         acct-01/server.token   (synced, 600, once minted)
+  acct-02/               (registered)        acct-02 -> /root/.claude ("adopted")
+    server.token / .credentials.json
+  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)
+```
+
+**Shim selection order** (identical file on both machines, `bin/claude`):
+
+1. `CLAUDE_CONFIG_DIR` or `CLAUDE_CODE_OAUTH_TOKEN` already set → pass straight through.
+2. `CLAUDE_ACCOUNT=acct-NN` → use that account (even if limit-marked — explicit wins).
+3. Among accounts valid **on this machine** (`.credentials.json` or `server.token`
+   present) and not excluded, pick the one with the **most remaining headroom** (see
+   below). Ties break randomly to spread load. `CLAUDE_SHIM_SELECT=random` restores plain
+   uniform-random selection.
+4. If every account is excluded → the highest-headroom valid account anyway + a warning
+   in `selection.log` (degraded beats down: the 100% rule).
+
+**Which account has "the most headroom"?** A Max subscription has three limits that a
+Fable request consumes at once: the 5-hour **session** bucket, the **weekly all-models**
+bucket, and the **weekly Fable** bucket. Anthropic's docs confirm these reset on very
+different horizons — the session bucket refills every ~5 hours, but weekly buckets only
+refill on the account's fixed weekly reset (days away). So the picker ranks primarily on
+**weekly headroom** (the peak of the durable buckets) and uses the self-healing session
+bucket only as a tiebreaker. An account sitting at 85% session / 10% weekly outranks one
+at 20% session / 70% weekly: the first only needs a few hours to recover, the second is
+burning headroom that's gone until next week. (`score = weekly% × 1000 + session%`,
+lowest wins.) **Exclusion** still fires on *any* bucket ≥ 90% — a full session bucket
+really does block right now — but that marker expires when the session resets, not days
+later.
+
+The shim prints nothing, logs `timestamp account cwd` (never prompt text) to
+`selection.log`, and `exec`s the real binary — stdin/stdout/exit codes pass through
+byte-identically. If anything is missing (no manifest, no accounts, unreadable state,
+even an unset `HOME`) it fails **open** into plain passthrough.
+
+**Limit-aware marking.** `claude-accounts limits` (every 60s via launchd on the Mac,
+cron on the server, plus an opportunistic non-blocking kick from the shim when data is
+>3 min stale) reads each account's own OAuth usage endpoint — the same data `/usage`
+shows. Every bucket the endpoint returns is tracked separately: `session`, `weekly_all`,
+and per-model scoped buckets — **`weekly_scoped:Fable` is its own bucket**. Any bucket
+≥ 90% ⇒ the account gets a `.limited` marker (with the bucket's reset time) and leaves the
+random pool until that bucket resets or a refresh shows it back under threshold.
+
+Bucket parsing is **shape-agnostic**: buckets are derived from whatever the endpoint
+returns (`kind`, plus `scope.model` when present), so if Anthropic renames a bucket,
+reshapes the payload, or drops the per-model Fable separation entirely, the remaining
+buckets keep being tracked and the ≥90% rule keeps working. Unparseable entries are
+skipped, an all-legacy payload falls back to `five_hour`/`seven_day`, and a payload the
+code cannot read at all degrades that one account (fail open), never the run.
+
+Telemetry failures never block work: no fresh data ⇒ account treated as available. The
+endpoint rate-limits per account, so the refresher skips accounts fetched in the last 45s
+and backs off exponentially (honoring `Retry-After`) on a 429 — `limits --force` overrides
+both. If an account's OAuth access token has expired (quiet machine, nothing ran claude for
+hours), the refresher first runs a zero-cost `claude auth status` under that account to let
+the app refresh its own credentials, then fetches; if that fails it logs and fails open.
+
+**Auto-retry** (`-p`/`--print` only, default on, `CLAUDE_SHIM_RETRY=0` disables): on an
+auth/rate-limit-looking failure the shim marks the account with a 10-minute error
+cooldown and retries once on a different account. Output is buffered so a retried call
+never double-emits. Only engages when stdin is finite (tty / regular file / `/dev/null`)
+and ≥2 accounts are eligible; service-spawned pipes take the plain exec path untouched.
+
+## 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        # npm i -g @latest + re-install
+claude-multiacc uninstall [--purge-data]
+claude-multiacc list | status | add <email> | ...   # passthrough to claude-accounts
+```
+
+**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 weekly job (launchd on macOS, cron on Linux) runs `claude-accounts self-update` to pull
+the latest npm release on its own; 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 <repo> && 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 ~/.claude-accounts
+```
+
+`self-update` auto-detects which of these you used (npm global vs git checkout).
+
+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` (60s) and
+  `.health` (weekly Mon 09:17). Warns if this Mac stores credentials in the Keychain
+  (file-based credentials are required for per-dir logins).
+- **Linux (root):** PATH block in `~/.bashrc` + `/etc/profile.d/claude-multiacc.sh`,
+  shim symlink at `/usr/local/bin/claude` (shadows via PATH order — on the systemd
+  default PATH too; the original binary is untouched), cron entries for limits/health.
+- Both: `~/.claude-accounts/` skeleton + `accounts.json` manifest.
+
+## Accounts
+
+```bash
+claude-accounts list      # pool at a glance
+claude-accounts status    # per-account auth health, per-bucket limits incl. Fable, markers, last pick
+```
+
+Every account in the pool is authenticated — `add` cannot register one otherwise.
+
+### Adopt this machine's existing login (no browser needed)
+
+```bash
+claude-accounts import you@example.com --id acct-01 --home mac
+claude-accounts adopt acct-01
+```
+
+`adopt` makes the account dir a **symlink to `~/.claude`** — the machine's existing
+login joins the pool with a single credential file (no copy of the OAuth grant exists
+anywhere else, so refreshes can never race). This is how the two current accounts run:
+acct-01 = the Mac's login, acct-02 = the server's login (adopted server-side).
+
+### Add a fresh account (~1 min, one browser sign-in)
+
+```bash
+claude-accounts add new@example.com
+```
+
+It prints a **clickable sign-in link**. Open it in a browser signed into that account,
+approve, and paste the code back into the same prompt. The account is registered **only
+after the sign-in is verified** — an aborted or failed sign-in leaves nothing behind, and
+a duplicate email is refused outright (`--force` overrides). The captured token has a
+~1-year lifetime, is inference-only, and does not rotate → it works on the Mac **and**
+the server with no cross-machine refresh races, so the account is usable everywhere the
+moment `add` returns.
+
+```bash
+claude-accounts login acct-NN     # re-run the same flow for an existing account
+                                  # (complete missing auth, or refresh an aging token)
+claude-accounts add x@y.com --tui # alternative: interactive /login instead, storing
+                                  # auto-refreshing OAuth creds (that machine only)
+```
+
+`status` warns when a token nears end of life; re-run `login` for that account.
+Both accounts currently in the pool are live and verified: acct-01 (support@gowalkae.com,
+Mac) and acct-02 (hasan@gowalkqa.com, server) — each adopted from its machine's existing
+login, so each runs on the machine that holds its credential.
+
+### Remove
+
+```bash
+claude-accounts remove acct-NN          # deletes locally, propagates to the server
+```
+
+## Server sync
+
+Mac → server, one-way (Mac = source of truth), fired automatically by
+`add`/`import`/`remove`/`mint` and manually via:
+
+```bash
+claude-accounts sync
+```
+
+Pushes the manifest + per-account `server.token` (0600) + one-time seeds; **never**
+syncs `.credentials.json` in either direction (two machines refreshing one OAuth grant
+invalidate each other). Removals propagate; an empty/corrupt manifest refuses to sync
+(guard against wiping the server pool). After every push the server re-seeds dirs and
+re-runs its quick verification matrix (`post-sync` hook). Everything logs to `sync.log`;
+failures are loud and non-zero.
+
+## Pinning & env switches
+
+| Env | Effect |
+| --- | --- |
+| `CLAUDE_ACCOUNT=acct-03` | pin this invocation to one account (wins over markers) |
+| `CLAUDE_CONFIG_DIR=...` | shim passes straight through (scripts can pin the old way) |
+| `CLAUDE_MULTIACC_DISABLE=1` | bypass selection entirely |
+| `CLAUDE_SHIM_RETRY=0` | disable the `-p` auto-retry |
+| `CLAUDE_ACCOUNTS_DIR=...` | relocate the pool (used by the test suite) |
+
+## Verification
+
+```bash
+tests/run-tests.sh            # 35 sandboxed tests, no quota
+claude-accounts verify        # real matrix: `claude -p "reply OK"` per authed account
+claude-accounts verify --quick# auth presence/expiry only, 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,
+  or an active `.limited` marker (shows bucket + minutes to reset).
+- **Everything marked limited** — the shim still runs (least-utilized fallback);
+  check `selection.log` for `all-limited` 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.
+- **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).