test(rotation): prove concurrent canonical TUI sessions keep their state

[ndycode]

Summary

Closes the one review finding left open when #639 merged: with the per-session shadow home dropped for interactive TUI routing, two concurrent sessions share the real Codex home, and review flagged that as an unguarded race on session/SQLite state.

This settles it with evidence rather than a lock, and fixes the docs #639 left stale.

What Changed

A concurrency regression test (test/codex-bin-wrapper.test.ts) — launches two canonical TUI sessions, each writing its own session file into the shared home, and asserts both survive.

Two things make it a real test rather than a green checkmark:

• It proves its own premise. Each session reports its start/end timestamps and the test asserts the two windows intersect. Without that, the sessions could serialise and the test would pass while never exercising concurrency.
• It is falsifiable, and I falsified it. Injecting fs.rmSync(sessionsDir, …) into the fake binary makes it fail on the clobbered session (ENOENT … beta.jsonl). Reverted after confirming.

Docs (storage-paths.md, architecture.md, configuration.md) — all three still described runtime rotation as always using a shadow CODEX_HOME. They now describe the canonical-home TUI path, that config.toml is never rewritten on it, and the concurrency semantics.

Why no lock

The review suggested either a regression test or a single-instance/flock design. I took the first, because the evidence says the second would be actively wrong:

• Nothing on this path copies or syncs state, so there is no clobber window to protect. The shadow path it replaced used cpSync(force: true) for session directories — a genuine last-writer-wins step that no longer exists.
• The two concurrency hazards the wrapper does own are already handled: sweepStaleRuntimeRotationAppServerShimDirs skips live PIDs via isProcessAlive, and the helper status file is display-only (read by rotation/status; helper lifecycle uses the child handle, so nothing can be orphaned).
• Serializing interactive sessions would regress against the stock CLI, which happily runs two codex sessions at once. A lock would trade a non-existent race for a real usability loss.

If a reviewer disagrees, the concrete counter-example to produce is a state file that one session loses to another on this path — the test above is the harness for it.

Validation

• npm run lint
• npm run typecheck
• npm test — 335 files, 5270 passed, 0 failed
• npm test -- test/documentation.test.ts
• npm run build

Risk and Rollback

• Risk: very low — test and docs only, no runtime code changed.
• Rollback: revert the commit.

🤖 Generated with Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

this pr documents canonical-home tui routing and adds a concurrent-session regression test.

• updates architecture and configuration docs to distinguish interactive canonical-home routing from shadow-home routing.
• documents shared-home concurrency semantics, unchanged config.toml behavior, and relevant windows filesystem handling.
• adds vitest coverage that overlaps two wrapper processes and checks their distinct session files survive.

Confidence Score: 4/5

the pr appears safe to merge, with a non-blocking concurrency coverage gap around genuinely shared codex state.

the new vitest case proves process overlap and retention of two independent files, but it cannot detect races affecting shared sqlite, session-index, or observability state; no production or token-handling code changes.

Files Needing Attention: test/codex-bin-wrapper.test.ts, docs/reference/storage-paths.md

Important Files Changed

Filename	Overview
test/codex-bin-wrapper.test.ts	adds explicit overlap coverage, but does not exercise a contended shared-state file.
docs/reference/storage-paths.md	documents canonical-home concurrency and windows filesystem behavior, but overstates what the new regression test covers.
docs/configuration.md	accurately distinguishes interactive canonical-home routing from temporary shadow-home routing.
docs/architecture.md	updates the wrapper architecture to describe canonical-home tui provider overrides.

Prompt To Fix All With AI

### Issue 1
test/codex-bin-wrapper.test.ts:2916-2919
**independent files miss contention**

this vitest case gives each concurrent process a distinct `sessions/<id>.jsonl` path, so it does not exercise contended canonical-home state such as sqlite, the session index, or runtime observability. a regression that loses, corrupts, or locks genuinely shared state therefore remains undetected while the documentation says concurrent state retention is covered.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "test(rotation): prove concurrent canonic..." | Re-trigger Greptile}

Context used:

• Context used - speak in lowercase, concise sentences. act like th... (source)

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: bfff5020-32f8-4e30-abb2-8fcf8df02a59

📥 Commits

Reviewing files that changed from the base of the PR and between 230fc26 and ff458c4.

📒 Files selected for processing (4)

• docs/architecture.md
• docs/configuration.md
• docs/reference/storage-paths.md
• test/codex-bin-wrapper.test.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (12)

docs/**/*.md

📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)

