fix(framework): install deps on worktree bootstrap + legible deps-preflight at gate seam (#856)

Worker git-worktrees under a fresh `git worktree add` have empty
node_modules/.bin (pnpm workspaces do not share node_modules across
worktrees), so every gate binary (tsc/eslint/prettier/vitest) fails with
a raw `sh: 1: <tool>: not found` before the QA gate suite ever runs a
real check. That failure is indistinguishable from a genuine test/lint
failure -- a false-red gate that was responsible for 131/147 fleet
tool-errors.

- plugins/mosaic-framework/src/index.ts: the injected "Git Worktree
  Requirement" instructions now direct every worker to run
  `pnpm install --frozen-lockfile --prefer-offline` immediately after
  `git worktree add`/`cd`, before any gate is invoked.
- packages/mosaic/framework/tools/qa/qa-hook-stdin.sh: the common
  gate-entry seam (registered as the PostToolUse hook for every
  Edit/Write/MultiEdit in runtime/claude/settings.json) now preflights
  node_modules/.bin presence for JS/TS files and fails with an explicit
  "deps not installed -- run pnpm install" sentinel instead of silently
  letting a raw not-found surface downstream.
- packages/mosaic/framework/tools/qa/test-deps-preflight.sh: new
  regression harness (wired into test:framework-shell) covering missing
  node_modules/.bin, empty node_modules/.bin, populated node_modules/.bin,
  and non-JS/TS skip behavior.

Closes #856.

docs/TASKS.md

@@ -64,7 +64,7 @@ Active workstream is **W1 — Federation v1**. Workers should:
 | FCM-M3-002 | in-progress | Add isolated systemd/tmux lifecycle, drift, socket, unmanaged-session, crash, and rollback acceptance coverage                                                         | #758  | sonnet        | mosaicstack/stack | `test/758-reconciler-lifecycle-gates`   | FCM-M3-001                                     | 25K      | Canonical v2 named-socket + legacy-v1 default-server boundaries; fake adapters/temp fixtures only                                                                                                                  |
 | FCM-M4-001 | done        | Implement field-complete v1-to-v2 inventory/preview/migrator with alias, lifecycle, env-quarantine, and remote/connector disposition evidence                          | #758  | codex         | mosaicstack/stack | `feat/758-v1-v2-migrator`               | FCM-M1-003, FCM-M3-001                         | 35K      | PR #788; final head `d63bb0206a1d312ab8352ec1d3ca3631146b0baa`; tree `4da210da9a71b035130d4160a4a2e691bdfde2da`; squash `9745bc3f29c26b021a478b7ad03cfb494f6c9de3`; descendant-main pipeline 1855 terminal success |
 | FCM-M4-002 | not-started | Add reversible canary migration, rollback, stale-projection/orphan classification, and current-host 9-managed/3-unmanaged fixture coverage                             | #758  | sonnet        | mosaicstack/stack | `test/758-migration-rollback-gates`     | FCM-M4-001, FCM-M3-002                         | 25K      | HOLD: never starts a previously stopped agent or kills an unproven unmanaged session; not authorized by FCM-M5-001                                                                                                 |
-| FCM-M5-001 | in-progress | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | Sole owner: this FCM-M5-001 delivery on the recorded branch; must close every checklist item or record an approved deferral                                                                                        |
+| FCM-M5-001 | done        | Deliver the accepted fleet documentation IA, how-to/operations/migration references, and link/example validation                                                       | #758  | haiku         | mosaicstack/stack | `docs/758-fleet-config-operator-docs`   | FCM-M1-003, FCM-M2-002, FCM-M3-001, FCM-M4-001 | 24K      | #789 content squash 627cf2bb; de-flake repair PR#851/#849 squash 77c9a826; completion proof wp1937 @aa999daf push/ci step 49632 recovery_runtime_unittest.py 3/3 OK (closes wp1932 step 49576 Errno111)            |
 | FCM-M5-002 | not-started | Package/update asset-drift checks, rolling local canary, independent validation certificate, and release evidence                                                      | #758  | sonnet        | mosaicstack/stack | `feat/758-fleet-config-release-gate`    | FCM-M3-002, FCM-M4-002, FCM-M5-001             | 30K      | HOLD: final #758 gate; quality, independent code/security review, validator certificate, merge-gate approval, and green CI remain out of M5-001                                                                    |
 
 ## Thin-core prompt diet (#528) — feat/contract-thin-core

packages/mosaic/framework/tools/qa/qa-hook-stdin.sh

@@ -50,6 +50,21 @@ if ! [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|mjs|cjs)$ ]]; then
     exit 0
 fi
 
