@muggleai/works 4.12.2 → 4.12.3

package/dist/plugin/skills/muggle-test-prepare/steps/env-file.md

@@ -0,0 +1,18 @@
+# Environment file sanity
+
+The env file is **per-repo** — don't hardcode `.env.local`. Detect by scanning `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
+
+When a dependency on an env file exists:
+
+1. Check `<cwd>/<envfile>` exists — if yes, no-op.
+2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
+3. If found:
+
+   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
+
+   - Option 1: "Yes — copy from `<sibling>`"
+   - Option 2: "No — I'll provide it another way"
+
+4. If not found anywhere, report and ask.
+
+Skip silently when no env file is referenced.

package/dist/plugin/skills/muggle-test-prepare/steps/fresh-install.md

@@ -0,0 +1,20 @@
+# Fresh install (clean-start default)
+
+Detect stack by indicator file, decide if install is missing/stale, run automatically (notify, don't ask). Only opt-out is aborting the skill.
+
+| Indicator | Stack | Stale check | Install command |
+|:----------|:------|:------------|:----------------|
+| `package.json` | Node | `node_modules/` missing OR `package-lock.json` newer than `node_modules/.package-lock.json` | `npm install --prefer-offline --no-audit --no-fund` |
+| `pyproject.toml` w/ `[tool.poetry]` | Poetry | `poetry.lock` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `poetry install --no-interaction` |
+| `pyproject.toml` (PEP 621) + `uv.lock` | uv | `uv.lock` newer than `.venv/pyvenv.cfg` | `uv sync` |
+| `requirements.txt` | pip | `requirements.txt` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `pip install -r requirements.txt` |
+| `Gemfile` | Bundler | `Gemfile.lock` newer than `vendor/bundle/` mtime | `bundle install` |
+| `composer.json` | Composer | `composer.lock` newer than `vendor/autoload.php` | `composer install --no-interaction` |
+| `pom.xml` | Maven | always (heavy — opt-in via `AskUserQuestion`) | `mvn -DskipTests install` |
+| `build.gradle*` | Gradle | always (heavy — opt-in via `AskUserQuestion`) | `gradle build -x test` |
+| `go.mod` | Go | skip — `go run`/`go build` handle deps |  |
+| `Cargo.toml` | Rust | skip — `cargo run`/`cargo build` handle deps |  |
+
+Notify one-liner: `Installing <service-name> (<stack>: <missing|stale>)…`.
+
+**Never symlink dep dirs** (`node_modules/`, `.venv/`, `vendor/bundle/`) from a sibling worktree — webpack rewrites paths via `resolve.symlinks: true` and Python/Ruby tooling has analogous issues. Run a real per-worktree install.

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

@@ -0,0 +1,28 @@
+# Identify required services & startup mode
+
+List folder names in the **parent directory** of the current working directory:
+
+```bash
+ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
+```
+
+Present folder names only (not contents). `AskUserQuestion` with `multiSelect: true`:
+
+> "Which of these need to be running for your tests?"
+
+Pre-check the ones matching the testing scope from [scope](./scope.md). Always include:
+- "Just the current project (no other services needed)"
+- "None of these — I'll tell you what I need"
+
+Include the current working directory as a candidate. If the user provides manual paths, verify they exist.
+
+**Immediately after selection**, ask startup mode:
+
+> "How do you want to handle these?"
+
+- Option 1: "Check what's running, start what's missing for me"
+- Option 2: "I'll start them myself — just verify they're up when I'm done"
+
+**Option 2**: skip [start-commands](./start-commands.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md). Wait for ready signal, then [check-running](./check-running.md), run [smoke-test](./smoke-test.md) against everything (the user-started case is exactly where the smoke test matters most), then [readiness-report](./readiness-report.md).
+
+**Option 1**: proceed through the normal flow.

package/dist/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -0,0 +1,26 @@
+# Final readiness report
+
+Only after every service passes [smoke-test](./smoke-test.md) or is skipped.
+
+```
+Service              PID      Port     Status         Smoke Test
+─────────────────────────────────────────────────────────────────
+backend-api          12345    3001     Running        ✓
+auth-service         12346    8080     Running        ✓
+frontend             12347    3000     Running        ✓
+─────────────────────────────────────────────────────────────────
+All services verified. Ready for E2E.
+```
+
+Surface skipped services so the caller knows the gap:
+
+```
+Skipped: payment-gateway — HTTP 500 on /
+```
+
+If you launched the services:
+
+```
+Logs: /tmp/muggle-prepare-*.log
+Cleanup: say "stop services" or re-invoke this skill.
+```

package/dist/plugin/skills/muggle-test-prepare/steps/rebase-check.md

@@ -0,0 +1,3 @@
+# Rebase check
+
+Gated by `autoRebase`. Fire per [`../../_shared/rebase-before-e2e.md`](../../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.

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

@@ -0,0 +1,11 @@
+# Scope (what are you testing?)
+
+`AskUserQuestion`:
+
+> "What are you testing locally?"
+
+- Option 1: "A frontend feature — I need the UI and its backend dependencies running"
+- Option 2: "A backend API — I just need the API server running"
+- Option 3: "The full stack — everything needs to be up"
+
+Scopes the rest of the workflow. Record under `testing_scope` in the tracking file. Use it later to pre-check matching service candidates in [identify-services](./identify-services.md).

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

@@ -0,0 +1,26 @@
+# Comprehensive smoke test
+
+Runs for **every** service in the tracking file, including `external: true`. Port-listening is not proof a service works — a stale dev server binds and returns 200 with a webpack error overlay.
+
+All three probes must pass:
+
+1. **HTTP** — `GET <serviceUrl>`, 3 s timeout, accept `2xx`/`3xx` (one redirect).
+2. **Body sniff** — match response body against broken-build markers in [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) → "Body sniff patterns".
+3. **Log tail** — scan last 200 lines of `/tmp/muggle-prepare-<service-name>.log` for failure patterns after the latest ready signal. Skip for `external: true` (no log).
+
+Use the primitives in `dev-server-readiness.md`. Don't re-implement.
+
+## Diagnose-and-fix loop
+
+On failure, show the concrete signal (HTTP code, sniff hit, or log line) and `AskUserQuestion`:
+
+> "**<service-name>** isn't healthy: `<signal>`. How do you want to proceed?"
+
+- Option 1: **Clean restart** (Recommended) — kill + [fresh-install](./fresh-install.md) + [start-services](./start-services.md) + re-run this step
+- Option 2: **Restart only** — kill + start-services + re-run this step
+- Option 3: **I'll fix it manually** — pause; re-run on user signal
+- Option 4: **Skip** — append to `excluded_services` with reason, continue
+
+Loop per service until pass or skip. Cap at **3 iterations** — then force a manual-intervention pause.
+
+For `external: true`, only Options 3 and 4 apply.

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

@@ -0,0 +1,29 @@
+# Determine start commands
+
+For each required service not already running, figure out how to start it. Read **only** the indicator file that exists.
+
+| Indicator | Stack | Default command | What to check |
+|:----------|:------|:----------------|:--------------|
+| `package.json` | Node.js | `npm run dev` | Read `scripts`: prefer `dev` > `start` > `serve` |
+| `Makefile` | Various | `make dev` | Existence; propose `make dev` or `make run` |
+| `Cargo.toml` | Rust | `cargo run` | Existence |
+| `go.mod` | Go | `go run .` | Existence |
+| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
+| `requirements.txt` | Python | `python app.py` | Existence |
+| `docker-compose.yml` | Docker | `docker compose up` | Existence |
+
+If no indicator found, ask the user for the start command.
+
+Present all commands in a single summary:
+
+```
+Service              Directory                          Command
+────────────────────────────────────────────────────────────────
+backend-api          ~/Github/backend-api               npm run dev
+auth-service         ~/Github/auth-service              go run .
+frontend             ~/Github/frontend                  npm run dev
+────────────────────────────────────────────────────────────────
+```
+
+- Option 1: "Looks good, start them"
+- Option 2: "I need to edit some commands"

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

@@ -0,0 +1,21 @@
+# Start services
+
+For each service, launch in the background:
+
+```bash
+cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
+echo $!
+```
+
+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:
+
+> "**backend-api** exited right after starting. Here's the tail of its log:"
+
+- Option 1: "Skip it and continue with the others"
+- Option 2: "Let me fix it — I'll re-invoke later"
+
+**Port discovery** — if the port wasn't known upfront, re-scan listening ports after startup. Record in tracking file. If not found within ~10 s, mark port unknown.

package/dist/plugin/skills/muggle-test-prepare/steps/viability-check.md

@@ -0,0 +1,21 @@
+# Viability check
+
+Some services can't run on a developer's machine by design — production secrets, HSMs, specific certificates, cloud-only infra. Don't waste time trying to start them.
+
+If the user volunteered this in their initial message, acknowledge and skip the question. Otherwise:
+
+> "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
+
+- Option 1: "All my services can run locally"
+- Option 2: "Some can't — I'll tell you which"
+
+If option 2, collect names and exclude from discovery.
+
+If an excluded service is a hard dependency for the app under test, suggest remote testing:
+
+> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment. Want to continue with a partial local setup, or switch to remote testing?"
+
+- Option 1: "Continue locally — I'll work around the missing service"
+- Option 2: "Switch to remote — I'll merge and test on preview"
+
+If remote, hand off to `/muggle-test` in remote mode and exit.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.12.2",
-  "buildId": "run-40-1",
-  "commitSha": "9039582dcc85172dff58bcebc185d8aaa495f947",
-  "buildTime": "2026-05-22T04:16:07Z",
+  "release": "4.12.3",
+  "buildId": "run-41-1",
+  "commitSha": "9f6c0d27cf0e83976386db90321cf9cc35ac5328",
+  "buildTime": "2026-05-22T06:22:26Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-ARTTHWNP.js → src-YR5UKLPC.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-I4VLYJ7M.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-CPF6AR2I.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "4.12.2",
+  "version": "4.12.3",
   "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.93",
+    "electronAppVersion": "1.0.94",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "79edb82904ff247a3176d7f25e6aea879bde0befe9f50ae1c977f9de01e09278",
-      "darwin-x64": "2b13541aee90eec7cff3e0d92a963fa2508f91a195aee3774edd851f69a45442",
-      "linux-x64": "438d8c80602c6c9746a2b5a11c9236d11997827ca74376e0e0fef1952f38640c",
-      "win32-x64": "6ccac8d05d40ce6d6b976f3079cbc7ca4bb3714d3d5b67776a72cd9bbf324f53"
+      "darwin-arm64": "22731d8fac9b3ce7dc0490932a099fad0b7bab901e4efe3c2f8e44b4dd165bdb",
+      "darwin-x64": "0965f1a3f7b0db6a976650e26de024f0baea58102cf9acc93e8c69c6dfd8709f",
+      "linux-x64": "5280ae8ac73215f1c4f92d3b280eee0918341179485993493bd04f3f5a95b5b5",
+      "win32-x64": "a02bf08ba6f5463b1dad354824c6369738248e86ce5ef02644d2185fdc2d047f"
     }
   },
   "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.12.2",
