@muggleai/works 5.9.0 → 5.11.0

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

@@ -11,7 +11,9 @@ Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
 
 **Startup verification** — confirm PID alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) against the log. Cap log-tail at 60 s. Halt on whatever surfaces.
 
-If a PID dies immediately, show the last 20 log lines:
+A boot that takes most of the 60 s cap but keeps making progress is a property of this stack, not a fault — record it per [record-resolution](./record-resolution.md) so the next run expects the wait instead of treating it as a hang.
+
+If a PID dies immediately, consult the recipe's recorded resolutions for this service first; apply a match without asking. Otherwise show the last 20 log lines:
 
 > "**backend-api** exited right after starting. Here's the tail of its log:"
 

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

@@ -65,7 +65,7 @@ If auth keeps failing, suggest the user run `muggle logout && muggle login` from
 
 A **project** is the unit on the Muggle AI dashboard that groups test cases, scripts, and runs. The user must pick the one to scan — never auto-select from repo name, branch, or URL heuristics.
 
-The per-repo project cache lives at `<cwd>/.muggle-ai/last-project.json` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
+The per-repo project cache lives in `~/.muggle-ai/last-project.json`, in the entry keyed on `<cwd>` (via the `muggle-local-last-project-get` / `muggle-local-last-project-set` MCP tools). Look for `Muggle Test Last Project: id=… url=… name="…"` in session context.
 
 Gate `autoSelectProject` (per `preference-gates/README.md`). Cache: `Muggle Test Last Project` session line.
 - `always` + cache → use cached `projectId`, proceed to Step 3. No cache → fall through to `ask`.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.9.0",
-  "buildId": "run-69-1",
-  "commitSha": "65137194ea9b71fb5eb97ae290869357a826b51d",
-  "buildTime": "2026-08-04T22:00:43Z",
+  "release": "5.11.0",
+  "buildId": "run-71-1",
+  "commitSha": "c63bb23b7fe35c075d6c973c07b2ac8315f274e4",
+  "buildTime": "2026-08-14T06:33:25Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/src-B5OTAZKM.js

@@ -0,0 +1 @@
+export { DEFAULT_PREFERENCES, PREFERENCES_FILE_NAME, PREFERENCES_PROJECT_DIR_NAME, PREFERENCES_SCHEMA, PREFERENCES_VERSION, PREFERENCE_ALLOWED_VALUES, PreferenceKey, PreferenceValue, ProjectPreferencesReconcileOutcome, WATCHER_LIFETIME_SECONDS, WATCHER_LIFETIME_UNBOUNDED_SECONDS, 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, reconcileProjectPreferences, resetConfig, resetLogger, resetPreference, resolveElectronAppPathOrNull, resolvePreferences, saveApiKey, saveApiKeyData, saveCredentials, startDeviceCodeFlow, toolRequiresAuth, validatePreference, verifyFileChecksum, writePreferences } from './chunk-MSPMXBO5.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.9.0",
+  "version": "5.11.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",
@@ -23,6 +23,7 @@
     "verify:plugin": "node scripts/verify-plugin-marketplace.mjs",
     "verify:contracts": "node scripts/verify-compatibility-contracts.mjs",
     "verify:skill-deps": "node scripts/check-skill-deps.mjs",
+    "verify:signatures": "node scripts/check-post-signatures.mjs",
     "smoke:cli": "node scripts/smoke-cli.mjs",
     "verify:electron-release-checksums": "node scripts/verify-electron-release-checksums.mjs",
     "verify:upgrade-experience": "node scripts/verify-upgrade-experience.mjs",
@@ -47,14 +48,14 @@
     "eval:studio-gen": "tsx internal/studio-gen-eval/src/run.ts"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.6.12",
