@muggleai/works 5.6.0 → 5.8.0

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

@@ -1,175 +1,191 @@
-# Session State Schemas
-
-Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; `muggle-do` is the current and only caller).
-
-All files are **whole-file atomic writes** — rewrite the entire file each time, never a partial Edit. The mechanism (tool-based, OS-agnostic) and the reason Edit fails on these files live in [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md).
-
-## Legacy location
-
-Before the move to the user's home, slots lived at the repo-relative `.muggle-do/sessions/<slug>/` (one per working tree, still gitignored). Bootstrap's Step 5 migrates a legacy slot to the home-dir location on the next run for that PR; nothing else reads the old path. The state is ephemeral and reconstructible from GitHub, so an un-migrated slot costs only a re-bootstrap, not data.
-
-## `prs.json`
-
-A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)
-
-```json
-[
-  {
-    "repo": "<owner>/<repo>",
-    "provider": "github" | "gitlab",
-    "number": <int>,
-    "url": "https://github.com/<owner>/<repo>/pull/<number>",
-    "head_sha": "<40-char-hex-sha>",
-    "state": "open" | "merged" | "closed"
-  }
-]
-```
-
-- `provider` selects the recipe set (`gh` vs `glab`). Absent ⇒ `github` — existing slots predate the field and stay GitHub.
-- Under GitLab, `number` holds the MR `iid` (per-project, not the global MR id); `head_sha` is unchanged. GitLab's `opened` normalizes to `open`; `merged` and `closed` already align.
-- `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.
-
-```json
-{
-  "<owner>/<repo>#<n>": {
-    "lastBodyReviewId": <int>,
-    "last_pushed_sha": "<sha-or-null>",
-    "idle_tick_count": <int>,
-    "cycles_completed": <int>,
-    "escalated_review_ids": [<int>, ...],
-    "pushed_shas": ["<sha>", ...],
-    "ci_fix_attempts": { "<sha>": <int> },
-    "ci_escalated_shas": ["<sha>", ...],
-    "conflict_resolve_attempts": { "<head-sha>..<base-tip-sha>": <int> },
-    "conflict_escalated_keys": ["<head-sha>..<base-tip-sha>", ...],
-    "blocked": {
-      "reason": "conflict_escalated" | "ci_escalated" | "reviews_escalated",
-      "since": "<ISO-8601>",
-      "fingerprint": {
-        "head_sha": "<sha>",
-        "latest_review_id": <int>,
-        "ci_digest": "<string>"
-      }
-    }
-  }
-}
-```
-
-- `lastBodyReviewId`: narrow watermark for **body-only** reviews (a submitted review carrying no line comments). The watcher dispatches a body-only review only when `id > lastBodyReviewId`. Line-comment threads do **not** use it — they are dispatched from live thread state (unresolved + not outdated + newest comment unmarked by the loop), so there is no cursor that can pin past them. Bootstrap sets it to the highest existing submitted review id with `--forward-only`, else `0`. The cursor keeps its name under GitLab, where it holds the highest note / discussion id.
-- `last_pushed_sha`: most recent SHA `/muggle-do` pushed in this PR's life; `null` until the first push.
-- `idle_tick_count`: incremented each tick whose actionable set is empty. Reset to 0 on any tick that dispatches `/muggle-do`. Diagnostic only — does not gate behavior.
-- `cycles_completed`: incremented each time `/muggle-do` completes an address-reviews invocation (regardless of actionable/ambiguous/mixed).
-- `escalated_review_ids`: review ids classified as ambiguous by `/muggle-do`. The watcher excludes these from the actionable set (both body-only reviews and the threads they own) so the same ambiguous review is never re-dispatched.
-- `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
-- `ci_fix_attempts`: per-SHA count of fix-ci cycles `/muggle-do` has run. The watcher stops dispatching fix-ci for a SHA once its count reaches 3. Keyed by head SHA.
-- `ci_escalated_shas`: head SHAs whose CI the fix-ci stage gave up on (attempts exhausted or only out-of-scope checks). The watcher excludes these from CI dispatch so a hopeless SHA is never re-fixed.
-- `conflict_resolve_attempts`: count of rebase cycles `/muggle-do` has run (behind-only or conflicting — both rebase onto the base). The watcher stops dispatching once a key's count reaches 2. Keyed by `rebase_key` — `"<head_sha>..<base_tip_sha>"`, the head paired with the base branch tip it was measured against.
-- `conflict_escalated_keys`: `rebase_key`s whose rebase `/muggle-do` gave up on (attempts exhausted, or a conflict under `autoResolveConflicts=never`). The watcher excludes these from rebase dispatch so a hopeless pairing is never re-attempted.
-
-Both are keyed on the pair, not the head alone, because whether a branch conflicts depends on both sides. Under a head-only key, a base that moves produces a genuinely new conflict against an unchanged head — and the stale entry suppresses it permanently, because nothing can change the head while the branch sits blocked. Pairing re-arms the budget whenever either side moves. Legacy entries written before this change are bare SHAs with no `..`; readers ignore them, which un-wedges any slot they had blocked.
-
-Unlike these, `ci_fix_attempts` / `ci_escalated_shas` stay keyed on the head SHA alone — a CI result is a function of the head only, so base movement must not re-arm them.
-- `blocked`: present only while the watcher is **awaiting the owner** on a PR that cannot progress without a human ([`contract.md`](contract.md) Step 7). Absent ⇒ the watcher is in its normal dispatch flow. When present, the watcher **keeps the normal `1m` cadence** and each tick is a reminder-or-resume check ([`contract.md`](contract.md) Step 2.5): it re-emits a one-line reminder to the owner, recomputes the `fingerprint`, and clears the block the moment any component moves. Its value is the reason-specific reminder plus fingerprint auto-resume.
-  - `reason`: which durable block is being awaited — `conflict_escalated` (`rebase_key` ∈ `conflict_escalated_keys`), `ci_escalated` (`head_sha` ∈ `ci_escalated_shas`), or `reviews_escalated` (a review sits in `escalated_review_ids` awaiting the user, actionable set empty). Selects the reminder wording; the resume decision is fingerprint-driven, not reason-driven.
-  - `since`: when the block was first flagged — lets the reminder state how long the owner has been the blocker.
-  - `fingerprint`: the external state the block is waiting on. `head_sha` moves on a new push (which also clears the per-SHA escalation sets, keyed by SHA); `latest_review_id` is `max(id)` over submitted reviews and moves when a reviewer submits anything new; `ci_digest` is a stable digest of the head SHA's CI rollup (bucket + each check's name/conclusion, sorted) and moves when a check flips, a rerun lands, or an external check such as a staging deploy posts. Any change clears the block and resumes evaluation.
-
-## `state.md`
-
-Free-form markdown. No required schema beyond a few well-known fields the caller-agnostic code reads:
-
-```markdown
-# Session — <slug>
-
-**PR:** <url>
-**Slug:** <slug>
-**Loop user:** <github-login>          ← cached from `gh api user`
-**Created:** <ISO-8601>
-**Bootstrapped from URL:** <yes | no>
-
-## Pre-flight answers
-
-- Validation: <local-e2e | staging-replay | unit-only | skip>
-- Local URL: <url | N/A>
-- Backend status: <up | down | N/A>
-- Muggle Test project: <name> (<uuid>)
-- Test credentials: <existing | new | skip>
-- Auth status: <ok | re-authed | N/A>
-- Working tree: <path>
-
-...free-form notes added by /muggle-do and bootstrap...
-```
-
-The `## Pre-flight answers` block is the **E2E validation context** consumed by `do/e2e-acceptance.md` Step 0 — seeded by bootstrap (Step 6.5) or by pre-flight's output block. Fields: [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields).
-
-The watcher does **not** read or write `state.md`. Only bootstrap, `/muggle-do`, and the caller's stages touch it.
-
-## `followup.log`
-
-Append-only line-per-tick log. One line per watcher tick, plus one line per `/muggle-do` invocation. Format is loose, but each line starts with an ISO-8601 timestamp:
-
-```
-2026-05-20T12:34:56Z tick pr=154 threads=0 idle
-2026-05-20T12:35:56Z tick pr=154 threads=1 dispatched=4295962800
-2026-05-20T12:36:14Z muggle-do cycle review_ids=[4295962800] outcome=pushed head_sha=abc1234
-```
-
-Used for forensics only — never read back by skills.
-
-## `result.md`
-
-Written exactly once when the PR's watcher exits terminally (PR merged or closed). Free-form markdown summarizing the PR's life under this loop:
-
-```markdown
-# Result — <slug>
-
-**PR:** <url>
-**Final state:** merged | closed
-**Cycles completed:** <int>
-**Pushed SHAs:** <comma-separated list>
-**Escalated review ids:** <comma-separated list or "none">
-
-## Timeline
-
-- <ISO-8601> bootstrap (lastBodyReviewId <id>; line-comment threads state-derived)
-- <ISO-8601> review <id> from <login> — actionable, pushed <sha>
-- <ISO-8601> review <id> from <login> — ambiguous, escalated
-- ...
-- <ISO-8601> PR <merged|closed> — watcher terminal
-```
-
-## Not in the slot
-
-`cycle.json` and `requirements.md` are not seeded or read. `/muggle-do` reads reviews off GitHub each invocation.
-
-## `watch-watermark.env`
-
-The watch loop's comparison floor — plain `KEY=VALUE` lines, one file per slot:
-
-- `REV` — highest submitted-review id already handled
-- `COM` — highest thread-comment id already handled
-- `THREADS` — semicolon-joined ids of threads already known unresolved
-
-Written whole-file by the orchestrating session — seeded at arm time from a post-drain fetch, advanced after every cycle from a post-replies fetch. Read by the watch loop each iteration; the loop never writes it. A stale watermark makes the next reported event the loop's own reply ([`arm-watcher.md`](arm-watcher.md)).
+# Session State Schemas
+
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; `muggle-do` is the current and only caller).
+
+All files are **whole-file atomic writes** — rewrite the entire file each time, never a partial Edit. The mechanism (tool-based, OS-agnostic) and the reason Edit fails on these files live in [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md).
+
+## Legacy location
+
+Before the move to the user's home, slots lived at the repo-relative `.muggle-do/sessions/<slug>/` (one per working tree, still gitignored). Bootstrap's Step 5 migrates a legacy slot to the home-dir location on the next run for that PR; nothing else reads the old path. The state is ephemeral and reconstructible from GitHub, so an un-migrated slot costs only a re-bootstrap, not data.
+
+## `prs.json`
+
+A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)
+
+```json
+[
+  {
+    "repo": "<owner>/<repo>",
+    "provider": "github" | "gitlab",
+    "number": <int>,
+    "url": "https://github.com/<owner>/<repo>/pull/<number>",
+    "head_sha": "<40-char-hex-sha>",
+    "state": "open" | "merged" | "closed"
+  }
+]
+```
+
+- `provider` selects the recipe set (`gh` vs `glab`). Absent ⇒ `github` — existing slots predate the field and stay GitHub.
+- Under GitLab, `number` holds the MR `iid` (per-project, not the global MR id); `head_sha` is unchanged. GitLab's `opened` normalizes to `open`; `merged` and `closed` already align.
+- `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.
+
+```json
+{
+  "<owner>/<repo>#<n>": {
+    "lastBodyReviewId": <int>,
+    "last_pushed_sha": "<sha-or-null>",
+    "idle_tick_count": <int>,
+    "cycles_completed": <int>,
+    "escalated_review_ids": [<int>, ...],
+    "pushed_shas": ["<sha>", ...],
+    "ci_fix_attempts": { "<sha>": <int> },
+    "ci_escalated_shas": ["<sha>", ...],
+    "conflict_resolve_attempts": { "<head-sha>..<base-tip-sha>": <int> },
+    "conflict_escalated_keys": ["<head-sha>..<base-tip-sha>", ...],
+    "blocked": {
+      "reason": "conflict_escalated" | "ci_escalated" | "reviews_escalated",
+      "since": "<ISO-8601>",
+      "fingerprint": {
+        "head_sha": "<sha>",
+        "latest_review_id": <int>,
+        "ci_digest": "<string>"
+      }
+    }
+  }
+}
+```
+
+- `lastBodyReviewId`: narrow watermark for **body-only** reviews (a submitted review carrying no line comments). The watcher dispatches a body-only review only when `id > lastBodyReviewId`. Line-comment threads do **not** use it — they are dispatched from live thread state (unresolved + not outdated + newest comment unmarked by the loop), so there is no cursor that can pin past them. Bootstrap sets it to the highest existing submitted review id with `--forward-only`, else `0`. The cursor keeps its name under GitLab, where it holds the highest note / discussion id.
+- `last_pushed_sha`: most recent SHA `/muggle-do` pushed in this PR's life; `null` until the first push.
+- `idle_tick_count`: incremented each tick whose actionable set is empty. Reset to 0 on any tick that dispatches `/muggle-do`. Diagnostic only — does not gate behavior.
+- `cycles_completed`: incremented each time `/muggle-do` completes an address-reviews invocation (regardless of actionable/ambiguous/mixed).
+- `escalated_review_ids`: review ids classified as ambiguous by `/muggle-do`. The watcher excludes these from the actionable set (both body-only reviews and the threads they own) so the same ambiguous review is never re-dispatched.
+- `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
+- `ci_fix_attempts`: per-SHA count of fix-ci cycles `/muggle-do` has run. The watcher stops dispatching fix-ci for a SHA once its count reaches 3. Keyed by head SHA.
+- `ci_escalated_shas`: head SHAs whose CI the fix-ci stage gave up on (attempts exhausted or only out-of-scope checks). The watcher excludes these from CI dispatch so a hopeless SHA is never re-fixed.
+- `conflict_resolve_attempts`: count of rebase cycles `/muggle-do` has run (behind-only or conflicting — both rebase onto the base). The watcher stops dispatching once a key's count reaches 2. Keyed by `rebase_key` — `"<head_sha>..<base_tip_sha>"`, the head paired with the base branch tip it was measured against.
+- `conflict_escalated_keys`: `rebase_key`s whose rebase `/muggle-do` gave up on (attempts exhausted, or a conflict under `autoResolveConflicts=never`). The watcher excludes these from rebase dispatch so a hopeless pairing is never re-attempted.
+
+Both are keyed on the pair, not the head alone, because whether a branch conflicts depends on both sides. Under a head-only key, a base that moves produces a genuinely new conflict against an unchanged head — and the stale entry suppresses it permanently, because nothing can change the head while the branch sits blocked. Pairing re-arms the budget whenever either side moves. Legacy entries written before this change are bare SHAs with no `..`; readers ignore them, which un-wedges any slot they had blocked.
+
+Unlike these, `ci_fix_attempts` / `ci_escalated_shas` stay keyed on the head SHA alone — a CI result is a function of the head only, so base movement must not re-arm them.
+- `blocked`: present only while the watcher is **awaiting the owner** on a PR that cannot progress without a human ([`contract.md`](contract.md) Step 7). Absent ⇒ the watcher is in its normal dispatch flow. When present, the watcher **keeps the normal `1m` cadence** and each tick is a reminder-or-resume check ([`contract.md`](contract.md) Step 2.5): it re-emits a one-line reminder to the owner, recomputes the `fingerprint`, and clears the block the moment any component moves. Its value is the reason-specific reminder plus fingerprint auto-resume.
+  - `reason`: which durable block is being awaited — `conflict_escalated` (`rebase_key` ∈ `conflict_escalated_keys`), `ci_escalated` (`head_sha` ∈ `ci_escalated_shas`), or `reviews_escalated` (a review sits in `escalated_review_ids` awaiting the user, actionable set empty). Selects the reminder wording; the resume decision is fingerprint-driven, not reason-driven.
+  - `since`: when the block was first flagged — lets the reminder state how long the owner has been the blocker.
+  - `fingerprint`: the external state the block is waiting on. `head_sha` moves on a new push (which also clears the per-SHA escalation sets, keyed by SHA); `latest_review_id` is `max(id)` over submitted reviews and moves when a reviewer submits anything new; `ci_digest` is a stable digest of the head SHA's CI rollup (bucket + each check's name/conclusion, sorted) and moves when a check flips, a rerun lands, or an external check such as a staging deploy posts. Any change clears the block and resumes evaluation.
+
+## `state.md`
+
+Free-form markdown. No required schema beyond a few well-known fields the caller-agnostic code reads:
+
+```markdown
+# Session — <slug>
+
+**PR:** <url>
+**Slug:** <slug>
+**Loop user:** <github-login>          ← cached from `gh api user`
+**Created:** <ISO-8601>
+**Bootstrapped from URL:** <yes | no>
+
+## Pre-flight answers
+
+- Validation: <local-e2e | staging-replay | unit-only | skip>
+- Local URL: <url | N/A>
+- Backend status: <up | down | N/A>
+- Muggle Test project: <name> (<uuid>)
+- Test credentials: <existing | new | skip>
+- Auth status: <ok | re-authed | N/A>
+- Working tree: <path>
+
+...free-form notes added by /muggle-do and bootstrap...
+```
+
+The `## Pre-flight answers` block is the **E2E validation context** consumed by `do/e2e-acceptance.md` Step 0 — seeded by bootstrap (Step 6.5) or by pre-flight's output block. Fields: [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields).
+
+The watcher does **not** read or write `state.md`. Only bootstrap, `/muggle-do`, and the caller's stages touch it.
+
+## `followup.log`
+
+Append-only line-per-tick log. One line per watcher tick, plus one line per `/muggle-do` invocation. Format is loose, but each line starts with an ISO-8601 timestamp:
+
+```
+2026-05-20T12:34:56Z tick pr=154 threads=0 idle
+2026-05-20T12:35:56Z tick pr=154 threads=1 dispatched=4295962800
+2026-05-20T12:36:14Z muggle-do cycle review_ids=[4295962800] outcome=pushed head_sha=abc1234
+```
+
+Used for forensics only — never read back by skills.
+
+## `result.md`
+
+Written exactly once when the PR's watcher exits terminally (PR merged or closed). Free-form markdown summarizing the PR's life under this loop:
+
+```markdown
+# Result — <slug>
+
+**PR:** <url>
+**Final state:** merged | closed
+**Cycles completed:** <int>
+**Pushed SHAs:** <comma-separated list>
+**Escalated review ids:** <comma-separated list or "none">
+
+## Timeline
+
+- <ISO-8601> bootstrap (lastBodyReviewId <id>; line-comment threads state-derived)
+- <ISO-8601> review <id> from <login> — actionable, pushed <sha>
+- <ISO-8601> review <id> from <login> — ambiguous, escalated
+- ...
+- <ISO-8601> PR <merged|closed> — watcher terminal
+```
+
+## Not in the slot
+
+`cycle.json` and `requirements.md` are not seeded or read. `/muggle-do` reads reviews off GitHub each invocation.
+
+## `watch-heartbeat`
+
+Touched (mtime refreshed) by the watch loop every iteration — content irrelevant. The slot's liveness beacon: a quiet monitor writes no log lines, so mtime is the only proof it is still polling. Read by [`reconcile.md`](reconcile.md) Step 3.6; a beacon older than 15 minutes means the poller is dead.
+
+## `watch-watermark.env`
+
+The watch loop's comparison floor — plain `KEY=VALUE` lines, one file per slot:
+
+- `REV` — highest submitted-review id already handled
+- `COM` — highest thread-comment id already handled
+- `THREADS` — semicolon-joined ids of threads already known unresolved
+- `CIRED` — head SHA whose settled-red CI the drain already handled; empty when the checks are green, still pending, or unseen. The CI floor is a SHA rather than a monotonic id because the check rollup flips green↔red and resets on each push — keying on the head SHA fires the loop once per red head and re-arms on the next push ([`arm-watcher.md`](arm-watcher.md)).
+
+Written whole-file by the orchestrating session — seeded at arm time to the **drain's own observed max** (the ids the drain read, snapshotted at that read) and advanced after every cycle to the **handled wave's snapshot** (the max review-id and comment-id the cycle read at the start of handling, captured before replies were posted). **Never** derived from a fresh fetch taken after the drain or after replies land: a later fetch includes ids that arrived in the handling window and were never read, and marking them seen swallows them ([`arm-watcher.md`](arm-watcher.md)). The advance also never moves any floor past an unresolved thread the cycle left unaddressed. Read by the watch loop each iteration; the loop never writes it. A stale watermark makes the next reported event the loop's own reply.
+
+**Never `source` this file, and quote or extract values.** `THREADS` holds bare semicolons: sourced unquoted, the shell splits the line at the first `;` and silently drops every id after it — the loop then re-reports known threads as new. The watch loop must extract values verbatim (e.g. `grep '^THREADS=' | cut -d= -f2- | tr -d '"\r'`), tolerating quotes and CRLF; writers should quote the value anyway.
+
+## `watch.pid`
+
+A single line: the process id of the watch loop that currently owns this slot. Written once by the loop itself on start (`echo "$$" > watch.pid`); read by two parties, never rewritten in place:
+
+- **arm-watcher's pre-arm dedup** ([`arm-watcher.md`](arm-watcher.md) Step 3) reads it and, if the PID is live (`kill -0`), skips arming — one live watcher per slot.
+- **the loop's own supersede guard** (`watcher_superseded`, [`../../scripts/pr-watch-guards.sh`](../../scripts/pr-watch-guards.sh)) compares it to `$$` each iteration and exits when they differ — a newer arm that overwrote the file steps the old loop down.
+
+This is the lease that keeps orphaned watchers from accumulating across sessions: the in-session monitor task dying does not stop the detached OS loop it launched (notably on Windows), so slot ownership is tracked by a durable PID on disk, not by the live task list. It is not seeded, migrated, or cleaned up — a stale PID (loop already dead) simply fails the `kill -0` liveness check and the next arm proceeds.

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

