@muggleai/works 5.4.2 → 5.5.0

package/dist/plugin/skills/muggle-pr-followup/blocked-tick.md

@@ -0,0 +1,38 @@
+# Blocked-tick procedure
+
+The watcher's conditional path for a PR **blocked pending a human** — a durable block only the user can clear (an escalated rebase or CI budget spent, or an ambiguous review awaiting direction). Entered from [`contract.md`](contract.md) Step 7 (flag), then driven each subsequent tick by Step 2.5 (remind-or-resume). None of this runs on a normal tick: when `last_seen.blocked` is absent, the watcher skips straight through.
+
+**Governing rule — remind at the normal `1m` cadence, never stop.** The poll stays at `1m` whether or not the PR is blocked — a `1m` tick is cheap (one fingerprint check, one line out) and keeps the owner nudged and an external unblock caught within a minute. The `blocked` state changes no cadence; its only job is (a) the reason-specific one-line reminder each tick and (b) fingerprint-based auto-resume. No cadence swap, no separate `reminded` flag — while `blocked` is set, the watcher reminds every tick by definition.
+
+## The fingerprint
+
+The external state a block is waiting on. Recompute from live state each blocked tick:
+
+- `head_sha` — from the tick's [`contract.md`](contract.md) Step 1 refresh.
+- `latest_review_id` — `max(id)` over submitted reviews per [`../_shared/vcs/github/submitted-reviews.md`](../_shared/vcs/github/submitted-reviews.md) (`0` if none).
+- `ci_digest` — the CI rollup digest for `head_sha` per [`../_shared/vcs/github/pr-checks.md`](../_shared/vcs/github/pr-checks.md): the bucket plus each check's name and conclusion, sorted into one stable string.
+
+Any component moving means the block may have cleared — a new push (`head_sha`, which also clears the per-SHA escalation sets), a new review (`latest_review_id`), or a CI/deploy state change (`ci_digest`, which is how an external staging deploy is caught).
+
+## Flag the block (from Step 7)
+
+When an idle tick is a durable human-block and `last_seen.blocked` is not already set:
+
+1. Increment `last_seen.idle_tick_count`.
+2. Write `last_seen.blocked = { reason, since: <now>, fingerprint }` (reuse the `latest_review_id` / `ci_digest` already fetched this tick).
+3. **Remind the owner** — emit the one-line reminder per [`output-templates/blocked-reminder.md`](output-templates/blocked-reminder.md): the pending act plus a reference back to the decision context.
+4. Append a `blocked reason=<reason>` line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md); emit a `tick` event with `idle: true`, `blocked: true`, and the same other fields as a transient idle. Exit. The `1m` cron is unchanged — no swap.
+
+## Remind or resume (the Step 2.5 gate)
+
+Every subsequent tick while `last_seen.blocked` is present: recompute the fingerprint and compare to `last_seen.blocked.fingerprint`.
+
+- **Unchanged** → still blocked. Re-emit the one-line reminder per [`output-templates/blocked-reminder.md`](output-templates/blocked-reminder.md). Increment `last_seen.idle_tick_count`, append a `blocked reason=<reason>` line to `followup.log`, emit a `tick` event with `idle: true`, `blocked: true`. Exit. The `1m` cron is unchanged.
+- **Changed** → clear `last_seen.blocked` and **fall through to [`contract.md`](contract.md) Step 3** to re-evaluate against the moved state this same tick. The cron is already `1m`, so no swap is needed: if Step 3–6 dispatches, that cancels the `1m` cron and `/muggle-do` respawns `1m` (normal single-thread); if it idles transient, the `1m` cron is already correct; if it idles back into the block, Step 7 re-flags.
+
+## Invariants
+
+- Cadence is `1m` whether blocked or active — the block never changes the poll interval. There is no cadence swap, so a blocked slot is never left cron-less by one.
+- The poll never stops — a blocked tick keeps firing and reminding; only a terminal PR or an explicit teardown removes the cron.
+- Every blocked tick emits exactly one owner reminder (implied by `blocked: true`, no separate flag) and no PR-side post.
+- The block clears the instant any fingerprint component moves; an external unblock is caught within one `1m` tick.

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

