@muggleai/works 5.0.1 → 5.0.2

package/dist/plugin/skills/muggle-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test
-description: "Run change-driven E2E acceptance testing using Muggle AI — detect the user's recent code changes (local diff or a PR), map them to affected user flows, then run real-browser acceptance tests on localhost or a deployed preview/staging URL, publish results to the dashboard, and post a screenshot summary to the PR. Use this whenever the user wants to test, validate, check, or regression-test their own changes or work — 'test my changes', 'validate my changes', 'regression test my work', 'make sure I didn't break anything', 'did my recent commits/changes break anything or any user flows?', 'test before I push' — and especially as the acceptance-test gate before opening a pull request or merging (e.g. 'validate my changes before I open the PR' means run the acceptance suite, not just a completion checklist). The defining signal is change-driven validation of in-progress work tied to a commit, push, PR, or merge. For testing one specific named feature/flow use muggle-test-feature-local; this is not importing existing tests, configuring preferences, or replaying a single named script."
+description: "Change-driven E2E acceptance testing with Muggle AI: detect the user's recent code changes (local diff or a PR), map them to affected user flows, run real-browser tests on localhost or a preview/staging URL, publish results, and post a screenshot summary to the PR. Use whenever the user wants to test, validate, or regression-test their own in-progress changes or work — \"make sure I didn't break anything\", \"did my recent commits break any user flows?\", \"test before I push\" — especially as the acceptance gate before opening or merging a PR. The defining signal is change-driven validation tied to a commit, push, PR, or merge. For one specific named feature/flow use muggle-test-feature-local; not for importing existing tests, configuring preferences, or replaying a single named script."
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
@@ -415,53 +415,15 @@ Use `AskUserQuestion`:
 
 This is a suggestion, not automatic invocation. Skip silently if every test passed cleanly.
 
-## Tool Reference
-
-| Phase | Tool | Mode |
-|:------|:-----|:-----|
-| Auth | `muggle-remote-auth-status` | Both |
-| Auth | `muggle-remote-auth-login` | Both |
-| Auth | `muggle-remote-auth-poll` | Both |
-| Project | `muggle-remote-project-list` | Both |
-| Project | `muggle-remote-project-create` | Both |
-| Use Case | `muggle-remote-use-case-list` | Both |
-| Use Case | `muggle-remote-use-case-create-from-prompts` | Both |
-| Test Case | `muggle-remote-test-case-list-by-use-case` | Both |
-| Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
-| Test Case | `muggle-remote-test-case-create` | Both |
-| Test Case | `muggle-remote-test-case-get` | Both |
-| Execute (regen) | `muggle-local-execute-test-generation` | Local |
-| Execute (replay) | `muggle-local-execute-replay` | Local |
-| Replay action script fetch | `muggle-remote-test-script-get`, `muggle-remote-action-script-get` | Local replay |
-| Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
-| Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
-| Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
-| Results | `muggle-local-run-result-get` | Local |
-| Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
-| Publish | `muggle-local-publish-test-script` | Local |
-| Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
-| Browser | `open` (shell command) | Both |
-| PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |
-
-## Guardrails
-
-- **Always confirm intent first** — never assume local vs remote without asking
-- **PR URLs always run in a dedicated worktree** — never switch the user's main checkout. Materialize per [`_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) and pass that path as `cwd` to local execute tools; the cross-worktree single-flight lock relies on it to serialize concurrent runs from different branches.
-- **User MUST select project** — present clickable options via `AskUserQuestion`, wait for explicit choice, never auto-select
-- **Best-effort shortlist use cases** — use the change summary to narrow the list to the most relevant 1–5 use cases and pre-check them; never dump every use case in the project on the user. Always leave an escape hatch to reveal the full list.
-- **Best-effort shortlist test cases** — same idea: pre-check the test cases most relevant to the change summary; never enumerate every test case attached to a use case. Always leave an escape hatch to reveal the full list.
-- **Use `AskUserQuestion` for every selection** — never ask the user to type a number; always present clickable options
-- **Auto-detect localhost URL when possible**; only fall back to free-text when nothing is listening on a common port
-- **Parallelize independent cloud jobs** — when creating N use cases, generating/creating N test cases, fetching N test case details, starting N remote workflows, polling N workflow runtimes, publishing N local runs, or fetching N per-step test scripts, issue all N calls in a single message so they fan out in parallel. The only tolerated sequential loop is local Electron execution (one browser, one test at a time). For use case creation specifically, use the native batch form of `muggle-remote-use-case-create-from-prompts` (all descriptions in one `instructions` array) instead of parallel calls.
-- **One atomic behavior per test case** — every test case verifies exactly one user-observable behavior. Never bundle signup/login/navigation/bootstrap/teardown into a test case body. Ordering and dependencies are Muggle Test's service responsibility, not the skill's.
-- **Never consolidate the generator's output** — if `muggle-remote-test-case-generate-from-prompt` returns N micro-tests, accept all N; never merge them into fewer test cases, even if "the plan" says 4 UC / 4 TC.
-- **Never skip the generate→review cycle** — always present generated test cases to the user before calling `muggle-remote-test-case-create`, even when you're confident. "I'll skip the review and create directly" is always wrong.
-- **Never silently drop test cases** — log failures and continue, then report them
-- **Never guess the URL** — always ask the user for localhost or preview URL
-- **Always publish before opening browser** — the dashboard needs the published data to show results
-- **Delegate PR posting to `muggle-pr-visual-walkthrough`** — never inline the walkthrough markdown or call `gh pr comment` directly from this skill; ask the user and hand off
-- **Can be invoked at any state** — if the user already has a project or use cases set up, skip to the relevant step rather than re-doing everything
-
-## Agent Dispatch
-
-When used in a multi-agent team (e.g., muggle-ai-teams), this skill is available through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators can dispatch it via `Agent()` instead of invoking this skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.
+## Non-negotiables
+
+Each rule below is covered in-step above; these are the ones this skill most often violates, kept here as reinforcement:
+
+- **Test-case shape** — never skip the generate→review cycle, never consolidate the generator's micro-tests, one atomic behavior per test case. Creating test cases directly or merging the generator's output is the single most frequent mistake.
+- **Confirm intent before acting** — local vs remote; never guess the localhost/preview URL.
+- **PR URLs run in a dedicated worktree** — never switch the user's main checkout; pass that worktree as `cwd`.
+- **Every selection uses `AskUserQuestion`** — never ask the user to type a number; the user picks the project (never auto-select).
+- **Parallelize independent cloud jobs**; the only sequential loop is local Electron execution (one browser).
+- **Publish before opening the browser**, and delegate PR posting to `muggle-pr-visual-walkthrough` — never inline the walkthrough or call `gh pr comment` here.
+
+Phase→tool map and multi-agent (acceptance-tester) dispatch: [`reference.md`](reference.md).

