diff --git a/.agents/skills/webjs/references/built-ins.md b/.agents/skills/webjs/references/built-ins.md
index 3aaabb757..262843896 100644
--- a/.agents/skills/webjs/references/built-ins.md
+++ b/.agents/skills/webjs/references/built-ins.md
@@ -216,7 +216,7 @@ An over-limit body responds `413` without buffering the whole payload.
 
 ### Doctor severity gate
 
-`webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` depends on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
+`webjs doctor` reports project health, and by default only a broken toolchain fails the exit. `--strict` makes EVERY warning fatal, which is unusable in CI, because four checks are environment-shaped: `GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, and `FRAMEWORK_RESOLVE` plus `FRAMEWORK_LINKS` depend on the environment. So per-check severity is CONFIG, keyed by the stable code every result carries.
 
 ```jsonc
 { "webjs": {
diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
new file mode 100755
index 000000000..4dbfd680c
--- /dev/null
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -0,0 +1,309 @@
+#!/usr/bin/env bash
+# PreToolUse hook (matcher: Bash): BLOCK an install command aimed at a directory
+# whose `node_modules` is a SYMLINK. In this repo that link points at the
+# PRIMARY checkout's tree, so the install acts on a checkout you are not working
+# in and the failure surfaces in someone else's session (#1442).
+#
+# Why a hook rather than a `preinstall` script. Measured on npm 11.19.0 and bun
+# 1.3.14, no package-manager lifecycle hook can prevent the damage:
+#   npm install  REPLACES the symlink with a real directory before `preinstall`
+#                runs, so a guard there never sees a symlink at all
+#   npm ci       DELETES the symlink's target, the whole of the primary's
+#                node_modules, before `preinstall` runs
+#   bun install  runs `preinstall` in time but IGNORES a non-zero exit
+# A PreToolUse hook is the only layer that sees the state before the package
+# manager starts. `scripts/warn-worktree-install.mjs` covers every other tool by
+# reporting rather than blocking.
+#
+# ## How the matching works, and why it is shaped this way
+#
+# Recognising a package-manager invocation inside an arbitrary shell command is
+# the hard part of this hook, and getting it wrong in either direction is
+# expensive: a false NEGATIVE lets the corruption through, and a false POSITIVE
+# fires on ordinary commands in a linked worktree, which is the mandated working
+# state here, until someone turns the gate off. Four passes of review found a
+# defect in each direction, so the matcher is built in explicit stages:
+#
+#   1. QUOTED SPANS ARE REMOVED FIRST. A manager invocation never has its own
+#      name inside quotes, while ordinary commands carry shell metacharacters
+#      there constantly. Splitting the raw string instead makes
+#      `git commit -m "fix: the link; npm install now blocks"` look like two
+#      commands, the second an install.
+#   2. The remainder is split on `&&`, `||`, `;`, `|`, `(`, `)` and newlines.
+#   3. Each segment is judged by its FIRST token, after leading env assignments
+#      and wrappers are stripped. A segment that does not START with a package
+#      manager is not an install, whatever else it contains.
+#   4. Only inside a manager-led segment are the remaining tokens scanned, and
+#      the FIRST one recognised as either an install verb or a known safe verb
+#      decides. Anything unrecognised is skipped rather than assumed, so a flag
+#      VALUE (`npm -w packages/core install`) does not hide the verb behind it.
+#
+# Contract: exit 0 = allow, exit 2 = block (message on stderr).
+# Escape hatch: WEBJS_NO_WORKTREE_INSTALL_GATE=1.
+
+if [ "${WEBJS_NO_WORKTREE_INSTALL_GATE:-0}" = "1" ]; then exit 0; fi
+if ! command -v jq >/dev/null 2>&1; then exit 0; fi
+
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+if [ -z "$cmd" ]; then exit 0; fi
+
+# Verbs that WRITE to node_modules. Every manager's documented aliases, because
+# a gate `bun i` walks past is worthless and Bun is the manager that writes
+# THROUGH the link rather than replacing it. `link`, `rebuild` and `prune` are
+# here for the same reason as the remove verbs: they all mutate the tree that
+# the symlink points at.
+# PER MANAGER, not one merged list. Merging them blocked `npm --workspace a run
+# build`, because `a` is a BUN alias for `add`, and blocked `bun upgrade`, which
+# upgrades the Bun BINARY and never touches node_modules.
+#
+# The one-letter aliases `a` and `r` are deliberately omitted from npm's list.
+# They are rare as commands and common as flag VALUES, and the scan cannot tell
+# the two apart, so admitting them blocks `npm -w a run build`. KNOWN GAP: `npm
+# r <pkg>` and `npm a <pkg>` are therefore not blocked. That is the deliberate
+# trade, because the false positive lands on an ordinary command while the false
+# negative lands on a spelling almost nobody types, and the repair, report and
+# doctor layers still catch the damage after the fact.
+NPM_INSTALL='install-ci-test|clean-install-test|install-clean|clean-install|install-test|install|isntall|isntal|isnta|isnt|instal|insta|inst|ins|in|i|add|ci|cit|sit|it|ic|update|upgrade|udpate|up|dedupe|ddp|uninstall|unlink|un|remove|rm|link|ln|rebuild|rb|prune'
+BUN_INSTALL='install|i|add|a|remove|rm|link|unlink|update|pm'
+PNPM_INSTALL='install|i|add|update|upgrade|up|dedupe|remove|rm|uninstall|un|link|unlink|prune|rebuild'
+YARN_INSTALL='install|add|upgrade|up|dedupe|remove|link|unlink'
+# Verbs that do NOT touch node_modules. Listed explicitly so the scan can STOP:
+# without them, `npm run test -- --grep add` would keep scanning and hit `add`.
+SAFE_VERBS='run|run-script|rum|urn|test|tst|t|start|stop|restart|exec|x|ls|list|la|ll|init|innit|create|publish|pack|version|view|v|info|show|why|ping|config|c|get|set|docs|home|repo|bugs|audit|fund|outdated|prefix|root|bin|whoami|token|team|org|access|star|unstar|search|s|se|find|help|doctor|explain|edit|deprecate|dist-tag|hook|login|logout|adduser|owner|profile|shrinkwrap|unpublish|completion|diff|query|sbom'
+# `npm audit` reports and is safe; `npm audit fix` INSTALLS revised versions
+# straight through the link, so it is matched ahead of the safe-verb scan.
+AUDIT_FIX='(^|[[:space:]])audit([[:space:]]+-[^[:space:]]+)*[[:space:]]+fix([[:space:]]|$)'
+# A GLOBAL install writes to the npm prefix, never through the local link, and
+# `npm update -g webjsdev` is this repo's documented post-release step.
+GLOBAL='(^|[[:space:]])(-g|--global)([[:space:]]|$)'
+
+# STAGE 1: neutralise quoted spans and drop heredoc bodies.
+#
+# A quoted span must keep its CONTENT (a quoted path is the ordinary defensive
+# spelling of `cd "<worktree>" && npm ci`, which is the arrival shape this hook
+# exists for) while losing its power to look like a command boundary. So the
+# quote characters are removed and only the SEPARATORS inside them are
+# neutralised. Deleting the whole span instead loses the path and fails open.
+#
+# It is a character-by-character state machine rather than a pair of seds
+# because quote nesting has to be tracked: an apostrophe inside a double-quoted
+# string is literal, and a sed pass over `'...'` first would pair it with the
+# next single quote in the line and swallow whatever sat between.
+#
+# A heredoc BODY is not commands. This repo's docs are full of `npm install`
+# lines, and `cat > doc.md <<'EOF'` ... `EOF` must not read as an install.
+scrubbed=$(printf '%s' "$cmd" | awk '
+  function flushline(l) { print l }
+  BEGIN { heredoc = "" }
+  {
+    if (heredoc != "") {
+      line = $0
+      sub(/[[:space:]]+$/, "", line)
+      if (line == heredoc) heredoc = ""
+      next
+    }
+    out = ""; inS = 0; inD = 0
+    n = length($0)
+    for (i = 1; i <= n; i++) {
+      c = substr($0, i, 1)
+      if (!inD && c == "\047") { inS = !inS; continue }
+      if (!inS && c == "\042") { inD = !inD; continue }
+      if ((inS || inD) && (c == "&" || c == "|" || c == ";" || c == "(" || c == ")")) { out = out "\001"; continue }
+      out = out c
+    }
+    # A HERE-STRING is not a heredoc: `<<<word` would otherwise match the
+    # heredoc regex from its second `<` and swallow every following line until
+    # one equals `word`. Blank the operator and its word first.
+    gsub(/<<<[^[:space:]]*/, " ", out)
+    if (match(out, /<<-?[[:space:]]*[A-Za-z_][A-Za-z0-9_]*/)) {
+      tag = substr(out, RSTART, RLENGTH)
+      sub(/^<<-?[[:space:]]*/, "", tag)
+      heredoc = tag
+      sub(/<<-?[[:space:]]*[A-Za-z_][A-Za-z0-9_]*.*$/, "", out)
+    }
+    flushline(out)
+  }
+')
+
+eff="$PWD"
+target=""
+# STAGE 2: split into segments. `cd` in an earlier segment moves the target the
+# way the shell would.
+while IFS= read -r seg; do
+  seg="${seg#"${seg%%[![:space:]]*}"}"
+  [ -z "$seg" ] && continue
+
+  # STAGE 3: strip leading env assignments and benign wrappers, token by token.
+  # The assignment test is anchored to the FIRST token: an unanchored
+  # `[A-Za-z_]*=*` glob matches the whole segment whenever any LATER token
+  # carries an `=`, which silently disabled the gate for `npm install --omit=dev`.
+  wrapper_seen=0
+  prev_flag=0
+  for _ in 1 2 3 4 5 6 7 8 9 10; do
+    first="${seg%%[[:space:]]*}"
+    [ -n "$first" ] || break
+    strip=0
+    case "$first" in
+      *=*)
+        name="${first%%=*}"
+        case "$name" in
+          ''|*[!A-Za-z0-9_]*|[0-9]*) ;;
+          *) strip=1 ;;
+        esac ;;
+      sudo|env|time|nice) wrapper_seen=1; prev_flag=0; strip=1 ;;
+      npm|bun|pnpm|yarn|yarnpkg) ;;
+      -*) [ "$wrapper_seen" = "1" ] && { prev_flag=1; strip=1; } ;;
+      *)
+        # The VALUE of a wrapper flag (`sudo -u foo`, `nice -n 10`). Deliberately
+        # narrow: walking past ARBITRARY tokens after a wrapper re-creates the
+        # token-anywhere class one level in, where `bash -c "echo yarn"` reaches
+        # the bare-yarn branch. `command`, `exec`, `bash` and `sh` are NOT
+        # wrappers for that reason, so `command -v yarn` stays allowed and
+        # `bash -c "npm ci"` is an accepted gap rather than a nested-shell parser.
+        # A QUOTED command substitution, `git commit -m "$(npm ci)"`, is the same
+        # accepted class: it executes, and the quote pass defuses it, and parsing
+        # nested execution contexts is the road this hook stays off. The unquoted
+        # form already blocks, since its parens split it into command position.
+        if [ "$wrapper_seen" = "1" ] && [ "$prev_flag" = "1" ]; then prev_flag=0; strip=1; fi ;;
+    esac
+    [ "$strip" = "1" ] || break
+    rest="${seg#*[[:space:]]}"
+    [ "$rest" = "$seg" ] && { seg=""; break; }
+    seg="${rest#"${rest%%[![:space:]]*}"}"
+  done
+  [ -n "$seg" ] || continue
+
+  set -- $seg
+  head_tok="$1"
+
+  # `cd` / `pushd` move the effective directory.
+  case "$head_tok" in
+    cd|pushd)
+      shift
+      # Skip `--` and any option, so `cd -- <dir>` and `cd -P <dir>` both work.
+      while [ $# -gt 0 ]; do
+        case "$1" in --) shift; break ;; -*) shift ;; *) break ;; esac
+      done
+      d="${1:-}"
+      case "$d" in
+        '') ;;
+        '~') eff="$HOME" ;;
+        '~/'*) eff="$HOME/${d#'~/'}" ;;
+        /*) eff="$d" ;;
+        *) eff="$eff/$d" ;;
+      esac
+      continue ;;
+  esac
+
+  # STAGE 4: only a manager-led segment can be an install.
+  case "$head_tok" in
+    npm) verbs="$NPM_INSTALL" ;;
+    bun) verbs="$BUN_INSTALL" ;;
+    pnpm) verbs="$PNPM_INSTALL" ;;
+    yarn|yarnpkg) verbs="$YARN_INSTALL" ;;
+    *) continue ;;
+  esac
+  shift
+
+  # A global install never touches this tree.
+  printf '%s' "$seg" | grep -Eq "$GLOBAL" && continue
+
+  verdict=""
+  if printf '%s' "$seg" | grep -Eq "$AUDIT_FIX"; then verdict="install"; fi
+  prefix_dir=""
+  pending_prefix=0
+  while [ $# -gt 0 ]; do
+    tok="$1"; shift
+    case "$tok" in
+      --prefix=*|-C=*|--cwd=*|--dir=*) prefix_dir="${tok#*=}"; continue ;;
+      --prefix|-C|--cwd|--dir) pending_prefix=1; continue ;;
+      -*) continue ;;
+    esac
+    if [ "$pending_prefix" = "1" ]; then prefix_dir="$tok"; pending_prefix=0; continue; fi
+    # The first token recognised either way decides; anything else is a flag
+    # value or a package name and is skipped rather than assumed.
+    # Do NOT stop at the verb: `--prefix` may still be ahead of us, and
+    # `npm install --prefix <worktree>` run from the primary would otherwise be
+    # judged against the primary's own real node_modules and allowed. The FIRST
+    # verdict wins; later tokens are only mined for the prefix.
+    [ -n "$verdict" ] && continue
+    if printf '%s' "$tok" | grep -Eq "^(${verbs})$"; then verdict="install"; continue; fi
+    if printf '%s' "$tok" | grep -Eq "^(${SAFE_VERBS})$"; then verdict="safe"; continue; fi
+  done
+
+  # A bare `yarn` (only flags, no verb) IS an install in yarn classic.
+  # A flags-only `yarn` IS an install in yarn classic, but `yarn --version` and
+  # `yarn --help` only print, so they must not be read as one.
+  if [ -z "$verdict" ]; then
+    case "$head_tok" in
+      yarn|yarnpkg)
+        if printf '%s' "$seg" | grep -Eq '(^|[[:space:]])(--version|-v|-V|--help|-h)([[:space:]]|$)'; then :
+        else verdict="install"; fi ;;
+    esac
+  fi
+  [ "$verdict" = "install" ] || continue
+
+  target="$eff"
+  if [ -n "$prefix_dir" ]; then
+    case "$prefix_dir" in
+      '~') target="$HOME" ;;
+      '~/'*) target="$HOME/${prefix_dir#'~/'}" ;;
+      /*) target="$prefix_dir" ;;
+      *) target="$eff/$prefix_dir" ;;
+    esac
+  fi
+  break
+done <<EOF
+$(printf '%s' "$scrubbed" | tr '&|;()' '\n\n\n\n\n')
+EOF
+
+[ -n "$target" ] || exit 0
+[ -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. 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
+  hit=""
+  if [ -L "$dir/node_modules" ]; then
+    hit="$dir/node_modules"
+  else
+    # Depth 5, NOT 4: the link script walks directories to depth 4 and plants
+    # <dir>/node_modules, one level deeper. packages/ui/packages/registry is the
+    # live shape. These two depths must agree or the gate is blind to links the
+    # script itself creates.
+    hit=$(find "$dir" -maxdepth 5 \( -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, 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 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. The link script plants NESTED"
+    echo "  node_modules links too (packages/server, website, ...), so remove them ALL first:"
+    echo "    find . -maxdepth 5 -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
+  exit 2
+done
+
+exit 0
diff --git a/.claude/hooks/cleanup-merged-worktree.sh b/.claude/hooks/cleanup-merged-worktree.sh
index a57c0d167..6ca3a5a95 100755
--- a/.claude/hooks/cleanup-merged-worktree.sh
+++ b/.claude/hooks/cleanup-merged-worktree.sh
@@ -19,9 +19,14 @@
 # Anything with uncommitted or unpushed-looking work is KEPT and reported, so
 # the hook can never destroy in-flight work.
 #
+# Before removing one, it repoints any `<primary>/node_modules/@webjsdev/*` link
+# that targets that worktree back at the primary's own packages (#1442), so a
+# removal cannot leave the primary resolving into a directory that is gone.
+#
 # It never blocks the tool (always exits 0) and reports what it did back to the
 # model via hookSpecificOutput.additionalContext. Disable with
-# WEBJS_NO_WORKTREE_CLEANUP=1.
+# WEBJS_NO_WORKTREE_CLEANUP=1, which disables the repoint along with everything
+# else, since it is the same teardown.
 #
 # Rule: AGENTS.md "One task per git worktree" + the webjs-start-work skill.
 
@@ -93,8 +98,51 @@ is_clean() {
   [ -z "$dirty" ]
 }
 
+# #1442: the primary may hold `@webjsdev/*` links pointing INTO a worktree we
+# are about to delete. Repoint them back at the primary's own packages while the
+# target still exists, so the removal cannot leave a dangling link behind. It is
+# scoped to links targeting THIS worktree; the general sweep belongs to
+# `npm run worktree:link`, which you run deliberately.
+repoint_primary_links() {
+  # NOT `base`: that name holds the script-global merge-base ref that
+  # `is_merged()` reads, and bash `local` is dynamically scoped, so shadowing
+  # it here would blank the ref for anything this function ever calls.
+  local wt="$1" scope wtreal entry_name abs rel
+  scope="$primary/node_modules/@webjsdev"
+  [ -d "$scope" ] || return 0
+  wtreal=$(cd "$wt" 2>/dev/null && pwd -P) || return 0
+
+  # Dot entries too: npm's `.name-HASH` staging links land in the same scope.
+  for e in "$scope"/* "$scope"/.[!.]*; do
+    # An unmatched glob arrives literally, and is not a symlink, so this also
+    # absorbs an empty scope.
+    [ -L "$e" ] || continue
+    entry_name=$(basename "$e")
+    # Resolve without `readlink -f`, which is GNU-only.
+    abs=$(cd "$(dirname "$e")" 2>/dev/null && cd "$(readlink "$e")" 2>/dev/null && pwd -P) || continue
+    case "$abs" in
+      "$wtreal"/*) ;;
+      *) continue ;;
+    esac
+    rel="${abs#"$wtreal"/}"
+    case "$entry_name" in
+      .*-????????)
+        rm -f "$e" && relinked+=("dropped staging entry @webjsdev/$entry_name")
+        ;;
+      *)
+        if [ -e "$primary/$rel" ]; then
+          ln -sfn "../../$rel" "$e" && relinked+=("repointed @webjsdev/$entry_name -> ../../$rel")
+        else
+          relinked+=("KEPT @webjsdev/$entry_name (points into $wt, but $rel is missing in the primary)")
+        fi
+        ;;
+    esac
+  done
+}
+
 removed=()
 kept=()
+relinked=()
 
 # Parse worktree path + branch pairs.
 wt=""
@@ -116,6 +164,7 @@ while IFS= read -r line; do
       if ! is_merged "$br"; then
         kept+=("$wt (branch $br not merged yet)"); wt=""; continue
       fi
+      repoint_primary_links "$wt"
       if git worktree remove --force "$wt" >/dev/null 2>&1; then
         removed+=("$wt ($br)")
       else
@@ -129,11 +178,12 @@ done < <(git worktree list --porcelain 2>/dev/null)
 git worktree prune >/dev/null 2>&1 || true
 
 # Report nothing if there was nothing to do.
-if [ "${#removed[@]}" -eq 0 ] && [ "${#kept[@]}" -eq 0 ]; then exit 0; fi
+if [ "${#removed[@]}" -eq 0 ] && [ "${#kept[@]}" -eq 0 ] && [ "${#relinked[@]}" -eq 0 ]; then exit 0; fi
 
 msg="Worktree cleanup after \`gh pr merge\`:"
 for r in "${removed[@]:-}"; do [ -n "$r" ] && msg="$msg"$'\n'"  removed $r (merged, clean)"; done
 for k in "${kept[@]:-}"; do [ -n "$k" ] && msg="$msg"$'\n'"  kept $k"; done
+for l in "${relinked[@]:-}"; do [ -n "$l" ] && msg="$msg"$'\n'"  $l"; done
 
 jq -n --arg ctx "$msg" '{
   hookSpecificOutput: {
diff --git a/.claude/settings.json b/.claude/settings.json
index 7a0487212..fb23dbafa 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -61,6 +61,10 @@
           {
             "type": "command",
             "command": ".claude/hooks/require-bun-parity-with-runtime-src.sh"
+          },
+          {
+            "type": "command",
+            "command": ".claude/hooks/block-install-in-linked-worktree.sh"
           }
         ]
       }
diff --git a/AGENTS.md b/AGENTS.md
index 222d886c8..12655a2f6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,7 +56,7 @@ cd ../<repo>-<slug>          # do ALL work for the task here
 
 **A fresh worktree has NO `node_modules`** (git worktrees do not copy it), so running an app from one (`webjs dev` / `webjs start`, the test runner, a scaffolded app) fails to resolve `@webjsdev/*` until you install or link it. `webjs doctor` warns for this exact case (#954) and `webjs dev` / `webjs start` print the cause + remedy instead of a raw `ERR_MODULE_NOT_FOUND`.
 
-Fix it with **`npm run worktree:link`** from inside the worktree (or a full `npm install` there, which is correct but slow and duplicates a large tree per worktree). **Do NOT hand-symlink only the root `node_modules`.** That is the obvious move and it produces a worktree that looks set up and then fails dozens of tests for reasons that point nowhere near the real cause. Three things beyond the root tree are needed, and the script handles all three:
+Fix it with **`npm run worktree:link`** from inside the worktree. A full `npm install` there is NOT an alternative once the link is standing, and the reason is below. **Do NOT hand-symlink only the root `node_modules`.** That is the obvious move and it produces a worktree that looks set up and then fails dozens of tests for reasons that point nowhere near the real cause. Three things beyond the root tree are needed, and the script handles all three:
 
 - **Every NESTED `node_modules`, not just the root.** npm hoists what it can, but a workspace whose range conflicts with the hoisted copy keeps its own nested tree. `packages/server` is the live example: the root carries `ws@7` (hoisted for another dependent) while `packages/server` declares `^8.20.0` and keeps `ws@8` nested. Link only the root and `WebSocketServer`, a ws@8-only named export, resolves up to ws@7 and throws at module load. That single miss failed hundreds of assertions across the server, integration, and smoke suites, none of them naming ws.
 - **`packages/core/dist`**, which is built rather than committed, so a fresh worktree has none and every test importing the built bundle fails to resolve it.
@@ -64,13 +64,15 @@ Fix it with **`npm run worktree:link`** from inside the worktree (or a full `npm
 
 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, run a real `npm install` in the worktree, 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 5 -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.
 
-Note the `webjs doctor` / `webjs dev` remedy message still suggests the root-only symlink. That advice is correct for a scaffolded APP worktree, which has no nested trees and no built `dist/`, and wrong only for this monorepo.
+**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`.
+
+Note the `webjs doctor` / `webjs dev` remedy message suggests the root-only symlink. That advice is correct for a scaffolded APP worktree, which has no nested trees and no built `dist/`, and wrong only for this monorepo. It stays app-generic on purpose, because it ships in the published CLI and `webjs dev` prints it verbatim to someone whose app has none of this repo's scripts; it names `npm run worktree:link` only when it finds a package.json actually declaring that script, so in this repo you get the monorepo path and in a scaffolded app you do not.
 
 Git enforces one-branch-per-worktree, so separate worktrees make the collision impossible. There is NO lone-agent exception: every task cuts a worktree, and the primary checkout stays an untouched mirror of main (tracked-file edits there are hook-blocked). The repo's `.hooks/pre-commit` additionally BLOCKS a published-library (`core`/`server`/`cli`/`mcp`/`ui`/`intellisense`) version bump on any non-`chore/release-*` branch, the canonical wrong-branch-release symptom.
 
-**Cleanup is automatic after a merge.** The `.claude/hooks/cleanup-merged-worktree.sh` PostToolUse hook fires after any `gh pr merge` and removes each linked worktree whose branch is merged AND whose tree is clean, so a merged branch's worktree never leaks (accumulated stale worktrees are exactly what it prevents). It is conservative: it KEEPS anything with uncommitted changes, an unmerged branch, or the worktree you ran the merge from (you cannot remove your current directory, so `cd` out and `git worktree remove` it yourself), and never touches the primary checkout. Disable with `WEBJS_NO_WORKTREE_CLEANUP=1`. Test: `test/hooks/cleanup-merged-worktree.test.mjs`.
+**Cleanup is automatic after a merge.** The `.claude/hooks/cleanup-merged-worktree.sh` PostToolUse hook fires after any `gh pr merge` and removes each linked worktree whose branch is merged AND whose tree is clean, so a merged branch's worktree never leaks (accumulated stale worktrees are exactly what it prevents). It is conservative: it KEEPS anything with uncommitted changes, an unmerged branch, or the worktree you ran the merge from (you cannot remove your current directory, so `cd` out and `git worktree remove` it yourself), and never touches the primary checkout. Before removing one it repoints any `<primary>/node_modules/@webjsdev/*` link that targets that worktree back at the primary's own packages and drops an npm staging entry that would be left dangling (#1442), so a removal can never leave the primary resolving into a directory that is gone; a link it cannot correct is kept and reported rather than repointed at a missing path. Disable with `WEBJS_NO_WORKTREE_CLEANUP=1`, which disables the repoint along with everything else. Test: `test/hooks/cleanup-merged-worktree.test.mjs`.
 
 ### Skills are routed deterministically, never skipped
 
@@ -571,7 +573,7 @@ webjs check  [--rules] [--json]    # correctness validator (report-only, no auto
 webjs routes [--json] [--table] [--no-headers]   # print the route table (path / owner file / methods, #975). Default tree; --json is byte-identical to the MCP list_routes tool; --no-headers drops the --table header for piping
 webjs elision [--json] [--verify] [--routes <paths>]  # the elision verdict (#1308): every component module as elided or shipped (a shipped one naming the EVIDENCE that forced it and the module that did the forcing), every page/layout as inert / import-only / ships-whole, and every orphan class that gets no verdict at all (either no registration call, or a computed tag; the scanner matches only a literal one). --json is byte-identical to the MCP list_elision tool. --verify renders every static page route with elision on and off and diffs the observable SSR bytes (the framework's own differential guard, pointed at your app): exit 0 on parity, non-zero on a divergence OR on a corpus where nothing could be compared. It proves elision did not change the bytes you SERVE, NOT post-hydration behaviour (a wrongly dropped module is a dead click, not different bytes), so run your browser/e2e suite twice under WEBJS_ELIDE=1 / WEBJS_ELIDE=0 for that half. Dynamic routes are skipped by name; --routes adds real paths
 webjs mcp                          # read-only MCP: routes, actions (RPC hashes), components, elision (what the browser drops, and why each shipped module ships), check, ui kit
-webjs doctor [--json] [--strict]   # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory PLUS the component-elision verdict, which warns only on an orphan (#1308); a warning when a route module writes a `<link rel="stylesheet">` without `asset()`, #1095); non-zero exit on a hard fail OR on a check the app gated `error`. --json emits `{ results, summary }` (results is the DoctorResult[], each carrying a stable code + its effective severity; summary counts pass/warn/fail/off), plus a third `configErrors` key on the one path where a rejected `webjs.doctor` config stops any check running; --strict additionally fails on every REMAINING warning (#975). Per-check severity is CONFIG, not a flag: `webjs.doctor.gate` maps a code to `off` / `warn` / `error` so CI gates a chosen subset (#1257)
+webjs doctor [--json] [--strict]   # project-health checklist (incl. a framework-resolve check that warns when @webjsdev/core can't be resolved from the app dir, the fresh-worktree-without-node_modules trap #954; a page/layout elision advisory PLUS the component-elision verdict, which warns only on an orphan (#1308); a `framework-links` check that warns when the `@webjsdev/core` entry is a symlink that DANGLES or resolves outside the checkout owning its `node_modules`, which is what an install inside a linked worktree leaves behind and what a plain resolve probe cannot see, #1442; a warning when a route module writes a `<link rel="stylesheet">` without `asset()`, #1095); non-zero exit on a hard fail OR on a check the app gated `error`. --json emits `{ results, summary }` (results is the DoctorResult[], each carrying a stable code + its effective severity; summary counts pass/warn/fail/off), plus a third `configErrors` key on the one path where a rejected `webjs.doctor` config stops any check running; --strict additionally fails on every REMAINING warning (#975). Per-check severity is CONFIG, not a flag: `webjs.doctor.gate` maps a code to `off` / `warn` / `error` so CI gates a chosen subset (#1257)
 webjs types                        # generate .webjs/routes.d.ts (typed Route union + per-route params, #258)
 webjs version                      # print the installed @webjsdev/cli version (also: webjs --version / -v, #975)
 webjs help   [command]             # full usage banner, or per-command usage + Options + Examples (e.g. webjs help routes, #975). Flag forms: webjs --help / -h (banner), webjs <command> --help / -h (that command). typecheck/db/ui --help forward to their wrapped tool; an unknown topic exits 1
diff --git a/framework-dev.md b/framework-dev.md
index af939146b..251e6cb51 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -146,6 +146,32 @@ It costs about two and a half seconds on a cold worktree and nothing once there
 
 It runs below the primary-checkout guard, so `worktree:link` in the primary stays a no-op. That guard is not what keeps seeding out of the test suite, though. The `defaultPrimary()` repo-health test runs the script bare against its own cwd, and from a linked worktree (the mandated workflow) the guard does not fire, so the script would seed that worktree's blog database as a side effect of `npm test`, racing `test/integration/blog-http.test.mjs` reading the same file in parallel. That test therefore sets `WEBJS_NO_WORKTREE_SEED=1` explicitly, and the helpers in that file strip the variable from the ambient env so an exported opt-out cannot invert the seed assertions.
 
+### Never install through a linked worktree's `node_modules` (#1442)
+
+`npm run worktree:link` symlinks a worktree's `node_modules` at the primary checkout's, which makes the worktree runnable and also puts a single writable path from every worktree into the primary's dependency tree. An install run inside a linked worktree therefore acts on the PRIMARY, and the damage lands on a session that did nothing wrong.
+
+Measured on npm 11.19.0 and bun 1.3.14:
+
+| Command, in a linked worktree | What actually happens |
+|---|---|
+| `npm install` | REPLACES the `node_modules` symlink with a real directory and builds a full tree there. The primary is untouched, but the worktree silently detaches and no longer runs the primary's framework source. |
+| `npm ci` | DELETES the symlink's TARGET, meaning the whole of `<primary>/node_modules`, then builds a real tree locally. The primary and every other linked worktree break at once. |
+| `bun add` / `bun install` | KEEPS the symlink and writes THROUGH it. New packages and `.bin` entries land in `<primary>/node_modules`. |
+
+**A `preinstall` script cannot prevent any of this.** Under `npm install` it runs with `node_modules` already a real directory, because npm replaced the symlink before the script started. Under `npm ci` it runs with the primary already emptied, because npm deletes the link's target first. Under Bun it does run in time and does see the symlink, but a non-zero exit does not stop Bun (measured: `bun install` exited 0 with a `preinstall` that exited 2). A non-zero `preinstall` DOES block `npm install` and `npm ci`, exit code propagated verbatim, so a buggy guard there would red every CI job for no protection at all.
+
+So prevention lives one layer up, and the rest is repair:
+
+- **Block.** `.claude/hooks/block-install-in-linked-worktree.sh` is a `PreToolUse` (Bash) hook, the only layer that sees the state before the package manager starts. It refuses an install verb whose target directory has a symlinked `node_modules`, at the root OR nested (the link script plants one per workspace carrying its own tree, so a worktree whose root link was removed still holds nested links the install writes through; remove them all with `find . -maxdepth 5 -type l -name node_modules -delete`), covering every manager's documented aliases (`bun i` matters most, since Bun writes THROUGH the link), the REMOVE verbs, and `link` / `rebuild` / `prune` / `audit fix`, all of which mutate the tree the symlink points at. The tables are per manager, so `bun upgrade`, which upgrades the Bun binary, stays allowed while `pnpm upgrade` does not. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+
+  It judges a COMMAND, never a token, in four stages. Quoted spans are neutralised FIRST, keeping their content but stripping the separators inside them, and heredoc bodies are dropped. The remainder is split on `&&`, `||`, `;`, `|`, `(`, `)` and newlines. Each segment is then judged by its FIRST token, after leading env assignments and wrappers like `sudo` are stripped. Only inside a manager-led segment are the remaining tokens scanned, for the first one recognised as either an install verb or a known safe verb, so a flag sitting before the verb does not hide it. Matching the manager token anywhere in the line is the obvious shortcut and it is badly wrong: it blocks `git commit -m "fix: npm install ..."`, `grep -rn "npm ci" AGENTS.md` and `git log --grep "npm install"`. A linked worktree is the mandated working state here, so that fires on ordinary commands constantly, and a gate that cries wolf is a gate someone turns off. `npm test`, `npm run <script>`, `npx ...`, `npm init` and `yarn test` all pass, and so does a GLOBAL install (`-g` / `--global`), which writes to the npm prefix rather than through the link and is this repo's documented post-release step.
+- **Report.** The root `preinstall` runs `scripts/warn-worktree-install.mjs`, which ALWAYS exits 0 and returns immediately unless `.git` is a FILE, so a normal clone and CI never see it. It names whichever of the three states it landed in and prints the repair.
+- **Repoint on teardown.** `.claude/hooks/cleanup-merged-worktree.sh` repoints any `<primary>/node_modules/@webjsdev/*` link targeting a worktree it is about to remove, before removing it.
+- **Repair on demand.** `npm run worktree:link` repairs the primary's `@webjsdev/*` scope: a dangling link, a link into a live foreign checkout, and an absolute in-primary link all become the relative form, and a DANGLING `.name-HASH` npm staging entry is dropped. A LIVE staging entry is left strictly alone. `npm run check:worktree-links` reports without writing and exits non-zero when there is work. Escape hatch `WEBJS_NO_WORKTREE_REPAIR=1` suppresses the repair WRITE only, so `--check` ignores it and still inspects; the `defaultPrimary()` test needs the hatch for the same reason it needs `WEBJS_NO_WORKTREE_SEED=1`: the repair pass sits ABOVE the primary-checkout guard by design, so it runs in both positions and would otherwise rewrite the real checkout during `npm test`.
+- **Detect.** `webjs doctor`'s `framework-links` check warns on a dangling or foreign `@webjsdev/core` link. `FRAMEWORK_RESOLVE` cannot see the foreign case, because a link into a live checkout resolves perfectly.
+
+Regression 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`, `test/hooks/cleanup-merged-worktree.test.mjs`, `test/cli/doctor.test.mjs`.
+
 ### `webjs check` runs per app, and the repo root refuses (#1301)
 
 `webjs check` is an APP-level tool: every rule assumes one application, meaning one module graph, one custom-element registry, one runtime. This repo's root is none of those, it is a workspace holding two apps plus every package's test suite plus editor fixtures plus the scaffold templates, so a root-level run used to walk all of it and report 67 collisions that no single runtime ever sees. `my-counter`, for instance, was reported as duplicated across a blog component, an editor-plugin fixture, two unit tests, and a type fixture, five files that never load together.
diff --git a/package.json b/package.json
index 294eab97a..aeea2ee2a 100644
--- a/package.json
+++ b/package.json
@@ -18,9 +18,11 @@
     "node": ">=24.0.0"
   },
   "scripts": {
+    "preinstall": "node scripts/warn-worktree-install.mjs || true",
     "prepare": "node scripts/git-worktree-safe.mjs 2>/dev/null || true",
     "fix:git": "node scripts/git-worktree-safe.mjs",
     "check:git": "node scripts/git-worktree-safe.mjs --check",
+    "check:worktree-links": "node scripts/link-worktree-deps.mjs --check",
     "worktree:link": "node scripts/link-worktree-deps.mjs",
     "dev": "node scripts/dev-all.js",
     "dev:gallery": "npm run dev --workspace=@webjsdev/gallery",
diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
index 7efacf11f..c915c383f 100644
--- a/packages/cli/AGENTS.md
+++ b/packages/cli/AGENTS.md
@@ -181,7 +181,7 @@ README.md                npm-facing package readme.
 | `webjs routes [--json\|--table] [--no-headers]` | Prints the route table to stdout (#975): every page (path, owner file, dynamic params) and every `route.{js,ts}` handler (path, owner file, HTTP methods). Reuses `buildRouteTable` from `@webjsdev/server` (the ONE walker, shared with `webjs types` + the dev server) and the shared `projectRoutes` projector from `@webjsdev/mcp/routes-report`, so `--json` is byte-identical to the MCP `list_routes` tool (the same split as `check --json` / `check-report.js`). Default is a grouped tree; `--table` is aligned KIND/PATH/METHODS/FILE columns and `--no-headers` drops the header row for piping. Read-only. Tests: `test/cli/routes.test.mjs` |
 | `webjs elision [--json] [--verify] [--routes <paths>]` | `analyzeAppElision()` from `@webjsdev/server` (#1308). Prints the display-only elision verdict: every component module as elided or shipped (a shipped one naming the EVIDENCE that forced it, `own` / `observed` / `closure` / `render` / `import` / `unreadable`, and the module that did the forcing), every page/layout as inert / import-only / ships-whole, and every ORPHAN class, one with no registration call or a computed tag, which the scanner cannot see either way. `--json` is byte-identical to the MCP `list_elision` tool (drift-tested). `--verify` boots two `createRequestHandler` instances with `WEBJS_ELIDE` flipped, renders the app's static page corpus through both, and diffs the masked SSR bytes via the shared `maskJsSet` / `staticPageRoutes` leaf: the framework's own differential guard pointed at an arbitrary app. It FORCES the ON side on (the override wins over `webjs.elide`, so an opted-out app still gets a real pair), skips dynamic routes by name (`--routes` adds real paths), skips a nondeterministic route rather than failing it, and exits non-zero on a divergence OR on a corpus where nothing was compared. It reports how many modules elision dropped, so a pass over a corpus with nothing elidable is visibly trivial rather than mistaken for proof |
 | `webjs mcp` | Delegates to `runMcpServer()` from the standalone `@webjsdev/mcp` package (#415; full surface in `packages/mcp/AGENTS.md`). A read-only MCP stdio server: INTROSPECTION (`list_routes` / `list_actions` / `list_components` / `list_elision` / `check`), KNOWLEDGE (`init` primer, `docs`, `resources`, `prompts`), and a `source` tool. The scaffold's `.claude.json` registers the server directly as `{ "command": "npx", "args": ["@webjsdev/mcp"] }` (mountable in any MCP host, e.g. Cursor `.cursor/mcp.json`); `webjs mcp` stays as a back-compat alias. STDOUT is the JSON-RPC channel (diagnostics go to stderr) |
-| `webjs doctor` | `runDoctorChecks()` from `lib/doctor.js` (delegating to `lib/doctor/runner.js`). TWO elision checks share ONE `analyzeAppElision()` call so the module graph is built once per run: `ELISION_CARRIERS` (#646, the page/layout carrier advisory) and `ELISION_COMPONENTS` (#1308, the other direction, which PASSES with the elided inventory and warns ONLY on an orphan, the one shape that gets no verdict and has no escape hatch; gateable like any other code via `webjs.doctor.gate`). A project-health checklist over existing signals (Node major, tsconfig `erasableSyntaxOnly`, `.env` drift vs `.env.example`, vendor-pin freshness, the `.gitignore` keeping `.webjs/vendor/` committable (`vendor-gitignore`, moved here from `webjs check` in #461 as a warn since it is a project-config concern, not source correctness), `@webjsdev/*` version coherence (`WEBJS_VERSIONS`, which resolves each declared dep's INSTALLED version through Node's own resolver anchored at the app dir rather than reading `<appDir>/node_modules/<dep>/package.json`, so a workspace-hoisted install resolves and the check agrees with `FRAMEWORK_RESOLVE` instead of contradicting it, #1300; the resolve tries `<dep>/package.json` FIRST because a bin-only package like `@webjsdev/cli` has no main entry, and falls back through the main entry plus a bounded walk to the package root on `ERR_PACKAGE_PATH_NOT_EXPORTED` because `@webjsdev/server` locks its manifest out of its `exports` map, so neither half alone resolves all four packages. Local to `lib/doctor.js` rather than `getPackageVersion` from `@webjsdev/server`, since doctor must run when the framework does not resolve at all (#954) and that helper returns null for a bin-only package. Before the fix the check warned on every healthy workspace install, which made it ungatable), a framework-resolve probe (#954: `checkFrameworkResolves` + the exported `frameworkResolves` helper WARN when `@webjsdev/core` cannot be resolved FROM the app dir via a directory-relative `createRequire` probe, naming the fresh-git-worktree-without-node_modules cause and the fix; silent PASS when it resolves, so a healthy app is untouched), importmap coherence, git pre-commit hook, and a page/layout elision advisory (#646: `checkElisionCarriers` runs `@webjsdev/server`'s `analyzeAppElision` and WARNS, naming the first client-effecting blocker, for each page/layout that ships whole instead of being elided as a carrier; advisory-only, skipped when elision is off or there is no `app/`), and an unmarked-stylesheet-link advisory (#1095: `checkUnmarkedAssetLinks` scans every `app/**` route module that renders markup (`page` / `layout`, plus the always-shipped `error` / `not-found` / `forbidden` / `unauthorized` / `loading` boundaries and `global-error`, which writes its own `<head>`), skipping `_private` folders the router never routes, for a `<link rel="stylesheet">` whose href is a STATIC, quoted, root-absolute `/public/...` literal, i.e. one not wrapped in `asset()`, and WARNs with `file:line`, since that url is un-versioned and a deploy cannot bust a CDN's copy. Scoped to `rel="stylesheet"`: a cross-origin sheet must keep its exact url, `rel="icon"` is a legitimate deliberate non-mark (the website leaves its favicons bare so the SEO repo-health tests parse the hrefs literally), `rel="preload"` MUST stay unversioned or its hint could never match the request the CSS `url()` makes, and an `href=${expr}` hole is undecidable from source and is exactly the marked shape. It reads the author's SOURCE and rewrites nothing, deliberately: the automatic form was built and rejected in #1196, and this is the same authoring-time posture Rails and Remix take)). PURE checks render with a `[pass]` / `[off]` / `[warn]` / `[fail]` marker; the exit is non-zero when a HARD check fails (Node below the floor, or `erasableSyntaxOnly` missing in an existing tsconfig) OR when a check the app gated `error` reports something (#1257, see below); an ungated warn (drift / staleness) never fails the exit. Each `DoctorResult` carries a stable SCREAMING_SNAKE `code` (#975, the `DOCTOR_CODES` map; e.g. `NODE_VERSION`, `TSCONFIG_ERASABLE`, `IMPORTMAP_COHERENCE`) so an agent branches on the failure KIND, not the message text. `--json` emits `{ results, summary }` where `results` is the raw `DoctorResult[]` (each carrying a `code` + its effective `severity`) and `summary` is `{ pass, warn, fail, off, strict, ok }` (the same array-under-a-key convention as `check --json`). A REJECTED `webjs.doctor` config is the one path that adds a third key, `configErrors`, an array of `{ kind }` entries (`malformed` / `unknown-key` / `unknown-code` / `bad-severity`) with `results` empty because no check ran; `--strict` additionally fails the exit on every REMAINING warning (on top of hard failures and gated errors), so doctor can gate a fully-clean fix loop. The only network touch (pin freshness, plus the importmap-coherence live resolve) is best-effort: a fetch failure is a warn, never a hard fail. The importmap-coherence check (#450) runs `@webjsdev/server`'s `checkImportmapCoherence` IDENTICALLY over the live importmap AND the vendored `.webjs/vendor/importmap.json`, warning when a pinned package needs a newer version of another pinned package than is pinned (the #446 skew class); it reads dependency metadata from the already-installed node_modules manifests (no network of its own) and degrades to "could not verify" when a manifest is unavailable. Tests: `test/cli/doctor.test.mjs` |
+| `webjs doctor` | `runDoctorChecks()` from `lib/doctor.js` (delegating to `lib/doctor/runner.js`). TWO elision checks share ONE `analyzeAppElision()` call so the module graph is built once per run: `ELISION_CARRIERS` (#646, the page/layout carrier advisory) and `ELISION_COMPONENTS` (#1308, the other direction, which PASSES with the elided inventory and warns ONLY on an orphan, the one shape that gets no verdict and has no escape hatch; gateable like any other code via `webjs.doctor.gate`). A project-health checklist over existing signals (Node major, tsconfig `erasableSyntaxOnly`, `.env` drift vs `.env.example`, vendor-pin freshness, the `.gitignore` keeping `.webjs/vendor/` committable (`vendor-gitignore`, moved here from `webjs check` in #461 as a warn since it is a project-config concern, not source correctness), `@webjsdev/*` version coherence (`WEBJS_VERSIONS`, which resolves each declared dep's INSTALLED version through Node's own resolver anchored at the app dir rather than reading `<appDir>/node_modules/<dep>/package.json`, so a workspace-hoisted install resolves and the check agrees with `FRAMEWORK_RESOLVE` instead of contradicting it, #1300; the resolve tries `<dep>/package.json` FIRST because a bin-only package like `@webjsdev/cli` has no main entry, and falls back through the main entry plus a bounded walk to the package root on `ERR_PACKAGE_PATH_NOT_EXPORTED` because `@webjsdev/server` locks its manifest out of its `exports` map, so neither half alone resolves all four packages. Local to `lib/doctor.js` rather than `getPackageVersion` from `@webjsdev/server`, since doctor must run when the framework does not resolve at all (#954) and that helper returns null for a bin-only package. Before the fix the check warned on every healthy workspace install, which made it ungatable), a framework-resolve probe (#954: `checkFrameworkResolves` + the exported `frameworkResolves` helper WARN when `@webjsdev/core` cannot be resolved FROM the app dir via a directory-relative `createRequire` probe, naming the fresh-git-worktree-without-node_modules cause and the fix; silent PASS when it resolves, so a healthy app is untouched), importmap coherence, git pre-commit hook, and a page/layout elision advisory (#646: `checkElisionCarriers` runs `@webjsdev/server`'s `analyzeAppElision` and WARNS, naming the first client-effecting blocker, for each page/layout that ships whole instead of being elided as a carrier; advisory-only, skipped when elision is off or there is no `app/`), a framework-link integrity check (#1442: `checkFrameworkLinks` + the exported `inspectFrameworkLink` helper WARN when the `@webjsdev/core` entry in node_modules is a symlink that DANGLES or resolves OUTSIDE the tree that PHYSICALLY owns that `node_modules`, which is what an install run inside a linked worktree leaves behind. `FRAMEWORK_RESOLVE` cannot see it, because a link into a live foreign checkout resolves perfectly and silently runs another branch's framework source. The owner rule is what keeps it correct in a linked worktree, where `node_modules` is itself a symlink at the primary's, so the owning tree is the PRIMARY and a target inside it is right rather than foreign; the link target is resolved against the directory the link physically sits in, since resolving `../../packages/core` lexically through a symlinked `node_modules` lands under the worktree and would report every healthy linked worktree as corrupted), and an unmarked-stylesheet-link advisory (#1095: `checkUnmarkedAssetLinks` scans every `app/**` route module that renders markup (`page` / `layout`, plus the always-shipped `error` / `not-found` / `forbidden` / `unauthorized` / `loading` boundaries and `global-error`, which writes its own `<head>`), skipping `_private` folders the router never routes, for a `<link rel="stylesheet">` whose href is a STATIC, quoted, root-absolute `/public/...` literal, i.e. one not wrapped in `asset()`, and WARNs with `file:line`, since that url is un-versioned and a deploy cannot bust a CDN's copy. Scoped to `rel="stylesheet"`: a cross-origin sheet must keep its exact url, `rel="icon"` is a legitimate deliberate non-mark (the website leaves its favicons bare so the SEO repo-health tests parse the hrefs literally), `rel="preload"` MUST stay unversioned or its hint could never match the request the CSS `url()` makes, and an `href=${expr}` hole is undecidable from source and is exactly the marked shape. It reads the author's SOURCE and rewrites nothing, deliberately: the automatic form was built and rejected in #1196, and this is the same authoring-time posture Rails and Remix take)). PURE checks render with a `[pass]` / `[off]` / `[warn]` / `[fail]` marker; the exit is non-zero when a HARD check fails (Node below the floor, or `erasableSyntaxOnly` missing in an existing tsconfig) OR when a check the app gated `error` reports something (#1257, see below); an ungated warn (drift / staleness) never fails the exit. Each `DoctorResult` carries a stable SCREAMING_SNAKE `code` (#975, the `DOCTOR_CODES` map; e.g. `NODE_VERSION`, `TSCONFIG_ERASABLE`, `IMPORTMAP_COHERENCE`) so an agent branches on the failure KIND, not the message text. `--json` emits `{ results, summary }` where `results` is the raw `DoctorResult[]` (each carrying a `code` + its effective `severity`) and `summary` is `{ pass, warn, fail, off, strict, ok }` (the same array-under-a-key convention as `check --json`). A REJECTED `webjs.doctor` config is the one path that adds a third key, `configErrors`, an array of `{ kind }` entries (`malformed` / `unknown-key` / `unknown-code` / `bad-severity`) with `results` empty because no check ran; `--strict` additionally fails the exit on every REMAINING warning (on top of hard failures and gated errors), so doctor can gate a fully-clean fix loop. The only network touch (pin freshness, plus the importmap-coherence live resolve) is best-effort: a fetch failure is a warn, never a hard fail. The importmap-coherence check (#450) runs `@webjsdev/server`'s `checkImportmapCoherence` IDENTICALLY over the live importmap AND the vendored `.webjs/vendor/importmap.json`, warning when a pinned package needs a newer version of another pinned package than is pinned (the #446 skew class); it reads dependency metadata from the already-installed node_modules manifests (no network of its own) and degrades to "could not verify" when a manifest is unavailable. Tests: `test/cli/doctor.test.mjs` |
 | `webjs types` | `generateRouteTypes()` from `@webjsdev/server`, writes `.webjs/routes.d.ts` (typed `Route` union + per-route params, #258). Also auto-emitted at `webjs dev` startup |
 | `webjs typecheck [tsc args]` | Resolves the project's own `typescript/bin/tsc` (via `createRequire` from the app cwd) and spawns it with `--noEmit`, passing extra args through. Exits non-zero on a type error (a CI gate). A clear message + non-zero exit when typescript is not installed (#265). The framework runs the standard compiler, it does not embed one |
 | `webjs create <name> [--template …] [--db …] [--runtime node\|bun]` | `scaffoldApp()` from `lib/create.js`. `<name>` is validated by `lib/app-name.js` BEFORE any file is written (#1066; npm package-name rules minus the lowercase-only clause, which never protected anything and which `webjs create MyApp` relied on), at all three entries (this bin, `scaffoldApp()`, and the `create-webjs` wrapper). `--runtime bun` (or `bun create webjs`, auto-detected) emits a Bun-flavored app (#541): `dev`/`start` scripts force `bun --bun`, `bun.lock`, a pure `oven/bun:1` Dockerfile + bun-install CI, and bun-command agent docs. Orthogonal to `--template` (invariant 1 stays exactly 3 templates). |
@@ -190,7 +190,7 @@ README.md                npm-facing package readme.
 | `webjs version` | Prints the installed `@webjsdev/cli` version (#975, `readCliVersion()` reads the package's own package.json). Also reachable as the top-level `webjs --version` / `-v` flag, handled at the top of `main()` before the Node preflight so it works on an old Node. Tests: `test/cli/help.test.mjs` |
 | `webjs help [command]` | Bare: the full USAGE banner. `webjs help <command>` prints that command's usage line, a one-line summary, an **Options** table (each flag + a universal `-h, --help` row, matching the Remix CLI's per-command Options section), and an Examples block from the `HELP` map in `bin/webjs.js` (#975), so an agent reads the exact invocation instead of guessing flags. An unknown help topic prints an error + the banner and **exits 1** (`printCommandHelp` returns false). The `--help` / `-h` FLAG forms are equivalent and handled at the top of `main()` (before the Node preflight, so they work on an old Node): `webjs --help` / `-h` prints the banner; `webjs <command> --help` / `-h` prints that command's help and short-circuits the body. Commands that forward args to an external CLI (`HELP_FLAG_PASSTHROUGH` = `typecheck` to tsc, `db` to drizzle-kit, `ui` to `@webjsdev/ui`) are excluded so the wrapped tool's own `--help` reaches it; an unrecognised command is not intercepted either, so it hits the Unknown-command error (exit 1). Tests: `test/cli/help.test.mjs` |
 
-**Per-check severity is CONFIG, not a flag (#1257), which is what lets CI gate doctor.** `--strict` is unusable in CI on its own, because four checks are environment-shaped and fatal under it (`GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, `FRAMEWORK_RESOLVE` is environment-dependent). So an app declares its policy in `package.json` under `"webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } }`, the same three-level scale ESLint uses and `eslint-plugin-next` ships as a rule-id-keyed map. `readDoctorPolicy(appDir)` reads it (PURE, returns `{ gate, unknownCodes, badSeverities, malformed, unknownKeys }`) and `applyDoctorPolicy(results, gate)` folds it over the results (PURE, returns a new array), both in `lib/doctor/policy.js` (re-exported by `lib/doctor.js`); the CHECKS stay policy-unaware and the bin composes the two. Four rules make it safe. **A code with no entry keeps its default** (`error` for a hard fail, `warn` otherwise), so an app with no `webjs.doctor` block produces byte-identical counts and the `failing = fail > 0 || (strict && warn > 0)` formula is untouched. **`severity` on a result is the EFFECTIVE level, not the declared one**, so a PASSING check reports `pass` even when its code is gated `error` and `results.some((r) => r.severity === 'error')` has no false positive. **A `bestEffort` result is CAPPED at `warn`**, so the four could-not-check branches (the two vendor-pin ones, the two importmap-coherence ones) can never be escalated and a jspm or npm outage cannot red the required job. **A malformed gate exits 1 naming the offender, without running the checks**, covering the wrong SHAPE (a non-object `doctor` or `gate`, or a misspelled sibling like `gates`) as well as an unknown code or severity, because any of them silently ignored would leave CI un-gated while looking gated, which is strictly worse than no gate since nobody goes looking. The JSON Schema catches these in an editor, and since #1300 it also runs at BOOT (`webjs-config-validate.js` in `@webjsdev/server`, called from `createRequestHandler`), but neither reach can be the enforcement here, and the boot one does not even apply. That check validates TOP-LEVEL keys only and never descends, so it says nothing at all about anything under `webjs.doctor`, whose schema type is `object`. Even if it did descend it would be the wrong tool: it warns where this gate must fail CLOSED, it runs in the server, which this CLI must work without (#954), and the schema can only express `propertyNames: { pattern: "^[A-Z][A-Z0-9_]*$" }`, so it cannot catch a well-shaped but wrong code such as `NODE_VERSIONS`, which `readDoctorPolicy` catches by checking the real `DOCTOR_CODES` set. Do not collapse the two. `off` is uniform and silences any code, the two hard-fail checks included, matching ESLint, where any rule can be turned off. The repo's own `conventions` CI job runs doctor over both in-repo apps, and `website` + `examples/blog` gate `UNMARKED_ASSET_LINKS` to `error`; the scaffold emits the same gate and its `ci.yml` runs `npm run doctor`. The config key rides the three-surface lockstep in `packages/server/AGENTS.md` (JSON Schema + `WebjsConfig` type + reader, plus the `KNOWN_KEYS` drift test), like `dev` / `start`. That file holds the one canonical reader inventory; do not restate it here.
+**Per-check severity is CONFIG, not a flag (#1257), which is what lets CI gate doctor.** `--strict` is unusable in CI on its own, because four checks are environment-shaped and fatal under it (`GIT_HOOK` wants a local pre-commit hook a runner has no reason to have, `ENV_DRIFT` compares against a `.env` CI does not carry, `VENDOR_PIN` fetches the network, `FRAMEWORK_RESOLVE` and `FRAMEWORK_LINKS` are environment-dependent). So an app declares its policy in `package.json` under `"webjs": { "doctor": { "gate": { "<CODE>": "off" | "warn" | "error" } } }`, the same three-level scale ESLint uses and `eslint-plugin-next` ships as a rule-id-keyed map. `readDoctorPolicy(appDir)` reads it (PURE, returns `{ gate, unknownCodes, badSeverities, malformed, unknownKeys }`) and `applyDoctorPolicy(results, gate)` folds it over the results (PURE, returns a new array), both in `lib/doctor/policy.js` (re-exported by `lib/doctor.js`); the CHECKS stay policy-unaware and the bin composes the two. Four rules make it safe. **A code with no entry keeps its default** (`error` for a hard fail, `warn` otherwise), so an app with no `webjs.doctor` block produces byte-identical counts and the `failing = fail > 0 || (strict && warn > 0)` formula is untouched. **`severity` on a result is the EFFECTIVE level, not the declared one**, so a PASSING check reports `pass` even when its code is gated `error` and `results.some((r) => r.severity === 'error')` has no false positive. **A `bestEffort` result is CAPPED at `warn`**, so the four could-not-check branches (the two vendor-pin ones, the two importmap-coherence ones) can never be escalated and a jspm or npm outage cannot red the required job. **A malformed gate exits 1 naming the offender, without running the checks**, covering the wrong SHAPE (a non-object `doctor` or `gate`, or a misspelled sibling like `gates`) as well as an unknown code or severity, because any of them silently ignored would leave CI un-gated while looking gated, which is strictly worse than no gate since nobody goes looking. The JSON Schema catches these in an editor, and since #1300 it also runs at BOOT (`webjs-config-validate.js` in `@webjsdev/server`, called from `createRequestHandler`), but neither reach can be the enforcement here, and the boot one does not even apply. That check validates TOP-LEVEL keys only and never descends, so it says nothing at all about anything under `webjs.doctor`, whose schema type is `object`. Even if it did descend it would be the wrong tool: it warns where this gate must fail CLOSED, it runs in the server, which this CLI must work without (#954), and the schema can only express `propertyNames: { pattern: "^[A-Z][A-Z0-9_]*$" }`, so it cannot catch a well-shaped but wrong code such as `NODE_VERSIONS`, which `readDoctorPolicy` catches by checking the real `DOCTOR_CODES` set. Do not collapse the two. `off` is uniform and silences any code, the two hard-fail checks included, matching ESLint, where any rule can be turned off. The repo's own `conventions` CI job runs doctor over both in-repo apps, and `website` + `examples/blog` gate `UNMARKED_ASSET_LINKS` to `error`; the scaffold emits the same gate and its `ci.yml` runs `npm run doctor`. The config key rides the three-surface lockstep in `packages/server/AGENTS.md` (JSON Schema + `WebjsConfig` type + reader, plus the `KNOWN_KEYS` drift test), like `dev` / `start`. That file holds the one canonical reader inventory; do not restate it here.
 
 ## UI subcommand: proxies to `@webjsdev/ui`
 
diff --git a/packages/cli/lib/doctor.js b/packages/cli/lib/doctor.js
index fd04a9672..9ba6c02ce 100644
--- a/packages/cli/lib/doctor.js
+++ b/packages/cli/lib/doctor.js
@@ -53,5 +53,5 @@
 export { DOCTOR_SEVERITIES, DOCTOR_CODES, codeForName } from './doctor/codes.js';
 export { readDoctorPolicy, applyDoctorPolicy } from './doctor/policy.js';
 export { readAppBasePath } from './doctor/route-modules.js';
-export { frameworkResolves, checkFrameworkResolves } from './doctor/probes/framework-resolves.js';
+export { frameworkResolves, checkFrameworkResolves, inspectFrameworkLink, checkFrameworkLinks } from './doctor/probes/framework-resolves.js';
 export { runDoctorChecks } from './doctor/runner.js';
diff --git a/packages/cli/lib/doctor/codes.js b/packages/cli/lib/doctor/codes.js
index c29caeb71..ebdf41fc6 100644
--- a/packages/cli/lib/doctor/codes.js
+++ b/packages/cli/lib/doctor/codes.js
@@ -42,6 +42,7 @@ export const DOCTOR_CODES = {
   'vendor-gitignore': 'VENDOR_GITIGNORE',
   'webjs-versions': 'WEBJS_VERSIONS',
   'framework-resolve': 'FRAMEWORK_RESOLVE',
+  'framework-links': 'FRAMEWORK_LINKS',
   'importmap-coherence': 'IMPORTMAP_COHERENCE',
   'git-hook': 'GIT_HOOK',
   'Page/layout elision (carrier hygiene)': 'ELISION_CARRIERS',
diff --git a/packages/cli/lib/doctor/probes/framework-resolves.js b/packages/cli/lib/doctor/probes/framework-resolves.js
index 7b99aa08e..4ce433801 100644
--- a/packages/cli/lib/doctor/probes/framework-resolves.js
+++ b/packages/cli/lib/doctor/probes/framework-resolves.js
@@ -1,5 +1,5 @@
-import { existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 
 /**
@@ -60,9 +60,7 @@ export function checkFrameworkResolves(appDir) {
         '@webjsdev/core cannot be resolved from this directory, and this is a git worktree with no ' +
         'node_modules. Git worktrees do not copy node_modules, so the framework is unresolvable here ' +
         'and `webjs dev` / `webjs start` would fail at SSR with a raw ERR_MODULE_NOT_FOUND.',
-      fix:
-        'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
-        'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`).',
+      fix: freshWorktreeFix(appDir),
     };
   }
   if (!hasNodeModules) {
@@ -79,6 +77,184 @@ export function checkFrameworkResolves(appDir) {
     message:
       '@webjsdev/core cannot be resolved from this directory even though node_modules exists ' +
       '(a partial or corrupted install).',
-    fix: 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).',
+    fix: linkAwareReinstallFix(appDir),
+  };
+}
+
+/**
+ * Whether `dir`'s own `node_modules` is a SYMLINK, which in a linked worktree
+ * means it points at the primary checkout's tree. The remedies below branch on
+ * this, because `npm install` is the right advice when it is false and is the
+ * exact command that corrupts the primary when it is true (#1442).
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function modulesAreLinked(dir) {
+  try { return lstatSync(join(dir, 'node_modules')).isSymbolicLink(); } catch { return false; }
+}
+
+/**
+ * The `npm run worktree:link` sentence, but ONLY where that script exists.
+ *
+ * This module ships in the PUBLISHED CLI, and `bin/webjs.js` prints these
+ * remedies verbatim as the `webjs dev` / `webjs start` preflight failure. A
+ * scaffolded app has no `worktree:link` script, so naming it unconditionally
+ * sends the exact audience this check exists for (#954, a fresh app worktree)
+ * to run something that does not exist. Walk up for a package.json that really
+ * declares it, and stay silent otherwise.
+ *
+ * @param {string} appDir
+ * @returns {string} a leading-space sentence, or the empty string
+ */
+function linkScriptHint(appDir) {
+  let dir = resolve(appDir);
+  for (let i = 0; i < 8; i += 1) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      if (pkg?.scripts?.['worktree:link']) {
+        return ' In this repo, `npm run worktree:link` does the whole setup and also repairs the shared tree.';
+      }
+    } catch { /* no package.json here, keep walking */ }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return '';
+}
+
+/**
+ * Remedy for the #954 fresh-worktree case, which is a worktree with NO
+ * `node_modules` at all. There is no symlink in the way yet, so a real install
+ * is safe here, and this stays the app-generic advice it has always been.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function freshWorktreeFix(appDir) {
+  return (
+    'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
+    'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`). If you symlink, ' +
+    'never run an install through that link afterwards: it acts on the checkout that owns the ' +
+    'tree, not this one (#1442).' + linkScriptHint(appDir)
+  );
+}
+
+/**
+ * Remedy for a `node_modules` that exists but does not resolve the framework.
+ * When it is a SYMLINK, a bare `npm install` is the action that corrupts the
+ * checkout that owns the tree, so the advice has to differ.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function linkAwareReinstallFix(appDir) {
+  if (modulesAreLinked(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 remove every node_modules symlink first, nested ones included ' +
+      '(`find . -maxdepth 5 -type l -name node_modules -delete`), and install here.' + linkScriptHint(appDir)
+    );
+  }
+  return 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).';
+}
+
+/**
+ * Classify the `@webjsdev/core` entry that `appDir` would resolve through.
+ *
+ * Walks up for the first `node_modules` carrying the package, then judges the
+ * link against the tree that PHYSICALLY owns that `node_modules`. That owner
+ * rule is the only one correct in a linked worktree: there `node_modules` is
+ * itself a symlink at the primary's, so the owning tree is the PRIMARY and a
+ * target inside it is right rather than foreign. Judging against `appDir` would
+ * report every correctly linked worktree as corrupted.
+ *
+ * @param {string} appDir
+ * @param {string} [pkg]
+ * @returns {{ state: 'absent'|'real'|'ok'|'dangling'|'foreign', entry?: string, target?: string, owner?: string }}
+ */
+export function inspectFrameworkLink(appDir, pkg = '@webjsdev/core') {
+  const parts = pkg.split('/');
+  let dir = resolve(appDir);
+  for (;;) {
+    const modules = join(dir, 'node_modules');
+    const entry = join(modules, ...parts);
+    let st = null;
+    try { st = lstatSync(entry); } catch { st = null; }
+    if (st) {
+      if (!st.isSymbolicLink()) return { state: 'real', entry };
+      let target = '';
+      try { target = readlinkSync(entry); } catch { return { state: 'real', entry }; }
+      // Resolve the target against the directory the link PHYSICALLY sits in,
+      // which is what the OS does. In a linked worktree `node_modules` is itself
+      // a symlink, so the lexical `dirname(entry)` is under the WORKTREE while
+      // the link really lives in the primary. Resolving lexically turns every
+      // correct `../../packages/core` into a worktree path and reports a healthy
+      // linked worktree as `foreign`.
+      let base = dirname(entry);
+      try { base = realpathSync(base); } catch { /* fall back to the lexical path */ }
+      const abs = resolve(base, target);
+      let owner = dir;
+      try { owner = dirname(realpathSync(modules)); } catch { /* use dir as given */ }
+      if (!existsSync(abs)) return { state: 'dangling', entry, target, owner };
+      let real = abs;
+      try { real = realpathSync(abs); } catch { /* compare the unresolved path */ }
+      let ownerReal = owner;
+      try { ownerReal = realpathSync(owner); } catch { /* compare as given */ }
+      if (real !== ownerReal && !real.startsWith(ownerReal + sep)) {
+        return { state: 'foreign', entry, target, owner: ownerReal };
+      }
+      return { state: 'ok', entry, target, owner: ownerReal };
+    }
+    const up = dirname(dir);
+    if (up === dir) return { state: 'absent' };
+    dir = up;
+  }
+}
+
+/**
+ * CHECK: framework link integrity (#1442). WARN when the `@webjsdev/core` entry
+ * in node_modules is a symlink that DANGLES or resolves OUTSIDE the tree that
+ * owns it. That is what an install run inside a linked worktree leaves behind,
+ * and it is invisible to the framework-resolve check above, which only asks
+ * whether the package resolves at all: a link into a live FOREIGN checkout
+ * resolves perfectly and silently runs another branch's framework source.
+ *
+ * Silent PASS for a real directory, a correct link, and no entry at all, so a
+ * normally installed app pays one `lstat`. WARN rather than fail, the same
+ * environment tier as the framework-resolve and version-coherence checks.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkFrameworkLinks(appDir) {
+  const name = 'framework-links';
+  const r = inspectFrameworkLink(appDir);
+  if (r.state === 'absent' || r.state === 'real' || r.state === 'ok') {
+    return {
+      name,
+      status: 'pass',
+      message: 'The @webjsdev framework links resolve inside the checkout that owns them.',
+    };
+  }
+  const fix =
+    'Repoint the entry at the package inside the checkout that owns this node_modules. Do NOT run ' +
+    '`npm install` here while node_modules is a symlink: it acts on that owning checkout, not this ' +
+    'one (#1442).' + linkScriptHint(appDir);
+  if (r.state === 'dangling') {
+    return {
+      name,
+      status: 'warn',
+      message:
+        `${r.entry} is a symlink to ${r.target}, which does not exist. An install run inside a linked ` +
+        'worktree leaves these behind, and the worktree it named has since been removed.',
+      fix,
+    };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${r.entry} is a symlink to ${r.target}, which resolves OUTSIDE ${r.owner}, the checkout that ` +
+      'owns this node_modules. It resolves fine, so nothing fails, and the framework source being run ' +
+      "is another checkout's. A deliberate `npm link` produces the same shape.",
+    fix,
   };
 }
diff --git a/packages/cli/lib/doctor/runner.js b/packages/cli/lib/doctor/runner.js
index c19f86a1f..54b42e1b2 100644
--- a/packages/cli/lib/doctor/runner.js
+++ b/packages/cli/lib/doctor/runner.js
@@ -10,7 +10,7 @@ import { checkGitHook } from './probes/git-hook.js';
 import { checkElisionCarriers, checkElisionComponents } from './probes/elision.js';
 import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
 import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
-import { checkFrameworkResolves } from './probes/framework-resolves.js';
+import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
 
 /**
  * @typedef {import('./codes.js').DoctorResult} DoctorResult
@@ -57,6 +57,7 @@ export async function runDoctorChecks(appDir, opts = {}) {
     checkVendorGitignore(appDir),
     checkWebjsVersions(appDir),
     Promise.resolve(checkFrameworkResolves(appDir)),
+    Promise.resolve(checkFrameworkLinks(appDir)),
     checkImportmapCoherence(appDir, opts),
     Promise.resolve(checkGitHook(appDir)),
     checkElisionCarriers(elision),
diff --git a/scripts/link-worktree-deps.mjs b/scripts/link-worktree-deps.mjs
index 6b2afbc61..e7c2fc168 100644
--- a/scripts/link-worktree-deps.mjs
+++ b/scripts/link-worktree-deps.mjs
@@ -34,19 +34,35 @@
  *
  * 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, run a real `npm install` in the worktree, 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 5 -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
+ * link before any lifecycle script runs, `bun install` writes packages into the
+ * primary through it, and `npm install` silently replaces the link with a real
+ * tree. All three land on a checkout you are not working in, so the failure
+ * surfaces in someone else's session with nothing naming the cause.
  *
  * Safety rules, all of which exist because the naive version of this script
  * broke a worktree while it was being written:
  *
- * - Never delete or overwrite anything. A path that already exists is left
+ * - Never delete or overwrite anything, with ONE exception: the repair pass over
+ *   `<primary>/node_modules/@webjsdev/` replaces a link that is ALREADY wrong
+ *   (dangling, or resolving outside the primary) and removes a DANGLING
+ *   `.name-HASH` npm staging entry. It never touches a real directory, never
+ *   touches a link that is already correct, and never removes a staging entry
+ *   that still resolves. Outside that pass, a path that already exists is left
  *   alone, so a worktree with a real `npm install` is untouched and re-running
  *   is a no-op.
  * - Never create a dangling link. A source that does not exist is skipped,
  *   because a dangling `node_modules` resolves more confusingly than a missing
- *   one.
+ *   one, and the repair pass declines to repoint when the corrected target is
+ *   missing.
  * - Never treat `<primary>/node_modules` itself as a search root. Descending
  *   into it yields thousands of nested `node_modules` belonging to third-party
  *   packages, none of which should be linked.
@@ -55,10 +71,12 @@
  *
  *   node scripts/link-worktree-deps.mjs           # link from the default primary
  *   node scripts/link-worktree-deps.mjs <primary> # or name it explicitly
+ *   node scripts/link-worktree-deps.mjs --check   # report repairs, change nothing
  *   npm run worktree:link
+ *   npm run check:worktree-links
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 
 /** Directory names never worth descending into when hunting for nested trees. */
