Summary

• Problem: legacy plugins/installs.json can keep producing migration warnings after openclaw doctor --fix when shared SQLite already has the authoritative resolved npm artifact metadata, but broad archival would hide real install metadata drift.
• Solution: archive the legacy JSON only when the current SQLite npm record proves it supersedes the legacy record: same package name, same resolved version, exact resolved spec, and registry artifact metadata such as integrity or shasum.
• What changed: kept the installed-plugin-index migration predicate narrow in src/infra/state-migrations.ts, preserved unresolved conflicts, and updated src/commands/doctor-state-migrations.test.ts for both the safe archival and true-conflict paths.
• Latest main sync: rebased to 272eafb9a707e417a1e9c7b26a91fae80cc7aaa0 and resolved the conflict by preserving current main's state-schema / exec-approvals migration imports plus this PR's npm-spec predicate.

Fixes #90213

Maintainer-ready notes

• Fix classification: Root cause fix.
• Maintainer-ready confidence: High for the source-runtime behavior exercised here; medium for packaged upgrade confidence because packaged v2026.6.1 and PiClaw upgrade runs are intentionally not claimed.
• Root cause: migrateLegacyInstalledPluginIndex treated all legacy/current install-record conflicts as the same conflict class, so a stale legacy npm record for the same resolved artifact could not reach the existing archive path without also archiving true metadata drift.
• Why it matters / User impact: Users who already have authoritative shared SQLite install metadata can keep seeing repeated doctor/startup migration warnings from a stale legacy plugins/installs.json, which makes real migration conflicts harder to notice.
• What did NOT change: This PR only changes the conflict predicate for legacy plugin install-index migration and only for npm records with same package identity, same resolved version, exact resolved spec, and registry artifact metadata. It does not change plugin activation, provider traffic, config loading, channel delivery, older-version supersession, broad conflict auto-resolution, packaged upgrade behavior, PiClaw behavior, or unrelated state migrations.
• Architecture / source-of-truth check: Shared SQLite remains the canonical installed-plugin index only when it proves the same resolved npm artifact through the migration-owned install-index predicate. The legacy JSON remains in place whenever package/spec/version identity is ambiguous, so the migration source of truth does not become a downstream warning suppressor.
• Related open PR scan: PR fix(state): retire superseded plugin install index #90474 covers older-version supersession. This PR intentionally keeps that predicate out of scope so maintainers can land the smaller same-version artifact fix separately or consolidate both policies explicitly.
• Out of scope: Older-version supersession, broad conflict auto-resolution, packaged upgrade proof, PiClaw proof, real plugin activation, external provider/model traffic, and non-Linux behavior.
• Patch quality notes: The added return false paths are deliberate guardrails for incomplete npm identity evidence: non-npm records, missing legacy spec/version, missing current resolved package/version, version mismatch, missing artifact integrity/shasum, or unparseable/different package specs all stay on the existing conflict-warning path.
• Why this is root-cause fix: The repeated warning was caused by a migration predicate that could not distinguish safe resolved npm artifact supersession from true metadata drift. This patch fixes that source predicate in the state migration owner instead of suppressing warnings, deleting the legacy file unconditionally, or adding a downstream fallback.
• Why this is the smallest reliable guardrail: The focused migration suite locks both sides of the invariant in the same doctor migration entrypoint: same-version resolved npm artifact metadata archives the stale legacy file, while unresolved package/spec drift stays visible and unarchived.

Merge risk

• Risk labels considered: compatibility; session-state.
• Risk explanation: This touches persisted upgrade/migration behavior for plugin install metadata, so the risk is accidentally archiving a legacy install index that still carries meaningful conflict information.
• Why acceptable: Archival is allowed only when SQLite proves the same npm artifact through package name, resolved version, exact resolved spec, and registry artifact metadata. All incomplete, non-npm, unparseable, package-mismatch, or selector-drift cases continue returning false and preserving the legacy file with the existing warning.

Real behavior proof

• Behavior or issue addressed: Repeated legacy plugin install-index migration warnings when plugins/installs.json disagrees with shared SQLite metadata that already has resolved npm artifact identity, while preserving warnings for unresolved metadata drift.

• Real environment tested: Local Linux checkout at 272eafb9a707e417a1e9c7b26a91fae80cc7aaa0, running the production legacy state migration entrypoint and shared SQLite installed-plugin index persistence with isolated temporary OPENCLAW_STATE_DIR and HOME fixtures.

• Exact steps or command run after this patch:

  set -o pipefail; PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false corepack pnpm@11.2.2 --dir "$TASK_WORKTREE" exec tsx "$EVIDENCE_DIR/latest-head-plugin-index-proof.ts" 2>&1 | tee "$EVIDENCE_DIR/latest-head-plugin-index-proof.log"
  set -o pipefail; PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false corepack pnpm@11.2.2 --dir "$TASK_WORKTREE" exec vitest run --config test/vitest/vitest.commands.config.ts src/commands/doctor-state-migrations.test.ts --hookTimeout 300000 --testTimeout 300000 2>&1 | tee "$EVIDENCE_DIR/latest-head-focused-vitest.log"

