docs(future) + feat: 18k-line improvement protocol + P0 wave implementation

[NagyVikt]

Summary

Adds 19 source-grounded improvement documents under docs/future/ (~18,016 lines total) covering every section of the project. The user asked for ~12,000 lines; the final set came in larger because each section's brief required substantive depth (per-method line citations, full TypeScript interface sketches, per-OS install matrices, conformance kits, etc.). No source files are modified.

What's inside

#	File	Lines	Scope
00	OVERVIEW	319	Protocol scope, conventions, reading order
01	ARCHITECTURE	1138	Layering, god-file split, domain model, errors, plugin story
02	CORE-LIBRARY-IMPROVEMENTS	1144	src/lib/*.ts (excl. accounts/config subdirs)
03	COMMANDS-IMPROVEMENTS	1634	Every src/commands/*.ts
04	ACCOUNTS-MODULE	1882	src/lib/accounts/ deep dive incl. account-service.ts decomposition
05	CONFIG-AND-PATHS	874	XDG layout, typed config schema, shim/hook redesign
06	AUTO-SWITCH-AND-DAEMON	1361	Policy engine, runtime, OS service hardening
07	USAGE-REFRESH-AND-API	1165	Quota model, HTTP client, forecaster, provider adapters
08	HOOKS-AND-SHELL-INTEGRATION	1078	PATH-shim, fish/nushell/pwsh, session-key resolver
09	MULTI-CLI-SUPPORT	1008	ProviderAdapter interface, built-in + future adapters
10	SECURITY-AND-SECRETS	985	Threat model, perms, keychain, supply chain
11	TESTING-STRATEGY	1139	Pyramid, fakes, CI matrix, property/mutation/fuzz
12	RELEASE-AND-DISTRIBUTION	670	Versioning, OIDC publish, brew/scoop/nix/docker
13	OBSERVABILITY-AND-LOGGING	711	Structured logger, diag, support-bundle, telemetry
14	CROSS-PLATFORM	818	Linux/macOS/Windows/WSL parity matrix
15	PERFORMANCE-AND-SCALABILITY	493	Budgets, hotspots, registry scaling ceilings
16	DOCUMENTATION-AND-DX	389	Docs site, contributor experience, error message guide
17	ROADMAP	564	Now / Next / Later / Maybe horizons, success metrics
18	GLOSSARY-AND-APPENDICES	644	Glossary + 7 appendices

Total: 18,016 lines.

Notable real findings surfaced by the audit

Several proposals are anchored to genuine bugs/risks discovered during the source read — these may be worth triaging independently:

• P0 (security): registry.json, snapshots, and accounts dir written without explicit mode → world-readable refresh tokens on default umask. src/lib/accounts/account-service.ts:986-998, src/lib/accounts/registry.ts:148-152.
• P0 (security): child_process.exec of user-controlled CODEX_LB_DASHBOARD_TOTP_COMMAND env var. src/lib/accounts/usage.ts:365-373.
• P0 (correctness): registry.ts:26 drops "proxy" usage source during sanitization; saved snapshots with source: "proxy" round-trip as "cached".
• P0 (UX): Bare authmux invocation auto-installs updates with [Y/n] defaulting to yes — effectively opt-out auto-update. src/hooks/init/update-notifier.ts:38-55.
• P0 (durability): No file lock on ~/.codex/auth.json or registry.json; race between manual use and daemon switch. Non-atomic registry write (no temp+rename) → silent reset to defaults on crash mid-write.
• P0 (CI): Only workflow is an LLM code-review bot; no CI runs npm test.
• Bug: src/commands/kiro.ts:81 fs.existsSync(...) || fs.lstatSync(...).isSymbolicLink() throws ENOENT when the file doesn't exist.
• Bug: src/commands/login.ts:41-44 disables auto-switch but never restores it on failure.
• 10 commands extend Command directly, bypassing BaseCommand.handleError and external-auth sync.
• Two divergent ChatGPT /wham/usage parsers (object rate_limit vs array rate_limits) — one likely stale.
• src/lib/hermes-mirror.ts:6 hardcodes ~/Documents/hermes-agent (developer-machine assumption).
• macOS LaunchAgent label is com.codex.auth.autoswitch (service-manager.ts:9) — pre-rename artifact needs deprecation cycle.
• src/tests/test_kiro_account_switcher.py (Python) is silently skipped by node --test.

Every proposal follows the Evidence → Diagnosis → Proposal → Migration → Rollout pattern and carries P0/P1/P2/P3 + S/M/L/XL tags so the work can be triaged into a real backlog.

Test plan

• Skim 00-OVERVIEW.md and confirm reading order matches expectations
• Spot-check 5–10 line-number citations against current src/
• Triage the P0 findings list above into separate issues for follow-up
• Decide which sections should be lifted into the published docs site (see 16-DOCUMENTATION-AND-DX.md)

---

Generated by Claude Code

[NagyVikt]

P0 wave implementation (commit 982bc43)

Implemented the highest-priority concrete findings from the protocol. Larger refactors stay deferred to separate PRs.

Security & correctness

• src/lib/io/secure-fs.ts (new) — atomic temp+rename writes with 0600 file mode and 0700 dir mode. No-op chmod on Windows.
• registry.saveRegistry — now atomic + secure perms.
• account-service.ts — chmod 0600 on every snapshot copy/write and 0700 on accounts dir; secureWriteFile for current-name, session-map, and materialized auth file.
• registry.sanitizeUsageSnapshot — "proxy" was missing from the source allowlist even though UsageSource declared it, so saved snapshots silently round-tripped as "cached". Fixed.

UX

• Init-hook update prompt flipped from [Y/n] default-yes to [y/N] default-no. New shouldProceedWithNoDefault helper.
• login command — restores auto-switch state on failure instead of leaving it disabled.

Bugs

• kiro switch — fs.existsSync(DATA_FILE) || lstatSync(DATA_FILE) threw ENOENT when the path was fully absent; replaced with a single unlink + ENOENT-tolerant block.

CI

• .github/workflows/ci.yml (new) — matrix Ubuntu/macOS/Windows × Node 18/20/22 running npm run build + npm test, plus an Ubuntu/macOS smoke job that npm-installs the packed tarball and runs authmux --help. Postinstall is suppressed in CI.

Tests

• 8 new tests (77 → 85 passing): secure-fs perms + atomicity, shouldProceedWithNoDefault matrix, registry proxy-source round-trip, full UsageSource enum coverage.

Deliberately deferred to follow-up PRs

• god-file split of account-service.ts (1663 LOC) into 7 modules — docs/future/04
• file locking + single-writer daemon — docs/future/06
• ProviderAdapter plugin SDK — docs/future/09
• XDG layout migration — docs/future/05
• structured logger + diag + support-bundle — docs/future/13
• daemon IPC + hysteresis policy engine — docs/future/06
• usage.ts decomposition + circuit breaker — docs/future/07
• PATH-shim replacement for the shell-function wrap — docs/future/08

Explicitly not implemented

• TOTP exec → execFile change (usage.ts:367). On reflection the env var CODEX_LB_DASHBOARD_TOTP_COMMAND is intentionally a shell command (users plug in things like oathtool ... | head -1 or op item get ...), so shell exec is the contract. The protocol doc's P0 tag was overstated; downgrading to P2 with a docs note recommended instead.

---

Generated by Claude Code