@@ -110,6 +128,158 @@ function link(src, dst, label) {
   return 'linked';
 }
 
+/**
+ * Map every workspace package NAME to its directory, relative to `primary`.
+ *
+ * The mapping cannot be derived from the entry name. `@webjsdev/example-blog`
+ * lives at `examples/blog`, `@webjsdev/ui-registry` at
+ * `packages/ui/packages/registry`, and `@webjsdev/intellisense` at
+ * `packages/editors/intellisense`, so a `packages/<name>` guess would repoint
+ * half the tree at directories that do not exist.
+ *
+ * @param {string} primary
+ * @returns {Map<string, string>} package name to directory relative to `primary`
+ */
+function workspacePackageDirs(primary) {
+  /** @type {Map<string, string>} */
+  const out = new Map();
+  /** @type {string[]} */
+  let patterns = [];
+  try {
+    patterns = JSON.parse(readFileSync(join(primary, 'package.json'), 'utf8')).workspaces || [];
+  } catch { return out; }
+
+  /** @type {string[]} */
+  const dirs = [];
+  for (const pattern of patterns) {
+    if (!pattern.endsWith('/*')) { dirs.push(pattern); continue; }
+    const parent = pattern.slice(0, -2);
+    let entries;
+    try { entries = readdirSync(join(primary, parent), { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) if (e.isDirectory()) dirs.push(`${parent}/${e.name}`);
+  }
+
+  for (const rel of dirs) {
+    try {
+      const name = JSON.parse(readFileSync(join(primary, rel, 'package.json'), 'utf8')).name;
+      if (typeof name === 'string' && name) out.set(name, rel);
+    } catch { /* not a package, skip */ }
+  }
+  return out;
+}
+
+/** npm's staging name for a package it is mid-reify on, `.name-HASH`. */
+const STAGING = /^\.(.+)-[A-Za-z0-9_-]{8}$/;
+
+/**
+ * Repair `<primary>/node_modules/@webjsdev/`, which an install run inside a
+ * LINKED worktree corrupts (#1442).
+ *
+ * Three defect classes, all produced by the same accident and all repaired to
+ * the same relative form the healthy tree uses:
+ *
+ * - a link that DANGLES, usually into a worktree that has since been removed;
+ * - a link that resolves OUTSIDE the primary, into a live foreign checkout,
+ *   which is the worst case because it resolves fine and silently runs another
+ *   branch's framework source;
+ * - a link that resolves inside the primary but is ABSOLUTE where every sibling
+ *   is relative, which is the same corruption pattern pointing at the right
+ *   place by accident.
+ *
+ * A LIVE `.name-HASH` staging entry is left strictly alone. Most of them resolve
+ * to real in-repo directories, nothing imports `@webjsdev/.ui-tVBcnl39`, at least
+ * one predates a package rename so its name maps to no current workspace, and
+ * deleting a live entry risks racing an install that is mid-reify. Only an
+ * UNUSABLE one, meaning staging-shaped AND dangling, is removed.
+ *
+ * Writes are atomic (symlink to a temp name, then rename over), because
+ * `npm test` resolves `@webjsdev/*` from many processes at once and an entry
+ * that briefly does not exist would fail one of them.
+ *
+ * @param {string} primary
+ * @param {{ check?: boolean }} [opts] `check` reports without changing anything
+ * @returns {{ repaired: string[], removed: string[], reported: string[] }}
+ */
+function repairPrimaryFrameworkLinks(primary, opts = {}) {
+  const check = opts.check === true;
+  const scope = join(primary, 'node_modules', '@webjsdev');
+  /** @type {{ repaired: string[], removed: string[], reported: string[] }} */
+  const out = { repaired: [], removed: [], reported: [] };
+
+  let entries;
+  try { entries = readdirSync(scope, { withFileTypes: true }); } catch { return out; }
+
+  let primaryReal = primary;
+  try { primaryReal = realpathSync(primary); } catch { /* use it as given */ }
+  const workspaces = workspacePackageDirs(primary);
+  const removeVerb = check ? 'would remove' : 'removed';
+  const pointVerb = check ? 'would repoint' : 'repointed';
+
+  for (const e of entries) {
+    // A real directory here is somebody's deliberate install, never ours to touch.
+    if (!e.isSymbolicLink()) continue;
+
+    const entry = join(scope, e.name);
+    let target;
+    try { target = readlinkSync(entry); } catch { continue; }
+    const absTarget = resolve(scope, target);
+    const dangling = !existsSync(absTarget);
+
+    if (STAGING.test(e.name)) {
+      if (!dangling) continue;
+      if (!check) { try { rmSync(entry, { force: true }); } catch { continue; } }
+      out.removed.push(e.name);
+      console.log(`[link-worktree-deps] ${removeVerb} dangling npm staging entry @webjsdev/${e.name}`);
+      continue;
+    }
+
+    const rel = workspaces.get(`@webjsdev/${e.name}`);
+    if (!rel) {
+      if (!dangling) continue;
+      out.reported.push(e.name);
+      console.log(`[link-worktree-deps] @webjsdev/${e.name} dangles and matches no workspace package; left alone.`);
+      continue;
+    }
+
+    const correct = join(primary, rel);
+    const desired = relative(scope, correct);
+    if (target === desired) continue;
+
+    let outside = false;
+    try { outside = !realpathSync(absTarget).startsWith(primaryReal + sep); } catch { outside = true; }
+    if (!dangling && !outside && !isAbsolute(target)) continue;
+
+    // A race guard, not a normal path: `workspacePackageDirs()` only maps a
+    // package whose `package.json` it just read, so `correct` exists unless the
+    // directory went away in between. Repointing at a missing path would trade
+    // one dangling link for another, which the safety rules forbid outright.
+    if (!existsSync(correct)) {
+      out.reported.push(e.name);
+      console.log(`[link-worktree-deps] @webjsdev/${e.name} points at ${target}, but ${rel} is missing here; left alone.`);
+      continue;
+    }
+
+    if (!check) {
+      const tmp = `${entry}.tmp-${process.pid}`;
+      try {
+        rmSync(tmp, { force: true });
+        symlinkSync(desired, tmp);
+        renameSync(tmp, entry);
+      } catch {
+        try { rmSync(tmp, { force: true }); } catch { /* nothing staged */ }
+        out.reported.push(e.name);
+        console.log(`[link-worktree-deps] could not repair @webjsdev/${e.name}; left alone.`);
+        continue;
+      }
+    }
+    out.repaired.push(e.name);
+    const why = dangling ? 'dangling' : (outside ? 'foreign' : 'absolute');
+    console.log(`[link-worktree-deps] ${pointVerb} ${why} @webjsdev/${e.name} -> ${desired}`);
+  }
+
+  return out;
+}
+
 /** @returns {string} absolute path of the primary checkout */
 function defaultPrimary() {
   // `--git-common-dir` is `<primary>/.git` from ANY worktree, linked or not
@@ -223,17 +393,49 @@ async function seedBlogDatabase(blogDir) {
 }
 
 const here = process.cwd();
-const primary = resolve(process.argv[2] || defaultPrimary());
+const CHECK = process.argv.includes('--check');
+// Filter the flag out of the positional argument, or `resolve('--check')` is
+// read as the primary path and the script reports on a directory named `--check`.
+const positional = process.argv.slice(2).filter((a) => a !== '--check');
+const primary = resolve(positional[0] || defaultPrimary());
 
-if (primary === here) {
-  console.log('[link-worktree-deps] this IS the primary checkout, nothing to link.');
-  process.exit(0);
-}
+// The checkout check sits ABOVE the primary-is-here guard, because the repair
+// below targets the PRIMARY and must run whether or not this checkout is it.
 if (!existsSync(join(primary, 'package.json'))) {
   console.error(`[link-worktree-deps] not a checkout: ${primary}`);
   process.exit(1);
 }
 
+// FIRST, so `npm run worktree:link` heals the primary from a worktree AND a bare
+// run or `--check` heals it from the primary itself. `WEBJS_NO_WORKTREE_REPAIR=1`
+// is why the `defaultPrimary()` test can run this against the real checkout
+// without mutating it, exactly as `WEBJS_NO_WORKTREE_SEED=1` does for seeding.
+let touched = 0;
+// The hatch suppresses the repair WRITE. `--check` never writes, so there is
+// nothing for it to suppress there, and skipping the inspection too would make
+// `check:worktree-links` exit 0 reporting a clean tree it never looked at.
+if (process.env.WEBJS_NO_WORKTREE_REPAIR === '1' && !CHECK) {
+  console.log('[link-worktree-deps] framework-link repair skipped (WEBJS_NO_WORKTREE_REPAIR=1).');
+} else {
+  const repair = repairPrimaryFrameworkLinks(primary, { check: CHECK });
+  touched = repair.repaired.length + repair.removed.length;
+  if (CHECK) {
+    console.log(`[link-worktree-deps] --check: ${touched} entr${touched === 1 ? 'y' : 'ies'} to repair, ${repair.reported.length} reported.`);
+  }
+}
+
+// `--check` is READ-ONLY and TERMINAL, unconditionally. This exit sits OUTSIDE
+// the branch above on purpose: nested inside the `else`, a run with BOTH
+// `--check` and `WEBJS_NO_WORKTREE_REPAIR=1` fell through to the linking loop
+// and the seed step, so the one combination documented as changing nothing was
+// the one that wrote. Linking is a mutation, so `--check` must never reach it.
+if (CHECK) process.exit(touched > 0 ? 1 : 0);
+
+if (primary === here) {
+  console.log('[link-worktree-deps] this IS the primary checkout, nothing to link.');
+  process.exit(0);
+}
+
 console.log(`[link-worktree-deps] linking from ${primary}`);
 
 let linked = 0;
diff --git a/scripts/warn-worktree-install.mjs b/scripts/warn-worktree-install.mjs
new file mode 100644
index 000000000..b2b105885
--- /dev/null
+++ b/scripts/warn-worktree-install.mjs
@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Root `preinstall` reporter: name what an install in a LINKED worktree just did
+ * to the PRIMARY checkout's `node_modules` (#1442).
+ *
+ * ## This reports, it never blocks, and that is deliberate
+ *
+ * Measured on npm 11.19.0 and bun 1.3.14, a `preinstall` script cannot PREVENT
+ * the damage, so trying to make it a guard would be a guard in name only:
+ *
+ * - Under `npm install`, `preinstall` runs with `node_modules` ALREADY a real
+ *   directory. npm replaced the symlink before the script started, so a
+ *   `lstatSync('node_modules').isSymbolicLink()` check can never be true here.
+ * - Under `npm ci`, `preinstall` runs with the primary's `node_modules` ALREADY
+ *   emptied. npm deletes the link's TARGET first, so the destruction precedes
+ *   any chance to stop it.
+ * - Under `bun install` / `bun add`, `preinstall` runs BEFORE the write and does
+ *   see the symlink, but a non-zero exit does not stop Bun (measured: `bun
+ *   install` exited 0 with a `preinstall` that exited 2).
+ * - A non-zero `preinstall` DOES block `npm install` and `npm ci`, exit code
+ *   propagated verbatim, so a buggy guard here would red every CI job. The same
+ *   reasoning is already written into `scripts/git-worktree-safe.mjs`.
+ *
+ * Blocking `npm install` would also leave the worktree with no symlink and a
+ * half-built tree, which is worse than what it prevented. So the prevention
+ * lives in `.claude/hooks/block-install-in-linked-worktree.sh`, which is the only
+ * layer that runs before the package manager, and this script turns a silent
+ * detach or a silently emptied primary into a named diagnosis with the repair.
+ *
+ * Silent and exit 0 in a normal clone, which is what CI has, because the first
+ * thing it checks is whether `.git` is a FILE (the linked-worktree marker).
+ */
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/** @param {string} msg */
+const say = (msg) => console.error(`[warn-worktree-install] ${msg}`);
+
+/**
+ * Whether `dir` exists and holds at least one entry.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function hasEntries(dir) {
+  try { return readdirSync(dir).length > 0; } catch { return false; }
+}
+
+try {
+  // A linked worktree checks out `.git` as a FILE (a gitdir pointer). A normal
+  // clone and the primary checkout both have a DIRECTORY, so they return here
+  // and CI is untouched by construction.
+  if (!statSync('.git').isFile()) process.exit(0);
+
+  // `--git-common-dir` is `<primary>/.git` from any worktree, so the primary is
+  // its parent. Same derivation as `defaultPrimary()` in link-worktree-deps.mjs.
+  const common = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    encoding: 'utf8',
+  }).trim();
+  const primary = resolve(dirname(common));
+  const primaryModules = join(primary, 'node_modules');
+
+  let linkStillStanding = false;
+  let haveOwnModules = false;
+  try {
+    const st = lstatSync('node_modules');
+    linkStillStanding = st.isSymbolicLink();
+    haveOwnModules = st.isDirectory();
+  } catch { /* no node_modules yet, nothing to report */ }
+
+  if (linkStillStanding) {
+    // The Bun shape: the link is intact, so the write is still ahead of us.
+    say('this worktree\'s node_modules is a SYMLINK at the primary checkout:');
+    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('remove EVERY node_modules symlink first (the link script plants nested ones too:');
+    say('`find . -maxdepth 5 -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:');
+    say(`  ${primaryModules}`);
+    say('An `npm ci` here deleted it through this worktree\'s node_modules symlink.');
+    say(`Repair it with:  cd ${primary} && npm install`);
+    say('Every other checkout resolving through the primary is broken until you do.');
+  } else if (haveOwnModules) {
+    // The `npm install` aftermath: the symlink was replaced by a real tree.
+    say('this worktree now has its OWN node_modules, so the symlink at the primary');
+    say('checkout is gone and the worktree no longer runs the primary\'s framework source.');
+    say('That is fine if you meant it. To go back to the shared tree:');
+    say('  rm -rf node_modules && npm run worktree:link');
+  }
+} catch {
+  // Never let a reporter break an install. Any failure here is silence.
+}
+
+process.exit(0);
diff --git a/test/architecture/barrel-surface.test.mjs b/test/architecture/barrel-surface.test.mjs
index d77faf43f..b9f4c558b 100644
--- a/test/architecture/barrel-surface.test.mjs
+++ b/test/architecture/barrel-surface.test.mjs
@@ -7,7 +7,7 @@ const BARREL_FLOORS = [
   { path: '../../packages/server/src/vendor.js', floor: 26 },
   { path: '../../packages/server/src/ssr.js', floor: 21 },
   { path: '../../packages/server/src/dev.js', floor: 16 },
-  { path: '../../packages/cli/lib/doctor.js', floor: 9 },
+  { path: '../../packages/cli/lib/doctor.js', floor: 11 },
   { path: '../../packages/core/src/render-server.js', floor: 2 },
   { path: '../../packages/core/src/component.js', floor: 2 },
   { path: '../../packages/server/src/check.js', floor: 2 },
diff --git a/test/cli/doctor.test.mjs b/test/cli/doctor.test.mjs
index 1bcf93aaa..401044d5c 100644
--- a/test/cli/doctor.test.mjs
+++ b/test/cli/doctor.test.mjs
@@ -16,7 +16,7 @@
 import { test, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync, utimesSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, utimesSync, symlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -1797,3 +1797,137 @@ test('asset-link advisory is not confused by balanced CSS comments in a style bl
   assert.equal(r.status, 'warn');
   assert.match(r.message, /after\.css/);
 });
+
+// ---------------------------------------------------------------------------
+// framework LINK integrity (#1442): an install run inside a linked worktree
+// corrupts the primary's `@webjsdev/*` links. The framework-resolve check above
+// cannot see it, because a link into a live FOREIGN checkout resolves fine.
+// ---------------------------------------------------------------------------
+const { inspectFrameworkLink, checkFrameworkLinks } = await import(
+  resolve(CLI_LIB_DIR, 'doctor.js')
+);
+
+/** An app dir with `node_modules/@webjsdev/core` planted as `plant` describes. */
+function linkFixture(plant) {
+  const dir = tmpDir();
+  write(dir, 'package.json', JSON.stringify({ name: 'x' }));
+  mkdirSync(join(dir, 'node_modules', '@webjsdev'), { recursive: true });
+  mkdirSync(join(dir, 'packages', 'core'), { recursive: true });
+  write(dir, 'packages/core/package.json', '{"name":"@webjsdev/core"}');
+  plant(dir);
+  return dir;
+}
+
+test('framework-links PASSES when @webjsdev/core is a real directory', () => {
+  const dir = linkFixture((d) => {
+    mkdirSync(join(d, 'node_modules', '@webjsdev', 'core'), { recursive: true });
+  });
+  assert.equal(inspectFrameworkLink(dir).state, 'real');
+  assert.equal(checkFrameworkLinks(dir).status, 'pass');
+});
+
+test('framework-links PASSES when the link resolves inside the tree that owns node_modules', () => {
+  const dir = linkFixture((d) => {
+    symlinkSync('../../packages/core', join(d, 'node_modules', '@webjsdev', 'core'));
+  });
+  assert.equal(inspectFrameworkLink(dir).state, 'ok');
+  assert.equal(checkFrameworkLinks(dir).status, 'pass');
+});
+
+test('framework-links PASSES through a SYMLINKED node_modules, the linked-worktree shape', () => {
+  // The no-false-positive case, and the one that caught a real bug: through a
+  // symlinked node_modules the link's LEXICAL directory is under the worktree
+  // while the link physically lives in the primary, so resolving `../../` the
+  // lexical way reports every healthy linked worktree as `foreign`.
+  const primary = linkFixture((d) => {
+    symlinkSync('../../packages/core', join(d, 'node_modules', '@webjsdev', 'core'));
+  });
+  const worktree = tmpDir();
+  write(worktree, 'package.json', JSON.stringify({ name: 'wt' }));
+  mkdirSync(join(worktree, 'packages', 'core'), { recursive: true });
+  symlinkSync(join(primary, 'node_modules'), join(worktree, 'node_modules'));
+
+  assert.equal(inspectFrameworkLink(worktree).state, 'ok');
+  assert.equal(checkFrameworkLinks(worktree).status, 'pass');
+});
+
+test('framework-links WARNS when the link DANGLES', () => {
+  const dir = linkFixture((d) => {
+    symlinkSync('/nonexistent/removed-worktree/packages/core', join(d, 'node_modules', '@webjsdev', 'core'));
+  });
+  assert.equal(inspectFrameworkLink(dir).state, 'dangling');
+  const r = checkFrameworkLinks(dir);
+  assert.equal(r.status, 'warn');
+  assert.match(r.fix, /owns this node_modules|owning checkout/);
+  assert.match(r.fix, /do NOT run `npm install`/i);
+});
+
+test('framework-links WARNS when the link resolves OUTSIDE the owning tree', () => {
+  const foreign = tmpDir();
+  mkdirSync(join(foreign, 'packages', 'core'), { recursive: true });
+  // A RESOLVABLE package, so the assertion below can show that
+  // `frameworkResolves` is perfectly happy with a link into a foreign checkout.
+  writeFileSync(join(foreign, 'packages', 'core', 'package.json'), '{"name":"@webjsdev/core","main":"index.js"}');
+  writeFileSync(join(foreign, 'packages', 'core', 'index.js'), 'export {};');
+  const dir = linkFixture((d) => {
+    symlinkSync(join(foreign, 'packages', 'core'), join(d, 'node_modules', '@webjsdev', 'core'));
+  });
+  assert.equal(inspectFrameworkLink(dir).state, 'foreign');
+  const r = checkFrameworkLinks(dir);
+  assert.equal(r.status, 'warn');
+  // It resolves fine, so the resolve check cannot see it. That is the point.
+  assert.equal(frameworkResolves(dir), true);
+  assert.match(r.message, /resolves OUTSIDE/);
+});
+
+test('framework-links PASSES when there is no @webjsdev entry at all', () => {
+  const dir = tmpDir();
+  write(dir, 'package.json', JSON.stringify({ name: 'x' }));
+  assert.equal(checkFrameworkLinks(dir).status, 'pass');
+});
+
+test('framework-resolve stops recommending a bare npm install through a symlink', () => {
+  // node_modules exists as a SYMLINK but carries no @webjsdev/core, so the
+  // resolve check falls into its corrupted-install branch. Recommending
+  // `npm install` there is what caused #1442 in the first place.
+  const target = tmpDir();
+  mkdirSync(join(target, 'node_modules'), { recursive: true });
+  const dir = tmpDir();
+  write(dir, 'package.json', JSON.stringify({ name: 'x' }));
+  symlinkSync(join(target, 'node_modules'), join(dir, 'node_modules'));
+
+  const r = checkFrameworkResolves(dir);
+  assert.equal(r.status, 'warn');
+  assert.match(r.fix, /do NOT run `npm install`/);
+  assert.match(r.fix, /checkout that owns the tree/);
+});
+
+test('the published-CLI remedies never name a script a scaffolded app does not have', () => {
+  // These strings ship in the published CLI, and `bin/webjs.js` prints them
+  // verbatim as the `webjs dev` / `webjs start` preflight failure. The #954
+  // audience is a scaffolded APP worktree, which has no `worktree:link` script,
+  // so naming it there sends the user to run something that does not exist.
+  const app = tmpDir();
+  write(app, 'package.json', JSON.stringify({ name: 'my-app', scripts: { dev: 'webjs dev' } }));
+  write(app, '.git', 'gitdir: /somewhere/.git/worktrees/x');
+
+  const fresh = checkFrameworkResolves(app);
+  assert.equal(fresh.status, 'warn');
+  assert.doesNotMatch(fresh.fix, /worktree:link/, 'no monorepo-only script for a scaffolded app');
+  assert.match(fresh.fix, /npm install/, 'a fresh worktree with no symlink CAN just install');
+
+  // The same repo, once it DOES declare the script, may name it.
+  const mono = tmpDir();
+  write(mono, 'package.json', JSON.stringify({ name: 'repo', scripts: { 'worktree:link': 'node x.mjs' } }));
+  write(mono, '.git', 'gitdir: /somewhere/.git/worktrees/y');
+  assert.match(checkFrameworkResolves(mono).fix, /worktree:link/);
+});
+
+test('framework-links is wired into the runner and carries its declared code', async () => {
+  const dir = tmpDir();
+  write(dir, 'package.json', JSON.stringify({ name: 'x' }));
+  const results = await runDoctorChecks(dir, baseOpts({ nodeVersion: '24.0.0' }));
+  const r = results.find((x) => x.name === 'framework-links');
+  assert.ok(r, 'the check runs');
+  assert.equal(r.code, 'FRAMEWORK_LINKS');
+});
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
new file mode 100644
index 000000000..1059325bd
--- /dev/null
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -0,0 +1,508 @@
+// The block-install-in-linked-worktree hook refuses a package-manager install
+// aimed at a directory whose `node_modules` is a SYMLINK, because the write
+// lands in the checkout that OWNS the tree rather than in this one (#1442).
+// It must stay narrow: the commands an agent actually runs in a worktree
+// (`npm test`, `npm run <script>`, `npx ...`) have to pass.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync, execSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HOOK = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '../../.claude/hooks/block-install-in-linked-worktree.sh'
+);
+
+/**
+ * Run the hook with `command` as the Bash tool input, from `cwd`.
+ * The escape hatch is pinned OFF so an inherited value in the invoking
+ * environment cannot silently flip a block assertion into a pass.
+ */
+function runHook(command, cwd, env = {}) {
+  return spawnSync('bash', [HOOK], {
+    input: JSON.stringify({ tool_input: { command } }),
+    cwd,
+    env: { ...process.env, WEBJS_NO_WORKTREE_INSTALL_GATE: '0', ...env },
+    encoding: 'utf8',
+  });
+}
+
+/**
+ * A primary checkout with a real `node_modules`, plus a sibling worktree whose
+ * `node_modules` is a symlink at it. That is exactly what `npm run worktree:link`
+ * produces and what an install must never be allowed to write through.
+ */
+function makeLinkedPair() {
+  const root = mkdtempSync(join(tmpdir(), 'install-gate-'));
+  const primary = join(root, 'primary');
+  const worktree = join(root, 'worktree');
+  mkdirSync(join(primary, 'node_modules'), { recursive: true });
+  mkdirSync(worktree, { recursive: true });
+  writeFileSync(join(primary, 'package.json'), '{"name":"primary"}\n');
+  writeFileSync(join(worktree, 'package.json'), '{"name":"worktree"}\n');
+  symlinkSync(join(primary, 'node_modules'), join(worktree, 'node_modules'));
+  return { root, primary, worktree };
+}
+
+test('blocks `cd <worktree> && npm ci`, naming the owning checkout and the safe alternative', () => {
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    const r = runHook(`cd ${worktree} && npm ci`, root);
+    assert.equal(r.status, 2, `expected block, got ${r.status}: ${r.stderr}`);
+    assert.match(r.stderr, /node_modules is a SYMLINK/);
+    assert.ok(r.stderr.includes(join(primary, 'node_modules')), 'names the owning tree');
+    assert.match(r.stderr, /npm run worktree:link/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks a bare `npm install` run from inside the linked worktree', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('npm install', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks `bun add`, which writes THROUGH the link rather than replacing it', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('bun add nanoid', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks the flags-before-verb form `npm --prefix <worktree> install`', () => {
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    // Run it from the PRIMARY, so the only thing naming the worktree is the flag.
+    assert.equal(runHook(`npm --prefix ${worktree} install`, primary).status, 2);
+    assert.equal(runHook(`npm install --prefix ${worktree}`, primary).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks every manager\'s install ALIAS, not just the canonical spelling', () => {
+  // A gate `bun i` walks past is worthless, and Bun is the manager that writes
+  // THROUGH the symlink into the primary rather than replacing it, so its
+  // aliases are the consequential ones. `yarn` bare is an install in yarn classic.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      'npm i', 'npm in', 'npm ic', 'npm it', 'npm clean-install', 'npm update',
+      'bun i', 'bun a nanoid', 'pnpm i', 'yarn', 'yarn --frozen-lockfile', 'yarn add x',
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks the HYPHENATED npm verbs, which the short aliases do not cover', () => {
+  // The trailing word boundary excludes `-`, so listing `install` does not reach
+  // `install-test`. Each hyphenated command needs its own entry.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['npm install-test', 'npm install-ci-test', 'npm clean-install-test', 'npm clean-install', 'npm install-clean']) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('blocks the REMOVE verbs, which delete from the owning checkout', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    // `npm r` and `npm a` are deliberately NOT in npm's table: they are rare as
+    // commands and common as flag VALUES, and the scan cannot tell the two
+    // apart, so admitting them blocks `npm -w a run build`. A documented gap.
+    for (const cmd of ['npm uninstall x', 'npm rm x', 'npm unlink x', 'bun rm x', 'pnpm rm x', 'yarn remove x', 'pnpm upgrade', 'pnpm dedupe', 'yarn dedupe']) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('judges a COMMAND, never a token that merely appears in the line', () => {
+  // This is the whole design of the matcher. An earlier version matched the
+  // manager token anywhere, which blocked this PR's own commit subject. Every
+  // worktree here is a linked worktree, so that fires on ordinary commands
+  // constantly, and a gate that cries wolf is a gate someone turns off.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      'git commit -m "fix: npm install in a linked worktree corrupts node_modules"',
+      'gh pr create --title "fix: npm install in a linked worktree" --body x',
+      'grep -rn "npm ci" AGENTS.md',
+      'git log --grep "npm install"',
+      'echo "the hook blocks npm rm x too"',
+      'rg "bun add" .',
+      'cat README | grep yarn',
+      // A shell metacharacter INSIDE the quoted text. Splitting the raw command
+      // makes the tail look like its own command, so each of these read as an
+      // install. Quoted spans are removed before the split for exactly this.
+      'git commit -m "fix: guard the link; npm install now blocks"',
+      'git commit -m "fix: cd wt && npm ci corrupts the primary"',
+      'gh pr create --body "| npm install | replaces the symlink |"',
+      'echo "run (npm ci) to reproduce"',
+      "git log --grep 'npm install'",
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('never blocks a GLOBAL install, which writes to the npm prefix not the link', () => {
+  // `npm update -g webjsdev` is this repo's documented post-release step, and a
+  // linked worktree is the mandated working state, so blocking it would refuse a
+  // workflow the repo requires over a corruption that cannot occur.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['npm update -g webjsdev', 'npm uninstall -g webjsdev', 'bun add -g webjsdev', 'npm i --global webjsdev']) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+    // ...but the same verb WITHOUT -g still blocks, so the carve-out is narrow.
+    assert.equal(runHook('npm update webjsdev', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('still sees the install through env assignments and benign wrappers', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      'WEBJS_X=1 npm ci', 'sudo npm ci', 'time npm install', 'FOO=a BAR=b bun install',
+      // A wrapper carrying its OWN flags, which the strip must walk past.
+      'sudo -u foo npm ci', 'nice -n 10 npm install',
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+    // `command`, `exec`, `bash` and `sh` are deliberately NOT wrappers. Walking
+    // into a nested shell command re-creates the token-anywhere class one level
+    // in, where `bash -c "echo yarn"` reaches the bare-yarn branch. So a lookup
+    // stays allowed, and `bash -c "npm ci"` is a known accepted gap.
+    assert.equal(runHook('command -v yarn', worktree).status, 0);
+    assert.equal(runHook('bash -c "echo yarn"', worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('an `=` in a FLAG does not disable the gate (fail-open regression)', () => {
+  // The env-assignment strip is anchored to the FIRST token. An unanchored
+  // `[A-Za-z_]*=*` case glob matches the WHOLE segment whenever any LATER token
+  // carries an `=`, so it ate the leading words and every one of these was
+  // ALLOWED, which is the one direction that actually matters: the gate exists
+  // to stop a write, and `npm install --workspace=packages/core` is an ordinary
+  // command in this monorepo that corrupts the primary.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      'npm install --omit=dev',
+      'npm ci --loglevel=error',
+      'npm install --workspace=packages/core',
+      'bun install --backend=hardlink',
+      'yarn add x --registry=https://r',
+      'npm i -D esbuild --foreground-scripts=true',
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('the --prefix= EQUALS form is reachable, not just the space form', () => {
+  // The regexes carry `[[:space:]=]+` deliberately, and the pre-existing prefix
+  // test used only the space form, so the equals branch was dead while green.
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook(`npm --prefix=${worktree} install`, primary).status, 2);
+    assert.equal(runHook(`npm install --prefix=${worktree}`, primary).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('bare `yarn` blocks only in COMMAND position, never as a trailing word', () => {
+  // The bare-yarn branch first lived inside the generic VERBS pattern, whose
+  // prefix any space satisfies, so it matched the token ANYWHERE and blocked
+  // `which yarn`, `rm -rf /tmp/yarn` and `git switch -c feat/yarn`. That fires
+  // on ordinary commands in a linked worktree, which is the mandated state here,
+  // and a gate that cries wolf gets turned off.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['yarn', 'yarn --frozen-lockfile', 'cd . && yarn']) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+    for (const cmd of [
+      'which yarn', 'command -v yarn', 'ls -la ~/.yarn', 'rm -rf /tmp/yarn',
+      'git switch -c feat/yarn', 'cat README | grep yarn', 'echo yarn',
+      'npm run build --workspace yarn',
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('the broadened alias table does not swallow non-install commands', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    // `npm init` must not match `in` or `i`, and a bare `yarn test` must not
+    // match the bare-yarn install branch.
+    for (const cmd of ['npm init', 'npm init -y', 'yarn test', 'yarn run build', 'bun run dev', 'bun test', 'pnpm run build', 'git rm x', 'rm -rf node_modules', 'npm run rm']) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('COUNTERFACTUAL: the identical command passes when node_modules is a real directory', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    rmSync(join(worktree, 'node_modules'));
+    mkdirSync(join(worktree, 'node_modules'));
+    const r = runHook(`cd ${worktree} && npm ci`, root);
+    assert.equal(r.status, 0, `expected allow, got ${r.status}: ${r.stderr}`);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('allows the commands an agent actually runs in a linked worktree', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['npm test', 'npm run test', 'npm run test:browser', 'npx webjs check', 'npm ls', 'npm exec webjs check', 'npm run install-deps']) {
+      const r = runHook(cmd, worktree);
+      assert.equal(r.status, 0, `expected allow for \`${cmd}\`, got ${r.status}: ${r.stderr}`);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a `cd` out of the worktree supersedes the session cwd, so an install elsewhere passes', () => {
+  const { root, worktree } = makeLinkedPair();
+  const elsewhere = join(root, 'elsewhere');
+  mkdirSync(elsewhere);
+  try {
+    const r = runHook(`cd ${elsewhere} && npm install`, worktree);
+    assert.equal(r.status, 0, `expected allow, got ${r.status}: ${r.stderr}`);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('fails OPEN when the target directory has no node_modules at all', () => {
+  const root = mkdtempSync(join(tmpdir(), 'install-gate-bare-'));
+  try {
+    assert.equal(runHook('npm install', root).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('honours WEBJS_NO_WORKTREE_INSTALL_GATE=1', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    const r = runHook('npm ci', worktree, { WEBJS_NO_WORKTREE_INSTALL_GATE: '1' });
+    assert.equal(r.status, 0, `expected allow, got ${r.status}: ${r.stderr}`);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('sees the verb through flags that sit BEFORE it', () => {
+  // `npm --silent install` and `npm -w packages/core install` are ordinary
+  // spellings. Only `--prefix` / `-C` used to be admitted in the pre-verb
+  // position, so every other flag hid the verb and the gate failed open.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      'npm --silent install', 'npm -s ci', 'npm --ignore-scripts ci',
+      'npm -w packages/core install', 'npm --workspace packages/core install',
+      'npm --no-audit install', 'npm --prefer-offline ci',
+      'pnpm -r install', 'pnpm --filter core install', 'bun --cwd . install',
+    ]) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a flag VALUE never hides the verb, and a safe verb still stops the scan', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    // `packages/core` is neither an install verb nor a safe one, so the scan
+    // continues and finds `install`.
+    assert.equal(runHook('npm -w packages/core install', worktree).status, 2);
+    // ...but `run` IS a safe verb, so the scan stops there and never reaches
+    // the `add` further along.
+    assert.equal(runHook('npm run test -- --grep add', worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('follows the `cd --`, `cd -P` and `pushd` spellings', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [`cd -- ${worktree} && npm ci`, `pushd ${worktree} && npm ci`, `cd -P ${worktree} && npm ci`]) {
+      assert.equal(runHook(cmd, root).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('treats `yarnpkg` as yarn, since it is declared a manager token', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['yarnpkg install', 'yarnpkg add x', 'yarnpkg']) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('the manager carve-out in the strip loop is load-bearing', () => {
+  // A BOOLEAN wrapper flag followed directly by the manager. Without the
+  // `npm|bun|pnpm|yarn|yarnpkg)` case in the strip loop, `npm` is taken for the
+  // value of `-E` and stripped, leaving `ci` as the head token and no block.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('sudo -E npm ci', worktree).status, 2);
+    assert.equal(runHook('sudo -n npm install', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('escalates to the git toplevel, so an install from a SUBDIRECTORY blocks', () => {
+  // The install lands at the package root. `makeLinkedPair` builds no git repo,
+  // so the toplevel term was never exercised by any other test here.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    execSync('git init -q -b main', { cwd: worktree, stdio: 'pipe' });
+    const sub = join(worktree, 'packages', 'core');
+    mkdirSync(sub, { recursive: true });
+    assert.equal(runHook('npm install', sub).status, 2, 'a subdirectory install still reaches the linked root');
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a QUOTED directory argument survives the quote handling', () => {
+  // Quoted spans must lose their power to look like a command boundary while
+  // KEEPING their content. Deleting the span instead leaves `cd` with no
+  // argument, so the install is judged against the session cwd (the primary,
+  // whose node_modules is real) and the headline scenario fails open. Quoting a
+  // path is the ordinary defensive spelling.
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of [
+      `cd "${worktree}" && npm ci`,
+      `cd '${worktree}' && npm ci`,
+      `cd "${worktree}" && bun install`,
+      `npm --prefix "${worktree}" install`,
+      `npm install --prefix '${worktree}'`,
+    ]) {
+      assert.equal(runHook(cmd, primary).status, 2, `expected block for \`${cmd}\``);
+    }
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('an apostrophe inside a double-quoted string does not swallow a later install', () => {
+  // Running a single-quote pass before a double-quote pass pairs the apostrophe
+  // in `can't` with the next single quote anywhere in the line and deletes
+  // everything between, taking a real install with it.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook(`echo "can't resolve" && npm i -D esbuild`, worktree).status, 2);
+    assert.equal(runHook(`git commit -m "don't ship" && npm ci && echo "it's done"`, worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a heredoc BODY is content, not commands', () => {
+  // This repo's docs are full of `npm install` lines.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook("cat > doc.md <<'EOF'\nnpm install\nEOF", worktree).status, 0);
+    assert.equal(runHook('cat > doc.md <<EOF\nnpm ci\nEOF', worktree).status, 0);
+    // ...but a real newline-separated install still blocks.
+    assert.equal(runHook('echo hi\nnpm ci', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('`npm audit fix` blocks while a bare `npm audit` does not', () => {
+  // `audit fix` installs revised versions straight through the link, which is
+  // the same test `rebuild`, `prune` and `link` pass.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('npm audit fix', worktree).status, 2);
+    assert.equal(runHook('npm audit fix --force', worktree).status, 2);
+    assert.equal(runHook('npm audit', worktree).status, 0);
+    assert.equal(runHook('npm audit --json', worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('the verb tables are PER MANAGER, so one manager alias cannot fire for another', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    // `a` is a BUN alias for add. As an npm flag VALUE it must mean nothing.
+    assert.equal(runHook('npm --workspace a run build', worktree).status, 0);
+    assert.equal(runHook('npm -w a run build', worktree).status, 0);
+    assert.equal(runHook('bun a nanoid', worktree).status, 2, 'but it IS an install for bun');
+    // `bun upgrade` upgrades the Bun BINARY and never touches node_modules.
+    assert.equal(runHook('bun upgrade', worktree).status, 0);
+    assert.equal(runHook('pnpm upgrade', worktree).status, 2, 'while pnpm upgrade DOES install');
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('an informational flags-only yarn is not read as a bare install', () => {
+  const { root, worktree } = makeLinkedPair();
+  try {
+    for (const cmd of ['yarn --version', 'yarn -v', 'yarnpkg --help', 'yarn -h']) {
+      assert.equal(runHook(cmd, worktree).status, 0, `expected allow for \`${cmd}\``);
+    }
+    assert.equal(runHook('yarn', worktree).status, 2, 'a truly bare yarn still installs');
+    assert.equal(runHook('yarn --frozen-lockfile', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('mines --cwd and --dir as target directories, not just --prefix', () => {
+  // Bun is the manager that writes THROUGH the link, so `bun --cwd` matters most.
+  const { root, primary, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook(`bun --cwd ${worktree} install`, primary).status, 2);
+    assert.equal(runHook(`pnpm --dir ${worktree} install`, primary).status, 2);
+    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 5 -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 }); }
+});
+
+test('sees a nested symlink at PATH DEPTH 5, where the link script can plant one', () => {
+  // findNodeModules walks directories to depth 4 and pushes <dir>/node_modules,
+  // one level deeper, so `packages/ui/packages/registry/node_modules` is a real
+  // planted shape. The probe used -maxdepth 4 and was blind to it; the two
+  // depths must come from the same fact.
+  const root = mkdtempSync(join(tmpdir(), 'install-gate-depth5-'));
+  const primary = join(root, 'primary');
+  const worktree = join(root, 'worktree');
+  mkdirSync(join(primary, 'packages', 'ui', 'packages', 'registry', 'node_modules'), { recursive: true });
+  mkdirSync(join(worktree, 'packages', 'ui', 'packages', 'registry'), { recursive: true });
+  mkdirSync(join(worktree, 'node_modules'), { recursive: true }); // REAL root tree
+  writeFileSync(join(worktree, 'package.json'), '{"name":"w"}\n');
+  symlinkSync(
+    join(primary, 'packages', 'ui', 'packages', 'registry', 'node_modules'),
+    join(worktree, 'packages', 'ui', 'packages', 'registry', 'node_modules'),
+  );
+  try {
+    assert.equal(runHook('npm install', worktree).status, 2);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('a HERE-STRING is not a heredoc opener', () => {
+  // `<<<foo` matched the heredoc regex from its second `<`, so the scrubber
+  // swallowed every following line until one equalled `foo`, and an install on
+  // the next line failed open.
+  const { root, worktree } = makeLinkedPair();
+  try {
+    assert.equal(runHook('grep x <<<foo\nnpm ci', worktree).status, 2);
+    // The real heredoc behaviour is unchanged.
+    assert.equal(runHook("cat > doc.md <<'EOF'\nnpm install\nEOF", worktree).status, 0);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
diff --git a/test/hooks/cleanup-merged-worktree.test.mjs b/test/hooks/cleanup-merged-worktree.test.mjs
index 439358c0a..d9fed145d 100644
--- a/test/hooks/cleanup-merged-worktree.test.mjs
+++ b/test/hooks/cleanup-merged-worktree.test.mjs
@@ -13,7 +13,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { mkdtempSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, symlinkSync, readlinkSync, lstatSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname, resolve, delimiter } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -190,3 +190,111 @@ test('honours the WEBJS_NO_WORKTREE_CLEANUP escape hatch', () => {
   assert.equal(r.status, 0);
   assert.ok(existsSync(clean), 'the escape hatch disables all cleanup');
 });
+
+// --- #1442: the primary's @webjsdev links must survive a worktree removal ---
+//
+// The primary can hold `node_modules/@webjsdev/*` links pointing INTO a
+// worktree, which is what an install run inside a linked worktree leaves behind.
+// Removing that worktree without repointing them leaves the primary resolving
+// into a directory that is gone, and every checkout resolving through the
+// primary breaks at once on an error naming nothing related.
+
+/** Plant a `@webjsdev/<name>` symlink in the primary, pointing at `target`. */
+function plantLink({ main }, name, target) {
+  mkdirSync(join(main, 'node_modules', '@webjsdev'), { recursive: true });
+  const entry = join(main, 'node_modules', '@webjsdev', name);
+  symlinkSync(target, entry);
+  return entry;
+}
+
+/** Give the primary a real `packages/<name>` so a repoint has somewhere to land. */
+function plantPackage({ main, git }, name) {
+  mkdirSync(join(main, 'packages', name), { recursive: true });
+  writeFileSync(join(main, 'packages', name, 'package.json'), `{"name":"@webjsdev/${name}"}\n`);
+  git('add', '-A');
+  git('commit', '-q', '-m', `add ${name}`);
+}
+
+test('repoints a primary @webjsdev link that targets the worktree being removed', () => {
+  const repo = makeRepo();
+  plantPackage(repo, 'core');
+  const wt = addWorktree(repo, 'feat-merged-clean', { merged: true });
+  const entry = plantLink(repo, 'core', join(wt, 'packages', 'core'));
+
+  const { code } = runHook('gh pr merge 1 --squash', repo.main);
+
+  assert.equal(code, 0);
+  assert.ok(!existsSync(wt), 'the merged worktree is still removed');
+  // COUNTERFACTUAL: without the repoint this link still names the deleted
+  // worktree, so `existsSync` on the resolved entry is false.
+  assert.equal(readlinkSync(entry), '../../packages/core');
+  assert.ok(existsSync(entry), 'the primary link resolves after the removal');
+});
+
+test('drops an npm staging entry that pointed into the removed worktree', () => {
+  const repo = makeRepo();
+  plantPackage(repo, 'core');
+  const wt = addWorktree(repo, 'feat-merged-clean', { merged: true });
+  const entry = plantLink(repo, '.core-AbCdEf12', join(wt, 'packages', 'core'));
+
+  runHook('gh pr merge 1 --squash', repo.main);
+
+  assert.ok(!existsSync(wt));
+  assert.throws(() => lstatSync(entry), 'the dangling-to-be staging entry is removed');
+});
+
+test('leaves a primary link that already points inside the primary alone', () => {
+  const repo = makeRepo();
+  plantPackage(repo, 'server');
+  const wt = addWorktree(repo, 'feat-merged-clean', { merged: true });
+  const entry = plantLink(repo, 'server', '../../packages/server');
+
+  runHook('gh pr merge 1 --squash', repo.main);
+
+  assert.ok(!existsSync(wt));
+  assert.equal(readlinkSync(entry), '../../packages/server', 'untouched, byte for byte');
+});
+
+test('never repoints to a path the primary does not have', () => {
+  const repo = makeRepo();
+  // No `packages/ghost` in the primary, so repointing would create a fresh
+  // dangling link. The entry must be kept and reported instead.
+  const wt = addWorktree(repo, 'feat-merged-clean', { merged: true });
+  mkdirSync(join(wt, 'packages', 'ghost'), { recursive: true });
+  const target = join(wt, 'packages', 'ghost');
+  const entry = plantLink(repo, 'ghost', target);
+
+  const { out } = runHook('gh pr merge 1 --squash', repo.main);
+
+  assert.equal(readlinkSync(entry), target, 'left exactly as it was');
+  assert.match(out, /KEPT @webjsdev\/ghost/);
+});
+
+test('leaves the primary links untouched when the worktree is KEPT', () => {
+  const repo = makeRepo();
+  plantPackage(repo, 'core');
+  const wt = addWorktree(repo, 'feat-merged-dirty', { merged: true, dirty: true });
+  const target = join(wt, 'packages', 'core');
+  const entry = plantLink(repo, 'core', target);
+
+  runHook('gh pr merge 1 --squash', repo.main);
+
+  assert.ok(existsSync(wt), 'a dirty worktree is kept');
+  assert.equal(readlinkSync(entry), target, 'so its links are left pointing at it');
+});
+
+test('repoint_primary_links never shadows the script-global `base` merge ref', () => {
+  // `base` holds the merge base ref resolved once at the top and read by
+  // `is_merged()`. bash `local` is dynamically scoped, so declaring `base` local
+  // inside this function blanks the ref for anything the function calls. Nothing
+  // calls a helper from there TODAY, which is why this is a source assertion
+  // rather than a behavioural one: the defect is unreachable until someone adds
+  // that call, and then it silently leaks the worktree this hook exists to remove.
+  const src = readFileSync(HOOK, 'utf8');
+  const fn = src.slice(src.indexOf('repoint_primary_links() {'));
+  const locals = fn.slice(0, fn.indexOf('\n}')).match(/^\s*local .*$/gm) || [];
+  assert.ok(locals.length > 0, 'the function still declares locals');
+  for (const line of locals) {
+    assert.doesNotMatch(line, /\blocal\b[^\n]*\bbase\b/, `shadows the global merge ref: ${line.trim()}`);
+  }
+});
diff --git a/test/repo-health/link-worktree-deps.test.mjs b/test/repo-health/link-worktree-deps.test.mjs
index 5fa5058b0..f88cc3608 100644
--- a/test/repo-health/link-worktree-deps.test.mjs
+++ b/test/repo-health/link-worktree-deps.test.mjs
@@ -15,7 +15,7 @@
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, symlinkSync, lstatSync, readlinkSync, existsSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, lstatSync, readlinkSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -69,6 +69,10 @@ function makeWorktree({ blog = false } = {}) {
  * seed tests below assert that seeding HAPPENS, and would silently invert into
  * failures for that person. Only the test that opts in passes it explicitly.
  *
+ * `WEBJS_NO_WORKTREE_REPAIR=1` is stripped for the same reason: the repair tests
+ * below assert that repair HAPPENS, and an exported opt-out would turn every one
+ * of them into a vacuous pass.
+ *
  * `DATABASE_URL` is stripped for the same reason: the script now resolves the
  * database path the way the blog does, so an exported value would point the
  * probe outside the synthetic worktree these tests build.
@@ -77,7 +81,7 @@ function makeWorktree({ blog = false } = {}) {
  * @returns {NodeJS.ProcessEnv}
  */
 function cleanEnv(env = {}) {
-  const { WEBJS_NO_WORKTREE_SEED: _seed, DATABASE_URL: _db, ...rest } = process.env;
+  const { WEBJS_NO_WORKTREE_SEED: _seed, WEBJS_NO_WORKTREE_REPAIR: _repair, DATABASE_URL: _db, ...rest } = process.env;
   return { ...rest, ...env };
 }
 
@@ -177,15 +181,18 @@ describe('link-worktree-deps (#1287)', () => {
     // git-derived default branch never executes at all.
     //
     // This is the ONE test that runs the script against a real checkout, so it
-    // must not seed. Run from the primary the `primary === here` guard stops it,
-    // but run from a linked worktree (the mandated workflow) that guard does not
-    // fire, and the script would migrate and seed that worktree's blog database
-    // as a side effect of `npm test`, concurrently with `blog-http.test.mjs`
-    // reading the same file. The escape hatch is what actually keeps it out.
+    // must neither seed nor repair. Run from the primary the `primary === here`
+    // guard stops the seeding, but run from a linked worktree (the mandated
+    // workflow) that guard does not fire, and the script would migrate and seed
+    // that worktree's blog database as a side effect of `npm test`, concurrently
+    // with `blog-http.test.mjs` reading the same file. The repair pass sits ABOVE
+    // that guard by design, so it runs in BOTH positions and would rewrite the
+    // real primary's `@webjsdev/*` links here. The two escape hatches are what
+    // actually keep this test off the developer's checkout.
     const out = execFileSync(process.execPath, [SCRIPT], {
       cwd: process.cwd(),
       encoding: 'utf8',
-      env: { ...process.env, WEBJS_NO_WORKTREE_SEED: '1' },
+      env: { ...process.env, WEBJS_NO_WORKTREE_SEED: '1', WEBJS_NO_WORKTREE_REPAIR: '1' },
     });
     // Run from the repo itself, so it must recognise the primary and no-op
     // rather than linking anything.
@@ -351,3 +358,247 @@ describe('link-worktree-deps (#1287)', () => {
   });
 });
 
+
+/**
+ * The repair pass over `<primary>/node_modules/@webjsdev/` (#1442).
+ *
+ * An install run inside a LINKED worktree acts on the PRIMARY, and leaves links
+ * that dangle, resolve into a foreign checkout, or resolve inside the primary
+ * but absolutely where every sibling is relative. All three are repaired to the
+ * relative form. A LIVE `.name-HASH` npm staging entry is deliberately NOT
+ * touched, because most of them resolve fine and deleting one risks racing an
+ * install that is mid-reify.
+ */
+describe('framework-link repair (#1442)', () => {
+  /**
+   * A primary whose `packages/` holds real workspace packages, so
+   * `workspacePackageDirs()` has something to map, plus a `@webjsdev` scope to
+   * plant broken links in.
+   */
+  function makeRepairPrimary() {
+    const root = mkdtempSync(join(tmpdir(), 'wjrepair-'));
+    writeFileSync(join(root, 'package.json'), JSON.stringify({
+      name: 'fake-primary',
+      workspaces: ['packages/*', 'examples/*'],
+    }));
+    mkdirSync(join(root, 'node_modules/@webjsdev'), { recursive: true });
+    for (const [dir, name] of [
+      ['packages/core', '@webjsdev/core'],
+      ['packages/server', '@webjsdev/server'],
+      ['packages/cli', '@webjsdev/cli'],
+      ['packages/ui', '@webjsdev/ui'],
+      ['examples/blog', '@webjsdev/example-blog'],
+    ]) {
+      mkdirSync(join(root, dir), { recursive: true });
+      writeFileSync(join(root, dir, 'package.json'), JSON.stringify({ name }));
+    }
+    return root;
+  }
+
+  const scopeOf = (primary) => join(primary, 'node_modules/@webjsdev');
+  const plant = (primary, name, target) => symlinkSync(target, join(scopeOf(primary), name));
+
+  test('repoints a DANGLING link to the relative in-primary path', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'core', '/nonexistent/gone-worktree/packages/core');
+      run(wt, primary);
+      // COUNTERFACTUAL: without the repair pass this still reads the dead
+      // absolute path, so `existsSync` on the resolved entry is false.
+      assert.equal(readlinkSync(join(scopeOf(primary), 'core')), '../../packages/core');
+      assert.ok(existsSync(join(scopeOf(primary), 'core')), 'the repaired link resolves');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('repoints a link that resolves OUTSIDE the primary, into a live foreign checkout', () => {
+    const primary = makeRepairPrimary();
+    const foreign = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'server', join(foreign, 'packages/server'));
+      run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'server')), '../../packages/server');
+    } finally {
+      rmSync(primary, { recursive: true, force: true });
+      rmSync(foreign, { recursive: true, force: true });
+      rmSync(wt, { recursive: true, force: true });
+    }
+  });
+
+  test('normalises an ABSOLUTE in-primary link to the relative form', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'cli', join(primary, 'packages/cli'));
+      run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'cli')), '../../packages/cli');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('maps a package whose directory is NOT packages/<name>', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'example-blog', '/nonexistent/gone/examples/blog');
+      run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'example-blog')), '../../examples/blog');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('removes a DANGLING .name-HASH npm staging entry', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, '.core-mTPzu12Q', '/nonexistent/gone-worktree/packages/core');
+      run(wt, primary);
+      assert.ok(!existsSync(join(scopeOf(primary), '.core-mTPzu12Q')), 'dangling staging entry removed');
+      assert.throws(() => lstatSync(join(scopeOf(primary), '.core-mTPzu12Q')));
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('leaves a LIVE .name-HASH staging entry strictly alone', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, '.ui-tVBcnl39', '../../packages/ui');
+      run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), '.ui-tVBcnl39')), '../../packages/ui');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('leaves a link that is already correct untouched, and reports nothing', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'core', '../../packages/core');
+      const out = run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'core')), '../../packages/core');
+      assert.doesNotMatch(out, /repointed/);
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('never touches a REAL directory sitting in @webjsdev', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      mkdirSync(join(scopeOf(primary), 'core'), { recursive: true });
+      writeFileSync(join(scopeOf(primary), 'core/package.json'), '{"name":"@webjsdev/core"}');
+      run(wt, primary);
+      assert.ok(lstatSync(join(scopeOf(primary), 'core')).isDirectory(), 'a deliberate install is left alone');
+      assert.equal(readFileSync(join(scopeOf(primary), 'core/package.json'), 'utf8'), '{"name":"@webjsdev/core"}');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('reports and LEAVES a dangling link whose package is in no workspace', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'ghost', '/nonexistent/gone/packages/ghost');
+      const out = run(wt, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'ghost')), '/nonexistent/gone/packages/ghost');
+      assert.match(out, /matches no workspace package/);
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('a repair never trades one dangling link for another', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      // A package that no longer has a directory is unmappable, so it is left as
+      // it is rather than repointed. This is the reachable half of the
+      // never-create-a-dangling-link rule; the `existsSync(correct)` guard in the
+      // script covers the TOCTOU race, which is not reproducible from a test.
+      rmSync(join(primary, 'packages/ui'), { recursive: true, force: true });
+      plant(primary, 'ui', '/nonexistent/gone/packages/ui');
+      plant(primary, 'core', '/nonexistent/gone/packages/core');
+      run(wt, primary);
+
+      assert.equal(
+        readlinkSync(join(scopeOf(primary), 'ui')),
+        '/nonexistent/gone/packages/ui',
+        'an unmappable entry is left exactly as it was',
+      );
+      // Every entry the pass DID rewrite must resolve.
+      for (const name of readdirSync(scopeOf(primary))) {
+        const entry = join(scopeOf(primary), name);
+        if (name === 'ui') continue;
+        assert.ok(existsSync(entry), `${name} resolves after the repair`);
+      }
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('repairs from the PRIMARY too, above the primary-is-here guard', () => {
+    const primary = makeRepairPrimary();
+    try {
+      plant(primary, 'core', '/nonexistent/gone-worktree/packages/core');
+      const out = run(primary, primary);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'core')), '../../packages/core');
+      assert.match(out, /this IS the primary checkout/);
+    } finally { rmSync(primary, { recursive: true, force: true }); }
+  });
+
+  test('--check reports without changing anything, and exits 1 only when there is work', () => {
+    const primary = makeRepairPrimary();
+    try {
+      plant(primary, 'core', '/nonexistent/gone-worktree/packages/core');
+      const dirty = spawnSync(process.execPath, [SCRIPT, primary, '--check'], {
+        cwd: primary, encoding: 'utf8', env: cleanEnv(),
+      });
+      assert.equal(dirty.status, 1);
+      assert.match(dirty.stdout, /would repoint/);
+      assert.equal(
+        readlinkSync(join(scopeOf(primary), 'core')),
+        '/nonexistent/gone-worktree/packages/core',
+        '--check must not write',
+      );
+
+      // Repair for real, then a second --check must be clean and exit 0.
+      run(primary, primary);
+      const clean = spawnSync(process.execPath, [SCRIPT, primary, '--check'], {
+        cwd: primary, encoding: 'utf8', env: cleanEnv(),
+      });
+      assert.equal(clean.status, 0);
+    } finally { rmSync(primary, { recursive: true, force: true }); }
+  });
+
+  test('--check with WEBJS_NO_WORKTREE_REPAIR=1 still INSPECTS, and still writes nothing', () => {
+    // Two separate bugs met here. The exit for `--check` used to live INSIDE the
+    // repair `else`, so this pair fell through to the linking loop and the seed
+    // step, and the flag pair documented as changing nothing was the pair that
+    // wrote. Moving the exit out fixed the write but left `touched` at its
+    // initializer, so the run then exited 0 reporting a clean tree it had never
+    // looked at. The hatch suppresses the repair WRITE; `--check` never writes,
+    // so it must still inspect.
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'core', '/nonexistent/gone-worktree/packages/core');
+      const r = spawnSync(process.execPath, [SCRIPT, primary, '--check'], {
+        cwd: wt,
+        encoding: 'utf8',
+        env: cleanEnv({ WEBJS_NO_WORKTREE_REPAIR: '1' }),
+      });
+      assert.equal(r.status, 1, 'a broken link is still reported as work to do');
+      assert.match(r.stdout, /would repoint/, 'it actually inspected');
+      assert.doesNotMatch(r.stdout, /linked node_modules/, '--check must never link');
+      assert.ok(!existsSync(join(wt, 'node_modules')), '--check must not create the symlink');
+      assert.equal(
+        readlinkSync(join(scopeOf(primary), 'core')),
+        '/nonexistent/gone-worktree/packages/core',
+        '--check must not repair either',
+      );
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+
+  test('WEBJS_NO_WORKTREE_REPAIR=1 skips the pass entirely', () => {
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      plant(primary, 'core', '/nonexistent/gone-worktree/packages/core');
+      const r = runWithResult(wt, primary, { WEBJS_NO_WORKTREE_REPAIR: '1' });
+      assert.match(r.stdout, /repair skipped/);
+      assert.equal(readlinkSync(join(scopeOf(primary), 'core')), '/nonexistent/gone-worktree/packages/core');
+    } finally { rmSync(primary, { recursive: true, force: true }); rmSync(wt, { recursive: true, force: true }); }
+  });
+});
diff --git a/test/repo-health/warn-worktree-install.test.mjs b/test/repo-health/warn-worktree-install.test.mjs
new file mode 100644
index 000000000..0997f1b8a
--- /dev/null
+++ b/test/repo-health/warn-worktree-install.test.mjs
@@ -0,0 +1,99 @@
+// The warn-worktree-install `preinstall` reporter names what an install in a
+// LINKED worktree did to the primary checkout's node_modules (#1442). It must
+// ALWAYS exit 0: a non-zero preinstall blocks `npm ci`, which would red every CI
+// job, and it cannot prevent the damage anyway (npm removes the symlink before
+// preinstall runs, `npm ci` has already emptied the primary, and Bun ignores the
+// exit code). Prevention lives in the PreToolUse hook instead.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync, execSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '../../scripts/warn-worktree-install.mjs'
+);
+
+function run(cwd) {
+  return spawnSync(process.execPath, [SCRIPT], { cwd, encoding: 'utf8' });
+}
+
+/**
+ * A real primary checkout plus a real linked worktree, so `git rev-parse
+ * --git-common-dir` resolves the way it does in the repo rather than against a
+ * hand-faked gitdir pointer.
+ */
+function makePair() {
+  const root = mkdtempSync(join(tmpdir(), 'warn-install-'));
+  const primary = join(root, 'primary');
+  const worktree = join(root, 'worktree');
+  mkdirSync(primary, { recursive: true });
+  const g = (cmd) => execSync(`git ${cmd}`, { cwd: primary, stdio: 'pipe' });
+  g('init -q -b main');
+  g('config user.email t@t');
+  g('config user.name t');
+  writeFileSync(join(primary, 'package.json'), '{"name":"primary"}\n');
+  g('add .');
+  g('commit -q -m init');
+  g(`worktree add -q -b feat ${worktree}`);
+  mkdirSync(join(primary, 'node_modules'), { recursive: true });
+  writeFileSync(join(primary, 'node_modules', '.keep'), '');
+  return { root, primary, worktree };
+}
+
+test('silent and exit 0 in the PRIMARY checkout, which is the CI and normal-clone shape', () => {
+  const { root, primary } = makePair();
+  try {
+    const r = run(primary);
+    assert.equal(r.status, 0);
+    assert.equal(r.stderr.trim(), '', `expected silence, got: ${r.stderr}`);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('with the symlink intact, warns BEFORE the fact and names the primary (the Bun shape)', () => {
+  const { root, primary, worktree } = makePair();
+  try {
+    symlinkSync(join(primary, 'node_modules'), join(worktree, 'node_modules'));
+    const r = run(worktree);
+    assert.equal(r.status, 0);
+    assert.match(r.stderr, /node_modules is a SYMLINK/);
+    assert.ok(r.stderr.includes(join(primary, 'node_modules')), 'names the primary tree');
+    assert.match(r.stderr, /worktree:link/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('with a real node_modules and an EMPTY primary, names the `npm ci` aftermath and the repair', () => {
+  const { root, primary, worktree } = makePair();
+  try {
+    rmSync(join(primary, 'node_modules'), { recursive: true, force: true });
+    mkdirSync(join(worktree, 'node_modules'), { recursive: true });
+    const r = run(worktree);
+    assert.equal(r.status, 0);
+    assert.match(r.stderr, /EMPTY or missing/);
+    assert.ok(r.stderr.includes(`cd ${primary} && npm install`), 'prints the exact repair command');
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('with a real node_modules and a POPULATED primary, reports the detach', () => {
+  const { root, worktree } = makePair();
+  try {
+    mkdirSync(join(worktree, 'node_modules'), { recursive: true });
+    const r = run(worktree);
+    assert.equal(r.status, 0);
+    assert.match(r.stderr, /its OWN node_modules/);
+    assert.match(r.stderr, /npm run worktree:link/);
+  } finally { rmSync(root, { recursive: true, force: true }); }
+});
+
+test('COUNTERFACTUAL: exit is 0 even when the gitdir pointer names a path that does not exist', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'warn-install-broken-'));
+  try {
+    writeFileSync(join(dir, '.git'), 'gitdir: /nonexistent/path/.git/worktrees/x\n');
+    mkdirSync(join(dir, 'node_modules'));
+    const r = run(dir);
+    assert.equal(r.status, 0, 'the reporter must never be able to block an install');
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/website/app/docs/configuration/page.ts b/website/app/docs/configuration/page.ts
index e64ebc222..6e0e2268a 100644
--- a/website/app/docs/configuration/page.ts
+++ b/website/app/docs/configuration/page.ts
@@ -47,7 +47,7 @@ webjs routes --json             # structured JSON (matches the MCP list_routes t
     <code-block>webjs doctor            # human-readable project-health checklist
 webjs doctor --json     # structured results (each with a stable code) + a summary
 webjs doctor --strict   # also fail on EVERY remaining warning, not just hard failures and gated errors</code-block>
-    <p>Per-check severity is <em>configuration</em>, not a flag. Declare it in <code>package.json</code> under <code>webjs.doctor.gate</code>, keyed by the stable code every result carries, on the same three-level scale ESLint uses. That is what lets CI gate on a chosen subset without <code>--strict</code> making every warning fatal, which is unusable on a runner (the git-hook, env-drift, vendor-pin, and framework-resolve checks are all environment-shaped and would fail a perfectly healthy build).</p>
+    <p>Per-check severity is <em>configuration</em>, not a flag. Declare it in <code>package.json</code> under <code>webjs.doctor.gate</code>, keyed by the stable code every result carries, on the same three-level scale ESLint uses. That is what lets CI gate on a chosen subset without <code>--strict</code> making every warning fatal, which is unusable on a runner (the git-hook, env-drift, vendor-pin, framework-resolve, and framework-links checks are all environment-shaped and would fail a perfectly healthy build).</p>
     <code-block>&#123;
   "webjs": &#123;
     "doctor": &#123;
@@ -59,7 +59,7 @@ webjs doctor --strict   # also fail on EVERY remaining warning, not just hard fa
   &#125;
 &#125;</code-block>
     <p><code>error</code> fails the exit, <code>warn</code> reports without failing, and <code>off</code> silences the check: its finding is not printed and it cannot fail the exit, including under <code>--strict</code>. A silenced check still appears on the checklist as <code>[off]</code> and in the summary's silenced count, so it is never invisible, and <code>--json</code> still carries its whole result. A code with no entry keeps its default (<code>error</code> for a hard toolchain failure, <code>warn</code> otherwise), so an app that declares nothing behaves exactly as it did before. Two guarantees make it safe to put in a required CI job: a result that could not check, such as a network or toolchain outage, is capped at <code>warn</code> and can never be escalated, and a malformed gate exits 1 naming the offender rather than being ignored, so a typo cannot silently un-gate the build. That last one covers an unknown code, a bad severity, a wrong shape (a non-object <code>doctor</code> or <code>gate</code>), and a misspelled sibling of <code>gate</code> such as <code>gates</code>; under <code>--json</code> they come back as a <code>configErrors</code> array alongside an empty <code>results</code>.</p>
-    <p>Verifies project health: the Node version floor, <code>erasableSyntaxOnly</code>, <code>.env</code> drift, vendor-pin freshness, importmap coherence, <code>@webjsdev/*</code> version coherence, framework resolvability, the git hook, a page/layout elision advisory, and a warning when a route module writes a <code>&lt;link rel="stylesheet"&gt;</code> without <code>asset()</code> (so its url is un-versioned and a deploy cannot bust a cached copy). Each result carries a stable machine <code>code</code> (for example <code>NODE_VERSION</code>, <code>TSCONFIG_ERASABLE</code>, <code>IMPORTMAP_COHERENCE</code>) so an agent branches on the failure kind, not the message text. The <code>--json</code> payload is an object <code>&#123; results, summary &#125;</code> (the <code>results</code> array holds the per-check objects, each with its <code>code</code> and its effective <code>severity</code>; the <code>summary</code> counts <code>pass</code> / <code>warn</code> / <code>fail</code> / <code>off</code>). A rejected <code>webjs.doctor</code> config is the one path that adds a third key, <code>configErrors</code>, with <code>results</code> empty because no check ran. The exit is non-zero on a hard <em>toolchain</em> failure, and on any check the app gated <code>error</code> (see the severity gate above); <code>--strict</code> additionally fails on every remaining warning, so it can gate a fully-clean fix loop the way <code>webjs check --json</code> does.</p>
+    <p>Verifies project health: the Node version floor, <code>erasableSyntaxOnly</code>, <code>.env</code> drift, vendor-pin freshness, importmap coherence, <code>@webjsdev/*</code> version coherence, framework resolvability, framework link integrity, the git hook, a page/layout elision advisory, and a warning when a route module writes a <code>&lt;link rel="stylesheet"&gt;</code> without <code>asset()</code> (so its url is un-versioned and a deploy cannot bust a cached copy). Each result carries a stable machine <code>code</code> (for example <code>NODE_VERSION</code>, <code>TSCONFIG_ERASABLE</code>, <code>IMPORTMAP_COHERENCE</code>) so an agent branches on the failure kind, not the message text. The <code>--json</code> payload is an object <code>&#123; results, summary &#125;</code> (the <code>results</code> array holds the per-check objects, each with its <code>code</code> and its effective <code>severity</code>; the <code>summary</code> counts <code>pass</code> / <code>warn</code> / <code>fail</code> / <code>off</code>). A rejected <code>webjs.doctor</code> config is the one path that adds a third key, <code>configErrors</code>, with <code>results</code> empty because no check ran. The exit is non-zero on a hard <em>toolchain</em> failure, and on any check the app gated <code>error</code> (see the severity gate above); <code>--strict</code> additionally fails on every remaining warning, so it can gate a fully-clean fix loop the way <code>webjs check --json</code> does.</p>
 
     <h3>webjs version</h3>
     <code-block>webjs version           # print the installed @webjsdev/cli version