+  "version": "4.12.3",
   "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.12.2",
+  "version": "4.12.3",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/skills/_shared/dev-server-readiness.md

@@ -49,6 +49,45 @@ netstat -ano | findstr /R /C:":3000 " /C:":3001 " /C:":4200 " /C:":5173 " /C:":8
 
 If the app declares a backend URL in its env file, probe the backend's health endpoint before treating the dev server as usable. 5xx or unreachable → halt; the frontend may render but its data layer is dead, so any query against it is meaningless.
 
+## Body sniff patterns
+
+A `200 OK` can still be a build-error overlay or stack trace. Search the response body (case-insensitive) for broken-build markers — a match means unhealthy regardless of status.
+
+| Stack | Pattern (regex) |
+|:------|:----------------|
+| Next.js | `__next_error__\|Failed to compile\|webpack-internal://` |
+| Vite | `vite-error-overlay\|Internal server error\|\[plugin:` |
+| Node / Express | `MODULE_NOT_FOUND\|Cannot find module\|npm ERR!\|Cannot GET /\|Cannot POST /\|Error: ENOENT\|EACCES\|EADDRINUSE` |
+| Django | `TemplateSyntaxError\|ProgrammingError at /\|<h1>Server Error \(500\)</h1>` |
+| Flask | `Werkzeug Debugger\|werkzeug-debug` |
+| FastAPI / Python | `Traceback \(most recent call last\)\|ModuleNotFoundError\|ImportError` |
+| Rails | `Better Errors\|ActionController::RoutingError\|<title>Action Controller:` |
+| Spring Boot | `Whitelabel Error Page` |
+| Tomcat | `HTTP Status 500.*Apache Tomcat` |
+| Laravel / PHP | `Whoops\\\\|<b>Fatal error</b>\|Parse error:\|Stack trace:` |
+| JS stack frame | `at .*\(.*\.[jt]sx?:\d+:\d+\)` |
+| Java stack frame | `at \w+(\.\w+)+\(\w+\.java:\d+\)` |
+| Python stack frame | `File ".*", line \d+, in ` |
+| Ruby stack frame | `\.rb:\d+:in ` |
+
+The bash/PowerShell snippets below use the union of all patterns above. Trim per-stack when you know the target.
+
+#### bash/zsh
+
+```bash
+BODY=$(curl -sS -L --max-redirs 1 --max-time 3 "$URL")
+PATTERN='__next_error__|Failed to compile|webpack-internal://|vite-error-overlay|Internal server error|MODULE_NOT_FOUND|Cannot find module|Cannot GET /|npm ERR!|Error: ENOENT|EACCES|EADDRINUSE|TemplateSyntaxError|Werkzeug Debugger|Traceback \(most recent call last\)|ModuleNotFoundError|ImportError|Better Errors|ActionController::RoutingError|Whitelabel Error Page|Apache Tomcat|Whoops|<b>Fatal error</b>|Parse error:|Stack trace:|at .*\(.*\.[jt]sx?:[0-9]+:[0-9]+\)|at \w+(\.\w+)+\(\w+\.java:[0-9]+\)|File ".*", line [0-9]+, in |\.rb:[0-9]+:in '
+echo "$BODY" | grep -qiE "$PATTERN" && { echo "BODY-SNIFF FAIL"; echo "$BODY" | grep -iE "$PATTERN" | head -3; exit 1; }
+```
+
+#### PowerShell
+
+```powershell
+$body = (Invoke-WebRequest -Uri $url -TimeoutSec 3 -MaximumRedirection 1 -ErrorAction Stop).Content
+$pattern = '__next_error__|Failed to compile|webpack-internal://|vite-error-overlay|Internal server error|MODULE_NOT_FOUND|Cannot find module|Cannot GET /|npm ERR!|Error: ENOENT|EACCES|EADDRINUSE|TemplateSyntaxError|Werkzeug Debugger|Traceback \(most recent call last\)|ModuleNotFoundError|ImportError|Better Errors|ActionController::RoutingError|Whitelabel Error Page|Apache Tomcat|Whoops|<b>Fatal error</b>|Parse error:|Stack trace:|at .*\(.*\.[jt]sx?:\d+:\d+\)|at \w+(\.\w+)+\(\w+\.java:\d+\)|File ".*", line \d+, in |\.rb:\d+:in '
+if ($body -imatch $pattern) { Write-Host "BODY-SNIFF FAIL"; [regex]::Matches($body, $pattern, 'IgnoreCase') | Select-Object -First 3 | ForEach-Object { $_.Value }; exit 1 }
+```
+
 ## Two-stage readiness — after starting a dev server
 
 Network reachability is necessary but not sufficient. Many dev servers bind to a port before build/startup work is complete. Wait for **both** network readiness and application readiness before issuing requests.

