chore: release v2.1.13-beta.0 (#490)

Prerelease that ships the pinned-account 503 diagnostic surface from
#487 (issue #486) to npm under the `beta` dist-tag. Users who can
reproduce the recurring 503 should install via
`npm i -g codex-multi-auth@beta` so the new structured `reason` and
`account_skip_reasons` fields are visible in their next failure, then
attach the body plus logs to issue #486 for root-cause analysis.

Stable v2.1.13 will land once the underlying forecast-vs-runtime state
desync is identified and patched.

Author: ndycode

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-multi-auth",
-  "version": "2.1.12",
+  "version": "2.1.13-beta.0",
   "description": "Install and operate codex-multi-auth for the official @openai/codex CLI with multi-account OAuth rotation, switching, health checks, and recovery tools.",
   "interface": {
     "composerIcon": "./assets/codex-multi-auth-icon.svg"

README.md

@@ -383,6 +383,7 @@ codex-multi-auth doctor --json
 
 ## Release Notes
 
+- Current prerelease: [docs/releases/v2.1.13-beta.0.md](docs/releases/v2.1.13-beta.0.md) — install via `npm i -g codex-multi-auth@beta`
 - Current stable: [docs/releases/v2.1.12.md](docs/releases/v2.1.12.md)
 - Previous stable: [docs/releases/v2.1.11.md](docs/releases/v2.1.11.md)
 - Earlier stable: [docs/releases/v2.1.10.md](docs/releases/v2.1.10.md)

docs/README.md

@@ -32,6 +32,7 @@ Public documentation for the `codex-multi-auth` Codex CLI multi-account OAuth ma
 
 | Document | Focus |
 | --- | --- |
+| [releases/v2.1.13-beta.0.md](releases/v2.1.13-beta.0.md) | Current prerelease notes (install via `npm i -g codex-multi-auth@beta`) |
 | [releases/v2.1.12.md](releases/v2.1.12.md) | Current stable release notes |
 | [releases/v2.1.11.md](releases/v2.1.11.md) | Prior stable release notes |
 | [releases/v2.1.10.md](releases/v2.1.10.md) | Earlier stable release notes |

docs/releases/v2.1.13-beta.0.md

@@ -0,0 +1,42 @@
+# v2.1.13-beta.0
+
+Beta prerelease that adds a diagnostic surface to the runtime rotation proxy's pinned-account 503 path. Issued so users who hit the recurring 503 reported in issue #486 can install the patched build, reproduce, and return the new structured `reason` field for root-cause analysis.
+
+This is a **prerelease**. Stable `v2.1.13` will land once the underlying forecast-vs-runtime state desync is identified and patched.
+
+## Install
+
+```bash
+npm i -g codex-multi-auth@beta
+```
+
+## Runtime Rotation
+
+### Fixes
+
+- Pinned-account 503 (`codex_pinned_account_unavailable`) now carries a structured `reason` field and a full `account_skip_reasons` map keyed by account index, mirroring the existing `writePoolExhausted` shape. Consumers can branch on the same payload across both 503 codes.
+- Human-readable `message` appends the skip reason in parentheses when present, for example `Pinned account 2 is currently unavailable (rate-limited); run ...`.
+- A missing skip reason resolves to explicit `null` in the response body and is recorded in `status.lastError` so a forecast-vs-runtime state desync becomes detectable instead of silently masked as `unknown`.
+- Extracted `buildPinnedUnavailableErrorBody` helper so the 503 payload shape is unit-testable in isolation; exported alongside a typed `PinnedUnavailableErrorBody` interface for stable external consumption.
+
+## Release Hygiene
+
+### Tests
+
+- Added end-to-end regression coverage for the pinned-503 rate-limited and cooling-down paths; existing disabled-account case extended to assert the new structured fields.
+- Extended `chooseAccount` unit suite to cover every pinned skip reason returned by `AccountManager.getAccountRuntimeSkipReason`: `rate-limited`, `cooling-down:auth-failure`, `disabled`, `workspace-disabled`, `circuit-open`, `policy-blocked`, `missing`, `already-attempted`.
+- Added direct unit coverage for `buildPinnedUnavailableErrorBody` across the empty-map (`reason: null`), populated-map, null-`pinnedIndex`, and mismatched-pinned-entry shapes.
+
+## Documentation
+
+- `docs/reference/error-contracts.md` documents the new `reason` and `account_skip_reasons` fields on the pinned-503 payload.
+
+## Known Gaps
+
+- The 503 root cause from issue #486 (doctor reports all green, runtime still returns 503) is **not** fixed by this prerelease. Users who reproduce on this build should set `ENABLE_PLUGIN_REQUEST_LOGGING=1`, repro, and attach the new 503 body plus logs from `~/.codex/multi-auth/logs/codex-plugin/` to issue #486.
+- Plugins-disabled and per-project history-loss symptoms reported alongside #486 are tracked separately in #488 and #489.
+
+## Refs
+
+- Issue #486 — `[bug] 503 Service Unavailable`
+- PR #487 — `fix(runtime): surface skip reason in pinned 503 (#486)`

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-multi-auth",
-	"version": "2.1.12",
+	"version": "2.1.13-beta.0",
 	"description": "Codex CLI multi-account OAuth manager with account switching, health checks, runtime rotation, diagnostics, and recovery tools for @openai/codex",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",