fix(migration): track applied migrations in sidecar so user reverts stick

Users who auto-migrated from `openai/gpt-5.3-codex` to `openai/gpt-5.4` and then reverted their config back to `gpt-5.3-codex` by hand had the migration re-apply on every startup in an infinite loop. Discord bug report pointed at the exact symptom: "i deleted the migrations and they kept coming back". The old migration tracking lived on the config body itself as a `_migrations` string array. The skip-already-applied check relied on the user not touching that field. But users hit by the unwanted migration naturally reached for the JSON file to roll their model back, and the natural human reaction to an incomprehensible internal field next to their config is to delete it. That wiped the migration memory and let the same migration re-apply at the next startup. This PR introduces a sidecar state file that lives next to the config as `<configPath>.migrations.json` and tracks applied migrations outside the user's hand-editable config body. The migration pipeline: 1. Reads applied migrations from BOTH the sidecar AND the legacy in-config `_migrations` field, unioning them. This keeps old configs that still carry `_migrations` working without forcing a reset. 2. Writes the updated migration set to the sidecar, never to the config body. 3. Strips the legacy `_migrations` field out of the config body on the first write after the sidecar takes over. Users stop seeing the mystery internal field in their own config from that point forward. If the user also deletes the sidecar (explicit fresh-start gesture) the migrations run again - that is intentional. Tests (TDD, all new tests written before implementation): - src/shared/migration/migrations-sidecar.test.ts - 11 unit tests covering read/write/round-trip, malformed-payload resilience, parent-directory creation, sorted output for stable diffs, and non-string entry filtering. - src/shared/migration.test.ts - 6 new integration tests under the "migrateConfigFile with migration tracking via sidecar" block covering: no-op path, sidecar-only write, sidecar skip after user revert, legacy _migrations mirroring + strip, sidecar + legacy union with dedupe, and partial-history append. Existing "preserves existing _migrations and appends new ones" test was rewritten to assert the new sidecar-based contract. - Also fixes a latent test-hygiene bug: the shared /tmp/nonexistent-path-for-test.json config path used by many migrateConfigFile tests did not clean up its companion sidecar between tests, letting state from one test bleed into the next. Added afterEach that unlinks the sidecar. Verified: - bun test src/shared/migration/ -> 11 new sidecar tests pass - bun test src/shared/migration.test.ts -> 82 pass, 0 fail - bun run typecheck -> clean - bun run script/run-ci-tests.ts -> 4458 pass, 0 fail (full suite)
2026-04-09 10:54:08 +09:00
parent d2bb5d57d1
commit 00a4f318ef
4 changed files with 444 additions and 51 deletions
@@ -321,6 +321,18 @@ describe("migrateHookNames", () => {
 describe("migrateConfigFile", () => {
  const testConfigPath = "/tmp/nonexistent-path-for-test.json"

+  // Tests in this block share a single config path and do not write a real
+  // config file, but migrateConfigFile now persists migration tracking to a
+  // sidecar next to the config (#3263). Clear the sidecar between tests so
+  // state from an earlier test does not bleed into the next one.
+  afterEach(() => {
+    try {
+      fs.unlinkSync(`${testConfigPath}.migrations.json`)
+    } catch {
+      // ignore — sidecar may not exist
+    }
+  })
+
  test("migrates experimental.hashline_edit to top-level hashline_edit", () => {
    // given: Config with legacy experimental.hashline_edit
    const rawConfig: Record<string, unknown> = {
@@ -790,8 +802,8 @@ describe("migrateConfigFile _migrations tracking", () => {
    fs.rmSync(tmpDir, { recursive: true })
  })

-  test("preserves existing _migrations and appends new ones", () => {
-    // given: Config with existing migration history and a new migratable model
+  test("migrates legacy in-config _migrations into the sidecar and appends new migrations (#3263)", () => {
+    // given: Config with an existing legacy in-config _migrations history and a new migratable model
    const tmpDir = fs.mkdtempSync("/tmp/migration-test-")
    const configPath = `${tmpDir}/oh-my-opencode.json`
    const rawConfig: Record<string, unknown> = {
@@ -804,12 +816,17 @@ describe("migrateConfigFile _migrations tracking", () => {
    // when: Migrate config file
    const result = migrateConfigFile(configPath, rawConfig)

-    // then: New migration appended, old one preserved
+    // then: The config body has _migrations stripped. The full history
+    // (legacy + new) is written to the sidecar file exactly once.
    expect(result).toBe(true)
-    expect(rawConfig._migrations).toEqual([
+    expect(rawConfig._migrations).toBeUndefined()
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).prometheus.model).toBe("anthropic/claude-opus-4-6")
+
+    const sidecar = JSON.parse(fs.readFileSync(`${configPath}.migrations.json`, "utf-8"))
+    expect(new Set(sidecar.appliedMigrations)).toEqual(new Set([
      "model-version:openai/gpt-5.4-codex->openai/gpt-5.3-codex",
      "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
-    ])
+    ]))

    // cleanup
    fs.rmSync(tmpDir, { recursive: true })
@@ -1263,7 +1280,7 @@ describe("migrateModelVersions with applied migrations", () => {
  })
 })

-describe("migrateConfigFile with _migrations tracking", () => {
+describe("migrateConfigFile with migration tracking via sidecar (#3263)", () => {
  const cleanupPaths: string[] = []

  afterEach(() => {
@@ -1276,72 +1293,180 @@ describe("migrateConfigFile with _migrations tracking", () => {
    cleanupPaths.length = 0
  })

-  test("records new migrations in _migrations field", () => {
-    // given: Config with old model, no _migrations field
-    const testConfigPath = "/tmp/test-config-migrations-1.json"
+  function tempConfigPath(label: string): string {
+    const workdir = fs.mkdtempSync(`/tmp/omo-migration-${label}-`)
+    cleanupPaths.push(workdir)
+    return path.join(workdir, "oh-my-openagent.json")
+  }
+
+  function sidecarPath(configPath: string): string {
+    return `${configPath}.migrations.json`
+  }
+
+  test("does not emit migration history when no migration applies", () => {
+    // given: Config with a model that does not appear in MODEL_VERSION_MAP
+    const testConfigPath = tempConfigPath("no-op")
    const rawConfig: Record<string, unknown> = {
      agents: {
        sisyphus: { model: "openai/gpt-5.4-codex" },
      },
    }
    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
-    cleanupPaths.push(testConfigPath)

-    // when: Migrate config file
    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)

-    // then: gpt-5.4-codex should not create migration history
    expect(needsWrite).toBe(false)
    expect(rawConfig._migrations).toBeUndefined()
    expect((rawConfig.agents as Record<string, Record<string, unknown>>).sisyphus.model).toBe("openai/gpt-5.4-codex")
+    expect(fs.existsSync(sidecarPath(testConfigPath))).toBe(false)
  })

-  test("skips re-applying already-recorded migrations", () => {
-    // given: Config with old model but migration already in _migrations
-    const testConfigPath = "/tmp/test-config-migrations-2.json"
+  test("writes applied migrations to sidecar instead of leaving them on the config", () => {
+    // given: Config that needs a real model migration and has no prior history
+    const testConfigPath = tempConfigPath("sidecar-write")
    const rawConfig: Record<string, unknown> = {
      agents: {
-        sisyphus: { model: "openai/gpt-5.4-codex" },
-      },
-      _migrations: ["model-version:openai/gpt-5.4-codex->openai/gpt-5.3-codex"],
-    }
-    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
-    cleanupPaths.push(testConfigPath)
-
-    // when: Migrate config file
-    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
-
-    // then: Should not migrate (user reverted)
-    expect(needsWrite).toBe(false)
-    expect((rawConfig.agents as Record<string, Record<string, unknown>>).sisyphus.model).toBe("openai/gpt-5.4-codex")
-    expect(rawConfig._migrations).toEqual(["model-version:openai/gpt-5.4-codex->openai/gpt-5.3-codex"])
-  })
-
-  test("preserves existing _migrations and appends new ones", () => {
-    // given: Config with multiple old models, partial migration history
-    const testConfigPath = "/tmp/test-config-migrations-3.json"
-    const rawConfig: Record<string, unknown> = {
-      agents: {
-        sisyphus: { model: "openai/gpt-5.4-codex" },
        oracle: { model: "anthropic/claude-opus-4-5" },
      },
-      _migrations: ["model-version:openai/gpt-5.4-codex->openai/gpt-5.3-codex"],
    }
    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
-    cleanupPaths.push(testConfigPath)

-    // when: Migrate config file
    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)

-    // then: Should skip sisyphus, migrate oracle, append to _migrations
    expect(needsWrite).toBe(true)
-    expect((rawConfig.agents as Record<string, Record<string, unknown>>).sisyphus.model).toBe("openai/gpt-5.4-codex")
    expect((rawConfig.agents as Record<string, Record<string, unknown>>).oracle.model).toBe("anthropic/claude-opus-4-6")
-    expect(rawConfig._migrations).toEqual([
-      "model-version:openai/gpt-5.4-codex->openai/gpt-5.3-codex",
+    expect(rawConfig._migrations).toBeUndefined()
+
+    const sidecar = JSON.parse(fs.readFileSync(sidecarPath(testConfigPath), "utf-8"))
+    expect(sidecar.appliedMigrations).toEqual([
      "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
    ])
  })

+  test("skips re-applying a migration that is recorded in the sidecar even if the user edited _migrations away", () => {
+    // This is the core #3263 regression: a user auto-migrated from
+    // gpt-5.3-codex to gpt-5.4, reverted to gpt-5.3-codex by hand, and
+    // deleted _migrations in the process. Without the sidecar their
+    // revert was clobbered on every startup.
+    const testConfigPath = tempConfigPath("sidecar-revert")
+    fs.writeFileSync(
+      sidecarPath(testConfigPath),
+      JSON.stringify({
+        appliedMigrations: ["model-version:openai/gpt-5.3-codex->openai/gpt-5.4"],
+      }),
+    )
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        oracle: { model: "openai/gpt-5.3-codex" },
+      },
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))

+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    expect(needsWrite).toBe(false)
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).oracle.model).toBe("openai/gpt-5.3-codex")
+    expect(rawConfig._migrations).toBeUndefined()
+  })
+
+  test("mirrors legacy in-config _migrations into the sidecar and then strips the field", () => {
+    // BC path: configs written by older OMO versions still carry the
+    // legacy _migrations field in the JSON body. On the next startup we
+    // must copy that history into the new sidecar and remove the field
+    // from the config so the migration tracking lives in exactly one
+    // place from then on.
+    const testConfigPath = tempConfigPath("bc-mirror")
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        oracle: { model: "openai/gpt-5.3-codex" },
+      },
+      _migrations: ["model-version:openai/gpt-5.3-codex->openai/gpt-5.4"],
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
+
+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    // needsWrite is true because we rewrote the config to drop _migrations
+    expect(needsWrite).toBe(true)
+    expect(rawConfig._migrations).toBeUndefined()
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).oracle.model).toBe("openai/gpt-5.3-codex")
+
+    const sidecar = JSON.parse(fs.readFileSync(sidecarPath(testConfigPath), "utf-8"))
+    expect(sidecar.appliedMigrations).toEqual([
+      "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+    ])
+  })
+
+  test("unions sidecar and legacy _migrations entries, deduplicating", () => {
+    // Defensive case: a config written by two different OMO versions
+    // could end up with an entry in _migrations that is also in the
+    // sidecar. The merged set should be deduplicated and the config
+    // should not be re-migrated.
+    const testConfigPath = tempConfigPath("sidecar-union")
+    fs.writeFileSync(
+      sidecarPath(testConfigPath),
+      JSON.stringify({
+        appliedMigrations: [
+          "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+          "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
+        ],
+      }),
+    )
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        oracle: { model: "anthropic/claude-opus-4-5" },
+      },
+      _migrations: ["model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6"],
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
+
+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    // needsWrite because the legacy _migrations field was stripped
+    expect(needsWrite).toBe(true)
+    expect(rawConfig._migrations).toBeUndefined()
+    // The reverted opus-4-5 value must be preserved
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).oracle.model).toBe("anthropic/claude-opus-4-5")
+
+    const sidecar = JSON.parse(fs.readFileSync(sidecarPath(testConfigPath), "utf-8"))
+    expect(sidecar.appliedMigrations).toEqual([
+      "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
+      "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+    ])
+  })
+
+  test("appends new migrations to the sidecar when partial history exists", () => {
+    // Scenario: sidecar already has one migration, a second model still
+    // needs to be migrated. The new migration should be recorded and the
+    // already-applied one preserved.
+    const testConfigPath = tempConfigPath("sidecar-append")
+    fs.writeFileSync(
+      sidecarPath(testConfigPath),
+      JSON.stringify({
+        appliedMigrations: ["model-version:openai/gpt-5.3-codex->openai/gpt-5.4"],
+      }),
+    )
+    const rawConfig: Record<string, unknown> = {
+      agents: {
+        codex: { model: "openai/gpt-5.3-codex" },
+        claude: { model: "anthropic/claude-opus-4-5" },
+      },
+    }
+    fs.writeFileSync(testConfigPath, JSON.stringify(rawConfig, null, 2))
+
+    const needsWrite = migrateConfigFile(testConfigPath, rawConfig)
+
+    expect(needsWrite).toBe(true)
+    // codex was reverted, must stay
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).codex.model).toBe("openai/gpt-5.3-codex")
+    // claude migrates
+    expect((rawConfig.agents as Record<string, Record<string, unknown>>).claude.model).toBe("anthropic/claude-opus-4-6")
+    expect(rawConfig._migrations).toBeUndefined()
+
+    const sidecar = JSON.parse(fs.readFileSync(sidecarPath(testConfigPath), "utf-8"))
+    expect(new Set(sidecar.appliedMigrations)).toEqual(new Set([
+      "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+      "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
+    ]))
+  })
 })
@@ -4,6 +4,7 @@ import { writeFileAtomically } from "../write-file-atomically"
 import { AGENT_NAME_MAP, migrateAgentNames } from "./agent-names"
 import { migrateHookNames } from "./hook-names"
 import { migrateModelVersions } from "./model-versions"
+import { readAppliedMigrations, writeAppliedMigrations } from "./migrations-sidecar"

 export function migrateConfigFile(
  configPath: string,
@@ -12,10 +13,22 @@ export function migrateConfigFile(
  const copy = structuredClone(rawConfig)
  let needsWrite = false

-  // Load previously applied migrations
-  const existingMigrations = Array.isArray(copy._migrations)
+  // Load previously applied migrations from BOTH the legacy in-config
+  // `_migrations` field AND the external sidecar file. The sidecar is the
+  // new source of truth because users were editing the config file to
+  // revert auto-migrated values and accidentally dropping the `_migrations`
+  // field in the process, which produced an infinite migration loop on
+  // every startup (#3263). Reading from both sources keeps old configs
+  // that still carry `_migrations` working without a forced reset.
+  const sidecarMigrations = readAppliedMigrations(configPath)
+  const inConfigMigrations = Array.isArray(copy._migrations)
    ? new Set(copy._migrations as string[])
    : new Set<string>()
+  const existingMigrations = new Set<string>([
+    ...sidecarMigrations,
+    ...inConfigMigrations,
+  ])
+  const hadLegacyInConfigMigrations = inConfigMigrations.size > 0
  const allNewMigrations: string[] = []

  if (copy.agents && typeof copy.agents === "object") {
@@ -54,13 +67,30 @@ export function migrateConfigFile(
    allNewMigrations.push(...newMigrations)
  }

-  // Record newly applied migrations
-  if (allNewMigrations.length > 0) {
-    const updatedMigrations = Array.from(existingMigrations)
-    updatedMigrations.push(...allNewMigrations)
-    copy._migrations = updatedMigrations
+  // Record newly applied migrations. We persist the full set (existing +
+  // new) to the external sidecar file and strip the legacy `_migrations`
+  // field from the config body on its way out, so users stop having to
+  // think about a field that never should have been in their config in
+  // the first place. The in-memory `rawConfig` never re-exposes
+  // `_migrations` to downstream schema validation.
+  const newMigrationsToRecord = allNewMigrations.filter(mKey => !existingMigrations.has(mKey))
+  if (newMigrationsToRecord.length > 0 || hadLegacyInConfigMigrations) {
+    const fullMigrationSet = new Set<string>([
+      ...existingMigrations,
+      ...newMigrationsToRecord,
+    ])
+    writeAppliedMigrations(configPath, fullMigrationSet)
+  }
+  if (newMigrationsToRecord.length > 0) {
    needsWrite = true
  }
+  if (hadLegacyInConfigMigrations) {
+    // Migrating state out of the config body is itself a config write.
+    needsWrite = true
+  }
+  if ("_migrations" in copy) {
+    delete copy._migrations
+  }

  if (copy.omo_agent) {
    copy.sisyphus_agent = copy.omo_agent
@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { getSidecarPath, readAppliedMigrations, writeAppliedMigrations } from "./migrations-sidecar"
+
+describe("migrations sidecar", () => {
+  let workdir: string
+
+  beforeEach(() => {
+    workdir = mkdtempSync(join(tmpdir(), "omo-migrations-sidecar-"))
+  })
+
+  afterEach(() => {
+    rmSync(workdir, { recursive: true, force: true })
+  })
+
+  describe("getSidecarPath", () => {
+    test("appends .migrations.json to the config path", () => {
+      expect(getSidecarPath("/home/user/.config/opencode/oh-my-openagent.json")).toBe(
+        "/home/user/.config/opencode/oh-my-openagent.json.migrations.json",
+      )
+    })
+
+    test("works for jsonc configs too", () => {
+      expect(getSidecarPath("/home/user/oh-my-openagent.jsonc")).toBe(
+        "/home/user/oh-my-openagent.jsonc.migrations.json",
+      )
+    })
+  })
+
+  describe("readAppliedMigrations", () => {
+    test("returns an empty set when no sidecar exists", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      expect(readAppliedMigrations(configPath).size).toBe(0)
+    })
+
+    test("returns the applied migrations listed in a well-formed sidecar", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      writeFileSync(
+        getSidecarPath(configPath),
+        JSON.stringify({
+          appliedMigrations: [
+            "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+            "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
+          ],
+        }),
+      )
+
+      const applied = readAppliedMigrations(configPath)
+
+      expect(applied.size).toBe(2)
+      expect(applied.has("model-version:openai/gpt-5.3-codex->openai/gpt-5.4")).toBe(true)
+      expect(applied.has("model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6")).toBe(true)
+    })
+
+    test("returns an empty set on malformed JSON instead of throwing", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      writeFileSync(getSidecarPath(configPath), "{ this is not json")
+
+      expect(readAppliedMigrations(configPath).size).toBe(0)
+    })
+
+    test("returns an empty set when the sidecar payload has the wrong shape", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      writeFileSync(getSidecarPath(configPath), JSON.stringify({ appliedMigrations: "not-an-array" }))
+
+      expect(readAppliedMigrations(configPath).size).toBe(0)
+    })
+
+    test("ignores non-string entries inside appliedMigrations", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      writeFileSync(
+        getSidecarPath(configPath),
+        JSON.stringify({
+          appliedMigrations: ["model-version:a->b", 42, null, "model-version:c->d"],
+        }),
+      )
+
+      const applied = readAppliedMigrations(configPath)
+
+      expect(applied.size).toBe(2)
+      expect(applied.has("model-version:a->b")).toBe(true)
+      expect(applied.has("model-version:c->d")).toBe(true)
+    })
+  })
+
+  describe("writeAppliedMigrations", () => {
+    test("creates the sidecar with the given migration keys", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      const migrations = new Set([
+        "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+      ])
+
+      const ok = writeAppliedMigrations(configPath, migrations)
+
+      expect(ok).toBe(true)
+      expect(existsSync(getSidecarPath(configPath))).toBe(true)
+
+      const body = JSON.parse(readFileSync(getSidecarPath(configPath), "utf-8"))
+      expect(body.appliedMigrations).toEqual(["model-version:openai/gpt-5.3-codex->openai/gpt-5.4"])
+    })
+
+    test("writes entries in sorted order for stable diffs", () => {
+      const configPath = join(workdir, "oh-my-openagent.json")
+      const migrations = new Set([
+        "model-version:z->y",
+        "model-version:a->b",
+        "model-version:m->n",
+      ])
+
+      writeAppliedMigrations(configPath, migrations)
+
+      const body = JSON.parse(readFileSync(getSidecarPath(configPath), "utf-8"))
+      expect(body.appliedMigrations).toEqual([
+        "model-version:a->b",
+        "model-version:m->n",
+        "model-version:z->y",
+      ])
+    })
+
+    test("creates parent directories if they do not exist yet", () => {
+      const nested = join(workdir, "nested", "dir", "that", "does", "not", "exist")
+      const configPath = join(nested, "oh-my-openagent.json")
+      // Parent chain intentionally not created.
+
+      const ok = writeAppliedMigrations(configPath, new Set(["model-version:a->b"]))
+
+      expect(ok).toBe(true)
+      expect(existsSync(getSidecarPath(configPath))).toBe(true)
+    })
+
+    test("round-trips via readAppliedMigrations", () => {
+      const configPath = join(workdir, "oh-my-openagent.jsonc")
+      const original = new Set([
+        "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+        "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6",
+      ])
+
+      writeAppliedMigrations(configPath, original)
+      const roundTripped = readAppliedMigrations(configPath)
+
+      expect(roundTripped).toEqual(original)
+    })
+  })
+})
@@ -0,0 +1,92 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { log } from "../logger"
+import { writeFileAtomically } from "../write-file-atomically"
+
+/**
+ * Sidecar state file that tracks applied config migrations outside the user's
+ * config file.
+ *
+ * Why this exists (#3263): users who revert an auto-migrated value (e.g.
+ * `gpt-5.4` → `gpt-5.3-codex`) and then delete the `_migrations` field from
+ * their config would fall into an infinite migration loop — every startup
+ * re-applied the migration because there was no memory of the previous
+ * application. The sidecar remembers applied migrations even when the user
+ * scrubs the config, and only "resets" when the user explicitly deletes both
+ * the config and the sidecar.
+ *
+ * The sidecar lives next to the config file as
+ * `<configFileName>.migrations.json`. One sidecar per config file. The file
+ * format is a flat JSON object:
+ *
+ *     {
+ *       "appliedMigrations": [
+ *         "model-version:openai/gpt-5.3-codex->openai/gpt-5.4",
+ *         "model-version:anthropic/claude-opus-4-5->anthropic/claude-opus-4-6"
+ *       ]
+ *     }
+ */
+
+export interface MigrationsSidecar {
+  appliedMigrations: string[]
+}
+
+export function getSidecarPath(configPath: string): string {
+  return `${configPath}.migrations.json`
+}
+
+/**
+ * Read the set of applied migration keys from the sidecar next to
+ * `configPath`. Returns an empty set on any read or parse failure so the
+ * caller can still trust the return value and safely fall back to the
+ * config's `_migrations` field.
+ */
+export function readAppliedMigrations(configPath: string): Set<string> {
+  const sidecarPath = getSidecarPath(configPath)
+  try {
+    if (!fs.existsSync(sidecarPath)) {
+      return new Set()
+    }
+    const content = fs.readFileSync(sidecarPath, "utf-8")
+    const parsed = JSON.parse(content) as unknown
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed) &&
+      Array.isArray((parsed as MigrationsSidecar).appliedMigrations)
+    ) {
+      return new Set((parsed as MigrationsSidecar).appliedMigrations.filter((m): m is string => typeof m === "string"))
+    }
+    return new Set()
+  } catch (err) {
+    log(`[migration] Failed to read migrations sidecar at ${sidecarPath}`, err)
+    return new Set()
+  }
+}
+
+/**
+ * Persist the given set of applied migration keys to the sidecar next to
+ * `configPath`. The sidecar is written atomically. Returns true on success,
+ * false if the write failed (the caller can still proceed — the next
+ * startup will re-run the migration, which is idempotent by design).
+ */
+export function writeAppliedMigrations(configPath: string, migrations: Set<string>): boolean {
+  const sidecarPath = getSidecarPath(configPath)
+  const body: MigrationsSidecar = {
+    appliedMigrations: Array.from(migrations).sort(),
+  }
+  try {
+    // Ensure the parent directory exists in case the config file was created
+    // out-of-band. We intentionally do NOT create the sidecar when the migration
+    // set is empty — there is nothing to remember.
+    const parentDir = path.dirname(sidecarPath)
+    if (!fs.existsSync(parentDir)) {
+      fs.mkdirSync(parentDir, { recursive: true })
+    }
+    writeFileAtomically(sidecarPath, JSON.stringify(body, null, 2) + "\n")
+    return true
+  } catch (err) {
+    log(`[migration] Failed to write migrations sidecar at ${sidecarPath}`, err)
+    return false
+  }
+}