Repository navigation
Description
Approved spec for a separate pull request (not part of #379). The full spec follows; its requirements are the acceptance criteria.
Stop defaulting Codex to a retired model
Status: Approved 2026-11-15 (approved in chat by the user)
Size: small Mode: quick Type: bug class
Source: conversation 2026-11-15 (a real Codex AI Terminal run stopped at Codex's own start-up question because BiBCode asked for a retired model)
Problem
BiBCode has a built-in Codex default of gpt-5.4, and gpt-5.4-mini for Git text generation. Codex retired both for sessions signed in with ChatGPT on 31 August 2026, so a Codex thread or AI Terminal started without a model chosen by the person meets Codex's "this model is no longer available" question and takes no prompt. Observed on 2026-11-15 in the packaged app with a fresh state folder; any install that never saved a Codex model is affected.
Goals
- A Codex thread, AI Terminal or Git text generation that nobody chose a model for starts and answers its first prompt, with no model question from Codex.
- The next retirement of a Codex model does not need a BiBCode release to keep the default working.
Non-goals
- Detecting every future retired model in stored threads: the two named models are the known case; a general check against Codex's model list is a separate decision.
- Changing which models a person can pick, or the defaults of other providers (Claude, Cursor, Grok, OpenCode): not affected by this retirement.
- Editing past database migrations that seeded
gpt-5.4: a migration that already ran must not change; stored values are handled at use time by R4. - Anti-goal: the model picker names one model while Codex runs another.
Users and scenarios
- As a person starting a Codex thread without choosing a model, I want Codex to start with a model it supports, so that my first prompt is answered.
- As a person whose old thread stored
gpt-5.4, I want it to keep working, so that I do not have to find and change a setting after a retirement. - As a person signed in to Codex with an API key, I want my explicitly stored model kept, so that BiBCode does not change a model that still works for me.
Requirements
R1. No model sent when none was chosen [Must]
WHEN a Codex thread, turn or AI Terminal starts with no model chosen by the person (unset or "auto"), the Codex provider SHALL start it without naming a model, so that Codex uses its own recommended model.
Scenario: fresh install
- GIVEN a new state folder with no saved Codex model
- WHEN the person starts a Codex thread and sends a prompt
- THEN the request to Codex names no model, and Codex answers the prompt without a model question
Scenario: a chosen model is kept
- GIVEN the person chose
gpt-6-astrafor the thread - WHEN the thread starts
- THEN the request names
gpt-6-astra, and no default replaces it
R2. Default name comes from Codex [Must]
WHEN BiBCode must show or send a Codex model name for a thread with no chosen model (the model picker, a request field that requires a name), the Codex provider SHALL use the default that the installed Codex reports in its model list.
Scenario: Codex reports a default
- GIVEN the installed Codex model list reports a default model
- WHEN the person opens the model picker of a Codex thread with no chosen model
- THEN the picker shows that model as the default, and not a built-in name
R3. Built-in fallback when Codex reports none [Must]
IF Codex reports no default model or its model list cannot be read, THEN the Codex provider SHALL use the one built-in fallback name where a name is required, and SHALL never use gpt-5.4 or gpt-5.4-mini as a default.
Scenario: model list unavailable
- GIVEN Codex cannot be reached for its model list
- WHEN a request that requires a model name is built
- THEN it carries the built-in fallback name, and never
gpt-5.4orgpt-5.4-mini
R4. Retired names stored in threads or settings [Should]
IF a thread or a saved setting names gpt-5.4 or gpt-5.4-mini (directly or through an alias that means one of them) and the Codex session is signed in with ChatGPT, THEN the Codex provider SHALL start it as if no model were chosen (R1), clear the stored choice, and show the person one notice line naming the retired model.
Scenario: old thread, ChatGPT sign-in
- GIVEN a thread stored with
gpt-5.4and Codex signed in with ChatGPT - WHEN the person sends a prompt
- THEN the turn starts without naming a model, the thread no longer stores
gpt-5.4, and one notice says the model was retired
Scenario: API-key sign-in keeps the model
- GIVEN a thread stored with
gpt-5.4and Codex signed in with an API key - WHEN the person sends a prompt
- THEN the request still names
gpt-5.4, the stored choice is unchanged, and no notice appears
R5. Git text generation follows the same rule [Must]
WHEN BiBCode generates Git text (commit messages, pull request text) with Codex and no Git text model was chosen, the Codex provider SHALL request it without naming a model.
Scenario: no Git text model chosen
- GIVEN no Git text generation model in settings
- WHEN the person asks for a generated commit message
- THEN the request to Codex names no model, and the message is generated
Scenario: a chosen Git text model is kept
- GIVEN the person chose a Git text model
- WHEN a commit message is generated
- THEN the request names that model
R6. One default everywhere [Must]
The server and the web client SHALL agree on the Codex default: the model the picker shows as default is the model the server sends, or both show and send none.
Scenario: picker and request agree
- GIVEN a Codex thread with no chosen model
- WHEN the person opens the picker and then sends a prompt
- THEN the picker's default and the request's model match (or the request names none and the picker says it uses Codex's default)
Constraints and assumptions
- Installed Codex CLI on the reference machine:
codex-cli 0.169.0(codex --version, 2026-11-15). gpt-5.4andgpt-5.4-miniretired from Codex with ChatGPT sign-in on 31 August 2026; API-key sessions are not affected (Codex models page, opened 2026-11-15, medium confidence). The page says that without a model Codex "uses a recommended model".- Current models on that page:
gpt-6-astra,gpt-6.1-sol,gpt-6.1-terra,gpt-6-luna. The page also namesgpt-6-solas the replacement ofgpt-5.4, so the fallback name must be confirmed against the installed CLI. - BiBCode already calls Codex's
model/listandaccount/read(the Codex provider's runtime), so the model list and the sign-in mode are available to it today.
Decisions
D1. Send no model when none was chosen. Alternatives: replace gpt-5.4 with another constant (goes stale at the next retirement). Decided by: user. Source: interview 1.
D2. Take a shown or required default from Codex's model list, with one built-in fallback, gpt-6.1-sol, confirmed against the installed CLI's model list before it is written. Alternatives: a constant only. Decided by: user. Source: interview 2.
D3. Move stored retired models to the default with a notice, only for ChatGPT sign-in. Alternatives: fail at Codex's question; rewrite for every sign-in mode (breaks API-key users). Decided by: user. Source: interview 3.
D4. Git text generation follows D1. Decided by: user. Source: interview 4.
D5. When Codex reports no default, the picker labels the choice "Codex default" instead of showing the fallback name, so the picker never names a model Codex may not run. Decided by: agent's call (reason: the anti-goal).
Risks
- Codex's model list may not mark a default in 0.169.0 -> R3 and D5 keep the behavior defined; see the open question.
- Clearing a stored choice (R4) changes saved data -> only for the two named models and ChatGPT sign-in, with a notice.
Verification
- R1, R5: server tests on the request payloads of thread start, turn start, the collaboration mode and Git text generation: no model field when none was chosen; the chosen model when one was.
- R2, R3, R6: a test that parses Codex's model list and drives the picker default; a test with the list unreadable that asserts the fallback name and the absence of the retired names; a web test that the picker and the request agree.
- R4: tests with a stored
gpt-5.4andgpt-5.4-miniunder each sign-in mode read fromaccount/read, asserting the request, the stored value and the notice. - End to end: a real Codex AI Terminal in the packaged app with a fresh state folder answers its first prompt (this also closes the open Codex step of the agent messaging plan's task 11.3).
- Uncovered inputs: a stored model name that Codex rejects for another reason is passed through unchanged and Codex's own error is shown, as today.
Open questions
- Which field of Codex's
model/listresponse marks the default model in 0.169.0, if any. Owner: engineering. Can wait because: R2 and R3 define the behavior with or without it; the implementer reads the installed CLI's schema.
Appendix: interview record
- 2026-11-15 Evidence: Codex models page and the openai/codex app-server README (research run) / Decision: the two models are retired for ChatGPT sign-in; Codex picks a recommended model when none is given.
- 2026-11-15 Evidence: the Codex provider already calls
model/listandaccount/read/ Decision: both can serve R2 and R3 without new Codex calls. - 2026-11-15 Q1: send no model when none was chosen? / Recommended: yes / Decision: yes.
- 2026-11-15 Q2: default from
model/list, one built-in fallbackgpt-6.1-solchecked against the CLI? / Recommended: yes / Decision: yes. - 2026-11-15 Q3: move stored retired models with a notice, ChatGPT sign-in only? / Recommended: yes / Decision: yes.
- 2026-11-15 Q4: Git text generation follows the same rule? / Recommended: yes / Decision: yes.
Activity
mubeda commentedon Nov 15, 2026
Added scope, moved here from #379 (task 11.3 of
docs/plans/2026-11-13-agent-messaging/): once the default model is fixed, verify a real Codex AI Terminal for agent messaging, which #379 could not do because Codex stopped at its retired-model question.In the packaged app, with the Profiler on and a fresh state folder, using the manual spec
apps/desktop/e2e/specs/manual/send-to-agent-real-providers.e2e.tsand the recipe indocs/testing/cross-platform-validation.md("Send to agent and agent messaging"):bibcode agent inboxandbibcode agent replyfrom its own shell tool, and the message reads completed. This also answers whether Codex's environment policy keepsBIBCODE_AGENT_AUTH.$HOMEto a Codex recipient shows the zero-width-space notice line and loads no skill.rpc.hangonsendRequests.*oragent.*.Record the results in
docs/plans/2026-11-13-agent-messaging/progress.md.fix: close the open issue batch and the findings its validation showed