fix(state): retire superseded plugin install index

849261680 · 849261680 · commit eb31b1f2255f · 2026-06-05T15:02:27.000+08:00
diff --git a/src/commands/doctor-state-migrations.test.ts b/src/commands/doctor-state-migrations.test.ts
@@ -1408,6 +1408,83 @@ describe("doctor legacy state migrations", () => {
     });
   });
 
+  it("archives legacy plugin install index when current npm records supersede older records", async () => {
+    const root = await makeTempRoot();
+    await writeExistingPluginInstallIndex(root, {
+      codex: {
+        source: "npm",
+        spec: "@openclaw/codex",
+        installPath: "/state/npm/projects/openclaw-codex-current",
+        resolvedName: "@openclaw/codex",
+        resolvedVersion: "2026.6.1",
+        resolvedSpec: "@openclaw/codex@2026.6.1",
+        installedAt: "2026-06-01T21:04:35.000Z",
+      },
+      discord: {
+        source: "npm",
+        spec: "@openclaw/discord",
+        installPath: "/state/npm/projects/openclaw-discord-current",
+        resolvedName: "@openclaw/discord",
+        resolvedVersion: "2026.6.1",
+        resolvedSpec: "@openclaw/discord@2026.6.1",
+        installedAt: "2026-06-01T21:04:36.000Z",
+      },
+    });
+    const sourcePath = writeLegacyPluginInstallIndex(root, {
+      codex: {
+        source: "npm",
+        spec: "@openclaw/codex@2026.5.18",
+        version: "2026.5.18",
+      },
+      discord: {
+        source: "npm",
+        spec: "@openclaw/discord@2026.5.18",
+        version: "2026.5.18",
+      },
+    });
+
+    const result = await runLegacyStateMigrationsForRoot(root);
+
+    expect(result.warnings).toStrictEqual([]);
+    expect(fs.existsSync(sourcePath)).toBe(false);
+    expect(fs.existsSync(`${sourcePath}.migrated`)).toBe(true);
+    await expect(readPersistedInstalledPluginIndex({ stateDir: root })).resolves.toMatchObject({
+      installRecords: {
+        codex: { resolvedVersion: "2026.6.1" },
+        discord: { resolvedVersion: "2026.6.1" },
+      },
+    });
+  });
+
+  it("keeps legacy plugin install index when npm records would replace newer metadata", async () => {
+    const root = await makeTempRoot();
+    await writeExistingPluginInstallIndex(root, {
+      codex: {
+        source: "npm",
+        spec: "@openclaw/codex",
+        installPath: "/state/npm/projects/openclaw-codex-current",
+        resolvedName: "@openclaw/codex",
+        resolvedVersion: "2026.5.18",
+        resolvedSpec: "@openclaw/codex@2026.5.18",
+      },
+    });
+    const sourcePath = writeLegacyPluginInstallIndex(root, {
+      codex: {
+        source: "npm",
+        spec: "@openclaw/codex@2026.6.1",
+        version: "2026.6.1",
+      },
+    });
+
+    const result = await runLegacyStateMigrationsForRoot(root);
+
+    expect(result.warnings).toStrictEqual([
+      "Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: codex",
+    ]);
+    expect(fs.existsSync(sourcePath)).toBe(true);
+    expect(fs.existsSync(`${sourcePath}.migrated`)).toBe(false);
+  });
+
   for (const fixture of [
     {
       label: "name different packages",
diff --git a/src/infra/state-migrations.ts b/src/infra/state-migrations.ts
@@ -64,7 +64,9 @@ import {
   getNodeSqliteKysely,
 } from "./kysely-sync.js";
 import { requireNodeSqlite } from "./node-sqlite.js";
+import { compareOpenClawReleaseVersions, parseRegistryNpmSpec } from "./npm-registry-spec.js";
 import { isWithinDir } from "./path-safety.js";
+import { compareComparableSemver, parseComparableSemver } from "./semver-compare.js";
 import {
   ensureDir,
   existsDir,
@@ -403,13 +405,95 @@ function legacyInstallRecordHasCurrentResolvedIdentity(params: {
   return Boolean(legacyResolvedSpec && currentResolvedSpec === legacyResolvedSpec);
 }
 
+function readNpmInstallRecordPackageName(
+  record: InstalledPluginIndex["installRecords"][string],
+): string | undefined {
+  const resolvedName = readInstallRecordStringField(record, "resolvedName")?.trim();
+  if (resolvedName) {
+    return resolvedName;
+  }
+  for (const key of ["resolvedSpec", "spec"]) {
+    const spec = readInstallRecordStringField(record, key);
+    if (!spec) {
+      continue;
+    }
+    const parsed = parseRegistryNpmSpec(spec);
+    if (parsed?.name) {
+      return parsed.name;
+    }
+  }
+  return undefined;
+}
+
+function readNpmInstallRecordVersion(
+  record: InstalledPluginIndex["installRecords"][string],
+): string | undefined {
+  const resolvedVersion = readInstallRecordStringField(record, "resolvedVersion")?.trim();
+  if (resolvedVersion) {
+    return resolvedVersion;
+  }
+  const version = readInstallRecordStringField(record, "version")?.trim();
+  if (version) {
+    return version;
+  }
+  for (const key of ["resolvedSpec", "spec"]) {
+    const spec = readInstallRecordStringField(record, key);
+    const parsed = spec ? parseRegistryNpmSpec(spec) : null;
+    if (parsed?.selectorKind === "exact-version" && parsed.selector) {
+      return parsed.selector;
+    }
+  }
+  return undefined;
+}
+
+function compareInstallRecordVersions(
+  currentVersion: string,
+  legacyVersion: string,
+): number | null {
+  const openClawVersionComparison = compareOpenClawReleaseVersions(currentVersion, legacyVersion);
+  if (openClawVersionComparison !== null) {
+    return openClawVersionComparison;
+  }
+  return compareComparableSemver(
+    parseComparableSemver(currentVersion, { normalizeLegacyDotBeta: true }),
+    parseComparableSemver(legacyVersion, { normalizeLegacyDotBeta: true }),
+  );
+}
+
+function legacyNpmInstallRecordSupersededByCurrent(params: {
+  currentRecord: InstalledPluginIndex["installRecords"][string];
+  legacyRecord: InstalledPluginIndex["installRecords"][string];
+}): boolean {
+  const { currentRecord, legacyRecord } = params;
+  if (currentRecord.source !== "npm" || legacyRecord.source !== "npm") {
+    return false;
+  }
+  const currentPackageName = readNpmInstallRecordPackageName(currentRecord);
+  const legacyPackageName = readNpmInstallRecordPackageName(legacyRecord);
+  if (!currentPackageName || currentPackageName !== legacyPackageName) {
+    return false;
+  }
+  if (!readInstallRecordStringField(currentRecord, "installPath")) {
+    return false;
+  }
+  const currentVersion = readNpmInstallRecordVersion(currentRecord);
+  const legacyVersion = readNpmInstallRecordVersion(legacyRecord);
+  if (!currentVersion || !legacyVersion) {
+    return false;
+  }
+  return compareInstallRecordVersions(currentVersion, legacyVersion) === 1;
+}
+
 function legacyInstallRecordCoveredByCurrent(
   currentRecord: InstalledPluginIndex["installRecords"][string],
   legacyRecord: InstalledPluginIndex["installRecords"][string],
 ): boolean {
   if (currentRecord.source !== legacyRecord.source) {
     return false;
   }
+  if (legacyNpmInstallRecordSupersededByCurrent({ currentRecord, legacyRecord })) {
+    return true;
+  }
   for (const key of Object.keys(legacyRecord).toSorted()) {
     const currentValue = readInstallRecordField(currentRecord, key);
     if (currentValue === readInstallRecordField(legacyRecord, key)) {
