claude plugin update keeps a stale cache directory when the version number is unchanged

[kyle-sexton]

Summary

claude plugin update -y <plugin>@<marketplace> re-points the plugin's gitCommitSha in installed_plugins.json without rewriting its cache directory when the manifest version number is unchanged. The directory keeps the older build while the metadata claims the new commit.

Impact

After delivering main to the cache on 2026-09-02, six plugins reported the new sha while their cache directories still held files from an earlier commit (guardrails: 12 stale files including the reviewed dispatcher; the three Write formatters; source-control and disk-hygiene hooks.json). Any measurement or behaviour test against the cache is then a test of the wrong build, and the version-and-sha check every delivery script relies on is not proof.

Evidence

.work/hook-performance-levers/cache-compare.sh (untracked helper; byte-compares every hook, script and lib file in a cache directory against a git ref) found the six; removing the version directories and running the update again recreated them from the clone. Recorded in the hook-performance program's DEVIATIONS log.

Ask

Decide between: (a) a repo-side rule that every plugin change bumps the version (already the CHANGELOG-parity gate's rule, so this only bites when a branch is delivered without a bump), (b) promoting the file-level compare into the delivery helper or the claude-ops plugin-fleet audit as a standing check, (c) an upstream report if the updater is meant to rewrite on a sha change. (b) is the cheap durable fix.

[kyle-sexton]

Triage (operator-authorized): priority: medium, work-class: scoped, status: ready.

Decision: taking route (b), promoting the file-level cache compare into the claude-ops plugin-fleet audit as a standing check. Rationale: (a) already exists as the CHANGELOG-parity gate and only fails when a branch is delivered without a bump, so it cannot catch the case that motivated this issue; (c) is worth filing but does nothing for machines today, and the updater's behaviour on an unchanged version may be intentional. (b) is the cheap, durable, local detection: each install record already carries gitCommitSha and the marketplace's installLocation is a git checkout, so every cached file can be byte-compared against git show :plugins//. Will land as a fleet-state.sh companion script plus an audit/sync report section that names stale-content installs (version and sha claim one build, files hold another) and points at the remediation the issue already proved works (remove the version directory, update again).

[kyle-sexton]