package/dist/plugin/skills/muggle-test/reference.md

@@ -0,0 +1,35 @@
+# muggle-test reference
+
+Lookup material pulled out of `SKILL.md` to keep the always-loaded body lean. Every tool here is also named inline in the step that uses it — consult this only when you want the full phase→tool map in one place.
+
+## Tool Reference
+
+| Phase | Tool | Mode |
+|:------|:-----|:-----|
+| Auth | `muggle-remote-auth-status` | Both |
+| Auth | `muggle-remote-auth-login` | Both |
+| Auth | `muggle-remote-auth-poll` | Both |
+| Project | `muggle-remote-project-list` | Both |
+| Project | `muggle-remote-project-create` | Both |
+| Use Case | `muggle-remote-use-case-list` | Both |
+| Use Case | `muggle-remote-use-case-create-from-prompts` | Both |
+| Test Case | `muggle-remote-test-case-list-by-use-case` | Both |
+| Test Case | `muggle-remote-test-case-generate-from-prompt` | Both |
+| Test Case | `muggle-remote-test-case-create` | Both |
+| Test Case | `muggle-remote-test-case-get` | Both |
+| Execute (regen) | `muggle-local-execute-test-generation` | Local |
+| Execute (replay) | `muggle-local-execute-replay` | Local |
+| Replay action script fetch | `muggle-remote-test-script-get`, `muggle-remote-action-script-get` | Local replay |
+| Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
+| Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
+| Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
+| Results | `muggle-local-run-result-get` | Local |
+| Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
+| Publish | `muggle-local-publish-test-script` | Local |
+| Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
+| Browser | `open` (shell command) | Both |
+| PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |
+
+## Agent Dispatch
+
+In a multi-agent team (e.g. muggle-ai-teams), this skill is reachable through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators dispatch it via `Agent()` instead of invoking the skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.

package/dist/plugin/skills/muggle-test-import/SKILL.md

@@ -1,15 +1,6 @@
 ---
 name: muggle-test-import
-description: >
-  Bring existing tests and test artifacts INTO Muggle Test — from Playwright, Cypress, PRDs,
-  Gherkin feature files, test plan docs, Notion exports, or any source.
-  TRIGGER when: user wants to import/migrate/load/upload/add/convert existing test files or
-  test docs into Muggle Test — e.g. "import my playwright tests", "migrate from cypress to muggle",
-  "upload my PRD to muggle", "add my e2e specs to our muggle project", "load these test cases
-  into muggle", "turn this feature file into muggle test cases", "create muggle test cases from
-  my PRD", "track my specs in muggle", or any .spec.ts/.cy.js/.feature/.md file + muggle.
-  DO NOT TRIGGER when: user wants to run/replay Muggle Test scripts, scan a site, generate new
-  tests from scratch, or check existing test results.
+description: "Bring existing tests and test artifacts INTO Muggle Test — from Playwright, Cypress, PRDs, Gherkin feature files, test-plan docs, Notion exports, or any source. TRIGGER when the user wants to import, migrate, load, or convert existing test files or docs into Muggle Test — import my playwright tests, migrate from cypress to muggle, upload my PRD to muggle, turn this feature file into muggle test cases, or any .spec.ts/.cy.js/.feature/.md file plus muggle. DO NOT trigger for running or replaying scripts, scanning a site, generating new tests from scratch, or checking results."
 ---
 
 # Muggle Test Import

