fix: judge nested node_modules symlinks, and correct the escape advice

`worktree:link` plants a symlink per workspace that carries its own tree,
eight in today's layout, and every escape-path remedy in this PR said `rm
node_modules`, singular. Following that advice removes the root link, leaves
seven live links into the primary, and the next install writes through the
nested ones, the same corruption one level down. The gate had the same blind
spot: it judged only the target's root node_modules, so with a real root tree
and a nested symlink still standing, `npm install` was allowed.

The hook now finds a nested node_modules symlink under the target and the git
toplevel (find without -L neither follows nor descends symlinks, and real
node_modules trees are pruned, so it is a handful of directory reads), and
every advice site names the plural remedy:

  find . -maxdepth 4 -type l -name node_modules -delete

Sites corrected: the hook message, the link script docblock, the preinstall
reporter, the doctor reinstall remedy, and AGENTS.md.

Author: vivek7405

.claude/hooks/block-install-in-linked-worktree.sh

@@ -254,23 +254,40 @@ EOF
 [ -d "$target" ] || exit 0
 
 # The install lands at the package root, which for a subdirectory is the
-# enclosing checkout, so judge the git toplevel too.
+# enclosing checkout, so judge the git toplevel too. And judge NESTED
+# node_modules symlinks, not only the root: `npm run worktree:link` plants one
+# per workspace that carries its own tree (packages/server, website, ...), so a
+# worktree whose root link was removed for a real install still holds seven live
+# links into the primary, and an install writes through the nested ones the same
+# way. This was the gate's blind spot in exactly the escape path its own message
+# recommends.
+#
+# find without -L neither follows nor descends symlinks, and the prune keeps it
+# out of real node_modules trees, so this is a handful of directory reads.
 top=$(git -C "$target" rev-parse --show-toplevel 2>/dev/null || true)
 for dir in "$target" "$top"; do
   [ -n "$dir" ] || continue
-  [ -L "$dir/node_modules" ] || continue
-  owner=$(cd "$dir" 2>/dev/null && cd "$(readlink node_modules)" 2>/dev/null && pwd -P) || owner="the checkout it points at"
+  hit=""
+  if [ -L "$dir/node_modules" ]; then
+    hit="$dir/node_modules"
+  else
+    hit=$(find "$dir" -maxdepth 4 \( -type d \( -name .git -o -name node_modules \) \) -prune -o -type l -name node_modules -print 2>/dev/null | head -1)
+  fi
+  [ -n "$hit" ] || continue
+  owner=$(cd "$(dirname "$hit")" 2>/dev/null && cd "$(readlink "$(basename "$hit")")" 2>/dev/null && pwd -P) || owner="the checkout it points at"
   {
-    echo "BLOCKED: this command installs into $dir, whose node_modules is a SYMLINK at $owner."
+    echo "BLOCKED: this command installs into $dir, where $hit is a SYMLINK at $owner."
     echo "An install through that link damages the checkout that OWNS the tree, not this one:"
-    echo "  npm ci       DELETES $owner outright, before any lifecycle script can run"
-    echo "  bun install  writes packages and .bin entries straight into $owner"
-    echo "  npm install  silently REPLACES the link with a real tree, detaching this worktree"
+    echo "  npm ci       DELETES the linked tree outright, before any lifecycle script can run"
+    echo "  bun install  writes packages and .bin entries straight through the link"
+    echo "  npm install  silently REPLACES a root link with a real tree, detaching this worktree"
     echo "A remove verb (npm rm, bun remove) deletes from that same owning checkout."
     echo "Safe alternatives:"
     echo "  npm run worktree:link          links a fresh worktree; it never installs"
-    echo "  a real install with NO symlink in the way. Run \`rm node_modules\` first (it is"
-    echo "  only a link, nothing else is lost), or install in the PRIMARY checkout."
+    echo "  a real install with NO symlink in the way. The link script plants NESTED"
+    echo "  node_modules links too (packages/server, website, ...), so remove them ALL first:"
+    echo "    find . -maxdepth 4 -type l -name node_modules -delete"
+    echo "  (they are only links, nothing else is lost), or install in the PRIMARY checkout."
     echo "A GLOBAL install (-g) is not affected by this and is never blocked."
     echo "Escape hatch for a deliberate exception: WEBJS_NO_WORKTREE_INSTALL_GATE=1."
   } >&2

AGENTS.md

@@ -64,7 +64,7 @@ Fix it with **`npm run worktree:link`** from inside the worktree. A full `npm in
 
 The script discovers the `node_modules` set from the primary checkout rather than hardcoding a list (it changes whenever a package gains a nested tree), never overwrites an existing path, and never creates a dangling link, so it is safe to re-run and safe in a worktree where you already ran a real `npm install`. The seed step keeps the same contract: it only ever applies pending migrations and inserts demo rows that are not there, so a database with rows in it is left untouched.
 