+    "electronAppVersion": "1.9.0",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "d313b881b6f448b968c838a3b9bea4d8f226c60b703c377514d37f33d0dacd66",
-      "darwin-x64": "31f316bdcc97dbc764a9656fc3003a2640c613d6ce1f8ba1a73564987235f2f1",
-      "linux-x64": "1d06dfbf66ea97f55abfb6e3cd8a3edbea2c7c6bf75acbbd607039e7c6dae69b",
-      "win32-x64": "ff1150431afad2717e30d419d4ba15df79d20e10ae48a6293f71a723c7b3159a"
+      "darwin-arm64": "1baa38bde71b74984705bcac3e5a42a7a158a7b0574dab496f3e240846c0ac65",
+      "darwin-x64": "098cc2db6f32c7857bd933512320524d213804b378dc8bf0ade791396f058041",
+      "linux-x64": "d434a88a087c7410785a443cfe03102322fa7a295b77600f5ed92e2113e271c2",
+      "win32-x64": "0aecbc01010ab0a268137ed31bcaaa05fe9215daa9f4c0e4871b07554d28c0c8"
     }
   },
   "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.9.0",
+  "version": "5.11.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.9.0",
+  "version": "5.11.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/README.md

@@ -21,19 +21,25 @@ This updates the CLI, configures Cursor MCP (`~/.cursor/mcp.json`), and syncs `m
 
 Type `muggle` to discover the full command family.
 
-| Skill | What it does |
-|:---|:---|
-| `/muggle:muggle` | Router and menu for all Muggle Test commands. |
-| `/muggle:muggle-do` | Autonomous dev pipeline: requirements, code, unit tests, E2E acceptance tests, PR. |
-| `/muggle:muggle-test` | Change-driven E2E acceptance router: detects code changes, maps to use cases, runs test generation locally or remotely, publishes to dashboard, opens in browser, posts E2E acceptance results to PR. |
-| `/muggle:muggle-test-feature-local` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
-| `/muggle:muggle-test-import` | Import existing tests into Muggle Test — from Playwright/Cypress specs, PRDs, Gherkin feature files, test plan docs, or any test artifact. |
-| `/muggle:muggle-test-regenerate-missing` | Bulk-regenerate test scripts for every test case in a project that doesn't currently have an active script. Scans DRAFT + GENERATION_PENDING, confirms the list with the user, and dispatches remote generation workflows for each. |
-| `/muggle:muggle-status` | Health check for Electron browser test runner, MCP server, and authentication. |
-| `/muggle:muggle-repair` | Diagnose and fix broken installation automatically. |
-| `/muggle:muggle-upgrade` | Update Electron browser test runner and MCP server to latest version. |
-
-Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
+| Skill | Shorthand | What it does |
+|:---|:---|:---|
+| `/muggle:muggle` | `/m` | Router and menu for all Muggle Test commands. |
+| `/muggle:muggle-do` | `/mdo` | Autonomous dev pipeline: requirements, code, unit tests, E2E acceptance tests, PR. |
+| `/muggle:muggle-test` | `/mtest` | Change-driven E2E acceptance router: detects code changes, maps to use cases, runs test generation locally or remotely, publishes to dashboard, opens in browser, posts E2E acceptance results to PR. |
+| `/muggle:muggle-test-feature-local` | `/mtestlocal` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
+| `/muggle:muggle-test-prepare` | `/mtestprep` | Verify the dev servers and sibling services a test run needs, and start whatever is missing. |
+| `/muggle:muggle-test-import` | `/mimport` | Import existing tests into Muggle Test — from Playwright/Cypress specs, PRDs, Gherkin feature files, test plan docs, or any test artifact. |
+| `/muggle:muggle-test-regenerate-missing` | `/mregen` | Bulk-regenerate test scripts for every test case in a project that doesn't currently have an active script. Scans DRAFT + GENERATION_PENDING, confirms the list with the user, and dispatches remote generation workflows for each. |
+| `/muggle:muggle-browser-task` | `/mbt` | Perform a real action on a website from plain English — log in and submit the form, create the ticket, refund the charge. |
+| `/muggle:muggle-pr-visual-walkthrough` | `/mpr` | Post per-test-case dashboard links, step-by-step screenshots, and a pass/fail summary to a PR. |
+| `/muggle:muggle-pr-followup` | `/mprfollowup` | Watch one PR's review thread and dispatch the work to address incoming feedback. |
+| `/muggle:muggle-feedback` | `/mfeedback` | Flag a generated action script, or one step in it, as wrong so Muggle can analyze and regenerate affected scripts. |
+| `/muggle:muggle-preferences` | `/mprefs` | View, set, or reset the preferences that gate Muggle Test behavior. |
+| `/muggle:muggle-status` | `/mstatus` | Health check for Electron browser test runner, MCP server, and authentication. |
+| `/muggle:muggle-repair` | `/mrepair` | Diagnose and fix broken installation automatically. |
+| `/muggle:muggle-upgrade` | `/mupgrade` | Update Electron browser test runner and MCP server to latest version. |
+
+Every skill ships the short alias in the table above. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`). Claude Code namespaces plugin commands, so the aliases resolve as `/muggle:mtest`; mirror them into `~/.claude/commands/` to type `/mtest` bare.
 
 ## MCP Tools
 

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