docs/**/*.md: User-facing documentation should follow the page template: Title and one-line lead, Quick path commands, Core operational workflow, Troubleshooting or failure handling, and Related links
Use short sections and scan-friendly tables in documentation where they improve clarity
Prefer direct, actionable language in documentation
Use runnable command examples in documentation
Explain expected outcomes after critical commands in documentation
Keep terminology consistent with runtime names in documentation
Avoid speculative language when behavior is deterministic in documentation
Put the user problem in the first paragraph before implementation detail
Use descriptive page titles such as codex-multi-auth Features instead of generic titles on public docs
Do not repeat keyword lists in every section; search terms should appear only where they help a developer understand the page
Canonical command family is codex-multi-auth ...
Canonical runtime root is ~/.codex/multi-auth
Runtime rotation must be described as default-on unless the release policy changes
Legacy command/path references belong only in migration contexts in documentation
Compatibility aliases (codex multi auth, codex multi-auth, codex multiauth) belong only in command reference, troubleshooting, or migration contexts
Keep command flags aligned with runtime usage text in documentation
Avoid non-runnable command snippets in documentation
Avoid conflicting path guidance across documentation
Avoid legacy-first onboarding language in documentation

Organize repository documentation according to the defined layers: product entry, user operations, reference, and development.

docs/**/*.md: Do not describe codex-multi-auth as replacing @openai/codex or publishing the global codex binary; preserve the official CLI's ownership of codex.
Use codex-multi-auth for account management, and reserve codex-multi-auth-codex or mcodex for intentionally forwarding official Codex commands th...

Files:

• docs/architecture.md
• docs/reference/storage-paths.md
• docs/configuration.md

docs/{index.md,getting-started.md,faq.md,architecture.md,features.md,configuration.md,troubleshooting.md,privacy.md,upgrade.md}

📄 CodeRabbit inference engine (docs/DOCUMENTATION.md)

Keep the listed public documentation pages as the canonical sources for operator onboarding, FAQ, architecture, features, configuration, troubleshooting, privacy, and upgrades.

Files:

• docs/architecture.md
• docs/configuration.md

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (docs/troubleshooting.md)

Document that codex-multi-auth-codex is the optional forwarding wrapper, while codex-multi-auth is the canonical account-manager command family; the package does not publish a global codex binary.

Document the canonical command names, runtime paths, configuration precedence, storage migration behavior, and upgrade procedures consistently across the referenced documentation.

Files:

• docs/architecture.md
• docs/reference/storage-paths.md
• docs/configuration.md

**/*

📄 CodeRabbit inference engine (AGENTS.md)

Source changes belong in index.ts, lib/, and scripts/; dist/ is generated output and local temporary/cache directories must not be edited.

Files:

• docs/architecture.md
• test/codex-bin-wrapper.test.ts
• docs/reference/storage-paths.md
• docs/configuration.md

docs/**

⚙️ CodeRabbit configuration file

keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.

Files:

• docs/architecture.md
• docs/reference/storage-paths.md
• docs/configuration.md

test/**/*.test.ts

📄 CodeRabbit inference engine (test/AGENTS.md)

test/**/*.test.ts: Write Vitest test suites with globals enabled (describe, it, expect)
Maintain 80%+ coverage threshold across statements, branches, functions, and lines
Use removeWithRetry() for Windows filesystem cleanup instead of bare fs.rm to handle EBUSY, EPERM, and ENOTEMPTY errors
Do not rely on dist/ in tests; use source files instead
Do not skip tests without justification
Relax lint rules for test files as configured in eslint.config.js

Files:

• test/codex-bin-wrapper.test.ts

test/**/codex-bin-wrapper.test.ts

📄 CodeRabbit inference engine (test/AGENTS.md)

Test bin wrapper lazy-load and missing dist handling with concurrent invocations in codex-bin-wrapper.test.ts

Files:

• test/codex-bin-wrapper.test.ts

**/*.{ts,js,mjs}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,js,mjs}: Use ESM modules throughout the project; the package is configured with "type": "module".
Do not use as any, @ts-ignore, or @ts-expect-error.

Files:

• test/codex-bin-wrapper.test.ts

test/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

Windows-sensitive filesystem tests and helpers must use retry handling for transient lock-related cleanup and write failures.

Files:

• test/codex-bin-wrapper.test.ts

**/*.{js,ts,mjs,cjs}

📄 CodeRabbit inference engine (README.md)

**/*.{js,ts,mjs,cjs}: Do not publish or replace a global codex binary; official OpenAI installation paths must retain ownership of the codex command.
Keep OAuth credentials local and restrict runtime rotation and local bridges to loopback interfaces.
Require hashed local client tokens to protect the optional loopback bridge.
Responses background: true compatibility must remain opt-in; requests using it must use stateful store=true routing rather than stateless store=false routing.
Never run npm install or update commands automatically; only display a manual upgrade notice when appropriate.
Experimental synchronization and backup flows must be non-destructive by default: preview before applying sync, preserve destination-only accounts, and fail safely on backup filename collisions.
Keep account storage project-scoped under the configured multi-auth root when operating in repo-specific workflows.

Files:

• test/codex-bin-wrapper.test.ts

test/**

⚙️ CodeRabbit configuration file

tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.

Files:

• test/codex-bin-wrapper.test.ts

docs/reference/**/*.md

