@muggleai/works 5.6.0 → 5.7.0

package/dist/plugin/hooks/README.md

@@ -20,7 +20,7 @@ A guardrail emits one of two strengths:
 - **Advise** — `additionalContext` (PostToolUse/UserPromptSubmit) or a plain Stop message. A soft nudge the model can ignore.
 - **Enforce** — a `Stop` `decision: "block"` that refuses to end the turn, or a `PreToolUse` `permissionDecision: "deny"` that refuses a tool call. The model cannot proceed until the condition is met.
 
-Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run and posting a deterministically-rendered report. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise.
+Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run, posting a deterministically-rendered report, and the post-merge handoff. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise; the post-merge gate hard-releases after `MAX_PR_TERMINAL_BLOCKS` (3) blocks, and only the AskUserQuestion next-options offer clears it — nothing else resets its counter.
 
 ## Mechanism
 
@@ -32,8 +32,11 @@ Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json
 | :--------- | :------ | :------- | :-------- | :--------- | :----- |
 | `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
 | `PostToolUse` (Bash + muggle execute/replay MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened, or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + Monitor) | `guardrail-pr-terminal.sh` | advise | a PR just went terminal — a `gh pr merge`/`gh pr close` success line or the watch monitor's `TERMINAL pr=N` exit line (never bare `"state":"MERGED"` metadata) | — | record `terminalPending`, direct the post-merge handoff: finalize the watcher slot, tear down per `autoCleanup`, offer next options via AskUserQuestion |
+| `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
 | `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
 | `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks) |
+| `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the AskUserQuestion next-options offer hasn't run since | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
 | `UserPromptSubmit` | `guardrail-build-router.sh` | advise | a build/implement/fix request (first one this session) | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers) |
 
 ## Session-start reconcile nudge

package/dist/plugin/hooks/hooks.json

@@ -47,6 +47,12 @@
             "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
           }
         ]
       },
@@ -60,6 +66,28 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Monitor",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-terminal.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-offer-ran.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
       }
     ],
     "Stop": [
@@ -70,6 +98,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-terminal-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Next-options-offer observer (PostToolUse/AskUserQuestion). An AskUserQuestion
+# call while a terminal PR is pending IS the post-merge handoff's exit: it
+# clears terminalPending so the Stop gate (guardrail-terminal-gate.sh)
+# releases. Emits no directive.
+#
+# 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')"
+
+# 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
+
+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
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" offer-ran 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrail-pr-terminal.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal guardrail (PostToolUse/Bash + Monitor). When a PR just went
+# terminal — a `gh pr merge`/`gh pr close` success line or the pr-followup
+# watch monitor's `TERMINAL pr=N` exit line — arm the post-merge handoff:
+# record the PR as pending, nudge the model to finalize/tear down and offer
+# next options, and hold the Stop gate (guardrail-terminal-gate.sh) until the
+# AskUserQuestion offer runs. Decision logic lives in the bundled guardrails.mjs.
+#
+# Fires after every Bash call, so a keyword pre-filter for the terminal output
+# shapes keeps Node off the hot path. Degrades to {} so it never blocks.
+payload="$(cat)"
+
+if ! grep -Eiq 'merged pull request|closed pull request|TERMINAL pr=' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" pr-terminal 2>/dev/null || printf '{}'

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal → post-merge handoff gate (Stop). When a PR went terminal this
+# session (merged/closed) and the next-options offer hasn't run, block the
+# turn end until the handoff — finalize, teardown, AskUserQuestion offer —
+# happens. Releases unconditionally after 3 blocks.
+#
+# This must stay synchronous (only a sync Stop hook can block the turn end),
+# and it fires on EVERY turn end. There is no command payload to key off, so
+# the pre-filter reads the same per-session state file guardrails.mjs uses and
+# only spawns Node when a terminal PR is actually pending. On the overwhelming
+# majority of turns no PR went terminal, so the state file is absent or
+# terminalPending is empty and we return {} in-shell. 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')"
+
+# 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
+
+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
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" terminal-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -40,6 +40,61 @@ ${input2.tool_response?.output ?? ""}`;
   return m ? m[0] : null;
 }
 
