[plan-16] Canonical Install Identity & Bundle Integrity — one resolvable, dependency-complete plugin root, and recycles that cannot kill a working worker

[thedotmack]

[plan-16] Canonical Install Identity & Bundle Integrity — one resolvable, dependency-complete plugin root, and recycles that cannot kill a working worker

Tracker: #3604 · Design doc: plans/16-canonical-install-identity-and-bundle-integrity.md · Series: plan-14 #3602 · plan-15 #3603 · plan-16 #3604 · plan-17 #3605 · plan-18 #3606 · plan-19 #3607 · plan-20 #3608 · plan-21 #3609 · plan-22 #3610 · plan-23 #3611

Defect

There is no single answer to "which copy of claude-mem is installed and runnable". Hooks, the supervisor's successor spawn, npx claude-mem (install/repair/doctor/status), the SDK subprocess, and the marketplace auto-updater each resolve the plugin root independently, and none of them verifies the copy has its runtime dependencies:

• The hook prelude picks the newest mtime under ~/.claude/plugins/cache/thedotmack/claude-mem/[0-9]*/ (ls -dt … | head -1), accepts 1-byte gutted stubs and .orphaned_at dirs, and falls back to ~/.claude/plugins/marketplaces/thedotmack/plugin/ — a checkout that never has node_modules. resolveWorkerScriptPath()/resolveSuccessorScript() repeat the same mtime sort in code (fixed on the hook side by fix(worker): single version oracle — never rank plugin cache dirs by mtime (restart-storm fix) #3371 in 13.12.x; still present in successor resolution per Stale-version recycle loop leaks chroma-mcp processes (759 procs / ~71 GB RSS) until the machine OOMs #3216/Version-mismatch recycle respawns the worker from marketplaces/…/plugin/, which never has node_modules — guaranteed respawn failure, then UserPromptSubmit blocks every prompt #3565).
• worker-service.cjs externalizes zod, shell-quote, tree-sitter-*, ajv*, better-auth, and (13.9.x) ../sqlite/{SessionStore,observations/files}.js; the bundle requires modules the build never emits and a node_modules the plugin update / marketplace pull never installs (Cannot find module 'zod/v3', Cannot find module '../sqlite/observations/files.js'). tree-sitter-cli's binary is fetched by an install script suppressed by --ignore-scripts; the Windows resolver checks an extensionless path; grammars declare conflicting tree-sitter peer majors (ERESOLVE); npm 12 rejects the --allow-scripts CLI flag the installer passes.
• The version-mismatch recycle compares the marketplace manifest version to the worker's /api/health version and kills the incumbent before a successor exists, then lazy-spawns from whichever path the resolver returns — often the marketplace copy or an older cache dir — and waits for a plugin-version match a fresh worker can never report when the manifest is stale. Result: unbounded recycle loops (86–449/hour) that feed plan-14's leak and plan-15's ghost ports, and a healthy worker replaced by a guaranteed-to-fail one.
• doctor checks marketplace node_modules, repair installs into the version cache, status reports "not installed" beside a healthy worker; .orphaned_at is honored by hook shells but not by the running daemon; stale cache versions are never GC'd; the marketplace has no root .claude-plugin/marketplace.json.
• The shipped bundle set is not audited: DEP0190 (args + shell:true) survives in dist/npx-cli, shell-quote and sync-hub transitive deps carry known CVEs, an agent-directive template ships in plugin/modes/, and Windows CI is red for reasons unrelated to the PR under test.

Children

• worker-service.cjs has external zod requires — breaks when node_modules missing #2831 — worker-service.cjs has external zod requires — breaks when node_modules missing
• v13.5.6: smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install - tree-sitter-cli binary never downloaded (--ignore-scripts), #1247's extensionless existsSync check still unfixed #2910 — smart_search/smart_outline/smart_unfold return 0 symbols on clean Windows install — tree-sitter-cli binary never downloaded (--ignore-scripts), extensionless existsSync
• Shared Windows CI noise #2922 — Shared Windows CI noise (tree-sitter-css node-gyp on hosted runner)
• DEP0190 still reproducible on 13.6.1 (regression of #1503 / #438 / #433): args + shell in the npx-cli bundle #2941 — DEP0190 still reproducible on 13.6.1: args + shell in the npx-cli bundle
• shell-quote 1.8.3 has CVE-2026-9277 — recommend upgrade #2952 — shell-quote 1.8.3 has CVE-2026-9277 — recommend upgrade
• tracking: plugin runtime deps missing in distributed bundles — zod external, tree-sitter-cli not downloaded, hooks crash #2964 — tracking: plugin runtime deps missing in distributed bundles — zod external, tree-sitter-cli not downloaded, hooks crash
• tracking: shared Windows CI noise — tree-sitter-css node-gyp rebuild fails on GitHub hosted runner (no MSVC) #2974 — tracking: shared Windows CI noise — tree-sitter-css node-gyp rebuild fails on GitHub hosted runner
• marketplace.json location not compatible with Claude Code plugin discovery #3004 — marketplace.json location not compatible with Claude Code plugin discovery
• ERESOLVE peer-dependency conflict: tree-sitter version mismatch on install #3035 — ERESOLVE peer-dependency conflict: tree-sitter version mismatch on install
• Add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle (testability/operability) #3054 — Add CLAUDE_MEM_WORKER_SCRIPT_PATH to pin the worker bundle
• SettingsDefaultsManager loadFromFile tests fail on a dev machine running claude-mem (ambient CLAUDE_MEM_* env leaks into expectations) #3056 — SettingsDefaultsManager loadFromFile tests fail on a dev machine running claude-mem (ambient env leaks)
• Native tree-sitter grammars (smart-explore) fail under bun on Windows - worker is always launched with bun, whose Node-API is incomplete #3072 — Native tree-sitter grammars fail under bun on Windows — worker always launched with bun, whose Node-API is incomplete
• v13.9.1: observation → Chroma vector sync fails on every observation (summaries/prompts unaffected) #3091 — v13.9.1: observation → Chroma vector sync fails on every observation (missing ../sqlite/observations/files.js)
• [Windows] 版本不匹配时 worker 自杀 + 端口 zombie 连锁故障（13.9.x） #3100 — [Windows] version-mismatch worker self-kill + port zombie chain (13.9.x)
• Chroma vector sync broken on 13.9.x: worker-service.cjs requires ../sqlite/*.js which the build never emits #3107 — Chroma vector sync broken on 13.9.x: worker-service.cjs requires ../sqlite/*.js which the build never emits
• doctor's required 'Marketplace deps' check cannot be cured by its own hint — repair installs only to the version cache #3117 — doctor's required 'Marketplace deps' check cannot be cured by its own hint — repair installs only to the version cache
• Backfill crashes on missing module '../sqlite/observations/files.js'; search query param ignored (v13.10.0, v13.9.3) #3126 — Backfill crashes on missing module '../sqlite/observations/files.js'; search query param ignored
• Linux: worker path resolves to different on-disk copies across invocation contexts (marketplace checkout vs version cache) → two concurrent daemons, one unsupervised orphan; stale cache versions never GC'd #3134 — Linux: worker path resolves to different on-disk copies across invocation contexts → two concurrent daemons; stale cache versions never GC'd
• smart_search/smart_outline broken for all languages — tree-sitter-cli binary never installed (side effect of --ignore-scripts fix for v12.6.2 hang) #3152 — smart_search/smart_outline broken for all languages — tree-sitter-cli binary never installed
• hooks.json plugin-root resolution can select a gutted stub or fall back to the marketplace copy during an auto-update window (zombie workers) #3155 — hooks.json plugin-root resolution can select a gutted stub or fall back to the marketplace copy during an auto-update window
• new install claude-mem @ 13.11.0 raise bug for "allowScripts" #3253 — new install claude-mem @ 13.11.0 raises "allowScripts" error
• CI: 'typecheck · build · test · bundle-size' job flakes with mass HealthMonitor/ProcessManager mock failures (order-dependent), plus CORS port-collision flake #3392 — CI: 'typecheck · build · test · bundle-size' job flakes (order-dependent mocks, CORS port collision)
• Fresh install broken: marketplace cache-miss on load, then subscription-auth fails for worker compression spawn #3424 — Fresh install broken: marketplace cache-miss on load, then subscription-auth fails for worker compression spawn
• Suggestion: make the 'no agent directives in shipped files' rule structural — law-study-CLAUDE.md still ships (inert today) #3438 — Make the 'no agent directives in shipped files' rule structural — law-study-CLAUDE.md still ships
• .orphaned_at is a hook-only filter — running daemon and chroma-mcp keep going, defeating the manual disable path (v13.12.4) #3456 — .orphaned_at is a hook-only filter — running daemon and chroma-mcp keep going, defeating the manual disable path
• osv-scanner: 2 High-severity transitive vulnerabilities in workers/sync-hub/bun.lock (brace-expansion, sharp) #3478 — osv-scanner: 2 High-severity transitive vulnerabilities in workers/sync-hub/bun.lock
• # Bug: observations never compress (stuck at 0) despite heavy PostToolUse/Stop activity; doctor/status report "not installed" right after a successful install #3534 — observations never compress; doctor/status report "not installed" right after a successful install
• Bug: plugin update does not install declared dependencies — worker fails with Cannot find module 'zod/v3' #3545 — plugin update does not install declared dependencies — worker fails with Cannot find module 'zod/v3'
• Version-mismatch recycle respawns the worker from marketplaces/…/plugin/, which never has node_modules — guaranteed respawn failure, then UserPromptSubmit blocks every prompt #3565 — Version-mismatch recycle respawns the worker from marketplaces/…/plugin/, which never has node_modules — guaranteed respawn failure

Related PRs to evaluate/rebase: #3371 (semver resolver, merged), #3095 (tree-sitter runtime provisioning, community-edge only), #3146 (inline parseFileList), #2887 (bundle zod, community-edge only), #3055 (CLAUDE_MEM_WORKER_SCRIPT_PATH), #2918, #2710, #2597, #2531, #3066, #2945, #2598, #1677, #2699.

Fix sequence

1. One resolver, three consumers. resolvePluginRoot() (shared TS, compiled into the hook prelude via hook-shell-template.ts, worker-utils.ts, and npx-cli) returns the highest semver cache dir that (a) has a worker-service.cjs above a size floor, (b) has no .orphaned_at, (c) has node_modules/zod/v3 (or whatever the bundle's external manifest lists), honoring CLAUDE_MEM_WORKER_SCRIPT_PATH first. The marketplace checkout is never a spawn target. installed_plugins.json installPath is preferred when present.
2. Bundle owes nothing to the filesystem it can't see. Inline every pure-JS external (zod, shell-quote, ajv, sqlite/observations/files); ship plugin/sqlite/ for anything that must stay external; add a build-time guard that scans plugin/scripts/*.cjs for require("../…")/external ids and fails unless the target is in the tarball. npm pack --dry-run diff is asserted in CI.
3. Dependencies materialize with the copy. Plugin update / first hook / repair run bun install --production (or vendored node_modules) inside the version dir with an .install-version marker written after success; tree-sitter-cli binary is fetched by an explicit non-lifecycle step with .exe resolution on Windows; grammars aligned to one tree-sitter major or moved behind an optional step; allowScripts declared in package.json/.npmrc, never as a CLI flag. New version dirs are published atomically (temp + rename).
4. Recycle only into a proven successor. Version comparison is semver-strict-newer against the resolved installed root, not the marketplace manifest; the successor is spawned first on a probe port, must answer /api/health with its own token, then the incumbent is asked to hand off (plan-15 handoff); failure keeps the incumbent and opens a per-boot circuit breaker (max 3 recycles/hour, logged). .orphaned_at is checked by the daemon at boot and each supervisor tick → graceful shutdown.
5. doctor / status / repair agree. All three use resolvePluginRoot(); doctor reports the resolved root, its version, and its dependency completeness; repair fixes that root; "not installed" is only reported when the resolver returns nothing. Marketplace registration writes .claude-plugin/marketplace.json at the root the host discovers.
6. GC and audit. On successful upgrade, remove cache dirs older than the previous version (keep N=2); CI runs osv-scanner on all lockfiles, check-spawn-env-discipline.cjs against dist/ (DEP0190), and a packaging lint that fails on tracked *CLAUDE.md outside an allowlist. Windows CI pinned to a runner with a working toolchain (or native grammar build skipped) so it is trustworthy; the flaky mock/port tests (CI: 'typecheck · build · test · bundle-size' job flakes with mass HealthMonitor/ProcessManager mock failures (order-dependent), plus CORS port-collision flake #3392, SettingsDefaultsManager loadFromFile tests fail on a dev machine running claude-mem (ambient CLAUDE_MEM_* env leaks into expectations) #3056) are isolated so the matrix can be gated on green.

Test matrix

Host	Install path	Scenario	Required behavior
macOS / Linux / Windows	marketplace	claude plugin update N → N+1 mid-session	hooks resolve N+1 only after its deps exist; incumbent N keeps serving until successor healthy; zero recycles logged after handoff
all	marketplace	manifest version ≠ cache version (stale manifest)	no recycle; doctor explains the skew
all	marketplace	cache dir with .orphaned_at / 1-byte stub / no node_modules	never selected; daemon from an orphaned dir shuts itself down
all	npx claude-mem install (npm 10/11/12, Node 20/22/24/26)	fresh install	exit 0; doctor green; smart_search returns symbols on a .ts file
Windows	Bun worker	tree-sitter grammars	either load under Node or degrade per-language with a WARN, never 0 symbols silently
all	tarball	npm pack	every require() target in plugin/scripts/*.cjs resolves inside the tarball
all	repo	CI	osv-scanner clean, DEP0190 lint clean, packaging lint clean, Windows job green on an empty PR

The matrix lives in CI (tests/infrastructure/plugin-distribution.test.ts, a fresh-install Docker job per Node/npm version, and the Windows job). A regression must fail CI before a user can file.

Out of scope

What happens to children of the killed incumbent (plan-14) and how the port is handed over/reclaimed (plan-15). Hook shell prelude cost and fail-open semantics (plan-17).