Master Repository Audit — codex-multi-auth

Historical snapshot: this audit was captured against codex-multi-auth@1.2.7 before the 2.0 runtime-rotation architecture. Preserve the evidence and findings as historical audit material. For current architecture, use docs/architecture.md and docs/development/ARCHITECTURE.md.

Audit Date: 2026-04-17 HEAD: 1f6da97d06dcc8c268b304e6e45b6baa9a386679 Branch: main Package: codex-multi-auth@1.2.7 Node: (captured in evidence/context.txt) Audit methodology: Sisyphus multi-wave plan executed under Atlas; evidence under docs/audits/evidence/ Composition note: Findings composed from dimension deep-dives (dim-C through dim-P). Several dimensions composed by Atlas from captured sub-agent analysis when agents exceeded step budgets before writing deliverables.

Severity Rubric

• CRITICAL: token/auth corruption, data loss, unsafe credential handling, or core trust breakage
• HIGH: likely real-world operational pain, hard-to-debug failures, serious maintainability or resilience risk, bypassable security
• MEDIUM: meaningful architecture/testing/DX weakness, degraded UX
• LOW: cleanup, polish, consistency

Dimensions Audited (Coverage Matrix)

Dim	Area	Primary Section	Evidence File
Dimension A	Product / system understanding	§1 Executive, §2 System Map	inventory.txt, context.txt
Dimension B	Architecture	§2 System Map, §8 Refactors, §16 Modules	all dim-*.md
Dimension C	Auth / OAuth / token lifecycle	§5 HIGH (H4, H5), §10 Security	dim-C-auth.md
Dimension D	Multi-account / routing / failover	§5 HIGH (H2, H3, H10), §6 MEDIUM	dim-D-routing.md
Dimension E	Storage / filesystem / state	§5 HIGH (H1), §6 MEDIUM (M01-M05)	dim-E-storage.md
Dimension F	Config / settings / precedence	§5 HIGH (H6), §6 MEDIUM (M21-M23)	dim-F-config.md
Dimension G	CLI / UX	§6 MEDIUM (M24-M28), §12	dim-G-cli.md
Dimension H	Request / SSE / resilience	§5 HIGH (H9), §6 MEDIUM (M16-M19)	dim-H-request.md
Dimension I	Type safety / validation	§6 MEDIUM (M20), §10	dim-I-types.md
Dimension J	Error handling	§6 MEDIUM (M29), §10	dim-JN-errors-health.md
Dimension K	Tests	§5 HIGH (H8), §11	dim-K-tests.md
Dimension L	Release / CI / OSS	§5 HIGH (H7, H8), §12	dim-LM-release-docs.md
Dimension M	Docs accuracy	§5 HIGH (H5, H8), §12	dim-LM-release-docs.md + docs-claims.txt
Dimension N	Code health / cleanup	§6 MEDIUM (M30, M31), §7	dim-JN-errors-health.md
Dimension O	Features	§9	feature-recs inline
Dimension P	Perf (lightweight)	§6 MEDIUM (M34, M35), §7 (L11)	dim-P-perf.md

Table of Contents

1. Executive Summary
2. System Map
3. What Is Already Strong
4. Critical Issues
5. High-Priority Improvements
6. Medium Improvements
7. Low-Priority Cleanups
8. Refactoring Plan
9. Feature Recommendations
10. Security / Trust Review
11. Testing Gap Analysis
12. CLI / DX / Docs Review
13. Quick Wins
14. Phased Implementation Roadmap
15. Top 20 Recommended Actions
16. Module-by-Module Notes
17. Final Verdict

---

1. Executive Summary

Maturity: 4/5. codex-multi-auth is a structurally healthy, security-conscious CLI-first OAuth manager. Strict TypeScript, centralized Zod schemas for high-risk payloads, no-explicit-any enforced (verified: 0 occurrences), @ts-ignore absent, clean typecheck, clean lint, clean audit:ci, clean vendor:verify, recent security-dep bump cadence, full OSS governance stack (SECURITY.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE), 4 CI workflows including CodeQL, and 3418 tests across 225 files with verified hermetic execution under redirected HOME + CODEX_MULTI_AUTH_DIR.

Biggest strengths (preserve):

• Hermeticity: tests do not leak to real ~/.codex/multi-auth/ when env-redirected — zero delta verified (see K-05)
• Strict TypeScript discipline: 0 as any, 0 @ts-ignore across lib/ + index.ts (I-01, I-02)
• Refresh-queue race prevention: token-keyed dedupe + rotation handoff + rollback on persist fail (C-10)
• Atomic writes for primary account storage + flagged storage + unified settings: temp+rename pattern used (E-03 positive)
• Request-loop termination safety: 4 independent guards prevent infinite retry (H-09)
• OSS readiness: governance files complete; CodeQL workflow + dep scanner workflow in CI (LM-03, LM-08)

Biggest risks:

1. resolvePath() path-guard regression on HEAD — test/paths.test.ts:846 fails; lookalike-prefix paths outside the home directory are not rejected; gates import/export, so a guard failure can redirect reads/writes outside approved roots (E-01, K-02)
2. Hybrid account selector can return blocked/unavailable accounts — selectHybridAccount() falls back to LRU even when available.length === 0; fetch loop trusts it without re-validating (D-01)
3. Plugin config precedence bug — loadPluginConfig does not prefer primary CONFIG_PATH over CODEX_HOME legacy path; test/plugin-config.test.ts:417 fails on HEAD (F-01, K-04)
4. Live OAuth URL leaks to stdout/clipboard — browser-fallback and manual login print raw URL containing live state and code_challenge (C-AUTH-05)
5. Docs-to-code drift: AGENTS.md claims v0.1.x / "87 files, 2071 tests" — reality is v1.2.7 / 225 files / 3418 tests; README/docs claim canonical redirect 127.0.0.1:1455 but code uses localhost:1455 (LM-02, LM-12, C-AUTH-03)

Top 5 priorities for the next cycle:

1. Fix resolvePath() lookalike bypass + plugin-config precedence + codex-manager-cli auth list message drift (the 3 failing tests are all real regressions)
2. Re-validate account availability after selectHybridAccount() OR change its contract to return null when no account is available
3. Redact OAuth URL in user-facing output (show host/port only, keep full URL for clipboard/browser handoff)
4. Fix pack:check bloat and truth-up AGENTS.md + docs redirect host
5. Split settings-hub.ts (2100 LOC) into sub-concern files (theme, accounts, sync, diagnostics, experimental)

---

2. System Map

Architecture (inferred)

User (CLI/terminal)
  │
  â–¼
scripts/codex.js  (bin wrapper — lazy-load auth runtime)
  │
  â–¼
