reference creatortrack worktree npm install symlink break 20260715T185918
name: CT warm-slot worktree: npm install breaks shared node_modules symlink description: Running npm install inside a CreatorTrack warm-slot worktree converts the shared node_modules symlink into a standalone ~1.5GB real directory, then stale-breaks the already-running dev server's module resolution type: reference
In a CreatorTrack warm-slot/worktree dev agent, running npm install (e.g. to add a new package like @huggingface/transformers) converts that worktree's shared node_modules symlink into a standalone real directory (~1.5GB), decoupling it from the other slots' shared install. Other slots (verified: slot-2, slot-3) are unaffected, only the slot where install ran.
Second-order effect: if a dev server was already running against that worktree before the install, it keeps cached stale module-resolution state after the symlink-to-real-dir swap, and starts throwing ENOENT ... node_modules/<new-package> even though the package is actually present on disk. The fix is not a partial restart or cache clear, it's killing the dev server and relaunching it exactly via the warm pool's own startup command in forge_creatortrack_agent_bootstrap.sh (a plain npm run dev or ad-hoc restart does not reliably clear this).
Why: Encountered live during Task 15 (retrieval/generation script build, 2026-07-15) when adding an embeddings dependency to a worktree already serving a running dev server. Cost real debugging time before the fix was found.
How to apply: Whenever a worktree/warm-slot dev agent runs npm install for a new dependency, expect the node_modules symlink to break for that slot only, and proactively kill+relaunch that slot's dev server via the bootstrap script rather than assuming a plain restart will pick up the new package. Related: [[reference_creatortrack_worktree_dev_turbopack_symlink]], [[reference_creatortrack_warm_slots]].
[auto-memory session 60d132de-4659-485c-8044-427af0ccce7f, confidence 0.72, mode staged]