fix(migration): stop rewriting explicit gpt-5.3-codex to gpt-5.4 (#3777)

`openai/gpt-5.3-codex` is the codex-series powerhouse still recommended
in docs/guide/agent-model-matching.md and listed in the default
fallback chain in docs/reference/configuration.md, not a deprecated
alias for `gpt-5.4`. The migration entry silently rewrote any user
config that picked `gpt-5.3-codex` for its token efficiency, sending
agents to a non-codex model on every startup.

Drop the bogus mapping from MODEL_VERSION_MAP and add a regression
test that explicit `gpt-5.3-codex` selections (including in nested
fallback_models) survive `migrateModelVersions`. Users already
auto-migrated previously can revert to `gpt-5.3-codex` by hand and it
will now stick on subsequent loads regardless of the sidecar history.

src/shared/migration.test.ts

@@ -578,10 +578,18 @@ describe("MODEL_VERSION_MAP", () => {
     expect(MODEL_VERSION_MAP["anthropic/claude-opus-4-5"]).toBe("anthropic/claude-opus-4-7")
   })
 
-  test("maps openai/gpt-5.3-codex to openai/gpt-5.4 for deep category migration", () => {
+  test("does not migrate openai/gpt-5.3-codex (still a supported codex variant, #3777)", () => {
     // given/when: Check MODEL_VERSION_MAP
-    // then: gpt-5.3-codex should migrate to gpt-5.4
-    expect(MODEL_VERSION_MAP["openai/gpt-5.3-codex"]).toBe("openai/gpt-5.4")
+    // then: gpt-5.3-codex must remain user-selectable — it is the codex
+    //       powerhouse documented in agent-model-matching.md, not a
+    //       deprecated alias for gpt-5.4
+    expect(MODEL_VERSION_MAP["openai/gpt-5.3-codex"]).toBeUndefined()
+  })
+
+  test("maps openai/gpt-5.4 to openai/gpt-5.5", () => {
+    // given/when: Check MODEL_VERSION_MAP
+    // then: gpt-5.4 should migrate to gpt-5.5
+    expect(MODEL_VERSION_MAP["openai/gpt-5.4"]).toBe("openai/gpt-5.5")
   })
 })
 
@@ -602,6 +610,26 @@ describe("migrateModelVersions", () => {
     expect(sisyphus.temperature).toBe(0.1)
   })
 
+  test("#given a config with explicit gpt-5.3-codex (#3777) #when migrating #then preserves the codex variant", () => {
+    // given: User explicitly picked the codex powerhouse for token efficiency
+    const agents = {
+      sisyphus: { model: "openai/gpt-5.3-codex", variant: "medium" },
+      hephaestus: {
+        model: "openai/gpt-5.3-codex",
+        fallback_models: [{ model: "openai/gpt-5.3-codex" }],
+      },
+    }
+
+    // when: Migrate model versions
+    const { migrated, changed, newMigrations } = migrateModelVersions(agents)
+
+    // then: gpt-5.3-codex must remain — auto-rewriting silently broke configs
+    expect(changed).toBe(false)
+    expect(newMigrations).toEqual([])
+    expect((migrated["sisyphus"] as Record<string, unknown>).model).toBe("openai/gpt-5.3-codex")
+    expect((migrated["hephaestus"] as Record<string, unknown>).model).toBe("openai/gpt-5.3-codex")
+  })
+
   test("replaces anthropic model version", () => {
     // given: Agent config with old anthropic model
     const agents = {

src/shared/migration/model-versions.ts

@@ -4,12 +4,17 @@
  * bumps to newer model versions.
  *
  * Keys are full "provider/model" strings. Only openai and anthropic entries needed.
+ *
+ * Only include genuinely retired/superseded models here. Do NOT add mappings
+ * for current, user-selectable variants — `gpt-5.3-codex` is the canonical
+ * codex powerhouse referenced in docs/guide/agent-model-matching.md and is
+ * NOT a deprecated alias for `gpt-5.4`. Auto-rewriting an explicit user
+ * choice silently broke configurations (#3777).
  */
 export const MODEL_VERSION_MAP: Record<string, string> = {
   "anthropic/claude-opus-4-5": "anthropic/claude-opus-4-7",
   "anthropic/claude-opus-4-6": "anthropic/claude-opus-4-7",
   "anthropic/claude-sonnet-4-5": "anthropic/claude-sonnet-4-6",
-  "openai/gpt-5.3-codex": "openai/gpt-5.4",
   "openai/gpt-5.4": "openai/gpt-5.5",
 }