@muggleai/works 5.4.2 → 5.5.0

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.2",
+  "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.2",
+  "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/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

@@ -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/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 `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

@@ -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
 

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
 
@@ -115,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

@@ -40,7 +40,7 @@ Commit per the `fix(ci): <check> — <what>` convention ([`../_shared/pr-followu
 ### Step 5 — Update state + respawn
 
 - 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: `/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).
+- 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/resolve-conflicts.md

@@ -29,7 +29,7 @@ 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):
   - `never` → abort and escalate per Step 5 (`kind: "rebase-conflict"`). The watcher keeps polling; the user resolves on GitHub.
-  - `always` → resolve behind the verify-or-rollback gate in [`../_shared/resolve-rebase-conflicts.md`](../_shared/resolve-rebase-conflicts.md).
+  - `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]` — 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 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
 

package/dist/plugin/skills/do/respawn-watcher.md

@@ -0,0 +1,27 @@
+# Respawn the watcher
+
+The single, guaranteed watcher restart shared by every watcher-dispatched `/muggle-do` mode — address-reviews, fix-ci, and rebase. The watcher cancels its own cron the moment it dispatches a cycle ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md) Steps 4 / 5 / 5b), so for the duration of the cycle **no cron is armed for this slot**. Respawning is what arms the next one. This is a runtime dispatch of the watcher's slash command, not a doc dependency on it — allowed per the one-way rule in [`../CLAUDE.md`](../CLAUDE.md).
+
+## The guarantee
+
+Respawn is the **last action on every exit path that leaves the PR open** — the happy path *and* every escalation, early-exit, or abort. Since the dispatch already cancelled the cron, any open-PR exit that skips respawn leaves the slot with no cron and no next tick: the poller stops silently and stays stopped until a session restart or a reconcile sweep re-arms it. That silent stop is the exact failure this file exists to prevent, so treat "did I respawn on this branch?" as a checklist item on every exit, not only the success case.
+
+The one exception is a **terminal** PR (merged or closed): a terminal PR needs no watcher, so the terminal branch finalizes instead of respawning.
+
+## Procedure
+
+Run as the final action of the turn:
+
+1. **Refresh PR state** — `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).
+2. **If merged or closed** → write `result.md` per [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#resultmd) and **do not respawn**. The PR is terminal; the watcher's job is done.
+3. **Otherwise** → dispatch, verbatim, as the turn's last action:
+
+   ```
+   /loop 1m /muggle:muggle-pr-followup <slug> <n>
+   ```
+
+   Exactly one cron results — the dispatch already cancelled the prior one, so this is never a duplicate. The next tick self-records the new cron id ([`../muggle-pr-followup/record-cron-id.md`](../muggle-pr-followup/record-cron-id.md)).
+
+## Recovery net
+
+This helper guarantees respawn on the paths that reach it, but a cycle that crashes or errors out *before* its exit path can still drop the respawn. [`../muggle-pr-followup/reconcile.md`](../muggle-pr-followup/reconcile.md) is the backstop: it re-arms any open slot whose watcher went silent (no tick within the staleness window), recovering a dropped respawn on the next sweep.

package/dist/plugin/skills/muggle-pr-followup/CLAUDE.md

@@ -7,10 +7,12 @@ This folder holds the watcher loop that drives one PR toward merge-ready. The wa
 - [`SKILL.md`](SKILL.md) — public entry. Routing between bootstrap (URL input), tick (slug + PR number), and auto-track (no args). Read first.
 - [`auto-track.md`](auto-track.md) — the no-args procedure: discovers PRs pushed this session (any repo) and seeds one poll-only watcher each. Seeds no E2E context — the watcher only watches.
 - [`bootstrap.md`](bootstrap.md) — the bootstrap procedure (resolves the validation context once when the PR has a testable surface — else seeds poll-only like auto-track — then dispatches the first watcher).
-- [`contract.md`](contract.md) — the watcher per-tick procedure (poll → dispatch → exit).
+- [`contract.md`](contract.md) — the watcher per-tick procedure (poll → dispatch → exit; on a human-blocked PR it reminds the owner each tick at the normal `1m` cadence, resuming evaluation on external change).
+- [`blocked-tick.md`](blocked-tick.md) — the conditional blocked-path detail: fingerprint, flag-and-remind (Step 7), and remind-or-resume (Step 2.5), all at the normal `1m` cadence. Referenced by `contract.md`; runs only while `last_seen.blocked` is set.
 - [`finalize.md`](finalize.md) — shared termination sequence for a terminal PR (mark terminal, `result.md`, log/telemetry, unschedule cron, post-merge cleanup handoff). Called by `contract.md` and `reconcile.md`.
-- [`cancel-cron.md`](cancel-cron.md) — the find-and-delete that stops this watcher's cron, with the tool-call-not-shell guard. Referenced by `contract.md` and `finalize.md`.
-- [`reconcile.md`](reconcile.md) — sweep that finalizes slots whose PR went terminal while polling lapsed; runs at the top of auto-track and on demand.
+- [`cancel-cron.md`](cancel-cron.md) — stops this watcher's cron, recorded-id-first (survives `CronList` going blind) with a `CronList`-match fallback, plus the tool-call-not-shell guard. Referenced by `contract.md` and `finalize.md`.
+- [`record-cron-id.md`](record-cron-id.md) — the per-tick self-record that keeps this slot's cron id in `cron.json` deletable after a compaction blinds `CronList`. Referenced by `contract.md` Step 0.
+- [`reconcile.md`](reconcile.md) — sweep that finalizes slots whose PR went terminal while polling lapsed, deletes orphaned crons, and re-arms open slots whose watcher stopped silently (dropped respawn); runs at the top of auto-track and on demand.
 - [`state-schemas.md`](state-schemas.md) — canonical JSON shapes of session state files.
 - [`output-templates.md`](output-templates.md) — TOC of message templates; per-group files in `output-templates/`.
 

package/dist/plugin/skills/muggle-pr-followup/SKILL.md

@@ -14,6 +14,10 @@ A watcher that babysits one open PR toward **merge-ready** — review threads ad
 
 **Per-PR isolation.** One watcher per PR. Multi-PR work runs N independent watchers.
 
+**Active reminders when blocked pending a human.** When a PR can't progress without the user — an escalated rebase/CI budget spent, or an ambiguous review awaiting direction — the watcher keeps its `1m` poll and turns each blocked tick into a **one-line reminder**: the pending act plus a reference back to the decision context, nudging the owner every poll until they act ([`contract.md`](contract.md) Steps 2.5, 7). The block reminds but never stops or slows: each tick stays cheap (a fingerprint check, one line out), and the block clears the instant a push, review, or CI/deploy state moves.
+
+**Cron lifecycle.** Each tick records its `/loop` cron id to `cron.json` while `CronList` can still see it ([`record-cron-id.md`](record-cron-id.md)), so teardown can delete the cron by id after a session continue / compaction blinds `CronList` to it. Reconcile ([`reconcile.md`](reconcile.md)) sweeps crons whose PR is terminal or whose slot is gone, and re-arms an open slot whose watcher stopped silently.
+
 ## Routing
 
 The skill recognizes its mode by inspecting `$ARGUMENTS` and falling back to on-disk state. It never runs procedure inline — it identifies the mode and routes to the appropriate procedure file.
@@ -29,7 +33,7 @@ The skill recognizes its mode by inspecting `$ARGUMENTS` and falling back to on-
 | `help` / `?` | — | **help:** list active loops per [`output-templates/help.md`](output-templates/help.md) |
 | `reconcile` / `sweep` (optional `<slug>`) | — | **reconcile** → [`reconcile.md`](reconcile.md) |
 
-Auto-track runs **reconcile** first, so a no-arg invocation also finalizes any slot whose PR merged or closed while its watcher was down (expired cron, ended session). Reconcile never re-arms a watcher.
+Auto-track runs **reconcile** first, so a no-arg invocation also finalizes any slot whose PR merged or closed while its watcher was down (expired cron, ended session) and re-arms any open slot whose watcher stopped silently (a dropped respawn). Reconcile recovers a watcher that was already running; it never seeds a first watcher for a PR — that is auto-track's / bootstrap's job.
 
 Bootstrap accepts three optional trailing flags:
 

package/dist/plugin/skills/muggle-pr-followup/auto-track.md

@@ -51,7 +51,7 @@ For each PR URL in the track list, run the [`bootstrap.md`](bootstrap.md) proced
 - **Existing slot → skip silently** (never the slot-conflict abort); add it to the *skipped* list.
 - **`caller = "auto-track"`** in the bootstrap telemetry event.
 
-Everything else is unchanged: URL parse, metadata + terminal-PR abort, slug, `lastBodyReviewId` 0 (line-comment threads are picked up live from thread state; body-only reviews from id 0), and the `prs.json`/`last_seen.json`/`state.md` writes minus the pre-flight block.
+Everything else is unchanged: URL parse, metadata + terminal-PR abort, slug, `lastBodyReviewId` 0 (line-comment threads are picked up live from thread state; body-only reviews from id 0), and the `prs.json`/`last_seen.json`/`cron.json`/`state.md` writes minus the pre-flight block.
 
 ### Step 5 — Print the summary