@muggleai/works 5.20.0-staging.142 → 5.20.0-staging.143

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "5.20.0-staging.142",
+  "version": "5.20.0-staging.143",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "5.20.0-staging.142",
+  "version": "5.20.0-staging.143",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/hooks/README.md

@@ -26,9 +26,9 @@ Enforcement is reserved for the handoffs that were being skipped: the E2E accept
 
 A recorder that *clears* an obligation — a walkthrough posted, a failure diagnosed, a test case classified — records only when the call did not visibly fail (`callOutcome.ts`). Recording from the request alone let a rejected `gh pr comment` mark the walkthrough posted, so the gate went quiet on a PR that never received it.
 
-Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json`. The wrapper pipes the event payload (stdin JSON) to the bundled `../scripts/guardrails.mjs <subcommand>`, which holds the decision logic (built from `src/guardrails/`, vitest-covered). Per-session state in `~/.muggle-ai/guardrails/<session_id>.json` tracks what fired. Any *failure* degrades to `{}` (allow) — a gate blocks only by an explicit, tested decision, never by accident.
+Each guardrail is a bash gate script in `../scripts/` holding a `guardrail_wants` pre-filter and the `guardrails.mjs` subcommand it feeds; the bundled `../scripts/guardrails.mjs` holds the decision logic (built from `src/guardrails/`, vitest-covered). The busy events — a shell command before and after it runs, and every turn end — register one `guardrail-dispatch.sh` command listing their gates, which reads the payload once, asks every gate's pre-filter in that one process, and starts Node once (`guardrails.mjs run <gates...>`) for just the gates that could fire, merging their responses. Rarer events call a gate script directly. Per-session state in `~/.muggle-ai/guardrails/<session_id>.json` tracks what fired. Any *failure* degrades to `{}` (allow) — a gate blocks only by an explicit, tested decision, never by accident; `guardrail-lib.sh` is the one place that falls back, and `run` isolates gates from each other.
 
-Each wrapper short-circuits in shell first, so the common case never pays Node cold-start. A gate that has spent its block budget stamps a `<gate>Released` flag, which its wrapper then pre-filters on — without it a released gate keeps cold-starting Node on every remaining turn end to answer `{}`, and the walkthrough gate keeps making provider calls to do it. That pre-filter is a second, looser copy of what `guardrails.mjs` matches, and it is the one place a guardrail can fail *silently*: a payload it drops — a skip marker, a reopen line, a comment edit — reaches no recorder, and the gate keeps demanding an action the user already took. Over-matching is free; under-matching is a dead escape hatch. `src/test/guardrails/hook-prefilter.test.ts` pins every payload each subcommand acts on against the wrapper guarding it, and derives the skip-marker tokens from source so a new marker is covered the moment it exists.
+Pre-filters are bash builtins only (`guardrail-lib.sh`), so an irrelevant event starts no process at all. A gate that has spent its block budget stamps a `<gate>Released` flag, which its wrapper then pre-filters on — without it a released gate keeps cold-starting Node on every remaining turn end to answer `{}`, and the walkthrough gate keeps making provider calls to do it. That pre-filter is a second, looser copy of what `guardrails.mjs` matches, and it is the one place a guardrail can fail *silently*: a payload it drops — a skip marker, a reopen line, a comment edit — reaches no recorder, and the gate keeps demanding an action the user already took. Over-matching is free; under-matching is a dead escape hatch. `src/test/guardrails/hook-prefilter.test.ts` pins every payload each subcommand acts on against the wrapper guarding it, and derives the skip-marker tokens from source so a new marker is covered the moment it exists.
 
 ## Guardrails
 
@@ -70,3 +70,18 @@ The nudge counts only slots **this session owns**, and reports the rest as orpha
 - Finalized watcher slots (`result.md` present) are pruned 30 days after finalize; their `followup.log` is forensic-only. An **open** slot — a PR watched for any length of time — has no `result.md` and is never touched.
 
 Both windows are overridable (`MUGGLE_GUARDRAILS_TTL_DAYS`, `MUGGLE_SLOT_TTL_DAYS`). TTL-gated to once per day via a `~/.cache/muggle/state-gc-checked` marker (the current-session refresh runs every start regardless); silent and best-effort, never blocks session start. Never touches an open slot or the current session's own state.
+
+## Footprint caps
+
+Every hook here fires on every tool call, prompt or turn end in every open session, so its cost is paid thousands of times a day on the user's machine; on Windows each process start costs 50 ms healthy and seconds under load. The budget is lightweight by construction: one hook command per busy event, and nothing started beyond it when the event is irrelevant. `src/test/guardrails/footprint/` holds CI to it:
+
+| Cap | Limit |
+| :-- | :-- |
+| Hook commands per busy slot (PreToolUse/PostToolUse on `Bash` and `Read`, Stop, UserPromptSubmit) | 1 |
+| Programs started beyond each hook's own launch on an irrelevant event | 0 (Stop: 1, a transcript `tail` until the capability-claim gate has nudged; bash cannot seek) |
+| `node`, `gh`, `python` on that path | 0 |
+| Median wall time of one irrelevant firing, Linux/macOS | 100 ms |
+| Hook commands in the whole manifest | 15 |
+| Hook timeout | declared on every hook; 30 s, SessionStart 120 s |
+
+Counts are exec counts, so they are identical on every runner. Every count is exact: CI fails when a change exceeds a limit, and also when it beats one until `footprint/constants.ts` is lowered to match, so a gain cannot be given back later.

package/dist/plugin/hooks/hooks.json

@@ -31,19 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-report-format.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-resolve-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-heading.sh\"",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-dispatch.sh\" guardrail-report-format.sh guardrail-resolve-gate.sh guardrail-walkthrough-heading.sh",
             "async": false,
             "timeout": 10
           }
@@ -67,33 +55,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-opened.sh\"",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-dispatch.sh\" guardrail-pr-opened.sh guardrail-record-tests.sh guardrail-pr-terminal.sh guardrail-record-stage-signals.sh guardrail-record-comment-replies.sh",
             "async": false,
             "timeout": 25
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-terminal.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-signals.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-comment-replies.sh\"",
-            "async": false,
-            "timeout": 10
           }
         ]
       },
@@ -180,57 +144,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-dispatch.sh\" guardrail-e2e-gate.sh guardrail-terminal-gate.sh guardrail-watch-gate.sh guardrail-build-followthrough-gate.sh guardrail-walkthrough-gate.sh guardrail-comment-reply-gate.sh guardrail-stage-gate.sh guardrail-debug-path-gate.sh guardrail-capability-claim.sh",
             "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-terminal-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-watch-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-followthrough-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-gate.sh\"",
-            "async": false,
-            "timeout": 15
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-comment-reply-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-stage-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-debug-path-gate.sh\"",
-            "async": false,
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-capability-claim.sh\"",
-            "async": false,
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }

package/dist/plugin/scripts/guardrail-build-followthrough-gate.sh

@@ -15,30 +15,20 @@ set -uo pipefail
 # overwhelming majority of turns no build intent was detected, so the state file
 # is absent or the flag is unset and we return {} in-shell, never paying Node
 # cold-start. Degrades to {}.
-payload="$(cat)"
 
-raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
-[ -n "$raw_sid" ] || raw_sid="unknown"
-sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
-# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
-# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
-home="${HOME:-}"
-if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
-  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
-fi
+GUARDRAIL_SUBCOMMAND="build-followthrough-gate"
 
-# A non-empty prsHandled array spans lines, so the empty match reliably says no
-# PR was opened. Skip Node unless a build request was routed and nothing shipped.
-state_file="$home/.muggle-ai/guardrails/$sid.json"
-if [ ! -f "$state_file" ] \
-  || ! grep -q '"buildIntentRouted": true' "$state_file" \
-  || ! grep -q '"prsHandled": \[\]' "$state_file" \
-  || grep -q '"buildSkipped": true' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  guardrail_load_state \
+    && guardrail_state_has '"buildIntentRouted": true' \
+    && guardrail_state_has '"prsHandled": []' \
+    && ! guardrail_state_has '"buildSkipped": true'
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" build-followthrough-gate 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-build-router.sh

@@ -12,12 +12,17 @@ set -uo pipefail
 # then applies the real detectBuildIntent logic (question/slash exclusions,
 # once-per-session dedupe). Over-matching here only costs an occasional needless
 # spawn; it can never emit a spurious offer. Degrades to {} so it never blocks.
-payload="$(cat)"
 
-if ! grep -Eiq '(implement|build|add|create|write|fix|refactor|wire up|hook up|make|change the|conflict|merged|passing|green)' <<<"$payload"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
+
+GUARDRAIL_SUBCOMMAND="build-router"
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" build-router 2>/dev/null || printf '{}'
+guardrail_wants() {
+  guardrail_payload_matches '(implement|build|add|create|write|fix|refactor|wire up|hook up|make|change the|conflict|merged|passing|green)'
+}
+
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-capability-claim.sh

@@ -15,24 +15,34 @@ set -uo pipefail
 # from being "corrected". Over-matching here costs a needless spawn; it can
 # never emit a spurious nudge. Degrades to {} so it never blocks on its own
 # failure.
-payload="$(cat)"
 
-transcript="$(printf '%s' "$payload" \
-  | grep -oE '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
-  | head -1 \
-  | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/' \
-  | sed 's/\\\\/\//g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-if [ -z "$transcript" ] || [ ! -f "$transcript" ]; then
-  printf '{}'
-  exit 0
-fi
+GUARDRAIL_SUBCOMMAND="capability-claim-gate"
 
-if ! tail -c 20000 "$transcript" \
-  | grep -Eiq 'can.t|cannot|unable to|no way to|untestable|unverifiable|impossible|infeasible'; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  if guardrail_load_state && guardrail_state_has '"capabilityClaimNudged": true'; then
+    return 1
+  fi
+  local transcript_pattern='"transcript_path"[[:space:]]*:[[:space:]]*"([^"]*)"'
+  [[ $GUARDRAIL_PAYLOAD =~ $transcript_pattern ]] || return 1
+  local json_escaped_separator='\\'
+  local transcript="${BASH_REMATCH[1]//"$json_escaped_separator"//}"
+  [[ -f $transcript ]] || return 1
+  # The one spawn left on a turn end: bash cannot seek, and reading a multi-MB transcript
+  # in-shell costs more than a tail. Gone for the session once the gate has nudged.
+  local transcript_tail
+  transcript_tail="$(tail -c 20000 "$transcript" 2>/dev/null)"
+  local claim_pattern='can.t|cannot|unable to|no way to|untestable|unverifiable|impossible|infeasible'
+  local matched=1
+  shopt -s nocasematch
+  [[ $transcript_tail =~ $claim_pattern ]] && matched=0
+  shopt -u nocasematch
+  return "$matched"
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" capability-claim-gate 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-classify-gate.sh

@@ -12,12 +12,17 @@ set -uo pipefail
 # unrelated payload never pays Node cold-start. It stays cheap by construction:
 # an execution call happens minutes apart and burns a real browser, so the spawn
 # is noise against what it protects. Degrades to {}.
-payload="$(cat)"
 
-if ! grep -Eiq 'muggle-local-(execute-test-generation|execute-replay)' <<<"$payload"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
+
+GUARDRAIL_SUBCOMMAND="classify-gate"
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" classify-gate 2>/dev/null || printf '{}'
+guardrail_wants() {
+  guardrail_payload_matches 'muggle-local-(execute-test-generation|execute-replay)'
+}
+
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-comment-reply-gate.sh

@@ -10,33 +10,22 @@ set -uo pipefail
 # than the session state file, so the pre-filter keys on a ledger existing at
 # all: with no ledger anywhere there is nothing this gate could owe, and we
 # return {} in-shell without paying Node cold-start. Degrades to {}.
-payload="$(cat)"
 
-raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
-[ -n "$raw_sid" ] || raw_sid="unknown"
-sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
-# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
-# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
-home="${HOME:-}"
-if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
-  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
-fi
+GUARDRAIL_SUBCOMMAND="comment-reply-gate"
 
-state_file="$home/.muggle-ai/guardrails/$sid.json"
-if ! ls "$home"/.muggle-ai/muggle-do/sessions/*/comment-ledger.json >/dev/null 2>&1; then
-  printf '{}'
-  exit 0
-fi
-if [ -f "$state_file" ] && grep -q '"commentReplySkipped": true' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
-if [ -f "$state_file" ] && grep -q '"commentReplyReleased": true' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  guardrail_resolve_home
+  local ledgers=("$GUARDRAIL_HOME"/.muggle-ai/muggle-do/sessions/*/comment-ledger.json)
+  [[ -e ${ledgers[0]} ]] || return 1
+  if guardrail_load_state; then
+    ! guardrail_state_has '"commentReplySkipped": true' && ! guardrail_state_has '"commentReplyReleased": true'
+  fi
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" comment-reply-gate 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-debug-path-gate.sh

@@ -12,31 +12,21 @@ set -uo pipefail
 # only when a failed run is recorded and unresolved. On the overwhelming majority
 # of turns nothing failed, so the state file is absent or failedRuns is empty and
 # we return {} in-shell. The evidence join runs in guardrails.mjs. Degrades to {}.
-payload="$(cat)"
 
-raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
-[ -n "$raw_sid" ] || raw_sid="unknown"
-sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
-# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
-# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
-home="${HOME:-}"
-if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
-  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
-fi
+GUARDRAIL_SUBCOMMAND="debug-path-gate"
 
-# Empty array serializes as `"failedRuns": []` (one line); a non-empty array
-# spans lines, so the empty match reliably tells them apart.
-state_file="$home/.muggle-ai/guardrails/$sid.json"
-if [ ! -f "$state_file" ] \
-  || ! grep -q '"failedRuns"' "$state_file" \
-  || grep -q '"failedRuns": \[\]' "$state_file" \
-  || grep -q '"debugReleased": true' "$state_file" \
-  || grep -q '"debugSkipped": true' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  guardrail_load_state \
+    && guardrail_state_has '"failedRuns"' \
+    && ! guardrail_state_has '"failedRuns": []' \
+    && ! guardrail_state_has '"debugReleased": true' \
+    && ! guardrail_state_has '"debugSkipped": true'
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" debug-path-gate 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-dispatch.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# One hook command per event instead of one per gate. hooks.json calls this with the gate
+# scripts that event feeds, in order:
+#
+#   guardrail-dispatch.sh guardrail-e2e-gate.sh guardrail-watch-gate.sh ...
+#
+# It reads the payload once, sources each gate (defining its guardrail_wants pre-filter and
+# GUARDRAIL_SUBCOMMAND without running it), and asks every pre-filter in this one process.
+# Irrelevant events — nearly all of them — end here with {} and no process started. When any
+# gate could fire, Node runs once for all of them (`guardrails.mjs run <gates...>`), merging
+# their outputs the way the harness merged separate hooks.
+
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
+
+guardrail_read_payload
+
+firing_subcommands=()
+for gate_script in "$@"; do
+  GUARDRAIL_SUBCOMMAND=""
+  . "$guardrail_script_dir/$gate_script" || continue
+  if [[ -n $GUARDRAIL_SUBCOMMAND ]] && guardrail_wants; then
+    firing_subcommands+=("$GUARDRAIL_SUBCOMMAND")
+  fi
+done
+
+if [[ ${#firing_subcommands[@]} -eq 0 ]]; then
+  printf '{}'
+  exit 0
+fi
+guardrail_run_node run "${firing_subcommands[@]}"

package/dist/plugin/scripts/guardrail-e2e-gate.sh

@@ -14,28 +14,20 @@ set -uo pipefail
 # overwhelming majority of turns (no test run, no PR) the state file is absent,
 # or unitTestsGreen is unset while prsHandled is empty, so we return {} in-shell
 # and never pay Node cold-start. Degrades to {}.
-payload="$(cat)"
 
-raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
-[ -n "$raw_sid" ] || raw_sid="unknown"
-sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
-# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
-# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
-home="${HOME:-}"
-if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
-  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
-fi
+GUARDRAIL_SUBCOMMAND="e2e-gate"
 
-state_file="$home/.muggle-ai/guardrails/$sid.json"
-if [ ! -f "$state_file" ] \
-  || { ! grep -q '"unitTestsGreen": true' "$state_file" && grep -q '"prsHandled": \[\]' "$state_file"; } \
-  || grep -q '"e2eReleased": true' "$state_file" \
-  || grep -q '"e2eRun": true' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  guardrail_load_state \
+    && { guardrail_state_has '"unitTestsGreen": true' || ! guardrail_state_has '"prsHandled": []'; } \
+    && ! guardrail_state_has '"e2eReleased": true' \
+    && ! guardrail_state_has '"e2eRun": true'
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" e2e-gate 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi

package/dist/plugin/scripts/guardrail-lib.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Spawn-free plumbing shared by every guardrail hook, sourced by the gate scripts and by
+# guardrail-dispatch.sh. Hooks fire on every tool call, prompt and turn end in every open
+# session, and on Windows each process start costs 50ms healthy and seconds under load, so
+# everything on the "this event is irrelevant" path is a bash builtin: payload and state are
+# read with `read`, matched with [[ =~ ]] and glob tests, and the session id is sanitised with
+# parameter expansion. Node starts only once a gate's pre-filter says it could fire.
+# src/test/guardrails/footprint caps this in CI.
+
+[[ -n ${GUARDRAIL_LIB_LOADED:-} ]] && return 0
+GUARDRAIL_LIB_LOADED=1
+
+GUARDRAIL_PAYLOAD=""
+GUARDRAIL_STATE=""
+GUARDRAIL_STATE_LOADED=""
+GUARDRAIL_HAS_STATE=""
+
+guardrail_read_payload() {
+  IFS= read -r -d '' GUARDRAIL_PAYLOAD || true
+}
+
+# Case-insensitive ERE over the whole payload. Unanchored, so it matches everything the
+# per-line `grep -Eiq` it replaced did; an over-match only costs a Node start.
+guardrail_payload_matches() {
+  local pattern="$1"
+  local matched=1
+  shopt -s nocasematch
+  [[ $GUARDRAIL_PAYLOAD =~ $pattern ]] && matched=0
+  shopt -u nocasematch
+  return "$matched"
+}
+
+# The home Node's os.homedir() resolves. HOME is right on macOS/Linux and most Git Bash
+# setups; when it doesn't hold the state dir, USERPROFILE (C:\Users\x) is converted to its
+# Git Bash form (/c/Users/x) in-shell rather than through cygpath.
+guardrail_resolve_home() {
+  GUARDRAIL_HOME="${HOME:-}"
+  local profile="${USERPROFILE:-}"
+  if [[ ! -d $GUARDRAIL_HOME/.muggle-ai && $profile == [A-Za-z]:* ]]; then
+    local drive="${profile:0:1}"
+    local rest="${profile:2}"
+    # Lower-cased by lookup, not ${drive,,}: macOS ships bash 3.2.
+    local upper_letters="ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    local lower_letters="abcdefghijklmnopqrstuvwxyz"
+    local letters_before="${upper_letters%%"$drive"*}"
+    if [[ $letters_before != "$upper_letters" ]]; then
+      drive="${lower_letters:${#letters_before}:1}"
+    fi
+    GUARDRAIL_HOME="/${drive}${rest//\\//}"
+  fi
+}
+
+# Loads this session's guardrail state once per process; returns 1 when the session has none.
+guardrail_load_state() {
+  if [[ -z $GUARDRAIL_STATE_LOADED ]]; then
+    GUARDRAIL_STATE_LOADED=1
+    local session_id_pattern='"session_id"[[:space:]]*:[[:space:]]*"([^"]*)"'
+    local raw_session_id="unknown"
+    if [[ $GUARDRAIL_PAYLOAD =~ $session_id_pattern ]] && [[ -n ${BASH_REMATCH[1]} ]]; then
+      raw_session_id="${BASH_REMATCH[1]}"
+    fi
+    guardrail_resolve_home
+    local state_file="$GUARDRAIL_HOME/.muggle-ai/guardrails/${raw_session_id//[^A-Za-z0-9_-]/_}.json"
+    if [[ -f $state_file ]]; then
+      GUARDRAIL_HAS_STATE=1
+      IFS= read -r -d '' GUARDRAIL_STATE <"$state_file" || true
+    fi
+  fi
+  [[ -n $GUARDRAIL_HAS_STATE ]]
+}
+
+# Fixed-string test against the loaded state (which sessionState writes pretty-printed).
+guardrail_state_has() {
+  [[ $GUARDRAIL_STATE == *"$1"* ]]
+}
+
+# Runs guardrails.mjs on the payload. Never blocks a turn: any failure degrades to {}.
+guardrail_run_node() {
+  local root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+  printf '%s' "$GUARDRAIL_PAYLOAD" | node "${root}/scripts/guardrails.mjs" "$@" 2>/dev/null || printf '{}'
+}
+
+# Entry for a gate script executed directly: its guardrail_wants decides whether Node runs.
+guardrail_run_standalone() {
+  guardrail_read_payload
+  if guardrail_wants; then
+    guardrail_run_node "$1"
+  else
+    printf '{}'
+  fi
+}

package/dist/plugin/scripts/guardrail-offer-ran.sh

@@ -9,27 +9,19 @@ set -uo pipefail
 # Pre-filter: only spawn Node when the per-session state actually has a
 # pending terminal PR, so the ordinary AskUserQuestion (no PR merged this
 # session) never pays Node cold-start. Degrades to {}.
-payload="$(cat)"
 
-raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
-[ -n "$raw_sid" ] || raw_sid="unknown"
-sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+guardrail_script_dir="${BASH_SOURCE[0]%/*}"
+[[ $guardrail_script_dir == "${BASH_SOURCE[0]}" ]] && guardrail_script_dir=.
+. "$guardrail_script_dir/guardrail-lib.sh"
 
-# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
-# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
-# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
-home="${HOME:-}"
-if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
-  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
-fi
+GUARDRAIL_SUBCOMMAND="offer-ran"
 
-state_file="$home/.muggle-ai/guardrails/$sid.json"
-if [ ! -f "$state_file" ] \
-  || ! grep -q '"terminalPending"' "$state_file" \
-  || grep -q '"terminalPending": \[\]' "$state_file"; then
-  printf '{}'
-  exit 0
-fi
+guardrail_wants() {
+  guardrail_load_state \
+    && guardrail_state_has '"terminalPending"' \
+    && ! guardrail_state_has '"terminalPending": []'
+}
 
-root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" offer-ran 2>/dev/null || printf '{}'
+if [[ ${BASH_SOURCE[0]} == "$0" ]]; then
+  guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
+fi