+// src/guardrails/constants.ts
+var GH_PR_MERGED_LINE = /\b(?:Merged|Squashed and merged|Rebased and merged) pull request [\w./-]*#(\d+)/;
+var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
+var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
+var MAX_PR_TERMINAL_BLOCKS = 3;
+
+// src/guardrails/prTerminal.ts
+function detectPrTerminal(input2) {
+  if (input2.tool_name !== "Bash" && input2.tool_name !== "Monitor") return null;
+  const response = input2.tool_response;
+  const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
+  const mergedMatch = haystack.match(GH_PR_MERGED_LINE);
+  if (mergedMatch) {
+    return { prNumber: Number(mergedMatch[1]), verdict: "merged" /* Merged */ };
+  }
+  const closedMatch = haystack.match(GH_PR_CLOSED_LINE);
+  if (closedMatch) {
+    return { prNumber: Number(closedMatch[1]), verdict: "closed" /* Closed */ };
+  }
+  const monitorMatch = haystack.match(PR_MONITOR_TERMINAL_LINE);
+  if (monitorMatch) {
+    return {
+      prNumber: Number(monitorMatch[1]),
+      verdict: monitorMatch[2] === "MERGED" ? "merged" /* Merged */ : "closed" /* Closed */
+    };
+  }
+  return null;
+}
+function applyPrTerminalDetected(state, prNumber) {
+  const pending = state.terminalPending ?? [];
+  const handled = state.terminalHandled ?? [];
+  if (pending.includes(prNumber) || handled.includes(prNumber)) return state;
+  return { ...state, terminalPending: [...pending, prNumber] };
+}
+function applyNextOptionsOffered(state) {
+  const pending = state.terminalPending ?? [];
+  if (pending.length === 0) return state;
+  return {
+    ...state,
+    terminalPending: [],
+    terminalHandled: [...state.terminalHandled ?? [], ...pending],
+    terminalBlockCount: 0
+  };
+}
+function prTerminalGateDecision(state, maxBlocks = MAX_PR_TERMINAL_BLOCKS) {
+  const blockCount = state.terminalBlockCount ?? 0;
+  if ((state.terminalPending ?? []).length === 0) {
+    return { action: "none" /* None */, blockCount };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
+
 // src/guardrails/testsGreen.ts
 var TEST_CMD = /\b(pnpm|npm|yarn)\s+(run\s+)?test\b|\b(jest|vitest|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/;
 var FAIL = /\b\d+\s+failed\b|\bFAIL\b|✗/;
@@ -197,6 +252,33 @@ function prOpened() {
 Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its incoming reviews. If autoWatchPR=always, start it now by invoking /muggle:muggle-pr-followup with the PR URL; if =ask, offer it to the user; if =never, do nothing.`;
   return envelope("PostToolUse", ctx, host);
 }
+function prTerminal() {
+  const terminalEvent = detectPrTerminal(input);
+  if (!terminalEvent) return "{}";
+  const state = readState(sessionId);
+  const next = applyPrTerminalDetected(state, terminalEvent.prNumber);
+  if (next === state) return "{}";
+  writeState(next);
+  const ctx = `PR #${terminalEvent.prNumber} went terminal (${terminalEvent.verdict}). Run the post-merge handoff now: finalize the watcher slot, tear down per autoCleanup, then OFFER NEXT OPTIONS to the user (AskUserQuestion) \u2014 release, queued work, deferred items. The stop gate holds until the offer runs.`;
+  return envelope("PostToolUse", ctx, host);
+}
+function offerRan() {
+  if (input.tool_name !== "AskUserQuestion") return "{}";
+  const state = readState(sessionId);
+  const next = applyNextOptionsOffered(state);
+  if (next !== state) writeState(next);
+  return "{}";
+}
+function terminalGate() {
+  const state = readState(sessionId);
+  const decision = prTerminalGateDecision(state);
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.terminalBlockCount = decision.blockCount;
+  writeState(state);
+  const pendingPrList = (state.terminalPending ?? []).map((prNumber) => `#${prNumber}`).join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. PR ${pendingPrList} went terminal (merged/closed) but the post-merge handoff has not run. Finalize the watcher slot, tear down per autoCleanup, then offer next options to the user via AskUserQuestion \u2014 release, queued work, deferred items. Only the AskUserQuestion offer clears this gate.` : `Post-merge handoff still owed for PR ${pendingPrList} (reminder ${decision.blockCount}/${MAX_PR_TERMINAL_BLOCKS}): finalize + tear down, then run the AskUserQuestion next-options offer.`;
+  return blockStop(reason, host);
+}
 function recordTests() {
   const cmd = input.tool_input?.command ?? "";
   const state = readState(sessionId);
@@ -233,8 +315,11 @@ function buildRouter() {
 }
 var handlers = {
   "pr-opened": prOpened,
+  "pr-terminal": prTerminal,
+  "offer-ran": offerRan,
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
+  "terminal-gate": terminalGate,
   "report-gate": reportGate,
   "build-router": buildRouter
 };

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.6.0",
-  "buildId": "run-65-1",
-  "commitSha": "5d15cf7c334a1714257f10f801ed41b9ec9e796b",
-  "buildTime": "2026-07-22T23:54:34Z",
+  "buildId": "run-66-1",
+  "commitSha": "9be0ff6106411ab4ef213a48ffc23f600cbca7c8",
+  "buildTime": "2026-07-23T07:41:54Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",

package/plugin/hooks/README.md

@@ -20,7 +20,7 @@ A guardrail emits one of two strengths:
 - **Advise** — `additionalContext` (PostToolUse/UserPromptSubmit) or a plain Stop message. A soft nudge the model can ignore.
 - **Enforce** — a `Stop` `decision: "block"` that refuses to end the turn, or a `PreToolUse` `permissionDecision: "deny"` that refuses a tool call. The model cannot proceed until the condition is met.
 
-Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run and posting a deterministically-rendered report. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise.
+Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run, posting a deterministically-rendered report, and the post-merge handoff. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise; the post-merge gate hard-releases after `MAX_PR_TERMINAL_BLOCKS` (3) blocks, and only the AskUserQuestion next-options offer clears it — nothing else resets its counter.
 
 ## Mechanism
 
@@ -32,8 +32,11 @@ Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json
 | :--------- | :------ | :------- | :-------- | :--------- | :----- |
 | `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
 | `PostToolUse` (Bash + muggle execute/replay MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened, or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + Monitor) | `guardrail-pr-terminal.sh` | advise | a PR just went terminal — a `gh pr merge`/`gh pr close` success line or the watch monitor's `TERMINAL pr=N` exit line (never bare `"state":"MERGED"` metadata) | — | record `terminalPending`, direct the post-merge handoff: finalize the watcher slot, tear down per `autoCleanup`, offer next options via AskUserQuestion |
+| `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
 | `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
 | `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks) |
+| `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the AskUserQuestion next-options offer hasn't run since | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
 | `UserPromptSubmit` | `guardrail-build-router.sh` | advise | a build/implement/fix request (first one this session) | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers) |
 
 ## Session-start reconcile nudge

package/plugin/hooks/hooks.json

@@ -47,6 +47,12 @@
             "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
           }
         ]
       },