@@ -0,0 +1,31 @@
+# Stop Procedure
+
+The procedure for the **stop mode** of `muggle-pr-followup` — the owner's kill switch. One command tears down every polling substrate a slot has (monitor, cron) and leaves the slot in a state where anything that survives teardown — an orphaned cron in an unreachable scheduler, a queued fire still draining — arrives as an inert one-line absorb ([`contract.md`](contract.md) Step 0). Routing is in [`SKILL.md`](SKILL.md#routing).
+
+Stopping is not finalizing: the PR stays open on the provider, and no `result.md` is written. A stopped slot can be resumed later by renaming `<slug>.stopped` back to `<slug>` and re-arming per [`arm-watcher.md`](arm-watcher.md).
+
+## Input
+
+`$ARGUMENTS` is `stop`, optionally followed by a `<slug>` to scope to one slot. No slug stops **every** open slot and writes the global kill file.
+
+## Procedure
+
+Run per slot in scope (every dir under `~/.muggle-ai/muggle-do/sessions/` with a `prs.json` and no `result.md`, or just the named one):
+
+1. **Stop the monitor.** `TaskStop` any running monitor whose command references this slot's `watch.sh`. On Windows also kill surviving grandchildren: `TaskStop` reaps the wrapper but the inner `bash <slot>/watch.sh` process can outlive it and keep touching `watch-heartbeat` — enumerate processes whose command line contains `<slug>/watch.sh` and kill them. A survivor here also blocks the Step 3 rename (open handles inside the dir).
+2. **Cancel the cron.** Per [`cancel-cron.md`](cancel-cron.md) — recorded-id first, `CronList` match as fallback. A cron neither can reach is orphaned; it stays inert via the absorb and dies with its session.
+3. **Mark the slot stopped.** Rename `~/.muggle-ai/muggle-do/sessions/<slug>/` → `<slug>.stopped/`. This single rename is the load-bearing act: the tick absorb keys on it and [`reconcile.md`](reconcile.md) skips `*.stopped` dirs — so no recovery path of any kind re-arms the slot.
+
+Then, for a no-slug (stop-everything) invocation only:
+
+4. **Write the global kill file.** `~/.muggle-ai/muggle-do/polling.disabled` (empty file). Ticks absorb on it before even resolving a slot, and reconcile's re-arm step refuses while it exists. Bootstrap deliberately ignores it — pasting a PR URL is an explicit request to watch, and it removes the kill file as its first act so the new watch isn't stillborn.
+
+## Output
+
+One line per slot (`stopped: <slug> — monitor <killed|none>, cron <cancelled|orphaned|none>`), plus `polling disabled globally` when the kill file was written. Report an orphaned cron honestly: it may keep firing one-line absorbs until its host session ends — that is the harness's floor, not a teardown failure.
+
+## Invariants
+
+- **Idempotent.** Stopping a stopped slot is a no-op; re-running never errors.
+- **Nothing revives a stopped slot.** Tick, reconcile, and auto-track all treat `*.stopped` as invisible. Only the owner resumes one (rename back + re-arm), and only bootstrap overrides the global kill file.
+- **Orphans are inert, never invisible.** The absorb line keeps a firing orphan observable without spending anything on it.