package/plugin/skills/_shared/failure-mode-handling.md

@@ -109,9 +109,15 @@ Triggered when `muggle-local-execute-replay` returns `status: "failed"` (or non-
 | **stale-script** | The test script no longer matches the live UI (selectors moved, label paths changed, page renamed). The product still works; the script is out of date. |
 | **product-defect** | The script and infra are fine; the user's app actually misbehaved (assertion failure on previously-passing step, unexpected error, wrong page after action). This is the failure mode acceptance testing exists to catch. |
 
-### Initial signal heuristics
+### Where to read signals
+
+Call `muggle-local-run-result-get` (local) or the remote equivalent and read **structured fields**, not `execute`'s response stdout tail (it's a truncated display excerpt and routinely cuts off mid-sentence). Order:
 
-Derive signals from the run's per-step results, error messages, and step screenshots (`muggle-local-run-result-get`):
+1. `Status` + `Error` — the verdict and the one-line cause.
+2. `Artifacts` section, when present — opens `artifactsDir`. Read `results.md` (step-by-step + screenshot links) for the per-step verdict, then `action-script.json` for what the agent attempted.
+3. `stdout.log` / `stderr.log` only when the Artifacts section is absent or `results.md` doesn't exist (e.g. early Electron failure).
+
+### Initial signal heuristics
 
 - **infra** signals: `electron-crash`, `chromium-error`, `click-no-effect-on-clickable-element`, `timeout-on-trivial-wait`, `internal-error-in-mcp-output`.
 - **stale-script** signals: `element-not-found`, `selector-timeout`, `label-path-mismatch`, `nav-target-404`, `aria-label-changed`.