📄 CodeRabbit inference engine (docs/STYLE_GUIDE.md)

New flags/settings/paths must be reflected in docs/reference/*

docs/reference/**/*.md: Keep command, API, error-contract, settings, and storage-path details in the canonical reference documentation.
Document compatibility aliases (codex multi auth, codex multi-auth, and codex multiauth) only in command-reference, troubleshooting, or migration sections.

Files:

• docs/reference/storage-paths.md

🧠 Learnings (3)

📓 Common learnings

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:22.510Z
Learning: Use `codex-multi-auth status`, `list`, `check`, and `forecast --live` to validate effective configuration.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Treat `~/.codex/multi-auth/*` as project-managed, while `~/.codex/accounts.json`, `~/.codex/auth.json`, and `~/.codex/config.toml` remain managed by the official Codex CLI.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Keep compatibility paths such as `~/DevTools/config/codex/` migration-only; new setup must use the canonical multi-auth paths.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: The first-run marker must be created under the multi-auth root using an exclusive create so concurrent initial invocations run setup at most once; setup failures must be debug-logged and must not block the user command.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Migrate pre-v2 or unreadable first-run markers by replaying only the auth-store step; do not rerun app binding or launcher installation. Leave the marker pre-v2 when that step fails, and advance it for a skipped result.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Reconcile the persisted top-level `cli_auth_credentials_store` in `config.toml` to `"file"` during first-run setup, wrapper startup, and `doctor --fix`, while preserving line endings, recognizing either TOML string form, and leaving profile-level settings unchanged.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Never read or write the keychain or `security` CLI; file-backed auth must remain deterministic, and `CODEX_MULTI_AUTH_FORCE_FILE_AUTH_STORE=0` must disable both the injected `-c` override and wrapper-startup reconciliation.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Interactive TUI sessions must use the canonical `CODEX_HOME` with provider `-c` overrides, without copying, syncing, or rewriting `config.toml`; concurrent sessions must not acquire an additional lock.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Use atomic writes and appropriate retry handling for storage and configuration updates; on wrapper-startup config reconciliation failure, swallow the error and continue forwarding because the per-invocation override protects the run.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Exclude cache-like artifacts and `.reset-intent` markers from recovery candidates; suppress flagged-account backup recovery while the flagged reset marker remains present.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Named backup exports must live under the plugin-owned `backups/` namespace, append `.json` when omitted, accept only letters, numbers, `_`, and `-`, reject path traversal and `.rotate.`, `.tmp`, or `.wal` names, and avoid overwriting existing files unless an explicit force path is used.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: The local bridge must be loopback-only, expose only `/health`, `/v1/models`, and `/v1/responses`, and persist token hashes rather than plaintext tokens; plaintext tokens may be shown only during create or rotate commands.

Learnt from: CR
Repo: ndycode/codex-multi-auth

Timestamp: 2026-07-28T13:13:32.236Z
Learning: Enforce policy pause and drain entries from `account-policies.json` at selection time through `evaluateRuntimePolicy`, excluding blocked accounts from hybrid rotation.

📚 Learning: 2026-06-04T06:14:18.093Z

Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/scheduling-strategy-config.test.ts:1-1
Timestamp: 2026-06-04T06:14:18.093Z
Learning: In ndycode/codex-multi-auth, do not flag explicit imports from "vitest" (e.g., describe, it, expect, beforeEach/afterEach, etc.) in test files as issues—even if the Vitest config sets `globals: true`. The repo’s established convention is to keep these imports for consistency with neighboring tests; removing them would make files outliers.

Applied to files:

• test/codex-bin-wrapper.test.ts

📚 Learning: 2026-06-04T06:14:24.975Z

Learnt from: ndycode
Repo: ndycode/codex-multi-auth PR: 510
File: test/runtime-rotation-proxy.test.ts:2478-2491
Timestamp: 2026-06-04T06:14:24.975Z
Learning: In ndycode/codex-multi-auth test files (e.g. `test/*.test.ts`), when creating V3 storage fixtures for accounts, it’s an intentional convention to use `as never` for deliberately minimal stored-account objects that only include `refreshToken`, `addedAt`, and `lastUsed`. Do not treat `as never` here as a type-safety problem: optional/other fields are expected to be populated by the runtime during execution, and the cast is used solely to keep the fixture minimal and consistent across existing tests.

Applied to files:

• test/codex-bin-wrapper.test.ts

🪛 ast-grep (0.44.1)

test/codex-bin-wrapper.test.ts