-**Know what this does NOT give you.** The worktree then runs the PRIMARY checkout's framework source through every bare `@webjsdev/*` specifier, because `<primary>/node_modules/@webjsdev/core` is a relative symlink into `<primary>/packages/core` and resolving through the linked root lands there. Relative imports (`../../../src/x.js`) and the browser suite, which web-test-runner serves from the worktree, do use the worktree's own files. So linking makes the suite RUNNABLE, not self-testing: if you are editing `packages/core/src` or `packages/server/src` and need a bare-specifier consumer to exercise YOUR copy, delete the `node_modules` SYMLINK first (`rm node_modules`, it is only a link and nothing else is lost) and then install, or repoint the individual `@webjsdev/<pkg>` entries at it. CI always builds from the branch, so it is unaffected either way.
+**Know what this does NOT give you.** The worktree then runs the PRIMARY checkout's framework source through every bare `@webjsdev/*` specifier, because `<primary>/node_modules/@webjsdev/core` is a relative symlink into `<primary>/packages/core` and resolving through the linked root lands there. Relative imports (`../../../src/x.js`) and the browser suite, which web-test-runner serves from the worktree, do use the worktree's own files. So linking makes the suite RUNNABLE, not self-testing: if you are editing `packages/core/src` or `packages/server/src` and need a bare-specifier consumer to exercise YOUR copy, delete EVERY `node_modules` SYMLINK first, not only the root one, because the link script plants one per workspace that carries its own tree (`find . -maxdepth 4 -type l -name node_modules -delete`, they are only links and nothing else is lost) and then install, or repoint the individual `@webjsdev/<pkg>` entries at it. CI always builds from the branch, so it is unaffected either way.
 
 **NEVER install while the `node_modules` symlink is standing (#1442).** This is the trap the two paragraphs above used to walk you into, and the damage lands on a checkout you are not working in, so the failure surfaces in someone else's session with nothing naming the cause. Measured on npm 11.19.0 and bun 1.3.14: `npm ci` DELETES the primary's whole `node_modules` through the link before any lifecycle script runs, `bun install` writes packages and `.bin` entries straight into the primary through it, and `npm install` silently replaces the link with a real tree, detaching the worktree from the shared source. No `preinstall` script can prevent any of it, because npm removes the symlink before `preinstall` runs, `npm ci` has already emptied the primary by then, and Bun runs it in time but ignores a non-zero exit. So the layers are: Claude Code BLOCKS the command through `.claude/hooks/block-install-in-linked-worktree.sh`, which covers every manager's install aliases plus the REMOVE verbs (`npm rm` in a linked worktree deletes from the owning checkout), judges a COMMAND rather than a token so `git commit -m "fix: npm install ..."` and `grep -rn "npm ci"` are unaffected, and never blocks a GLOBAL `-g` install such as the post-release `npm update -g webjsdev` (escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`), the root `preinstall` REPORTS it for every other tool without ever blocking, `npm run worktree:link` REPAIRS an already-damaged primary, and `npm run check:worktree-links` reports what it would repair without changing anything, exiting non-zero when there is work. `WEBJS_NO_WORKTREE_REPAIR=1` suppresses the repair WRITE, so it has no effect on `--check`, which never writes and always inspects. Tests: `test/hooks/block-install-in-linked-worktree.test.mjs`, `test/repo-health/warn-worktree-install.test.mjs`, `test/repo-health/link-worktree-deps.test.mjs`.
 

packages/cli/lib/doctor/probes/framework-resolves.js

@@ -150,7 +150,8 @@ function linkAwareReinstallFix(appDir) {
     return (
       'node_modules here is a SYMLINK at another checkout, so do NOT run `npm install`: it would act ' +
       'on that checkout, not this one (#1442). Either reinstall in the checkout that owns the tree, ' +
-      'or `rm node_modules` first (it is only a link) and install here.' + linkScriptHint(appDir)
+      'or remove every node_modules symlink first, nested ones included ' +
+      '(`find . -maxdepth 4 -type l -name node_modules -delete`), and install here.' + linkScriptHint(appDir)
     );
   }
   return 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).';