@@ -71,7 +71,9 @@ Write under `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 **`prs.json`** — see [`state-schemas.md`](state-schemas.md#prsjson). One entry, `state` = `"open"`, `head_sha` from Step 2's `headRefOid`.
 
-**`last_seen.json`** — see [`state-schemas.md`](state-schemas.md#last_seenjson). One key (`"<owner>/<repo>#<n>"`), `lastBodyReviewId` from Step 6, `last_pushed_sha: null`, `idle_tick_count: 0`, `cycles_completed: 0`, `escalated_review_ids: []`, `pushed_shas: []`.
+**`last_seen.json`** — see [`state-schemas.md`](state-schemas.md#last_seenjson). One key (`"<owner>/<repo>#<n>"`), `lastBodyReviewId` from Step 6, `last_pushed_sha: null`, `idle_tick_count: 0`, `cycles_completed: 0`, `escalated_review_ids: []`, `pushed_shas: []`. Omit `blocked` — the watcher starts unblocked.
+
+**`cron.json`** — see [`state-schemas.md`](state-schemas.md#cronjson). `cron_id: null` (Step 8 dispatches `/loop` as the last action, so the id isn't observable yet — the first tick self-records it per [`record-cron-id.md`](record-cron-id.md)), `command: "/muggle:muggle-pr-followup <slug> <n>"`, `interval: "1m"`, `recorded_at: <now>`.
 
 **`state.md`** — see [`state-schemas.md`](state-schemas.md#statemd). `Bootstrapped from URL: yes`. Cache the loop-user login. If Step 6.5 resolved a validation context, append the `## Pre-flight answers` block with its fields, per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields). If it seeded poll-only, write **no** such block — a missing block is a clean E2E skip.
 

package/dist/plugin/skills/muggle-pr-followup/cancel-cron.md

@@ -1,11 +1,12 @@
 # Cancel the watcher's cron
 
-The find-and-delete every tick uses to stop its own loop: the stale-fire guard and terminal unschedule ([`finalize.md`](finalize.md) Step 4), and each single-thread "stop this watcher" before a `/muggle-do` dispatch ([`contract.md`](contract.md) Steps 4–6).
+Deletes this slot's watcher cron, and nothing more — the caller owns whatever comes next (respawn or terminal teardown). Used by the stale-fire guard and terminal unschedule ([`finalize.md`](finalize.md) Step 4) and each single-thread "stop this watcher" before a `/muggle-do` dispatch ([`contract.md`](contract.md) Steps 4–6).
 
 > **`CronList` and `CronDelete` are Claude Code tool calls, not shell commands.** Invoke them directly through the tool system. Never wrap them in a Bash/shell call: `bash -c "CronDelete …"` fails with "command not found", which a `2>/dev/null` on the line swallows, so the delete silently no-ops and the per-minute cron keeps firing — every later tick hits the stale-fire guard and re-fires until the 7-day expiry.
 
-1. Call the `CronList` tool.
-2. Find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` — the exact two-arg match for this slot's PR.
-3. Call the `CronDelete` tool with that job's id.
+Two lookups, recorded-id first so the delete still works when `CronList` has gone blind to the cron (survived a session continue / compaction — see [`state-schemas.md`](state-schemas.md#cronjson)):
 
-No-op when none matches — a manually-run tick, or a cron that already expired.
+1. **By recorded id.** Read `cron.json` ([`state-schemas.md`](state-schemas.md#cronjson)). If `cron_id` is non-null, call `CronDelete` with it. This is the only handle that survives `CronList` blindness.
+2. **By `CronList` match (fallback).** Call `CronList`, find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` — the exact two-arg match for this slot's PR — and `CronDelete` its id. This catches a stale recorded id (a since-respawned cron whose new id no tick has recorded yet) and the case where `cron.json` is absent.
+
+Both lookups are no-ops when nothing matches — a manually-run tick, or a cron that already expired. Deleting an already-gone id is harmless. Do **not** delete `cron.json` itself here; a terminal slot keeps it as a record, and reconcile ([`reconcile.md`](reconcile.md)) may still read it to sweep a straggler.

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

