fix(state-migrations): use generic conflict warning text

Bartok9 · Bartok9 · commit ceb21116323c · 2026-06-05T05:12:11.000-04:00
Per ClawSweeper review feedback [P3]: the previous text 'shared SQLite
state has newer metadata for' was misleading — conflicts can arise from
mismatched floating selectors, package renames, or malformed legacy spec
metadata, not necessarily because SQLite is newer. Use a generic conflict
description that accurately covers all conflict reasons.
diff --git a/src/commands/doctor-state-migrations.test.ts b/src/commands/doctor-state-migrations.test.ts
@@ -1,4 +1,3 @@
-// Doctor state migration tests cover legacy state moves, archive markers, and repair behavior.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -1511,18 +1510,35 @@ describe("doctor legacy state migrations", () => {
     current: InstalledPluginInstallRecordInfo;
     legacy: InstalledPluginInstallRecordInfo;
   }>) {
-    it(`keeps legacy plugin install index when same-version npm records ${fixture.label}`, async () => {
+    it(`archives legacy plugin install index and warns (once) when same-version npm records ${fixture.label}`, async () => {
       const root = await makeTempRoot();
       await writeExistingPluginInstallIndex(root, { demo: fixture.current });
       const sourcePath = writeLegacyPluginInstallIndex(root, { demo: fixture.legacy });
 
       const result = await runLegacyStateMigrationsForRoot(root);
 
+      // The conflict warning is emitted once, then the legacy file is archived so it
+      // cannot trigger the same warning on subsequent gateway startups (fixes #90213).
       expect(result.warnings).toStrictEqual([
-        "Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: demo",
+        "Archived plugin install index after detecting conflicting plugin install metadata for: demo",
       ]);
-      expect(fs.existsSync(sourcePath)).toBe(true);
-      expect(fs.existsSync(`${sourcePath}.migrated`)).toBe(false);
+      expect(fs.existsSync(sourcePath)).toBe(false);
+      expect(fs.existsSync(`${sourcePath}.migrated`)).toBe(true);
+    });
+
+    it(`does not re-emit plugin install conflict warning on subsequent runs when ${fixture.label}`, async () => {
+      const root = await makeTempRoot();
+      await writeExistingPluginInstallIndex(root, { demo: fixture.current });
+      const sourcePath = writeLegacyPluginInstallIndex(root, { demo: fixture.legacy });
+
+      // First run: archives the legacy file and emits the warning once.
+      const first = await runLegacyStateMigrationsForRoot(root);
+      expect(first.warnings).toHaveLength(1);
+      expect(fs.existsSync(sourcePath)).toBe(false);
+
+      // Second run: no legacy file exists, so migration is skipped entirely — no repeated warning.
+      const second = await runLegacyStateMigrationsForRoot(root);
+      expect(second.warnings).toHaveLength(0);
     });
   }
 
diff --git a/src/infra/state-migrations.ts b/src/infra/state-migrations.ts
@@ -1499,12 +1499,11 @@ async function migrateLegacyInstalledPluginIndex(params: {
       }
     }
     if (merged.conflicts.length > 0) {
-      return {
-        changes,
-        warnings: [
-          `Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: ${merged.conflicts.join(", ")}`,
-        ],
-      };
+      warnings.push(
+        `Archived plugin install index after detecting conflicting plugin install metadata for: ${merged.conflicts.join(", ")}`,
+      );
+      archiveLegacyInstalledPluginIndex({ sourcePath, changes, warnings });
+      return { changes, warnings };
     }
   }
 

Original file line number	Diff line number	Diff line change
`@@ -1499,12 +1499,11 @@ async function migrateLegacyInstalledPluginIndex(params: {`
`1499`	`1499`	`}`
`1500`	`1500`	`}`
`1501`	`1501`	`if (merged.conflicts.length > 0) {`
`1502`		`- return {`
`1503`		`- changes,`
`1504`		`- warnings: [`
`1505`		- `Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: ${merged.conflicts.join(", ")}`,
`1506`		`- ],`
`1507`		`- };`
	`1502`	`+ warnings.push(`
	`1503`	+ `Archived plugin install index after detecting conflicting plugin install metadata for: ${merged.conflicts.join(", ")}`,
	`1504`	`+ );`
	`1505`	`+ archiveLegacyInstalledPluginIndex({ sourcePath, changes, warnings });`
	`1506`	`+ return { changes, warnings };`
`1508`	`1507`	`}`
`1509`	`1508`	`}`
`1510`	`1509`