@muggleai/works 5.4.2 → 5.5.1

package/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/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/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/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/plugin/skills/do/resolve-conflicts.md

@@ -14,13 +14,13 @@ Rebase a PR's branch onto its base — whether it's merely **behind** (out of da
 
 ## Inputs from disk
 
-From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + branch + `head_sha`), `last_seen.json` (`conflict_resolve_attempts`, `conflict_escalated_shas`, `pushed_shas`), `state.md` (worktree path, validation strategy, base branch).
+From `~/.muggle-ai/muggle-do/sessions/<slug>/`: `prs.json` (PR + branch + `head_sha`), `last_seen.json` (`conflict_resolve_attempts`, `conflict_escalated_keys`, `pushed_shas`), `state.md` (worktree path, validation strategy, base branch).
 
 ## Procedure
 
 ### Step 1 — Re-attach
 
-Materialize the PR branch in its worktree per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) (or use `state.md`'s `worktreePath`). Capture `rebase_sha = prs.json[0].head_sha` and the base branch (`baseRefName` from [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md)).
+Materialize the PR branch in its worktree per [`../_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) (or use `state.md`'s `worktreePath`). Capture `rebase_sha = prs.json[0].head_sha` and the base branch (`baseRefName` from [`../_shared/vcs/github/pr-metadata.md`](../_shared/vcs/github/pr-metadata.md)). Capture the base tip too — `.base_commit.sha` from that recipe's `compare` call — and form `rebase_key = "<rebase_sha>..<base_tip_sha>"`. Both budget fields below are keyed on that pair, matching the watcher's Step 5; writing a bare SHA instead leaves an entry the watcher ignores, and the rebase re-dispatches forever.
 
 ### Step 2 — Rebase onto base (resolve conflicts if any)
 
@@ -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,21 +37,15 @@ 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_key]` — 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)
 
-When `autoResolveConflicts=never`, the resolution failed verification, or `conflict_resolve_attempts[rebase_sha]` has reached 2:
+When `autoResolveConflicts=never`, the resolution failed verification, or `conflict_resolve_attempts[rebase_key]` has reached 2:
 
-1. Add `rebase_sha` to `last_seen.conflict_escalated_shas` so the watcher does not re-dispatch this SHA.
+1. Add `rebase_key` to `last_seen.conflict_escalated_keys` so the watcher does not re-dispatch this head against this base. If the base later moves, the key changes and the branch re-arms on its own — a conflict the user resolved upstream stops being this watcher's dead end.
 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/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/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 on demand, at the top of auto-track, and nudged by a session-start hook.
 - [`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/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,9 @@ 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.
+
+**Reconcile also runs at session start** — a `SessionStart` hook ([`../../hooks/README.md`](../../hooks/README.md)) surfaces the sweep when open slots exist, catching a watcher that died with its session (end, or 7-day `/loop` expiry) before a manual sweep would. See [`reconcile.md`](reconcile.md#triggers).
 
 Bootstrap accepts three optional trailing flags:
 

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

package/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/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/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/plugin/skills/muggle-pr-followup/contract.md

@@ -29,13 +29,15 @@ 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.
+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 both `behind_by` (out-of-date signal) and `.base_commit.sha` — the base branch tip, Step 5's `base_tip_sha`.
 
 ### Step 2 — Termination check
 
@@ -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:
@@ -94,7 +102,11 @@ A merge-ready branch is **current with its base** — neither conflicting nor be
 
 This trigger is **independent of approval and CI state**: an out-of-date branch is rebased whether or not it has been reviewed, approved, or has green checks. The watcher acts on staleness directly — it never waits for an approval to surface it.
 
-If a rebase is due **and** `conflict_resolve_attempts[head_sha] < 2` **and** `head_sha` ∉ `conflict_escalated_shas` → dispatch and exit:
+Rebase dedup is keyed on the **pair** `rebase_key = "<head_sha>..<base_tip_sha>"`, not on the head alone. Whether a branch conflicts is a function of both sides, so a head-only key wedges a PR permanently the first time the base moves: the head cannot change while nobody pushes, so one stale entry suppresses every genuinely new conflict that base movement introduces, forever. Take `base_tip_sha` from the Step 1 compare's `.base_commit.sha` (the base branch tip, which advances when the base does) — **never** `.merge_base_commit.sha`, which does not move when only the base advances and so would never re-arm.
+
+Entries written by an older watcher are bare head SHAs with no `..` — ignore them when reading `conflict_escalated_keys`, which re-arms any slot a head-only key had wedged.
+
+If a rebase is due **and** `conflict_resolve_attempts[rebase_key] < 2` **and** `rebase_key` ∉ `conflict_escalated_keys` → dispatch and exit:
 
   1. Reset `last_seen.idle_tick_count` to 0.
   2. **Stop this watcher (single-thread):** cancel its cron exactly as in Step 4 — `/muggle-do`'s rebase respawns it when the cycle is done.
@@ -106,7 +118,7 @@ If a rebase is due **and** `conflict_resolve_attempts[head_sha] < 2` **and** `he
   4. Append a dispatching line to `followup.log`; emit a `tick` event with `rebase_needed: true`, `dispatched_rebase: true`.
   5. Exit. The dev cycle owns the PR; its respawn restarts the watcher, whose 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.
 
-Otherwise — `behind_by == 0` and not conflicting (`mergeable == UNKNOWN` is fine here: `behind_by` is exact while GitHub is still computing conflict state, so a stale branch still triggers), or budget spent (`conflict_resolve_attempts[head_sha] >= 2` or `head_sha` ∈ `conflict_escalated_shas`) → fall through to CI.
+Otherwise — `behind_by == 0` and not conflicting (`mergeable == UNKNOWN` is fine here: `behind_by` is exact while GitHub is still computing conflict state, so a stale branch still triggers), or budget spent (`conflict_resolve_attempts[rebase_key] >= 2` or `rebase_key` ∈ `conflict_escalated_keys`) → fall through to CI.
 
 ### Step 6 — No actionable feedback, branch current → poll CI for the head SHA
 
@@ -125,10 +137,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:
+
+- `rebase_key` ∈ `conflict_escalated_keys` — a rebase `/muggle-do` gave up on (a semantic conflict, or `autoResolveConflicts=never`), reason `conflict_escalated`. This block clears on its own when the base moves: the new `base_tip_sha` yields a key the set does not contain, and the branch re-arms for a fresh rebase attempt; 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/plugin/skills/muggle-pr-followup/evals/evals.json

@@ -0,0 +1,89 @@
+{
+  "skill_name": "muggle-pr-followup",
+  "notes": "These evals test the TICK DECISION behavior. A real tick needs live GitHub state and the Cron tools, so each prompt hands the model a concrete slot + provider state and asks for the step-by-step plan it would execute; assertions check the plan takes the branch the contract mandates. Run via skill-creator's eval runner — CI does not execute these (ci.yml gates on vitest/check-skill-deps; skill-eval.yml runs gate scenarios sourced from muggle-ai-brain and the routing eval).",
+  "evals": [
+    {
+      "id": 0,
+      "eval_name": "actionable-threads-dispatch-address-reviews",
+      "prompt": "Tick muggle-ai-works-pr500 500. The slot is open. The PR has two unresolved, not-outdated review threads whose newest comments are from a human (no muggle-do:bot marker), CI is fully green, and the branch is level with master. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "computes_actionable_from_live_thread_state", "text": "Plan derives the actionable set from current unresolved-thread state, not from a stored review-id cursor." },
+        { "name": "classifies_by_loop_marker", "text": "Plan decides a thread is actionable by the absence of the muggle-do:bot marker on the newest comment, never by author login." },
+        { "name": "cancels_own_cron_before_dispatch", "text": "Plan cancels this watcher's own cron before dispatching, so no tick overlaps the running cycle." },
+        { "name": "dispatches_address_reviews", "text": "Plan dispatches /muggle-do with an address-reviews directive carrying the PR URL, slug, and owning review ids, then exits." },
+        { "name": "stays_a_dumb_pipe", "text": "Plan does NOT classify reviews, post replies, resolve threads, or escalate — those belong to /muggle-do." }
+      ]
+    },
+    {
+      "id": 1,
+      "eval_name": "reviews-preempt-ci",
+      "prompt": "Tick muggle-ai-works-pr501 501. The slot is open. There is one unresolved human review thread AND two red required checks on the head SHA. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "dispatches_address_reviews_only", "text": "Plan dispatches address-reviews for the review thread." },
+        { "name": "does_not_poll_or_dispatch_ci", "text": "Plan does NOT dispatch fix-ci on this tick — actionable feedback preempts the CI branch entirely." },
+        { "name": "single_dispatch_then_exit", "text": "Plan performs exactly one dispatch and exits rather than handling both concerns in one tick." }
+      ]
+    },
+    {
+      "id": 2,
+      "eval_name": "behind-branch-dispatches-rebase",
+      "prompt": "Tick muggle-ai-works-pr502 502. The slot is open, there are no unresolved review threads, CI is green. GitHub reports mergeStateStatus BLOCKED and mergeable MERGEABLE, and the compare call shows behind_by 4. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "reads_staleness_from_compare", "text": "Plan determines the branch is out of date from behind_by on the compare call (commit ancestry)." },
+        { "name": "does_not_trust_mergeStateStatus", "text": "Plan does NOT conclude the branch is current just because mergeStateStatus reads BLOCKED rather than BEHIND." },
+        { "name": "dispatches_rebase", "text": "Plan dispatches /muggle-do with a rebase directive (PR URL + slug, no review ids, no check names)." },
+        { "name": "keys_dedup_on_head_and_base_pair", "text": "Plan keys the rebase attempt/escalation lookup on the head..base_tip pair, not the head SHA alone." }
+      ]
+    },
+    {
+      "id": 3,
+      "eval_name": "red-ci-within-budget-dispatches-fix-ci",
+      "prompt": "Tick muggle-ai-works-pr503 503. The slot is open, no unresolved review threads, branch is level with its base. Two checks are red on the head SHA. ci_fix_attempts for that SHA is 1 and the SHA is not in ci_escalated_shas. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "checks_attempt_budget", "text": "Plan verifies ci_fix_attempts for the head SHA is under the cap of 3 before dispatching." },
+        { "name": "checks_escalated_set", "text": "Plan verifies the head SHA is not in ci_escalated_shas." },
+        { "name": "dispatches_fix_ci_with_check_names", "text": "Plan dispatches /muggle-do with a fix-ci directive carrying the red check names." },
+        { "name": "cancels_own_cron_before_dispatch", "text": "Plan cancels this watcher's cron before dispatching." }
+      ]
+    },
+    {
+      "id": 4,
+      "eval_name": "red-ci-over-budget-idles",
+      "prompt": "Tick muggle-ai-works-pr504 504. The slot is open, no unresolved review threads, branch is level with its base. Three checks are red on the head SHA, ci_fix_attempts for that SHA is 3, and the SHA is in ci_escalated_shas. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "does_not_dispatch", "text": "Plan does NOT dispatch fix-ci — the budget is spent and the SHA is already escalated." },
+        { "name": "treats_as_durable_block", "text": "Plan classifies this idle as blocked pending a human (reason ci_escalated), not as a transient idle." },
+        { "name": "reminds_owner_at_1m", "text": "Plan emits a one-line owner reminder and keeps the normal 1m cadence — it does not back off, slow down, or stop polling." },
+        { "name": "no_pr_side_post", "text": "Plan does NOT post anything to the PR for a blocked tick; the reminder goes to the loop owner in-session." }
+      ]
+    },
+    {
+      "id": 5,
+      "eval_name": "merged-pr-finalizes-without-respawn",
+      "prompt": "Tick muggle-ai-works-pr505 505. Refreshing the PR shows state MERGED. The slot on disk still says open. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "finalizes_the_slot", "text": "Plan finalizes the slot: marks it terminal, writes result.md, logs, and unschedules this watcher's cron." },
+        { "name": "does_not_respawn", "text": "Plan does NOT respawn or re-arm a watcher — a terminal PR needs none." },
+        { "name": "hands_off_terminal_wrapup", "text": "Plan hands the terminal wrap-up to /muggle-do post-merge cleanup as the turn's last action." },
+        { "name": "unschedules_recorded_id_first", "text": "Plan cancels the cron by the id recorded in cron.json first, falling back to a CronList match — so teardown works even after CronList has gone blind." }
+      ]
+    },
+    {
+      "id": 6,
+      "eval_name": "stale-queued-fire-does-not-refinalize",
+      "prompt": "Tick muggle-ai-works-pr506 506. Reading the slot, prs.json already records state merged and result.md exists — this fire was queued before the cron was cancelled. Walk me through the plan for this tick.",
+      "files": [],
+      "assertions": [
+        { "name": "detects_stale_fire", "text": "Plan recognises this as a stale queued fire from the on-disk terminal state before fetching anything." },
+        { "name": "does_not_refetch_or_refinalize", "text": "Plan does NOT re-fetch the PR, re-write result.md, or re-run the terminal handoff." },
+        { "name": "defensively_cancels_and_logs", "text": "Plan defensively cancels any lingering cron for the slug and appends a stale-tick line to followup.log, then exits." }
+      ]
+    }
+  ]
+}

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