Merge pull request #318 from ndycode/release/mainbound-20260323

release: merge current main-target PR set

Author: ndycode

.github/workflows/pr-ci.yml

@@ -49,3 +49,61 @@ jobs:
 
       - name: Build
         run: npm run build
+
+      - name: Typecheck scripts
+        run: npm run typecheck:scripts
+
+      - name: Pack budget check
+        run: npm run pack:check
+
+      - name: Verify vendor provenance
+        run: npm run vendor:verify
+
+  node22-smoke:
+    name: Node 22 Smoke
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run type check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+      - name: Security audit (CI policy)
+        run: npm run audit:ci
+
+      - name: Build
+        run: npm run build
+
+  scripts-windows:
+    name: Script Typecheck (Windows)
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck scripts
+        run: npm run typecheck:scripts

README.md

@@ -62,8 +62,11 @@ npm i -g codex-multi-auth
 
 ### Option C: Verify wiring
 
+`codex --version` confirms the official Codex CLI is reachable. `codex-multi-auth --version` confirms the installed wrapper package version.
+
 ```bash
 codex --version
+codex-multi-auth --version
 codex auth status
 ```
 
@@ -93,54 +96,65 @@ codex auth check
 
 ## Quick Start
 
+Install and sign in:
+
 ```bash
+npm i -g @openai/codex
+npm i -g codex-multi-auth
 codex auth login
+```
+
+Verify the wrapper and the new account:
+
+```bash
 codex auth status
 codex auth check
-codex auth forecast --live
 ```
 
-Day-1 command set:
+Use these next:
 
 ```bash
+codex auth list
 codex auth switch 2
-codex auth report --live --json
-codex auth fix --dry-run
-codex auth doctor --fix
+codex auth forecast --live
 ```
 