@@ -60,6 +66,28 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Monitor",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-terminal.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-offer-ran.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
       }
     ],
     "Stop": [
@@ -70,6 +98,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-terminal-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Next-options-offer observer (PostToolUse/AskUserQuestion). An AskUserQuestion
+# call while a terminal PR is pending IS the post-merge handoff's exit: it
+# clears terminalPending so the Stop gate (guardrail-terminal-gate.sh)
+# releases. Emits no directive.
+#
+# 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')"
+
+# 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
+
+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
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" offer-ran 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-pr-terminal.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal guardrail (PostToolUse/Bash + Monitor). When a PR just went
+# terminal — a `gh pr merge`/`gh pr close` success line or the pr-followup
+# watch monitor's `TERMINAL pr=N` exit line — arm the post-merge handoff:
+# record the PR as pending, nudge the model to finalize/tear down and offer
+# next options, and hold the Stop gate (guardrail-terminal-gate.sh) until the
+# AskUserQuestion offer runs. Decision logic lives in the bundled guardrails.mjs.
+#
+# Fires after every Bash call, so a keyword pre-filter for the terminal output
+# shapes keeps Node off the hot path. Degrades to {} so it never blocks.
+payload="$(cat)"
+
+if ! grep -Eiq 'merged pull request|closed pull request|TERMINAL pr=' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" pr-terminal 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-terminal-gate.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal → post-merge handoff gate (Stop). When a PR went terminal this
+# session (merged/closed) and the next-options offer hasn't run, block the
+# turn end until the handoff — finalize, teardown, AskUserQuestion offer —
+# happens. Releases unconditionally after 3 blocks.
+#
+# This must stay synchronous (only a sync Stop hook can block the turn end),
+# and it fires on EVERY turn end. There is no command payload to key off, so
+# the pre-filter reads the same per-session state file guardrails.mjs uses and
+# only spawns Node when a terminal PR is actually pending. On the overwhelming
+# majority of turns no PR went terminal, so the state file is absent or
+# terminalPending is empty and we return {} in-shell. 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')"
+
+# 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
+
+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
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" terminal-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrails.mjs

@@ -40,6 +40,61 @@ ${input2.tool_response?.output ?? ""}`;
   return m ? m[0] : null;
 }
 
+// src/guardrails/constants.ts
+var GH_PR_MERGED_LINE = /\b(?:Merged|Squashed and merged|Rebased and merged) pull request [\w./-]*#(\d+)/;
+var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
+var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
+var MAX_PR_TERMINAL_BLOCKS = 3;
+
+// src/guardrails/prTerminal.ts
+function detectPrTerminal(input2) {
+  if (input2.tool_name !== "Bash" && input2.tool_name !== "Monitor") return null;
+  const response = input2.tool_response;
+  const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
+  const mergedMatch = haystack.match(GH_PR_MERGED_LINE);
+  if (mergedMatch) {
+    return { prNumber: Number(mergedMatch[1]), verdict: "merged" /* Merged */ };
+  }
+  const closedMatch = haystack.match(GH_PR_CLOSED_LINE);
+  if (closedMatch) {
+    return { prNumber: Number(closedMatch[1]), verdict: "closed" /* Closed */ };
+  }
+  const monitorMatch = haystack.match(PR_MONITOR_TERMINAL_LINE);
+  if (monitorMatch) {
+    return {
+      prNumber: Number(monitorMatch[1]),
+      verdict: monitorMatch[2] === "MERGED" ? "merged" /* Merged */ : "closed" /* Closed */
+    };
+  }
+  return null;
+}
+function applyPrTerminalDetected(state, prNumber) {
+  const pending = state.terminalPending ?? [];
+  const handled = state.terminalHandled ?? [];
+  if (pending.includes(prNumber) || handled.includes(prNumber)) return state;
+  return { ...state, terminalPending: [...pending, prNumber] };
+}
+function applyNextOptionsOffered(state) {
+  const pending = state.terminalPending ?? [];
+  if (pending.length === 0) return state;
+  return {
+    ...state,
+    terminalPending: [],
+    terminalHandled: [...state.terminalHandled ?? [], ...pending],
+    terminalBlockCount: 0
+  };
+}
+function prTerminalGateDecision(state, maxBlocks = MAX_PR_TERMINAL_BLOCKS) {
+  const blockCount = state.terminalBlockCount ?? 0;
+  if ((state.terminalPending ?? []).length === 0) {
+    return { action: "none" /* None */, blockCount };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
+
 // src/guardrails/testsGreen.ts
 var TEST_CMD = /\b(pnpm|npm|yarn)\s+(run\s+)?test\b|\b(jest|vitest|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/;
 var FAIL = /\b\d+\s+failed\b|\bFAIL\b|✗/;
@@ -197,6 +252,33 @@ function prOpened() {
 Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its incoming reviews. If autoWatchPR=always, start it now by invoking /muggle:muggle-pr-followup with the PR URL; if =ask, offer it to the user; if =never, do nothing.`;
   return envelope("PostToolUse", ctx, host);
 }
