@herbertgao/pi-extensions 2026.9.9 → 2026.9.11

package/node_modules/pi-multi-account/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to pi-multi-account
+
+Thanks for your interest in improving pi-multi-account! Issues and pull
+requests are welcome. All PRs are reviewed by the maintainer before merge.
+
+## Ground rules
+
+- **Never include secrets.** The extension handles credentials for provider
+  authentication and usage requests and can keep a `0600` private OAuth recovery
+  sidecar while publishing loopback proxies. Credential values never enter
+  rotation state or logs; only SHA-256 fingerprints are persisted there. Never
+  paste tokens, API keys, or `auth.json` contents into issues, PRs, logs, or tests.
+- Keep each PR focused on a single concern.
+- Discuss large or breaking changes in an issue first.
+
+## Development setup
+
+```bash
+git clone https://github.com/Sarrius/pi-multi-account.git
+cd pi-multi-account
+npm install
+```
+
+Requirements: Node.js >= 22.
+
+## Before you open a PR
+
+```bash
+npm run check        # TypeScript type-check (tsc --noEmit)
+npm run pack:check   # npm pack --dry-run — verify the published file set
+```
+
+CI runs the same checks on every pull request; they must pass before review.
+
+## Coding guidelines
+
+- The whole extension lives in `index.ts`. Match the surrounding style.
+- Prefer small, well-commented guards over clever one-liners — failover logic is
+  safety-critical (a bad loop can peg a machine).
+- Update `CHANGELOG.md` under a new version / `Unreleased` heading describing the
+  user-visible effect of your change.
+
+## Releasing (maintainer only)
+
+Publishing runs on GitHub Actions through npm **trusted publishing** (OIDC). There is no
+npm token anywhere, and `npm publish` is never run from a laptop — the workflow refuses to
+publish unless it is checked out on the tag matching `package.json`.
+
+1. Bump `version` in **both** `package.json` and `const VERSION` in `index.ts` — they must
+   match — and add the `CHANGELOG.md` entry.
+2. Land the change on `main` via PR (CI must be green).
+3. Tag and push the tag:
+   `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`
+4. Dry run first — this exercises the whole pipeline without uploading:
+   `gh workflow run publish.yml --ref vX.Y.Z -f dist_tag=latest -f dry_run=true`
+5. When that is green, publish for real:
+   `gh workflow run publish.yml --ref vX.Y.Z -f dist_tag=latest -f dry_run=false`
+6. Create the GitHub release for the tag.
+
+`--ref` must be the **tag**, not a branch: the workflow asserts `GITHUB_REF_TYPE=tag` and
+`GITHUB_REF_NAME=v<version>`, so dispatching from `main` fails that guard by design.

package/node_modules/pi-multi-account/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-multi-account contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/pi-multi-account/README.md

