@muggleai/works 5.8.0 → 5.9.0

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

@@ -1,129 +1,130 @@
----
-name: muggle-test-prepare
-model: opus
-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
-
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-prepare"`.
-
-Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
-
-Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
-
-## Privacy Boundary
-
-This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
-
-- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
-- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
-- **Never traverse upward more than one level** from the current working directory to list folders.
-
-## PID Tracking
-
-All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
-
-```json
-{
-  "session_started": "2025-01-15T10:30:00Z",
-  "testing_scope": "frontend",
-  "excluded_services": [
-    {"name": "payment-gateway", "reason": "Needs production certificates"}
-  ],
-  "services": [
-    {
-      "name": "backend-api",
-      "dir": "/Users/user/Github/backend-api",
-      "command": "npm run dev",
-      "pid": 12345,
-      "port": 3001,
-      "log": "/tmp/muggle-prepare-backend-api.log"
-    }
-  ]
-}
-```
-
-`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
-
-This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge.
-
-**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
-- Option 1: "Keep them running — skip to testing"
-- Option 2: "Tear down and start fresh"
-- Option 3: "Add more services to the running set"
-
-Prune dead PIDs silently.
-
-## Preferences
-
-Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
-
-| Preference | Gates |
-|------------|-------|
-| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
-| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
-| `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
-
-## Workflow
-
-Run the stages in this order. The sequence number is display-only — it lives only in this table for at-a-glance ordering; detail files and cross-references use slugs. Each row links to its detail file; read the file when you reach the stage.
-
-| # | Stage | Summary |
-|:--|:------|:--------|
-| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); short-circuits to check-running on reuse |
-| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
-| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
-| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
-| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
-| 5 | [check-running](./steps/check-running.md) | Detect what's already listening |
-| 6 | [env-file](./steps/env-file.md) | Env file present + correct |
-| 7 | [start-commands](./steps/start-commands.md) | Determine per-service start command |
-| 8 | [fresh-install](./steps/fresh-install.md) | Auto-install deps if missing/stale |
-| 9 | [start-services](./steps/start-services.md) | Launch + two-stage readiness |
-| 10 | [smoke-test](./steps/smoke-test.md) | HTTP + body sniff + log tail; clean-restart on fail |
-| 11 | [readiness-report](./steps/readiness-report.md) | Final ready table |
-
-## Cleanup
-
-Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh".
-
-1. Read `/tmp/muggle-test-prepare.json`
-2. Skip services marked `external: true`
-3. For each managed service: `kill <pid>` (SIGTERM)
-4. Wait ~2 s, verify with `kill -0`
-5. If still alive: `kill -9 <pid>`
-6. `rm -f /tmp/muggle-prepare-*.log`
-7. `rm -f /tmp/muggle-test-prepare.json`
-
-Report:
-
-```
-Stopped 3 services:
-  backend-api    (PID 12345)
-  auth-service   (PID 12346)
-  frontend       (PID 12347)
-```
-
-## Integration Contract (for other skills)
-
-`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
-
-After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
-
-## Guardrails
-
-- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
-- **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
-- **Verify first, offer to start second** — check what's already running before proposing to start anything.
-- **The user may prefer to start services themselves** — always offer that option.
-- **Never start a process the user didn't approve.**
-- **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
-- **Never leave orphan processes untracked** — every background PID goes into the tracking file.
-- **Never kill a process the user started independently** — `external: true` survives cleanup.
-- **Never assume start commands** — verify via indicator file; confirm with user.
-- **Bail early on non-viable services** — don't start what can't run locally.
-- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
-- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
-- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
-- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.
+---
+name: muggle-test-prepare
+model: opus
+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
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-prepare"`.
+
+Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
+
+Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
+
+The skill runs in two phases because a dispatched agent has no channel back to the user. **Decide (in-session):** resolve every choice that needs a human — plan reuse, scope, exclusions, service selection, start approvals. **Execute (agent):** hand the fully-resolved plan to the `test-prepare-runner` agent (`plugin/agents/test-prepare-runner.md`); it runs the mechanical stages headless and returns the readiness verdict, or a `needs-input:` line for any decision the plan left open.
+
+## Privacy Boundary
+
+This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
+
+- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
+- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
+- **Never traverse upward more than one level** from the current working directory to list folders.
+
+## PID Tracking
+
+All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
+
+```json
+{
+  "session_started": "2025-01-15T10:30:00Z",
+  "testing_scope": "frontend",
+  "excluded_services": [
+    {"name": "payment-gateway", "reason": "Needs production certificates"}
+  ],
+  "services": [
+    {
+      "name": "backend-api",
+      "dir": "/Users/user/Github/backend-api",
+      "command": "npm run dev",
+      "pid": 12345,
+      "port": 3001,
+      "log": "/tmp/muggle-prepare-backend-api.log"
+    }
+  ]
+}
+```
+
+`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
+
+This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+
+**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
+- Option 1: "Keep them running — skip to testing"
+- Option 2: "Tear down and start fresh"
+- Option 3: "Add more services to the running set"
+
+Prune dead PIDs silently.
+
+## Preferences
+
+Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md). All three resolve in the Decide phase; the agent receives outcomes, never gates.
+
+| Preference | Gates |
+|------------|-------|
+| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
+| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
+| `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
+
+## Workflow
+
+**Decide (in-session).** Run these stages in order; read each detail file when you reach it:
+
+| # | Stage | Summary |
+|:--|:------|:--------|
+| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); on reuse, skip straight to dispatch |
+| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
+| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
+| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
+| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
+
+The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, and resolved gate outcomes.
+
+**Execute (agent).** Dispatch the `test-prepare-runner` agent (subagent type `muggle:test-prepare-runner`; bare `test-prepare-runner` where the plugin namespace is absent), synchronously, passing the resolved plan; it returns `READY` / `DEGRADED` plus the readiness table. The agent's own definition lists its stage files; in a harness with no agent/subagent facility, run the execute-phase stages ([check-running](./steps/check-running.md) through [readiness-report](./steps/readiness-report.md)) inline instead.
+
+Relay the readiness table to the user or calling skill verbatim. A `needs-input:` line from the agent names an unresolved decision — resolve it here (asking the user if needed) and re-dispatch; the agent never asks.
+
+## Cleanup
+
+Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh". Runs in-session, not in the agent.
+
+1. Read `/tmp/muggle-test-prepare.json`
+2. Skip services marked `external: true`
+3. For each managed service: `kill <pid>` (SIGTERM)
+4. Wait ~2 s, verify with `kill -0`
+5. If still alive: `kill -9 <pid>`
+6. `rm -f /tmp/muggle-prepare-*.log`
+7. `rm -f /tmp/muggle-test-prepare.json`
+
+Report:
+
+```
+Stopped 3 services:
+  backend-api    (PID 12345)
+  auth-service   (PID 12346)
+  frontend       (PID 12347)
+```
+
+## Integration Contract (for other skills)
+
+`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
+
+After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
+
+## Guardrails
+
+- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
+- **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
+- **Verify first, offer to start second** — check what's already running before proposing to start anything.
+- **The user may prefer to start services themselves** — always offer that option.
+- **Never start a process the user didn't approve** — approvals are granted in Decide and travel in the plan; the agent starts nothing outside it.
+- **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
+- **Never leave orphan processes untracked** — every background PID goes into the tracking file.
+- **Never kill a process the user started independently** — `external: true` survives cleanup.
+- **Never assume start commands** — verify via indicator file; confirm with user.
+- **Bail early on non-viable services** — don't start what can't run locally.
+- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
+- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
+- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
+- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.8.0",
-  "buildId": "run-67-1",
-  "commitSha": "f0fbb486a0d7886d880eaec3129bc53964524f01",
-  "buildTime": "2026-08-01T07:54:45Z",
+  "release": "5.9.0",
+  "buildId": "run-69-1",
+  "commitSha": "65137194ea9b71fb5eb97ae290869357a826b51d",
+  "buildTime": "2026-08-04T22:00:43Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.8.0",
+  "version": "5.9.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",
@@ -43,17 +43,18 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:gates:behavioral": "tsx internal/skill-gate-eval/src/run.ts",
+    "test:agents:behavioral": "tsx internal/agent-gate-eval/src/run.ts",
     "eval:studio-gen": "tsx internal/studio-gen-eval/src/run.ts"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.6.11",
+    "electronAppVersion": "1.6.12",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "97f7f5ba622dc3baf86457184bc44030c777d7dbac58b8c1c5418970662e7a07",
-      "darwin-x64": "c8c2745282583144b34110ef45c4745e03c03c4ac2e020c820daa51124c3fc50",
-      "linux-x64": "d85e14ed38cb8035b932aef26148934e3aec6e036b6bb80ff8927cbde901a935",
-      "win32-x64": "6e38a5b017ee5756985e1507def6c5a92d357a4bbd4e4032b6e490ad05dd09a2"
+      "darwin-arm64": "d313b881b6f448b968c838a3b9bea4d8f226c60b703c377514d37f33d0dacd66",
+      "darwin-x64": "31f316bdcc97dbc764a9656fc3003a2640c613d6ce1f8ba1a73564987235f2f1",
+      "linux-x64": "1d06dfbf66ea97f55abfb6e3cd8a3edbea2c7c6bf75acbbd607039e7c6dae69b",
+      "win32-x64": "ff1150431afad2717e30d419d4ba15df79d20e10ae48a6293f71a723c7b3159a"
     }
   },
   "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.8.0",
+  "version": "5.9.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.8.0",
+  "version": "5.9.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/agents/test-prepare-runner.md

@@ -0,0 +1,47 @@
+---
+name: test-prepare-runner
+description: "Executes a fully-resolved Muggle Test prepare plan — detects what's listening, verifies env files, fresh-installs stale deps, starts approved services, smoke-tests, and returns the readiness table. Dispatched by the muggle-test-prepare skill after all user decisions are resolved; carries the opus pin so execution never runs below its reliability floor on a cheaper session model."
+model: opus
+---
+
+# Test Prepare Runner
+
+You bring a local dev stack to verified readiness for E2E testing: detect what's already listening, verify env files, install stale dependencies, start approved services, smoke-test them, and report the readiness table. Every decision — which services, their directories, start commands and approvals, scope, exclusions, the dev-server URL — arrives resolved in the dispatch prompt from the muggle-test-prepare skill. You have no channel to the user: when the plan is missing a decision you need, return one `needs-input:` line naming it and stop — the dispatching skill resolves it (asking the user if needed) and re-dispatches.
+
+## Input contract
+
+The dispatch prompt carries the resolved prepare plan:
+
+- `services[]` — name, dir, start command, expected port, `external` flag, approval already granted.
+- `testingScope` and `excludedServices[]` (with reasons).
+- The recorded dev-server URL (from the `autoSelectLocalHost` resolution) — never invent or default a host/port; a framework default like `:3000` is not a fallback.
+- Resolved gate values the stages read (`autoRebase` outcome already applied or explicitly skipped upstream).
+
+## Stages
+
+Run these stage files from the skill, in order, exactly as written — they are the single source of truth for each stage's procedure:
+
+1. [`../skills/muggle-test-prepare/steps/check-running.md`](../skills/muggle-test-prepare/steps/check-running.md)
+2. [`../skills/muggle-test-prepare/steps/env-file.md`](../skills/muggle-test-prepare/steps/env-file.md)
+3. [`../skills/muggle-test-prepare/steps/start-commands.md`](../skills/muggle-test-prepare/steps/start-commands.md)
+4. [`../skills/muggle-test-prepare/steps/fresh-install.md`](../skills/muggle-test-prepare/steps/fresh-install.md)
+5. [`../skills/muggle-test-prepare/steps/start-services.md`](../skills/muggle-test-prepare/steps/start-services.md)
+6. [`../skills/muggle-test-prepare/steps/smoke-test.md`](../skills/muggle-test-prepare/steps/smoke-test.md)
+7. [`../skills/muggle-test-prepare/steps/readiness-report.md`](../skills/muggle-test-prepare/steps/readiness-report.md)
+
+Where a stage file offers the user a choice, take the branch the plan resolved; where the plan doesn't cover it, return `needs-input:` — never guess, never start anything unapproved.
+
+## PID tracking
+
+Track every launched process in `/tmp/muggle-test-prepare.json` exactly per the skill's schema (`session_started`, `testing_scope`, `excluded_services`, `services[]` with pid/port/log). Processes the user started independently stay `external: true` and are never killed. Prune dead PIDs silently.
+
+## Output contract
+
+Return the readiness-report table verbatim as your report, prefixed by one line: `READY` (all services green), `DEGRADED: <which service, why>` (something is up but failed its smoke test after the clean-restart loop), or `needs-input: <decision>`. The dispatcher relays this to its caller — other skills gate on it, so a wrong `READY` is expensive; when in doubt between READY and DEGRADED, pick DEGRADED and say why. `needs-input:` is only for a decision the plan failed to resolve (a missing URL, an unapproved start, an unknown directory) — a service that stays broken after the loop is `DEGRADED` with the diagnosis, never `needs-input:`, even when no further automated fix exists. Repairing the app's own source code is out of scope entirely: a source-level bug surfaced by the smoke test is a `DEGRADED` diagnosis to report, not a decision to escalate.
+
+## Guardrails
+
+- Privacy boundary as the skill defines it: file contents only inside directories the plan names; never traverse upward past one level.
+- Port-listening is never enough — smoke-test (HTTP + body sniff + log tail) is mandatory before the report.
+- Clean Restart is the first fix in the smoke-test loop; fresh-install notifies, doesn't ask.
+- Never leave an orphan process untracked; never kill an `external` one.

package/plugin/agents/visual-walkthrough-builder.md

@@ -0,0 +1,58 @@
+---
+name: visual-walkthrough-builder
+description: "Renders the Muggle Test E2E visual walkthrough for a PR — assembles the E2eReport, runs `muggle build-pr-section`, and either posts to the PR (Mode A) or returns the rendered block to the dispatcher (Modes B/C). Dispatched by the muggle-pr-visual-walkthrough skill; carries its sonnet pin so the render runs on sonnet regardless of the session model."
+model: sonnet
+---
+
+# Visual Walkthrough Builder
+
+You render and (in Mode A) post the Muggle Test E2E visual walkthrough. The dispatching skill has already resolved the mode, the PR, and user consent. You have no channel to the user: if an input you need is missing, return a single `needs-input:` line naming it and stop — the dispatching skill resolves it and re-dispatches.
+
+## Input contract
+
+The dispatch prompt carries:
+
+- `mode` — `post` (Mode A), `render-for-new-pr` (Mode B), or `embed` (Mode C).
+- `prNumber` + repo — Mode A only, already verified to exist.
+- The `E2eReport` JSON inline, **or** the run identifiers (`projectId`, per-test `runId`/`testCaseId` list) to assemble it from.
+
+When assembling from identifiers, follow [`../skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md). The `E2eReport` schema, required fields, and the inconclusive rule live there and in the CLI's Zod schema (`src/cli/pr-section/types.ts`) — a run that couldn't produce pass/fail is `inconclusive` with a `reason`, never dropped.
+
+## Render
+
+Pipe the report to the CLI; it writes `{"body": "...", "comment": "..." | null}`:
+
+```bash
+echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
+```
+
+- Non-zero exit → surface the CLI's stderr verbatim; do not swallow or retry blindly.
+- `comment` is non-null only in the overflow case; the CLI owns fit-vs-overflow.
+
+## Deliver
+
+**Mode A (`post`)** — post `body` as a PR comment, then `comment` only if non-null. Append the Muggle Works signature to each posted body per [`../skills/_shared/vcs/post-signature.md`](../skills/_shared/vcs/post-signature.md) — this post is the walkthrough's own, so the command it names is `/muggle-pr-visual-walkthrough`:
+
+```bash
+sig='🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
+{ jq -r '.body' /tmp/muggle-pr-section.json; printf '\n\n%s\n' "$sig"; } | gh pr comment <prNumber> --body-file -
+{ jq -r '.comment' /tmp/muggle-pr-section.json; printf '\n\n%s\n' "$sig"; } | gh pr comment <prNumber> --body-file -   # skip when null
+```
+
+Report back: PR URL + whether an overflow comment was posted.
+
+**Modes B/C (`render-for-new-pr` / `embed`)** — do not post, do not touch `gh`. Return the CLI output verbatim as your report:
+
+```
+body:
+<body>
+comment:
+<comment or null>
+```
+
+## Guardrails
+
+- Never hand-write or modify the walkthrough markdown — the CLI is the single source of truth. No custom tables, no added "Verdict" lines, no `Tested on:`/`Project:` footers; the CLI computes the verdict and emits per-test dashboard links.
+- Never invent report fields — missing `projectId`, `viewUrl`, or `screenshotUrl` → `needs-input:`, never a placeholder.
+- Never post the overflow comment when `comment` is null.
+- Never create a PR, never choose a mode — both belong to the dispatcher.

package/plugin/hooks/hooks.json

@@ -110,6 +110,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-terminal-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-watch-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

package/plugin/scripts/guardrail-watch-gate.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# watcher-arm gate (Stop). When a PR was opened this session but no watcher was
+# armed for it, block the turn end and point at the Stage-8 hand-off (or the
+# MUGGLE_WATCH_SKIP escape hatch). Mirrors guardrail-e2e-gate.sh: synchronous
+# (only a sync Stop hook can block the turn end), fires on EVERY turn end, and
+# pre-filters in shell so Node spawns only when a PR was opened this session and
+# no skip was recorded. The real owed-vs-armed decision (a sessions/*/ slot scan)
+# runs in guardrails.mjs. On the overwhelming majority of turns no PR was opened,
+# so the state file is absent or prsHandled is empty and we return {} in-shell,
+# never paying Node cold-start. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+# Empty array serializes as `"prsHandled": []` (one line); a non-empty array spans
+# lines, so the empty match reliably tells them apart. Skip Node unless a PR was
+# opened this session and no watcher skip was recorded.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"prsHandled"' "$state_file" \
+  || grep -q '"prsHandled": \[\]' "$state_file" \
+  || grep -q '"watchSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" watch-gate 2>/dev/null || printf '{}'