@@ -189,9 +195,18 @@ Triggered when `muggle-local-execute-test-generation` (or the remote equivalent)
 | **agent-course** | The generation agent went down a wrong path (chose the wrong button, misread the goal, looped on a blocking modal). The product is fine and the test case is fine — the agent's *course* needs steering. |
 | **product-uxux** | The product itself blocks the test (broken page, missing element, server error). Agent can't proceed because the feature doesn't actually work. |
 
-### Initial signal heuristics
+### Where to read signals
 
-From `muggle-local-run-result-get` (summary, structured summary, last steps, error):
+Same rule as section B: read **structured fields** from `muggle-local-run-result-get`, not `execute`'s response stdout tail. The `Artifacts` section is present on failed regen too — `action-script.json` is included when generation reached the step-emission stage (typical for `goal_not_achievable`: the agent's attempted steps + halt summary). `results.md` and per-step screenshots are absent on failure (electron-app emits those only on the successful completion path).
+
+Order:
+
+1. `Status` + `Error` — the verdict and one-line cause. `Error: Electron exited with code 26` typically means `goal_not_achievable`.
+2. `action-script.json` in `artifactsDir` when present — read the steps the agent attempted and the `summaryStep` (halt reason, goal-not-achievable verdict).
+3. `stdout.log` / `stderr.log` at `artifactsDir/` — last 100 lines is usually enough; look for the final structured summary the generation agent emitted (it appears near the end as a JSON-ish block, not in the truncated execute tail).
+4. Remote regen — fetch the workflow run with `muggle-remote-wf-get-ts-gen-latest-run`; signals live in `summaryStep` and the per-step list there.
+
+### Initial signal heuristics
 
 - **transient**: `network-error`, `llm-rate-limit`, `single-tool-call-error`, run had partial progress then died.
 - **infra**: `electron-mcp-handler-crash`, `internal-validation-error`, `pipeline-stuck`, identical failure repeated more than twice.