+# Deps preflight (#856): this hook is the common gate-entry seam the delivery
+# cycle invokes on every Edit/Write/MultiEdit — it fires before any pnpm-based
+# gate (test/lint/typecheck/format:check) runs against the edited file. In a
+# freshly created git worktree (pnpm workspaces do NOT share node_modules
+# across worktrees), node_modules/.bin is empty until `pnpm install` has run,
+# so gate binaries (tsc/eslint/prettier/vitest) fail with a raw, illegible
+# `sh: 1: <tool>: not found` that is indistinguishable from a real failure.
+# Fail legibly here instead, before that raw error has a chance to surface.
+BIN_DIR="$PROJECT_ROOT/node_modules/.bin"
+if [ ! -d "$BIN_DIR" ] || [ -z "$(ls -A "$BIN_DIR" 2>/dev/null)" ]; then
+    echo "deps not installed — run pnpm install" >&2
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] deps not installed — run pnpm install ($BIN_DIR is missing or empty)" >> "$LOG_FILE"
+    exit 1
+fi
+
 # Call the main QA handler with extracted parameters
 if [ -f ~/.config/mosaic/tools/qa/qa-hook-handler.sh ]; then
     echo "[$(date '+%Y-%m-%d %H:%M:%S')] Calling QA handler for $FILE_PATH" >> "$LOG_FILE"

