[bug] Per-project history disappears after reinstall unless tagged

[ndycode]

Summary

After uninstall + reinstall + relaunching the Codex desktop app, per-project conversation history is no longer visible unless the threads were explicitly tagged. Untagged threads appear lost.

Split from issue #486 as the symptom is independent of the pinned-account 503 root cause being tracked there.

Reporter context

• macOS, Codex CLI 0.134.0, Codex app 26.519.81530 (3178)
• Reported in [bug] 503 Service Unavailable #486 (comment)

Expected

Project history survives a reinstall cycle and remains visible without requiring tags.

Actual

Only tagged threads remain visible after reinstall. Other per-project history appears unreachable from the UI.

Investigation ideas

• Verify whether per-project history is keyed by a project identifier that is regenerated on reinstall (e.g., a new project key derived from path + install id).
• Check whether the uninstall path removes a project-key index or workspace-affinity store that the UI consults to surface untagged threads.
• Confirm whether the underlying thread data is still on disk and only the index/listing is lost, vs. truly deleted.

Compliance Confirmation

• Personal development workflow scope
• No policy-bypass request
• No secrets in the report

Refs #486.

[coderabbitai]

Coding Plan

Summary

• introduce persistent-client-key.json at ~/.codex/multi-auth/ level (outside app-bind/ cleanup scope)
• bind reads persistent key first, falls back to state file, generates only if neither exists
• migration handled by copying existing state file key to persistent file on first bind after upgrade
• unbind unchanged — persistent file not deleted, preserving key for next install

Design Choices

Design Choice 1: codex desktop keys history visibility by something correlated with `experimental_bearer_token` in `config.toml`

Options Considered:

1. preserve clientApiKey in a persistent file outside the unbind cleanup scope
2. modify unbind to not delete runtime-rotation-app-bind.json at all
3. store a stable machine-derived key instead of random bytes

Chosen Option: 1

Rationale: option 1: preserving in a separate file maintains clean unbind semantics while adding persistence. option 2 would leave stale operational state. option 3 would reduce security and complicate key derivation.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Persist clientApiKey Across Reinstall Cycles

add a dedicated persistent storage file for the clientApiKey at ~/.codex/multi-auth/persistent-client-key.json, outside the app-bind/ directory that gets cleaned during unbind. modify bind logic to read from this file first, ensuring the same key is used across reinstall cycles.

Task 1: Add Persistent Client Key Storage

introduce storage primitives for the persistent client key file, following the pattern established by lib/local-client-tokens.ts.

• add constant PERSISTENT_CLIENT_KEY_FILE = "persistent-client-key.json" in lib/runtime/app-bind.ts near existing constants at lines 16-19
• add interface PersistentClientKey { version: 1; clientApiKey: string; createdAt: number; } for the storage schema
• add readPersistentClientKey(multiAuthDir: string): Promise<string | null> that reads the key file, returns null on ENOENT or invalid schema
• add writePersistentClientKey(multiAuthDir: string, key: string): Promise<void> that writes the key with proper error handling
• the file path should be join(multiAuthDir, PERSISTENT_CLIENT_KEY_FILE) — note this is at the ~/.codex/multi-auth/ level, not inside app-bind/

Task 2: Modify Bind Logic to Use Persistent Key

update bindCodexAppRuntimeRotationLocked to read from the persistent file before generating a new key, and write to it when generating.

• in lib/runtime/app-bind.ts, modify the key resolution at lines 639-646 to: (1) check persistent file first, (2) fallback to existing state file, (3) generate new only if neither exists
• when a key is retrieved from existing state but persistent file doesn't exist, write to persistent file (migration path for existing installs)
• when a new key is generated, write to both the persistent file and the state file
• no changes needed to unbindCodexAppRuntimeRotationLocked — the persistent file is outside app-bind/ and won't be in the delete list

Task 3: Add Regression Tests

add test coverage to ensure the key persists across unbind/rebind cycles.

• add test in test/app-bind.test.ts verifying that clientApiKey is identical after unbind + rebind when persistent file exists
• add test verifying that deleting runtime-rotation-app-bind.json but keeping persistent file results in same key on rebind
• add test for migration: existing state file with key but no persistent file → rebind should copy key to persistent file
• flag: ensure tests cover the windows case where path casing might differ between reads — use resolvePath consistently
• flag: verify no concurrency issues with the existing lockfile mechanism covering the new file operations

🤖 Prompt for AI agents

this phase adds a persistent storage layer for `clientApiKey` in
`lib/runtime/app-bind.ts` and wires it into the bind flow so the key survives
unbind/rebind cycles. the goal is zero key churn across reinstalls without
touching unbind logic.