package/plugin/skills/_shared/pr-branch-worktree.md

@@ -0,0 +1,31 @@
+# PR-Branch Worktree — Shared Reference
+
+> Source of truth for materializing a PR's branch in an isolated worktree so the user's main checkout is never disturbed. Used by `muggle-test` (and any future skill that takes a GitHub PR URL). Skills MUST link here rather than restate the steps.
+
+## When this applies
+
+A skill receives a GitHub PR URL of the form `github.com/<org>/<repo>/pull/<n>` and needs the PR's branch checked out to test against it locally.
+
+## Steps
+
+1. **Resolve the PR's head branch:**
+   `gh pr view <n> --repo <org>/<repo> --json headRefName -q .headRefName`
+2. **Sanitize the branch name** for filesystem use — replace `/` and other path separators with `-`. Example: `claude/regen-test-replay-flow-ZSScQ` → `claude-regen-test-replay-flow-ZSScQ`.
+3. **Build the target worktree path:** `<repo>/.claude/worktrees/<sanitized-branch>`.
+4. **Materialize the worktree:**
+   - If the target path does NOT exist:
+     - `git -C <repo> fetch origin <branch>`
+     - `git -C <repo> worktree add <target-path> <branch>`
+   - If the target path EXISTS (reused from a prior run):
+     - `git -C <target-path> fetch`
+     - `git -C <target-path> reset --hard origin/<branch>` — picks up new pushes, drops any local cruft.
+5. **Use the worktree path as the working directory** for the rest of the run, including:
+   - Passing it as the **`cwd` parameter** to `muggle-local-execute-test-generation` and `muggle-local-execute-replay`. This is required, not optional — see `_shared/failure-mode-handling.md` and the lock identity discussion in those tools' MCP source.
+   - Resolving any `npm install` / dev-server start commands inside the worktree (it has its own `node_modules/` and `.env*` files).
+6. **Tell the user** where the worktree lives so they can clean it up later with `git -C <repo> worktree remove <target-path>`.
+
+## Invariants
+
+- **Never switch the user's main checkout.** The whole point of this flow is isolation; `git checkout <branch>` on the main checkout is forbidden.
+- **Never share `node_modules/` via symlink** across worktrees. Each worktree runs its own `npm install` (or `pnpm install`) — webpack's `resolve.symlinks: true` rewrites paths and breaks asset-identity tracking.
+- **`.env*` files do not propagate.** A freshly created worktree has no env files unless the repo commits them. If the parent skill's dev server fails to boot, check whether `.env.local` (or framework equivalent) needs to be copied from the main checkout before launching.

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

