# Shared Non-Credential Codex State Design

Audience: AI coding agents first.

## Goal

Share all Codex configuration and runtime state across `cdx` account profiles. Keep only credentials account-specific.

## State Contract

- Treat `~/.codex` as canonical shared home.
- Keep `auth.json` and every top-level name beginning with `auth.` account-local.
- Link every other non-SQLite top-level entry from each account `CODEX_HOME` to canonical shared home.
- Discover entries dynamically from canonical and account homes. NEVER use a sharing whitelist.
- Route SQLite-backed threads, memories, goals, and logs through `CODEX_SQLITE_HOME=~/.codex`.
- Leave old account-local SQLite files untouched while older Codex processes may hold them open. New `cdx` processes MUST ignore them through `CODEX_SQLITE_HOME`.

## Migration Contract

`AccountRegistry.sync_all_shared_links() -> None`

- Apply only to Codex registries.
- Discover account homes from directories under `accounts/`; registry JSON MUST NOT be required.
- Merge directories recursively.
- Merge `history.jsonl` and `session_index.jsonl` as deduplicated chronological JSONL.
- Append differing `.log` files so historical diagnostics remain available.
- Prefer canonical files for conflicts inside generated `.tmp`, `tmp`, and `cache` trees.
- Remove equal duplicate files.
- Raise on different-content conflicts for other files. NEVER overwrite or discard unknown state.
- Repair links and remain idempotent.
- Preserve every account-local credential file unchanged.

`cdx.main(argv) -> int`

- Synchronize all non-credential state after resolving selected account and before `execvpe`.
- Set `CODEX_HOME` to selected account home.
- Set `CODEX_SQLITE_HOME` to canonical `~/.codex`.
- On migration failure, print concise `cdx:` error and exit `1` without launching Codex.

## Data Flow

1. Resolve selected account.
2. Merge account-local non-credential files into canonical shared home.
3. Link canonical non-credential entries into every account home.
4. Launch Codex with selected credentials and shared SQLite location.
5. Repeat synchronization on each launch so newly introduced Codex paths become shared automatically.

## Testing

- Prove arbitrary canonical and account-local names become shared links.
- Prove credentials remain separate regular files.
- Prove active and archived conversations, history, session names, commands, agents, skills, memories, and future unknown paths share one canonical location.
- Prove SQLite environment routing uses canonical home.
- Prove JSONL merge, idempotency, equal duplicate handling, and conflict protection.

## Architecture Decisions

- Use dynamic discovery, not a whitelist. Requirement includes future Codex state.
- Use supported `CODEX_SQLITE_HOME`, not live SQLite file moves. Moving WAL/SHM sets under active processes risks corruption.
- Reject global `auth.json` swapping. Concurrent sessions could authenticate as the wrong account.
- Reject mount-namespace overlays. Platform and sandbox coupling exceed this local wrapper's needs.