package/dist/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -144,16 +144,22 @@ gh pr view --json number,url,title 2>/dev/null
 
 ### 3A.2: Post the body as a PR comment
 
-Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, then pipe to `--body-file -`:
+Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, append the Muggle Works signature (command `/muggle-pr-visual-walkthrough`) per [`../_shared/vcs/post-signature.md`](../_shared/vcs/post-signature.md), then pipe to `--body-file -`. The renderer's sentinel stays at the top of `body`, so the report-format guardrail still recognises the post:
 
 ```bash
-jq -r '.body' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
+{
+  jq -r '.body' /tmp/muggle-pr-section.json
+  printf '\n\n%s\n' '🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
+} | gh pr comment <pr-number> --body-file -
 ```
 
 ### 3A.3: Post the overflow comment only if the CLI emitted one
 
 ```bash
-jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <pr-number> --body-file -
+{
+  jq -r '.comment' /tmp/muggle-pr-section.json
+  printf '\n\n%s\n' '🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
+} | gh pr comment <pr-number> --body-file -
 ```
 
 **Skip this step entirely if `comment` is `null`** — do not post a placeholder. The CLI decides fit-vs-overflow; never post the overflow comment speculatively.
@@ -172,10 +178,13 @@ Instead of posting, **return** the CLI output to the caller's context so they ca
 
 1. **Embed `body`** in their PR body, concatenated after `## Changes`. `body` already includes its own `## E2E Acceptance Results` header — do not add another.
 2. **Create the PR** with `gh pr create --title "..." --body "..."` using the concatenated body.