**task 1: add storage primitives in `lib/runtime/app-bind.ts`**
- add constant `PERSISTENT_CLIENT_KEY_FILE = "persistent-client-key.json"` near
the existing constants at lines 16-19
- add interface `PersistentClientKey { version: 1; clientApiKey: string;
createdAt: number; }` for the file schema
- add `readPersistentClientKey(multiAuthDir: string): Promise<string | null>` —
reads `join(multiAuthDir, PERSISTENT_CLIENT_KEY_FILE)`, returns `null` on
`ENOENT` or invalid schema, following the pattern in
`lib/local-client-tokens.ts`
- add `writePersistentClientKey(multiAuthDir: string, key: string):
Promise<void>` — writes the key with proper error handling
- the file lives at `~/.codex/multi-auth/persistent-client-key.json`, not inside
`app-bind/`

**task 2: update key resolution in `bindCodexAppRuntimeRotationLocked` at lines
639-646**
- resolution order: (1) read from persistent file first, (2) fallback to
existing state file, (3) generate new only if neither exists
- migration path: if key comes from existing state file but persistent file is
absent, write key to persistent file
- new key path: write to both persistent file and state file
- do not touch `unbindCodexAppRuntimeRotationLocked` — persistent file is
outside `app-bind/` and is not in the delete list

**task 3: add regression tests in `test/app-bind.test.ts`**
- test: `clientApiKey` is identical after unbind + rebind when persistent file
exists
- test: deleting `runtime-rotation-app-bind.json` but keeping persistent file →
same key on rebind
- test: migration scenario — state file has key, no persistent file → rebind
copies key to persistent file
- **flag missing regression tests** if any of the above are not covered
- **flag windows edge case:** path casing differences between reads — use
`resolvePath` consistently in all new paths
- **flag concurrency risk:** verify the existing `lockfile` mechanism in
`lib/runtime/app-bind.ts` covers all new file operations

Research

the app-bind system in lib/runtime/app-bind.ts manages codex desktop integration by rewriting ~/.codex/config.toml with a provider block containing an experimental_bearer_token (the clientApiKey). this key is generated via randomBytes(32).toString("hex") at lib/runtime/app-bind.ts:159-161 and stored only in runtime-rotation-app-bind.json. during unbind (lib/runtime/app-bind.ts:791-801), all three state files in ~/.codex/multi-auth/app-bind/ are deleted, losing the key. on reinstall, a new random key is generated, causing codex desktop to lose correlation with prior conversation history. the pattern for persistent storage that survives uninstall already exists in lib/local-client-tokens.ts which writes to ~/.codex/multi-auth/local-client-tokens.json.

---

🚀 Next Steps

🤖 All AI agent prompts combined

this phase adds a persistent storage layer for `clientApiKey` in
`lib/runtime/app-bind.ts` and wires it into the bind flow so the key survives
unbind/rebind cycles. the goal is zero key churn across reinstalls without
touching unbind logic.

**task 1: add storage primitives in `lib/runtime/app-bind.ts`**
- add constant `PERSISTENT_CLIENT_KEY_FILE = "persistent-client-key.json"` near
the existing constants at lines 16-19
- add interface `PersistentClientKey { version: 1; clientApiKey: string;
createdAt: number; }` for the file schema
- add `readPersistentClientKey(multiAuthDir: string): Promise<string | null>` —
reads `join(multiAuthDir, PERSISTENT_CLIENT_KEY_FILE)`, returns `null` on
`ENOENT` or invalid schema, following the pattern in
`lib/local-client-tokens.ts`
- add `writePersistentClientKey(multiAuthDir: string, key: string):
Promise<void>` — writes the key with proper error handling
- the file lives at `~/.codex/multi-auth/persistent-client-key.json`, not inside
`app-bind/`

**task 2: update key resolution in `bindCodexAppRuntimeRotationLocked` at lines
639-646**
- resolution order: (1) read from persistent file first, (2) fallback to
existing state file, (3) generate new only if neither exists
- migration path: if key comes from existing state file but persistent file is
absent, write key to persistent file
- new key path: write to both persistent file and state file
- do not touch `unbindCodexAppRuntimeRotationLocked` — persistent file is
outside `app-bind/` and is not in the delete list

**task 3: add regression tests in `test/app-bind.test.ts`**
- test: `clientApiKey` is identical after unbind + rebind when persistent file
exists
- test: deleting `runtime-rotation-app-bind.json` but keeping persistent file →
same key on rebind
- test: migration scenario — state file has key, no persistent file → rebind
copies key to persistent file
- **flag missing regression tests** if any of the above are not covered
- **flag windows edge case:** path casing differences between reads — use
`resolvePath` consistently in all new paths
- **flag concurrency risk:** verify the existing `lockfile` mechanism in
`lib/runtime/app-bind.ts` covers all new file operations

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!