@@ -96,7 +96,7 @@ Analyze the changes to understand what's impacted. Two sources, picked by what t
 **PR URL** (user passed `github.com/<org>/<repo>/pull/<n>`):
 1. `gh pr diff <n> --repo <org>/<repo> --name-only` for the changed file list
 2. `gh pr diff <n> --repo <org>/<repo>` for the actual diff
-3. The repo lives at a sibling path (e.g. `C:\Users\stan4\Github\<repo>`) — `cd` into it and verify the PR branch is checked out before running tests; if not, ask the user to check it out (or offer to do it).
+3. Materialize the PR branch in a dedicated worktree per [`_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md). Use that worktree path as the `cwd` for the rest of the run (including the `cwd` parameter on local execute tools).
 
 Either way:
 1. Identify impacted feature areas:
@@ -273,6 +273,7 @@ Execution itself **must** be sequential because there is only one local Electron
 1. Call `muggle-local-execute-test-generation`:
    - `testCase`: Full test case object from the parallel fetch above
    - `localUrl`: User's local URL from the pre-flight question
+   - `cwd`: Absolute path of the active working directory — the PR-branch worktree if one was created in Step 2, otherwise the user's repo root. Drives the cross-worktree single-flight lock so concurrent muggle-test runs from different branches serialize.
    - `showUi`: from the `showElectronBrowser` resolution — omit (default visible) for `always`, pass `false` for `never`
    - `freshSession`: `true` if the test case requires a clean browser state (see above), omit otherwise
 2. Store the returned `runId` and tag the result `mode: "regen"`.
@@ -282,14 +283,16 @@ Execution itself **must** be sequential because there is only one local Electron
 2. Call `muggle-local-execute-replay`:
    - `testScript`: from `muggle-remote-test-script-get`
    - `actionScript`: from `muggle-remote-action-script-get`
-   - `localUrl`, `showUi`, `freshSession`: same resolution as regen
+   - `localUrl`, `cwd`, `showUi`, `freshSession`: same resolution as regen
 3. Store the returned `runId` and tag the result `mode: "replay"`.
 
 If a run fails, log it and continue to the next — do not abort the batch. Failures are routed through Step 7C's post-failure handler after the batch completes.
 
 ### Collect results (in parallel)
 
-For every `runId`, issue all `muggle-local-run-result-get` calls in parallel. Extract: status, duration, step count, `artifactsDir`.
+For every `runId`, issue all `muggle-local-run-result-get` calls in parallel. Extract from the **structured response only** (not from `execute`'s stdout tail, which is a truncated display excerpt): `Status`, `Error`, `Duration`, and the `Artifacts` section (always present after a run completes — names `artifactsDir` and lists the files actually on disk).
+
+For passed runs, `results.md` inside `artifactsDir` is the step-by-step verdict — read it before summarizing. For failed runs, `stdout.log` + `stderr.log` are always present and `action-script.json` is present when generation reached the step-emission stage (typical for `goal_not_achievable`); use `Error` as the headline verdict and route through Step 7C.
 
 ### Publish each run to cloud (gated by `autoPublishLocalResults`)
 
@@ -459,6 +462,7 @@ This is a suggestion, not automatic invocation. Skip silently if every test pass
 ## Guardrails
 
 - **Always confirm intent first** — never assume local vs remote without asking
+- **PR URLs always run in a dedicated worktree** — never switch the user's main checkout. Create or reuse `<repo>/.claude/worktrees/<sanitized-branch>` and pass that path as the `cwd` parameter to local execute tools. The cross-worktree single-flight lock relies on this to serialize concurrent runs from different branches.
 - **User MUST select project** — present clickable options via `AskUserQuestion`, wait for explicit choice, never auto-select
 - **Best-effort shortlist use cases** — use the change summary to narrow the list to the most relevant 1–5 use cases and pre-check them; never dump every use case in the project on the user. Always leave an escape hatch to reveal the full list.
 - **Best-effort shortlist test cases** — same idea: pre-check the test cases most relevant to the change summary; never enumerate every test case attached to a use case. Always leave an escape hatch to reveal the full list.

package/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -195,8 +195,12 @@ If publish rejects with `has no generated actionScript steps to publish` (true z
 
 ### 9. Report
 
+**Do not diagnose from `execute`'s response stdout tail.** That tail is a truncated excerpt for human display and routinely cuts off mid-sentence. The only ground truth is the run record.
+
 - `muggle-local-run-result-get` with the run id from execute.
-- Include: status, duration, pass/fail summary, per-step summary, artifact/screenshot paths, errors if failed, and script view URL when publishing ran.
+- **Read in this order:** `Status` → `Error` → **`Artifacts` section** (always present after a run completes; names `artifactsDir` and lists the files actually on disk: `action-script.json`, `results.md`, `screenshots/`, `stdout.log`, `stderr.log`). On a `passed` run, `results.md` is the step-by-step verdict with screenshot links — read it before summarizing.
+- **On failure**, the `Artifacts` section is still present. `stdout.log` + `stderr.log` are always there. `action-script.json` is there when generation got far enough to emit it (typical for `goal_not_achievable` / mid-progress crashes — the file holds the agent's attempted steps + halt summary). `results.md` and per-step screenshots are absent on failure (electron-app only emits those on the successful completion path) — don't hunt elsewhere on disk for them.
+- Include in the report: status, duration, pass/fail summary, per-step summary (passed runs), artifact paths, errors if failed, and script view URL when publishing ran.
 
 ### 9a. Route failures through the failure-mode handler
 
@@ -242,6 +246,7 @@ After reporting results:
 
 - No silent auth skip.
 - **Never prompt for Electron launch approval** before execution — invoking this skill is the approval. Just run.
+- **Never diagnose a failed run from `execute`'s response stdout tail.** Always call `muggle-local-run-result-get` first; classify only from its structured fields and (when present) the artifacts it names. The execute tail is an excerpt and routinely truncates the failure cause.
 - If replayable scripts exist, do not default to generation without user choice.
 - No hiding failures: surface errors and artifact paths.
 - **Always offer the agent-guidance reminder after every Electron run** (Step 9b) — pass or fail — unless 9a already routed the user into `muggle-feedback`. Never silently end a run without giving the user a one-click path to flag what was wrong.