package/dist/plugin/skills/muggle-test-prepare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-prepare
-description: "Use this skill to get a user's local environment ready before running E2E acceptance tests — verifying that the dev servers, APIs, and sibling services they need are actually up and responding, and offering to start whatever is missing (with approval at each step). Trigger whenever the user wants to confirm that specific ports or localhost URLs are listening/up before testing (e.g. 'check if localhost:3000 and the api on 8080 are listening', 'are my services up?'), make sure required services are running, spin up or prepare their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not listening on the expected ports. This is environment readiness and service startup, not running the tests themselves."
+description: "Get a user's local environment ready before running E2E acceptance tests — verify the dev servers, APIs, and sibling services they need are up and responding, and offer to start whatever is missing (with approval per step). Trigger when the user wants to confirm specific ports or localhost URLs are listening before testing (check if localhost:3000 and the api on 8080 are up, are my services running), spin up their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not. This is environment readiness and service startup, not running the tests."
 ---
 
 # Muggle Test Prepare

package/dist/plugin/skills/muggle-test-regenerate-missing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-regenerate-missing
-description: "Bulk-regenerate test scripts for every test case in a Muggle AI project that doesn't currently have an active script. Scans the project, finds test cases stuck in DRAFT or GENERATION_PENDING (no usable script attached), shows the user the list, and on approval kicks off bulk remote test script generation via the Muggle Test cloud. Use this skill whenever the user asks to 'regenerate missing scripts', 'fill in missing test scripts', 'generate scripts for test cases without one', 'regen all the test cases that don't have scripts', 'rebuild scripts for stale test cases', 'fix test cases with no script', 'bulk regenerate', or any phrasing that means 'kick off script generation across a project for the cases that need it'. Triggers on: 'regenerate missing test scripts', 'generate scripts for all empty test cases', 'fill the gaps in my test scripts', 'bulk test script regen', 'all my test cases without active scripts'. This is the go-to skill for project-wide script catch-up — it handles discovery, filtering, confirmation, and remote workflow dispatch end-to-end."
+description: "Bulk-regenerate test scripts for every test case in a Muggle AI project that has no active script. Scans the project, finds test cases stuck in DRAFT or GENERATION_PENDING, shows the user the list, and on approval kicks off bulk remote script generation via the Muggle Test cloud. Use when the user wants to regenerate missing scripts, fill in missing test scripts, generate scripts for test cases without one, rebuild scripts for stale test cases, or bulk regenerate across a project. Handles discovery, filtering, confirmation, and remote dispatch end-to-end."
 ---
 
 # Muggle Test — Regenerate Missing Test Scripts

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.0.1",
-  "buildId": "run-49-1",
-  "commitSha": "a12a3252381af4fb34b79598208ba62f9764154d",
-  "buildTime": "2026-06-04T17:35:40Z",
+  "release": "5.0.2",
+  "buildId": "run-50-1",
+  "commitSha": "9893215c2e48b50b132e223dbfa952531b7d2442",
+  "buildTime": "2026-06-08T07:17:59Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.0.1",
+  "version": "5.0.2",
   "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",
@@ -41,14 +41,14 @@
     "test:watch": "vitest"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.0.116",
+    "electronAppVersion": "1.1.0",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "382466a6eefe49cddc5662556cb6b744c60c2eed9984e520df9f62726bc468a0",
-      "darwin-x64": "9c57b10b1ed03bcd6629cb36abd5c0e0b5d095a27a38305ad4272c77cd6334af",
-      "linux-x64": "d6b10a829f99027747349ab37521b765041343676f59e59792afcec1de024080",
-      "win32-x64": "77981c9d77dd49a786cfca7156ce326f56a75716cf911adad270521230435f75"
+      "darwin-arm64": "1df66af13de18e90b53a0dfad7b329358265a7380bc8f61b6bfcfaaefdce2825",
+      "darwin-x64": "3d350547f398c09e485d6b33bb3493d50698ab19a63890792a7a03aeee4a93f2",
+      "linux-x64": "93bed227dee0c52cff3cdc6e2a346c86d1902ce0ca93bced5632d4d8e7ae290e",
+      "win32-x64": "c2971e824fea4637ce520b3ee8a2fd8bd8562f1f826ac3674a80931791007088"
     }
   },
   "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.0.1",
+  "version": "5.0.2",
   "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.0.1",
+  "version": "5.0.2",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/scripts/guardrails.mjs