-3. **Post `comment` as a follow-up only if the CLI emitted one:**
+3. **Post `comment` as a follow-up only if the CLI emitted one**, ending the posted body with the signature (the caller owns this post, so command `/muggle-do`) per [`../_shared/vcs/post-signature.md`](../_shared/vcs/post-signature.md):
 
    ```bash
-   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <new-pr-number> --body-file -
+   {
+     jq -r '.comment' /tmp/muggle-pr-section.json
+     printf '\n\n%s\n' '🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
+   } | gh pr comment <new-pr-number> --body-file -
    ```
 
    Skip if `comment` is `null`.

package/dist/plugin/skills/muggle-test-prepare/steps/start-services.md

@@ -1,9 +1,9 @@
 # Start services
 
-For each service, launch in the background:
+For each service, launch in the background through the shipped process cap: wrap the service's start command as `node <plugin-root>/scripts/guard-run.mjs --service -- <command>` (resolve `<plugin-root>` from `CLAUDE_PLUGIN_ROOT`). The wrapper is plain node and picks the cap mechanism per OS itself, so the instruction is the same everywhere; it kernel-bounds the service's process tree (a runaway spawn loop dies at the cap, not the machine) while letting the service outlive this session. From the Bash tool:
 
 ```bash
-cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
+cd "<service-dir>" && nohup node "${CLAUDE_PLUGIN_ROOT}/scripts/guard-run.mjs" --service -- <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
 echo $!
 ```
 

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.6.0",
-  "buildId": "run-65-1",
-  "commitSha": "5d15cf7c334a1714257f10f801ed41b9ec9e796b",
-  "buildTime": "2026-07-22T23:54:34Z",
+  "release": "5.8.0",
+  "buildId": "run-67-1",
+  "commitSha": "f0fbb486a0d7886d880eaec3129bc53964524f01",
+  "buildTime": "2026-08-01T07:54:45Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.6.0",
+  "version": "5.8.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",
@@ -46,14 +46,14 @@
     "eval:studio-gen": "tsx internal/studio-gen-eval/src/run.ts"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.6.10",
