fix: stop autoupdate from deleting the running session's bundle

[efenocchi]

Summary

Fixes Stop hook error: Plugin directory does not exist: /…/.claude/plugins/cache/hivemind/hivemind/<old-version> errors that appeared for every post-SessionStart hook (Stop, PostToolUse, SessionEnd) once an auto-update happened mid-session.

• Remove the destructive rmSync loop in src/hooks/session-start.ts that explicitly rm -rf'd every non-latest version directory from inside a running session (the actual source of the error — an empirical claude plugin update doesn't wipe adjacent versions on its own).
• Wrap the claude plugin update execSync in both session-start.ts and session-start-setup.ts with a PID-scoped snapshot → restore-or-cleanup dance, so the live session keeps finding its bundle paths even if Claude's installer wipes the versioned directory under some scope.
• Add a new SessionEnd hook plugin-cache-gc.ts that garbage-collects older version directories — keeps the current version plus the two next-newest (DEFAULT_KEEP_COUNT = 3, enough headroom for a session pinned through two further updates) and sweeps up stale .keep-<pid> snapshots from crashed SessionStart updates.
• Add a || true guard to each scope in session-start-setup.ts's update command so it stops spuriously logging autoupdate failed when a scope doesn't have hivemind installed.

Why it happens

At session start the hook registry bakes the resolved CLAUDE_PLUGIN_ROOT (e.g. …/hivemind/0.6.38/) into every hook command. When the sync SessionStart hook runs claude plugin update and then iterates the cache directory removing every non-latest version — the currently-executing version among them — later hooks in the same session (Stop, PostToolUse, SessionEnd) all fail with ENOENT on their bundle path. Cleanup now only happens in SessionEnd, by which time the session is gone.

Architecture

• src/utils/plugin-cache.ts (new): pure helpers — resolveVersionedPluginDir (dev-layout guard), snapshotPluginDir / restoreOrCleanup (PID-scoped backup/restore around the installer), readCurrentVersionFromManifest, planGc / executeGc (leaves non-semver entries and live-PID snapshots alone, bails if current version isn't on disk).
• src/hooks/plugin-cache-gc.ts (new): thin runGc(bundleDir, opts) orchestrator wired as an async SessionEnd hook (15s timeout) alongside the existing summary hook — separate hook to keep the concern isolated and to run even when HIVEMIND_CAPTURE=false disables the summary flow.
• Helpers are guarded so a local --plugin-dir dev run skips all snapshot/GC work and never touches a developer checkout.

Verification

• Full test suite: 46 files / 967 tests pass under --coverage.
• Coverage on the four touched files, ≥ 90 on every metric and locked in vitest.config.ts:
  • utils/plugin-cache.ts — stmts 93.45, branch 90.47, funcs 100, lines 96.66
  • hooks/plugin-cache-gc.ts — 100 / 100 / 100 / 100
  • hooks/session-start.ts — 98.82 / 90.47 / 100 / 98.76
  • hooks/session-start-setup.ts — 100 / 100 / 100 / 100
• Real claude -p --plugin-dir ./claude-code with claude-code/.claude-plugin/plugin.json manually lowered to 0.6.30 (to force the update path) — hook-debug.log shows both autoupdate paths firing with autoupdate snapshot outcome: noop (dev-layout guard correct) and autoupdate succeeded, no more cache cleanup: removed old version lines, and plugin-cache-gc skipping correctly.
• Subprocess integration test plugin-cache-gc-bundle.integration.test.ts runs the actual shipped plugin-cache-gc.js bundle against a fake HOME — validates keep-current-plus-two, preserves live-PID snapshots, bails without a manifest, and skips dev layouts.
• Empirical check: a ghost 0.6.40-ghost/ directory survived a no-op claude plugin update — confirms the installer doesn't wipe adjacent versions on its own, so the destructive rmSync loop was responsible for the errors observed in production. (A real version-bump install could still wipe the directory on its own; the snapshot/restore dance handles that case too.)

Known limitation

Accepted tradeoff: a session pinned to version X through three further updates can still lose its bundle. Reference-counting per version would close this; deferred as out of scope. N = 3 gives two updates of headroom, which covers every real-world scenario observed so far.

Test plan

• CI green (tests + coverage thresholds + PR coverage comment ≥ 90 on the four files).
• Smoke test in a real install: run any Claude session, trigger an auto-update by bumping the published version beyond the installed one, confirm no Plugin directory does not exist errors in subsequent hooks.
• Next SessionEnd cleans old versions down to 3 (observe in hook-debug.log: [plugin-cache-gc] gc kept=… deletedVersions=…).

[claude]

Claude finished @efenocchi's task in 7m 24s —— View job

---

Review findings

• restoreOrCleanup error swallowed silently (src/utils/plugin-cache.ts:96-97) — when renameSync throws after the installer deletes pluginDir, the function returns "noop" (same as the dev-layout path), so callers can't detect that the bundle dir is actually gone and the original ENOENT will resurface in subsequent hooks.
• Concurrent-session GC gap (src/utils/plugin-cache.ts:154-158) — isPidAlive protects .keep-<pid> snapshots but not version directories themselves; a second session running the same old version has its bundle deleted when the first session exits and GC fires.

[github-actions]

Coverage Report

Scope: files changed in this PR. Enforced threshold: 90% per metric (per file via vitest.config.ts).

Status	Category	Percentage	Covered / Total
🟢	Lines	98.31% (🎯 90%)	232 / 236
🟢	Statements	97.01% (🎯 90%)	260 / 268
🟢	Functions	100.00% (🎯 90%)	24 / 24
🟢	Branches	93.39% (🎯 90%)	113 / 121

File Coverage — 4 files changed

File	Stmts	Branches	Functions	Lines
src/hooks/plugin-cache-gc.ts	🟢 100.0%	🟢 100.0%	🟢 100.0%	🟢 100.0%
src/hooks/session-start-setup.ts	🟢 100.0%	🟢 100.0%	🟢 100.0%	🟢 100.0%
src/hooks/session-start.ts	🟢 98.8%	🟢 90.5%	🟢 100.0%	🟢 98.8%
src/utils/plugin-cache.ts	🟢 93.6%	🟢 90.5%	🟢 100.0%	🟢 96.7%

_{Generated for commit 2c92448.}

[claude]

When renameSync throws (e.g. EACCES, EXDEV), this catch returns "noop" — the same value as the dev-layout path at line 84 — so the caller cannot distinguish "not a versioned install" from "restore failed and pluginDir is still gone", silently reproducing the original ENOENT bug in all subsequent hooks.

Add a distinct return value or at minimum log before falling through, so the snapshot outcome is observable:

Suggested change

	} catch {
	return "noop";
	} catch (e: any) {
	// renameSync failed — pluginDir may still be absent; log and surface
	// as a distinct outcome so callers can detect the broken state.
	try { process.stderr.write(`[plugin-cache] restore failed: ${e?.message}\n`); } catch { /* ignore */ }
	return "noop";
	}