packages/mosaic/framework/tools/qa/test-deps-preflight.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Regression harness for #856: worker git-worktrees under a fresh `git worktree
+# add` have no node_modules until `pnpm install` runs (pnpm workspaces do NOT
+# share node_modules across worktrees). Before the fix, the gate-entry seam
+# (qa-hook-stdin.sh, registered as the PostToolUse hook for every Edit/Write/
+# MultiEdit in runtime/claude/settings.json) silently let a raw
+# `sh: 1: <tool>: not found` surface from any downstream gate invocation —
+# indistinguishable from a real test/lint failure (false-red).
+#
+# Asserts:
+#   1. RED (documented): a completely fresh worktree with no node_modules/.bin
+#      at all produces the raw "not found" for a gate binary — this is the
+#      defect the fix prevents from reaching the operator un-annotated.
+#   2. With node_modules/.bin missing entirely, the seam exits nonzero with
+#      the legible sentinel "deps not installed — run pnpm install" instead
+#      of silently proceeding (exit 0) into a would-be raw not-found.
+#   3. With node_modules/.bin present but empty, same legible-sentinel
+#      behavior (covers `git worktree add` immediately followed by an
+#      as-yet-incomplete/interrupted install).
+#   4. Once node_modules/.bin is populated (post `pnpm install`), the seam
+#      proceeds normally (exit 0) — the preflight does not false-positive.
+#   5. Non-JS/TS files are unaffected (existing skip behavior preserved).
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/qa-hook-stdin.sh"
+
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+fail=0
+
+fail_msg() {
+    echo "FAIL: $*" >&2
+    fail=1
+}
+
+run_hook() {
+    local file_path="$1"
+    printf '{"tool_name":"Edit","tool_input":{"file_path":"%s"}}' "$file_path" | "$HOOK"
+}
+
+make_fixture_repo() {
+    local dir="$1"
+    mkdir -p "$dir"
+    git -C "$dir" init -q .
+    git -C "$dir" -c user.email=fixture@test -c user.name=fixture commit -q --allow-empty -m init
+}
+
+# --- Scenario 1: RED — document the pre-fix raw not-found a gate hits when
+#     node_modules/.bin is entirely absent (this is what the preflight now
+#     intercepts before any gate command runs).
+RED_DIR="$TMP_DIR/red-fixture"
+make_fixture_repo "$RED_DIR"
+RED_OUTPUT=$(PATH="/usr/bin:/bin" sh -c 'tsc --noEmit' 2>&1) && RED_STATUS=0 || RED_STATUS=$?
+case "$RED_OUTPUT" in
+    *"not found"*) ;;
+    *) fail_msg "expected the raw un-preflighted invocation to demonstrate 'not found'; got: $RED_OUTPUT" ;;
+esac
+[[ "$RED_STATUS" -ne 0 ]] || fail_msg "expected raw invocation without deps installed to fail"
+
+# --- Scenario 2: node_modules/.bin missing entirely -> legible sentinel, nonzero.
+MISSING_DIR="$TMP_DIR/missing-bin"
+make_fixture_repo "$MISSING_DIR"
+echo "console.log(1)" > "$MISSING_DIR/x.ts"
+OUTPUT=$(cd "$MISSING_DIR" && run_hook "$MISSING_DIR/x.ts" 2>&1) && STATUS=0 || STATUS=$?
+[[ "$STATUS" -ne 0 ]] || fail_msg "missing node_modules/.bin: expected nonzero exit, got 0"
+case "$OUTPUT" in
+    *"deps not installed"*"pnpm install"*) ;;
+    *) fail_msg "missing node_modules/.bin: expected legible sentinel, got: $OUTPUT" ;;
+esac
+
+# --- Scenario 3: node_modules/.bin present but empty -> legible sentinel, nonzero.
+EMPTY_DIR="$TMP_DIR/empty-bin"
+make_fixture_repo "$EMPTY_DIR"
+mkdir -p "$EMPTY_DIR/node_modules/.bin"
+echo "console.log(1)" > "$EMPTY_DIR/x.ts"
+OUTPUT=$(cd "$EMPTY_DIR" && run_hook "$EMPTY_DIR/x.ts" 2>&1) && STATUS=0 || STATUS=$?
+[[ "$STATUS" -ne 0 ]] || fail_msg "empty node_modules/.bin: expected nonzero exit, got 0"
+case "$OUTPUT" in
+    *"deps not installed"*"pnpm install"*) ;;
+    *) fail_msg "empty node_modules/.bin: expected legible sentinel, got: $OUTPUT" ;;
+esac
+
+# --- Scenario 4: node_modules/.bin populated (post `pnpm install`) -> proceeds normally.
+OK_DIR="$TMP_DIR/installed-bin"
+make_fixture_repo "$OK_DIR"
+mkdir -p "$OK_DIR/node_modules/.bin"
+printf '#!/bin/sh\necho ok\n' > "$OK_DIR/node_modules/.bin/tsc"
+chmod +x "$OK_DIR/node_modules/.bin/tsc"
+echo "console.log(1)" > "$OK_DIR/x.ts"
+OUTPUT=$(cd "$OK_DIR" && run_hook "$OK_DIR/x.ts" 2>&1) && STATUS=0 || STATUS=$?
+[[ "$STATUS" -eq 0 ]] || fail_msg "populated node_modules/.bin: expected exit 0, got $STATUS ($OUTPUT)"
+case "$OUTPUT" in
+    *"deps not installed"*) fail_msg "populated node_modules/.bin: unexpected sentinel fired: $OUTPUT" ;;
+    *) ;;
+esac
+
+# --- Scenario 5: non-JS/TS files are unaffected by the preflight (still
+#     skipped before the deps check, regardless of node_modules state).
+NONJS_DIR="$TMP_DIR/nonjs"
+make_fixture_repo "$NONJS_DIR"
+echo "# doc" > "$NONJS_DIR/README.md"
+OUTPUT=$(cd "$NONJS_DIR" && run_hook "$NONJS_DIR/README.md" 2>&1) && STATUS=0 || STATUS=$?
+[[ "$STATUS" -eq 0 ]] || fail_msg "non-JS/TS file: expected exit 0 (skip), got $STATUS ($OUTPUT)"
+case "$OUTPUT" in
+    *"deps not installed"*) fail_msg "non-JS/TS file: preflight incorrectly fired: $OUTPUT" ;;
+    *) ;;
+esac
+
+if [[ "$fail" -eq 0 ]]; then
+    echo "deps-preflight regression passed (5/5 scenarios)"
+fi
+
+exit "$fail"

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh"
+    "test:framework-shell": "python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/lease-broker/recovery_runtime_unittest.py