• Evidence after fix:

  {
    "head": "272eafb9a707e417a1e9c7b26a91fae80cc7aaa0",
    "proofScope": "production legacy state migration entrypoint plus shared SQLite installed-plugin index persistence using temporary local OPENCLAW_STATE_DIR fixtures",
    "safeArtifact": {
      "firstWarnings": [],
      "firstChanges": [
        "Archived plugin install index legacy source → /tmp/openclaw-90267-safe-artifact-W8zF3j/plugins/installs.json.migrated"
      ],
      "sourceExistsAfterFirst": false,
      "archiveExistsAfterFirst": true,
      "secondWarnings": [],
      "secondChanges": [],
      "canonicalSpecs": {
        "brave": "brave@latest",
        "lobster": "lobster@latest"
      }
    },
    "unresolvedConflict": {
      "firstWarnings": [
        "Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: demo"
      ],
      "firstChanges": [],
      "sourceExistsAfterFirst": true,
      "archiveExistsAfterFirst": false,
      "secondWarnings": [
        "Left plugin install index in place because shared SQLite state has conflicting plugin install metadata for: demo"
      ],
      "secondChanges": [],
      "canonicalSpecs": {
        "demo": "demo@latest"
      }
    }
  }

  RUN  v4.1.7 /media/vdc/code/ai/aispace/openclaw-worktrees/pr-90267
  
  Test Files  1 passed (1)
       Tests  62 passed (62)
    Duration  112.53s (transform 1.65s, setup 392ms, import 3.22s, tests 108.63s, environment 0ms)
  

• Observed result after fix: SQLite-canonical npm records with exact resolved artifact metadata archive plugins/installs.json on the first migration and the second migration run is quiet; unresolved package/spec drift keeps the legacy source in place and continues surfacing the existing warning.

• What was not tested: No packaged v2026.6.1 upgrade, PiClaw upgrade, globally installed npm package, real Brave/Lobster plugin activation, external Brave Search API calls, LM Studio, provider/model traffic, or non-Linux environment was exercised.

Review findings addressed

• RF-001: Source-runtime proof is refreshed at latest head and the packaged-upgrade gap is explicitly disclosed for maintainer judgment.
• RF-002: The shipped migration behavior change remains narrowly bounded to same-package, same-version npm artifact identity with registry artifact metadata; unresolved conflicts are preserved.
• RF-003: The proof still does not claim packaged v2026.6.1 or PiClaw upgrade coverage; that is listed under “What was not tested.”
• RF-004: Related PR fix(state): retire superseded plugin install index #90474 covers older-version supersession. This PR intentionally does not absorb that predicate and can land separately unless maintainers prefer consolidation.
• RF-005: No broader automated code repair is included beyond the narrow migration predicate and conflict-preservation tests; the remaining decision is maintainer compatibility judgment.

Regression Test Plan

• Coverage level: state migration unit/integration coverage plus real source-runtime proof with temporary state directories.
• Target test file: src/commands/doctor-state-migrations.test.ts.
• Scenario locked in: resolved npm artifact metadata archives legacy plugins/installs.json and a follow-up migration run is quiet; unresolved package/spec drift remains warning-visible and unarchived.
• Diff scope after latest main sync: only src/infra/state-migrations.ts and src/commands/doctor-state-migrations.test.ts changed.

Compatibility and related PRs

• Related PR fix(state): retire superseded plugin install index #90474 covers a different migration shape: older legacy npm install records superseded by newer current SQLite records.
• This PR intentionally stays narrower and covers only same-version npm records where the current SQLite entry has exact resolved artifact metadata for the same package/version.
• The two predicates are independent: this PR does not archive older-version supersession without artifact equality, and unresolved selector/package/spec drift remains on the existing warning path.
• Suggested merge policy: land separately if maintainers want the smallest safe fix for [Bug]: After updating to OpenClaw 2026.6.1, legacy state migration warnings keep appearing even after running openclaw doctor --fix. #90213 first; consolidate only if maintainers prefer one combined migration-policy PR for both [Bug]: After updating to OpenClaw 2026.6.1, legacy state migration warnings keep appearing even after running openclaw doctor --fix. #90213 and [Bug]: Upgrade leaves repeated shared SQLite plugin install metadata conflict warnings for codex/discord #90418.

Root Cause

• Root cause: migrateLegacyInstalledPluginIndex treated all legacy/current install-record conflicts the same, so safe superseded npm artifact records could not reach the existing archive step without also broadening archival for true conflicts.
• Missing detection / guardrail: the old regression coverage did not distinguish proven-safe resolved artifact metadata from unresolved install metadata drift.