@@ -29,10 +29,12 @@ Every `increment`/`reset` this procedure applies to `last_seen.json`, and the `p
 
 ## Procedure
 
-### Step 0 — Stale-fire guard
+### Step 0 — Stale-fire guard, then record this cron's id
 
 If `prs.json[0].state` on disk is already `merged` or `closed`, this slot was finalized by a prior tick and this is a stale (queued) fire — per-minute cron fires enqueued while the session was busy still drain after the cron is cancelled. Defensively cancel any lingering cron for this slug per [`cancel-cron.md`](cancel-cron.md) (no-op if none), append a `stale-tick` line to `followup.log`, and exit. Do not re-fetch or re-finalize.
 
+Otherwise, self-record this watcher's cron id per [`record-cron-id.md`](record-cron-id.md) before proceeding. Recording every tick — while `CronList` can still see the cron — is what keeps the id a valid `CronDelete` target after a session continue / compaction blinds `CronList` to it, so teardown ([`finalize.md`](finalize.md), [`reconcile.md`](reconcile.md)) can always kill the orphan.
+
 ### Step 1 — Refresh PR state
 
 Per [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response; keep `mergeable` (conflict signal) for Step 5, and run the recipe's `compare` call to capture `behind_by` (out-of-date signal) for Step 5.
@@ -52,6 +54,12 @@ If `state` is `MERGED` or `CLOSED`:
 3. Exit. The watcher has unscheduled itself; no future ticks fire for this PR.
 
 
+### Step 2.5 — Blocked-tick gate
+
+Only when `last_seen.blocked` is present (the watcher is awaiting the owner on a durable human-block, flagged in Step 7). When absent, skip straight to Step 3.
+
+Run the remind-or-resume gate per [`blocked-tick.md`](blocked-tick.md): recompute the fingerprint, re-emit the one-line owner reminder and stay blocked while it holds, or clear the block and fall through to Step 3 the moment it moves. While blocked the watcher keeps the normal `1m` cadence and reminds the owner each tick — the block reminds rather than backs off, and never changes the poll interval.
+
 ### Step 3 — Compute the actionable set from live thread state
 
 The watcher's dispatch trigger is **derived from current provider state**, not a stored review-id cursor — see the [thread-state baseline design](../../../../muggle-ai-brain/architecture/2026-06-06-pr-followup-thread-state-baseline-design.md). Resolve the provider per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md), then:
@@ -125,10 +133,20 @@ Fetch the CI rollup for `prs.json[0].head_sha`, provider resolved as in Step 3
   5. Exit. The dev cycle owns the PR; its respawn restarts the watcher, whose next tick re-checks CI on the new head SHA — CI itself is the verify loop.
 - **One or more red, but `ci_fix_attempts[head_sha] >= 3` or `head_sha` ∈ `ci_escalated_shas`** → idle. The fix budget is spent; `/muggle-do`'s fix-ci stage already recorded the escalation. The watcher does not re-dispatch.
 
-### Step 7 — Idle
+### Step 7 — Idle (remind when blocked pending a human)
+
+Any idle branch (Steps 4–6 that did not dispatch). First classify **why** this tick idled. It is **blocked pending a human** when the head is under a durable block that only the user can clear:
+
+- `head_sha` ∈ `conflict_escalated_shas` — a rebase `/muggle-do` gave up on (a semantic conflict, or `autoResolveConflicts=never`), reason `conflict_escalated`; or
+- `head_sha` ∈ `ci_escalated_shas` — CI the fix-ci stage gave up on, reason `ci_escalated`; or
+- `last_seen.escalated_review_ids` is non-empty with the actionable set empty — an ambiguous review awaiting the user's direction, reason `reviews_escalated`.
+
+Everything else that idles is **transient** — green and waiting for the next review, CI still pending, or `mergeable == UNKNOWN` — and must keep the responsive `1m` cadence; those turn a state on their own and the watcher should catch it promptly.
+
+**Transient idle** (no durable block): unchanged — increment `last_seen.idle_tick_count`, append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md), emit a `tick` event with `idle: true`, `blocked: false`, `actionable_threads: 0`, `dispatched_review_ids: []`, `rebase_needed: <bool>`, `dispatched_rebase: false`, `checks_red: <count or 0>`, `dispatched_ci_fix: false`. Exit. The next tick fires in 1 min via `/loop`.
 
-Any idle branch (Steps 4–6 that did not dispatch): increment `last_seen.idle_tick_count`, append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md), emit a `tick` event with `idle: true`, `actionable_threads: 0`, `dispatched_review_ids: []`, `rebase_needed: <bool>`, `dispatched_rebase: false`, `checks_red: <count or 0>`, `dispatched_ci_fix: false`. Exit. The next tick fires in 1 min via `/loop`.
+**Blocked pending a human** (a durable block, and `last_seen.blocked` not already set): enter the blocked path per [`blocked-tick.md`](blocked-tick.md) — flag `last_seen.blocked` and emit the one-line owner reminder (the watcher reminds each tick at the normal `1m` cadence rather than backing off). From the next tick on, the Step 2.5 gate carries the block. Exit.
 
 ## Output
 
-No console output beyond the turn preamble and (if Step 5 fires) the `/muggle-do` dispatch. The watcher is invisible to the reviewer.
+The watcher stays invisible to the **GitHub reviewer** — it never posts to the PR from a tick. To the **loop owner** in the session it emits: the turn preamble, the one-line blocked reminder while awaiting the owner (Steps 2.5 / 7), and (when a dispatch fires) the `/muggle-do` directive. Nothing else.

package/dist/plugin/skills/muggle-pr-followup/output-templates/blocked-reminder.md

@@ -0,0 +1,30 @@
+# Blocked reminder
+
+The watcher's one-line nudge to the loop owner, emitted every tick a PR sits blocked pending a human ([`../contract.md`](../contract.md) Steps 2.5 / 7). It goes to the **session** — the owner running the loop — never to the PR, so it never notifies the GitHub reviewer. Keep it to **one line**: the pending act plus a reference to trace back to the decision context.
+
+## Shape
+
+```
+⏳ <owner>/<repo>#<n> awaiting you (<duration>): <pending act>. → <reference>
+```
+
+- `<duration>` — how long the block has stood, from `last_seen.blocked.since` (e.g. `2h`, `1d`).
+- `<pending act>` — the one thing the owner must do, keyed by `reason`.
+- `<reference>` — where to trace the decision back to: the review, the PR checks, or the blocked SHA.
+
+## By reason
+
+- **`reviews_escalated`** — an ambiguous review awaits your direction:
+  ```
+  ⏳ acme/widget#142 awaiting you (2h): pick a direction on ambiguous review #<id> from <login>. → reply on the review or tell me here: <review-url>
+  ```
+- **`conflict_escalated`** — a rebase the loop gave up on:
+  ```
+  ⏳ acme/widget#142 awaiting you (2h): resolve the rebase conflict on <short-sha> (autoResolveConflicts=never), then push — or set the pref to always. → <pr-url>
+  ```
+- **`ci_escalated`** — the CI fix budget is spent:
+  ```
+  ⏳ acme/widget#142 awaiting you (2h): the failing checks on <short-sha> need your call — fix and push, or advise here. → <pr-url>/checks
+  ```
+
+The reminder repeats every blocked tick (at the normal `1m` cadence) until the owner acts; the watcher stops it the moment the fingerprint moves (a push, a new review, or a CI/deploy change).

package/dist/plugin/skills/muggle-pr-followup/output-templates/watcher-log.md

@@ -1,6 +1,6 @@
 # Watcher tick log lines
 
-The watcher does **not** print to the user during normal operation. It only appends to `followup.log`. All user-facing escalations come from `/muggle-do`.
+The watcher only appends to `followup.log` during normal operation; the one visible exception is the one-line owner reminder on a blocked tick ([`blocked-reminder.md`](blocked-reminder.md)). All user-facing escalations come from `/muggle-do`.
 
 ## Idle tick
 
@@ -14,6 +14,16 @@ The watcher does **not** print to the user during normal operation. It only appe
 <ISO-8601> tick pr=<n> threads=<count> dispatched=<id1>,<id2>,...
 ```
 