@@ -16,6 +16,7 @@ The dispatch prompt carries the resolved prepare plan:
 - `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).
+- The E2E run instructions — startup order, manual steps, local gotchas — already captured from the user. Honour the recorded startup order when starting services, and write the instructions out per the readiness-report stage. Absent means the skill had nothing to record; never invent them.
 
 ## Stages
 
@@ -37,7 +38,9 @@ Track every launched process in `/tmp/muggle-test-prepare.json` exactly per the
 
 ## 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.
+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>`.
+
+Also return every problem you hit and what cleared it — signal, service, resolution — per [`../skills/muggle-test-prepare/steps/record-resolution.md`](../skills/muggle-test-prepare/steps/record-resolution.md). On a learning run the dispatcher folds these into the recipe gate; on a replay they confirm the recipe still holds. A problem you could not clear is not a resolution: report it as an exclusion with its reason. You persist none of this yourself — the dispatcher owns every write. 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
 

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

@@ -31,15 +31,22 @@ echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
 
 ## 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`:
+**Mode A (`post`)** — deliver `body`, then `comment` only if non-null. Sign each posted body per [`../skills/_shared/vcs/post-signature.md`](../skills/_shared/vcs/post-signature.md) with `--mode plain` — this post is the walkthrough's own, so the command it names is `/muggle-pr-visual-walkthrough`.
+
+**Update in place when this PR already carries a walkthrough.** A rerun after a failure must leave the PR with **one** walkthrough reflecting latest state, not a comment per attempt. Resolve which comment to update by reading the PR — never by remembering an id — so the behavior is idempotent across sessions and survives a lost session or a forgotten handle:
 
 ```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
+sign() { bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-pr-visual-walkthrough --mode plain; }
+existing=$(gh api "repos/<owner>/<repo>/issues/<prNumber>/comments" \
+  --jq '[.[] | select(.body | contains("muggle-pr-section")) | .id] | join(" ")')
 ```
 
-Report back: PR URL + whether an overflow comment was posted.
+- `existing` empty → post fresh: `jq -r '.body' … | sign | gh pr comment <prNumber> --body-file -`, then the same for `.comment` when non-null.
+- `existing` non-empty → update the first id with `body` via `gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@-`, feeding the same signed text on stdin. Handle `comment` against the second id when both exist; post it fresh when the overflow is new, and delete a now-surplus overflow comment (`gh api --method DELETE …`) so a stale tail never outlives the run it described.
+
+Match only comments carrying the sentinel — never every comment the loop user wrote — so an unrelated reply is never overwritten.
+
+Report back: PR URL, whether an overflow comment was involved, and whether this was a fresh post or an update.
 
 **Modes B/C (`render-for-new-pr` / `embed`)** — do not post, do not touch `gh`. Return the CLI output verbatim as your report:
 