@@ -0,0 +1,197 @@
+# pi-multi-account
+
+Automatic multi-account failover & rotation for [Pi Agent](https://pi.dev/), across **Anthropic (Claude)**, **OpenAI / ChatGPT Codex**, **Kimi For Coding**, **Cursor**, **Qwen / Alibaba**, and **Ollama**.
+
+When the account you are using hits a quota or rate limit, `pi-multi-account` transparently switches to the next authenticated account/model and (optionally) resumes the interrupted task — so a long agent run does not die just because one account ran out of budget.
+
+## What it does
+
+- **Auto-discovers** every authenticated account from `~/.pi/agent/auth.json` (Anthropic Claude Pro/Max, OpenAI/ChatGPT Codex, Kimi For Coding, Cursor, Qwen/Alibaba, and Ollama) and builds the failover rotation dynamically — no manual config editing.
+- **Grows the rotation on login.** Run `/login`, choose **Use a subscription**, then select a numbered slot such as `anthropic-account-3` or `openai-codex-account-5`. The next discovery sweep adds it to the rotation automatically.
+- **Auto-discovers new Codex models per account.** At session start (and on `reload` / `rediscover`) it reads OpenAI's authenticated model catalog, mirrors each account's actually available models onto its Pi alias, and follows OpenAI's server priority. A new flagship can therefore win immediately without an extension release or a hard-coded model id.
+- **Handles auth failures without poisoning healthy OAuth accounts.** A generic final 401 briefly cools down a refreshable account and moves the current task forward. Explicit provider verdicts such as `authentication token has been invalidated` force an early refresh; if the refresh token is dead too, the slot is removed and Pi prints the interactive `/login` recovery steps.
+- **Fails over on quota / rate-limit** (429 / 402 / 403 and friends): the exhausted account goes on cooldown (parsed from the provider's own reset metadata when available) and Pi first tries another account with the same model. If it must leave the family, it preserves the model's quality band — Sol/Opus/other frontier flagships stay frontier; Terra/Sonnet stay balanced; Luna/Haiku stay fast — and keeps the session's thinking level. A fresh provider verdict of `blocked` or 100% is skipped automatically instead of wasting the turn; manual `next` remains an explicit one-attempt override for stale telemetry.
+- **Optional auto-continue**: resumes the interrupted turn after a switch from the last safe point. Temporary 5xx/overload errors and Cursor stalls retry the exact selected provider/account/model, without marking its quota exhausted. After four failed attempts (or an earlier recovery breaker), automatic retries stop with an explicit explanation; temporary errors never authorize a switch. Same-route retries are labelled as retries, not fake switches. A failed or cancelled automatic compaction still continues the task instead of leaving the session parked in Working.
+- **Never hides a fresh user message in a private cooldown queue.** If no account is ready, the message remains in Pi's visible transcript and Pi owns its normal delivery/retry path.
+- **Session-bound overnight resume**: if every account is cooling down, the live Pi session waits for the earliest recovery and continues automatically. A new user message, `/multi-account stop`, session exit, or Esc during a running turn cancels the chain.
+- **Deduplicates provably identical accounts** so duplicate Codex workspace memberships and identical credentials do not consume multiple rotation slots or get separate cooldowns. Different users in one Team/Business workspace remain distinct. New provable duplicate logins are rejected before the redundant slot is saved.
+- **Keeps YOUR reasoning level across automatic switches.** Whatever the session runs at — your Pi default, `/thinking`, or a per-agent `--thinking low` — is preserved and restored after every account/model switch, so it never drifts downward when a weaker fallback model clamps it. Manual `/model` selections adopt Pi's per-model thinking default in `auto` mode; an explicit CLI `--thinking` or forced `reasoningLevel` remains authoritative. The extension does not otherwise override your level, and extreme levels such as `xhigh` / Max / Ultra are never forced.
+- **Shows live limits for the active account** in Pi's footer: remaining 5-hour/session and weekly allowance plus reset countdowns for Codex, Anthropic, and Ollama Cloud accounts, SuperGrok / xAI subscription credit usage for `/login xai` OAuth (not Cursor Grok, not `XAI_API_KEY`), and GLM Coding Plan CN 5-hour/weekly credit quota for `zai-coding-cn`. GLM CN uses the raw Coding Plan API key only at `https://open.bigmodel.cn/api/monitor/usage/quota/limit`; global `zai` keys are not sent there. Missing or malformed quota is unknown, never assumed unused.
+
+## Install
+
+```bash
+pi install npm:pi-multi-account
+```
+
+Restart Pi or run `/reload` after installation.
+
+Requires Node 22+ and `@earendil-works/pi-ai` 0.78 or newer — it is installed automatically as a
+dependency. Both the pre-0.80 OAuth API and the 0.80+ provider-factory API are supported, so the
+extension keeps working across pi-ai upgrades. If a pi-ai it cannot adapt is ever encountered, the
+extension still loads and API-key accounts keep rotating; only subscription login is unavailable,
+and it says so at session start.
+
+> **Anthropic (Claude Pro/Max) works out of the box.** OAuth login and request
+> shaping for the base `anthropic` provider and every `anthropic-account-*` alias
+> are built in — no separate `pi-anthropic-auth` install is required. If you
+> already have `pi-anthropic-auth`, the two coexist safely (the shaping is
+> idempotent). OpenAI Codex / ChatGPT and Qwen accounts work as well.
+
+### Recommended setting
+
+Set Pi provider-level retries to zero so the SDK does not keep retrying an exhausted account before failover kicks in. Pi's separate agent-level retry loop may remain enabled: the extension cancels its pending wake if that retry succeeds. Repeated temporary failures get bounded recovery on the same route, then an explicit stop—not provider failover. In `~/.pi/agent/settings.json`:
+
+```json
+{ "retry": { "provider": { "maxRetries": 0 } } }
+```
+
+## Usage
+
+Add accounts by opening the login picker:
+
+```text
+/login
+Use a subscription
+ChatGPT Plus/Pro (Codex openai-codex-account-2)
+/multi-account rediscover
+```
+
+Pi 0.79.3 does not accept a provider argument after `/login`; select the account
+slot from the interactive provider picker instead.
+
+Check what's in the rotation at any time:
+
+```text
+/multi-account status
+```
+
+Force-refresh and display detailed limits for the active account:
+
+```text
+/multi-account limits refresh
+```
+
+Example status output:
+
+```text
+pi-multi-account: enabled · auto-discover ON
+Current: anthropic/claude-opus-4-8
+Current limits: Claude | 5h 0% left/2h14m | 7d 92% left/1d18h
+Rotation (3): anthropic → openai-codex → openai-codex-account-2
+Registered login slots: anthropic-account-2, openai-codex-account-2
+Cooldowns: none
+Invalidated (need re-login): none
+Pending auto-resume: none
+```
+
+### Commands
+
+All three names are aliases for the same command: `/multi-account`, `/provider-failover`, `/failover`.
+
+| Subcommand | Description |
+|---|---|
+| `status` (default) | Show enabled state, current model, rotation, login slots, cooldowns, invalidations, pending resume. |
+| `limits [refresh]` | Show active-account session/weekly limits; `refresh` bypasses the cache. Aliases: `usage`, `quota`. |
+| `accounts [refresh]` | List every configured slot with provider-reported alias/email, plan, limits, and live routing status. Uses cached metadata unless `refresh` is explicit. |
+| `rediscover` | Force a re-scan of `auth.json`, rebuild the rotation, and refresh Codex model catalogs now. |
+| `add [anthropic\|codex\|kimi\|cursor\|ollama\|qwen]` | Print the next free account slot to select from the interactive `/login` picker. Subscription families (Anthropic, Codex, Kimi, Cursor) are logged in through `/login`; API-key families are filled in `auth.json`. |
+| `remove [anthropic\|codex\|kimi\|cursor\|ollama\|qwen\|<provider-id>]` | Remove an account from `auth.json` and rotation. Family name drops the highest numbered alias slot; a full provider id removes that exact slot. Aliases: `rm`, `delete`. |
+| `next` | Manually switch to the next compatible-quality fallback, deliberately overriding recorded cooldowns for one attempt. Use explicit `switch` to select a different tier. |
+| `only-active [on\|off]` | Legacy picker preference; the complete Pi model registry remains available to all clients. Pi currently has no separate picker-only filter. Alias: `focus`. |
+| `stop` | Abort and cancel automatic failover/resume for the current task. |
+| `reset` | Clear all cooldowns, invalidations and any pending auto-resume. |
+| `reload` | Reload config from disk and re-discover accounts. |
+| `enable` / `disable` | Turn failover on/off for the current Pi process. |
+
+## How rotation membership works
+
+- **Joins the rotation** when an account has a present, non-expired credential in `auth.json` (after `/login`).
+- **Leaves the rotation** when the credential is logged out / removed, its access token is expired with no refresh token, an API key is rejected, or a refreshable OAuth credential produces three distinct final auth failures without a success in between.
+- **Quota / rate-limit** does not invalidate an account — it puts it on a temporary cooldown and the account returns once the cooldown expires.
+- **Duplicate identities** share one rotation position and one cooldown, and status/startup identifies the redundant slot. Codex/ChatGPT is matched by the JWT's stable `chatgpt_account_user_id` workspace-membership claim; tokens without it use the documented `chatgpt_user_id` plus workspace id, with stored `accountId` as the final legacy fallback. Identical API keys or literal identical tokens are also matched. Separate Anthropic OAuth logins cannot be proven identical because Anthropic's stored credential exposes no stable account identifier.
+
+Rotation refresh is triggered by changes to `auth.json` (detected on session/turn start) or on demand with `/multi-account rediscover`.
+
+After re-authenticating an invalidated slot, restart any older Pi processes that
+were already running. Pi keeps a still-unexpired access token in each process's
+memory, so an old process can continue using the invalidated token even after a
+new `/login` updates `auth.json`.
+
+## Configuration
+
+A default config is created at `~/.pi/agent/provider-failover.json` on first run. Useful keys:
+
+| Key | Default | Description |
+|---|---|---|
+| `enabled` | `true` | Master switch. |
+| `autoContinue` | `true` | Queue a continuation prompt after a switch. |
+| `autoDiscover` | `true` | Auto-discover accounts from `auth.json`. |
+| `autoDiscoverModels` | `true` | Fetch OpenAI's authenticated model catalog for every Codex account and register new models on that account's alias automatically. |
+| `includeQwen` | `true` | Include Qwen / Alibaba accounts. |
+| `includeOllama` | `true` | Include Ollama (local) accounts. |
+| `neverFailoverProviders` | `[]` | Provider ids to never fail away from, e.g. `["my-provider"]`. For **unmanaged** providers that run their own retry logic (typically a companion extension owning retries for that provider) — switching accounts underneath it would fight those retries. Managed accounts still cool and rotate normally. |
+| `includeCursor` | `true` | Include Cursor subscription accounts. The Cursor provider is a separate, optional repo — until it is cloned this setting does nothing at all: no cursor login slot is offered and no warning is printed. Run `/multi-account add cursor` to get the install instructions. |
+| `childProxy` | `true` | Serve OAuth rotation slots to processes that do not load this extension (a memory extension consolidating its notes, an external CLI, any `pi -p --no-extensions` call) through a loopback route this process owns. A bare child launched without `--model` inherits Pi's **saved global default**, which since Pi 0.84.3 intentionally may differ from this session's live rotation; an explicitly pinned child uses its requested slot. Without a usable publication either form can fail authentication and fall back to whichever provider Pi finds first. The published route carries a non-secret placeholder; the real credential never leaves the parent. |
+| `providerOrder` | `["anthropic","openai-codex","qwen","ollama"]` | Preferred family order in the rotation. |
+| `cooldownMs` | 6 h | Default cooldown when no reset metadata is provided. |
+| `showUsage` | `true` | Show active Codex/Claude/xAI limits in Pi's footer. |
+| `usageRefreshMs` | 5 min | Per-account usage cache TTL; every authenticated rotation account is refreshed independently, and Anthropic is clamped to at least 10 min to avoid endpoint throttling. |
+| `usageStatusRefreshMs` | 1 min | Re-render the footer and sweep idle sessions for stale usage/model catalogs; network refreshes remain limited by their five-minute (Anthropic: ten-minute) TTLs. |
+| `maxAutoContinuesPerPrompt` | `8` | Cap on auto-resume hops per task. |
+| `continuationPrompt` | (built-in) | Template; supports `{from}`, `{to}`, `{reason}`. |
+| `maxRecheckIntervalMs` | `600000` (10 min) | Ceiling on how long a quota snapshot may bench an account before background refresh/re-evaluation. A fresh explicit provider verdict (`serviceable: false`) is authoritative during that interval and is skipped by automatic routing; manual `next` can still spend one deliberate probe. |
+| `preserveInterruptedContext` | `true` | Rewrite the turn that triggered the failover into a verbatim `[handoff:interrupted-turn]` record so the account taking over still sees the reasoning, output and tool calls of the turn pi-ai would otherwise drop as unreplayable — including which calls never returned. Deterministic (never moves the prompt-cache breakpoint) and hard-capped. Set to `false` for the previous drop-everything behaviour. |
+| `continueAfterCompaction` | `true` | After an **automatic** compaction, carry the task on instead of ending the run and waiting for the user to type "continue". This covers both Pi's threshold/overflow path (a follow-up is queued while compaction is still in flight so Pi's own `hasQueuedMessages()` route drains it) and the extension's context-guard summary (a real turn starts only from Pi's completion callback, because that guard compacts from an already-idle boundary). One continuation shares the `maxAutoContinuesPerPrompt` budget with failover and is skipped for a manual `/compact`, when Pi is already retrying, when another message/turn is present, and after the user pressed Esc. The message tells the model that finishing is valid. Set `false` only when another installed extension owns post-compaction continuation. |
+| `providerPriority` | managed families, per-token providers last | Where work goes once **every** account of the current provider is spent. An ordered list of provider groups — a managed family, or the base id of anything else you are logged in to (`openrouter`, `zai`, `minimax`…), which `providerOrder` could never name. Three bounds: same-provider failover always runs first and is untouched (588 of 602 automatic failovers in a real black box stayed inside the family — that step already worked); an account on a real cooldown is never chosen over a free one; and a group nobody ranked sorts after every group somebody did. Inside those bounds it settles the hop that used to be arbitrary — the other 14 of those 602 scattered across five destinations with no policy behind them. It sits below the per-account liveness signals on purpose: evidence about one account beats a preference about its category. Set with `/multi-account priority ...`. |
+| `contextGuard` | `true` | Keep every request inside the model's context window **while the agent is working**. Pi ≥0.84.4 also compacts between tool execution and the next assistant request. This optional guard adds a local window cap (especially for advertised 1M windows). Existing elisions are reapplied before measuring the outgoing request; another batch is added only when it crosses the soft threshold again, rather than invalidating the cached prefix on each tool turn. Above 75 % of the usable window the oldest large tool results are left out of the outgoing request (the transcript is never touched); above 70 % a real summary is requested at the next settled boundary. The size is measured locally rather than taken from the provider, because Cursor and openai-codex both report the size of their own server-side copy of the conversation. Pass an object to override `softPercent`, `targetPercent`, `compactPercent`, `keepVerbatimTokens`, `minElideTokens`, `maxWindowTokens` (default `400000`: a ceiling on advertised windows, since a model claiming 1 000 000 puts Pi's own threshold out of reach entirely). `false` disables it. |
+| `routeCompactionToHealthyAccount` | `true` | When the active account is rate-limited/invalid and Pi needs to compact, generate the summary on a healthy fallback account. If every live attempt fails, cancel — never hand the job to Pi's default on the spent account (that is the infinite "Compacting context…" spinner). |
+| `compactionWatchdogMs` | 8 min | Upper bound for one routed compaction attempt. A timed-out attempt is aborted and the next live account is tried. |
+| `resumeIdleTimeoutMs` | 90 s | Max time to wait for the previous turn to go idle before a resume gives up and retries later (never an unbounded loop). |
+| `stuckWatchdogMs` | 180 s | A resumed turn silent for this long (with no tool running) is treated as wedged. |
+| `autoRecoverStuck` | `true` | When a resume wedges, auto-cancel it and retry the same provider/model within the shared recovery budget, instead of only notifying. Set `false` for notify-only. |
+| `debugLog` | `true` | Write a structured "black box" decision log to `provider-failover-debug.log` (no credentials — only provider/model ids and truncated reasons). View with `/multi-account log`. |
+| `preferLatestModel` | `true` | Rank the strongest/current model ahead of older siblings within the current quality band during automatic failover. |
+| `reasoningLevel` | `"auto"` | `"auto"` follows the level the session actually runs at (your Pi default, `/thinking`, per-agent `--thinking`) and only restores it after switches. Set an explicit level (`"off"`…`"xhigh"`) to **force** it on every turn regardless of the session — `"xhigh"` only if you really want the extreme level. |
+| `preferredModels` | `{}` | Optional manual strongest-first override per family; when present it wins over live catalog priority. |
+
+State (cooldowns, invalidations, recent switches, credential-free Codex model catalogs, and a diagnostic pending marker) is persisted to `~/.pi/agent/provider-failover-state.json`. The actual pending task is session-local: one Pi window never consumes or resumes another window's work. Pending work is discarded when its owning session closes.
+
+### Session model ownership
+
+Requires Agent Pi **0.85.1 or newer**. Pi's session branch and explicit SDK/CLI launch model are authoritative. Shared account telemetry and legacy `lastUserModel` / `lastUserThinkingLevel` state cannot replace another pane's live selection, and shutdown does not publish that selection as a global default. Cold-catalog repair uses this session's model history once at startup. Configure Pi's saved default explicitly for new sessions.
+
+### Host-owned background completions
+
+When the host exposes `registerCompletionRouter`, Multi Account registers one credentialless completion router with it. This is capability-detected, not inferred from the Pi version: stock Pi 0.85.1 does not expose this optional API, so the integration remains inactive there. Extensions can request isolated background completions through Pi without importing or calling Multi Account. The router sees operation IDs, model identities, attempt outcomes, and provider response facts only; prompts and credentials remain inside the host.
+
+Background attempts share the same cooldown and invalidation state as foreground routing. Quota, authentication, model, and transport failures can select a healthy fallback; parser and consumer failures do not affect route health. The route lease is operation-local: it never calls `pi.setModel`, queues a continuation, or changes the user's selected foreground model.
+
+### pi-subagents and delegation-broker compatibility
+
+`pi-subagents` marks native child processes with `PI_SUBAGENT_CHILD=1` and owns their explicit model plus `fallbackModels` chain. Concurrent in-process SDK sessions also stay passive while a root session activation is live. The root lease is released at session shutdown, so `/reload`, `/new` and replacement root sessions do not permanently lose routing ownership. This is process-local ownership, not detection based on model names or a permanent first-factory flag. In those children this extension stays loaded only for provider/account registration, OAuth request shaping, and catalog support. It deliberately does **not** restore the interactive process's remembered model, persist the child's model as a user preference, switch models, queue work, or auto-continue after errors. The original provider error is returned unchanged so the parent runner can advance its verified fallback chain without a second router competing for model identity.
+
+[`pi-delegation-broker`](https://github.com/Sarrius/pi-delegation-broker) is an optional companion for splitting work among isolated child agents, with task budgets, reports and verification. Each extension works independently and depends on Agent Pi, not on the other extension. Together, Multi Account manages your interactive account rotation while the broker delegates through Pi's registered providers and models. Neither installs or initializes the other.
+
+## Staying unstuck (resilience)
+
+A failover is only useful if the agent actually keeps working afterward. These guarantees keep a switch from silently freezing the session:
+
+- **Compaction survives account limits — and never leaves the spinner running.** When your context fills up and the active account is rate-limited, the summary is generated on a *healthy* account. If that attempt times out it is aborted (not leaked) and the next live account is tried. If none can finish, compaction is cancelled so "Compacting context…" stops; Pi's default is never given a spent account.
+- **Resumes only happen when there is something to resume.** The extension continues a turn only when it actually ended in an error it can pick up from — it never tries to "continue" a finished reply (the cause of the cryptic `Cannot continue from message role: assistant` error).
+- **A forward-progress watchdog that acts.** If a resumed turn goes completely silent (no streaming, no tool activity, no provider response) and no tool is running, the extension auto-cancels the wedged turn and retries the same provider/model within the recovery budget — you do not have to press Esc or re-type the prompt. A long, silent build/test command is never mistaken for a wedge.
+- **A circuit breaker as the floor.** If automatic recovery keeps failing, the extension drops to *advisory mode*: confirmed quota limits can still select a fresh account, but temporary errors preserve the selected route and stop the auto-continue that was failing, so a bad state can never spiral into repeated hangs. It re-enables itself on the next success, a new prompt, or `/multi-account reset`.
+- **A black box for diagnosis.** Every decision (switch, error and how it was classified, watchdog action, breaker trip, compaction routing) is appended to `~/.pi/agent/provider-failover-debug.log`. If anything misbehaves, run `/multi-account log` — the exact sequence is there, so a bug can be reproduced and fixed instead of guessed at. The file is bounded in size and redacts token-shaped material; review private project details before sharing it.
+
+## Privacy & security
+
+`pi-multi-account` reads credentials through Pi and its account store. Account removal, OAuth refresh and parent-owned proxy publication can update the credential files under Pi-compatible locks. Proxy publication keeps a private recovery copy before replacing a credential with a loopback placeholder, and restores the real credential before deleting that copy. Credentials are never stored in rotation state. Account/token values are reduced to a short irreversible SHA-256 fingerprint for re-login detection and deduplication. Credentials are sent only to their own provider endpoints: usage/account probes (`chatgpt.com/backend-api/wham/usage`, `api.anthropic.com/api/oauth/usage`, `cli-chat-proxy.grok.com/v1/billing`, `open.bigmodel.cn/api/monitor/usage/quota/limit` (CN Coding Plan keys only), Ollama Cloud's `/api/me` and `/api/usage`, or Ollama's loopback-only `http://127.0.0.1:11434/api/me` fallback), OpenAI's authenticated `chatgpt.com/backend-api/codex/models` catalog, and provider OAuth token endpoints when Pi's authentication implementation refreshes a login (for xAI, `auth.x.ai/oauth2/token`). Cached state contains percentages, reset times, plan/credit metadata, model metadata, provider-reported account email/alias, and the fingerprint, never the token. Config, state, and the debug log are written with `0600` permissions. The debug log records only provider/model ids, decisions, and truncated reasons — token-shaped material is redacted defensively — Review logs for private project details before sharing an issue. Disable it with `"debugLog": false` or `/multi-account log off`.
+
+## License
+
+[MIT](./LICENSE)
+
+
+### Help make these tools more reliable
+
+Use them on real work? Share a reproducible [issue](https://github.com/Sarrius/pi-multi-account/issues), a small regression test, a documentation improvement, or a focused PR. Include Pi/extension versions and expected versus actual behavior; remove credentials and private task data. Shared fixes cover more providers and workflows than one maintainer can test alone.

package/node_modules/pi-multi-account/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub's
+[security advisories](https://github.com/Sarrius/pi-multi-account/security/advisories/new)
+rather than opening a public issue.
+
+## Handling of credentials
+
+pi-multi-account reads authenticated accounts from `~/.pi/agent/auth.json`. Raw
+credentials are never copied into rotation state or logs. A `0600` private
+recovery sidecar can temporarily retain OAuth credentials while the public
+account store contains loopback proxy placeholders. Credentials are transmitted
+over HTTPS to provider endpoints needed for authentication, account usage, and
+model-catalog operations. The only non-HTTPS exception is Ollama's tightly
+scoped `http://127.0.0.1:11434/api/me` loopback fallback. The endpoints currently
+called by the extension are documented under
+[Privacy & security](./README.md#privacy--security); OAuth refresh delegates to
+the provider authentication implementation shipped by Pi.
+
+- Only SHA-256 fingerprints (first 12 hex chars) of tokens/keys are kept in
+  extension state, to detect re-login and dedupe accounts.
+- Its config and state files are written with `0600` permissions.
+
+When reporting an issue, never include tokens, API keys, or the contents of
+`auth.json`.

package/node_modules/pi-multi-account/auth-file-transaction.ts

@@ -0,0 +1,56 @@
+/** Pi-compatible cross-process auth lock and crash-safe OAuth shadow publication. */
+import { createRequire } from "node:module";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { AuthBlob } from "./slot-proxy-auth.ts";
+
+const require = createRequire(import.meta.url);
+type Auth = Record<string, AuthBlob>;
+type Plan = { auth: Auth; sidecar: Auth; changed: boolean };
+
+function read(path: string): Auth {
+  if (!existsSync(path)) return {};
+  const value = JSON.parse(readFileSync(path, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("auth storage is not an object");
+  return value;
+}
+
+function atomicWrite(path: string, data: Auth): void {
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(data, null, "\t")}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(temp, path);
+  } finally { rmSync(temp, { force: true }); }
+}
+
+export function mutateProxyAuth(
+  authPath: string,
+  sidecarPath: string,
+  transform: (auth: Auth, sidecar: Auth) => Plan,
+  mode: "shadow" | "restore",
+  write: (path: string, data: Auth) => void = atomicWrite,
+): boolean {
+  mkdirSync(dirname(authPath), { recursive: true, mode: 0o700 });
+  if (!existsSync(authPath)) {
+    try { writeFileSync(authPath, "{}\n", { mode: 0o600, flag: "wx" }); }
+    catch (error: any) { if (error?.code !== "EEXIST") throw error; }
+  }
+  // Same package/options as Pi FileAuthStorageBackend. Never read a snapshot before locking.
+  const lockfile = require("proper-lockfile") as { lockSync(path: string, options: object): () => void };
+  const release = lockfile.lockSync(authPath, { realpath: false });
+  try {
+    const plan = transform(read(authPath), read(sidecarPath));
+    if (!plan.changed) return false;
+    if (mode === "shadow") {
+      // Persist the only recoverable OAuth copy BEFORE replacing auth with a placeholder.
+      write(sidecarPath, plan.sidecar);
+      write(authPath, plan.auth);
+    } else {
+      // Restore the real credential BEFORE removing its recovery copy.
+      write(authPath, plan.auth);
+      write(sidecarPath, plan.sidecar);
+    }
+    return true;
+  } finally { release(); }
+}

package/node_modules/pi-multi-account/child-usability.ts

@@ -0,0 +1,233 @@
+/**
+ * Can an extension-free Pi child actually use this rotation slot?
+ *
+ * ## Why this exists
+ *
+ * Pi keeps an optional saved global default in `settings.json`. On Pi <=0.84.2 every model
+ * switch rewrites it; since Pi 0.84.3 ordinary model selection is session-scoped and only an
+ * explicit persistent choice rewrites it. Anything that later spawns a bare
+ * `pi -p --no-extensions` child without `--model` inherits that saved default — which may
+ * intentionally differ from whichever rotation slot is active in this session. Brokered and
+ * subagent children pass an explicit provider/model and do not use this fallback.
+ *
+ * A child launched that way does not load this extension, so a slot named `openai-codex-account-4`
+ * exists for it only if we published it into Pi's own `models.json`. Publishing the *name*,
+ * however, is not the same as publishing a usable route, and the difference is invisible until
+ * something fails far away from here.
+ *
+ * ## What was measured (2026-08-24), not assumed
+ *
+ * In an isolated agent directory containing one `models.json` provider entry mirroring the
+ * built-in Codex definition plus the matching **OAuth** credential under the same key:
+ *
+ *     pi -p --no-extensions --no-session --model openai-codex-account-4/gpt-5.6-sol …
+ *     → exit 1: "No API key found for openai-codex-account-4."
+ *
+ * The same child, pointed at the **built-in** `openai-codex` provider with its OAuth credential,
+ * got past authentication (it reached the network instead of refusing).
+ *
+ * The reason is in Pi: `checkProviderAuth` honours an OAuth credential only when the *provider
+ * definition* declares an OAuth flow. A `models.json` entry declares none, so an OAuth token
+ * sitting in `auth.json` under exactly that key is never consulted. An API key is different —
+ * it resolves through the credential store and works.
+ *
+ * ## What was measured again (2026-08-30), and what it corrected
+ *
+ * The row below claiming a built-in provider is usable whatever its credential turned out to be
+ * true of authentication and false of the request. On the account the parent session was itself
+ * using successfully at that moment:
+ *
+ *     pi -p --no-extensions --no-session --model anthropic/claude-opus-5 …
+ *     → 400 invalid_request_error: "Third-party apps now draw from your extra usage, not your
+ *       plan limits."
+ *
+ * Pi resolved the built-in provider and its OAuth credential correctly; Anthropic then refused,
+ * because a subscription token is only honoured for a request carrying the client identity the
+ * parent adds and a bare child does not. So for that family being built-in is not sufficient,
+ * and the same parent-owned loopback route the alias slots use is what makes it usable. Codex
+ * is unaffected — the 2026-08-24 measurement of a bare child on built-in `openai-codex` reached
+ * the network and was served.
+ *
+ * | slot shape | child outcome |
+ * |---|---|
+ * | built-in provider, credential the vendor serves any client (API key, Codex OAuth) | usable — Pi owns the auth flow |
+ * | **built-in Anthropic on a subscription OAuth token** | **authenticates, then refused as a third-party app** |
+ * | alias slot published with a real or placeholder `apiKey` | usable — Pi sees a credential |
+ * | **alias slot with an OAuth credential and no `apiKey`** | **resolves by name, then fails at auth** |
+ *
+ * The third row is what we do today for Kimi slots, under a comment promising that
+ * "extension-free children resolve it". True of the name; false of the credential. The Cursor
+ * slots avoid it by publishing a non-secret placeholder that points at a parent-owned local
+ * proxy, so the child authenticates to `127.0.0.1` while the real token stays in the parent.
+ *
+ * This module is deliberately pure: it decides and explains, and it touches no file, no socket
+ * and no credential. Wiring and the proxy itself are separate, reviewable pieces — this one can
+ * be tested exhaustively without any of them.
+ */
+
+/** How a slot's credential is stored, as far as `auth.json` is concerned. */
+export type SlotCredentialKind = "oauth" | "api_key" | "none";
+
+export interface SlotChildFacts {
+  /** Rotation slot id, e.g. `openai-codex-account-4` or a base provider name. */
+  slotId: string;
+  /** Credential kind held for this exact slot id. */
+  credential: SlotCredentialKind;
+  /** True when Pi itself defines this provider (it then owns the OAuth flow). */
+  builtin: boolean;
+  /** `apiKey` published for this slot in `models.json`, when we published one. */
+  publishedApiKey?: string;
+  /** `baseUrl` published for this slot in `models.json`, when we published one. */
+  publishedBaseUrl?: string;
+}
+
+export type ChildUsability =
+  /** A bare child can authenticate and run on this slot. */
+  | { usable: true; slotId: string; via: "builtin" | "api-key" | "parent-proxy"; note: string }
+  /** A bare child cannot use it; `remedy` says what would change that. */
+  | { usable: false; slotId: string; reason: string; remedy: string };
+
+/**
+ * Families whose subscription refuses a request that does not carry the parent's client
+ * identity, even when Pi resolved the credential. Being built-in does not help here: the
+ * failure is the vendor's answer, not Pi's auth lookup.
+ */
+function vendorRefusesBareChild(
+  slotId: string,
+  credential: SlotCredentialKind,
+  builtin: boolean,
+): boolean {
+  // Numbered alias slots never get this far: Pi does not consult their OAuth blob at all.
+  // The 400 is specific to a built-in Anthropic provider, which does resolve the credential.
+  return builtin && credential === "oauth" && /^anthropic(?:-account-\d+)?$/.test(slotId);
+}
+
+/** Loopback-only, so a published route can never send a child off this machine. */
+function isLoopback(baseUrl?: string): boolean {
+  if (!baseUrl) return false;
+  try {
+    // `URL` reports an IPv6 host bracketed (`[::1]`), so compare against the unwrapped form.
+    const hostname = new URL(baseUrl).hostname.replace(/^\[|\]$/g, "");
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide, for one slot, whether an extension-free child can run on it.
+ *
+ * Order matters: Pi's resolver keys off the stored credential *type* before it ever looks at a
+ * models.json apiKey. An OAuth blob under the same key as a published placeholder is therefore
+ * not a usable child route — measured against Pi's own `resolveProviderAuth`: stored OAuth plus a
+ * provider that has no OAuth method returns undefined (\"No API key found\"), and stored OAuth
+ * plus a built-in OAuth method ignores the placeholder entirely.
+ */
+export function classifyChildUsability(facts: SlotChildFacts): ChildUsability {
+  const { slotId, credential, builtin, publishedApiKey, publishedBaseUrl } = facts;
+
+  const vendorRefuses = vendorRefusesBareChild(slotId, credential, builtin);
+
+  // A built-in provider is resolved by Pi without us — but resolution is not service. When the
+  // vendor refuses a bare client, a loopback baseUrl is what actually redirects the request;
+  // the published apiKey is not what Pi sends, because the stored credential is still OAuth.
+  if (builtin && !vendorRefuses) {
+    return {
+      usable: true,
+      slotId,
+      via: "builtin",
+      note: "Pi defines this provider itself and owns its auth flow, so a bare child resolves it without this extension.",
+    };
+  }
+
+  if (vendorRefuses && isLoopback(publishedBaseUrl)) {
+    return {
+      usable: true,
+      slotId,
+      via: "parent-proxy",
+      note: "The child still presents the subscription token; the published loopback is what makes the parent shape that request instead of the vendor refusing it as a third-party app.",
+    };
+  }
+
+  if (vendorRefuses) {
+    return {
+      usable: false,
+      slotId,
+      reason:
+        "The credential is a subscription OAuth token. Pi resolves it, but the vendor then refuses the call as a third-party app (\"Third-party apps now draw from your extra usage, not your plan limits\"), because a bare child does not send the client identity the parent adds.",
+      remedy:
+        "Publish this account against a parent-owned loopback proxy so the child's request is shaped by the parent that holds the subscription.",
+    };
+  }
+
+  if (credential === "api_key") {
+    if (publishedApiKey && isLoopback(publishedBaseUrl)) {
+      return {
+        usable: true,
+        slotId,
+        via: "parent-proxy",
+        note: "The child authenticates to a parent-owned loopback route with a non-secret placeholder; the real credential never leaves the parent.",
+      };
+    }
+    return {
+      usable: true,
+      slotId,
+      via: "api-key",
+      note: "The credential is an API key, which Pi resolves through its own credential store for a published provider.",
+    };
+  }
+
+  if (credential === "oauth") {
+    return {
+      usable: false,
+      slotId,
+      reason:
+        "The credential is OAuth, and Pi honours OAuth only for a provider definition that declares the flow. A models.json entry declares none, so the token under this key is never consulted — even a published placeholder is ignored, and the slot then fails with \"No API key found\".",
+      remedy:
+        "While the parent proxy is listening, present this slot to a child as a non-secret api_key placeholder and keep the OAuth blob where only the parent reads it.",
+    };
+  }
+
+  return {
+    usable: false,
+    slotId,
+    reason: "No credential is held for this slot.",
+    remedy: "Log in to this account, or drop the slot from the published registry.",
+  };
+}
+
+/**
+ * The slot a bare unpinned child would actually be sent to, given Pi's saved global default.
+ * Returns `undefined` when that saved route is usable.
+ *
+ * This is the check that turns a silent, far-away failure into something sayable here: when the
+ * active rotation slot is not child-usable, every child spawned without an explicit `--model`
+ * falls through Pi's own "first available provider" list instead — which is a different account,
+ * often a different vendor, and never the one the rotation chose.
+ */
+export function defaultRouteWarning(
+  savedDefaultSlotId: string | undefined,
+  classify: (slotId: string) => ChildUsability | undefined,
+): string | undefined {
+  if (!savedDefaultSlotId) return undefined;
+  const verdict = classify(savedDefaultSlotId);
+  if (!verdict || verdict.usable) return undefined;
+  return (
+    `Pi's saved global default is ${savedDefaultSlotId}, but a bare extension-free child launched ` +
+    `without --model cannot use it: ${verdict.reason} Such an unpinned child falls back to Pi's ` +
+    `own first-available provider. The live multi-account session and explicitly pinned ` +
+    `broker/subagent children are unaffected. ${verdict.remedy}`
+  );
+}
+
+/** One line per slot, for `/multi-account status`. Stable order: unusable first, then by id. */
+export function describeChildUsability(verdicts: readonly ChildUsability[]): string[] {
+  const ordered = [...verdicts].sort(
+    (a, b) => Number(a.usable) - Number(b.usable) || a.slotId.localeCompare(b.slotId),
+  );
+  return ordered.map((verdict) =>
+    verdict.usable
+      ? `  ${verdict.slotId} — usable by a bare child (${verdict.via})`
+      : `  ${verdict.slotId} — NOT usable by a bare child: ${verdict.reason}`,
+  );
+}

package/node_modules/pi-multi-account/compaction-summary.ts

@@ -0,0 +1,32 @@
+/**
+ * Guard against Pi throwing away an accumulated compaction summary.
+ *
+ * Pi's `compact()` has a branch for "the cut fell inside a turn": it summarizes the history
+ * range, summarizes the turn prefix, and glues them together. When the history range is empty —
+ * which is exactly what happens when a second compaction fires minutes after the first — that
+ * branch substitutes the literal string "No prior history." and never passes `previousSummary`
+ * to the model at all. The new compaction entry then replaces the accumulated summary with a
+ * note about one truncated turn, and everything the session had learned is gone.
+ *
+ * Seen in a real session: an 11 130-char summary became 2 032 chars beginning "No prior history."
+ * and describing work from a different day.
+ *
+ * We intercept compaction anyway (to route it to a healthy account), so the repair goes here:
+ * put the previous summary back where the placeholder is, keeping the turn-prefix context Pi
+ * did manage to produce.
+ */
+
+/** The exact placeholder Pi writes when it has no history left to summarize. */
+const NO_HISTORY_PLACEHOLDER = "No prior history.";
+
+export function restorePreviousSummary(summary: string, previousSummary?: string): string {
+  if (!summary.startsWith(NO_HISTORY_PLACEHOLDER)) return summary;
+  const previous = previousSummary?.trim();
+  if (!previous) return summary;
+  return `${previous}${summary.slice(NO_HISTORY_PLACEHOLDER.length)}`;
+}
+
+/** True when Pi produced a summary that dropped an existing accumulated summary. */
+export function droppedPreviousSummary(summary: string, previousSummary?: string): boolean {
+  return summary.startsWith(NO_HISTORY_PLACEHOLDER) && !!previousSummary?.trim();
+}