@@ -64,12 +64,13 @@ function shouldRunE2E(state) {
 
 // src/guardrails/detectBuildIntent.ts
 var BUILD = /\b(implement|build|add|create|write|fix|refactor|wire up|hook up|make (a|the|it)|change the)\b/i;
+var DEVCYCLE = /\bresolve\b[^.?!]{0,40}\bconflicts?\b|\bget\b[^.?!]{0,40}\bpr\b[^.?!]{0,40}\b(green|merged?|passing)\b/i;
 var QUESTION = /^\s*(why|what|how|when|where|who|is|are|does|do|can you (explain|tell)|explain)\b/i;
 function detectBuildIntent(prompt) {
   const p = (prompt ?? "").trim();
   if (!p || p.startsWith("/")) return false;
   if (QUESTION.test(p)) return false;
-  return BUILD.test(p);
+  return BUILD.test(p) || DEVCYCLE.test(p);
 }
 
 // src/guardrails/emit.ts

package/plugin/skills/_shared/github-cli-recipes/submitted-reviews.md

@@ -1,16 +1,24 @@
-# Submitted reviews past a cursor
+# Submitted reviews
 
-For the watcher's poll and the address-reviews fetch.
+Two consumers (this recipe links to neither — it is a shared primitive):
+
+- the watcher's **body-only-review** check — a submitted review carrying a summary body but **no** line comments. Line-comment threads are dispatched from live thread state, not here.
+- the address-reviews fetch of a **specific** review id.
 
 ```bash
 gh api repos/<owner>/<repo>/pulls/<n>/reviews --paginate
 ```
 
-Filter client-side:
+Common filter:
 
 - `submitted_at != null` (skip PENDING drafts)
-- `id > last_seen.reviewId`
-- `id` not in `last_seen.escalated_review_ids`
 - `user.login` in the resolved allow-list
 - `state` in `{CHANGES_REQUESTED, COMMENTED}`, OR `APPROVED` with a non-empty body or at least one line comment
-- **Not a loop echo.** `POST /pulls/<n>/comments/<id>/replies` creates an implicit review whose comments all have `in_reply_to_id` set. Fetch each candidate review's comments via `gh api repos/<owner>/<repo>/pulls/<n>/reviews/<id>/comments` and drop the review **only if every comment is a reply (`in_reply_to_id != null`) and carries the loop marker `<!-- muggle-do:bot -->`** (see [`../pr-followup-helpers/loop-signature.md`](../pr-followup-helpers/loop-signature.md)). A reply-only wrapper with any comment **lacking** the marker is a human follow-up — keep it; the round addresses it. Matching the marker, not structure, is what skips the loop's own replies (posted under the author's identity in single-account workflows) without dropping genuine follow-ups.
+
+The **watcher's body-only check** adds:
+
+- the review has **no line comments** — `gh api repos/<owner>/<repo>/pulls/<n>/reviews/<id>/comments` returns `[]`. A review with line comments is dispatched from thread state, not here.
+- `id > last_seen.lastBodyReviewId`
+- `id` not in `last_seen.escalated_review_ids`
+
+A reply posted by the loop surfaces as an implicit review, but it always carries the reply as a line comment, so it can never be body-only — the body-only filter excludes it structurally, no marker check needed. Thread-level echo protection is intrinsic to the marker rule in [`unresolved-threads.md`](unresolved-threads.md).

package/plugin/skills/_shared/github-cli-recipes/unresolved-threads.md

@@ -1,6 +1,6 @@
 # Unresolved comment threads
 
-For the resolve-reminder stage. GraphQL only — REST does not expose `isResolved`.
+For the watcher's dispatch trigger and the resolve-reminder stage. GraphQL only — REST does not expose `isResolved`/`isOutdated`.
 
 ```bash
 gh api graphql -F owner=<owner> -F name=<repo> -F number=<n> -f query='
@@ -11,9 +11,11 @@ query($owner: String!, $name: String!, $number: Int!) {
         nodes {
           id
           isResolved
+          isOutdated
           comments(first: 100) {
             nodes {
               databaseId
+              pullRequestReview { databaseId }
               author { login }
               body
               createdAt
@@ -29,7 +31,9 @@ query($owner: String!, $name: String!, $number: Int!) {
 Filter client-side to `isResolved == false`. Walk each thread's comments in `createdAt` order and classify by the loop marker (see [`../pr-followup-helpers/loop-signature.md`](../pr-followup-helpers/loop-signature.md)), not by `author.login` — the login is ambiguous under a shared account:
 
 - **Addressed, awaiting resolve** — the **newest** comment carries the loop marker `<!-- muggle-do:bot -->`. The loop has replied and nothing newer is waiting. → resolve-reminder.
-- **Unaddressed human comment** — the newest comment lacks the marker and is newer than the thread's newest loop-marked comment (or the thread has no loop comment yet). → actionable: the round should address it.
+- **Unaddressed human comment** — the newest comment lacks the marker and is newer than the thread's newest loop-marked comment (or the thread has no loop comment yet). → actionable: the round should address it. The **watcher's dispatch trigger** additionally requires `isOutdated == false` — a thread whose anchored line has since changed is skipped, since re-surfacing a stale anchor risks answering a concern the change already mooted. The resolve-reminder stage ignores `isOutdated`.
 - **Not addressed** — indeterminate (e.g. no comments).
 
+Each comment exposes its owning review as `pullRequestReview.databaseId` — the watcher collects this from an actionable thread's newest comment to build its dispatch list.
+
 A loop comment also cites a `<short-sha>` from `last_seen.pushed_shas[]` in its body, which tells *which* push addressed the thread.

package/plugin/skills/_shared/github-cli-recipes.md

@@ -9,10 +9,10 @@ Skills assume a working `gh auth status`. Auth errors surface verbatim from `gh`
 | Recipe | Use case |
 | :----- | :------- |
 | [`pr-metadata`](github-cli-recipes/pr-metadata.md) | Snapshot PR state, head SHA, branch — watcher + bootstrap. |
-| [`submitted-reviews`](github-cli-recipes/submitted-reviews.md) | Fetch reviews past a cursor — watcher's poll. |
+| [`submitted-reviews`](github-cli-recipes/submitted-reviews.md) | Fetch a review by id / watcher's body-only-review check. |
 | [`pr-checks`](github-cli-recipes/pr-checks.md) | Check-run rollup for the head SHA — watcher's CI poll. |
 | [`line-comments-for-review`](github-cli-recipes/line-comments-for-review.md) | Pull a review's line comments — `/muggle-do` per-comment routing. |
-| [`unresolved-threads`](github-cli-recipes/unresolved-threads.md) | GraphQL fetch of unresolved comment threads — resolve-reminder. |
+| [`unresolved-threads`](github-cli-recipes/unresolved-threads.md) | GraphQL unresolved-thread state — watcher's dispatch trigger + resolve-reminder. |
 | [`reply-line-comment`](github-cli-recipes/reply-line-comment.md) | POST a threaded reply on a line comment. |
 | [`top-level-comment`](github-cli-recipes/top-level-comment.md) | POST a top-level PR comment — resolve-reminder + overflow. |
 | [`push-to-branch`](github-cli-recipes/push-to-branch.md) | Push + capture new SHA after address-reviews work. |

package/plugin/skills/_shared/pr-followup-helpers/classify.md

@@ -10,7 +10,7 @@ A review is a **self-loop** iff **every** line comment under it is a reply (`in_
 
 If any comment in a reply-only wrapper **lacks** the marker, it is a **human follow-up** on an existing thread — not a self-loop. It carries reviewer intent; treat it as actionable and address it in this round (the caller's unresolved-thread sweep picks up the thread context).
 
-Self-loops bypass the actionable/ambiguous decision entirely. Action: advance the cursor silently. No push, no reply, no resolve-reminder, no escalation, no entry in `escalated_review_ids`. Telemetry: emit one `cycle` event with `outcome: "self-loop-skip"`.
+Self-loops bypass the actionable/ambiguous decision entirely. Action: skip silently — a body-only echo folds its id into `lastBodyReviewId`; a line-comment echo already drops out of the actionable set via the marker. No push, no reply, no resolve-reminder, no escalation, no entry in `escalated_review_ids`. Telemetry: emit one `cycle` event with `outcome: "self-loop-skip"`.
 
 Only reviews that survive the self-loop check proceed to classify below.
 
@@ -51,7 +51,7 @@ Reply shape (all replies for one review reference the same SHA):
 | 1 comment: "won't this break the prod migration we did last week?" | Implicit change request gated on knowledge the loop can't access |
 | Mixed: 2 concrete directives + 1 "rethink the whole approach" | The "rethink" subverts the others; escalate to confirm scope |
 
-Escalate per the caller's procedure (add the review id to the cursor's escalated set, emit one terminal message, pause the PR).
+Escalate per the caller's procedure (add the review id to `escalated_review_ids`, emit one terminal message, pause the PR).
 
 ## Borderline rule
 

package/plugin/skills/_shared/pr-followup-helpers/echo-skip.md

@@ -1,16 +1,10 @@
-# Reply-echo skip
+# Echo protection (intrinsic under thread-state)
 
-When `/muggle-do` posts a threaded reply to a review comment, GitHub surfaces that reply as a **new submitted review** under the same account. Left unchecked, the next watcher tick reads that review as fresh feedback and dispatches another cycle — which posts another reply, which becomes another review. The loop never converges.
+When `/muggle-do` posts a threaded reply to a review comment, GitHub surfaces that reply as a **new submitted review** under the same account, and the reply becomes the newest comment in its thread. The watcher must never read that as fresh feedback, or it replies to itself forever.
 
-## Rule
+Under the thread-state dispatch trigger this is **intrinsic** — there is no "advance past the echo" step to get wrong:
 
-A submitted review is an **echo** when **every** comment in it carries the loop marker `<!-- muggle-do:bot -->` (see [`loop-signature.md`](loop-signature.md)). An echo is the loop's own reply wearing a review's clothing, never human intent.
+- **Line-comment threads.** A thread is actionable only when its newest comment lacks the loop marker `<!-- muggle-do:bot -->` (see [`loop-signature.md`](loop-signature.md)). After the loop replies, the newest comment is the loop's own and carries the marker, so the thread drops out of the actionable set on its own.
+- **Body-only reviews.** A loop reply always carries a line comment, so it is never body-only; the body-only check (no line comments, `id > lastBodyReviewId` — see [`../github-cli-recipes/submitted-reviews.md`](../github-cli-recipes/submitted-reviews.md)) excludes echoes structurally.
 
-On an echo review, the watcher must:
-
-1. Advance `last_seen.reviewId` past the echo's id (so it is not seen again), and
-2. **Skip it** — never dispatch `/muggle-do` for it.
-
-## Detection
-
-Classify by the marker, never by `author.login` — under a shared account the loop posts as the PR author, so the login cannot tell echo from human. Fetch the review's comments; if the set is non-empty and every comment body contains `<!-- muggle-do:bot -->`, it is an echo. A review with at least one marker-less comment is human feedback and must be processed normally.
+Classify by the marker, never by `author.login` — under a shared account the loop posts as the PR author, so the login cannot tell echo from human.

package/plugin/skills/_shared/pr-followup-helpers/reply-routing.md

@@ -37,4 +37,4 @@ fix(ci): lint — remove unused import
 
 - Never post a top-level comment in reply to a line-level comment. It loses thread context.
 - Never `gh pr review --comment` for replies — that endpoint is for *new* reviews.
-- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.
+- Never reply twice to the same comment. The loop marker on each posted reply is the re-entry guard — a thread whose newest comment is loop-marked is no longer actionable, so the next round won't re-reply.

package/plugin/skills/_shared/telemetry-events/pr-followup-tick.md

@@ -9,7 +9,7 @@ One per watcher iteration (idle or not).
   "session_slug": "<slug>",
   "repo": "<owner>/<repo>",
   "pr_number": <int>,
-  "reviews_seen": <int>,
+  "actionable_threads": <int>,
   "dispatched_review_ids": [<int>, ...],
   "checks_red": <int>,
   "dispatched_ci_fix": true | false,
@@ -19,9 +19,9 @@ One per watcher iteration (idle or not).
 }
 ```
 
-- `reviews_seen`: count of new submitted reviews past the cursor, **after** filtering by the escalated set.
-- `dispatched_review_ids`: review ids handed to `/muggle-do`. Empty when idle.
+- `actionable_threads`: count of actionable items this tick — unresolved, non-outdated threads whose newest comment is unmarked, plus body-only reviews past `lastBodyReviewId` — **after** filtering by the escalated set.
+- `dispatched_review_ids`: owning review ids handed to `/muggle-do`. Empty when idle.
 - `checks_red`: count of failing checks on the head SHA. `0` when reviews were dispatched (reviews preempt the CI poll) or CI was green/pending.
 - `dispatched_ci_fix`: true when this tick dispatched `/muggle-do` with a fix-ci directive.
 - `terminal`: true when this tick observed the PR merged or closed and wrote `result.md`.
-- `idle`: true when no reviews were dispatched this tick.
+- `idle`: true when nothing was dispatched this tick.

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

@@ -13,16 +13,16 @@ The entry procedure for `/muggle-do`'s **address-reviews** mode — invoked by t
 `$ARGUMENTS` carries:
 - PR URL: `<owner>/<repo>#<n>` derivable from the URL.
 - Session slug: `<slug>`.
-- List of review ids: one or more integers.
+- Owning review ids: one or more integers (the reviews whose actionable threads or body-only feedback the watcher flagged).
 
-Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md#step-5-if-one-or-more-new-reviews-dispatch)). Parse all three out of the directive text.
+Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)). Parse all three out of the directive text.
 
 ## Inputs from disk
 
 Read from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 - `prs.json` — to locate the PR's local checkout path (the `repo` field maps to a configured local repo) and capture `head_sha_before`.