package/plugin/commands/mtest.md

@@ -1,5 +1,5 @@
 ---
-description: Run change-driven E2E acceptance tests on your changes (alias for /muggle-test)
+description: Real-browser E2E on your changes — no Playwright code, screenshots on the PR (alias for /muggle-test)
 argument-hint: [optional context, e.g. "on staging"]
 allowed-tools: [Skill]
 ---

package/plugin/hooks/README.md

@@ -26,24 +26,36 @@ Enforcement is reserved for the handoffs that were being skipped: the E2E accept
 
 Each guardrail is a thin bash wrapper in `../scripts/` registered in `hooks.json`. The wrapper pipes the event payload (stdin JSON) to the bundled `../scripts/guardrails.mjs <subcommand>`, which holds the decision logic (built from `src/guardrails/`, vitest-covered). Per-session state in `~/.muggle-ai/guardrails/<session_id>.json` tracks what fired. Any *failure* degrades to `{}` (allow) — a gate blocks only by an explicit, tested decision, never by accident.
 
+Each wrapper short-circuits in shell first, so the common case never pays Node cold-start. That pre-filter is a second, looser copy of what `guardrails.mjs` matches, and it is the one place a guardrail can fail *silently*: a payload it drops — a skip marker, a reopen line, a comment edit — reaches no recorder, and the gate keeps demanding an action the user already took. Over-matching is free; under-matching is a dead escape hatch. `src/test/guardrails/hook-prefilter.test.ts` pins every payload each subcommand acts on against the wrapper guarding it, and derives the skip-marker tokens from source so a new marker is covered the moment it exists.
+
 ## Guardrails
 
 | Hook event | Wrapper | Strength | Condition | Preference | Effect |
 | :--------- | :------ | :------- | :-------- | :--------- | :----- |
 | `PostToolUse` (Bash) | `guardrail-pr-opened.sh` | advise | a `gh pr create`/`gh pr ready` just succeeded | `autoWatchPR` | start a `muggle-pr-followup` watcher on the new PR |