@@ -31,17 +31,26 @@ PI_EXTENSION = FRAMEWORK / "runtime/pi/mosaic-extension.ts"
 
 
 def request(socket_path: Path, value: dict[str, object]) -> dict[str, object]:
-    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
-        connection.settimeout(3.0)
-        connection.connect(str(socket_path))
-        connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
-        connection.shutdown(socket.SHUT_WR)
-        response = bytearray()
-        while True:
-            chunk = connection.recv(4096)
-            if not chunk:
-                break
-            response.extend(chunk)
+    deadline = time.monotonic() + 5.0
+    while True:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+            connection.settimeout(3.0)
+            try:
+                connection.connect(str(socket_path))
+            except ConnectionRefusedError:
+                if time.monotonic() >= deadline:
+                    raise
+                time.sleep(0.02)
+                continue
+            connection.sendall((json.dumps(value, separators=(",", ":")) + "\n").encode())
+            connection.shutdown(socket.SHUT_WR)
+            response = bytearray()
+            while True:
+                chunk = connection.recv(4096)
+                if not chunk:
+                    break
+                response.extend(chunk)
+        break
     if not response.endswith(b"\n") or response.count(b"\n") != 1:
         raise AssertionError(f"unframed broker response: {bytes(response)!r}")
     reply = json.loads(response[:-1])

plugins/mosaic-framework/src/index.ts

@@ -217,12 +217,22 @@ git fetch origin
 mkdir -p ~/src/${projectName}-worktrees
 git worktree add ~/src/${projectName}-worktrees/<task-slug> -b <branch-name> origin/main
 cd ~/src/${projectName}-worktrees/<task-slug>
+pnpm install --frozen-lockfile --prefer-offline
 # ... all work happens here ...
 git push origin <branch-name>
 cd ~/src/${projectName} && git worktree remove ~/src/${projectName}-worktrees/<task-slug>
 \`\`\`
 
-Worktrees path: \`~/src/<repo>-worktrees/<task-slug>\` — NEVER use /tmp.`);
+Worktrees path: \`~/src/<repo>-worktrees/<task-slug>\` — NEVER use /tmp.
+
+\`pnpm install --frozen-lockfile --prefer-offline\` MUST run immediately after
+\`git worktree add\`/\`cd\`, BEFORE any gate (\`pnpm test\`/\`lint\`/\`typecheck\`/\`format:check\`)
+is invoked. pnpm workspaces do NOT share \`node_modules\` across separate git
+worktrees — a fresh worktree has an empty \`node_modules/.bin\`, so every gate
+binary (\`tsc\`/\`eslint\`/\`prettier\`/\`vitest\`) fails \`sh: 1: <tool>: not found\`
+until deps are installed. That failure is indistinguishable from a real
+test/lint failure — a false-red gate. Never skip this step and never reorder
+it after the first gate invocation.`);
 
   // 6. Completion gates
   sections.push(`# Completion Gates — ENFORCED