@muggleai/works 4.11.3 → 4.12.0

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

@@ -1,190 +1,73 @@
-# PR follow-up per-tick contract
+# Watcher Per-Tick Contract
 
-Caller-agnostic per-tick contract for the [muggle-pr-followup](SKILL.md) skill. One tick = one polling iteration scoped to one PR.
+The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews, dispatches `/muggle-do` if there are any, and exits. It does not classify, amend requirements, post replies, run cycles, or escalate.
 
-## Turn preamble
-
-```
-**PR follow-up** — polling <repo>#<pr-number>, tick #<K>.
-```
-
-Resolve `<K>` from `idle_tick_count + cycles_completed` in this PR's state slot.
-
-## When this contract may break the caller's "no questions" rule
-
-Most callers' forward pipelines never ask the user mid-cycle. This loop, however, may emit a single escalation message when a submitted review is ambiguous (see [classify](#step-6-classify-the-review) below). By the time the loop is polling, the user has walked away from the forward pipeline; forcing a guess on an ambiguous review is worse than pausing.
-
-Escalation is the **only** user-facing path. Otherwise the cycle runs silently end to end.
-
-## Inputs
-
-Read these from `.muggle-<caller>/sessions/<slug>/` (the caller's session dir):
+Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The architectural rationale lives in the brain doc `architecture/2026-05-08-muggle-do-pr-comment-loop-design.md`.
 
-- `state.md` — session metadata (for context when classifying reviews).
-- `prs.json` — list of `{repo, number, url, head_sha, state, escalated?, cycling?}`. This loop touches only the entry whose `number` matches the dispatched PR number.
-- `last_seen.json` — keyed by `"<owner>/<repo>#<n>"`. For this PR: `{reviewId, last_pushed_sha, idle_tick_count, cycles_completed, escalated_review_ids[]}`.
-- `cycle.json` — caller's declared implementation cycle (see [SKILL.md](SKILL.md#caller-supplied-implementation-cycle)).
-
-If any of these don't exist or the PR isn't in `prs.json`, the tick is a no-op — log an error to `followup.log` and exit.
-
-## Per-tick contract
-
-### Step 1: Refresh this PR's state
+## Turn preamble
 
-```bash
-gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
 ```
-
-If `state` is `MERGED` or `CLOSED`, mark this entry terminal in `prs.json`. Update `head_sha` if it changed.
-
-### Step 2: Termination check
-
-If this PR is terminal: write a per-PR section into `result.md` (URL, final state, `cycles_completed`, count escalated, final SHA), emit final telemetry, **do not schedule another tick**. Other PRs in the session have their own loops; they terminate independently.
-
-### Step 3: Resolve the reviewer allow-list (every tick)
-
-```bash
-gh pr view <number> --repo <repo> --json reviewRequests,author
+**muggle-pr-followup tick** — polling <repo>#<pr-number>.
 ```
 
-Add requested reviewers. Add CODEOWNERS by parsing `.github/CODEOWNERS` (or `CODEOWNERS` / `docs/CODEOWNERS`) from the PR's head branch. Remove the PR author and any bot accounts (logins ending in `[bot]`, plus the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`).
+## Input
 
-### Step 4: Pull new submitted reviews
+`$ARGUMENTS = <slug> <pr-number>` (or `<pr-number>` alone — slug inferred from on-disk state per [`SKILL.md`](SKILL.md#routing)).
 
-```bash
-gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
-```
+## Inputs from disk
 
-Filter to reviews where:
+Read these from `.muggle-do/sessions/<slug>/`:
 
-- `submitted_at` is non-null (skip drafts — `PENDING` reviews are still being composed).
-- `id > last_seen.reviewId`.
-- `user.login` is in the allow-list.
-- `id` is not in `escalated_review_ids`.
-- `state` is `CHANGES_REQUESTED` or `COMMENTED`, OR `APPROVED` with at least one line comment or a non-empty body.
+- `prs.json` — see [`state-schemas.md`](state-schemas.md#prsjson). The watcher touches the single entry whose `number` matches the dispatched PR number.
+- `last_seen.json` — see [`state-schemas.md`](state-schemas.md#last_seenjson). Keyed by `"<owner>/<repo>#<n>"`.
 
-### Step 5: Pick the oldest new review
+If either file is missing or the PR is not in `prs.json`, the tick is a no-op. Log an error line in `followup.log` and exit. The watcher must not be invoked in this state — if it happens, the slot is corrupt.
 
-If no new review past the cursor: increment `idle_tick_count`, append a heartbeat line to `followup.log`, exit. Next tick fires in 1 min via `/loop`.
+## Procedure
 
-If one or more: take the oldest by `submitted_at`. Fetch its associated line comments (`gh api repos/<owner>/<repo>/pulls/<n>/comments` filtered by `pull_request_review_id`). Reset `idle_tick_count` to 0.
+### Step 1 — Refresh PR state
 
-**At most one review per tick.** If two reviews land between ticks, the second waits.
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response.
 
-### Step 6: Classify the review
+### Step 2 — Termination check
 
-Apply the classify rule in [`../_shared/pr-followup-helpers.md`](../_shared/pr-followup-helpers.md). The rule applies to the **review as a unit**. Two outcomes:
+If `state` is `MERGED` or `CLOSED`:
 
-- **Actionable** → continue to Step 7.
-- **Ambiguous** → continue to Step 8.
+1. Mark the entry terminal in `prs.json`.
+2. Write `result.md` per [`state-schemas.md`](state-schemas.md#resultmd).
+3. Append a terminal line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `terminal: true` per [`../_shared/telemetry-events/pr-followup-tick.md`](../_shared/telemetry-events/pr-followup-tick.md).
+5. Exit. **Do not schedule another tick.** The `/loop` framework stops invoking this skill once it sees no follow-up dispatch.
 
-### Step 7: Dispatch the implementation cycle
+### Step 3 — Fetch new submitted reviews
 
-When the review is actionable:
+Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
 
-1. **Pause polling** for this PR (set `cycling: true` on this PR's entry in `prs.json`).
-2. **Amend `requirements.md`** in the session dir with a new `## Amendment — review <review_id> by <login> (<timestamp>)` section pasting the review body and each comment (with `<file>:<line>` context).
-3. **Invoke the implementation cycle** declared in the caller's `cycle.json`. Iterate the `steps[]` in order. Each step is either a markdown file to follow, a skill to invoke, or a shell command (per the `cycle.json` schema in SKILL.md). When a step fails, the cycle returns `failed: <step-name>`; the loop escalates per Step 8 with the failure as the reason.
-4. **Push** via `cycle.json`'s `pushHandler`. Set `last_seen.last_pushed_sha` to the new HEAD.
-5. **Reply** per [helpers § Reply routing](../_shared/pr-followup-helpers.md#reply-routing) and [§ Classify](../_shared/pr-followup-helpers.md#classify) (reply shape). For each line comment in the review, derive `<attribution>` from `git diff <last_pushed_sha>..HEAD -- <comment.path>` near `comment.line` ±5 (fall back to `addressed indirectly — see walkthrough` if empty). `<status>` = `ran clean` or `had <N> failures, see walkthrough`. If the review is body-only (no line comments), post the top-level fallback shape; if both body and line comments, threaded replies cover it — no top-level.
-6. **Resume polling**: clear `cycling: true`, increment `cycles_completed`, advance `last_seen.reviewId` past this review.
-7. Emit per-cycle telemetry.
+### Step 4 — If zero new reviews → idle
 
-If the cycle returns `failed: design-adjustment` (the cycle discovered the review can't be implemented without rethinking the design itself, not just the code), escalate per Step 8 with a `design-adjustment` reason — the terminal message asks the user to confirm the design intent before retrying.
+1. Increment `last_seen.idle_tick_count`.
+2. Append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+3. Emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`.
+4. Exit. The next tick fires in 1 min via `/loop`.
 
-### Step 8: Escalate
+### Step 5 — If one or more new reviews → dispatch
 
-When the review is ambiguous, or the cycle failed:
+The watcher does **not** classify. Classification, batching, replying, escalation, and cycle execution all live in `/muggle-do`. The watcher's job is to hand over the list of new review ids and exit.
 
-1. Add the review id to `last_seen.escalated_review_ids`.
-2. Append a `followup.log` entry describing the review and the reason.
-3. Pause this PR's loop by writing `escalated: true` against this PR's entry in `prs.json`.
-4. End the turn with a **single terminal message** to the user:
+1. Reset `last_seen.idle_tick_count` to 0.
+2. Dispatch `/muggle-do` with an *address-reviews* directive carrying:
+   - PR URL (from `prs.json[0].url`)
+   - Session slug (from the invocation arguments)
+   - Every new review id from Step 3, as a space-separated list
 
-```
-**PR follow-up escalation — <repo>#<number> — review <review_id>**
-
-<reviewer-login> submitted a review I can't act on coherently:
-
-> <quoted review body, or "(no body)" if empty>
-
-Comments:
-- <file>:<line> — <quoted comment body>
-
-[For ambiguous]
-Best two interpretations:
-1. <one-line interpretation A>
-2. <one-line interpretation B>
-
-[For cycle failure]
-The implementation cycle failed at <step-name>: <reason>.
-
-Reply on the review yourself, leave a follow-up comment, or tell me which way to go.
-```
-
-The user clears the escalation by replying on GitHub (next tick sees a new submitted review past the cursor) or by giving a directive in this terminal session.
-
-### Step 9: Emit tick-summary telemetry and exit
-
-Emit one tick event per `muggle-local-telemetry-skill-emit`. Exit the turn.
-
-## Reply routing
-
-- **Threaded reply per line comment** (default): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies`. Use for every line comment in the review so each thread can be resolved in GitHub's UI.
-- **Top-level summary on a body-only review** (fallback): `gh pr comment <number> --body "..."` referencing the review id and the new SHA. Used only when the review has body content and zero line comments — GitHub has no "reply to a review body" endpoint.
-- **Never post the same reply twice** — `last_seen.reviewId` is the only re-entry guard.
-- **Never post a top-level summary alongside threaded replies** — duplication pollutes the Conversation tab.
-
-## Telemetry
-
-**Per-cycle** (one event per actionable review handled):
-
-```json
-{
-  "skill": "muggle-pr-followup",
-  "event": "cycle",
-  "caller": "<caller>",
-  "session_slug": "<slug>",
-  "repo": "<repo>",
-  "pr_number": <n>,
-  "review_id": <id>,
-  "outcome": "pushed|escalated|failed:<step>",
-  "comment_count": <count>,
-  "head_sha_before": "<sha>",
-  "head_sha_after": "<sha-or-null>"
-}
-```
-
-**Per-tick summary** (always one, even idle):
-
-```json
-{
-  "skill": "muggle-pr-followup",
-  "event": "tick",
-  "session_slug": "<slug>",
-  "repo": "<repo>",
-  "pr_number": <n>,
-  "reviews_seen": <count>,
-  "review_picked": true|false,
-  "cycle_dispatched": true|false,
-  "tick_duration_ms": <ms>
-}
-```
+   Exact phrasing belongs to `/muggle-do`'s intent-routing. A reasonable shape is:
+   ```
+   /muggle-do address reviews <id1> <id2> ... on <pr-url> slug=<slug>
+   ```
+3. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
+5. Exit. **Do not schedule another tick.** `/muggle-do` will respawn the watcher at the end of its cycle.
 
 ## Output
 
-This stage produces no console output beyond:
-- The turn preamble (always).
-- An escalation terminal message (only when escalating).
-- The final `result.md` summary section for this PR (only on the terminating tick — written to disk, not printed).
-
-## Self-check before ending the turn
-
-- [ ] `last_seen.json` advanced for any review handled.
-- [ ] `prs.json` reflects current state (terminal marked; `escalated`/`cycling` flags consistent).
-- [ ] `followup.log` has at minimum a heartbeat or per-review line for this tick.
-- [ ] Telemetry events emitted (per-cycle when applicable + per-tick).
-- [ ] If pushed, `last_pushed_sha` is set and `cycles_completed` incremented.
-- [ ] If actionable, one threaded reply posted per line comment (or one top-level reply for body-only reviews) — never both, never zero.
-- [ ] If escalated, `escalated_review_ids` contains the review id.
-- [ ] If terminal, the loop is NOT continued.
+No console output beyond the turn preamble and (if Step 5 fires) the `/muggle-do` dispatch. The watcher is invisible to the reviewer.

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

@@ -0,0 +1,42 @@
+# Bootstrap output templates
+
+## Success summary (printed just before dispatch)
+
+```
+Bootstrapped PR follow-up for <owner>/<repo>#<n>
+  Slug:           <slug>
+  Cursor:         review #<id> (forward-only) | empty (no prior reviews)
+  Working tree:   <toplevel>
+  Dispatching:    /loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+## Aborts
+
+**Terminal PR:**
+```
+PR <owner>/<repo>#<n> is <state>; nothing to poll. Bootstrap aborted.
+```
+
+**Wrong working tree / wrong branch:**
+```
+Bootstrap needs the PR's branch checked out locally.
+Current cwd:    <toplevel-or-"not in a git repo">
+Current branch: <HEAD-or-"n/a">
+Expected:       a clone of <owner>/<repo> on branch <headRefName>.
+From that clone, run: gh pr checkout <n>
+```
+
+**Slot conflict (no `--resume`):**
+```
+Session <slug> already exists at <path>.
+To reuse it, pass --resume on this invocation.
+To start fresh, rm -rf the directory and re-run.
+```
+
+**Malformed URL:**
+```
+Could not parse <input> as a GitHub PR URL.
+Expected: https://github.com/<owner>/<repo>/pull/<number>
+```
+
+**GitHub API failure (PR not found, no auth, etc.):** repeat the underlying `gh` error verbatim. Do not paraphrase.

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

@@ -0,0 +1,32 @@
+# Escalation messages
+
+Emitted by `/muggle-do` in address-reviews mode. One per invocation, at most. Anchored here so wording stays consistent.
+
+## Ambiguous escalation
+
+```
+**Review-followup escalation — <owner>/<repo>#<n>**
+
+I can't act on <count> review(s) without your input. Listed below; reply on GitHub by submitting a new review with clearer direction, or tell me here which way to go.
+
+Review #<id> from <login>:
+> <body or "(no body)">
+
+Comments:
+- <file>:<line> — <body>
+- ...
+
+[Repeat per ambiguous review in the batch.]
+```
+
+## Design-adjustment escalation
+
+```
+**Design-adjustment needed — <owner>/<repo>#<n>**
+
+While addressing review #<id>, the cycle surfaced a conflict with the current design:
+
+  <one-paragraph description of the conflict>
+
+This is beyond a routine code change. Confirm the design intent (reply here, or update the requirements doc) before I retry.
+```

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

@@ -0,0 +1,17 @@
+# Help output
+
+For `/muggle:muggle-pr-followup` with no args, or with `help` / `?`:
+
+```
+muggle-pr-followup — watcher loop for PR review follow-ups
+
+Active loops:
+  <slug> → <owner>/<repo>#<n> (cursor @ review #<id>, <N> cycles)
+  ...
+  (or "no active loops")
+
+Usage:
+  /muggle:muggle-pr-followup <pr-url>            → bootstrap a new loop
+  /muggle:muggle-pr-followup <slug> <pr-number>  → run one tick (called by /loop)
+  /muggle:muggle-pr-followup <pr-number>         → run one tick (slug inferred from on-disk state)
+```

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

@@ -0,0 +1,17 @@
+# Per-comment inline reply
+
+Posted via `gh api .../comments/<comment-id>/replies` per cycle, one per line comment.
+
+```
+Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
+```
+
+`<short-sha>` is the first 7 chars of the new SHA. The body must contain that substring — the resolve-reminder stage greps for it to classify threads as addressed-by-loop.
+
+## Top-level fallback (review-body-only)
+
+When an actionable review has a non-empty body but zero line comments, GitHub has no `/replies` endpoint for the body. Post a top-level PR comment instead, at most once per such review:
+
+```
+Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
+```

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

@@ -0,0 +1,12 @@
+# Resolve-reminder top-level PR comment
+
+Posted via `gh pr comment` after the resolve-reminder stage scans threads. Only when at least one addressed-by-loop thread exists.
+
+```
+I addressed these threads in <short-sha> — mark them resolved when satisfied:
+- #<thread-id-1>
+- #<thread-id-2>
+- ...
+```
+
+If `addressed_by_loop == 0`, no comment is posted (silent).

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

@@ -0,0 +1,21 @@
+# 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`.
+
+## Idle tick
+
+```
+<ISO-8601> tick pr=<n> reviews_seen=0 idle
+```
+
+## Dispatching tick
+
+```
+<ISO-8601> tick pr=<n> reviews_seen=<count> dispatched=<id1>,<id2>,...
+```
+
+## Terminal tick
+
+```
+<ISO-8601> tick pr=<n> terminal=<merged|closed> result.md written
+```

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

@@ -0,0 +1,14 @@
+# Output templates
+
+All user-facing message text used by the watcher, bootstrap, and `/muggle-do` in address-reviews mode. Each template group is its own file — load only what the current step emits.
+
+## Index
+
+| 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). |
+| [`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. |
+| [`help`](output-templates/help.md) | Skill help output (no args / `help` / `?`). |

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

@@ -0,0 +1,104 @@
+# Session State Schemas
+
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `.muggle-do/sessions/<slug>/` (the caller's session dir; `muggle-do` is the current and only caller).
+
+All files are atomic writes — the caller rewrites the whole file each time, never mutates in place. Use a temp file + rename if the platform supports it.
+
+## `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>",
+    "number": <int>,
+    "url": "https://github.com/<owner>/<repo>/pull/<number>",
+    "head_sha": "<40-char-hex-sha>",
+    "state": "open" | "merged" | "closed"
+  }
+]
+```
+
+- `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.
+
+## `last_seen.json`
+
+Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
+
+```json
+{
+  "<owner>/<repo>#<n>": {
+    "reviewId": <int>,
+    "last_pushed_sha": "<sha-or-null>",
+    "idle_tick_count": <int>,
+    "cycles_completed": <int>,
+    "escalated_review_ids": [<int>, ...],
+    "pushed_shas": ["<sha>", ...]
+  }
+}
+```
+
+- `reviewId`: the cursor. The watcher fetches reviews with `id > reviewId`. Bootstrap pins this to the highest existing submitted review id (or `0` if none).
+- `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 that sees zero new reviews. 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 future review fetches 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.
+
+## `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>
+
+...free-form notes added by /muggle-do and bootstrap...
+```
+
+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 reviews_seen=0 idle
+2026-05-20T12:35:56Z tick pr=154 reviews_seen=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 (cursor pinned at <reviewId>)
+- <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.

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

@@ -180,15 +180,15 @@ Bulk regen does not run replays, so the section B (replay) router does not apply
 
 ### Step 8 — Open the Dashboard
 
-Open the Muggle AI dashboard so the user can watch progress visually:
+Open the Muggle AI dashboard so the user can watch progress visually. Point them at the **scripts** page (where DRAFT → GENERATING → ACTIVE transitions are visible), not `/runs` (which is for replay batches and shows nothing for a regen):
 
 ```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
+open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts"
 ```
 
 Tell them:
 
-> "I've opened the project's runs page. Generation jobs typically take a few minutes each — they'll appear here as they progress. Your test cases will move into `ACTIVE` status as scripts complete."
+> "I've opened the project's scripts page. Generation jobs typically take a few minutes each — your test cases will move from `DRAFT` through `GENERATING` to `ACTIVE` as scripts complete."
 
 ### Step 9 (optional) — Poll Status
 

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.11.3",
-  "buildId": "run-36-1",
-  "commitSha": "b2f2343428698517af23e12cbf2d3fe505f923fe",
-  "buildTime": "2026-05-20T18:23:15Z",
+  "release": "4.12.0",
+  "buildId": "run-38-1",
+  "commitSha": "8a01015dc5a95c7b5a34e982132e8ca4a1c0d9f1",
+  "buildTime": "2026-05-21T18:38:53Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-NJUUHKPW.js → src-ARTTHWNP.js}

@@ -1 +1 @@
-export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-AYWLYB3F.js';
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, buildElectronAppChecksumsUrl, buildElectronAppReleaseAssetUrl, buildElectronAppReleaseTag, calculateFileChecksum, createApiKeyWithToken, createChildLogger, deleteApiKeyData, deleteCredentials, e2e_exports as e2e, formatPreferencesOneLiner, getApiKey, getApiKeyFilePath, getAuthService, getBundledElectronAppVersion, getCallerCredentials, getCallerCredentialsAsync, getChecksumForPlatform, getConfig, getCredentialsFilePath, getDataDir, getDownloadBaseUrl, getElectronAppChecksums, getElectronAppDir, getElectronAppVersion, getElectronAppVersionSource, getLocalQaTools, getLogger, getPlatformKey, getQaTools, getValidApiKeyData, getValidCredentials, hasApiKey, isElectronAppInstalled, isFirstRun, loadApiKeyData, loadCredentials, local_exports as localQa, mcp_exports as mcp, openBrowserUrl, performLogin, performLogout, pollDeviceCode, e2e_exports as qa, readGlobalPreferences, readProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-I4VLYJ7M.js';

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.11.3",
+    "version": "4.12.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",
@@ -41,14 +41,14 @@
         "test:watch": "vitest"
     },
     "muggleConfig": {
-        "electronAppVersion": "1.0.87",
+        "electronAppVersion": "1.0.90",
         "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
         "runtimeTargetDefault": "production",
         "checksums": {
-            "darwin-arm64": "df04c98269e22ae427bb863956215b3f20cbf2ff0b51c037647d6e734a7b7502",
-            "darwin-x64": "e9f5b8a61f4a9f47743aaabb27d6e4c462dca5aa922ba66ae04f0a0133b8a7eb",
-            "win32-x64": "75e552672757d280259637bdcbe0aae0eecc2417ed9a6e5bd49f42d3466f66cf",
-            "linux-x64": "2c8b64cf549f9a6682db959b17c5f04578d632d5bcdba1ac9efbb45d6a097802"
+            "darwin-arm64": "13fc830ede44af479761302e3477c4f2516be142885445c8c5baf574041a7069",
+            "darwin-x64": "02007eb996d2fa2cf5be6546b6a1a01de769f1b12c7e3b2af1e93eb1b4deda0e",
+            "win32-x64": "5ea49f43ce6c432eac42dd10179873c78067ff1fc1328d8f664ce2c81da38f49",
+            "linux-x64": "f92c350bde46c95fb35ceab8c1c115352663a53d44d210ea98316fe1a92cf41e"
         }
     },
     "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": "4.11.3",
+  "version": "4.12.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": "4.11.3",
+  "version": "4.12.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/scripts/ensure-electron-app.sh

@@ -3,10 +3,35 @@
 set -euo pipefail
 
 # Ensure the Electron browser test runner is installed/up to date (silent, best-effort).
-if command -v muggle >/dev/null 2>&1; then
-  muggle setup >/dev/null 2>&1 || true
-else
-  npx -y @muggleai/works setup >/dev/null 2>&1 || true
+#
+# Bounded + cached: this script runs from a SessionStart hook on every Claude
+# session, so a hung `muggle setup` (e.g. one blocked by host security policy
+# on Windows) must not leak a ~100 MB orphan per session start. We cap the
+# attempt with `timeout` and skip the call entirely if we already checked
+# within the last day.
+ensure_marker_dir="${HOME}/.cache/muggle"
+ensure_marker="${ensure_marker_dir}/electron-app-checked"
+ensure_ttl=$((24 * 60 * 60))
+
+ensure_now=$(date +%s)
+ensure_last=0
+if [ -f "${ensure_marker}" ]; then
+    ensure_last=$(stat -f %m "${ensure_marker}" 2>/dev/null || stat -c %Y "${ensure_marker}" 2>/dev/null || echo 0)
+fi
+
+if [ $((ensure_now - ensure_last)) -ge "${ensure_ttl}" ]; then
+    if command -v timeout >/dev/null 2>&1; then
+        ensure_timeout="timeout -k 5 60"
+    else
+        ensure_timeout=""
+    fi
+    if command -v muggle >/dev/null 2>&1; then
+        ${ensure_timeout} muggle setup >/dev/null 2>&1 || true
+    else
+        ${ensure_timeout} npx -y @muggleai/works setup >/dev/null 2>&1 || true
+    fi
+    mkdir -p "${ensure_marker_dir}" 2>/dev/null || true
+    touch "${ensure_marker}" 2>/dev/null || true
 fi
 
 # --- Context injection ---