-| `PostToolUse` (Bash + muggle execute/replay/skill-emit MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened (execute/replay call, or the muggle-test skill's own telemetry emit — which registers a clean SKIP verdict too), or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` session state |
+| `PostToolUse` (Bash + muggle execute/replay/skill-emit MCP tools) | `guardrail-record-tests.sh` | record | a unit-test command passed, an E2E run happened (execute/replay call, or the muggle-test skill's own telemetry emit — which registers a clean SKIP verdict too), or an `echo "MUGGLE_E2E_SKIP: <reason>"` marker declared E2E un-runnable, or a walkthrough carrying the `build-pr-section` sentinel was posted / declared un-postable via `echo "MUGGLE_WALKTHROUGH_SKIP: <reason>"` | — | set `unitTestsGreen` / `e2eRun` / `e2eSkipped` / `walkthroughPosted` / `walkthroughSkipped` session state |
 | `PostToolUse` (Bash + Monitor) | `guardrail-pr-terminal.sh` | advise | a PR just went terminal — a `gh pr merge`/`gh pr close` success line or the watch monitor's `TERMINAL pr=N` exit line (never bare `"state":"MERGED"` metadata) | — | record `terminalPending`, direct the post-merge handoff: finalize the watcher slot, tear down per `autoCleanup`, offer next options via AskUserQuestion |
 | `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
-| `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
+| `PostToolUse` (Skill + muggle telemetry-skill-emit) | `guardrail-skill-stages.sh` | advise | a skill this plugin ships was invoked; its `SKILL.md` frontmatter may declare `mandatoryStages`. Registered on the skill's own MCP announcement too, so the declaration still lands if the Skill payload ever stops carrying a name | — | record `lastInvokedSkillName` + `mandatoryStages`, and name the declared files as required reading at the moment of use |
+| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped |
+| `PostToolUse` (Bash + muggle telemetry-event-emit / user-feedback-create) | `guardrail-record-stage-signals.sh` | record | a Step 6f `pre-execution-classification` emit, debug-path evidence for a failed run (a `*-failure-classified\|resolved` emit or feedback naming it), or a `MUGGLE_STAGE_SKIP` / `MUGGLE_CLASSIFY_SKIP` / `MUGGLE_DEBUG_SKIP` marker | — | set `classifiedTestCaseIds` / `debuggedRuns` / the matching skip flag |
+| `PreToolUse` (Bash) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body — or a `gh api … issues/comments/<id>` PATCH editing one — reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
+| `PreToolUse` (muggle local execute/replay) | `guardrail-classify-gate.sh` | **enforce** | `muggle-test` is the skill in play and the target test case has no `pre-execution-classification` this session | — | **deny** — run Step 6f first (it calls `muggle-remote-test-script-list`, which is where the run learns the case has never passed) or record a legitimate skip via `MUGGLE_CLASSIFY_SKIP`. Scoped to `muggle-test`, so the single-target skills that legitimately skip classification are untouched; fails open when the test case can't be resolved |
 | `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks) |
 | `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the AskUserQuestion next-options offer hasn't run since | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
+| `Stop` | `guardrail-watch-gate.sh` | **enforce** | a PR opened this session that no `muggle-do` session slot tracks | `autoWatchPR` | **block** the turn until a slot is seeded via `muggle-pr-followup` or a `MUGGLE_WATCH_SKIP` marker records a legitimate skip (releases after 3 blocks) |
+| `Stop` | `guardrail-walkthrough-gate.sh` | **enforce** | an E2E acceptance run happened this session and a PR in play — opened this session or on the working branch — carries no walkthrough in its body or comments | `postPRVisualWalkthrough` | **block** the turn until the walkthrough is posted via `muggle-pr-visual-walkthrough` or a `MUGGLE_WALKTHROUGH_SKIP` marker records a legitimate skip (releases after 3 blocks; an unreachable PR fails open to not-owed) |
+| `Stop` | `guardrail-stage-gate.sh` | **enforce** | a skill invoked this session declared `mandatoryStages` and one of those files was never opened | — | **block** the turn until the stages are read or a `MUGGLE_STAGE_SKIP` marker records a legitimate skip (releases after 3 blocks) |
+| `Stop` | `guardrail-debug-path-gate.sh` | **enforce** | a local execution returned a non-passing run this session and nothing routed it through `_shared/debug-failed-run.md` | — | **block** the turn until the run is diagnosed (its `*-failure-classified` emit or feedback naming it) or a `MUGGLE_DEBUG_SKIP: <runId> <reason>` marker clears that run (releases after 3 blocks) |
 | `UserPromptSubmit` | `guardrail-build-router.sh` | advise | a build/implement/fix request (first one this session) | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers) |
 
 ## Session-start reconcile nudge
 
 `SessionStart` (`scripts/reconcile-stale-watchers.sh`) — a standalone advisory, not part of the `guardrails.mjs` decision tree above.
 
-`muggle-pr-followup` watchers are session-only (a monitor or `/loop` cron); they die with their session, leaving open PRs with no live poller. This is by design — a review is addressed only inside a session that carries the context to address it. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them at the next session start — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs Claude tools a shell hook can't call. So this hook nudges rather than acts: it scans `~/.muggle-ai/muggle-do/sessions/*/` for open slots (a `prs.json` with no `result.md`) and, **only when one or more exist**, injects `additionalContext` telling the agent to run `/muggle:muggle-pr-followup reconcile`. Zero open slots → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
+`muggle-pr-followup` watchers are session-only (a monitor or `/loop` cron); they die with their session, leaving open PRs with no live poller. This is by design — a review is addressed only inside a session that carries the context to address it. The skill's [`reconcile`](../skills/muggle-pr-followup/reconcile.md) procedure recovers them at the next session start — finalizes slots whose PR went terminal, sweeps orphan crons, re-arms silently-stopped open watchers — but re-arming needs Claude tools a shell hook can't call. So this hook nudges rather than acts.
+
+The nudge counts only slots **this session owns**, and reports the rest as orphans it will not act on — ownership and the recovery rules it gates are defined in [`reconcile`](../skills/muggle-pr-followup/reconcile.md). Nothing owned and nothing orphaned → it emits nothing. A pure directory scan (no `gh`, no writes), so it's cheap enough for every session start.
 
 ## Session-start state GC
 

package/plugin/hooks/hooks.json

@@ -36,6 +36,17 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*(execute-test-generation|execute-replay)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-classify-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -59,6 +70,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-terminal.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-signals.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       },
@@ -73,6 +90,50 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*muggle.*(telemetry-event-emit|user-feedback-create)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-signals.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-skill-stages.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*muggle.*telemetry-skill-emit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-skill-stages.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-record-stage-read.sh\"",
+            "async": false,
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Monitor",
         "hooks": [
@@ -116,6 +177,24 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-watch-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-walkthrough-gate.sh\"",
+            "async": false,
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-stage-gate.sh\"",
+            "async": false,
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-debug-path-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

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

@@ -110,6 +110,10 @@ version_check() {
 version_check || true
 
 # --- Preferences injection ---
+# Preferences are user-level: defaults overlaid by the global file only. A legacy
+# <cwd>/.muggle-ai/preferences.json is left on disk but no longer read, so the
+# keys it can no longer apply are named once — the stamp file suppresses the
+# repeat until that key set changes.
 prefs_global_file="${HOME}/.muggle-ai/preferences.json"
 prefs_line=""
 prefs_file_note=""
@@ -119,8 +123,13 @@ if [ -f "$prefs_global_file" ]; then
   # Uses node for reliable JSON parsing (already required for muggle).
   prefs_line=$(node -e "
     const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
     try {
-      const g = JSON.parse(fs.readFileSync('${prefs_global_file}', 'utf-8')).preferences || {};
+      // Resolved through node, not the shell's \$HOME: under Git Bash the shell
+      // reports a POSIX path that Windows node cannot open.
+      const globalFile = path.join(os.homedir(), '.muggle-ai', 'preferences.json');
+      const g = JSON.parse(fs.readFileSync(globalFile, 'utf-8')).preferences || {};
       const defaults = {
         autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
         showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
@@ -131,15 +140,30 @@ if [ -f "$prefs_global_file" ]; then
         autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
         autoE2ETest:'always', autoRouteBuildToMuggleDo:'ask'
       };
+      const resolved = { ...defaults, ...g };
+      const line = Object.entries(resolved).map(([k,v]) => k+'='+v).join(' ');
+      const blocks = ['Muggle Test Preferences (~/.muggle-ai/preferences.json):\\\\n' + line];
+
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-      const pPath = require('path').join(cwd, '.muggle-ai', 'preferences.json');
+      const pPath = path.join(cwd, '.muggle-ai', 'preferences.json');
       let p = {};
       try { p = JSON.parse(fs.readFileSync(pPath, 'utf-8')).preferences || {}; } catch {}
-      const merged = { ...defaults, ...g, ...p };
-      const hasProject = Object.keys(p).length > 0;
-      const note = hasProject ? ', project overrides active' : '';
-      const line = Object.entries(merged).map(([k,v]) => k+'='+v).join(' ');
-      console.log('Muggle Test Preferences (~/.muggle-ai/preferences.json' + note + '):\\\\n' + line);
+      const inertKeys = Object.keys(p).filter((k) => p[k] !== resolved[k]).sort();
+      if (inertKeys.length > 0) {
+        const stampDir = path.join(os.homedir(), '.cache', 'muggle');
+        const stampFile = path.join(stampDir, 'project-prefs-inert');
+        const stamp = cwd + '|' + inertKeys.join(',');
+        let lastStamp = '';
+        try { lastStamp = fs.readFileSync(stampFile, 'utf-8'); } catch {}
+        if (lastStamp !== stamp) {
+          try { fs.mkdirSync(stampDir, { recursive: true }); fs.writeFileSync(stampFile, stamp); } catch {}
+          blocks.push(
+            'Muggle Test: per-project preferences were removed — ' + pPath + ' is no longer read, so these keys no longer take effect: ' + inertKeys.join(', ') + '.\\\\n' +
+            'Tell the user to re-apply any they want everywhere with \`/muggle-preferences\`; the file is safe to delete.'
+          );
+        }
+      }
+      console.log(blocks.join('\\\\n\\\\n'));
     } catch { console.log(''); }
   " 2>/dev/null || true)
   if [ -n "$prefs_line" ]; then
@@ -149,53 +173,44 @@ else
   prefs_file_note="\\n\\nMuggle Test Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
 fi
 
-# --- Last-project cache injection ---
-# Per-repo "last used Muggle Test project" cache. Lives at <cwd>/.muggle-ai/last-project.json
-# and is honored by skills when autoSelectProject = always.
-last_project_line=""
-last_project_note=""
-last_project_line=$(node -e "
-  const fs = require('fs');
-  const path = require('path');
-  try {
-    const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-    const lpPath = path.join(cwd, '.muggle-ai', 'last-project.json');
-    if (!fs.existsSync(lpPath)) { console.log(''); return; }
-    const raw = JSON.parse(fs.readFileSync(lpPath, 'utf-8'));
-    const lp = raw && raw.lastProject;
-    if (!lp || !lp.projectId) { console.log(''); return; }
-    const safeName = String(lp.projectName || '').replace(/\"/g, '\\\\\"');
-    console.log('Muggle Test Last Project: id=' + lp.projectId + ' url=' + lp.projectUrl + ' name=\"' + safeName + '\"');
-  } catch { console.log(''); }
-" 2>/dev/null || true)
-if [ -n "$last_project_line" ]; then
-  last_project_note="\\n\\n${last_project_line}"
-fi
-
-# --- Last-host cache injection ---
-# Per-repo cache of the local dev server URL the user picked on the previous
-# run. Lives at <cwd>/.muggle-ai/last-host.json. Skills silently reuse it
-# when the user has set the autoSelectLocalHost preference to "always".
-last_host_line=""
-last_host_note=""
-last_host_line=$(node -e "
+# --- Last-used cache injection ---
+# The "last used Muggle Test project" and "last used local dev server URL"
+# caches live in ~/.muggle-ai/, keyed by working directory, and are honored by
+# skills when autoSelectProject / autoSelectLocalHost = always. A cache written
+# before the move to the home directory still sits in <cwd>/.muggle-ai/ and is
+# read as a fallback, so those sessions keep their context lines.
+last_cache_notes=""
+last_cache_notes=$(node -e "
   const fs = require('fs');
+  const os = require('os');
   const path = require('path');
   try {
     const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-    const lhPath = path.join(cwd, '.muggle-ai', 'last-host.json');
-    if (!fs.existsSync(lhPath)) { console.log(''); return; }
-    const raw = JSON.parse(fs.readFileSync(lhPath, 'utf-8'));
-    const lh = raw && raw.lastHost;
-    if (!lh || !lh.host) { console.log(''); return; }
-    console.log('Muggle Test Last Host: ' + lh.host);
+    const parseFile = (filePath) => {
+      try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); } catch { return null; }
+    };
+    const readEntry = (fileName, legacyEntryKey) => {
+      const home = parseFile(path.join(os.homedir(), '.muggle-ai', fileName));
+      const homeEntry = home && home.entries && home.entries[path.resolve(cwd)];
+      if (homeEntry) { return homeEntry; }
+      const legacy = parseFile(path.join(cwd, '.muggle-ai', fileName));
+      return (legacy && legacy[legacyEntryKey]) || null;
+    };
+    const lines = [];
+    const lastProject = readEntry('last-project.json', 'lastProject');
+    if (lastProject && lastProject.projectId) {
+      const safeName = String(lastProject.projectName || '').replace(/\"/g, '\\\\\"');
+      lines.push('Muggle Test Last Project: id=' + lastProject.projectId + ' url=' + lastProject.projectUrl + ' name=\"' + safeName + '\"');
+    }
+    const lastHost = readEntry('last-host.json', 'lastHost');
+    if (lastHost && lastHost.host) {
+      lines.push('Muggle Test Last Host: ' + lastHost.host);
+    }
+    console.log(lines.map((line) => '\\\\n\\\\n' + line).join(''));
   } catch { console.log(''); }
 " 2>/dev/null || true)
-if [ -n "$last_host_line" ]; then
-  last_host_note="\\n\\n${last_host_line}"
-fi
 
-context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle Test launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}${last_project_note}${last_host_note}"
+context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle Test launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}${last_cache_notes}"
 
 escaped_context=$(escape_for_json "$context")
 

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

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# pre-execution-classification gate (PreToolUse/muggle local execution tools).
+# Denies a generation or replay whose test case was never classified per
+# muggle-test Step 6f. That step calls muggle-remote-test-script-list, which is
+# where the run finds out the test case has never passed or has failed
+# repeatedly — the check is free before dispatch and costs a full browser run
+# once skipped.
+#
+# The pre-filter re-states the execution tool names the gate acts on, so an
+# unrelated payload never pays Node cold-start. It stays cheap by construction:
+# an execution call happens minutes apart and burns a real browser, so the spawn
+# is noise against what it protects. Degrades to {}.
+payload="$(cat)"
+
+if ! grep -Eiq 'muggle-local-(execute-test-generation|execute-replay)' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" classify-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-debug-path-gate.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# debug-path gate (Stop). When a run failed this session and never went through
+# _shared/debug-failed-run.md, block the turn end naming the run (or the
+# MUGGLE_DEBUG_SKIP escape hatch). muggle-test Step 7C marks that routing
+# mandatory and it was still routinely skipped, so failures were summarized and
+# dropped — the run a reviewer most needs to see is the one nobody looked at.
+#
+# Mirrors guardrail-watch-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 failed run is recorded and unresolved. On the overwhelming majority
+# of turns nothing failed, so the state file is absent or failedRuns is empty and
+# we return {} in-shell. The evidence join runs in guardrails.mjs. 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 `"failedRuns": []` (one line); a non-empty array
+# spans lines, so the empty match reliably tells them apart.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"failedRuns"' "$state_file" \
+  || grep -q '"failedRuns": \[\]' "$state_file" \
+  || grep -q '"debugSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" debug-path-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-pr-terminal.sh

@@ -9,10 +9,14 @@ set -uo pipefail
 # AskUserQuestion offer runs. Decision logic lives in the bundled guardrails.mjs.
 #
 # Fires after every Bash call, so a keyword pre-filter for the terminal output
-# shapes keeps Node off the hot path. Degrades to {} so it never blocks.
+# shapes keeps Node off the hot path. The reopen line belongs here too: it is
+# the one signal that retracts a terminal verdict, and while the pre-filter
+# dropped it a close+reopen — routine, to re-fire a lost workflow trigger — left
+# the handoff armed on a change that is open again. Degrades to {} so it never
+# blocks.
 payload="$(cat)"
 
-if ! grep -Eiq 'merged pull request|closed pull request|TERMINAL pr=' <<<"$payload"; then
+if ! grep -Eiq '(merged|closed|reopened) pull request|TERMINAL pr=' <<<"$payload"; then
   printf '{}'
   exit 0
 fi