From ccd62a32c3530ddc88d67faeb5ff84b1593ead7a Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 03:45:24 +0530
Subject: [PATCH 01/12] fix: block a package-manager install inside a linked
 worktree

`npm run worktree:link` symlinks a worktree's node_modules at the primary
checkout's, so an install run in the worktree acts on the primary. Measured
on npm 11.19.0 and bun 1.3.14: `npm ci` deletes the primary's whole
node_modules through the link, `bun install` writes packages into it, and
`npm install` silently replaces the link with a real tree and detaches the
worktree. The damage lands on a session that did nothing wrong.

No package-manager lifecycle hook can prevent this. npm removes the symlink
before `preinstall` runs, `npm ci` has already emptied the primary by then,
and Bun runs `preinstall` in time but ignores a non-zero exit. A PreToolUse
hook is the only layer that sees the state before the manager starts.
---
 .../hooks/block-install-in-linked-worktree.sh | 104 ++++++++++++++
 .claude/settings.json                         |   4 +
 .../block-install-in-linked-worktree.test.mjs | 127 ++++++++++++++++++
 3 files changed, 235 insertions(+)
 create mode 100755 .claude/hooks/block-install-in-linked-worktree.sh
 create mode 100644 test/hooks/block-install-in-linked-worktree.test.mjs

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..029a7298d
--- /dev/null
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -0,0 +1,104 @@
+#!/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.
+#
+# The predicate runs against the COMMAND's target directory, not just the session
+# cwd: the harness resets cwd to the primary checkout between commands, so a real
+# install in a worktree arrives as `cd /path/to/worktree && npm ci`.
+#
+# 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
+
+# Install verbs only. `npm run test`, `npm test`, `npm exec`, `npm ls`, and every
+# `npx ...` must pass, so the verb is matched at a word boundary on both sides.
+# The second alternation branch is the flags-before-verb form
+# (`npm --prefix <dir> install`). Only the two flags that themselves name a
+# target directory are admitted there, so this stays targeted rather than
+# swallowing an arbitrary token run and matching something like `npm run install`.
+VERBS='(npm[[:space:]]+(install|i|ci|add|update|dedupe)|bun[[:space:]]+(install|add|update)|pnpm[[:space:]]+(install|add|update)|yarn[[:space:]]+(install|add)|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(install|i|ci|add|update|dedupe))'
+if ! printf '%s' "$cmd" | grep -Eq "(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$)"; then
+  exit 0
+fi
+
+# Candidate target directories. An install acts on ONE directory, so the session
+# cwd counts only until the command changes out of it: `cd /tmp && npm install`
+# targets /tmp, not the worktree this shell happens to sit in. So walk the `cd`
+# tokens that appear BEFORE the install verb and let them supersede the cwd, then
+# add any directory a package manager is pointed at explicitly.
+prefix=$(printf '%s' "$cmd" | sed -E "s/(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$).*//")
+
+eff="$PWD"
+resolve_against_eff() {
+  local d="$1"
+  case "$d" in
+    /*) printf '%s' "$d" ;;
+    ~*) printf '%s' '' ;;
+    *) printf '%s' "$eff/$d" ;;
+  esac
+}
+while IFS= read -r d; do
+  [ -n "$d" ] || continue
+  d=$(printf '%s' "$d" | tr -d "\"'")
+  r=$(resolve_against_eff "$d")
+  [ -n "$r" ] && eff="$r"
+done < <(printf '%s\n' "$prefix" \
+  | grep -oE '(^|[^[:alnum:]_./-])cd[[:space:]]+[^[:space:]&|;]+' \
+  | sed -E 's/.*cd[[:space:]]+//')
+
+cands=("$eff")
+while IFS= read -r d; do
+  [ -n "$d" ] || continue
+  d=$(printf '%s' "$d" | tr -d "\"'")
+  r=$(resolve_against_eff "$d")
+  [ -n "$r" ] && cands+=("$r")
+done < <(printf '%s\n' "$cmd" \
+  | grep -oE '(^|[[:space:]])(-C|--prefix)[[:space:]=]+[^[:space:]&|;]+' \
+  | sed -E 's/.*(-C|--prefix)[[:space:]=]+//')
+
+for cand in "${cands[@]}"; do
+  [ -d "$cand" ] || continue
+  # The install lands at the package root, which for a subdirectory is the
+  # enclosing checkout, so judge the git toplevel too.
+  top=$(git -C "$cand" rev-parse --show-toplevel 2>/dev/null || true)
+  for dir in "$cand" "$top"; do
+    [ -n "$dir" ] || continue
+    [ -L "$dir/node_modules" ] || continue
+    target=$(cd "$(dirname "$dir/node_modules")" 2>/dev/null && readlink "node_modules" || true)
+    owner=$(cd "$dir" 2>/dev/null && cd "$(readlink node_modules)" 2>/dev/null && pwd -P || printf '%s' "${target:-the primary checkout}")
+    {
+      echo "BLOCKED: this command installs into $dir, whose node_modules is a SYMLINK at $owner."
+      echo "An install through that link damages the checkout that OWNS the tree, not this one:"
+      echo "  npm ci       DELETES $owner outright, before any lifecycle script can run"
+      echo "  bun install  writes packages and .bin entries straight into $owner"
+      echo "  npm install  silently REPLACES the link with a real tree, detaching this worktree"
+      echo "Safe alternatives:"
+      echo "  npm run worktree:link          links a fresh worktree; it never installs"
+      echo "  a real install with NO symlink in the way. Run \`rm node_modules\` first (it is"
+      echo "  only a link, nothing else is lost), or install in the PRIMARY checkout."
+      echo "Escape hatch for a deliberate exception: WEBJS_NO_WORKTREE_INSTALL_GATE=1."
+    } >&2
+    exit 2
+  done
+done
+
+exit 0
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/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..67f203025
--- /dev/null
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -0,0 +1,127 @@
+// 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 } 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('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 }); }
+});

From 7bab6ef1a7c30076b7dd3d503c5e607884942397 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 03:47:06 +0530
Subject: [PATCH 02/12] fix: report a linked-worktree install through the root
 preinstall

The PreToolUse hook covers Claude Code sessions. Every other tool needs a
diagnosis after the fact, because the three damaging shapes are otherwise
silent: `npm install` detaches the worktree, `npm ci` empties the primary's
node_modules, and `bun install` writes into it through the link.

The script always exits 0. A non-zero preinstall blocks `npm ci` and would
red every CI job, and it cannot prevent the damage anyway, so making it a
guard would be a guard in name only. It returns immediately unless `.git` is
a FILE, so a normal clone and CI never see it.
---
 package.json                                  |  2 +
 scripts/warn-worktree-install.mjs             | 96 ++++++++++++++++++
 .../warn-worktree-install.test.mjs            | 99 +++++++++++++++++++
 3 files changed, 197 insertions(+)
 create mode 100644 scripts/warn-worktree-install.mjs
 create mode 100644 test/repo-health/warn-worktree-install.test.mjs

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/scripts/warn-worktree-install.mjs b/scripts/warn-worktree-install.mjs
new file mode 100644
index 000000000..4ca5bf987
--- /dev/null
+++ b/scripts/warn-worktree-install.mjs
@@ -0,0 +1,96 @@
+#!/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('`rm node_modules` first if a real, self-contained 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/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 }); }
+});

From 7064c3b4e5d94623b17dfd9be356e0316e29190d Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 03:50:20 +0530
Subject: [PATCH 03/12] fix: repair corrupted primary framework links from
 worktree:link

The primary's `node_modules/@webjsdev/` accumulates three defect classes when
an install runs inside a linked worktree: links that dangle into a removed
worktree, links resolving into a live foreign checkout (the worst case, since
it resolves fine and silently runs another branch's source), and links that
resolve inside the primary but absolutely where every sibling is relative.

All three are repaired to the relative form, atomically, since `npm test`
resolves these from many processes at once. A LIVE `.name-HASH` staging entry
is left alone: most resolve to real in-repo directories, nothing imports them,
one predates a package rename, and deleting one risks racing a live install.
Only a staging entry that is BOTH staging-shaped and dangling is removed.

`--check` reports without writing, mirroring `npm run check:git`.
---
 scripts/link-worktree-deps.mjs               | 214 ++++++++++++++++-
 test/repo-health/link-worktree-deps.test.mjs | 238 ++++++++++++++++++-
 2 files changed, 432 insertions(+), 20 deletions(-)

diff --git a/scripts/link-worktree-deps.mjs b/scripts/link-worktree-deps.mjs
index 6b2afbc61..996c85dc1 100644
--- a/scripts/link-worktree-deps.mjs
+++ b/scripts/link-worktree-deps.mjs
@@ -34,19 +34,33 @@
  *
  * 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 the `node_modules` SYMLINK first
+ * (`rm node_modules`, it is only a link and nothing else is lost) and then
+ * install, or point the individual `@webjsdev/<pkg>` entries at this worktree
+ * instead. CI always builds from the branch, so it is unaffected either way.
+ *
+ * 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 +69,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 +126,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 +391,39 @@ 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.
+if (process.env.WEBJS_NO_WORKTREE_REPAIR === '1') {
+  console.log('[link-worktree-deps] framework-link repair skipped (WEBJS_NO_WORKTREE_REPAIR=1).');
+} else {
+  const repair = repairPrimaryFrameworkLinks(primary, { check: CHECK });
+  const 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.`);
+    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/test/repo-health/link-worktree-deps.test.mjs b/test/repo-health/link-worktree-deps.test.mjs
index 5fa5058b0..25b2acb2b 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,218 @@ 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('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 }); }
+  });
+});

From 0cdbc2a6a4cb534cffb4f9f162e73a93facb560e Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 03:51:27 +0530
Subject: [PATCH 04/12] fix: repoint primary framework links before removing a
 worktree

The cleanup hook removes merged worktrees and had no idea the primary could
hold `@webjsdev/*` links pointing INTO the tree it is deleting. It now
repoints them at the primary's own packages first, while the target is still
identifiable, and drops an npm staging entry that would be left dangling.

Scoped to links targeting THIS worktree, and conservative: a link it cannot
correct is kept and reported rather than repointed at a missing path, and a
worktree that is KEPT has its links left pointing at it.
---
 .claude/hooks/cleanup-merged-worktree.sh    | 51 ++++++++++-
 test/hooks/cleanup-merged-worktree.test.mjs | 94 ++++++++++++++++++++-
 2 files changed, 142 insertions(+), 3 deletions(-)

diff --git a/.claude/hooks/cleanup-merged-worktree.sh b/.claude/hooks/cleanup-merged-worktree.sh
index a57c0d167..a8acb46db 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,48 @@ 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() {
+  local wt="$1" scope wtreal base 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
+    base=$(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 "$base" in
+      .*-????????)
+        rm -f "$e" && relinked+=("dropped staging entry @webjsdev/$base")
+        ;;
+      *)
+        if [ -e "$primary/$rel" ]; then
+          ln -sfn "../../$rel" "$e" && relinked+=("repointed @webjsdev/$base -> ../../$rel")
+        else
+          relinked+=("KEPT @webjsdev/$base (points into $wt, but $rel is missing in the primary)")
+        fi
+        ;;
+    esac
+  done
+}
+
 removed=()
 kept=()
+relinked=()
 
 # Parse worktree path + branch pairs.
 wt=""
@@ -116,6 +161,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 +175,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/test/hooks/cleanup-merged-worktree.test.mjs b/test/hooks/cleanup-merged-worktree.test.mjs
index 439358c0a..84658d280 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, 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,95 @@ 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');
+});

From 50ccedaee2c24cc14d0c678f234428124a526cc0 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 03:56:08 +0530
Subject: [PATCH 05/12] fix: detect a dangling or foreign framework link in
 webjs doctor

`FRAMEWORK_RESOLVE` is a bare `require.resolve` in a try/catch, so it reports
only resolvable versus not. A link into a live FOREIGN checkout passes it
while being exactly the corrupted state, and silently runs another branch's
framework source. Its remedy also recommended a bare `npm install`, which is
the command that causes this when node_modules is a symlink.

The new `framework-links` check judges the link against the tree that
PHYSICALLY owns its node_modules. That owner rule is what keeps a healthy
linked worktree passing, since there node_modules is itself a symlink at the
primary's, so the primary is the owner. The target is resolved against the
directory the link physically sits in for the same reason: resolving
`../../packages/core` lexically through a symlinked node_modules lands under
the worktree and reports every correctly linked worktree as foreign.
---
 .agents/skills/webjs/references/built-ins.md  |   2 +-
 AGENTS.md                                     |  10 +-
 framework-dev.md                              |  24 +++
 packages/cli/AGENTS.md                        |   4 +-
 packages/cli/lib/doctor.js                    |   2 +-
 packages/cli/lib/doctor/codes.js              |   1 +
 .../lib/doctor/probes/framework-resolves.js   | 156 +++++++++++++++++-
 packages/cli/lib/doctor/runner.js             |   3 +-
 test/cli/doctor.test.mjs                      | 115 ++++++++++++-
 website/app/docs/configuration/page.ts        |   4 +-
 10 files changed, 303 insertions(+), 18 deletions(-)

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/AGENTS.md b/AGENTS.md
index 394e42db4..a80d076f1 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 the `node_modules` SYMLINK first (`rm node_modules`, it is only a link and nothing else is lost) and then install, or repoint the individual `@webjsdev/<pkg>` entries at it. CI always builds from the branch, so it is unaffected either way.
+
+**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` (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 (escape hatch `WEBJS_NO_WORKTREE_REPAIR=1`). 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 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.
 
 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..4295f36ed 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -146,6 +146,30 @@ 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`, and stays narrow: `npm test`, `npm run <script>`, and `npx ...` all pass. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+- **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`, which the `defaultPrimary()` test needs 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/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..76803929e 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, 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(),
     };
   }
   if (!hasNodeModules) {
@@ -79,6 +77,152 @@ 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; }
+}
+
+/**
+ * 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; the link script is named first because it is the cheap path.
+ * @returns {string}
+ */
+function freshWorktreeFix() {
+  return (
+    'Link this worktree to the primary checkout (`npm run worktree:link`), which is the supported ' +
+    'setup and takes seconds. A real `npm install` here also works, since there is no node_modules ' +
+    'symlink in the way yet. Once one exists, never install through it (#1442).'
+  );
+}
+
+/**
+ * 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). Run `npm run worktree:link`, which repairs the shared ' +
+      'tree, or `rm node_modules` first if you want a real self-contained install.'
+    );
+  }
+  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 =
+    'Run `npm run worktree:link` from this checkout, which repoints it. Do NOT run `npm install` ' +
+    'here while node_modules is a symlink: it acts on the checkout that owns the tree (#1442). ' +
+    '`npm run check:worktree-links` lists every entry that needs repair without changing anything.';
+  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/test/cli/doctor.test.mjs b/test/cli/doctor.test.mjs
index 1bcf93aaa..eb64ead61 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,116 @@ 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, /worktree:link/);
+  assert.doesNotMatch(r.fix, /Run `npm install`/);
+});
+
+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, /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/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

From 0874936fd117096c39df532c6dbb5d7177a32778 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 04:09:50 +0530
Subject: [PATCH 06/12] fix: close four defects the review found in the
 worktree-install guards

The doctor remedies are the serious one. They ship in the PUBLISHED CLI and
`bin/webjs.js` prints them verbatim as the `webjs dev` / `webjs start`
preflight failure, so naming `npm run worktree:link` unconditionally sent the
#954 audience, a scaffolded APP worktree with no such script, to run something
that does not exist. They are app-generic again, and name the monorepo script
only where a package.json actually declares it.

`--check` was not read-only: its exit sat inside the repair `else`, so with
`WEBJS_NO_WORKTREE_REPAIR=1` it fell through to the linking loop and the seed
step. The one flag pair documented as changing nothing was the pair that wrote.

The install gate admitted `npm i` but leaked `bun i`, `pnpm i`, bare `yarn`,
`npm clean-install`, `npm ic` and `npm in`. `bun i` is the consequential leak,
since Bun writes THROUGH the link into the primary rather than replacing it.

The teardown repoint shadowed the script-global `base`, which holds the merge
base ref `is_merged()` reads. Latent today, and bash's dynamic scoping makes it
a silent worktree leak the day anything calls a helper from that function.

Each defect gains the regression test that would have caught it.
---
 .../hooks/block-install-in-linked-worktree.sh | 25 +++++++--
 .claude/hooks/cleanup-merged-worktree.sh      | 15 +++--
 AGENTS.md                                     |  2 +-
 .../lib/doctor/probes/framework-resolves.js   | 55 +++++++++++++++----
 scripts/link-worktree-deps.mjs                | 11 +++-
 test/cli/doctor.test.mjs                      | 27 ++++++++-
 .../block-install-in-linked-worktree.test.mjs | 26 +++++++++
 test/repo-health/link-worktree-deps.test.mjs  | 19 +++++++
 8 files changed, 151 insertions(+), 29 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index 029a7298d..590fe8660 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -31,11 +31,26 @@ if [ -z "$cmd" ]; then exit 0; fi
 
 # Install verbs only. `npm run test`, `npm test`, `npm exec`, `npm ls`, and every
 # `npx ...` must pass, so the verb is matched at a word boundary on both sides.
-# The second alternation branch is the flags-before-verb form
-# (`npm --prefix <dir> install`). Only the two flags that themselves name a
-# target directory are admitted there, so this stays targeted rather than
-# swallowing an arbitrary token run and matching something like `npm run install`.
-VERBS='(npm[[:space:]]+(install|i|ci|add|update|dedupe)|bun[[:space:]]+(install|add|update)|pnpm[[:space:]]+(install|add|update)|yarn[[:space:]]+(install|add)|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(install|i|ci|add|update|dedupe))'
+# Every manager's documented install ALIASES, not just its canonical spelling.
+# The gate is worthless if `bun i` walks past it, and Bun is the manager that
+# writes THROUGH the symlink into the primary rather than replacing it, so its
+# aliases are the consequential ones. npm's list is long because npm ships a
+# large alias table of its own (`npm help install`), typo aliases included.
+#
+# Word boundaries on BOTH sides keep this narrow: `npm init` does not match `in`
+# or `i`, because the next character is alphanumeric, and `npm run install-deps`
+# does not match because `run` is not a verb here.
+NPM_VERBS='install|i|in|ins|inst|insta|instal|isnt|isnta|isntal|isntall|add|ci|clean-install|ic|install-clean|sit|it|cit|update|up|upgrade|udpate|dedupe|ddp'
+BUN_VERBS='install|i|add|a|update|up'
+PNPM_VERBS='install|i|add|update|up'
+YARN_VERBS='install|add|up|upgrade'
+# The last two branches are the two shapes a plain verb regex cannot see:
+#   * `npm --prefix <dir> install`, flags BEFORE the verb. Only the two flags
+#     that themselves name a target directory are admitted, so this stays
+#     targeted rather than swallowing a token run and matching `npm run install`.
+#   * bare `yarn`, which IS an install in yarn classic. Matched only when it ends
+#     the command or is followed by a flag, so `yarn test` stays allowed.
+VERBS="(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(${NPM_VERBS})|yarn([[:space:]]+-[^[:space:]]*)*[[:space:]]*(\$|[&|;]))"
 if ! printf '%s' "$cmd" | grep -Eq "(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$)"; then
   exit 0
 fi
diff --git a/.claude/hooks/cleanup-merged-worktree.sh b/.claude/hooks/cleanup-merged-worktree.sh
index a8acb46db..6ca3a5a95 100755
--- a/.claude/hooks/cleanup-merged-worktree.sh
+++ b/.claude/hooks/cleanup-merged-worktree.sh
@@ -104,7 +104,10 @@ is_clean() {
 # scoped to links targeting THIS worktree; the general sweep belongs to
 # `npm run worktree:link`, which you run deliberately.
 repoint_primary_links() {
-  local wt="$1" scope wtreal base abs rel
+  # 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
@@ -114,7 +117,7 @@ repoint_primary_links() {
     # An unmatched glob arrives literally, and is not a symlink, so this also
     # absorbs an empty scope.
     [ -L "$e" ] || continue
-    base=$(basename "$e")
+    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
@@ -122,15 +125,15 @@ repoint_primary_links() {
       *) continue ;;
     esac
     rel="${abs#"$wtreal"/}"
-    case "$base" in
+    case "$entry_name" in
       .*-????????)
-        rm -f "$e" && relinked+=("dropped staging entry @webjsdev/$base")
+        rm -f "$e" && relinked+=("dropped staging entry @webjsdev/$entry_name")
         ;;
       *)
         if [ -e "$primary/$rel" ]; then
-          ln -sfn "../../$rel" "$e" && relinked+=("repointed @webjsdev/$base -> ../../$rel")
+          ln -sfn "../../$rel" "$e" && relinked+=("repointed @webjsdev/$entry_name -> ../../$rel")
         else
-          relinked+=("KEPT @webjsdev/$base (points into $wt, but $rel is missing in the primary)")
+          relinked+=("KEPT @webjsdev/$entry_name (points into $wt, but $rel is missing in the primary)")
         fi
         ;;
     esac
diff --git a/AGENTS.md b/AGENTS.md
index a80d076f1..495dc77da 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -68,7 +68,7 @@ The script discovers the `node_modules` set from the primary checkout rather tha
 
 **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` (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 (escape hatch `WEBJS_NO_WORKTREE_REPAIR=1`). 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 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.
+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.
 
diff --git a/packages/cli/lib/doctor/probes/framework-resolves.js b/packages/cli/lib/doctor/probes/framework-resolves.js
index 76803929e..e59c0d45b 100644
--- a/packages/cli/lib/doctor/probes/framework-resolves.js
+++ b/packages/cli/lib/doctor/probes/framework-resolves.js
@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 
@@ -60,7 +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: freshWorktreeFix(),
+      fix: freshWorktreeFix(appDir),
     };
   }
   if (!hasNodeModules) {
@@ -93,17 +93,48 @@ 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; the link script is named first because it is the cheap path.
+ * is safe here, and this stays the app-generic advice it has always been.
+ * @param {string} appDir
  * @returns {string}
  */
-function freshWorktreeFix() {
+function freshWorktreeFix(appDir) {
   return (
-    'Link this worktree to the primary checkout (`npm run worktree:link`), which is the supported ' +
-    'setup and takes seconds. A real `npm install` here also works, since there is no node_modules ' +
-    'symlink in the way yet. Once one exists, never install through it (#1442).'
+    '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)
   );
 }
 
@@ -118,8 +149,8 @@ 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). Run `npm run worktree:link`, which repairs the shared ' +
-      'tree, or `rm node_modules` first if you want a real self-contained install.'
+      'on that checkout, not this one (#1442). Either reinstall in the checkout that owns the tree, ' +
+      'or `rm node_modules` first (it is only a link) and install here.' + linkScriptHint(appDir)
     );
   }
   return 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).';