+    "electronAppVersion": "1.6.11",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "11672d444a151125a4d2f3413a7f0f4f8cb2de64ecbd2a43eddca4f364743b13",
-      "darwin-x64": "6277246853cdcc3aa3fbbaae703d428cfbf85c53fda6720a71a0cadbe8f5a5f6",
-      "linux-x64": "9485e0f9f4a0fb90666e63e87bd83da3c4b865a8cff8da40dc4d1b0ad2aba242",
-      "win32-x64": "e68471bcbf4f00d501067a282e835d00bb2f4941dc42878a8f041a5dab06acdf"
+      "darwin-arm64": "97f7f5ba622dc3baf86457184bc44030c777d7dbac58b8c1c5418970662e7a07",
+      "darwin-x64": "c8c2745282583144b34110ef45c4745e03c03c4ac2e020c820daa51124c3fc50",
+      "linux-x64": "d85e14ed38cb8035b932aef26148934e3aec6e036b6bb80ff8927cbde901a935",
+      "win32-x64": "6e38a5b017ee5756985e1507def6c5a92d357a4bbd4e4032b6e490ad05dd09a2"
     }
   },
   "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.6.0",
+  "version": "5.8.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.6.0",
+  "version": "5.8.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/hooks/README.md

@@ -20,7 +20,7 @@ A guardrail emits one of two strengths:
 - **Advise** — `additionalContext` (PostToolUse/UserPromptSubmit) or a plain Stop message. A soft nudge the model can ignore.
 - **Enforce** — a `Stop` `decision: "block"` that refuses to end the turn, or a `PreToolUse` `permissionDecision: "deny"` that refuses a tool call. The model cannot proceed until the condition is met.
 
-Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run and posting a deterministically-rendered report. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise.
+Enforcement is reserved for the handoffs that were being skipped: the E2E acceptance run, posting a deterministically-rendered report, and the post-merge handoff. Each enforcing gate carries an escape so it can't trap a turn — the E2E gate accepts an explicit skip declaration (`echo "MUGGLE_E2E_SKIP: <reason>"`, session-durable) and hard-releases after `MAX_E2E_BLOCKS` (3) blocks; the report gate only denies a body it can positively see is a hand-written report and fails open otherwise; the post-merge gate hard-releases after `MAX_PR_TERMINAL_BLOCKS` (3) blocks, and only the AskUserQuestion next-options offer clears it — nothing else resets its counter.
 
 ## Mechanism
 
@@ -31,13 +31,25 @@ Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json
 | Hook event | Wrapper | Strength | Condition | Preference | Effect |
 | :--------- | :------ | :------- | :-------- | :--------- | :----- |
 | `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
-| `PostToolUse` (Bash + muggle execute/replay MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened, or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + muggle execute/replay/skill-emit MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened (execute/replay call, or the muggle-test skill's own telemetry emit — which registers a clean SKIP verdict too), or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + Monitor) | `guardrail-pr-terminal.sh` | advise | a PR just went terminal — a `gh pr merge`/`gh pr close` success line or the watch monitor's `TERMINAL pr=N` exit line (never bare `"state":"MERGED"` metadata) | — | record `terminalPending`, direct the post-merge handoff: finalize the watcher slot, tear down per `autoCleanup`, offer next options via AskUserQuestion |
+| `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
 | `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
 | `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks) |