+## Blocked tick
+
+The tick idled on a durable human-block ([`../contract.md`](../contract.md) Step 7) and emitted the one-line owner reminder ([`blocked-reminder.md`](blocked-reminder.md)). One per tick for as long as the block stands, at the normal `1m` cadence:
+
+```
+<ISO-8601> tick pr=<n> blocked reason=<conflict_escalated|ci_escalated|reviews_escalated>
+```
+
+When the fingerprint moves the block clears and the tick logs a normal idle or dispatching line — there is no separate unblock line.
+
 ## Terminal tick
 
 ```

package/dist/plugin/skills/muggle-pr-followup/output-templates.md

@@ -7,7 +7,8 @@ All user-facing message text used by the watcher, bootstrap, and `/muggle-do` in
 | Group | Use case |
 | :---- | :------- |
 | [`bootstrap`](output-templates/bootstrap.md) | Bootstrap success summary + all bootstrap aborts. |
-| [`watcher-log`](output-templates/watcher-log.md) | The three `followup.log` line shapes (idle, dispatching, terminal). |
+| [`watcher-log`](output-templates/watcher-log.md) | The `followup.log` line shapes (idle, dispatching, blocked, terminal). |
+| [`blocked-reminder`](output-templates/blocked-reminder.md) | The watcher's one-line owner reminder while a PR is blocked pending a human. |
 | [`escalation`](output-templates/escalation.md) | `/muggle-do` terminal escalation messages (ambiguous, design-adjustment). |
 | [`inline-reply`](output-templates/inline-reply.md) | Per-comment inline reply + top-level fallback for body-only reviews. |
 | [`resolve-reminder`](output-templates/resolve-reminder.md) | Top-level PR comment for the resolve-reminder stage. |

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

@@ -1,6 +1,6 @@
 # Reconcile Procedure
 
-The procedure for the **reconcile mode** of `muggle-pr-followup` — a sweep that finalizes session slots whose PR went terminal while polling was lapsed. Routing is in [`SKILL.md`](SKILL.md#routing).
+The procedure for the **reconcile mode** of `muggle-pr-followup` — a sweep that finalizes session slots whose PR went terminal while polling was lapsed, and re-arms open slots whose watcher stopped silently (a dropped respawn). Routing is in [`SKILL.md`](SKILL.md#routing).
 
 Termination is otherwise tick-driven ([`contract.md`](contract.md) Step 2): a slot finalizes only when a tick fires and observes `MERGED` / `CLOSED`. If the tick stream stops first — the recurring `/loop` cron auto-expires after 7 days, the session ends, or the machine is off when the PR merges — no tick catches the transition, and the slot is left un-finalized: no `result.md`, no post-merge cleanup, and a surviving cron would keep polling a dead PR. Reconcile is the catch-up.
 
@@ -20,14 +20,37 @@ For each candidate, fetch the PR per [`../_shared/vcs/github/pr-metadata.md`](..
 
 ### Step 3 — Finalize the terminal ones
 
-For each candidate whose live `state` is `MERGED` or `CLOSED`, run [`finalize.md`](finalize.md). `finalize.md` dispatches nothing, so a backfilled merge gets no post-merge cleanup — its branch is typically long gone, and the `autoCleanup` gate governs if the user runs cleanup later. Slots still `open` are left untouched — reconcile finalizes, it does not re-arm a watcher (re-arming an open PR is [`auto-track.md`](auto-track.md)'s job).
+For each candidate whose live `state` is `MERGED` or `CLOSED`, run [`finalize.md`](finalize.md) — which unschedules the cron recorded-id-first per [`cancel-cron.md`](cancel-cron.md), killing it even when `CronList` has gone blind. `finalize.md` dispatches nothing, so a backfilled merge gets no post-merge cleanup — its branch is typically long gone, and the `autoCleanup` gate governs if the user runs cleanup later. Slots still `open` are carried to Step 3.6, which re-arms any whose watcher went silent.
+
+### Step 3.5 — Sweep orphaned crons
+
+Step 3 kills the cron of every slot it finalized this run. This step catches the crons **finalize can't reach through a slot** — a watcher cron whose session slot was deleted out from under it, or one already-finalized (`result.md` present, skipped in Step 1) whose cron outlived the finalize. Both keep polling a dead or absent PR until the 7-day `/loop` expiry.
+
+Call `CronList`. For every job whose command ends with `/muggle:muggle-pr-followup <slug> <n>`:
+
+- **No session slot for `<slug>`** (`~/.muggle-ai/muggle-do/sessions/<slug>/` is gone) → `CronDelete` it. The slot it belonged to was removed; the cron is a pure orphan.
+- **Slot present and terminal** (`result.md` exists, or `prs.json[0].state` is `merged`/`closed`) → `CronDelete` it. A straggler the finalize missed.
+- **Slot present and open** → leave it. A live watcher.
+
+This reaches only crons `CronList` still enumerates. A cron that both survived a compaction (invisible to `CronList`) **and** lost its slot (recorded id gone with it) is beyond either mechanism — see the residual note below.
+
+### Step 3.6 — Re-arm a silently-stopped open watcher
+
+The recovery net for a **dropped respawn**: a `/muggle-do` cycle cancels the watcher's cron when it dispatches ([`contract.md`](contract.md) Steps 4 / 5 / 5b) and is responsible for respawning it when the cycle ends, but a cycle that crashes or errors out before it respawns can leave an open slot with no cron and no next tick — the poller stops silently. This step re-arms it.
+
+For each candidate still `open` after Step 3, check when its watcher last ticked — the newest ISO-8601 line in `followup.log` (or `cron.json.recorded_at` if the log is empty). If that is **older than 15 minutes** (comfortably beyond the `1m` cadence, so a live cron would have logged many times inside the window), the poller is gone → re-arm:
+
+- `CronCreate` a recurring cron (call the **tool**, never a shell) with `cron: "* * * * *"` and prompt `/muggle:muggle-pr-followup <slug> <n>`, then record its id and `interval: "1m"` to `cron.json` (whole-file rewrite per [`state-schemas.md`](state-schemas.md#cronjson)). Append a `re-armed (silent watcher)` line to the slot's `followup.log`.
+
+A fresh log line (within the window) means the cron is alive — even one `CronList` has gone blind to — so this step leaves it untouched; re-arming can never double an already-live poller. This recovers only a slot that was **already being watched**; a PR that never had a watcher is seeded by [`auto-track.md`](auto-track.md) / bootstrap, not here.
 
 ### Step 4 — Report
 
-One line: slots scanned, finalized (with final state each), and left open. Silent only when zero slots exist.
+One line: slots scanned, finalized (with final state each), left open, re-armed (silently-stopped watchers recovered), and orphan crons swept. Silent only when zero slots exist and nothing was swept.
 
 ## Invariants
 
-- **Idempotent.** A slot with `result.md` is never re-finalized; once everything terminal is swept, re-running is a no-op.
-- **Finalize-only.** Reconcile never seeds, re-arms, or dispatches a watcher. Open slots pass through untouched.
+- **Idempotent.** A slot with `result.md` is never re-finalized; a still-ticking open slot is never re-armed; once everything terminal is swept and every open watcher is live, re-running is a no-op.
+- **Recover, don't seed.** Reconcile finalizes terminal slots, sweeps orphan crons, and re-arms an open slot whose watcher went silent (a dropped respawn — Step 3.6). It never arms a PR that was never watched — seeding a first watcher is [`auto-track.md`](auto-track.md)'s / bootstrap's job.
 - **Per-slot isolation.** One slot's `gh` failure never blocks finalizing the others.
+- **Residual orphan.** A cron that survived a compaction (blind to `CronList`) whose slot was also deleted has no on-disk id left to `CronDelete` and no `CronList` entry to match — only a session restart clears it. Recording the id durably while the slot lives ([`record-cron-id.md`](record-cron-id.md)) shrinks this window to slots removed before their first tick.

package/dist/plugin/skills/muggle-pr-followup/record-cron-id.md

@@ -0,0 +1,12 @@
+# Record the watcher's cron id
+
+The self-record every tick runs so this slot's cron stays deletable after `CronList` goes blind to it. `CronList` stops enumerating a `/loop` cron once its session is continued or compacted, but the cron keeps firing; a cron id captured to `cron.json` **while the cron was still visible** remains a valid `CronDelete` target for teardown ([`cancel-cron.md`](cancel-cron.md), [`finalize.md`](finalize.md), [`reconcile.md`](reconcile.md)). Recording early — every tick, starting with the first — is what makes the id durable.
+
+> **`CronList` is a Claude Code tool call, not a shell command.** Invoke it through the tool system. Never wrap it in Bash.
+
+1. Call the `CronList` tool.
+2. Find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` — the exact two-arg match for this slot's PR.
+3. If found and its id differs from `cron.json.cron_id`: rewrite `cron.json` (whole-file Write per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md)) with the observed `cron_id`, the current `interval`, and a fresh `recorded_at`.
+4. If `CronList` returns nothing (already blind) and `cron.json` holds a non-null `cron_id`: **leave it** — the previously-recorded id is the only handle left, so never overwrite it with `null`.
+
+Skip in the stale-fire path ([`contract.md`](contract.md) Step 0): a stale slot is being torn down, not re-recorded.

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.
@@ -46,7 +63,16 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
     "ci_fix_attempts": { "<sha>": <int> },
     "ci_escalated_shas": ["<sha>", ...],
     "conflict_resolve_attempts": { "<sha>": <int> },
