@muggleai/works 5.4.2 → 5.5.1

package/dist/plugin/skills/muggle-pr-followup/state-schemas.md

@@ -30,6 +30,23 @@ A list of one entry. (Historical: the file is an array for forward-compat with t
 - `state` is the **observed** state from the last `gh pr view`. The watcher refreshes it each tick.
 - Terminal states (`merged`, `closed`) are sticky — once set, the watcher writes `result.md` and exits without rescheduling.
 
+## `cron.json`
+
+A durable, on-disk handle to this slot's watcher cron. Its whole reason to exist: `CronList` goes **blind to crons that outlive a session continue / compaction** (the watcher's `/loop` cron survives, but the tool can no longer enumerate it), so a teardown that can only find crons through `CronList` can never delete the orphan — it re-fires until the 7-day `/loop` expiry. A cron id recorded to disk **while the cron was still visible** stays a valid `CronDelete` target afterward. See [`record-cron-id.md`](record-cron-id.md) (who writes it) and [`cancel-cron.md`](cancel-cron.md) (who deletes by it).
+
+```json
+{
+  "cron_id": "<scheduler-id-or-null>",
+  "command": "/muggle:muggle-pr-followup <slug> <n>",
+  "interval": "1m",
+  "recorded_at": "<ISO-8601>"
+}
+```
+
+- `cron_id`: the scheduler id of the live `/loop` cron for this slot. Bootstrap seeds `null` (it dispatches `/loop` as its last action and cannot yet see the id); the first tick self-records the real id per [`record-cron-id.md`](record-cron-id.md). `null` again for the one tick after `/muggle-do` respawns the watcher (a dispatch cancels the old cron and the respawn arms a new one whose id is unknown until the next tick observes it).
+- `command`: the exact two-arg dispatch, the same string [`cancel-cron.md`](cancel-cron.md) matches on as its `CronList` fallback.
+- `interval`: the poll cadence — always `1m`. The watcher polls at `1m` whether or not the PR is blocked; a blocked PR reminds at `1m`, it does not back off (see [`blocked-tick.md`](blocked-tick.md) and [`contract.md`](contract.md) Steps 2.5 / 7). Recorded for teardown/forensics.
+
 ## `last_seen.json`
 
 Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
@@ -45,8 +62,17 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
     "pushed_shas": ["<sha>", ...],
     "ci_fix_attempts": { "<sha>": <int> },
     "ci_escalated_shas": ["<sha>", ...],
-    "conflict_resolve_attempts": { "<sha>": <int> },
-    "conflict_escalated_shas": ["<sha>", ...]
+    "conflict_resolve_attempts": { "<head-sha>..<base-tip-sha>": <int> },
+    "conflict_escalated_keys": ["<head-sha>..<base-tip-sha>", ...],
+    "blocked": {
+      "reason": "conflict_escalated" | "ci_escalated" | "reviews_escalated",
+      "since": "<ISO-8601>",
+      "fingerprint": {
+        "head_sha": "<sha>",
+        "latest_review_id": <int>,
+        "ci_digest": "<string>"
+      }
+    }
   }
 }
 ```
@@ -59,8 +85,16 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
 - `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
 - `ci_fix_attempts`: per-SHA count of fix-ci cycles `/muggle-do` has run. The watcher stops dispatching fix-ci for a SHA once its count reaches 3. Keyed by head SHA.
 - `ci_escalated_shas`: head SHAs whose CI the fix-ci stage gave up on (attempts exhausted or only out-of-scope checks). The watcher excludes these from CI dispatch so a hopeless SHA is never re-fixed.