-If the shell should not launch a browser, use the manual callback flow:
+If browser launch is blocked, use the alternate login paths in [docs/getting-started.md](docs/getting-started.md#alternate-login-paths).
 
-```bash
-codex auth login --manual
-CODEX_AUTH_NO_BROWSER=1 codex auth login
-```
+---
 
-In non-TTY/manual shells, provide the full redirect URL on stdin instead of waiting for a browser callback:
+## Command Toolkit
 
-```bash
-echo "http://127.0.0.1:1455/auth/callback?code=..." | codex auth login --manual
-```
+### Start here
 
-No new npm scripts or storage migration steps are required for this login-flow update.
+| Command | What it answers |
+| --- | --- |
+| `codex auth login` | How do I add or re-open the account menu? |
+| `codex auth status` | Is the wrapper active right now? |
+| `codex auth check` | Do my saved accounts look healthy? |
 
----
+### Daily use
 
-## Command Toolkit
+| Command | What it answers |
+| --- | --- |
+| `codex auth list` | Which accounts are saved and which one is active? |
+| `codex auth switch <index>` | How do I move to a different saved account? |
+| `codex auth forecast --live` | Which account looks best for the next session? |
 
-| Command | What it does |
+### Repair
+
+| Command | What it answers |
 | --- | --- |
-| `codex auth login` | Open interactive account dashboard |
-| `codex auth list` | List saved accounts and active account |
-| `codex auth status` | Print short runtime/status summary |
-| `codex auth switch <index>` | Set active account by index |
-| `codex auth check` | Run quick account health checks |
-| `codex auth verify-flagged` | Re-test flagged accounts and optionally restore |
-| `codex auth forecast --live` | Forecast best next account with live probes |
-| `codex auth report --live --json` | Generate machine-readable health report |
-| `codex auth fix --dry-run` | Preview safe repairs |
-| `codex auth fix --live --model gpt-5-codex` | Run repairs with live probe model |
-| `codex auth doctor --fix` | Diagnose and apply safe fixes |
+| `codex auth verify-flagged` | Can any previously flagged account be restored? |
+| `codex auth fix --dry-run` | What safe storage or account repairs are available? |
+| `codex auth doctor --fix` | Can the CLI diagnose and apply the safest fixes now? |
+
+### Advanced
+
+| Command | What it answers |
+| --- | --- |
+| `codex auth report --live --json` | How do I get the full machine-readable health report? |
+| `codex auth fix --live --model gpt-5-codex` | How do I run live repair probes with a chosen model? |
 
 ---
 
@@ -199,6 +213,7 @@ Selected runtime/environment overrides:
 | `CODEX_TUI_V2=0/1` | Disable/enable TUI v2 |
 | `CODEX_TUI_COLOR_PROFILE=truecolor|ansi256|ansi16` | TUI color profile |
 | `CODEX_TUI_GLYPHS=ascii|unicode|auto` | TUI glyph style |
+| `CODEX_AUTH_BACKGROUND_RESPONSES=0/1` | Opt in/out of stateful Responses `background: true` compatibility |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>` | Request timeout override |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Stream stall timeout override |
 
@@ -210,6 +225,8 @@ codex auth check
 codex auth forecast --live
 ```
 
+Responses background mode stays opt-in. Enable `backgroundResponses` in settings or `CODEX_AUTH_BACKGROUND_RESPONSES=1` only for callers that intentionally send `background: true`, because those requests switch from stateless `store=false` routing to stateful `store=true`. See [docs/upgrade.md](docs/upgrade.md) for rollout guidance.
+
 ---
 
 ## Experimental Settings Highlights
@@ -291,9 +308,9 @@ codex auth doctor --json
 
 ## Release Notes
 
-- Current stable: [docs/releases/v1.2.0.md](docs/releases/v1.2.0.md)
-- Previous stable: [docs/releases/v1.1.10.md](docs/releases/v1.1.10.md)
-- Earlier stable: [docs/releases/v0.1.9.md](docs/releases/v0.1.9.md)
+- Current stable: [docs/releases/v1.1.10.md](docs/releases/v1.1.10.md)
+- Previous stable: [docs/releases/v0.1.9.md](docs/releases/v0.1.9.md)
+- Earlier stable: [docs/releases/v0.1.8.md](docs/releases/v0.1.8.md)
 - Archived prerelease: [docs/releases/v0.1.0-beta.0.md](docs/releases/v0.1.0-beta.0.md)
 
 ## License

docs/README.md

@@ -7,35 +7,41 @@ Public documentation for `codex-multi-auth`.
 ## Start Here
 
 1. [Getting Started](getting-started.md)
-2. [FAQ](faq.md)
-3. [Architecture](architecture.md)
+2. [Daily-use landing page](index.md)
+3. [FAQ](faq.md)
 4. [Troubleshooting](troubleshooting.md)
 
 ---
 
-## User Guides
+## Daily Use
 
 | Document | Focus |
 | --- | --- |
-| [index.md](index.md) | Daily-use landing page for common `codex auth ...` workflows |
-| [getting-started.md](getting-started.md) | Install, first login, and first health check |
+| [Daily-use landing page](index.md) | Common `codex auth ...` workflows and quick-start guidance |
 | [faq.md](faq.md) | Short answers to common adoption questions |
-| [architecture.md](architecture.md) | Public system overview of the wrapper, storage, and optional plugin runtime |
 | [features.md](features.md) | User-facing capability map |
 | [configuration.md](configuration.md) | Stable defaults, precedence, and environment overrides |
-| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, switching, and stale state |
+| [architecture.md](architecture.md) | Public system overview of the wrapper, storage, and optional plugin runtime |
 | [privacy.md](privacy.md) | Data handling and local storage behavior |
-| [upgrade.md](upgrade.md) | Migration from legacy package and path history |
-| [releases/v1.2.0.md](releases/v1.2.0.md) | Stable release notes |
-| [releases/v1.1.10.md](releases/v1.1.10.md) | Previous stable release notes |
-| [releases/v0.1.9.md](releases/v0.1.9.md) | Earlier stable release notes |
+| [releases/v1.1.10.md](releases/v1.1.10.md) | Stable release notes |
+| [releases/v0.1.9.md](releases/v0.1.9.md) | Previous stable release notes |
+| [releases/v0.1.8.md](releases/v0.1.8.md) | Earlier stable release notes |
 | [releases/v0.1.7.md](releases/v0.1.7.md) | Archived stable release notes |
 | [releases/v0.1.6.md](releases/v0.1.6.md) | Archived stable release notes |
 | [releases/v0.1.5.md](releases/v0.1.5.md) | Archived stable release notes |
 | [releases/v0.1.0-beta.0.md](releases/v0.1.0-beta.0.md) | Archived prerelease notes |
 
 ---
 
+## Repair
+
+| Document | Focus |
+| --- | --- |
+| [troubleshooting.md](troubleshooting.md) | Recovery playbooks for install, login, switching, and stale state |
+| [upgrade.md](upgrade.md) | Migration from legacy package and path history |
+
+---
+
 ## Reference
 
 | Document | Focus |
@@ -45,9 +51,9 @@ Public documentation for `codex-multi-auth`.
 | [reference/storage-paths.md](reference/storage-paths.md) | Canonical and compatibility storage paths |
 | [reference/public-api.md](reference/public-api.md) | Public API stability and semver contract |
 | [reference/error-contracts.md](reference/error-contracts.md) | CLI, JSON, and helper error semantics |
-| [releases/v1.2.0.md](releases/v1.2.0.md) | Current stable release notes |
+| [releases/v1.1.10.md](releases/v1.1.10.md) | Current stable release notes |
 | [releases/v0.1.0-beta.0.md](releases/v0.1.0-beta.0.md) | Archived prerelease reference |
-| [User Guides release notes](#user-guides) | Stable, previous, and archived release notes |
+| [Daily Use release notes](#daily-use) | Stable, previous, and archived release notes |
 | [releases/legacy-pre-0.1-history.md](releases/legacy-pre-0.1-history.md) | Archived pre-0.1 changelog history |
 
 ---
@@ -62,7 +68,13 @@ Public documentation for `codex-multi-auth`.
 | [development/IA_FINDABILITY_AUDIT_2026-03-01.md](development/IA_FINDABILITY_AUDIT_2026-03-01.md) | IA and findability baseline audit |
 | [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md) | Complete field and environment inventory |
 | [development/CONFIG_FLOW.md](development/CONFIG_FLOW.md) | Configuration resolution flow |
+| [development/RUNBOOK_ADD_AUTH_COMMAND.md](development/RUNBOOK_ADD_AUTH_COMMAND.md) | Safe workflow for adding a new `codex auth ...` command |
+| [development/RUNBOOK_ADD_CONFIG_FIELD.md](development/RUNBOOK_ADD_CONFIG_FIELD.md) | Safe workflow for introducing a new config field |
+| [development/RUNBOOK_CHANGE_ROUTING_POLICY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY.md) | Safe workflow for changing routing, retry, or fallback policy |
 | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path |
+| [development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md](development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md) | Safe workflow for adding a new `codex auth` command |
+| [development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md](development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md) | Safe workflow for introducing a new config/settings field |
+| [development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md](development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md) | Safe workflow for changing routing or account-selection policy |
 | [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix |
 | [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist |
 | [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark methodology and outputs |

docs/development/CONFIG_FIELDS.md

@@ -31,6 +31,7 @@ Used only for host plugin mode through the host runtime config file.
 | `reasoningEffort` | string | `none\|minimal\|low\|medium\|high\|xhigh` | Reasoning effort hint |
 | `reasoningSummary` | string | `auto\|concise\|detailed` | Summary detail hint |
 | `textVerbosity` | string | `low\|medium\|high` | Text verbosity target |
+| `promptCacheRetention` | string | `5m\|1h\|24h\|7d` | Default server-side prompt cache retention when the request body omits `prompt_cache_retention` |
 | `include` | string[] | `reasoning.encrypted_content` | Extra payload include |
 | `store` | boolean | `false` | Required for stateless backend mode |
 
@@ -74,10 +75,19 @@ Used only for host plugin mode through the host runtime config file.
 | `tokenRefreshSkewMs` | `60000` |
 | `sessionRecovery` | `true` |
 | `autoResume` | `true` |
+| `responseContinuation` | `false` |
+| `backgroundResponses` | `false` |
 | `proactiveRefreshGuardian` | `true` |
 | `proactiveRefreshIntervalMs` | `60000` |
 | `proactiveRefreshBufferMs` | `300000` |
 
+`backgroundResponses` is an opt-in compatibility switch for Responses API `background: true` requests. When enabled, those requests become stateful (`store=true`) instead of following the default stateless Codex routing.
+
+Upgrade note:
+- Leave this disabled for existing stateless pipelines that do not intentionally send `background: true`.
+- Enable it only for callers that need stateful background responses and can accept forced `store=true`, preserved input item IDs, and the loss of stateless-only defaults such as fast-session trimming.
+- After enabling it, test one known `background: true` request end to end before rolling it across shared automation.
+
 ### Storage / Sync
 
 | Key | Default |

docs/development/RUNBOOK_ADD_AUTH_COMMAND.md

@@ -0,0 +1,61 @@
+# Runbook: Add Auth Command
+
+Safe workflow for adding a new `codex auth ...` command without expanding scope or breaking the existing CLI contract.
+
+* * *
+
+## Goal
+
+Add one new command path while keeping:
+
+- `codex auth ...` as the canonical command family
+- current help text and aliases aligned with docs
+- JSON and human-readable output predictable
+- command behavior covered by targeted tests
+
+* * *
+
+## Primary Files
+
+- `lib/codex-manager.ts`
+- `docs/reference/commands.md`
+- `README.md` when user-visible workflow changes
+- `test/codex-manager-cli.test.ts`
+- `test/documentation.test.ts`
+
+* * *
+
+## Implementation Steps
+
+1. Add the command logic in `lib/codex-manager.ts` or the current command handler module.
+2. Keep usage text literal and copy-pasteable.
+3. Reuse existing storage, refresh, and quota helpers instead of adding new command-local state.
+4. Add or extend CLI tests in `test/codex-manager-cli.test.ts` for:
+   - success path
+   - invalid input or missing args
+   - JSON mode if supported
+   - non-interactive behavior if relevant
+5. Update `docs/reference/commands.md` with the command and flags.
+6. Update `README.md` only when the command changes the recommended user workflow.
+7. Update `test/documentation.test.ts` if new command text must stay aligned across docs and runtime usage text.
+
+* * *
+
+## Validation
+
+```bash
+npm run lint
+npm run typecheck
+npm test -- test/codex-manager-cli.test.ts test/documentation.test.ts
+npm run build
+```
+
+* * *
+
+## Review Checklist
+
+- command name is consistent across runtime and docs
+- help text matches actual flags
+- no unrelated settings or storage changes were mixed in
+- JSON output is stable if exposed
+- tests cover failure paths, not only the happy path