+| `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the AskUserQuestion next-options offer hasn't run since | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
 | `UserPromptSubmit` | `guardrail-build-router.sh` | advise | a build/implement/fix request (first one this session) | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers) |
 
 ## Session-start reconcile nudge
 
 `SessionStart` (`scripts/reconcile-stale-watchers.sh`) — a standalone advisory, not part of the `guardrails.mjs` decision tree above.
 
-`muggle-pr-followup` watchers are session-only `/loop` crons; they die on session end and the 7-day `/loop` expiry, leaving open PRs with no live poller. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs the `CronCreate` tool, which a shell hook can't call. So this hook nudges rather than acts: it scans `~/.muggle-ai/muggle-do/sessions/*/` for open slots (a `prs.json` with no `result.md`) and, **only when one or more exist**, injects `additionalContext` telling the agent to run `/muggle:muggle-pr-followup reconcile`. Zero open slots → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
+`muggle-pr-followup` watchers are session-only (a monitor or `/loop` cron); they die with their session, leaving open PRs with no live poller. This is by design — a review is addressed only inside a session that carries the context to address it. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them at the next session start — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs Claude tools a shell hook can't call. So this hook nudges rather than acts: it scans `~/.muggle-ai/muggle-do/sessions/*/` for open slots (a `prs.json` with no `result.md`) and, **only when one or more exist**, injects `additionalContext` telling the agent to run `/muggle:muggle-pr-followup reconcile`. Zero open slots → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
+
+## Session-start state GC
+
+`SessionStart` (`scripts/gc-state.sh`) — prunes ephemeral state that nothing else garbage-collects, so it doesn't grow without bound (the per-session guardrails files and finalized watcher slots otherwise accumulate one-per-session forever). Collection is keyed on **inactivity, never creation age**, so state a long-lived session still relies on is never deleted out from under it:
+
+- `~/.muggle-ai/guardrails/*.json` (one per session) is pruned only after 14 days of **no activity**. An in-use session keeps rewriting its file (`guardrails.mjs` on every guarded tool call) and this hook refreshes it on every resume, so its mtime tracks last activity — a session that runs for months stays live indefinitely, and only one that has genuinely gone quiet for the whole window (i.e. ended) is collected.
+- Finalized watcher slots (`result.md` present) are pruned 30 days after finalize; their `followup.log` is forensic-only. An **open** slot — a PR watched for any length of time — has no `result.md` and is never touched.
+
+Both windows are overridable (`MUGGLE_GUARDRAILS_TTL_DAYS`, `MUGGLE_SLOT_TTL_DAYS`). TTL-gated to once per day via a `~/.cache/muggle/state-gc-checked` marker (the current-session refresh runs every start regardless); silent and best-effort, never blocks session start. Never touches an open slot or the current session's own state.