-- `conflict_resolve_attempts`: per-SHA count of rebase cycles `/muggle-do` has run for this SHA (behind-only or conflicting — both rebase onto the base). The watcher stops dispatching a rebase for a SHA once its count reaches 2. Keyed by head SHA. A clean behind-only rebase produces a new SHA, so the cap only bites a SHA that keeps failing to rebase-and-verify.
-- `conflict_escalated_shas`: head SHAs whose rebase `/muggle-do` gave up on (attempts exhausted, or a conflict under `autoResolveConflicts=never`). The watcher excludes these from rebase dispatch so a hopeless SHA is never re-attempted.
+- `conflict_resolve_attempts`: count of rebase cycles `/muggle-do` has run (behind-only or conflicting — both rebase onto the base). The watcher stops dispatching once a key's count reaches 2. Keyed by `rebase_key` — `"<head_sha>..<base_tip_sha>"`, the head paired with the base branch tip it was measured against.
+- `conflict_escalated_keys`: `rebase_key`s whose rebase `/muggle-do` gave up on (attempts exhausted, or a conflict under `autoResolveConflicts=never`). The watcher excludes these from rebase dispatch so a hopeless pairing is never re-attempted.
+
+Both are keyed on the pair, not the head alone, because whether a branch conflicts depends on both sides. Under a head-only key, a base that moves produces a genuinely new conflict against an unchanged head — and the stale entry suppresses it permanently, because nothing can change the head while the branch sits blocked. Pairing re-arms the budget whenever either side moves. Legacy entries written before this change are bare SHAs with no `..`; readers ignore them, which un-wedges any slot they had blocked.
+
+Unlike these, `ci_fix_attempts` / `ci_escalated_shas` stay keyed on the head SHA alone — a CI result is a function of the head only, so base movement must not re-arm them.
+- `blocked`: present only while the watcher is **awaiting the owner** on a PR that cannot progress without a human ([`contract.md`](contract.md) Step 7). Absent ⇒ the watcher is in its normal dispatch flow. When present, the watcher **keeps the normal `1m` cadence** and each tick is a reminder-or-resume check ([`contract.md`](contract.md) Step 2.5): it re-emits a one-line reminder to the owner, recomputes the `fingerprint`, and clears the block the moment any component moves. Its value is the reason-specific reminder plus fingerprint auto-resume.
+  - `reason`: which durable block is being awaited — `conflict_escalated` (`rebase_key` ∈ `conflict_escalated_keys`), `ci_escalated` (`head_sha` ∈ `ci_escalated_shas`), or `reviews_escalated` (a review sits in `escalated_review_ids` awaiting the user, actionable set empty). Selects the reminder wording; the resume decision is fingerprint-driven, not reason-driven.
+  - `since`: when the block was first flagged — lets the reminder state how long the owner has been the blocker.
+  - `fingerprint`: the external state the block is waiting on. `head_sha` moves on a new push (which also clears the per-SHA escalation sets, keyed by SHA); `latest_review_id` is `max(id)` over submitted reviews and moves when a reviewer submits anything new; `ci_digest` is a stable digest of the head SHA's CI rollup (bucket + each check's name/conclusion, sorted) and moves when a check flips, a rerun lands, or an external check such as a staging deploy posts. Any change clears the block and resumes evaluation.
 
 ## `state.md`
 

package/dist/plugin/skills/skill-deps.config.json

@@ -0,0 +1,8 @@
+{
+  "supportDirs": { "do": "muggle-do" },
+  "sharedNamespaces": ["_shared"],
+  "knownReverseDeps": {
+    "comment": "Reverse dependencies grandfathered so CI stays green — each is a genuine violation of plugin/skills/CLAUDE.md (a shared module or lower-level skill linking UP into a caller). Currently empty: the tree is one-way. If an entry is ever added here, it is debt to fix and delete, not a pattern to copy. The guard blocks any NEW cycle regardless of this list.",
+    "edges": []
+  }
+}

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.4.2",
-  "buildId": "run-62-1",
-  "commitSha": "d87dd32f6b01e48c82ff97aa568835bd2e5a7fc3",
-  "buildTime": "2026-07-05T08:59:08Z",
+  "release": "5.5.1",
+  "buildId": "run-64-1",
+  "commitSha": "60e0213974d01fae642c7b480589d2e6b512f2c7",
+  "buildTime": "2026-07-20T23:29:20Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.4.2",
+  "version": "5.5.1",
   "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",
@@ -22,6 +22,7 @@
     "build:release": "npm run build",
     "verify:plugin": "node scripts/verify-plugin-marketplace.mjs",
     "verify:contracts": "node scripts/verify-compatibility-contracts.mjs",
+    "verify:skill-deps": "node scripts/check-skill-deps.mjs",
     "smoke:cli": "node scripts/smoke-cli.mjs",
     "verify:electron-release-checksums": "node scripts/verify-electron-release-checksums.mjs",
     "verify:upgrade-experience": "node scripts/verify-upgrade-experience.mjs",
@@ -45,14 +46,14 @@
     "eval:studio-gen": "tsx internal/studio-gen-eval/src/run.ts"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.6.6",
+    "electronAppVersion": "1.6.10",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "c905921dda5412bdbb66735cdb81b0e0f76f4211c9ec129eae599d910213547e",
-      "darwin-x64": "3ad51b6babadf73ae607e965dd713fb9ad8a530e6c15c47779c34a96ea90dab4",
-      "linux-x64": "444c603453967f91b4a4ccb12f4344d7bed8d83b5b99d04fc43924c6c45b08f7",
-      "win32-x64": "ab7864489da53920af13905671aca4960cc141e41637590044757e47a439a9d7"
+      "darwin-arm64": "11672d444a151125a4d2f3413a7f0f4f8cb2de64ecbd2a43eddca4f364743b13",
+      "darwin-x64": "6277246853cdcc3aa3fbbaae703d428cfbf85c53fda6720a71a0cadbe8f5a5f6",
+      "linux-x64": "9485e0f9f4a0fb90666e63e87bd83da3c4b865a8cff8da40dc4d1b0ad2aba242",
+      "win32-x64": "e68471bcbf4f00d501067a282e835d00bb2f4941dc42878a8f041a5dab06acdf"
     }
   },
   "dependencies": {

package/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.4.2",
+  "version": "5.5.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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.4.2",
+  "version": "5.5.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/hooks/README.md

@@ -35,3 +35,9 @@ Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json
 | `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 and no E2E ran yet | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` (releases after 3 blocks) |
 | `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
+
+`SessionStart` (`scripts/reconcile-stale-watchers.sh`) — a standalone advisory, not part of the `guardrails.mjs` decision tree above.
+
+`muggle-pr-followup` watchers are session-only `/loop` crons; they die on session end and the 7-day `/loop` expiry, leaving open PRs with no live poller. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs the `CronCreate` tool, which a shell hook can't call. So this hook nudges rather than acts: it scans `~/.muggle-ai/muggle-do/sessions/*/` for open slots (a `prs.json` with no `result.md`) and, **only when one or more exist**, injects `additionalContext` telling the agent to run `/muggle:muggle-pr-followup reconcile`. Zero open slots → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.

package/plugin/hooks/hooks.json

@@ -7,7 +7,14 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/ensure-electron-app.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 120
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/reconcile-stale-watchers.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -19,7 +26,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-report-format.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -31,12 +39,14 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-opened.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           },
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       },
@@ -46,7 +56,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -57,7 +68,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -68,7 +80,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-router.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }

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

@@ -1,9 +1,23 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -uo pipefail
 
 # Front-door router (UserPromptSubmit). On the first build/implement/fix prompt
 # of a session, offers to route the work through /muggle-do (build delegated to
 # superpowers), gated by autoRouteBuildToMuggleDo. Fires once per session.
-# Degrades to {} so it never blocks a turn.
+#
+# Node cold-start (spawn + module load) stalls the turn on a loaded box, and this
+# hook runs on EVERY prompt. A cheap in-shell keyword pre-filter mirrors the build
+# verbs guardrails.mjs looks for, so the vast majority of prompts (questions,
+# status checks, chit-chat) never spawn Node. Node runs only on a keyword hit,
+# 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
+
 root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-node "${root}/scripts/guardrails.mjs" build-router 2>/dev/null || printf '{}'
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" build-router 2>/dev/null || printf '{}'

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

@@ -1,8 +1,38 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -uo pipefail
 
 # tests-green → E2E gate (Stop). When unit tests passed this session and no E2E
 # acceptance run has happened, offer to run change-driven E2E (gated by
-# autoE2ETest). Fires once per session. Degrades to {} so it never blocks a turn.
+# autoE2ETest). Fires once per session.
+#
+# 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 the gate could actually fire — i.e. shouldRunE2E: unit tests
+# went green and no E2E run is recorded yet. On the overwhelming majority of
+# turns (no test run this session) the state file is absent or unitTestsGreen is
+# unset, 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')"
+
+# 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 '"unitTestsGreen": true' "$state_file" \
+  || grep -q '"e2eRun": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
 root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-node "${root}/scripts/guardrails.mjs" e2e-gate 2>/dev/null || printf '{}'
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" e2e-gate 2>/dev/null || printf '{}'

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

@@ -1,10 +1,21 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -uo pipefail
 
 # PR-opened guardrail (PostToolUse/Bash). When a `gh pr create`/`gh pr ready`
 # just succeeded, offer to start a muggle-pr-followup watcher on the new PR
 # (gated by autoWatchPR, deduped per session). Decision logic lives in the
-# bundled guardrails.mjs; this wrapper just pipes the event payload through and
-# degrades to {} so a guardrail can never block a turn.
+# bundled guardrails.mjs.
+#
+# This fires after EVERY Bash call, so a keyword pre-filter for the PR-open
+# commands keeps Node off the hot path — only a `gh pr create|ready` or
+# `glab mr create|update` even reaches guardrails.mjs, which then confirms the
+# command succeeded and extracts the URL. Degrades to {} so it never blocks.
+payload="$(cat)"
+
+if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(create|ready)|glab[[:space:]]+mr[[:space:]]+(create|update)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
 root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-node "${root}/scripts/guardrails.mjs" pr-opened 2>/dev/null || printf '{}'
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" pr-opened 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-record-tests.sh

@@ -1,9 +1,22 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -uo pipefail
+
+# tests-green observer (PostToolUse/Bash + muggle E2E tools). Records in
+# per-session state when a unit-test command passed (and when a muggle E2E run
+# happened). Emits no directive — the Stop gate (guardrail-e2e-gate.sh) reads
+# the state.
+#
+# Fires after every Bash call and every muggle execute/replay, so a keyword
+# pre-filter for test runners and the muggle E2E tool names keeps Node off the
+# hot path. Only a `test` command (npm/pnpm/yarn/jest/vitest/pytest/go/cargo) or
+# a muggle execute/replay/test-generation event reaches guardrails.mjs, which
+# then inspects the output for pass/fail and updates state. Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
 
-# tests-green observer (PostToolUse/Bash). Records in per-session state when a
-# unit-test command passed (and when a muggle E2E run happened). Emits no
-# directive — the Stop gate (guardrail-e2e-gate.sh) reads the state. Degrades
-# to {} so it never blocks a turn.
 root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-node "${root}/scripts/guardrails.mjs" record-tests 2>/dev/null || printf '{}'
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" record-tests 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-report-format.sh

@@ -1,9 +1,23 @@
 #!/usr/bin/env bash
-set -euo pipefail
+set -uo pipefail
 
 # Report-format gate (PreToolUse, Bash). Denies a `gh pr comment|create|edit`
 # whose body reads like a hand-written E2E report — one that lacks the
 # build-pr-section sentinel — so every posted walkthrough goes through the
-# deterministic renderer. Degrades to {} so it never blocks an unrelated command.
+# deterministic renderer.
+#
+# This must stay synchronous (only a sync PreToolUse hook can deny), and it fires
+# before every Bash call. A keyword pre-filter for the three PR-posting commands
+# keeps Node off the hot path: a plain `ls`/`git status`/build command returns {}
+# in-shell and never pays cold-start. Only a `gh pr comment|create|edit` reaches
+# guardrails.mjs, which reads the body (incl. --body-file) and decides. Degrades
+# to {} so it never blocks an unrelated command.
+payload="$(cat)"
+
+if ! grep -Eiq 'gh[[:space:]]+pr[[:space:]]+(comment|create|edit)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
 root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
-node "${root}/scripts/guardrails.mjs" report-gate 2>/dev/null || printf '{}'
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" report-gate 2>/dev/null || printf '{}'

package/plugin/scripts/reconcile-stale-watchers.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# muggle-pr-followup watchers are session-only crons — they die on session end
+# and on the 7-day /loop expiry, leaving open PRs with no live poller. Re-arming
+# needs CronCreate, a Claude tool a shell hook can't call, so this hook can't
+# recover a watcher itself. It nudges instead: on session start, if any open slot
+# exists, it tells the agent to run reconcile (which finalizes terminal slots and
+# re-arms silently-dead open watchers). A pure directory scan — no gh, no writes —
+# so it stays cheap enough to run on every session start.
+
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+# A slot is a live-or-dead open watcher iff it has prs.json (a tracked PR) but no
+# result.md (not yet finalized). result.md is the terminal marker.
+sessions_dir="${HOME}/.muggle-ai/muggle-do/sessions"
+stale_count=0
+if [ -d "$sessions_dir" ]; then
+    for slot in "$sessions_dir"/*/; do
+        [ -d "$slot" ] || continue
+        if [ -f "${slot}prs.json" ] && [ ! -f "${slot}result.md" ]; then
+            stale_count=$((stale_count + 1))
+        fi
+    done
+fi
+
+# Clean state: no open slots to reconcile → stay completely silent, never nudge.
+if [ "$stale_count" -eq 0 ]; then
+    exit 0
+fi
+
+if [ "$stale_count" -eq 1 ]; then
+    slot_word="slot"
+else
+    slot_word="slots"
+fi
+
+context="muggle-pr-followup: ${stale_count} open watcher ${slot_word} found (a tracked PR with no result.md). Session-only watcher crons die on session end and after the 7-day /loop expiry, so these may have no live poller. Run \`/muggle:muggle-pr-followup reconcile\` to finalize any whose PR went terminal and re-arm silently-stopped open watchers. Reconcile is idempotent — it re-arms only genuinely dead watchers and stays quiet on the rest."
+
+escaped_context=$(escape_for_json "$context")
+
+if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
+    printf '{\n  "additional_context": "%s"\n}\n' "$escaped_context"
+elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+    printf '{\n  "hookSpecificOutput": {\n    "hookEventName": "SessionStart",\n    "additionalContext": "%s"\n  }\n}\n' "$escaped_context"
+else
+    printf '{\n  "additional_context": "%s"\n}\n' "$escaped_context"
+fi
+
+exit 0

package/plugin/skills/CLAUDE.md

@@ -14,6 +14,12 @@ A reverse reference (A → B and B → A) couples the depended-on skill to its c
 
 When you feel the urge to link "up" to a caller, that is the smell — restructure so the caller passes what is needed in.
 
+### Enforcement
+
+`scripts/check-skill-deps.mjs` derives the cross-skill link graph and fails on any cycle. A "reference" is a markdown file-link into another skill's directory — runtime slash-command dispatch is not a link and is not counted. It runs three ways: the `skill-deps` CI job on every PR, a `PreToolUse` hook (`.claude/settings.json`) that blocks the write mid-session with the offending link named, and `pnpm run verify:skill-deps` locally.
+
+`plugin/skills/skill-deps.config.json` declares support dirs grouped into their owning skill (`do/` → `muggle-do`), shared namespaces exploded to per-file nodes (`_shared`), and `knownReverseDeps` — pre-existing violations grandfathered so CI stays green. That list is debt: fix each link and delete its entry. A new reverse dependency is blocked whether or not it is on the list.
+
 ## Model tiers
 
 Each skill sets a `model:` in its `SKILL.md` frontmatter sized to its cognitive load. `model:` is a native Claude Code field — the override applies while the skill is active and reverts to the session model when it exits. Cheaper, faster models run the mechanical skills; the default (Opus) is reserved for the ones that actually reason. Cost and latency scale with the model, and these skills run often (the watcher fires every minute), so the tier is a real lever, not cosmetics.

package/plugin/skills/_shared/dev-loop/run.md

@@ -1,6 +1,6 @@
 # Dev Loop — Run a Test
 
-> The local dev loop: run one test case in the browser (replay an existing script, or regenerate from the case), then record the result. Source of truth for the run mechanics; the sibling files in this folder own each invariant. Used by `muggle-test`, `muggle-test-feature-local`, `muggle-do` Stage 6 ([`../../do/e2e-acceptance.md`](../../do/e2e-acceptance.md)), and the `acceptance-tester` agent.
+> The local dev loop: run one test case in the browser (replay an existing script, or regenerate from the case), then record the result. Source of truth for the run mechanics; the sibling files in this folder own each invariant.
 
 Not owned here — the caller resolves and passes in: which test cases to run, replay-vs-regen classification and failure routing ([`../failure-mode-handling.md`](../failure-mode-handling.md)), dev-server readiness ([`../dev-server-readiness.md`](../dev-server-readiness.md)), validation context ([`../resolve-e2e-validation-context.md`](../resolve-e2e-validation-context.md)), and PR posting ([`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md)).
 

package/plugin/skills/_shared/post-merge-cleanup.md

@@ -2,9 +2,8 @@
 
 Gated by [`autoCleanup`](../muggle-preferences/preference-gates/autoCleanup.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md). Fire only after the PR is **merged** — never while it's still open.
 
-On `always`, the four steps below run as one pre-authorized sequence (no per-step prompts). Stop on the first failure; do not force.
+On `always`, the steps below run as one pre-authorized sequence (no per-step prompts). Stop on the first failure; do not force.
 
-1. `git worktree remove {worktreePath}` — only if a worktree was used.
+1. **Remove the worktree — link-safe.** `git worktree remove {worktreePath}`, only if a worktree was used. A worktree's dependency dir (e.g. `node_modules`) is often a **link** (symlink, or a Windows junction) to a shared tree, not a real copy — and a forced/recursive delete follows the link and wipes that shared target, breaking every worktree. So never `--force`: unlink the dependency link first (remove the link only, using the host OS's unlink), then a plain `git worktree remove {worktreePath}`.
 2. `git branch -d {branch}` — **skip when no worktree was used**: the branch is the user's current live checkout (a bootstrap/auto-track watcher), and the checked-out branch must never be deleted. Then `git push origin --delete {branch}`.
 3. Clear `.muggle-ai/` session folders for this branch's runs and stale `/tmp/muggle-prepare-*.log` files. Cloud results stay.
-4. Invoke `commit-commands:clean_gone` via the `Skill` tool.

package/plugin/skills/_shared/rebase-before-e2e.md

@@ -16,6 +16,6 @@ Pass `{behind}` and `{default}` to the picker prompts. On `always`:
 2. `git rebase origin/${default}`.
 3. On conflict, branch by [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
    - `never` → `git rebase --abort`; stop and report, naming the conflicted files. Never auto-resolve.
-   - `always` → hand off to [`resolve-rebase-conflicts.md`](resolve-rebase-conflicts.md) with `pre_rebase_sha`; it resolves, runs the verify-or-rollback gate, and either proceeds or restores `pre_rebase_sha` and escalates.
+   - `always` → hand off to [`resolve-rebase-conflicts.md`](resolve-rebase-conflicts.md) with `pre_rebase_sha` to resolve the conflicts, then run the [`verify-or-rollback-gate.md`](verify-or-rollback-gate.md) with `pre_rebase_sha`; it either proceeds or restores `pre_rebase_sha` and escalates.
 
 Stale branches produce false failures and false greens — that's why this gate exists.

package/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -28,7 +28,7 @@ Resolve without prompting; use as questionnaire defaults:
 
 ## Questions
 
-One `AskUserQuestion` for the validation subset, detected values as defaults. Canonical wording lives in [`../do/pre-flight.md`](../do/pre-flight.md) — reference, don't fork:
+One `AskUserQuestion` for the validation subset, detected values as defaults. Ask each with the same intent the interactive pre-flight uses; the caller supplies the exact option wording:
 
 - Validation strategy — pre-flight Q4
 - Local URL — pre-flight Q5 (defers to [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md))

package/plugin/skills/_shared/resolve-rebase-conflicts.md

@@ -1,14 +1,13 @@
-# Auto-Resolve Rebase Conflicts
+# Resolve Rebase Conflicts
 
-The autonomous conflict-resolution body, run when a rebase onto `origin/{default}` reports conflicts **and** [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md) is `always`. Under `never` the caller aborts and escalates instead, and this file never runs. The caller hands off the inputs below; this file names no caller — the dependency runs one way.
+How to resolve the conflicts a rebase onto `origin/{default}` reports, when [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md) is `always`. Under `never` the caller aborts and escalates instead, and this file never runs. The caller hands off the inputs below and, once resolution completes, runs the [`verify-or-rollback-gate.md`](verify-or-rollback-gate.md) before anything ships. This file names no caller — the dependency runs one way.
 
-Contract: never push an auto-resolved rebase that has not passed the verify gate, and always keep the branch restorable to its pre-rebase state.
+Contract: resolve deterministically where the change is mechanical, reason about intent where it is semantic, and never guess in load-bearing logic — hand an unreconcilable conflict back to the caller rather than fabricating a merge.
 
 ## Inputs
 
-- `pre_rebase_sha` — branch HEAD captured by the caller **before** `git rebase`; the rollback point.
+- `pre_rebase_sha` — branch HEAD captured by the caller **before** `git rebase`; the caller passes it on to the verify-or-rollback gate as the rollback point.
 - `default` — the branch being rebased onto.
-- Session context: slug, PR url/number, and the persisted validation strategy (for the E2E step).
 
 ## Procedure
 
@@ -26,35 +25,12 @@ Classify each conflicted path:
 ### Step 2 — Resolve
 
 - **Mechanical** → resolve deterministically: regenerate the lockfile with the repo's package manager; regenerate or take-incoming for generated files; run the repo's formatter. Never hand-merge a lockfile.
-- **Semantic** → a reasoned 3-way resolution preserving the intent of **both** sides (ours = the PR's change, theirs = the new default-branch line). If intent in load-bearing logic can't be confidently reconciled, do not guess → Step 5.
+- **Semantic** → a reasoned 3-way resolution preserving the intent of **both** sides (ours = the PR's change, theirs = the new default-branch line). If intent in load-bearing logic can't be confidently reconciled, do not guess: `git rebase --abort` and hand the unreconcilable paths back to the caller, which restores `pre_rebase_sha` and escalates via the verify-or-rollback gate.
 
-Then `git add -A && git rebase --continue`, and repeat Steps 1–2 for each remaining conflicted commit until the rebase completes.
-
-### Step 3 — Verify gate (mandatory)
-
-Each must pass, in order:
-
-1. **Build** — typecheck + lint on the changed surface, per [`../do/build.md`](../do/build.md).
-2. **Unit suite** — per [`../do/unit-tests.md`](../do/unit-tests.md); record PASS.
-3. **E2E** — per [`../do/e2e-acceptance.md`](../do/e2e-acceptance.md) and the persisted [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md) strategy. A poll-only session with no validation context reports `SKIPPED`, same as the normal cycle.
-
-### Step 4 — Pass → proceed
-
-Return success. The caller resumes the normal flow; the push happens downstream, so a resolved rebase ships only after it has verified.
-
-### Step 5 — Fail → restore + escalate
-
-On an unreconcilable semantic conflict (Step 2) or any verify failure (Step 3):
-
-```bash
-git rebase --abort 2>/dev/null || true
-git reset --hard <pre_rebase_sha>
-```
-
-The branch is now byte-for-byte its pre-rebase state. Emit one terminal escalation per [`../muggle-pr-followup/output-templates/escalation.md`](../muggle-pr-followup/output-templates/escalation.md) naming the conflicted files and the failing step, plus the `muggle-do:escalation` event with `kind: "rebase-conflict"` ([`telemetry-events/muggle-do-escalation.md`](telemetry-events/muggle-do-escalation.md)). Do not push.
+Then `git add -A && git rebase --continue`, and repeat Steps 1–2 for each remaining conflicted commit until the rebase completes. On success, return to the caller, which runs the verify-or-rollback gate before the resolved tree ships.
 
 ## Invariants
 
-- A push never follows a verify failure.
-- The branch is always restorable to `pre_rebase_sha`.
-- This file runs only under `autoResolveConflicts = always`; `never` is the caller's unchanged abort-and-escalate path.
+- Never fabricate a merge in load-bearing logic; an unreconcilable conflict goes back to the caller.
+- This file resolves; it does not verify or push. The [`verify-or-rollback-gate.md`](verify-or-rollback-gate.md) owns the ship-or-rollback decision.
+- Runs only under `autoResolveConflicts = always`; `never` is the caller's unchanged abort-and-escalate path.

package/plugin/skills/_shared/session-state-writes.md

@@ -1,6 +1,6 @@
 # Writing session-state files
 
-How to update the session-state JSON — `last_seen.json` and `prs.json` under `~/.muggle-ai/muggle-do/sessions/<slug>/`. Field shapes: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md). Both the watcher and `/muggle-do` write these.
+How to update the session-state JSON — `last_seen.json` and `prs.json` under `~/.muggle-ai/muggle-do/sessions/<slug>/`. Field shapes: see the [`## Field map`](#field-map) below.
 
 ## Mechanism — tool-based, OS-agnostic
 
@@ -18,5 +18,5 @@ If you script the rewrite instead of using the Write tool, any tool that replace
 
 ## Field map
 
-- `last_seen.json` — one object keyed by `"<owner>/<repo>#<n>"`. Mutate fields under that key: `idle_tick_count`, `cycles_completed` (counters), `last_pushed_sha`, `lastBodyReviewId` (scalars), `pushed_shas`, `escalated_review_ids`, `ci_escalated_shas`, `conflict_escalated_shas` (arrays), `ci_fix_attempts[<sha>]`, `conflict_resolve_attempts[<sha>]` (per-SHA maps).
+- `last_seen.json` — one object keyed by `"<owner>/<repo>#<n>"`. Mutate fields under that key: `idle_tick_count`, `cycles_completed` (counters), `last_pushed_sha`, `lastBodyReviewId` (scalars), `pushed_shas`, `escalated_review_ids`, `ci_escalated_shas`, `conflict_escalated_keys` (arrays), `ci_fix_attempts[<sha>]` (keyed by head SHA), `conflict_resolve_attempts[<head-sha>..<base-tip-sha>]` (keyed by the head/base-tip pair).
 - `prs.json` — a one-element array. Mutate `[0]`: `head_sha`, `state`.

package/plugin/skills/_shared/telemetry-events/muggle-do-cycle.md

@@ -30,6 +30,6 @@ One per address-reviews invocation, regardless of outcome.
 - `"ci-fixed"` — a watcher-dispatched fix-ci cycle pushed a fix for one or more red checks.
 - `"ci-escalated"` — fix-ci exhausted its 3 attempts for the SHA or the failing checks were out of scope; the SHA was added to `ci_escalated_shas`. No further auto-fix on it.
 - `"rebased"` — a watcher-dispatched rebase cycle rebased the branch onto its base (behind-only or conflicts resolved), verified, and force-pushed.
-- `"rebase-escalated"` — the rebase couldn't be completed (a conflict under `autoResolveConflicts=never`, verification failed, or the 2-attempt budget for the SHA was spent); the SHA was added to `conflict_escalated_shas`. No further auto-rebase on it.
+- `"rebase-escalated"` — the rebase couldn't be completed (a conflict under `autoResolveConflicts=never`, verification failed, or the 2-attempt budget for the head/base-tip pair was spent); the pair was added to `conflict_escalated_keys`. No further auto-rebase until either side moves.
 
 For fix-ci cycles (`ci-fixed` / `ci-escalated`) the `review_ids_*` arrays are empty and the `ci_checks_*` arrays carry the data: `ci_checks_in` (red checks dispatched), `ci_checks_fixed` (made green and pushed), `ci_checks_escalated` (out-of-scope or unresolved). For rebase cycles (`rebased` / `rebase-escalated`) all the `review_ids_*` and `ci_checks_*` arrays are empty; the SHA fields carry the before/after of the rebase.

package/plugin/skills/_shared/telemetry-events/pr-followup-tick.md

@@ -17,6 +17,7 @@ One per watcher iteration (idle or not).
   "dispatched_ci_fix": true | false,
   "terminal": true | false,
   "idle": true | false,
+  "blocked": true | false,
   "tick_duration_ms": <int>
 }
 ```
@@ -29,3 +30,4 @@ One per watcher iteration (idle or not).
 - `dispatched_ci_fix`: true when this tick dispatched `/muggle-do` with a fix-ci directive.
 - `terminal`: true when this tick observed the PR merged or closed and wrote `result.md`.
 - `idle`: true when nothing was dispatched this tick.
+- `blocked`: true on a tick that idled on a durable human-block (escalated rebase/CI, or an ambiguous review awaiting the user) and emitted the one-line owner reminder. `false` otherwise. Always accompanies `idle: true`. The block reminds at the normal `1m` cadence — it never backs off — so a `blocked: true` tick reminds exactly once.

package/plugin/skills/_shared/use-worktrees.md

@@ -7,7 +7,6 @@ Use this for feature development, local validation, and PR iteration.
 - **One worktree per branch.** Never switch branches inside a long-lived checkout.
 - **Isolate runtime resources.** Parallel worktrees need unique ports and isolated mutable test state.
 - **Keep worktrees disposable.** Create for focused work, remove after merge.
-- **Existing PR branch?** Materialize it via [`pr-branch-worktree.md`](pr-branch-worktree.md) — same `<repo>/.claude/worktrees/` path scheme, checking out the existing branch instead of creating a new one.
 
 ## Start new change work