@@ -203,9 +234,9 @@ export function checkFrameworkLinks(appDir) {
     };
   }
   const fix =
-    'Run `npm run worktree:link` from this checkout, which repoints it. Do NOT run `npm install` ' +
-    'here while node_modules is a symlink: it acts on the checkout that owns the tree (#1442). ' +
-    '`npm run check:worktree-links` lists every entry that needs repair without changing anything.';
+    '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,
diff --git a/scripts/link-worktree-deps.mjs b/scripts/link-worktree-deps.mjs
index 996c85dc1..bb8668138 100644
--- a/scripts/link-worktree-deps.mjs
+++ b/scripts/link-worktree-deps.mjs
@@ -408,17 +408,24 @@ if (!existsSync(join(primary, 'package.json'))) {
 // 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;
 if (process.env.WEBJS_NO_WORKTREE_REPAIR === '1') {
   console.log('[link-worktree-deps] framework-link repair skipped (WEBJS_NO_WORKTREE_REPAIR=1).');
 } else {
   const repair = repairPrimaryFrameworkLinks(primary, { check: CHECK });
-  const touched = repair.repaired.length + repair.removed.length;
+  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.`);
-    process.exit(touched > 0 ? 1 : 0);
   }
 }
 
+// `--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);
diff --git a/test/cli/doctor.test.mjs b/test/cli/doctor.test.mjs
index eb64ead61..401044d5c 100644
--- a/test/cli/doctor.test.mjs
+++ b/test/cli/doctor.test.mjs
@@ -1858,8 +1858,8 @@ test('framework-links WARNS when the link DANGLES', () => {
   assert.equal(inspectFrameworkLink(dir).state, 'dangling');
   const r = checkFrameworkLinks(dir);
   assert.equal(r.status, 'warn');
-  assert.match(r.fix, /worktree:link/);
-  assert.doesNotMatch(r.fix, /Run `npm install`/);
+  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', () => {
@@ -1899,7 +1899,28 @@ test('framework-resolve stops recommending a bare npm install through a symlink'
   const r = checkFrameworkResolves(dir);
   assert.equal(r.status, 'warn');
   assert.match(r.fix, /do NOT run `npm install`/);
-  assert.match(r.fix, /worktree:link/);
+  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 () => {
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index 67f203025..62d8e1040 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -81,6 +81,32 @@ test('blocks the flags-before-verb form `npm --prefix <worktree> install`', () =
   } 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('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']) {
+      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 {
diff --git a/test/repo-health/link-worktree-deps.test.mjs b/test/repo-health/link-worktree-deps.test.mjs
index 25b2acb2b..951e0d402 100644
--- a/test/repo-health/link-worktree-deps.test.mjs
+++ b/test/repo-health/link-worktree-deps.test.mjs
@@ -562,6 +562,25 @@ describe('framework-link repair (#1442)', () => {
     } finally { rmSync(primary, { recursive: true, force: true }); }
   });
 
+  test('--check stays read-only even with WEBJS_NO_WORKTREE_REPAIR=1 set', () => {
+    // The exit for `--check` used to live INSIDE the repair `else`, so this one
+    // combination fell through to the linking loop and the seed step. The flag
+    // pair AGENTS.md documents as changing nothing was the pair that wrote.
+    const primary = makeRepairPrimary();
+    const wt = makeWorktree();
+    try {
+      const r = spawnSync(process.execPath, [SCRIPT, primary, '--check'], {
+        cwd: wt,
+        encoding: 'utf8',
+        env: cleanEnv({ WEBJS_NO_WORKTREE_REPAIR: '1' }),
+      });
+      assert.equal(r.status, 0);
+      assert.match(r.stdout, /repair skipped/);
+      assert.doesNotMatch(r.stdout, /linked node_modules/, '--check must never link');
+      assert.ok(!existsSync(join(wt, 'node_modules')), '--check must not create the symlink');
+    } 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();

From f5cfde9cab73fc364f5bf1baf424816c8b8e5033 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 04:20:17 +0530
Subject: [PATCH 07/12] fix: close five more defects the delta review found

The bare-`yarn` branch was the worst of these. It 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 working state here, and a gate that cries wolf gets turned off. It is
now its own anchored pattern requiring command position.

The hyphenated npm verbs needed spelling out. The trailing word boundary
excludes `-`, so listing `install` never reached `install-test`,
`install-ci-test` or `clean-install-test`, and the short aliases do not cover
them. The remove verbs are in the table too: `npm rm` in a linked worktree
deletes from the checkout that owns the tree.

`--check` under WEBJS_NO_WORKTREE_REPAIR=1 exited 0 while inspecting nothing,
because `touched` kept its initializer when the repair block was skipped. The
hatch suppresses the repair WRITE, and `--check` never writes, so it now always
inspects. My previous test asserted the exit 0 and locked the defect in.

The `entry_name` rename gets the source guard the last commit claimed for it.
---
 .../hooks/block-install-in-linked-worktree.sh | 42 ++++++++++++------
 AGENTS.md                                     |  2 +-
 framework-dev.md                              |  2 +-
 scripts/link-worktree-deps.mjs                |  5 ++-
 .../block-install-in-linked-worktree.test.mjs | 43 ++++++++++++++++++-
 test/hooks/cleanup-merged-worktree.test.mjs   | 18 +++++++-
 test/repo-health/link-worktree-deps.test.mjs  | 22 +++++++---
 7 files changed, 111 insertions(+), 23 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index 590fe8660..db1f03f18 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -37,21 +37,38 @@ if [ -z "$cmd" ]; then exit 0; fi
 # aliases are the consequential ones. npm's list is long because npm ships a
 # large alias table of its own (`npm help install`), typo aliases included.
 #
+# HYPHENATED verbs must be spelled out. The trailing word boundary excludes `-`,
+# so `install-test` is NOT reached by listing `install`; each hyphenated command
+# needs its own entry, and the short aliases (`it`, `cit`, `sit`) do not cover
+# the long spellings.
+#
+# The REMOVE verbs are here too. `npm rm <pkg>` in a linked worktree deletes
+# from the checkout that owns the tree, the same corruption in the other
+# direction.
+#
 # Word boundaries on BOTH sides keep this narrow: `npm init` does not match `in`
 # or `i`, because the next character is alphanumeric, and `npm run install-deps`
 # does not match because `run` is not a verb here.
-NPM_VERBS='install|i|in|ins|inst|insta|instal|isnt|isnta|isntal|isntall|add|ci|clean-install|ic|install-clean|sit|it|cit|update|up|upgrade|udpate|dedupe|ddp'
-BUN_VERBS='install|i|add|a|update|up'
-PNPM_VERBS='install|i|add|update|up'
-YARN_VERBS='install|add|up|upgrade'
-# The last two branches are the two shapes a plain verb regex cannot see:
-#   * `npm --prefix <dir> install`, flags BEFORE the verb. Only the two flags
-#     that themselves name a target directory are admitted, so this stays
-#     targeted rather than swallowing a token run and matching `npm run install`.
-#   * bare `yarn`, which IS an install in yarn classic. Matched only when it ends
-#     the command or is followed by a flag, so `yarn test` stays allowed.
-VERBS="(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(${NPM_VERBS})|yarn([[:space:]]+-[^[:space:]]*)*[[:space:]]*(\$|[&|;]))"
-if ! printf '%s' "$cmd" | grep -Eq "(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$)"; then
+NPM_VERBS='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|r'
+BUN_VERBS='install|i|add|a|update|up|remove|rm'
+PNPM_VERBS='install|i|add|update|upgrade|up|dedupe|remove|rm|uninstall|un'
+YARN_VERBS='install|add|upgrade|up|dedupe|remove'
+# `npm --prefix <dir> install`, flags BEFORE the verb. Only the two flags that
+# themselves name a target directory are admitted, so this stays targeted rather
+# than swallowing a token run and matching `npm run install`.
+VERBS="(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(${NPM_VERBS}))"
+
+# Bare `yarn` IS an install in yarn classic, and it needs its own anchored
+# pattern rather than a branch of VERBS. VERBS is wrapped in a generic
+# non-word-character prefix, which any space satisfies, so a bare-yarn branch
+# inside it matched the token ANYWHERE in the command: `which yarn`,
+# `rm -rf /tmp/yarn` and `git switch -c feat/yarn` all blocked. Here `yarn` must
+# sit in COMMAND position, at the start or straight after a `&&`, `||`, `;` or
+# `|`, and be followed only by flags.
+BARE_YARN='(^|[&|;])[[:space:]]*yarn([[:space:]]+-[^[:space:]]*)*[[:space:]]*($|[&|;])'
+
+if ! printf '%s' "$cmd" | grep -Eq "(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$)" \
+  && ! printf '%s' "$cmd" | grep -Eq "$BARE_YARN"; then
   exit 0
 fi
 
@@ -61,6 +78,7 @@ fi
 # tokens that appear BEFORE the install verb and let them supersede the cwd, then
 # add any directory a package manager is pointed at explicitly.
 prefix=$(printf '%s' "$cmd" | sed -E "s/(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$).*//")
+prefix=$(printf '%s' "$prefix" | sed -E "s/${BARE_YARN}.*//")
 
 eff="$PWD"
 resolve_against_eff() {
diff --git a/AGENTS.md b/AGENTS.md
index 495dc77da..e046dd602 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,7 +66,7 @@ The script discovers the `node_modules` set from the primary checkout rather tha
 
 **Know what this does NOT give you.** The worktree then runs the PRIMARY checkout's framework source through every bare `@webjsdev/*` specifier, because `<primary>/node_modules/@webjsdev/core` is a relative symlink into `<primary>/packages/core` and resolving through the linked root lands there. Relative imports (`../../../src/x.js`) and the browser suite, which web-test-runner serves from the worktree, do use the worktree's own files. So linking makes the suite RUNNABLE, not self-testing: if you are editing `packages/core/src` or `packages/server/src` and need a bare-specifier consumer to exercise YOUR copy, delete the `node_modules` SYMLINK first (`rm node_modules`, it is only a link and nothing else is lost) and then install, or repoint the individual `@webjsdev/<pkg>` entries at it. CI always builds from the branch, so it is unaffected either way.
 
-**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` (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 (escape hatch `WEBJS_NO_WORKTREE_REPAIR=1`). 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`.
+**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` (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.
 
diff --git a/framework-dev.md b/framework-dev.md
index 4295f36ed..25706ce7d 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -165,7 +165,7 @@ 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`, and stays narrow: `npm test`, `npm run <script>`, and `npx ...` all pass. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
 - **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`, which the `defaultPrimary()` test needs 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`.
+- **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`.
diff --git a/scripts/link-worktree-deps.mjs b/scripts/link-worktree-deps.mjs
index bb8668138..dbe1d480c 100644
--- a/scripts/link-worktree-deps.mjs
+++ b/scripts/link-worktree-deps.mjs
@@ -409,7 +409,10 @@ if (!existsSync(join(primary, 'package.json'))) {
 // 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;
-if (process.env.WEBJS_NO_WORKTREE_REPAIR === '1') {
+// 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 });
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index 62d8e1040..e47d09c4d 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -96,12 +96,53 @@ test('blocks every manager\'s install ALIAS, not just the canonical spelling', (
   } 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 {
+    for (const cmd of ['npm uninstall x', 'npm rm x', 'npm r 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('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']) {
+    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 }); }
diff --git a/test/hooks/cleanup-merged-worktree.test.mjs b/test/hooks/cleanup-merged-worktree.test.mjs
index 84658d280..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, mkdirSync, writeFileSync, existsSync, chmodSync, symlinkSync, readlinkSync, lstatSync } 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';
@@ -282,3 +282,19 @@ test('leaves the primary links untouched when the worktree is KEPT', () => {
   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 951e0d402..f88cc3608 100644
--- a/test/repo-health/link-worktree-deps.test.mjs
+++ b/test/repo-health/link-worktree-deps.test.mjs
@@ -562,22 +562,32 @@ describe('framework-link repair (#1442)', () => {
     } finally { rmSync(primary, { recursive: true, force: true }); }
   });
 
-  test('--check stays read-only even with WEBJS_NO_WORKTREE_REPAIR=1 set', () => {
-    // The exit for `--check` used to live INSIDE the repair `else`, so this one
-    // combination fell through to the linking loop and the seed step. The flag
-    // pair AGENTS.md documents as changing nothing was the pair that wrote.
+  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, 0);
-      assert.match(r.stdout, /repair skipped/);
+      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 }); }
   });
 

From 4c6b094575fe6707352d364623513a72916d8345 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 04:33:56 +0530
Subject: [PATCH 08/12] fix: judge a command, not a token, in the install gate

The false-positive class fixed for bare `yarn` last round was left standing
for the other three managers, and the remove verbs widened it. The gate
matched a manager+verb pair ANYWHERE in the line, so it blocked this PR's own
commit subject, `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 gets turned off.

The command is now split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment
is judged only by what it STARTS with, after leading env assignments and
wrappers like `sudo` are stripped. That kills the class structurally rather
than by adding another anchored special case per manager.

A GLOBAL install is never blocked either. `-g` writes to the npm prefix, never
through the link, and `npm update -g webjsdev` is this repo's own documented
post-release step, so the gate was refusing a workflow the repo requires over
a corruption that cannot occur.

Docs updated for both, plus the remove verbs the last commit added silently.
---
 .../hooks/block-install-in-linked-worktree.sh | 180 +++++++++---------
 AGENTS.md                                     |   2 +-
 framework-dev.md                              |   4 +-
 .../block-install-in-linked-worktree.test.mjs |  44 +++++
 4 files changed, 141 insertions(+), 89 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index db1f03f18..008869db1 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -15,6 +15,16 @@
 # manager starts. `scripts/warn-worktree-install.mjs` covers every other tool by
 # reporting rather than blocking.
 #
+# ## It matches a COMMAND, never a token
+#
+# The command is split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment is
+# judged only by what it STARTS with. Matching the manager token anywhere in the
+# line instead 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"`. 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.
+#
 # The predicate runs against the COMMAND's target directory, not just the session
 # cwd: the harness resets cwd to the primary checkout between commands, so a real
 # install in a worktree arrives as `cd /path/to/worktree && npm ci`.
@@ -29,109 +39,105 @@ input=$(cat)
 cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
 if [ -z "$cmd" ]; then exit 0; fi
 
-# Install verbs only. `npm run test`, `npm test`, `npm exec`, `npm ls`, and every
-# `npx ...` must pass, so the verb is matched at a word boundary on both sides.
 # Every manager's documented install ALIASES, not just its canonical spelling.
 # The gate is worthless if `bun i` walks past it, and Bun is the manager that
-# writes THROUGH the symlink into the primary rather than replacing it, so its
-# aliases are the consequential ones. npm's list is long because npm ships a
-# large alias table of its own (`npm help install`), typo aliases included.
-#
-# HYPHENATED verbs must be spelled out. The trailing word boundary excludes `-`,
-# so `install-test` is NOT reached by listing `install`; each hyphenated command
-# needs its own entry, and the short aliases (`it`, `cit`, `sit`) do not cover
-# the long spellings.
+# writes THROUGH the symlink into the primary rather than replacing it.
 #
-# The REMOVE verbs are here too. `npm rm <pkg>` in a linked worktree deletes
-# from the checkout that owns the tree, the same corruption in the other
-# direction.
+# HYPHENATED verbs are spelled out: the trailing word boundary excludes `-`, so
+# `install-test` is NOT reached by listing `install`, and the short aliases
+# (`it`, `cit`, `sit`) do not cover the long spellings.
 #
-# Word boundaries on BOTH sides keep this narrow: `npm init` does not match `in`
-# or `i`, because the next character is alphanumeric, and `npm run install-deps`
-# does not match because `run` is not a verb here.
+# The REMOVE verbs are here too. `npm rm <pkg>` in a linked worktree deletes from
+# the checkout that owns the tree, the same corruption in the other direction.
 NPM_VERBS='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|r'
 BUN_VERBS='install|i|add|a|update|up|remove|rm'
 PNPM_VERBS='install|i|add|update|upgrade|up|dedupe|remove|rm|uninstall|un'
 YARN_VERBS='install|add|upgrade|up|dedupe|remove'
-# `npm --prefix <dir> install`, flags BEFORE the verb. Only the two flags that
+# `npm --prefix <dir> install` puts flags BEFORE the verb. Only the two flags that
 # themselves name a target directory are admitted, so this stays targeted rather
 # than swallowing a token run and matching `npm run install`.
-VERBS="(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]&|;]+[[:space:]]+(${NPM_VERBS}))"
+SEG_VERBS="^(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]]+[[:space:]]+(${NPM_VERBS}))([^[:alnum:]_-]|\$)"
+# Bare `yarn` IS an install in yarn classic, but only when it is the whole
+# command: `yarn test` is not one.
+SEG_BARE_YARN='^yarn([[:space:]]+-[^[:space:]]*)*[[: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:]]|$)'
 
-# Bare `yarn` IS an install in yarn classic, and it needs its own anchored
-# pattern rather than a branch of VERBS. VERBS is wrapped in a generic
-# non-word-character prefix, which any space satisfies, so a bare-yarn branch
-# inside it matched the token ANYWHERE in the command: `which yarn`,
-# `rm -rf /tmp/yarn` and `git switch -c feat/yarn` all blocked. Here `yarn` must
-# sit in COMMAND position, at the start or straight after a `&&`, `||`, `;` or
-# `|`, and be followed only by flags.
-BARE_YARN='(^|[&|;])[[:space:]]*yarn([[:space:]]+-[^[:space:]]*)*[[:space:]]*($|[&|;])'
-
-if ! printf '%s' "$cmd" | grep -Eq "(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$)" \
-  && ! printf '%s' "$cmd" | grep -Eq "$BARE_YARN"; then
-  exit 0
-fi
+# Walk the segments in order so a `cd` earlier in the line moves the target the
+# way the shell would.
+eff="$PWD"
+target=""
+while IFS= read -r seg; do
+  seg="${seg#"${seg%%[![:space:]]*}"}"
+  [ -z "$seg" ] && continue
 
-# Candidate target directories. An install acts on ONE directory, so the session
-# cwd counts only until the command changes out of it: `cd /tmp && npm install`
-# targets /tmp, not the worktree this shell happens to sit in. So walk the `cd`
-# tokens that appear BEFORE the install verb and let them supersede the cwd, then
-# add any directory a package manager is pointed at explicitly.
-prefix=$(printf '%s' "$cmd" | sed -E "s/(^|[^[:alnum:]_-])${VERBS}([^[:alnum:]_-]|\$).*//")
-prefix=$(printf '%s' "$prefix" | sed -E "s/${BARE_YARN}.*//")
+  # Strip leading env assignments and benign wrappers, so `FOO=1 npm ci` and
+  # `sudo npm ci` are still judged on the manager that follows them.
+  while :; do
+    case "$seg" in
+      [A-Za-z_]*=*)
+        rest="${seg#* }"; [ "$rest" = "$seg" ] && break
+        seg="${rest#"${rest%%[![:space:]]*}"}" ;;
+      sudo\ *|env\ *|time\ *|nice\ *)
+        rest="${seg#* }"
+        seg="${rest#"${rest%%[![:space:]]*}"}" ;;
+      *) break ;;
+    esac
+  done
 
-eff="$PWD"
-resolve_against_eff() {
-  local d="$1"
-  case "$d" in
-    /*) printf '%s' "$d" ;;
-    ~*) printf '%s' '' ;;
-    *) printf '%s' "$eff/$d" ;;
+  case "$seg" in
+    cd|cd\ *)
+      d="${seg#cd}"; d="${d#"${d%%[![:space:]]*}"}"; d="${d%% *}"
+      d=$(printf '%s' "$d" | tr -d "\"'")
+      case "$d" in
+        '') ;;
+        /*) eff="$d" ;;
+        '~'*) ;;
+        *) eff="$eff/$d" ;;
+      esac
+      continue ;;
   esac
-}
-while IFS= read -r d; do
-  [ -n "$d" ] || continue
-  d=$(printf '%s' "$d" | tr -d "\"'")
-  r=$(resolve_against_eff "$d")
-  [ -n "$r" ] && eff="$r"
-done < <(printf '%s\n' "$prefix" \
-  | grep -oE '(^|[^[:alnum:]_./-])cd[[:space:]]+[^[:space:]&|;]+' \
-  | sed -E 's/.*cd[[:space:]]+//')
 
-cands=("$eff")
-while IFS= read -r d; do
-  [ -n "$d" ] || continue
-  d=$(printf '%s' "$d" | tr -d "\"'")
-  r=$(resolve_against_eff "$d")
-  [ -n "$r" ] && cands+=("$r")
-done < <(printf '%s\n' "$cmd" \
-  | grep -oE '(^|[[:space:]])(-C|--prefix)[[:space:]=]+[^[:space:]&|;]+' \
-  | sed -E 's/.*(-C|--prefix)[[:space:]=]+//')
+  if printf '%s' "$seg" | grep -Eq "$SEG_VERBS" || printf '%s' "$seg" | grep -Eq "$SEG_BARE_YARN"; then
+    printf '%s' "$seg" | grep -Eq "$GLOBAL" && continue
+    target="$eff"
+    # An explicit --prefix / -C on the install itself wins over the cwd.
+    p=$(printf '%s' "$seg" | grep -oE '(^|[[:space:]])(-C|--prefix)[[:space:]=]+[^[:space:]]+' | sed -E 's/.*(-C|--prefix)[[:space:]=]+//' | tr -d "\"'" | head -1)
+    if [ -n "$p" ]; then
+      case "$p" in /*) target="$p" ;; '~'*) ;; *) target="$eff/$p" ;; esac
+    fi
+    break
+  fi
+done <<EOF
+$(printf '%s' "$cmd" | tr '&|;()' '\n\n\n\n\n')
+EOF
 
-for cand in "${cands[@]}"; do
-  [ -d "$cand" ] || continue
-  # The install lands at the package root, which for a subdirectory is the
-  # enclosing checkout, so judge the git toplevel too.
-  top=$(git -C "$cand" rev-parse --show-toplevel 2>/dev/null || true)
-  for dir in "$cand" "$top"; do
-    [ -n "$dir" ] || continue
-    [ -L "$dir/node_modules" ] || continue
-    target=$(cd "$(dirname "$dir/node_modules")" 2>/dev/null && readlink "node_modules" || true)
-    owner=$(cd "$dir" 2>/dev/null && cd "$(readlink node_modules)" 2>/dev/null && pwd -P || printf '%s' "${target:-the primary checkout}")
-    {
-      echo "BLOCKED: this command installs into $dir, whose node_modules is a SYMLINK at $owner."
-      echo "An install through that link damages the checkout that OWNS the tree, not this one:"
-      echo "  npm ci       DELETES $owner outright, before any lifecycle script can run"
-      echo "  bun install  writes packages and .bin entries straight into $owner"
-      echo "  npm install  silently REPLACES the link with a real tree, detaching this worktree"
-      echo "Safe alternatives:"
-      echo "  npm run worktree:link          links a fresh worktree; it never installs"
-      echo "  a real install with NO symlink in the way. Run \`rm node_modules\` first (it is"
-      echo "  only a link, nothing else is lost), or install in the PRIMARY checkout."
-      echo "Escape hatch for a deliberate exception: WEBJS_NO_WORKTREE_INSTALL_GATE=1."
-    } >&2
-    exit 2
-  done
+[ -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.
+top=$(git -C "$target" rev-parse --show-toplevel 2>/dev/null || true)
+for dir in "$target" "$top"; do
+  [ -n "$dir" ] || continue
+  [ -L "$dir/node_modules" ] || continue
+  owner=$(cd "$dir" 2>/dev/null && cd "$(readlink node_modules)" 2>/dev/null && pwd -P) || owner="the checkout it points at"
+  {
+    echo "BLOCKED: this command installs into $dir, whose node_modules is a SYMLINK at $owner."
+    echo "An install through that link damages the checkout that OWNS the tree, not this one:"
+    echo "  npm ci       DELETES $owner outright, before any lifecycle script can run"
+    echo "  bun install  writes packages and .bin entries straight into $owner"
+    echo "  npm install  silently REPLACES the link with a real tree, detaching this worktree"
+    echo "A remove verb (npm rm, bun remove) deletes from that same owning checkout."
+    echo "Safe alternatives:"
+    echo "  npm run worktree:link          links a fresh worktree; it never installs"
+    echo "  a real install with NO symlink in the way. Run \`rm node_modules\` first (it is"
+    echo "  only a link, nothing else is lost), or install in the PRIMARY checkout."
+    echo "A 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/AGENTS.md b/AGENTS.md
index e046dd602..856198c52 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,7 +66,7 @@ The script discovers the `node_modules` set from the primary checkout rather tha
 
 **Know what this does NOT give you.** The worktree then runs the PRIMARY checkout's framework source through every bare `@webjsdev/*` specifier, because `<primary>/node_modules/@webjsdev/core` is a relative symlink into `<primary>/packages/core` and resolving through the linked root lands there. Relative imports (`../../../src/x.js`) and the browser suite, which web-test-runner serves from the worktree, do use the worktree's own files. So linking makes the suite RUNNABLE, not self-testing: if you are editing `packages/core/src` or `packages/server/src` and need a bare-specifier consumer to exercise YOUR copy, delete the `node_modules` SYMLINK first (`rm node_modules`, it is only a link and nothing else is lost) and then install, or repoint the individual `@webjsdev/<pkg>` entries at it. CI always builds from the branch, so it is unaffected either way.
 
-**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` (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`.
+**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.
 
diff --git a/framework-dev.md b/framework-dev.md
index 25706ce7d..d329c612c 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -162,7 +162,9 @@ Measured on npm 11.19.0 and bun 1.3.14:
 
 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`, and stays narrow: `npm test`, `npm run <script>`, and `npx ...` all pass. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+- **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`, covering every manager's documented aliases (`bun i` matters most, since Bun writes THROUGH the link) and the REMOVE verbs too, because `npm rm` in a linked worktree deletes from the checkout that owns the tree. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+
+  It judges a COMMAND, never a token. The command is split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment is judged only by what it STARTS with, after leading env assignments and wrappers like `sudo` are stripped. 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`.
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index e47d09c4d..5b4c76600 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -116,6 +116,50 @@ test('blocks the REMOVE verbs, which delete from the owning checkout', () => {
   } 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',
+    ]) {
+      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']) {
+      assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
+    }
+  } 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

From 0017635f714e41fab706794e6190a0b784401648 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 04:44:37 +0530
Subject: [PATCH 09/12] fix: stop an `=` in a flag from disabling the install
 gate

The env-assignment strip used an unanchored `[A-Za-z_]*=*` case glob, which
matches the WHOLE segment whenever any LATER token carries an `=`. It then ate
the leading words, so `npm install --omit=dev`, `npm ci --loglevel=error` and
`npm install --workspace=packages/core` were all ALLOWED. That is the one
direction that matters, since the gate exists to stop a write, and the last is
an ordinary command in this monorepo. It also made the `--prefix=` branch of
the regexes dead while the space-form test stayed green over it.

The strip is token-wise now, and the assignment test is anchored to the first
token alone.

Walking past arbitrary tokens after a wrapper turned out to re-create the
token-anywhere class one level in: with `command` and `bash` treated as
wrappers, `command -v yarn` blocked and `bash -c "echo yarn"` would have. So
the walk covers a wrapper's own flags and their values only, and `command`,
`exec`, `bash` and `sh` are not wrappers. `bash -c "npm ci"` is a documented
accepted gap rather than a parser for nested shells.
---
 .../hooks/block-install-in-linked-worktree.sh | 58 +++++++++++++++----
 .../block-install-in-linked-worktree.test.mjs | 45 +++++++++++++-
 2 files changed, 91 insertions(+), 12 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index 008869db1..d874e3407 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -69,22 +69,58 @@ GLOBAL='(^|[[:space:]])(-g|--global)([[:space:]]|$)'
 eff="$PWD"
 target=""
 while IFS= read -r seg; do
+  # Quotes are dropped so a quoted command body tokenizes (`bash -c "npm ci"`).
+  # This is safe: what keeps `git commit -m "npm ci"` out is the command-position
+  # rule below, never the quoting.
+  seg=$(printf '%s' "$seg" | tr -d '"'"'"'')
   seg="${seg#"${seg%%[![:space:]]*}"}"
   [ -z "$seg" ] && continue
 
-  # Strip leading env assignments and benign wrappers, so `FOO=1 npm ci` and
-  # `sudo npm ci` are still judged on the manager that follows them.
-  while :; do
-    case "$seg" in
-      [A-Za-z_]*=*)
-        rest="${seg#* }"; [ "$rest" = "$seg" ] && break
-        seg="${rest#"${rest%%[![:space:]]*}"}" ;;
-      sudo\ *|env\ *|time\ *|nice\ *)
-        rest="${seg#* }"
-        seg="${rest#"${rest%%[![:space:]]*}"}" ;;
-      *) break ;;
+  # Strip leading env assignments and benign wrappers, so `FOO=1 npm ci`,
+  # `sudo npm ci` and `bash -c "npm ci"` are still judged on the manager that
+  # follows them.
+  #
+  # This is done TOKEN BY TOKEN, and the env-assignment test is anchored to the
+  # first token alone. An unanchored `[A-Za-z_]*=*` case glob matches the WHOLE
+  # segment whenever any LATER token contains `=`, so it ate leading words and
+  # `npm install --omit=dev`, `npm ci --loglevel=error` and
+  # `npm install --workspace=packages/core` all failed OPEN. Failing open is the
+  # one direction that matters here, since the whole point is to stop a write.
+  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
+      *=*)
+        # A real env assignment: NAME=..., NAME being a valid shell identifier.
+        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) ;;
+      -*)
+        # A wrapper's OWN flag, e.g. `sudo -u foo npm ci`.
+        [ "$wrapper_seen" = "1" ] && { prev_flag=1; strip=1; } ;;
+      *)
+        # The VALUE of the wrapper flag just stripped, e.g. the `foo` in `-u foo`
+        # or the `10` in `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"` would reach the bare-yarn branch and block.
+        # `command`, `exec`, `bash` and `sh` are NOT wrappers here for that reason,
+        # so `command -v yarn` stays allowed and `bash -c "npm ci"` is a known,
+        # accepted gap rather than a parser for nested shells.
+        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
 
   case "$seg" in
     cd|cd\ *)
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index 5b4c76600..f839f3db1 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -154,12 +154,55 @@ test('never blocks a GLOBAL install, which writes to the npm prefix not the link
 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']) {
+    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',
+      'pnpm add x --dir=/y',
+      '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

From 92e8295715ed28f13763515e9948518d2e05b3d6 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 05:00:38 +0530
Subject: [PATCH 10/12] fix: rebuild the install matcher in explicit stages

Five review rounds each found a defect in this one file, in both directions,
so this replaces the accreted matcher rather than patching case seven.

Recognising a package-manager invocation inside an arbitrary shell command was
the whole problem. Every false positive came from quoted text and every false
negative from an over-narrow token scan, so the matcher now runs in stages:
quoted spans are removed FIRST, the remainder is split on separators, a segment
is judged by its FIRST token, and only inside a manager-led segment are the
remaining tokens scanned for the first recognised verb.

Removing quoted spans first is what kills the false-positive class at the root.
A manager never has its own name inside quotes, while ordinary commands carry
shell metacharacters there constantly, so `git commit -m "fix: the link; npm
install now blocks"` no longer reads as two commands.

Scanning for the first RECOGNISED verb, with an explicit safe-verb list to stop
on, is what kills the false-negative class: `npm --silent install` and
`npm -w packages/core install` now block, while `npm run test -- --grep add`
still does not. The scan no longer stops at the verb either, since a trailing
`--prefix` decides which directory is judged.

Also fixes `cd --` / `cd ~` / `pushd`, makes `yarnpkg` real rather than a token
listed in one place and matched nowhere, and drops an inert quote strip. The
two branches that were holding real blocks with no coverage, the manager
carve-out and the git-toplevel escalation, now have tests.
---
 .../hooks/block-install-in-linked-worktree.sh | 182 +++++++++++-------
 .../block-install-in-linked-worktree.test.mjs |  80 +++++++-
 2 files changed, 187 insertions(+), 75 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index d874e3407..5bc327216 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -15,19 +15,28 @@
 # manager starts. `scripts/warn-worktree-install.mjs` covers every other tool by
 # reporting rather than blocking.
 #
-# ## It matches a COMMAND, never a token
+# ## How the matching works, and why it is shaped this way
 #
-# The command is split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment is
-# judged only by what it STARTS with. Matching the manager token anywhere in the
-# line instead 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"`. 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.
+# 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:
 #
-# The predicate runs against the COMMAND's target directory, not just the session
-# cwd: the harness resets cwd to the primary checkout between commands, so a real
-# install in a worktree arrives as `cd /path/to/worktree && npm ci`.
+#   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.
@@ -39,53 +48,35 @@ input=$(cat)
 cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
 if [ -z "$cmd" ]; then exit 0; fi
 
-# Every manager's documented install ALIASES, not just its canonical spelling.
-# The gate is worthless if `bun i` walks past it, and Bun is the manager that
-# writes THROUGH the symlink into the primary rather than replacing it.
-#
-# HYPHENATED verbs are spelled out: the trailing word boundary excludes `-`, so
-# `install-test` is NOT reached by listing `install`, and the short aliases
-# (`it`, `cit`, `sit`) do not cover the long spellings.
-#
-# The REMOVE verbs are here too. `npm rm <pkg>` in a linked worktree deletes from
-# the checkout that owns the tree, the same corruption in the other direction.
-NPM_VERBS='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|r'
-BUN_VERBS='install|i|add|a|update|up|remove|rm'
-PNPM_VERBS='install|i|add|update|upgrade|up|dedupe|remove|rm|uninstall|un'
-YARN_VERBS='install|add|upgrade|up|dedupe|remove'
-# `npm --prefix <dir> install` puts flags BEFORE the verb. Only the two flags that
-# themselves name a target directory are admitted, so this stays targeted rather
-# than swallowing a token run and matching `npm run install`.
-SEG_VERBS="^(npm[[:space:]]+(${NPM_VERBS})|bun[[:space:]]+(${BUN_VERBS})|pnpm[[:space:]]+(${PNPM_VERBS})|yarn[[:space:]]+(${YARN_VERBS})|(npm|pnpm|yarn)[[:space:]]+(--prefix|-C)[[:space:]=]+[^[:space:]]+[[:space:]]+(${NPM_VERBS}))([^[:alnum:]_-]|\$)"
-# Bare `yarn` IS an install in yarn classic, but only when it is the whole
-# command: `yarn test` is not one.
-SEG_BARE_YARN='^yarn([[:space:]]+-[^[:space:]]*)*[[:space:]]*$'
+# 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.
+INSTALL_VERBS='install-ci-test|clean-install-test|install-clean|clean-install|install-test|install|isntall|isntal|isnta|isnt|instal|insta|inst|ins|in|i|add|a|ci|cit|sit|it|ic|update|upgrade|udpate|up|dedupe|ddp|uninstall|unlink|un|remove|rm|r|link|ln|rebuild|rb|prune'
+# 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'
 # 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:]]|$)'
 
-# Walk the segments in order so a `cd` earlier in the line moves the target the
-# way the shell would.
+# STAGE 1: remove quoted spans. See the docblock; this is what keeps a shell
+# metacharacter inside a commit message from being read as a command boundary.
+scrubbed=$(printf '%s' "$cmd" | sed -e "s/'[^']*'/ /g" -e 's/"[^"]*"/ /g')
+
 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
-  # Quotes are dropped so a quoted command body tokenizes (`bash -c "npm ci"`).
-  # This is safe: what keeps `git commit -m "npm ci"` out is the command-position
-  # rule below, never the quoting.
-  seg=$(printf '%s' "$seg" | tr -d '"'"'"'')
   seg="${seg#"${seg%%[![:space:]]*}"}"
   [ -z "$seg" ] && continue
 
-  # Strip leading env assignments and benign wrappers, so `FOO=1 npm ci`,
-  # `sudo npm ci` and `bash -c "npm ci"` are still judged on the manager that
-  # follows them.
-  #
-  # This is done TOKEN BY TOKEN, and the env-assignment test is anchored to the
-  # first token alone. An unanchored `[A-Za-z_]*=*` case glob matches the WHOLE
-  # segment whenever any LATER token contains `=`, so it ate leading words and
-  # `npm install --omit=dev`, `npm ci --loglevel=error` and
-  # `npm install --workspace=packages/core` all failed OPEN. Failing open is the
-  # one direction that matters here, since the whole point is to stop a write.
+  # 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
@@ -94,7 +85,6 @@ while IFS= read -r seg; do
     strip=0
     case "$first" in
       *=*)
-        # A real env assignment: NAME=..., NAME being a valid shell identifier.
         name="${first%%=*}"
         case "$name" in
           ''|*[!A-Za-z0-9_]*|[0-9]*) ;;
@@ -102,17 +92,14 @@ while IFS= read -r seg; do
         esac ;;
       sudo|env|time|nice) wrapper_seen=1; prev_flag=0; strip=1 ;;
       npm|bun|pnpm|yarn|yarnpkg) ;;
-      -*)
-        # A wrapper's OWN flag, e.g. `sudo -u foo npm ci`.
-        [ "$wrapper_seen" = "1" ] && { prev_flag=1; strip=1; } ;;
+      -*) [ "$wrapper_seen" = "1" ] && { prev_flag=1; strip=1; } ;;
       *)
-        # The VALUE of the wrapper flag just stripped, e.g. the `foo` in `-u foo`
-        # or the `10` in `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"` would reach the bare-yarn branch and block.
-        # `command`, `exec`, `bash` and `sh` are NOT wrappers here for that reason,
-        # so `command -v yarn` stays allowed and `bash -c "npm ci"` is a known,
-        # accepted gap rather than a parser for nested shells.
+        # 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.
         if [ "$wrapper_seen" = "1" ] && [ "$prev_flag" = "1" ]; then prev_flag=0; strip=1; fi ;;
     esac
     [ "$strip" = "1" ] || break
@@ -122,31 +109,78 @@ while IFS= read -r seg; do
   done
   [ -n "$seg" ] || continue
 
-  case "$seg" in
-    cd|cd\ *)
-      d="${seg#cd}"; d="${d#"${d%%[![:space:]]*}"}"; d="${d%% *}"
-      d=$(printf '%s' "$d" | tr -d "\"'")
+  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
 
-  if printf '%s' "$seg" | grep -Eq "$SEG_VERBS" || printf '%s' "$seg" | grep -Eq "$SEG_BARE_YARN"; then
-    printf '%s' "$seg" | grep -Eq "$GLOBAL" && continue
-    target="$eff"
-    # An explicit --prefix / -C on the install itself wins over the cwd.
-    p=$(printf '%s' "$seg" | grep -oE '(^|[[:space:]])(-C|--prefix)[[:space:]=]+[^[:space:]]+' | sed -E 's/.*(-C|--prefix)[[:space:]=]+//' | tr -d "\"'" | head -1)
-    if [ -n "$p" ]; then
-      case "$p" in /*) target="$p" ;; '~'*) ;; *) target="$eff/$p" ;; esac
-    fi
-    break
+  # STAGE 4: only a manager-led segment can be an install.
+  case "$head_tok" in
+    npm|bun|pnpm|yarn|yarnpkg) ;;
+    *) continue ;;
+  esac
+  shift
+
+  # A global install never touches this tree.
+  printf '%s' "$seg" | grep -Eq "$GLOBAL" && continue
+
+  verdict=""
+  prefix_dir=""
+  pending_prefix=0
+  while [ $# -gt 0 ]; do
+    tok="$1"; shift
+    case "$tok" in
+      --prefix=*|-C=*) prefix_dir="${tok#*=}"; continue ;;
+      --prefix|-C) 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 "^(${INSTALL_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.
+  if [ -z "$verdict" ]; then
+    case "$head_tok" in yarn|yarnpkg) verdict="install" ;; 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' "$cmd" | tr '&|;()' '\n\n\n\n\n')
+$(printf '%s' "$scrubbed" | tr '&|;()' '\n\n\n\n\n')
 EOF
 
 [ -n "$target" ] || exit 0
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index f839f3db1..b25549563 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -5,7 +5,7 @@
 // (`npm test`, `npm run <script>`, `npx ...`) have to pass.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
+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';
@@ -131,6 +131,14 @@ test('judges a COMMAND, never a token that merely appears in the line', () => {
       '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}\``);
     }
@@ -279,3 +287,73 @@ test('honours 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 every `cd` spelling, including ~, --, and pushd', () => {
+  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 }); }
+});

From 41c562ca3cf267ee84abf393bc386112485a51ab Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 05:12:49 +0530
Subject: [PATCH 11/12] fix: keep quoted paths, drop heredoc bodies, split the
 verb tables

The previous commit's quote handling DELETED quoted spans, which took the path
with them. `cd "<worktree>" && npm ci` left `cd` with no argument, so the
install was judged against the session cwd and allowed. That is the arrival
shape this hook exists for, and quoting a path is the ordinary spelling, so the
rewrite regressed the headline case.

Quoted spans are now neutralised rather than removed: the quote characters go,
the content stays, and only the separators inside them are defused. It is a
character-by-character state machine because quote nesting has to be tracked,
and a single-quote sed pass running first paired the apostrophe in `can't` with
the next quote in the line and swallowed a real install between them.

Heredoc bodies are dropped. This repo's docs are full of `npm install` lines
and a newline is a command separator here.

The merged verb table is per manager again: `a` is a BUN alias, so merging it
blocked `npm --workspace a run build`, and `bun upgrade` upgrades the Bun
binary rather than node_modules. `npm audit fix` joins the block list on the
same rationale as `link`, `rebuild` and `prune`, `--cwd` and `--dir` are mined
as target directories like `--prefix`, and an informational `yarn --version` is
no longer read as a bare install.
---
 .../hooks/block-install-in-linked-worktree.sh | 85 ++++++++++++++--
 framework-dev.md                              |  4 +-
 .../block-install-in-linked-worktree.test.mjs | 96 ++++++++++++++++++-
 3 files changed, 171 insertions(+), 14 deletions(-)

diff --git a/.claude/hooks/block-install-in-linked-worktree.sh b/.claude/hooks/block-install-in-linked-worktree.sh
index 5bc327216..078bbdf5f 100755
--- a/.claude/hooks/block-install-in-linked-worktree.sh
+++ b/.claude/hooks/block-install-in-linked-worktree.sh
@@ -53,17 +53,74 @@ if [ -z "$cmd" ]; then exit 0; fi
 # 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.
-INSTALL_VERBS='install-ci-test|clean-install-test|install-clean|clean-install|install-test|install|isntall|isntal|isnta|isnt|instal|insta|inst|ins|in|i|add|a|ci|cit|sit|it|ic|update|upgrade|udpate|up|dedupe|ddp|uninstall|unlink|un|remove|rm|r|link|ln|rebuild|rb|prune'
+# 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: remove quoted spans. See the docblock; this is what keeps a shell
-# metacharacter inside a commit message from being read as a command boundary.
-scrubbed=$(printf '%s' "$cmd" | sed -e "s/'[^']*'/ /g" -e 's/"[^"]*"/ /g')
+# 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
+    }
+    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=""
@@ -133,7 +190,10 @@ while IFS= read -r seg; do
 
   # STAGE 4: only a manager-led segment can be an install.
   case "$head_tok" in
-    npm|bun|pnpm|yarn|yarnpkg) ;;
+    npm) verbs="$NPM_INSTALL" ;;
+    bun) verbs="$BUN_INSTALL" ;;
+    pnpm) verbs="$PNPM_INSTALL" ;;
+    yarn|yarnpkg) verbs="$YARN_INSTALL" ;;
     *) continue ;;
   esac
   shift
@@ -142,13 +202,14 @@ while IFS= read -r seg; do
   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=*) prefix_dir="${tok#*=}"; continue ;;
-      --prefix|-C) pending_prefix=1; continue ;;
+      --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
@@ -159,13 +220,19 @@ while IFS= read -r seg; do
     # 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 "^(${INSTALL_VERBS})$"; then verdict="install"; continue; fi
+    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) verdict="install" ;; esac
+    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
 
diff --git a/framework-dev.md b/framework-dev.md
index d329c612c..67765b6c9 100644
--- a/framework-dev.md
+++ b/framework-dev.md
@@ -162,9 +162,9 @@ Measured on npm 11.19.0 and bun 1.3.14:
 
 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`, covering every manager's documented aliases (`bun i` matters most, since Bun writes THROUGH the link) and the REMOVE verbs too, because `npm rm` in a linked worktree deletes from the checkout that owns the tree. Escape hatch `WEBJS_NO_WORKTREE_INSTALL_GATE=1`.
+- **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`, 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. The command is split on `&&`, `||`, `;`, `|`, `(` and `)`, and each segment is judged only by what it STARTS with, after leading env assignments and wrappers like `sudo` are stripped. 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.
+  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`.
diff --git a/test/hooks/block-install-in-linked-worktree.test.mjs b/test/hooks/block-install-in-linked-worktree.test.mjs
index b25549563..97d0d9acf 100644
--- a/test/hooks/block-install-in-linked-worktree.test.mjs
+++ b/test/hooks/block-install-in-linked-worktree.test.mjs
@@ -110,7 +110,10 @@ test('blocks the HYPHENATED npm verbs, which the short aliases do not cover', ()
 test('blocks the REMOVE verbs, which delete from the owning checkout', () => {
   const { root, worktree } = makeLinkedPair();
   try {
-    for (const cmd of ['npm uninstall x', 'npm rm x', 'npm r x', 'bun rm x', 'pnpm rm x', 'yarn remove x', 'pnpm upgrade', 'pnpm dedupe', 'yarn dedupe']) {
+    // `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 }); }
@@ -193,7 +196,6 @@ test('an `=` in a FLAG does not disable the gate (fail-open regression)', () =>
       'npm install --workspace=packages/core',
       'bun install --backend=hardlink',
       'yarn add x --registry=https://r',
-      'pnpm add x --dir=/y',
       'npm i -D esbuild --foreground-scripts=true',
     ]) {
       assert.equal(runHook(cmd, worktree).status, 2, `expected block for \`${cmd}\``);
@@ -317,7 +319,7 @@ test('a flag VALUE never hides the verb, and a safe verb still stops the scan',
   } finally { rmSync(root, { recursive: true, force: true }); }
 });
 
-test('follows every `cd` spelling, including ~, --, and pushd', () => {
+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`]) {
@@ -357,3 +359,91 @@ test('escalates to the git toplevel, so an install from a SUBDIRECTORY blocks',
     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 }); }
+});

From 38024bd8cda85714bd1a3bb96b6d33dc4b0a55a8 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Fri, 21 Aug 2026 17:37:29 +0530
Subject: [PATCH 12/12] test: raise the doctor barrel floor for the two new
 exports

`inspectFrameworkLink` and `checkFrameworkLinks` took the doctor.js barrel
from 9 named exports to 11, and the barrel-surface drift guard pins the
count. CI caught it while the local runner did not, because the local test
runner never selects test/architecture at all.
---
 test/architecture/barrel-surface.test.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/architecture/barrel-surface.test.mjs b/test/architecture/barrel-surface.test.mjs
index 207464ae2..a04331e87 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 },