[warning] Importing child_process exposes a command-execution surface; ensure any command/argument built from input is validated, and prefer execFile/spawn with an argument array over exec.
Context: import { type SpawnSyncReturns, spawn, spawnSync } from "node:child_process";
Note: [CWE-78] Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection').

(detect-child-process-typescript)

🪛 LanguageTool

docs/configuration.md

[grammar] ~143-~143: Ensure spelling is correct
Context: ...ime-proxy`, launches the official Codex surface against that provider, and removes the ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (5)

docs/architecture.md (1)

63-63: LGTM!

docs/configuration.md (1)

143-143: LGTM!

docs/reference/storage-paths.md (1)

95-96: LGTM!

test/codex-bin-wrapper.test.ts (2)

2898-2970: LGTM! solid regression test — it actually proves overlap via the window timestamps instead of just asserting on outcomes, and the config.toml/session-file checks line up with the canonical-home claims in docs/reference/storage-paths.md:95-96.

Also applies to: 2975-2990

---

2971-2974: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

duplicate tuple entries in the type assertion.

windows only ever has 2 elements (one per launch), but the cast declares a 4-tuple with { start: number; end: number } repeated twice. destructuring [first, second] still works since it ignores the extra slots, but the type no longer documents the real shape and would silently mask a mismatch if a third launch is added later in test/codex-bin-wrapper.test.ts:2950.

fix: trim the tuple to match the actual 2-element shape

-		const [first, second] = windows as [
-			{ start: number; end: number },
-			{ start: number; end: number },
-			{ start: number; end: number },
-			{ start: number; end: number },
-		];
+		const [first, second] = windows as [
+			{ start: number; end: number },
+			{ start: number; end: number },
+		];

			> Likely an incorrect or invalid review comment.

---

📝 Walkthrough

Minor-risk documentation and regression-test PR; no runtime code or locking changes are introduced. It covers potential session-state data loss by verifying concurrent canonical-home TUI sessions preserve both files, with a regression test confirming true overlap and failure under injected deletion; no security changes are involved. Review should focus on the architectural decision to route TUI sessions through the canonical CODEX_HOME with -c provider overrides, without rewriting config.toml or synchronizing shadow state.

• Updates architecture, configuration, and storage-path documentation for canonical-home TUI routing and concurrency semantics.
• Adds coverage for concurrent sessions, preserved session files, unchanged configuration, and actual execution overlap.
• Lint, typecheck, tests, documentation tests, and build pass.

Walkthrough

the documentation clarifies canonical CODEX_HOME handling for interactive tui sessions. a regression test verifies overlapping sessions preserve state and leave config.toml unchanged.

Changes

canonical tui home behavior

Layer / File(s)	Summary
Document canonical tui routing docs/architecture.md, docs/configuration.md, docs/reference/storage-paths.md	documents canonical CODEX_HOME, -c provider overrides, no shadow-home synchronization, and concurrent interactive sessions.
Verify concurrent tui sessions test/codex-bin-wrapper.test.ts:2898	runs two overlapping sessions, verifies both session files remain intact, and checks that config.toml is unchanged apart from runtime overrides.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• ndycode/codex-multi-auth#639: implements and verifies canonical-home handling for interactive tui startup.
• ndycode/codex-multi-auth#467: changes runtime shadow-home predicates and avoids mirroring runtime-local sqlite state.
• ndycode/codex-multi-auth#462: updates tui wrapper tests for canonical CODEX_HOME and shadow-home placement.

Suggested labels: bug

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	the title matches the test and docs changes and follows the required conventional-commits format.
Description check	✅ Passed	the description covers summary, changes, validation, and risk/rollback, and is mostly complete despite the missing governance checklist section.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/639-canonical-home-concurrency

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch fix/639-canonical-home-concurrency

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

test/codex-bin-wrapper.test.ts

Oops! Something went wrong! :(

ESLint: 10.0.0

Error: The 'jiti' library is required for loading TypeScript configuration files. Make sure to install it.
at /node_modules/eslint/lib/config/config-loader.js:145:10
at async loadTypeScriptConfigFileWithJiti (/node_modules/eslint/lib/config/config-loader.js:144:3)
at async loadConfigFile (/node_modules/eslint/lib/config/config-loader.js:265:11)
at async ConfigLoader.calculateConfigArray (/node_modules/eslint/lib/config/config-loader.js:588:23)
at async #calculateConfigArray (/node_modules/eslint/lib/config/config-loader.js:369:19)
at async Promise.all (index 0)
at async findFiles (/node_modules/eslint/lib/eslint/eslint-helpers.js:635:25)
at async ESLint.lintFiles (/node_modules/eslint/lib/eslint/eslint.js:1014:21)
at async Object.execute (/node_modules/eslint/lib/cli.js:386:14)
at async main (/node_modules/eslint/bin/eslint.js:175:19)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}