[DOCS] [Plugins] `.in_use` PID lock files and the daily stale-marker sweep are not documented in the plugin reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

The "Plugin caching" / disk-layout area of the Plugins reference (and the Claude directory page section on ~/.claude/plugins/). The runtime behavior of per-plugin .in_use PID lock files and the daily sweep of stale markers from crashed sessions is not described.

Current Documentation

The Plugins reference only describes static plugin storage and update retention. The closest relevant passage in the Claude directory page is:

Affected Pages: | Page | Line(s) | Context | |------|---------|---------| | docs/code.claude.com/docs/en/claude-directory.md | 1453 | "Installed plugins — ~/.claude/plugins — Cloned marketplaces, installed plugin versions, and per-plugin data, managed by claude plugin commands. Orphaned versions are deleted 7 days after a plugin update or uninstall. See plugin caching." | | docs/code.claude.com/docs/en/claude-directory.md | 1519, 1532, 1535 | Sweep behavior for shell-snapshots/, legacy todos/, statsig/, logs/ directories | | docs/code.claude.com/docs/en/plugins-reference.md | (no PID/lock/sweep references) | Reference describes the plugin cache directory and 7-day orphan cleanup only |

The Plugins reference has no mention of .in_use files, per-plugin PID locks, lock acquisition, or any periodic cleanup. The Claude directory page lists per-plugin storage but does not document the .in_use files written inside ~/.claude/plugins/ or the daily sweep that prunes them.

What's Wrong or Missing?

A. .in_use PID lock files are not documented

The plugin runtime writes .in_use files (PID lock files) inside the plugin data area to mark a plugin as currently held by a running session. None of the documentation pages that describe ~/.claude/plugins/ or the plugin cache explain these files, where they live, or what writes/reads them.

B. Daily sweep of stale markers is not documented

When a session crashes, the .in_use marker it wrote is left behind. Starting with v2.1.169, the runtime sweeps these stale markers once per day. This daily-sweep behavior, its cadence, and which user-visible problems it addresses (e.g., "Why does my plugin cache have leftover .in_use files?") are not described anywhere in the plugin reference, the plugin caching notes, the Claude directory page, or the troubleshooting docs.

C. Operators have no way to reason about lock-file accumulation

Because the lock-file format, naming, and lifecycle are undocumented, users who see .in_use files accumulating in ~/.claude/plugins/ cannot tell whether they are healthy, stale, or actionable. The 7-day orphan cleanup described for plugin versions is a different mechanism and does not explain .in_use accumulation from a single crashed session over the course of one day.

Suggested Improvement

Add a short subsection to the Plugins reference under the plugin caching / disk layout area, and a corresponding row in the Claude directory page's plugin storage description. Suggested text (use blockquote format, not MDX components, in any rendered output):

Plugin .in_use lock files While a session has a plugin loaded, the plugin runtime writes an .in_use file inside that plugin's data directory under ~/.claude/plugins/. The file contains the running session's PID and acts as a per-plugin lock so that concurrent operations on the same plugin (install, update, uninstall) can see whether a session is still using it. The lock is released when the session exits normally. If a session crashes or is killed before the lock is released, the .in_use marker is left behind. To prevent these stale markers from accumulating indefinitely, the runtime runs a sweep once per day that removes .in_use files whose owning PID is no longer alive. Manual cleanup of .in_use files is not normally needed; if you see persistent .in_use files after a sweep has run, treat that as a bug and report it with the version from claude --version.

Add a matching row to the Claude directory page's ~/.claude/plugins/ description:

| ~/.claude/plugins/<plugin>/.in_use | Per-plugin PID lock file written while a session has the plugin loaded. Released on clean exit. A daily sweep removes stale markers whose owning PID is no longer running. |

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins-reference | (no PID/lock/sweep section) | Reference for plugin caching and disk layout |
| https://code.claude.com/docs/en/claude-directory | 1453, 1519–1535 | ~/.claude/plugins/ storage row and sweep coverage for other directories |
| https://code.claude.com/docs/en/plugin-marketplaces | 1016, 1024 | Mentions "stale clone" handling for marketplaces; not the same as per-plugin .in_use locks |
| https://code.claude.com/docs/en/plugin-dependencies | 97 | Discusses stale plugin.json version values during tag resolution; unrelated to .in_use |

Total scope: 2 primary pages affected (Plugins reference, Claude directory); 2 cross-references (Plugin marketplaces, Plugin dependencies) cover "stale" concepts in adjacent areas and would benefit from a brief link.

Version: The changelog entry that introduced the daily sweep is for v2.1.169. The lock-file format itself is older and is not documented in any version.

Related existing documentation: The Claude directory page already documents sweep behavior for shell-snapshots/, todos/, statsig/, logs/, and orphan-version cleanup for plugin cache directories. Adding the plugin .in_use row fits the existing table style and would not require a new structural section.