+function prTerminal() {
+  const terminalEvent = detectPrTerminal(input);
+  if (!terminalEvent) return "{}";
+  const state = readState(sessionId);
+  const next = applyPrTerminalDetected(state, terminalEvent.prNumber);
+  if (next === state) return "{}";
+  writeState(next);
+  const ctx = `PR #${terminalEvent.prNumber} went terminal (${terminalEvent.verdict}). Run the post-merge handoff now: finalize the watcher slot, tear down per autoCleanup, then OFFER NEXT OPTIONS to the user (AskUserQuestion) \u2014 release, queued work, deferred items. The stop gate holds until the offer runs.`;
+  return envelope("PostToolUse", ctx, host);
+}
+function offerRan() {
+  if (input.tool_name !== "AskUserQuestion") return "{}";
+  const state = readState(sessionId);
+  const next = applyNextOptionsOffered(state);
+  if (next !== state) writeState(next);
+  return "{}";
+}
+function terminalGate() {
+  const state = readState(sessionId);
+  const decision = prTerminalGateDecision(state);
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.terminalBlockCount = decision.blockCount;
+  writeState(state);
+  const pendingPrList = (state.terminalPending ?? []).map((prNumber) => `#${prNumber}`).join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. PR ${pendingPrList} went terminal (merged/closed) but the post-merge handoff has not run. Finalize the watcher slot, tear down per autoCleanup, then offer next options to the user via AskUserQuestion \u2014 release, queued work, deferred items. Only the AskUserQuestion offer clears this gate.` : `Post-merge handoff still owed for PR ${pendingPrList} (reminder ${decision.blockCount}/${MAX_PR_TERMINAL_BLOCKS}): finalize + tear down, then run the AskUserQuestion next-options offer.`;
+  return blockStop(reason, host);
+}
 function recordTests() {
   const cmd = input.tool_input?.command ?? "";
   const state = readState(sessionId);
@@ -233,8 +315,11 @@ function buildRouter() {
 }
 var handlers = {
   "pr-opened": prOpened,
+  "pr-terminal": prTerminal,
+  "offer-ran": offerRan,
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
+  "terminal-gate": terminalGate,
   "report-gate": reportGate,
   "build-router": buildRouter
 };