-- `last_seen.json` — for `pushed_shas[]` (used by the resolve-reminder stage) and to update the cursor.
+- `last_seen.json` — for `pushed_shas[]` (used by the resolve-reminder stage) and to update `lastBodyReviewId`.
 - `state.md` — for the cached `loop_user` login (used by resolve-reminder thread classification).
 
 ## Procedure
@@ -37,10 +37,10 @@ Two sources, combined into one batch (dedupe by comment id):
 
 **(a) The dispatched reviews.** For each review id in the input:
 
-- Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) (cursor 0; filter to the specific id).
+- Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) (no watermark; filter to the specific id).
 - Fetch its line comments per [`../_shared/github-cli-recipes/line-comments-for-review.md`](../_shared/github-cli-recipes/line-comments-for-review.md).
 
-**(b) Unaddressed comments on every unresolved thread.** Fetch unresolved threads per [`../_shared/github-cli-recipes/unresolved-threads.md`](../_shared/github-cli-recipes/unresolved-threads.md). For each thread classified **unaddressed human comment** — newest comment lacks the loop marker `<!-- muggle-do:bot -->` ([`loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)) and post-dates the loop's last marked reply — add it to the batch, even if its review predates the cursor. This is how a human thread follow-up (a marker-less reply) gets addressed. **Exclude** comments whose review id is in `last_seen.escalated_review_ids` — paused awaiting the user, not re-work.
+**(b) Unaddressed comments on every unresolved thread.** Fetch unresolved threads per [`../_shared/github-cli-recipes/unresolved-threads.md`](../_shared/github-cli-recipes/unresolved-threads.md). For each thread classified **unaddressed human comment** — newest comment lacks the loop marker `<!-- muggle-do:bot -->` ([`loop-signature.md`](../_shared/pr-followup-helpers/loop-signature.md)) and post-dates the loop's last marked reply — add it to the batch — unresolved thread state, not any review-id watermark, is the authority here. This is how a human thread follow-up (a marker-less reply) gets addressed. **Exclude** comments whose review id is in `last_seen.escalated_review_ids` — paused awaiting the user, not re-work.
 
 Group (a) and (b) into one combined batch.
 
@@ -101,7 +101,7 @@ Invoke [`per-comment-replies.md`](per-comment-replies.md) with the actionable re
 
 - `last_seen.cycles_completed` += 1
 - `last_seen.last_pushed_sha` = the new head SHA (update.md already wrote this; verify)
-- `last_seen.reviewId` = max(input review ids ∪ last_seen.reviewId)
+- `last_seen.lastBodyReviewId` = max(body-only input review ids ∪ last_seen.lastBodyReviewId) — line-comment threads need no watermark; they fall out of the actionable set once the per-comment reply carries the loop marker.
 
 ### Step 5.5 — Resolve-reminder (runs every round)
 
@@ -145,5 +145,5 @@ Do **not** push, do **not** post replies, do **not** run resolve-reminder. The c
 ## Invariants
 
 - One `/muggle-do` invocation = at most one push and one resolve-reminder, regardless of how many reviews are in the batch.
-- Every input review id ends up in either the cursor (handled) or `escalated_review_ids` (skipped) — never both, never neither.
+- Every input review id ends up either handled (its thread answered with a loop-marked reply, or — for a body-only review — folded into `lastBodyReviewId`) or in `escalated_review_ids` (skipped) — never both, never neither.
 - The watcher is respawned exactly when the PR is still open at the end of the cycle.

package/plugin/skills/do/open-prs/forward.md

@@ -46,7 +46,7 @@ Write `~/.muggle-ai/muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-fo
 [{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
 ```
 
-Seed `~/.muggle-ai/muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty cursor shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `reviewId: 0`.
+Seed `~/.muggle-ai/muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty-watermark shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `lastBodyReviewId: 0`.
 
 **Do not** seed `cycle.json` or `requirements.md`. The watcher is a dumb pipe; `/muggle-do` reads reviews off GitHub.
 

package/plugin/skills/muggle-feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-feedback
-description: Use when the user wants to flag that a generated Muggle Test action script — or one specific step in it — did the wrong thing, and have it captured so Muggle can analyze and regenerate affected scripts. Covers any report that a script or step is wrong, broken, or misbehaving (clicked the wrong element, bad summary, "step N didn't work", "broken at the submit step"), whether the user just ran a test locally or remotely or pastes a Muggle dashboard run/script URL and points at what failed. Also use to view, list, or delete previously submitted feedback. Triggers on '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'flag this run', 'show/list/delete my feedback'. Auto-detects run context from a recent local run, a remote run, or a dashboard URL in the prompt.
+description: "Use when the user wants to flag that a generated Muggle Test action script — or one specific step in it — did the wrong thing, so Muggle can analyze and regenerate affected scripts. Covers any report that a script or step is wrong, broken, or misbehaving (clicked the wrong element, step N did not work, broken at the submit step), whether from a recent local/remote run or a pasted Muggle dashboard run/script URL. Also lists, views, or deletes previously submitted feedback. Triggers on /muggle-feedback, give feedback on this run, the test was wrong, flag this run."
 ---
 
 # Muggle Test Feedback

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-pr-followup
-description: Use this skill when the user wants a pull request's incoming review feedback handled for them — it watches one PR's review thread and, each time a reviewer submits new comments, dispatches the work to address them. Engage on PR-review-follow-up intent: "watch my PR and address review comments as they come in", "keep an eye on PR #123 and respond to reviewer feedback", "follow up on my PR's reviews", "babysit my PR's review thread", "auto-handle reviews on the PR I just opened", "I'm stepping away — handle my PR's reviews while I'm gone". Run with no args to track every PR you pushed this session (any repo); pass a PR URL to start watching a specific one. This is PR-review-specific automation: when the recurring thing the user wants handled is a PR's review comments, use this — not the generic `loop` skill. It only watches and dispatches; the actual edits and replies are `muggle-do`. Not for posting test results to a PR (use muggle-pr-visual-walkthrough).
+description: "Use when the user wants a pull request's incoming review feedback handled for them — it watches one PR's review thread and, each time a reviewer submits new comments, dispatches the work to address them. Engage on PR-review-follow-up intent: \"watch my PR and address review comments as they come in\", \"keep an eye on PR #123 and respond to reviewer feedback\", \"babysit my PR's review thread\", \"I'm stepping away — handle my PR's reviews while I'm gone\". This is PR-review-specific automation — prefer it over the generic loop skill. It only watches and dispatches; the actual edits and replies are muggle-do. Not for posting test results to a PR (use muggle-pr-visual-walkthrough)."
 ---
 
 # muggle-pr-followup
@@ -34,7 +34,7 @@ Bootstrap accepts three optional trailing flags:
 
 - `--slug=<name>` — override the default `<repo>-pr<n>` slug
 - `--resume` — opt in to reusing an existing session slot (default is refuse on conflict)
-- `--forward-only` — pin cursor past existing reviews (skip history). Default is cursor 0, which processes prior submitted reviews on the first tick.
+- `--forward-only` — pin `lastBodyReviewId` past existing **body-only** reviews (skip history on those). Line-comment threads are always picked up from live thread state, regardless of this flag.
 
 ## Preferences
 

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, cursor 0 (process prior reviews on the first tick), 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`/`state.md` writes minus the pre-flight block.
 
 ### Step 5 — Print the summary
 

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

@@ -17,7 +17,7 @@ Bootstrap asks **one** questionnaire — the E2E validation context the loop wil
 - `<pr-url>` matches `https?://github\.com/[^/]+/[^/]+/pull/\d+` — required.
 - `--slug=<name>` overrides the default `<repo>-pr<n>` slug.
 - `--resume` opts into refreshing an existing slot instead of refusing on conflict.
-- `--forward-only` pins the cursor past existing reviews (skip history). Default is cursor 0 — the watcher will pick up prior submitted reviews on its first tick.
+- `--forward-only` pins `lastBodyReviewId` past existing **body-only** reviews (skip history on those). It does **not** affect line-comment threads — those are always picked up from live thread state. Default is `0`.
 
 ## Procedure
 
@@ -46,12 +46,14 @@ Default: `<repo>-pr<n>` (e.g. `muggle-ai-works-pr154`). Override: `--slug=<name>
 If `~/.muggle-ai/muggle-do/sessions/<slug>/` exists (including a slot just migrated above):
 
 - Without `--resume` → exit with the slot-conflict abort. Both remedies (delete + re-run, or pass `--resume`) are spelled out in the message.
-- With `--resume` → refresh `prs.json[0].head_sha` to the current `headRefOid` from Step 2; leave `last_seen.json` and the cursor untouched. If `state.md` already has a `## Pre-flight answers` block, skip to Step 8; if not (older session), run Step 6.5 to backfill it, then skip to Step 8.
+- With `--resume` → refresh `prs.json[0].head_sha` to the current `headRefOid` from Step 2; leave `last_seen.json` untouched. If `state.md` already has a `## Pre-flight answers` block, skip to Step 8; if not (older session), run Step 6.5 to backfill it, then skip to Step 8.
 
-### Step 6 — Resolve the initial cursor
+### Step 6 — Resolve the body-only watermark
 
-- **Default (no `--forward-only`):** cursor is `0`. The watcher will pick up every existing submitted review on its first tick. This matches the common case where the user opened the PR, left review comments they want addressed, and is now running bootstrap.
-- **With `--forward-only`:** fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md), then take `max(id)`. The watcher only acts on later submissions. Use when bootstrapping a PR with stale/already-handled prior reviews you don't want re-processed.
+Line-comment threads need no seeding — the watcher derives them from live thread state on every tick, so existing unresolved threads are picked up on the first tick regardless of this step. This step only sets `lastBodyReviewId`, the narrow watermark for body-only reviews (a submitted review with no line comments).
+
+- **Default (no `--forward-only`):** `lastBodyReviewId = 0`. The watcher picks up every existing body-only review on its first tick. Matches the common case — the user opened the PR, left feedback they want addressed, and is now bootstrapping.
+- **With `--forward-only`:** fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md), then take `max(id)`. Body-only reviews at or below that id are treated as already-handled. This no longer hides existing line-comment threads — those are always picked up from thread state.
 
 ### Step 6.5 — Resolve E2E validation context
 
@@ -67,7 +69,7 @@ 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>"`), `reviewId` 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: []`.
 
 **`state.md`** — see [`state-schemas.md`](state-schemas.md#statemd). `Bootstrapped from URL: yes`. Cache the loop-user login. Append the `## Pre-flight answers` block with the fields resolved in Step 6.5, per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields).