@muggleai/works 5.4.1 → 5.5.0

package/README.md

@@ -555,7 +555,7 @@ CI/CD and publishing
 | `verify-end-user-upgrade.yml` | Weekly + manual | Existing-user upgrade validation (cleanup + re-download + health checks) |
 | `publish-works-to-npm.yml` | Tag `v*` or manual  | Verify (including release checksums), audit, smoke-install, publish to npm |
 
-**Publishing `@muggleai/works`:** use the maintainer-only skill **`.claude/skills/muggle-works-npm-release/SKILL.md`** — a repo-local project skill (invoke `/muggle-works-npm-release` in Claude Code, or `/mrelease`, while working in this repo; mirrored to `.cursor/skills/` for Cursor). It is intentionally not in the published plugin (`plugin/skills/`) since it is maintainer-only. It does the bump + `pnpm run sync:versions`, local verify, `chore(release)` PR, merge, then `workflow_dispatch` with an explicit `version`. Do not rely on tagging alone while `package.json` / marketplace manifests on `master` are still old — CI can publish a version that does not match the checked-in manifests. Tag `v*` push remains a valid workflow trigger when it matches the merged release commit.
+**Publishing `@muggleai/works`:** use the maintainer-only skill **`.claude/skills/muggle-works-npm-release/SKILL.md`** — a repo-local project skill (invoke `/muggle-works-npm-release` in Claude Code, or `/mrelease`, while working in this repo; mirrored to `.cursor/skills/` for Cursor). To invoke it from any project — not only when the cwd is this repo — run `pnpm run link:maintainer-skills`, which symlinks the maintainer skills from `.claude/skills/` into `~/.claude/skills/`; it is idempotent and safe to re-run if a skill moves. It is intentionally not in the published plugin (`plugin/skills/`) since it is maintainer-only. It does the bump + `pnpm run sync:versions`, local verify, `chore(release)` PR, merge, then `workflow_dispatch` with an explicit `version`. Do not rely on tagging alone while `package.json` / marketplace manifests on `master` are still old — CI can publish a version that does not match the checked-in manifests. Tag `v*` push remains a valid workflow trigger when it matches the merged release commit.
 
 Release tag strategy
 

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

package/dist/plugin/hooks/hooks.json

@@ -7,7 +7,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/ensure-electron-app.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 120
           }
         ]
       }
@@ -19,7 +20,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-report-format.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -31,12 +33,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 +50,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-tests.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -57,7 +62,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-e2e-gate.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }
@@ -68,7 +74,8 @@
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-build-router.sh\"",
-            "async": false
+            "async": false,
+            "timeout": 10
           }
         ]
       }

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -2,6 +2,26 @@
 
 set -euo pipefail
 
+# Epoch mtime of a file, or 0 if unreadable. GNU coreutils (Linux/WSL/Git Bash)
+# need `stat -c %Y`; BSD/macOS need `stat -f %m`. The wrong form doesn't fail
+# cleanly — GNU `stat -f` prints filesystem info to stdout and exits non-zero —
+# so each form is tried alone and accepted only when all-digits, keeping stray
+# text like `File:` out of the caller's arithmetic.
+file_mtime() {
+    local f="$1" m
+    m=$(stat -c %Y "$f" 2>/dev/null) || m=""
+    case "$m" in ''|*[!0-9]*) ;; *) printf '%s\n' "$m"; return 0 ;; esac
+    m=$(stat -f %m "$f" 2>/dev/null) || m=""
+    case "$m" in ''|*[!0-9]*) ;; *) printf '%s\n' "$m"; return 0 ;; esac
+    printf '0\n'
+}
+
+# Sourcing with MUGGLE_ENSURE_ELECTRON_LIB_ONLY=1 exposes the helper above
+# without running the hook — used by the unit test.
+if [ -n "${MUGGLE_ENSURE_ELECTRON_LIB_ONLY:-}" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
 # Ensure the Electron browser test runner is installed/up to date (silent, best-effort).
 #
 # Bounded + cached: this script runs from a SessionStart hook on every Claude
@@ -16,7 +36,7 @@ ensure_ttl=$((24 * 60 * 60))
 ensure_now=$(date +%s)
 ensure_last=0
 if [ -f "${ensure_marker}" ]; then
-    ensure_last=$(stat -f %m "${ensure_marker}" 2>/dev/null || stat -c %Y "${ensure_marker}" 2>/dev/null || echo 0)
+    ensure_last=$(file_mtime "${ensure_marker}")
 fi
 
 if [ $((ensure_now - ensure_last)) -ge "${ensure_ttl}" ]; then
@@ -60,7 +80,7 @@ version_check() {
     now=$(date +%s)
 
     if [ -f "$cache_file" ]; then
-        mtime=$(stat -f %m "$cache_file" 2>/dev/null || stat -c %Y "$cache_file" 2>/dev/null || echo 0)
+        mtime=$(file_mtime "$cache_file")
         age=$((now - mtime))
         if [ "$age" -lt "$ttl" ]; then
             cached=$(cat "$cache_file" 2>/dev/null || true)

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/plugin/skills/_shared/rebase-before-e2e.md

@@ -15,7 +15,7 @@ Pass `{behind}` and `{default}` to the picker prompts. On `always`:
 1. Capture the rollback point: `pre_rebase_sha=$(git rev-parse HEAD)`.
 2. `git rebase origin/${default}`.
 3. On conflict, branch by [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
-   - `never` (default) → `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.
+   - `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` 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/dist/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/dist/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 the default `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/dist/plugin/skills/_shared/session-state-writes.md

@@ -0,0 +1,22 @@
+# 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: see the [`## Field map`](#field-map) below.
+
+## Mechanism — tool-based, OS-agnostic
+
+To apply any `increment` / `reset` / `set` / `append` a procedure calls for:
+
+1. **Read** the whole file (Read tool).
+2. Change the one field in the parsed JSON.
+3. **Write** the whole file back (Write tool).
+
+A whole-file rewrite with the Read and Write tools. These are platform-independent — no shell — so the same three steps hold on Windows, macOS, and Linux.
+
+**Never use the Edit tool on these files.** Edit needs its `old_string` to match the file's exact bytes, but the on-disk formatting isn't guaranteed to match the shapes documented in `state-schemas.md` — a writer may emit the JSON on a single line. A mismatched `old_string` silently fails: the edit is dropped ("malformed edit") and the value never changes. A whole-file Write can't miss.
+
+If you script the rewrite instead of using the Write tool, any tool that replaces the **whole file** is fine — e.g. `jq '…' file > tmp && mv tmp file` in a POSIX shell, or the equivalent `Get-Content`/`Set-Content` in PowerShell. The rule is only: whole file, never a partial Edit.
+
+## 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).
+- `prs.json` — a one-element array. Mutate `[0]`: `head_sha`, `state`.

package/dist/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/dist/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
 

package/dist/plugin/skills/_shared/vcs/github/verify-working-tree.md

@@ -14,4 +14,4 @@ Accept any remote URL form for `<owner>/<repo>` (with or without trailing `.git`
 - `git@github.com:<owner>/<repo>`
 - `ssh://git@github.com/<owner>/<repo>`
 
-Any mismatch → bootstrap aborts using the wrong-checkout template in [`../../../muggle-pr-followup/output-templates/bootstrap.md`](../../../muggle-pr-followup/output-templates/bootstrap.md).
+Any mismatch → abort; the calling skill reports the wrong checkout to the user with its own message.

package/dist/plugin/skills/_shared/verify-or-rollback-gate.md

@@ -0,0 +1,39 @@
+# Verify-or-Rollback Gate
+
+The mandatory gate a caller runs after an operation has mutated the working tree and that tree must be proven safe before anything ships — e.g. a resolved rebase onto `origin/{default}`. It verifies the changed surface; on any failure it restores the branch to its pre-mutation state and escalates. The caller hands off the inputs below; this file names no caller — the dependency runs one way.
+
+Contract: never let a mutated tree ship without passing verification, and always keep the branch restorable to its pre-mutation state.
+
+## Inputs
+
+- `pre_rebase_sha` — branch HEAD the caller captured **before** the mutating operation; the rollback point.
+- Session context: slug, PR url/number, and the persisted validation strategy (for the E2E step).
+
+## Procedure
+
+### Step 1 — Verify (mandatory)
+
+Each must pass, in order:
+
+1. **Build** — typecheck + lint on the changed surface, run via the caller's build step.
+2. **Unit suite** — the caller's unit run; record PASS.
+3. **E2E** — the caller's E2E step under 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 2 — Pass → proceed
+
+Return success. The caller resumes the normal flow; the push happens downstream, so a mutated tree ships only after it has verified.
+
+### Step 3 — Fail → restore + escalate
+
+On any verify failure — or when the caller reports the preceding operation could not complete:
+
+```bash
+git reset --hard <pre_rebase_sha>
+```
+
+The branch is now byte-for-byte its pre-mutation state. Emit one terminal escalation — the caller's escalation message — naming 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.
+
+## Invariants
+
+- A push never follows a verify failure.
+- The branch is always restorable to `pre_rebase_sha`.

package/dist/plugin/skills/do/address-reviews.md

@@ -29,7 +29,7 @@ Read from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 ### Step 0 — Track the default branch
 
-Before assembling work, rebase onto the latest default branch so the cycle addresses reviews against current master, not a stale base. Run [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) — gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md): the default `never` aborts and escalates (`kind: "rebase-conflict"`); `always` resolves behind the verify-or-rollback gate. If the rebase escalates, stop the cycle — do not push.
+Before assembling work, rebase onto the latest default branch so the cycle addresses reviews against current master, not a stale base. Run [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) — gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), fires only when `behind > 0`. Conflict handling follows [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md): the default `never` aborts and escalates (`kind: "rebase-conflict"`); `always` resolves behind the verify-or-rollback gate. If the rebase escalates, stop the cycle — do not push, do not address reviews — but **skip to Step 6 to respawn the watcher**. Escalating the rebase does not end the PR; the poller must keep running (it will remind on the `conflict_escalated` block), so skipping respawn here is exactly the silent-stop bug [`respawn-watcher.md`](respawn-watcher.md) exists to prevent.
 
 ### Step 1 — Assemble the work set
 
@@ -103,6 +103,8 @@ Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable re
 
 ### Step 5 — Update session state
 
+Apply each field write below as a whole-file rewrite (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md) — never the Edit tool.
+
 - `last_seen.cycles_completed` += 1
 - `last_seen.last_pushed_sha` = the new head SHA (update.md already wrote this; verify)
 - `last_seen.lastBodyReviewId` = max(body-only input review ids ∪ last_seen.lastBodyReviewId) — line-comment threads need no watermark; they fall out of the actionable set once the per-comment reply carries the loop marker.
@@ -113,16 +115,7 @@ Invoke [`resolve-reminder.md`](resolve-reminder.md) once, regardless of whether
 
 ### Step 6 — Respawn the watcher
 
-Refresh PR state with the provider resolved in Step 1 — `github` per [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md), `gitlab` per [`../_shared/vcs/gitlab/mr-metadata.md`](../_shared/vcs/gitlab/mr-metadata.md) (`state == merged`/`closed`, lowercase). If the PR is now merged or closed:
-
-1. Write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd).
-2. Do **not** respawn the watcher.
-
-Otherwise, dispatch the next watcher as the last action of this turn. The watcher cancelled its own cron when it dispatched this cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 4), so this restart is the single live watcher — never a duplicate:
-
-```
-/loop 1m /muggle:muggle-pr-followup <slug> <n>
-```
+Respawn per [`respawn-watcher.md`](respawn-watcher.md): refresh PR state, finalize (write `result.md`, no respawn) if the PR is now merged or closed, otherwise restart the single live watcher as the turn's last action. **Every** exit path in this procedure lands here — the actionable-and-pushed happy path, the ambiguous-only branch (Step 3), the design-adjustment escalation, and the Step 0 rebase-escalation — so an open PR is never left un-watched.
 
 ### Step 7 — Telemetry
 

package/dist/plugin/skills/do/fix-ci.md

@@ -39,8 +39,8 @@ Commit per the `fix(ci): <check> — <what>` convention ([`../_shared/pr-followu
 
 ### Step 5 — Update state + respawn
 
-- Increment `last_seen.ci_fix_attempts[red_sha]`.
-- Respawn the watcher: `/loop 1m /muggle:muggle-pr-followup <slug> <n>`. The watcher cancelled its own cron when it dispatched this fix-ci cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 5), so this restart is the single live watcher. CI on the new SHA is the verify loop — a still-red SHA returns as a fresh dispatch, bounded by the per-SHA fix budget (Step 6).
+- Increment `last_seen.ci_fix_attempts[red_sha]` — a whole-file rewrite (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md), never the Edit tool.
+- Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md). CI on the new SHA is the verify loop — a still-red SHA returns as a fresh dispatch, bounded by the per-SHA fix budget (Step 6).
 
 ### Step 6 — Escalate (budget spent or out of scope)
 
@@ -48,7 +48,8 @@ When the failing checks are all out of scope, or `ci_fix_attempts[red_sha]` has
 
 1. Add `red_sha` to `last_seen.ci_escalated_shas` so the SHA is not re-fixed.
 2. Emit one terminal message naming the unresolved checks.
-3. Emit the cycle event with `outcome: "ci-escalated"` (Step 7). Do not loop further on this SHA.
+3. Emit the cycle event with `outcome: "ci-escalated"` (Step 7).
+4. **Respawn the watcher** per [`respawn-watcher.md`](respawn-watcher.md). Escalation stops fix-ci from re-dispatching this SHA — but the poller must keep running: it reminds on the `ci_escalated` block and catches a new push, a new review, or the user's own fix. Skipping respawn here is the silent-stop bug the helper exists to prevent.
 
 ### Step 7 — Telemetry
 

package/dist/plugin/skills/do/open-prs/update.md

@@ -24,7 +24,7 @@ Resolve the provider once per [`../../_shared/vcs/detect-vcs.md`](../../_shared/
 
 1. **Push:** per [`../../_shared/vcs/github/push-to-branch.md`](../../_shared/vcs/github/push-to-branch.md). Capture the new SHA.
 
-2. **Append new SHA** to `last_seen.json[<key>].pushed_shas` (the resolve-reminder stage uses this to recognize threads addressed by the loop). Set `last_seen.last_pushed_sha` to the new SHA too.
+2. **Append new SHA** to `last_seen.json[<key>].pushed_shas` (the resolve-reminder stage uses this to recognize threads addressed by the loop). Set `last_seen.last_pushed_sha` to the new SHA too. Both are whole-file rewrites (Read → change field → Write) per [`../../_shared/session-state-writes.md`](../../_shared/session-state-writes.md) — never the Edit tool.
 
 3. **Refresh title if state changed.** Compare the new state against the current PR title prefix:
    - E2E now passing, current title has `[E2E FAILING]` → strip the prefix per [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md).

package/dist/plugin/skills/do/resolve-conflicts.md

@@ -28,8 +28,8 @@ Run the rebase from [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before
 
 - **Clean replay** — a behind-only branch (and any rebase that hits no conflicts) replays without intervention. Proceed to Step 3.
 - **Conflicts** — handle per [`autoResolveConflicts`](../muggle-preferences/preference-gates/autoResolveConflicts.md):
-  - default `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub, or opts into `autoResolveConflicts=always`.
-  - `always` → resolve behind the verify-or-rollback gate in [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md).
+  - `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub.
+  - `always` → resolve via [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md); Steps 3 and 5 below are this mode's instance of the [`../_shared/verify-or-rollback-gate.md`](../_shared/verify-or-rollback-gate.md).
 
 ### Step 3 — Verify the resolution
 
@@ -37,13 +37,7 @@ Build (typecheck + lint on the changed surface) + unit suite must pass. Run E2E
 
 ### Step 4 — Force-push + respawn
 
-Push with `--force-with-lease` (the rebase rewrote history). Append the new SHA to `last_seen.pushed_shas`; increment `last_seen.conflict_resolve_attempts[rebase_sha]`. Respawn the watcher as the last action:
-
-```
-/loop 1m /muggle:muggle-pr-followup <slug> <n>
-```
-
-The watcher cancelled its own cron when it dispatched this cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Step 5b), so this restart is the single live watcher. Its next tick re-checks the branch against its base on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
+Push with `--force-with-lease` (the rebase rewrote history). Append the new SHA to `last_seen.pushed_shas`; increment `last_seen.conflict_resolve_attempts[rebase_sha]` — both whole-file rewrites (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md), never the Edit tool. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md). Its next tick re-checks the branch against its base on the new head — the rebase is its own verify loop, bounded by the per-SHA attempt budget.
 
 ### Step 5 — Escalate (can't resolve / budget spent)
 
@@ -51,7 +45,7 @@ When `autoResolveConflicts=never`, the resolution failed verification, or `confl
 
 1. Add `rebase_sha` to `last_seen.conflict_escalated_shas` so the watcher does not re-dispatch this SHA.
 2. Emit one terminal escalation naming the PR and the conflicting files (or the failing verification, for a behind-only rebase that didn't verify).
-3. Respawn the watcher (last action) — it keeps polling for the user's manual resolution or any new reviews.
+3. Respawn the watcher per [`respawn-watcher.md`](respawn-watcher.md) — it keeps polling for the user's manual resolution or any new reviews.
 
 ### Step 6 — Telemetry
 
@@ -61,4 +55,4 @@ Emit one `muggle-do:cycle` event ([`../_shared/telemetry-events/muggle-do-cycle.
 
 - Max 2 rebase attempts per SHA; then escalate rather than churn.
 - Never push an unverified rebase — verify-or-rollback always.
-- The default `autoResolveConflicts=never` escalates to the user rather than guessing a conflict resolution. Auto-resolution of conflicts is strictly opt-in; a clean behind-only rebase needs no opt-in.
+- Resolve `autoResolveConflicts` from the configured preference (per the gate contract — don't assume a default): `always` resolves conflicts behind the verify-or-rollback gate, `never` escalates to the user. A clean behind-only rebase needs neither.