scripts/link-worktree-deps.mjs

@@ -34,10 +34,12 @@
  *
  * So this makes the suite RUNNABLE, not self-testing. If you are editing
  * `packages/core/src` or `packages/server/src` and need a bare-specifier
- * consumer to exercise YOUR copy, delete the `node_modules` SYMLINK first
- * (`rm node_modules`, it is only a link and nothing else is lost) and then
- * install, or point the individual `@webjsdev/<pkg>` entries at this worktree
- * instead. CI always builds from the branch, so it is unaffected either way.
+ * consumer to exercise YOUR copy, delete EVERY `node_modules` SYMLINK first,
+ * not only the root one, because this script plants one per workspace that
+ * carries its own tree (`find . -maxdepth 4 -type l -name node_modules -delete`,
+ * they are only links and nothing else is lost) and then install, or point the
+ * individual `@webjsdev/<pkg>` entries at this worktree instead. CI always
+ * builds from the branch, so it is unaffected either way.
  *
  * NEVER install while the link is standing (#1442). Measured on npm 11.19.0 and
  * bun 1.3.14: `npm ci` DELETES the primary's whole `node_modules` through the

scripts/warn-worktree-install.mjs

@@ -74,7 +74,8 @@ try {
     say(`  ${primaryModules}`);
     say('An install now writes THROUGH that link, into a checkout you are not working in.');
     say('Stop it if you can. Use `npm run worktree:link` to set this worktree up, or');
-    say('`rm node_modules` first if a real, self-contained install is what you want.');
+    say('remove EVERY node_modules symlink first (the link script plants nested ones too:');
+    say('`find . -maxdepth 4 -type l -name node_modules -delete`) if a real install is what you want.');
   } else if (haveOwnModules && !hasEntries(primaryModules)) {
     // The `npm ci` aftermath: npm deleted the link's target before we ran.
     say('the PRIMARY checkout\'s node_modules is now EMPTY or missing:');

test/hooks/block-install-in-linked-worktree.test.mjs

@@ -447,3 +447,29 @@ test('mines --cwd and --dir as target directories, not just --prefix', () => {
     assert.equal(runHook(`yarn --cwd ${worktree} install`, primary).status, 2);
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
+
+test('a NESTED node_modules symlink blocks, not only the root one', () => {
+  // `worktree:link` plants a symlink per workspace that carries its own tree
+  // (packages/server is the live example). Removing just the root link for a
+  // real install leaves those live, and an install writes through them into the
+  // primary the same way. This was the gate's blind spot in exactly the escape
+  // path its own message used to recommend.
+  const root = mkdtempSync(join(tmpdir(), 'install-gate-nested-'));
+  const primary = join(root, 'primary');
+  const worktree = join(root, 'worktree');
+  mkdirSync(join(primary, 'packages', 'server', 'node_modules'), { recursive: true });
+  mkdirSync(join(worktree, 'packages', 'server'), { recursive: true });
+  mkdirSync(join(worktree, 'node_modules'), { recursive: true }); // REAL root tree
+  writeFileSync(join(worktree, 'package.json'), '{"name":"w"}\n');
+  symlinkSync(join(primary, 'packages', 'server', 'node_modules'), join(worktree, 'packages', 'server', 'node_modules'));
+  try {
+    const r = runHook('npm install', worktree);
+    assert.equal(r.status, 2, `expected block, got ${r.status}: ${r.stderr}`);
+    assert.match(r.stderr, /packages\/server\/node_modules is a SYMLINK/);
+    assert.match(r.stderr, /find \. -maxdepth 4 -type l -name node_modules -delete/, 'the remedy removes them ALL');
+    // COUNTERFACTUAL: the same layout with a real nested directory passes.
+    rmSync(join(worktree, 'packages', 'server', 'node_modules'));
+    mkdirSync(join(worktree, 'packages', 'server', 'node_modules'));
+    assert.equal(runHook('npm install', worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});