[efenocchi]

Fixed in 35d04cb. The catch now returns a distinct "restore-failed" outcome (new RestoreOutcome union) and writes a one-line diagnostic to stderr, so the existing log(\autoupdate snapshot outcome: ${outcome}`)` in both session-start hooks surfaces the real state instead of silently matching the dev-layout "noop" path.

Test rewritten to assert both the new return value and the stderr emission.

[claude]

isPidAlive only guards .keep-<pid> snapshot directories, not the version directories themselves. If two sessions start on the same old version and Session A exits first, GC deletes that version while Session B is still using it — the original ENOENT reappears for a concurrent session.

Consider checking whether any live .keep-<pid> snapshot references a version directory before deleting it (i.e., if <ver>.keep-<alivePid> exists for a version, don't delete <ver>):

Suggested change

	if (currentVersion && versions.includes(currentVersion)) {
	for (const v of versions) {
	if (!keep.has(v)) deleteVersions.push(v);
	}
	}
	const deleteVersions: string[] = [];
	if (currentVersion && versions.includes(currentVersion)) {
	const liveSnapshotVersions = new Set(
	snapshots.filter(s => { const m = s.match(KEEP_RE); return m && isAlive(Number(m[1])); })
	.map(s => s.replace(/\.keep-\d+$/, "")),
	);
	for (const v of versions) {
	if (!keep.has(v) && !liveSnapshotVersions.has(v)) deleteVersions.push(v);
	}
	}

[efenocchi]

Walking through the scenario with concrete numbers: with DEFAULT_KEEP_COUNT = 3, planGc always keeps [current, current-1, current-2]. Two sessions on the same old version — e.g. both on 0.6.40 while current = 0.6.41 — look like:

sorted desc = [0.6.41, 0.6.40, 0.6.39, 0.6.38]
keep         = {0.6.41, 0.6.40, 0.6.39}
deleteVersions = [0.6.38]   ← 0.6.40 is NOT here

So a single update between the two sessions doesn't fail — the previous version is always in the keep-list. The bug only triggers when the pinned version falls off the keep-list entirely, which needs three further updates during the session's lifetime. That case is already called out in the PR description under "Known limitation" as an accepted tradeoff.

The proposed .keep-<alivePid> guard also doesn't cover that case. Snapshots are only created inside the autoupdate branch of a session — see snapshotPluginDir call sites in session-start.ts:166 and session-start-setup.ts:79. A long-running session that stays on its version without updating never creates a snapshot pointing at itself, so liveSnapshotVersions never contains the version that actually needs protecting. The guard's set would be empty for exactly the version at risk.

The real fix would be per-session reference counting (<versionDir>/.sessions/<pid>, checked in planGc). That's ~40–50 lines of helper + plumbing + tests, and rough consensus with the author of this PR was to defer it given how rare the actual failure mode is (a single Claude session staying alive through three plugin releases). Not closing this thread silently — happy to revisit if you have a scenario that still repros under N=3.