lib/codex-manager.ts  (command dispatcher)
  ├── codex auth login|status|check|list|switch|forecast|verify-flagged|fix|doctor|report
  │
  ├─▶ lib/auth/  ────────────────┐
  │   auth.ts (PKCE, JWT, token)  │
  │   server.ts (callback :1455)  │
  │   browser.ts                  ▼
  │                        OAuth 2.0 Authorization Code + PKCE
  │                        https://auth.openai.com/...
  │
  ├─▶ lib/accounts.ts + lib/accounts/**  ──▶  lib/rotation.ts  ──▶  lib/health.ts
  │                                            (hybrid/round-robin/sticky)
  │                                                  │
  │                                                  ▼
  ├─▶ lib/request/** (index.ts 7-step pipeline)  ──▶  lib/circuit-breaker.ts
  │   URL rewrite → init → transform → continuation → account iter/refresh/headers
  │   → fetch+timeout+retry/rotation → success+SSE+failover
  │                                                  │
  │                                                  ▼
  │                                    OpenAI Codex backend (ChatGPT routing)
  │
  ├─▶ lib/storage.ts + lib/storage/**  ──▶  atomic writes
  │   V1 ↔ V3 migrations, worktree resolution, EBUSY retry
  │   ~/.codex/multi-auth/ or CODEX_MULTI_AUTH_DIR
  │
  ├─▶ lib/codex-manager/settings-hub.ts  (2100 LOC dashboard TUI)
  │
  └─▶ lib/ui/**  (ansi, auth-menu, theme, select, copy)

Storage/config flow

• Root: ~/.codex/multi-auth/ (override: CODEX_MULTI_AUTH_DIR)
• Settings: settings.json (EBUSY/EPERM retry, max 4 exponential)
• Accounts (global): openai-codex-accounts.json
• Accounts (project-scoped): projects/<project-key>/openai-codex-accounts.json
• Flagged: openai-codex-flagged-accounts.json
• Quota cache: quota-cache.json
• Runtime observability: runtime-observability.json
• Logs: logs/codex-plugin/
• Config path: CODEX_MULTI_AUTH_CONFIG_PATH primary, CODEX_HOME legacy (precedence currently BUGGY — F-01)

Trust boundaries

1. User ↔ CLI (low — stdin + fs)
2. CLI ↔ OS keychain / file system (MEDIUM — tokens persisted as plaintext JSON, mode 0600; larger-than-minimum secret footprint — C-AUTH-08)
3. CLI ↔ Browser / Localhost callback (HIGH — :1455 bound on any-interface; redirect URI mismatch risk C-AUTH-03)
4. CLI ↔ auth.openai.com (HIGH — OAuth endpoint; hardcoded single host, no allowlist abstraction C-AUTH-12)
5. CLI ↔ ChatGPT backend (HIGH — headers, rate-limits, model routing; failover across multiple accounts)
6. Multi-account isolation (MEDIUM — project-scoped storage can silently collapse to global when Codex CLI sync enabled D-06)

Highest-risk boundaries

• lib/storage/paths.ts::resolvePath() — path-guard for import/export (HIGH — regression at HEAD, E-01/K-02)
• lib/auth/auth.ts::REDIRECT_URI ↔ lib/auth/server.ts bind (HIGH — host mismatch C-AUTH-03)
• lib/accounts.ts::selectHybridAccount() ↔ fetch loop in index.ts (HIGH — unavailable-account selection D-01)
• Token file at rest — plaintext JSON with refresh tokens + cached access tokens (MEDIUM — C-AUTH-08)

---

3. What Is Already Strong

These decisions work well and should be preserved through any refactor:

Strength	Evidence	Preserve by
Hermetic test design — HOME / CODEX_MULTI_AUTH_DIR redirection produces zero drift under full suite	K-05	Keep env-redirect pattern; add regression test asserting hermeticity when new tests land
Strict TypeScript with zero escape hatches — 0 as any, 0 @ts-ignore, 0 @ts-expect-error, 0 @ts-nocheck in lib/ + index.ts; strict: true in tsconfig	I-01, I-02, I-05	Keep ESLint flat-config no-explicit-any rule; add CI gate if not present
Refresh-queue race prevention with token-keyed dedupe + rotation handoff + rollback on persist fail	C-10	Add a targeted regression test around rotation-then-persist-failure rollback if coverage does not already lock it
Atomic writes for primary account storage, flagged storage, unified settings, export	E-03 (positive)	Extend same pattern to recovery/session storage (currently violates — E-03)
4-gate request-loop termination (attempted.size, outbound budget, MAX_SHORT_RETRY_ATTEMPTS=3, MAX_STREAM_FAILOVERS=1)	H-09	Document the gates inline; add invariant test
Defensive storage corruption recovery — checksum-protected WAL + rotating backups	C-AUTH-09	Add observability signal when WAL/backup recovery is used so operators notice silent recovery
Structured CLI doctrine — doctor --fix dry-run safe; Q=cancel hotkey consistent; theme live-preview with baseline restore on cancel	G-07, G-05	Apply same --dry-run discipline to new repair commands
OSS governance — SECURITY.md, CODE_OF_CONDUCT, CONTRIBUTING, LICENSE, issue/PR templates, CodeQL + plugin scanner + dep scanner workflows	LM-03, LM-08	Keep the full governance stack
Clean supply chain — audit:ci (prod + dev allowlist) + vendor:verify + bundleDependencies + npm overrides	LM-04, LM-05	Keep; add per-release vendor manifest hash pinning if not present
Active security maintenance — recent hono 4.12.14, vite ^7.3.2 bumps at HEAD	LM-09	Keep dependabot cadence; keep Dependabot config
Refresh-failure taxonomy in lib/refresh-guardian.ts — rate-limit/auth/network bucketed cooldowns; missing-refresh accounts auto-disabled	C-AUTH-13	Surface bucketed states in operator diagnostics
Strong OAuth state generation — 16 bytes from node:crypto = 128-bit CSRF entropy	C-AUTH-02	Add invariant test; keep node:crypto source
Rich CLI surface organized by Start/Daily/Repair/Advanced per README	LM-11	Keep README structure; keep separation of repair commands from daily ops

---

4. Critical Issues

Updated 2026-04-17 post-Oracle review — see docs/audits/evidence/oracle-verdicts.md. Original draft had no CRITICAL findings; Oracle elevated AUDIT-H1 upon determining the failing unit test IS the reproduction.

ID	Severity	Claim	Evidence	Confidence	Impact	Fix direction
AUDIT-C1	CRITICAL	resolvePath() lookalike-prefix bypass — path-guard for import/export does not reject lookalike prefix paths outside home directory. Trust boundary broken: import/export surfaces can read from attacker-controlled siblings or write outside approved roots. Maps to "unsafe credential handling" + "core trust breakage" in severity rubric.	test/paths.test.ts:842-846 (FAILING on HEAD); lib/storage/paths.ts:333-357; cross-ref AUDIT-H1, E-01, K-02	confirmed (failing test = code-level reproduction)	Local-access attacker creates lookalike directory (e.g. <HOME>/.codex-multi-auth-evil/) that bypasses guard; affects both read + write surfaces	Harden isWithinDirectory() with canonicalization; add regression tests for home/project/tmp lookalikes on Windows + POSIX. Block next release on fix.

Post-Oracle severity adjustments (applied to findings-index.json with oracle_adjusted flag):

Original	Oracle Verdict	Finding	Rationale
HIGH	CRITICAL (elevated)	AUDIT-H1 resolvePath lookalike	Failing test = reproduction; path-guard failure = trust breakage
MEDIUM	HIGH (elevated)	AUDIT-M09 project-scope silent bypass on CLI sync	Silent credential leak across projects matches HIGH criteria
HIGH	MEDIUM (demoted)	AUDIT-H6 loadPluginConfig precedence	Workaround exists; narrow blast radius
HIGH	MEDIUM (demoted)	AUDIT-H8 AGENTS.md staleness	Docs drift only, no runtime impact
HIGH	MEDIUM (demoted)	AUDIT-H9 SSE malformed-chunk discard	Dim-H internally marked MEDIUM — reconciled
HIGH	MEDIUM (demoted)	AUDIT-H10 dangling active pointer	Operator-facing friction, no credential dimension
MEDIUM	HIGH (conditional)	AUDIT-M13 plaintext tokens at rest	Elevates to HIGH only if AUDIT-C1 ships unfixed

Final severity distribution (post-Oracle): 2 CRITICAL · 6 HIGH · 38 MEDIUM · 14 LOW (60 total incl. AUDIT-C1).

Oracle top-3 refactor verdict (confirmed with rationale, see oracle-verdicts.md §2):

1. R2 RedirectURI SSOT — closes AUDIT-H5 + eliminates drift class
2. R3 Zod at JSON.parse boundaries — additive, fail-closed, scales to 59 sites
3. R4 Routing mutex + selection-record — closes AUDIT-H2/H3/D09 simultaneously

Oracle assumptions flagged for follow-up validation (see oracle-verdicts.md §4):

• Inspect pack:check tarball for .env/fixtures/secrets — if present, AUDIT-H7 → CRITICAL
• Pin PKCE dep + audit source (C-AUTH-01)
• Spot-check 3 dim-H citations (salvaged from step-budget-truncated agent)
• Qualify hermeticity claim: applies to HOME/CODEX_MULTI_AUTH_DIR, NOT to CWD (evidenced by 6 tmp files at repo root)
• Count lib/schemas.ts schemas vs unique payload shapes across 59 parse sites (R3 cost estimation)

---

5. High-Priority Improvements

ID	Severity	Claim	Evidence	Fix direction
AUDIT-H1	HIGH	resolvePath() does not reject lookalike-prefix paths on HEAD — import/export path-guard regression; can redirect reads/writes outside approved home/project/tmp roots	E-01; K-02; test/paths.test.ts:842-846, lib/storage/paths.ts:333-357	Reproduce with real Windows+POSIX lookalike cases, harden isWithinDirectory(), add regression tests
AUDIT-H2	HIGH	Hybrid account selector returns unavailable accounts — selectHybridAccount() falls back to LRU even when available.length === 0; fetch loop trusts it	D-01; lib/rotation.ts:379-392, lib/accounts.ts:668-697, index.ts:1149-1157	Change selector contract to return null when no account available OR re-run isAccountAvailableForFamily() after hybrid selection
AUDIT-H3	HIGH	Short-window 429 retry does not mark account unavailable before sleeping — concurrent requests keep selecting the same freshly rate-limited account	D-07; index.ts:2089-2114, lib/accounts.ts:534-545,673-677	Write immediate transient rate-limit marker before short-retry sleep OR reserve account locally until sleep window ends
AUDIT-H4	HIGH	Live OAuth URL leaks to stdout/clipboard — browser-fallback and manual login print raw URL with live state and code_challenge	C-AUTH-05; lib/codex-manager.ts:1825-1841, lib/auth/auth.ts:15-20,262-269, lib/auth/browser.ts:158-177	Print redacted display URL; keep full URL only for clipboard/open-browser handoff; add --show-full-url debug escape hatch
AUDIT-H5	HIGH	Redirect host drift — code uses localhost:1455 but docs claim 127.0.0.1:1455	C-AUTH-03; lib/auth/auth.ts:12, lib/auth/server.ts:78-80,104, docs/reference/commands.md:84,98, CHANGELOG.md:125	Choose one canonical callback origin; derive all user-facing strings from it; align docs/tests
AUDIT-H6	HIGH	loadPluginConfig CONFIG_PATH precedence bug — does not prefer primary over legacy CODEX_HOME path when both exist	F-01; K-04; test/plugin-config.test.ts:417	Fix precedence order to match documented model (primary → legacy); add explicit precedence test matrix
AUDIT-H7	HIGH	npm run pack:check FAILS exit=1 — pack budget violation; published tarball likely includes unintended files	LM-01; docs/audits/evidence/pack-check.txt	Inspect pack manifest; tighten files field in package.json; add CI gate on pack size delta
AUDIT-H8	HIGH	AGENTS.md stale across 4 axes — v0.1.x/Commit 9ac8a84/Generated 2026-03-01/"87 files, 2071 tests" vs reality v1.2.7/1f6da97/225 files/3418 tests	LM-02; K-01; AGENTS.md §OVERVIEW vs context.txt	Regenerate AGENTS.md via /init-deep or equivalent; make generation a release gate
AUDIT-H9	HIGH	SSE non-streaming conversion buffers full stream up to 10MB and silently discards malformed JSON chunks	H-03; lib/request/response-handler.ts	Surface malformed-chunk warnings via logger.warn; add structured parse-error taxonomy; consider streaming decode instead of buffer-then-parse
AUDIT-H10	HIGH	Active-account pointer can dangle after disable — getActiveIndexForFamily() clamps bounds only; setAccountEnabled() does not repair pointer	D-05; lib/accounts.ts:506-512,583-592,1145-1155, lib/runtime/account-status.ts:10-17	Normalize active indices on every disable/remove; "active" means routable, not merely in-range

---

6. Medium Improvements

ID	Severity	Claim	Evidence	Fix direction
AUDIT-M01	MEDIUM	Recovery/session storage uses direct sync writes/deletes (no atomic temp+rename, no retry)	E-03; lib/recovery/storage.ts:7,167-168,261-262,281-282,374-375	Introduce shared atomic-write helper for recovery files + retry-safe deletes on Windows lock codes
AUDIT-M02	MEDIUM	Concurrency guard is in-process only — two CLI processes can race on shared ~/.codex/multi-auth files	E-04; lib/storage/transactions.ts:10-34, lib/unified-settings.ts:23,423-430	Add advisory file locking OR journal/compare-and-swap for shared files
AUDIT-M03	MEDIUM	Active code supports V1↔V3 only; no V2 migration path despite docs claiming V1/V2→V3	E-05; lib/storage.ts:1155-1180, lib/storage/migrations.ts:83-116	Implement explicit V2 handling OR correct docs
AUDIT-M04	MEDIUM	Account-clear writes reset marker AFTER deleting artifacts — crash between looks like accidental loss	E-07; lib/storage/account-clear.ts:58-64	Align account-clear ordering with flagged-clear flow: marker first
AUDIT-M05	MEDIUM	Flagged-account read retry omits EPERM	E-08; lib/storage/flagged-storage-file.ts:4-26, lib/storage/flagged-storage-io.ts:34-52	Include EPERM in retryable flagged-read codes
AUDIT-M06	MEDIUM	Routing non-determinism — PID-based bias + cursor mutation makes reproduction hard	D-02; lib/rotation.ts:332-338,400-425, lib/accounts.ts:693-696	Make deterministic mode default; gate PID bias behind explicit opt-in flag
AUDIT-M07	MEDIUM	Health + quota tracker state NOT persisted; resets on restart	D-03; lib/rotation.ts:78-83,184-188,543-557, lib/accounts.ts:887-910	Persist routing state OR explicitly mark ephemeral + avoid "stable" health claims
AUDIT-M08	MEDIUM	lib/health.ts stale vs live AccountManager state — uses wrong field names	D-04; lib/health.ts:27-53, lib/accounts.ts:253-255,725-731,806-818	Rebuild health report from AccountManager directly OR delete stale abstraction
AUDIT-M09	MEDIUM	Project-scoped isolation silently bypassed when Codex CLI sync enabled — forces global storage	D-06; lib/runtime/storage-scope.ts:20-34, lib/storage.ts:598-623	Treat as hard config conflict with surfaced state; scope synced state per project identity
AUDIT-M10	MEDIUM	Stream failover bypasses server-error policy path — 5xx bursts on fallback don't update shared cooldown	D-08; index.ts:1974-2059,2198-2507,2395-2445	Reuse evaluateFailurePolicy() helper inside stream failover
AUDIT-M11	MEDIUM	Callback server doesn't eager-close on terminal outcomes; close() doesn't await shutdown	C-AUTH-11; lib/auth/server.ts:41-99	Close immediately after terminal outcomes; convert mismatch/duplicate-code paths into explicit terminal results
AUDIT-M12	MEDIUM	Token freshness trusts persisted expires/expiresAt only — doesn't decode JWT exp	C-AUTH-07; lib/proactive-refresh.ts:54-72,81-85, lib/auth/auth.ts:165-179, lib/accounts.ts:1033-1039	Fall back to decoded JWT exp when metadata missing; treat missing expiry as refresh-needed
AUDIT-M13	MEDIUM	Access tokens + refresh tokens both stored plaintext JSON (file mode 0600)	C-AUTH-08; lib/storage/migrations.ts:46-69, lib/accounts.ts:887-907, lib/storage.ts:1673-1687	Minimize access-token caching OR move secrets to OS keychain
AUDIT-M14	MEDIUM	Port 1455 duplicated across server bind + status copy + oauth-success.html instead of derived from single parsed redirect URI	C-AUTH-04; lib/auth/server.ts:78-80,107, lib/ui/copy.ts:67, lib/oauth-success.html:117-123	Parse redirect URI once; feed server bind + UI copy + html from shared helpers
AUDIT-M15	MEDIUM	Manual-paste callback returns null on state mismatch — surfaced as generic callback-miss text	C-AUTH-06; lib/codex-manager.ts:1257-1332,1854-1867, lib/runtime/manual-oauth-flow.ts:59-69,81-86	Return structured mismatch error; surface explicit state-mismatch in both flows
AUDIT-M16	MEDIUM	No distinct connect timeout — single total timeout for both connect + body/stream	H-02; lib/request/fetch-helpers.ts:724-969	Add connectTimeoutMs separate from total + stall
AUDIT-M17	MEDIUM	Observability uneven — trace ID / account ID / attempt # not uniformly attached across retry/failover branches	H-05; index.ts multi call sites	Define log schema with mandatory correlation fields; structured logger with required keys
AUDIT-M18	MEDIUM	Deprecation/sunset headers logged in success path only — not in error paths	H-08; lib/request/fetch-helpers.ts	Log deprecation headers in both success + error handling
AUDIT-M19	MEDIUM	Mid-stream failover intentionally disabled after first byte — users see hard error mid-generation	H-04; lib/request/stream-failover.ts	Document limitation; consider opt-in "resume with marker" for idempotent prompts
AUDIT-M20	MEDIUM	JSON.parse surface is 59 calls across 31 files; schema validation centralized in single lib/schemas.ts not applied at parse boundaries	I-03, I-04; lib/schemas.ts; high clusters in request-init, runtime/request-init, storage, recovery, fetch-helpers	Wrap JSON.parse call sites with safeParse* helpers from lib/schemas.ts; add schemas for currently-unvalidated payloads
AUDIT-M21	MEDIUM	Dual-linter stack (eslint + biome) without documented scope separation	F-02; repo root files, package.json scripts	Adopt one OR document scope split (biome=format, eslint=correctness)
AUDIT-M22	MEDIUM	prepare hook installs husky on every npm install — mutates .git/hooks/ as side effect	F-03; package.json scripts.prepare	Document side effect prominently in CONTRIBUTING; consider opt-in install
AUDIT-M23	MEDIUM	Env var surface 11+ vars; no central env-schema	F-04; README Configuration section	Centralize env validation via z.object() in lib/schemas.ts; parse process.env at startup
AUDIT-M24	MEDIUM	settings-hub.ts ~2100 LOC — overgrown file mixing theme/account/sync/diagnostics/experimental	G-01, JN-03; AGENTS.md §WHERE TO LOOK	Split by sub-concern (see Section 8 Refactor R1)
AUDIT-M25	MEDIUM	auth list empty-storage message drift — test expects "Storage was intentionally reset." but code outputs "No accounts configured." / "Storage: " / "Storage health: empty"	G-02, K-03; test/codex-manager-cli.test.ts:913	Align code output to documented messaging or update tests after agreeing on canonical message
AUDIT-M26	MEDIUM	--json coverage unclear across subcommand surface (confirmed on report, doctor, verify-flagged; unverified on list, switch, check, forecast, fix)	G-03; README	Audit each subcommand; standardize --json + deterministic exit codes + schema
AUDIT-M27	MEDIUM	Bifurcation lib/codex-cli/ and lib/codex-manager/ without documented boundary	G-06, JN-04; AGENTS.md §STRUCTURE	Document ownership map OR merge
AUDIT-M28	MEDIUM	Experimental settings flagged but no stability-promise policy	G-09; README Experimental section	Document experimental-tier semver policy
AUDIT-M29	MEDIUM	Error taxonomy implicit — no central CodexError/AuthError/NetworkError base class confirmed	JN-05	Introduce structured error hierarchy; map failures to stable error codes
AUDIT-M30	MEDIUM	Duplicate 1455 port constant across auth, server, copy, html (cross-ref C-AUTH-04)	JN-08, C-AUTH-04	Derive from shared helper
AUDIT-M31	MEDIUM	6 tmp files at repo root (tmp-flagged.json.*.tmp, tmp-accounts.marker) — test-cleanup leakage	E-02, JN-09, LM-06; clean-repo-check.txt footer + test/account-clear.test.ts:13-45, test/flagged-storage-io.test.ts:29-53	Move tests to temp dirs via os.tmpdir(); use shared retry cleanup helper
AUDIT-M32	MEDIUM	CHANGELOG drift check incomplete — v1.2.5/6/7 vs git log v1.2.4..HEAD not cross-referenced	LM-07	Run CHANGELOG check per release; add CI gate
AUDIT-M33	MEDIUM	Semver over v1.2.4–v1.2.7 — no 2.x breaking changes; need to verify no silent breaking behaviors in minors	LM-10	Add behavioral-change flag in CHANGELOG entries
AUDIT-M34	MEDIUM	Non-streaming SSE conversion buffers full stream up to 10MB in memory before parse	P-03, H-03	Streaming decode OR bounded chunk count
AUDIT-M35	MEDIUM	Hot paths (request pipeline, SSE parser, account selection, storage writes, token refresh) lack benchmarks	P-02	Add micro-benchmarks for top-3 hot paths

---

7. Low-Priority Cleanups

ID	Severity	Claim	Evidence	Fix
AUDIT-L01	LOW	PKCE entropy is "probable strong" — generator lives in external dep, not audited in-repo	C-AUTH-01	Add regression test asserting S256 + document trust boundary
AUDIT-L02	LOW	Token endpoint + authorize endpoint hardcoded — no allowlist abstraction	C-AUTH-12	Centralize behind small allowlisted resolver for test/regional variants
AUDIT-L03	LOW	Auth storage corruption recovery works but silent — no operator-visible signal when WAL/backup path taken	C-AUTH-09	Emit audit log when recovery path used
AUDIT-L04	LOW	docs/reference/storage-paths.md references non-existent deriveProjectKey; code exports getProjectStorageKey	E-06; docs/reference/storage-paths.md:67-76, lib/storage/paths.ts:217-245	Update docs
AUDIT-L05	LOW	Recovery readers silently skip unreadable files (no corruption signal)	E-09; lib/recovery/storage.ts:67-114,273-384	Log corruption counts/paths
AUDIT-L06	LOW	docs/reference/settings.md precedence rule not formally verified	F-07	Add formal precedence table
AUDIT-L07	LOW	Fallback 429 path hardcodes "quota" reason in one branch; primary passes stableAccountKey	H-06; index.ts:2408-2412	Align fallback branch with primary
AUDIT-L08	LOW	Empty-response retry after SSE conversion may trigger unnecessary round-trip	H-10; index.ts:2169-2681	Add log; bounded count
AUDIT-L09	LOW	Test output contains stray PowerShell node.exe error lines on Windows — harness brittleness	K-09; test-summary.txt:16-22	Investigate stderr redirection
AUDIT-L10	LOW	Test import phase 40s dominates startup	K-08	Profile module graph for lazy-import opportunities
AUDIT-L11	LOW	No perf regression CI gate; bench results not baselined	P-06	Add perf CI with bench baseline commits
AUDIT-L12	LOW	Repeated regex compilation not fully verified; potential hot-path trap	P-05	Targeted new RegExp( scan
AUDIT-L13	LOW	Property/chaos catalogs not explicitly inventoried in this audit	K-06	Document invariants property-tested + failures chaos-injected
AUDIT-L14	LOW	Dead code scan incomplete (ts-prune not run)	JN-07	Run ts-prune pass; file findings

---

8. Refactoring Plan

R1. Split lib/codex-manager/settings-hub.ts (2100 LOC)

• Why: Single file mixing theme / accounts / sync / diagnostics / experimental. Future additions will make it worse. Cognitive load + merge-conflict surface.
• Files: lib/codex-manager/settings-hub.ts → new settings-hub/{theme,accounts,sync,diagnostics,experimental,index}.ts
• Target: Each sub-module <500 LOC; index.ts composes menu tree; each sub-module exports render() + action handlers
• Implementation order: 1) create sub-module files with empty exports, 2) extract theme first (smallest + well-isolated), 3) extract experimental, 4) extract diagnostics, 5) extract sync, 6) extract accounts, 7) convert root file to composition
• Migration risk: LOW — internal structure; public CLI surface unchanged. Test by bun test test/codex-manager-cli.test.ts at each step
• Payoff: Reviewable diffs; independent module tests; contributor ramp-up easier

R2. Introduce RedirectURI single source of truth

• Why: Current drift (localhost vs 127.0.0.1) causes confirmed login-break risk + 4+ duplicated port 1455 literals
• Files: lib/auth/auth.ts (REDIRECT_URI const), lib/auth/server.ts (bind), lib/ui/copy.ts, lib/oauth-success.html, docs/reference/commands.md, docs/getting-started.md, CHANGELOG.md
• Target: Single export const AUTH_REDIRECT = { host, port, path, origin, full } parsed once; all sites import
• Order: 1) define + export constant, 2) migrate server bind, 3) migrate auth flow, 4) migrate copy/html, 5) regen docs from constant, 6) add invariant test
• Migration risk: MEDIUM — user-facing OAuth redirect change if host standardizes on 127.0.0.1; existing Google OAuth apps may need re-registration
• Payoff: Kills drift class; fixes AUDIT-H5

R3. Consolidate JSON.parse behind Zod schemas

• Why: 59 parse calls across 31 files; single-file Zod hub exists but not applied at parse boundaries. Validation gap on untrusted payloads.
• Files: lib/schemas.ts (add schemas), all lib/** with JSON.parse call sites (highest: lib/request/request-init.ts, lib/runtime/request-init.ts, lib/storage.ts, lib/recovery/storage.ts, lib/request/fetch-helpers.ts)
• Target: Every JSON.parse → safeParse* helper returning { success, data | error }
• Order: 1) schemas for storage payloads (highest blast radius), 2) recovery, 3) request/response, 4) config, 5) ancillary
• Risk: LOW — additive change; fail-closed on parse error maps to clear operator signal
• Payoff: Hardens boundaries; improves runtime error messages; sets pattern for future parse sites

R4. Introduce routing mutex + selection-record pattern

• Why: Concurrent fetch + cursor mutation + debounced save can produce out-of-order persistence (AUDIT-H2 + D-09)
• Files: lib/accounts.ts (cursor + lastUsed mutation), lib/rotation.ts (selector)
• Target: selectAccount returns SelectionRecord = { account, selectionId, timestamp }; cursor advanced only after record accepted by fetch loop (or reverted on fast-fail); persistDebounced operates on ordered record queue
• Order: 1) add record type, 2) thread through fetch loop, 3) wrap cursor mutation in withMutex, 4) replay tests under concurrency
• Risk: MEDIUM — touches hot path; benchmark before merge
• Payoff: Fixes hybrid-selector bug (AUDIT-H2) and 429-race (AUDIT-H3) without amplifying throttling

R5. Unify lib/health.ts with live AccountManager state

• Why: Stale abstraction reports wrong fields (D-04)
• Files: lib/health.ts, lib/accounts.ts
• Target: getAccountHealth reads from tracker state directly OR module deleted and consumers redirected
• Order: 1) inventory consumers, 2) refactor to tracker-direct, 3) delete stale module if no consumers, 4) regression-test health snapshot shape
• Risk: LOW — internal; diagnostic output shape may shift (communicate in CHANGELOG)
• Payoff: Fixes operator-visible drift

R6. Harden recovery storage with atomic writes

• Why: E-03 confirmed violation; only recovery still uses direct sync writes
• Files: lib/recovery/storage.ts
• Target: Extract shared atomicWriteFile(path, data) helper used by lib/storage.ts + apply to recovery
• Order: 1) extract helper, 2) migrate recovery writes, 3) add retry-safe delete helper for Windows locks, 4) regression tests
• Risk: LOW
• Payoff: Recovery state survives mid-write crashes

---

9. Feature Recommendations

All features tied to concrete findings. Priorities: H = next cycle, M = subsequent, L = opportunistic.

F1. codex auth why-selected [--last|--now|--json] (Priority: H)

• Problem: AUDIT-M06 + D-04 — users can't understand why a given account was chosen; routing non-determinism + stale health model erode trust
• Fit: Complements existing status/report/forecast; same TUI/JSON pattern
• Complexity: S — read from existing tracker snapshot; add one CLI verb
• Deps: R5 (unified health)
• Risk: LOW — read-only

F2. codex auth verify --paths [--json] (Priority: H)

• Problem: AUDIT-H1 — resolvePath regression means users need a self-test for their import/export targets before using them
• Fit: Aligns with doctor --fix philosophy
• Complexity: S
• Deps: None
• Risk: LOW

F3. Per-account disable/quarantine with explicit state + TTL (Priority: H)

• Problem: AUDIT-H10 (dangling active pointer) + D-05 — no explicit quarantine/disable lifecycle; state transitions implicit
• Fit: Makes Section 8 R4 tangible at UX layer
• Complexity: M — add state: { value, enteredAt, ttl?, reason } to account record; migrate storage schema (bump V3 → V4 with migration); update selection/health
• Deps: R4, storage V4 migration
• Risk: MEDIUM — schema change; release-note required

F4. Structured incident-report bundle codex auth bundle [--out <path>] (Priority: M)

• Problem: H-05 (uneven observability) + J/N findings — post-failure reconstruction is hard; users need a redacted diagnostics tarball to share
• Fit: Extends report --json; produces filesystem bundle (logs + redacted state + env + timestamps)
• Complexity: M — needs redaction helper (reuse from this audit); tar/zip output
• Deps: Structured logger (R via JN-06)
• Risk: HIGH if redaction is weak — must apply JWT/email/path redaction before bundling

F5. Repair/migration dry-run preview codex auth fix --preview --json (Priority: M)

• Problem: AUDIT-M04 (account-clear ordering) — users can't preview safe fixes before applying
• Fit: Existing fix --dry-run has shape; extend with structured output
• Complexity: S
• Risk: LOW

F6. Shell completion for codex auth (Priority: M)

• Problem: G-08 — help discoverability unverified; rich subcommand surface
• Fit: Standard OSS CLI DX
• Complexity: S — generate bash/zsh/fish/powershell completions
• Risk: LOW

F7. Codex CLI compatibility probe codex auth compat [--json] (Priority: M)

• Problem: Implicit version coupling to upstream @openai/codex or native binary; no compatibility check
• Fit: Guards install/upgrade flow
• Complexity: S
• Risk: LOW

F8. Pool backup + restore with filename prompt (Priority: M)

• Note: Already in experimental tier per README — graduate to stable after adding collision safety test
• Problem: Experimental tier unstable; users want safe backup/restore
• Fit: Stabilize existing flow
• Complexity: S (test + docs)
• Risk: LOW

F9. Machine-readable status/forecast/report unification (Priority: M)

• Problem: AUDIT-M26 — --json coverage inconsistent
• Fit: Standardize schema version across status, check, list, forecast, report
• Complexity: M
• Risk: LOW

F10. Perf regression CI gate (Priority: L)

• Problem: P-06 — no baseline
• Fit: Extends existing CI
• Complexity: M (bench baseline commits + comparison job)

---

10. Security / Trust Review

Auth / Token Handling

• Positive: OAuth state 128-bit (C-AUTH-02); PKCE S256 (C-AUTH-01); file mode 0600 on token storage
• Concerns: Live OAuth URL leaks to stdout/clipboard (AUDIT-H4); redirect host drift localhost vs 127.0.0.1 (AUDIT-H5); JWT exp not validated on load (AUDIT-M12); access + refresh tokens both in plaintext JSON at rest (AUDIT-M13); token endpoint hardcoded single-host (AUDIT-L02)

Local State / Storage

• Positive: Atomic writes for primary storage + WAL/backup corruption recovery (C-AUTH-09)
• Concerns: resolvePath lookalike-prefix bypass (AUDIT-H1); recovery storage non-atomic (AUDIT-M01); in-process-only concurrency guard (AUDIT-M02); V2 migration missing (AUDIT-M03); project-scoped isolation collapses to global on CLI sync (AUDIT-M09)

Privacy / Logging

• Positive: docs/privacy.md exists; clean audit:ci
• Concerns: Structured logger present but fields inconsistent (AUDIT-M17); WAL/backup recovery silent (AUDIT-L03); recovery readers silently skip unreadable files (AUDIT-L05)

Trust Messaging vs Real Guarantees

• README claims reliability behaviors (whole-pool replay disabled by default, bounded outbound budget, burst cooldown) — verified in code
• Docs claim canonical redirect is 127.0.0.1:1455 — code uses localhost:1455 (DRIFT: AUDIT-H5)
• AGENTS.md claims "87 files, 2071 tests" — reality 225/3418 (DRIFT: AUDIT-H8)

Recommended Hardening Steps (priority order)

1. Fix resolvePath lookalike bypass + add regression tests for home/project/tmp lookalikes
2. Redact OAuth URL in user-facing output (AUDIT-H4)
3. Reconcile redirect host: pick 127.0.0.1 (better for OAuth pinning) + update all 4+ sites + tests + docs (AUDIT-H5)
4. Decode JWT exp on token load; treat missing expiry as refresh-needed (AUDIT-M12)
5. Consider OS keychain integration for token storage (AUDIT-M13)
6. Apply Zod at all JSON.parse boundaries (R3)
7. Add redaction helper as published module (also supports F4 incident bundle)

---

11. Testing Gap Analysis

Covered Well

• V3 storage format (fixtures in test/fixtures/v3-storage.json)
• Refresh-queue race dedupe (C-10)
• Chaos test directory + property-test directory exist — good stratification (K-06)
• Hermeticity works as designed when env redirected (K-05)

Under-Tested

• resolvePath lookalike rejection — currently BROKEN (K-02)
• Hybrid selector behavior when no accounts available (D-01) — no regression test
• Short-window 429 concurrent-request race (D-07) — no concurrent-request test
• loadPluginConfig CONFIG_PATH precedence (K-04) — test exists but is failing
• auth list empty-storage message (K-03) — test exists but drift
• V2 migration (E-05) — absent code path, absent tests
• SSE malformed-chunk handling (H-03) — silent discard, likely no explicit coverage
• Mid-stream failover recovery (H-04) — chaos test candidate
• CHANGELOG-to-git-log consistency per release (LM-07)
• Pack-budget regression (LM-01) — failing on HEAD

Exact Cases To Add (ordered by impact)

1. resolvePath lookalike prefix → throw on Windows + POSIX (fixes AUDIT-H1; unblocks coverage)
2. selectHybridAccount when all accounts blocked → returns null (fixes AUDIT-H2)
3. Concurrent requests on single rate-limited account → one marks, rest wait (fixes AUDIT-H3)
4. loadPluginConfig with both CONFIG_PATH + CODEX_HOME set → primary wins (fixes AUDIT-H6)
5. auth list empty storage → canonical message (fixes AUDIT-M25)
6. V2 storage payload → either migrates or rejects explicitly (fixes AUDIT-M03)
7. SSE malformed chunk → emits structured warn log (fixes AUDIT-H9)
8. Pack-size delta → CI gate (fixes AUDIT-H7)
9. Invariant: PKCE always S256 (preserves C-AUTH-01)
10. Invariant: OAuth state always 16-byte crypto random (preserves C-AUTH-02)

Best Order To Improve Confidence

1. Add security regressions first (cases 1-3) — highest blast radius
2. Fix existing failing tests (cases 4-5) — green baseline
3. Add taxonomy gaps (cases 6-7)
4. Add CI gates (case 8)
5. Lock in positives (cases 9-10)

---

12. CLI / DX / Docs Review

Command Ergonomics (Strong)

• README "Start here / Daily use / Repair / Advanced" taxonomy is excellent
• doctor --fix as canonical safe-recovery is a good trust pattern
• Dashboard hotkeys (Q=cancel) consistent per AGENTS.md

Command Ergonomics (Gaps)

• --json coverage uneven (AUDIT-M26)
• No shell completion (F6)
• No why-selected visibility (F1)
• No incident bundle (F4)
• Help discoverability unverified (G-08)

Install/Upgrade Flow

• npm i -g codex-multi-auth standard; legacy @ndycode/codex-multi-auth migration path documented — GOOD
• prepare → husky install side effect undocumented in CONTRIBUTING (AUDIT-M22)
• pack:check fails — tarball bloat (AUDIT-H7)

Docs Mismatches

• AGENTS.md stale across 4 axes (AUDIT-H8)
• Redirect host localhost vs 127.0.0.1 (AUDIT-H5)
• docs/reference/storage-paths.md references deriveProjectKey (does not exist); code uses getProjectStorageKey (AUDIT-L04)
• CHANGELOG-to-git-log cross-ref not verified (AUDIT-M32)

Contributor Ergonomics

• Governance files complete (SECURITY.md, CODE_OF_CONDUCT, CONTRIBUTING, LICENSE) — LM-08
• Runbooks present in docs/development/ (RUNBOOK_ADD_AUTH_COMMAND.md, etc.) — strong onboarding signal
• Strict TS + 0 escape hatches + lint — signals strong taste (I-01, I-02)
• Dual linter confusion (AUDIT-M21)

OSS Readiness: STRONG

• All governance stack present
• CodeQL + plugin scanner + CI + PR-CI workflows
• Clean supply chain audit
• Active security bump cadence
• README structural quality high

---

13. Quick Wins

Each is S-effort (hours, not days):

1. Fix AGENTS.md staleness (regen via /init-deep) — AUDIT-H8
2. Fix README/docs redirect host (localhost → 127.0.0.1) — AUDIT-H5
3. Fix docs/reference/storage-paths.md deriveProjectKey typo — AUDIT-L04
4. Delete/fix the 6 repo-root tmp files + patch leaking tests (test/account-clear.test.ts, test/flagged-storage-io.test.ts) — AUDIT-M31
5. Add EPERM to flagged-read retry codes — AUDIT-M05
6. Align account-clear marker-first ordering with flagged-clear flow — AUDIT-M04
7. Emit audit log when WAL/backup corruption recovery is used — AUDIT-L03
8. Log deprecation headers in error paths too — AUDIT-M18
9. Document prepare-hook husky side effect in CONTRIBUTING.md — AUDIT-M22
10. Document dual-linter scope (eslint=correctness, biome=format) in CONTRIBUTING.md — AUDIT-M21
11. Align fallback 429 path to pass stableAccountKey — AUDIT-L07
12. Add invariant test: PKCE always S256 — preserves C-AUTH-01
13. Add invariant test: OAuth state 16 crypto bytes — preserves C-AUTH-02
14. Add pack-size CI gate (runs pack:check, fails PR on regression) — AUDIT-H7 preventive
15. Add strict: true explicit documentation to CONTRIBUTING — I-05 lock-in
16. Document codex-cli vs codex-manager boundary in lib/AGENTS.md — AUDIT-M27
17. Add resolvePath regression tests (home/project/tmp lookalikes, Windows+POSIX) — AUDIT-H1 coverage
18. Redact OAuth URL in user-facing browser-launch output — AUDIT-H4
19. Move test tmp files to os.tmpdir() — AUDIT-M31
20. Document experimental-tier stability policy in README — AUDIT-M28

---

14. Phased Implementation Roadmap

Phase 1: Correctness & Safety (2–3 weeks)

Scope: All HIGH findings + security-relevant MEDIUM. Tasks:

• Fix AUDIT-H1 resolvePath + add regression tests
• Fix AUDIT-H2 hybrid selector contract + test
• Fix AUDIT-H3 short-429 race + concurrent-request test
• Fix AUDIT-H4 OAuth URL redaction
• Fix AUDIT-H5 redirect host (R2 refactor)
• Fix AUDIT-H6 CONFIG_PATH precedence
• Fix AUDIT-H7 pack:check + add CI gate
• Regen AGENTS.md (AUDIT-H8)
• Fix AUDIT-H9 SSE malformed-chunk logging
• Fix AUDIT-H10 active-pointer dangling
• Fix 3 failing tests (K-02, K-03, K-04) Deps: None (correctness fixes are independent) Benefits: Unblocks release; restores test-suite green baseline; fixes confirmed security regression Rollback: Each fix is small/atomic — per-commit revert

Phase 2: Architecture & Refactor (3–5 weeks)

Scope: R1-R6 refactors + error-taxonomy introduction. Tasks:

• R1 settings-hub split
• R2 redirect-URI SSOT (from Phase 1)
• R3 JSON.parse → Zod schemas at boundaries
• R4 routing mutex + selection-record
• R5 unify health with AccountManager
• R6 atomic writes for recovery
• AUDIT-M29 introduce CodexError/AuthError/NetworkError hierarchy
• AUDIT-M17 structured logger schema with required correlation fields Deps: Phase 1 green baseline Benefits: Long-term maintainability; reduced race surface; clean observability Rollback: R1 + R5 + R6 independent; R2 already Phase-1; R3 additive; R4 needs feature flag for safe rollback

Phase 3: Testing, Docs, DX (2–3 weeks)

Scope: Test gap closure + docs truth-up + DX features. Tasks:

• Testing cases 1-10 from Section 11
• --json standardization (AUDIT-M26)
• Shell completion (F6)
• Fix docs drifts (AUDIT-L04, AUDIT-M32)
• Document experimental-tier policy (AUDIT-M28)
• Document codex-cli vs codex-manager (AUDIT-M27)
• Add perf regression CI (AUDIT-L11) Deps: Phase 1 + Phase 2 Benefits: Contributor confidence; operator confidence; release safety Rollback: All additive

Phase 4: Strategic Features (4–6 weeks)

Scope: Feature recs F1-F9. Tasks:

• F1 why-selected (depends on R5)
• F2 verify --paths
• F3 per-account quarantine state (needs V3→V4 migration)
• F4 incident bundle (needs redaction helper + R3 logger)
• F5 fix --preview
• F7 Codex CLI compat probe
• F8 graduate backup/restore from experimental
• F9 unified machine-readable outputs Deps: Phase 2 (schemas, logger, routing mutex) Benefits: User experience, debuggability, trust Rollback: Each feature behind --experimental flag until stable

---

15. Top 20 Recommended Actions

Formula: score = severity_weight × probability × blast_radius. Weights: CRITICAL=5, HIGH=4, MEDIUM=2, LOW=1.

Rank	Action	Category	Reason	Difficulty	Impact
1	Fix resolvePath lookalike bypass + regression tests	Security/Correctness	HIGH-security path guard failure	M	HIGH
2	Fix hybrid selector to return null when no accounts available	Routing	Prevents unavailable-account retries	S	HIGH
3	Fix short-429 race (mark unavailable before sleep)	Routing	Amplified throttling under concurrency	S	HIGH
4	Redact OAuth URL in user-facing output	Security	CSRF/state leak to stdout/clipboard	S	HIGH
5	Reconcile redirect host (127.0.0.1 canonical) + SSOT refactor (R2)	Docs/Security	Confirmed drift breaks login; 4+ duplicate sites	M	HIGH
6	Fix loadPluginConfig CONFIG_PATH precedence	Config	Failing test; config bug	S	HIGH
7	Fix pack:check + add CI gate	Release	Tarball bloat; release blocker	S	HIGH
8	Regenerate AGENTS.md (docs truth-up)	Docs	4-axis drift erodes contributor trust	S	HIGH
9	Surface SSE malformed-chunk as structured warn	Reliability	Silent data loss	S	HIGH
10	Normalize active-account pointer on disable/remove	Routing	Dangling pointer UX/state confusion	S	HIGH
11	Split settings-hub.ts into sub-concerns (R1)	Architecture	2100 LOC overgrown file	L	MEDIUM
12	Zod schemas at all JSON.parse boundaries (R3)	Security/Types	59 raw parse sites	L	MEDIUM
13	Add connectTimeoutMs distinct from total/stall	Reliability	Diagnostic clarity + connect-vs-upstream disambiguation	S	MEDIUM
14	Structured logger schema with required correlation fields	Observability	Uneven logs across retry paths	M	MEDIUM
15	Atomic writes + retry-safe deletes for recovery storage (R6)	Reliability	Mid-write crash risk in recovery	S	MEDIUM
16	Move test tmp files to os.tmpdir() + shared cleanup helper	Tests	6 leaking tmp files at repo root	S	MEDIUM
17	Introduce CodexError/AuthError/NetworkError taxonomy	Errors	Ad-hoc error construction	M	MEDIUM
18	V2 migration path (match docs claim) or docs correction	Storage	V1↔V3 only; docs overstate	S	MEDIUM
19	Feature F1 codex auth why-selected + F2 verify --paths	Features	Operator visibility + path self-test	M	MEDIUM
20	Invariant tests for PKCE S256 + OAuth state 16-byte crypto	Tests	Lock-in positive findings	S	LOW-MEDIUM

---

16. Module-by-Module Notes

Module	Purpose	Strengths	Concerns	Verdict
index.ts	7-step fetch pipeline	4-gate loop termination (H-09); deprecation header logging (success path)	7 steps not documented inline (H-01); fallback 429 hardcodes reason (H-06); active-pointer normalization missing (D-05)	Harden — inline step comments + fix fallback paths
lib/auth/	OAuth + PKCE + callback	Strong OAuth state entropy (C-AUTH-02); refresh-guardian taxonomy (C-AUTH-13); auth storage corruption recovery (C-AUTH-09); refresh-queue race prevention (C-10)	Redirect host drift (C-AUTH-03); live URL leak (C-AUTH-05); port duplicated (C-AUTH-04); JWT exp unvalidated (C-AUTH-07); callback server not eager-close (C-AUTH-11); access+refresh tokens plaintext (C-AUTH-08)	Harden — R2 SSOT + secret minimization
lib/accounts.ts + lib/accounts/	Per-account rate-limit tracking + selection	Case-insensitive email dedup (AGENTS.md); health scoring implementation	Hybrid selector returns unavailable (D-01); non-deterministic routing (D-02); health + quota memory volatile (D-03); active pointer can dangle (D-05); project-scoped bypass on CLI sync (D-06); routing races (D-09)	Refactor — R4 mutex + selection record
lib/codex-cli/	CLI state, sync, observability, writer	Existence of observability layer	Unclear boundary vs lib/codex-manager/ (G-06)	Document or merge
lib/codex-manager/	Command dispatcher + settings-hub	Rich command surface; Q=cancel consistency	settings-hub.ts 2100 LOC (G-01); auth list message drift (G-02); --json coverage uneven (G-03); experimental tier undocumented (G-09)	Split — R1
lib/prompts/	Model-family prompts + GitHub ETag cache	ETag cache is performance-aware	Not deeply audited in this pass	Preserve
lib/recovery/	Conversation state persistence	Defensive against partial writes (via skip-unreadable)	Non-atomic writes (E-03); silent-skip no-log (E-09)	Harden — R6
lib/request/	Request transform, SSE, failover, backoff	4-gate termination; structured failure policy; burst cooldown	SSE non-streaming buffers 10MB + silent-skip malformed (H-03); observability uneven (H-05); stream failover bypasses server-error policy (D-08); no connect timeout (H-02)	Harden
lib/storage/	V1↔V3 migrations + worktree resolution	V3 format robust; WAL + backups; Windows removeWithRetry	resolvePath lookalike bypass (E-01/K-02) — HIGH; V2 absent (E-05); in-process-only locks (E-04); account-clear ordering (E-07)	Harden — priority on E-01
lib/tools/	Hashline tool helpers	Scoped, focused	Not deeply audited	Preserve
lib/ui/	ansi, auth-menu, theme, select, copy	Theme live-preview + baseline restore pattern (G-05)	Some text duplicates port 1455 literal (C-AUTH-04)	Preserve — fix R2 duplication
scripts/	install, build, hygiene, benchmarks	11+ scripts; Windows-safe removeWithRetry; verify-vendor-provenance.mjs; check-pack-budget.mjs; audit-dev-allowlist.js	pack:check FAILS on HEAD (LM-01)	Fix pack:check
test/	225 files, 3418 tests, 80% coverage	Chaos + property + fixtures; hermetic via env redirection (K-05)	3 failing tests on HEAD (K-02/K-03/K-04); repo-root tmp leakage (K-09/JN-09); coverage % unverified (K-07)	Harden — fix failures + leakage
docs/	14+ markdown docs + sub-directories	Strong README taxonomy; full governance; runbooks	Redirect host drift (AUDIT-H5); deriveProjectKey typo (E-06); AGENTS.md stale (AUDIT-H8); CHANGELOG drift unverified (LM-07)	Truth-up
.github/workflows/	ci, pr-ci, codex-plugin-scanner, codeql	Full OSS CI stack; CodeQL + plugin scanner + dep scanner	No perf CI gate (P-06); no pack-size gate (LM-01 preventive)	Extend
bench/format-benchmark/	Code-edit format benchmark	Focused, documented	Hot paths (request, SSE, selection, storage) lack bench (P-02)	Extend
vendor/codex-ai-plugin, vendor/codex-ai-sdk	File-protocol vendored deps	vendor:verify provenance script; bundleDependencies	Black-box inside audit scope	Preserve provenance discipline

---

17. Final Verdict

Is the codebase structurally healthy?

Yes — it is structurally healthy with known, addressable gaps. This is a serious, well-crafted CLI tool with strong TypeScript discipline (0 as any, 0 @ts-ignore), hermetic test design, active security maintenance, full OSS governance, and a clean supply chain. The architecture boundaries (auth / accounts / request / storage / codex-manager) are sensible; the 7-step request pipeline has safety gates; OAuth uses PKCE with 128-bit CSRF entropy.

The current HEAD (v1.2.7) has 10 HIGH-severity findings across correctness/security/docs that should be addressed before the next minor release. None reach CRITICAL severity with confirmed evidence in this pass, but AUDIT-H1 (resolvePath lookalike bypass) is CRITICAL-candidate pending real-host reproduction.

What is the biggest long-term bottleneck?

The settings-hub monolith (2100 LOC) and the implicit state machines in lib/accounts.ts + lib/rotation.ts. Together they concentrate change risk in single files and blur ownership. Left unsplit, every new feature touches them, regression surface grows, and subtle races (AUDIT-H2/H3/M07) will keep resurfacing.

The secondary bottleneck is absence of a structured error taxonomy + uniform logger schema — makes post-incident reconstruction hard and slows debugging.

What should be implemented first?

Phase 1 Correctness & Safety — fix the 10 HIGH findings and restore a green test baseline. Specifically:

1. resolvePath lookalike + selectHybridAccount + short-429 race + OAuth URL redaction + loadPluginConfig precedence + pack:check — in parallel tracks
2. codex auth list empty-storage message + resolvePath test + plugin-config precedence test — restores green baseline
3. AGENTS.md regen + localhost → 127.0.0.1 docs truth-up

What must NOT be broken during refactoring?

Preserve (cross-referenced to Section 3):

1. Hermetic test design — HOME + CODEX_MULTI_AUTH_DIR env-redirect pattern; verified zero drift
2. Strict TypeScript doctrine — 0 as any, 0 @ts-ignore, strict: true
3. Refresh-queue race prevention — token-keyed dedupe + rotation + rollback on persist fail
4. 4-gate request-loop termination — attempted.size, outbound budget, MAX_SHORT_RETRY_ATTEMPTS=3, MAX_STREAM_FAILOVERS=1
5. Atomic writes for primary + flagged + settings — extend, don't regress
6. Clean supply chain — audit:ci green, vendor:verify green
7. OSS governance — SECURITY/COC/CONTRIBUTING/LICENSE + CodeQL + scanners
8. CLI command taxonomy — Start/Daily/Repair/Advanced organization in README

---

Appendix: Evidence Index

Under docs/audits/evidence/:

File	Source	Purpose
context.txt	T0b	HEAD SHA, version, node, OS, CI workflows
inventory.txt	T1	LOC/file inventory per module
typecheck.txt	T2	npm run typecheck output (exit 0)
test-summary.txt	T3	Vitest summary (225 files/3418 tests/3 fail) + hermeticity verdict
lint.txt	T4	npm run lint (exit 0)
audit-ci.txt	T4	npm run audit:ci (exit 0)
vendor-verify.txt	T4	npm run vendor:verify (exit 0)
pack-check.txt	T4	npm run pack:check (exit 1) — budget violation
clean-repo-check.txt	T4	Hygiene check + 6 tmp files flagged
git-forensics.txt	T5	Churn, blame, regression commits
docs-claims.txt	T6	Docs claim inventory for drift cross-ref
redaction-report.txt	T7	Redaction validation grid (PASS)
dim-C-auth.md	T8	Auth/OAuth/Token dimension (13 findings)
dim-D-routing.md	T9	Multi-account routing dimension (9 findings)
dim-E-storage.md	T10	Storage dimension (9 findings)
dim-F-config.md	T11 Atlas	Config/settings/dual-linter (7 findings)
dim-G-cli.md	T13 Atlas	CLI/settings-hub (9 findings)
dim-H-request.md	T12 Atlas salvage	Request pipeline/SSE/resilience (10 findings)
dim-I-types.md	T14	Type safety sweep (6 findings)
dim-JN-errors-health.md	T15 Atlas	Error handling + code health (10 findings)
dim-K-tests.md	T16 Atlas	Test strategy + hermeticity (10 findings)
dim-LM-release-docs.md	T17 Atlas	Release/CI + docs drift (12 findings)
dim-P-perf.md	T17b Atlas	Perf lightweight (6 findings)

Total distinct findings: ~110 across 16 dimensions.

---

End of MASTER_AUDIT.md — composed under Sisyphus/Atlas workflow. See Section 3 for strengths to preserve. See Section 14 for the 4-phase roadmap.