Plugin manager: `.orphaned_at` flag has no garbage collector

Plugin manager: .orphaned_at flag has no garbage collector

Summary

Plugin version directories in ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ accumulate .orphaned_at flag files but are never automatically pruned. Orphaned versions persist on disk indefinitely, holding stale agent definitions, stale .in_use/<pid> lock files, and stale MCP configurations that can be re-loaded if any external tooling or shell script targets them by path.

Reproduction

# Install plugin A v1.0.0 — directory created at:
#   ~/.claude/plugins/cache/<marketplace>/<plugin>/1.0.0/
# Upgrade to v2.0.0 — plugin manager creates:
#   ~/.claude/plugins/cache/<marketplace>/<plugin>/2.0.0/
# Plugin manager flags v1.0.0 as orphaned by writing:
#   ~/.claude/plugins/cache/<marketplace>/<plugin>/1.0.0/.orphaned_at
# Wait N days. The 1.0.0/ directory is never deleted.

Confirmed locally on 2026-05-13:

• chrome-devtools-mcp/0.22.0/.orphaned_at = 1778282953517 (2026-05-04). Still present 9 days later until manually removed.
• A similar orphan-then-resurrect cycle on accessibility-agents/4.0.0/.orphaned_at = 1777980116068 led to a legacy shell-script updater picking the older v3.2.0 directory alphabetically and keeping its 80-agent content hot. The result was a "Large cumulative agent descriptions will impact performance (~15.5k tokens > 15.0k)" warning at session start that persisted across restarts until the user manually intervened.

Impact

• Disk: orphan directories contain node_modules, full plugin assets, and (for plugins under active development) frequently a 0.x.y and a hashed-commit directory simultaneously — easily hundreds of MB per plugin over a year.
• Operational: any tooling that walks ~/.claude/plugins/cache/<marketplace>/<plugin>/*/ (linters, sync scripts, the user's own automation) can pick an orphaned directory and treat it as authoritative.
• Trust: an orphaned version with a stale .in_use/<pid> from a long-dead process can mislead diagnostics; the user assumes the plugin manager has the directory live when it doesn't.

Proposed fix

Add a configurable TTL on the .orphaned_at flag. Default: 14 days.

Implementation sketch:

1. On every plugin-manager cache touch (install, update, list, orphan-flag), opportunistically scan sibling versions of the affected plugin.
2. For each sibling with .orphaned_at mtime > TTL, and no live PIDs in .in_use/, rm -rf the version directory.
3. Surface the cleanup in the plugin manager's log/output: "Removed orphaned plugin version <plugin>@<version> after N days."
4. Allow opt-out via setting (e.g. pluginCache.orphanTTLDays: -1 to disable).

Alternative: a /plugin gc command users can run on demand. Less safe (relies on user action) but trivial to ship.

Acceptance

• A plugin upgraded to a new version with .orphaned_at set 14+ days ago has its old version directory automatically removed by the plugin manager on next interaction.
• Disabled via setting works without error.
• Garbage collection skips orphaned versions whose .in_use/ still contains a live PID (defensive — should be rare given Issue #02 in this series, but right behavior nonetheless).

See also

• Companion issue: .in_use/<pid> lock files leak stale PIDs — #58881
• Companion issue: plugin major-version updates that change agent count drastically should expose a post-update migration hook — #58882