-    "conflict_escalated_shas": ["<sha>", ...]
+    "conflict_escalated_shas": ["<sha>", ...],
+    "blocked": {
+      "reason": "conflict_escalated" | "ci_escalated" | "reviews_escalated",
+      "since": "<ISO-8601>",
+      "fingerprint": {
+        "head_sha": "<sha>",
+        "latest_review_id": <int>,
+        "ci_digest": "<string>"
+      }
+    }
   }
 }
 ```
@@ -61,6 +87,10 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
 - `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.
+- `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` (`head_sha` ∈ `conflict_escalated_shas`), `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.0",
+  "buildId": "run-63-1",
+  "commitSha": "47b7ae51ea3c831a6abbcbe230405cb92486f381",
+  "buildTime": "2026-07-18T02:08:15Z",
   "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.0",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",
@@ -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.9",
     "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": "293f4ca402ab4132946801b9a3a354818e431f4839b1f91f40e0890f4477b3c5",
+      "darwin-x64": "c34f923f7fd3b37e60d2d335d01069e117632113ec0c811c573d219f0109291e",
+      "linux-x64": "d7ce0910043f5b557448dc800bcba8cf86b663df961959603deb6f6451b4904f",
+      "win32-x64": "c376de74e1e3bd34206aa002107b789f47a15972d91a888ae12d0eb5385bbf5f"
     }
   },
   "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.0",
   "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.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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/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 '{}'