Provider terminals can select a different Codex home through inherited environment, provider overrides or cwd. Inspect the configured/generated shadow and the actual projected launch home before starting a terminal. Apply canonical SQLite defaults when the selected home is the managed authentication shadow, including relative and symlink-alias selections, while preserving explicit overrides and unrelated direct-home defaults.
Keep native path selection and existing CLI authentication, check restarts before stopping the running PTY, and leave running attachment unchanged. Carry fixed recovery guidance through the typed terminal error. The resolver performs no installation, authentication or shadow writes. Recovery documentation identifies generated/configured shadows on the environment's host, including Windows paths and the intentional all-platform upgrade interruption.
Rebuilt from Timpan4's #19861. Depends on #21947; land both together. The original terminal-home, account-lookup, direct-alias, restart-preservation and diagnostic requirements remain, with redundant permutation tests removed.
Validation: all 365 focused cases pass, including 125 terminal cases, plus the scoped settings case; scoped lint/format and server typecheck pass. Fresh captured-PTY regressions failed before the generated-shadow default fix. Current-head proof passed actual terminal-resolver output into real Codex 0.156.1: exact, relative and symlink-alias selections committed threads to the shared database, the explicit SQLite control used its chosen directory, and the generated shadow gained no SQLite files. Shared auth bytes stayed unchanged. Synthetic CLI credentials and loopback inference were used; the native process was launched directly with resolver output. The terminal service tests prove the PTY environment, but no native interactive PTY session was exercised.
Human startup/recovery-policy approval remains required: the deliberate all-links refusal interrupts older overlays on Linux/macOS too. No real OAuth, UI, Windows/macOS, packaged Electron/SEA or mobile pass is claimed. Windows test cases inject platform semantics on Linux.
Models/harness: GPT-6 Astra tests; GPT-6.1 Sol implementation; independent Opus 5.5 and GPT-6 Sol reviews, through T3 Code.
Added 6 commits
Verdict: Needs Human Approval
Macroscope's review found this PR requires human approval — The PR changes Codex terminal launch and restart behavior across platforms, including preflight checks that can block spawning and a new default SQLite-home assignment. Its production-path scope and altered default warrant human review despite focused tests and strong ownership history.
You can add or adjust custom eligibility rules. Learn more.
✅ Thread transfer remains within every enforced ceiling.
ℹ️ No successful
mainbaseline artifact is available yet. This run establishes the initial measurement.
| Provider | Metric | Main baseline | This PR | Impact | PR ceiling | |
|---|---|---|---|---|---|---|
| Codex | Total thread wire | — | 5.0 KiB | — | 6.8 KiB | ✅ |
| Codex | Thread snapshot wire | — | 3.8 KiB | — | 4.9 KiB | ✅ |
| Codex | Live turn WebSocket wire | — | 1.2 KiB | — | 2.0 KiB | ✅ |
| Codex | Live turn WebSocket decoded | — | 20.9 KiB | — | 29.3 KiB | ✅ |
| Codex | Live turn messages | — | 2 | — | 8 | ✅ |
| Claude | Total thread wire | — | 5.0 KiB | — | 6.8 KiB | ✅ |
| Claude | Thread snapshot wire | — | 3.8 KiB | — | 4.9 KiB | ✅ |
| Claude | Live turn WebSocket wire | — | 1.2 KiB | — | 2.0 KiB | ✅ |
| Claude | Live turn WebSocket decoded | — | 21.2 KiB | — | 29.3 KiB | ✅ |
| Claude | Live turn messages | — | 2 | — | 8 | ✅ |
Baseline: unavailable · PR result: 627ab75 · Source CI: success
10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.
Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.
No actionable comments were generated in the recent review. 🎉
8f5dc2dc-2d1a-49db-9484-8aef8e8bb25eReviewing files that changed from the base of the PR and between 7bb8b1a74a2a36d6d5ccac8589bd91c73256704e and 627ab752b7225b026c250e66d0048800b1a7ec58.
apps/server/src/serverSettings.test.tsapps/server/src/terminal/Manager.test.tsapps/server/src/terminal/Manager.tsdocs/user/providers-codex.mdpackages/contracts/src/terminal.test.tspackages/contracts/src/terminal.tspackages/shared/src/HostProcess.tsLimit details: You’ve used all 10 included reviews currently available.
Terminal environment resolution now applies Codex SQLite-home settings and checks relevant homes for SQLite recovery conditions before launch or restart. Provider environment errors can include recovery guidance. Tests cover environment precedence, home selection, and failure behavior.
Changes: Codex SQLite Home Recovery
| Layer / File(s) | Summary |
|---|---|
Environment and error contracts packages/contracts/src/terminal.ts, apps/server/src/terminal/Manager.ts | The provider environment resolver accepts state directory and working directory inputs. TerminalProviderEnvironmentError can use a supplied detail string. |
Codex environment resolution and launch wiring apps/server/src/terminal/Manager.ts, packages/shared/src/HostProcess.ts | Terminal open and restart resolution applies Codex SQLite-home settings and inspects the recovery layout and selected Codex home. It wires filesystem and account-home access into resolution. |
Resolution coverage and recovery guidance apps/server/src/terminal/Manager.test.ts, apps/server/src/serverSettings.test.ts, packages/contracts/src/terminal.test.ts, docs/user/providers-codex.md | Tests cover environment precedence, selected-home checks, and typed failures. The documentation describes manual recovery and symlink removal. |
Priority: ➖ Normal
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Feature
| 1 | sequenceDiagram |
| 2 | participant TerminalManager |
| 3 | participant EnvironmentResolver |
| 4 | participant FileSystem |
| 5 | participant PTY |
| 6 | TerminalManager->>EnvironmentResolver: resolve open or restart environment |
| 7 | EnvironmentResolver->>FileSystem: inspect relevant Codex homes |
| 8 | FileSystem-->>EnvironmentResolver: return inspection results |
| 9 | EnvironmentResolver-->>TerminalManager: return environment or typed error |
| 10 | TerminalManager->>PTY: spawn after successful resolution |
Suggested reviewers: t3dotgg, maria-rcks
627abTerminals that use Codex accounts now share a SQLite home. Before launch or restart, they check for legacy SQLite symlinks and show recovery guidance when one is found. Attaching to a terminal that needs a new process still applies the same environment and checks. No concrete merge-blocking risk was found.
| Check name | Status | Explanation |
|---|---|---|
| Title check | Passed | The title clearly and concisely describes the primary change: inspecting actual Codex terminal homes before launch. |
| Description check | Passed | The description explains the problem, implementation, scope, verification results, limitations, dependencies, and required approval. It is mostly complete, although it does not use the template headin… |
| 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. |
Explanation
The description explains the problem, implementation, scope, verification results, limitations, dependencies, and required approval. It is mostly complete, although it does not use the template headings and does not provide a direct maintainer-approval link or comment.
Note
This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.
Comment @coderabbitai help to get the list of available commands.