@muggleai/works 5.0.3 → 5.1.0

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

@@ -7,7 +7,7 @@ description: "Change-driven E2E acceptance testing with Muggle AI: detect the us
 
 > Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test"`.
 
-A router skill that detects code changes, resolves impacted test cases, executes them locally or remotely, publishes results to the Muggle AI dashboard, and posts E2E acceptance summaries to the PR. The user can invoke this at any moment, in any state.
+A router skill that detects code changes, resolves impacted test cases, executes them locally or remotely, reads the cloud results from the Muggle AI dashboard (local runs are published by the studio during execution; remote runs publish cloud-side), and posts E2E acceptance summaries to the PR. The user can invoke this at any moment, in any state.
 
 ## UX Guidelines — Minimize Typing
 
@@ -42,11 +42,10 @@ Gates run per `preference-gates/README.md`.
 |------------|------|-------------------|
 | `autoLogin` | 3 | Reuse saved credentials when auth is required |
 | `autoSelectProject` | 4 | Reuse last-used Muggle Test project for this repo |
-| `autoSelectLocalHost` | 7A | Reuse last-used local dev server URL for this repo |
+| `autoSelectLocalHost` | execute-local | Reuse last-used local dev server URL for this repo |
 | `autoDetectChanges` | 2 | Scan local git changes and map to affected test cases |
 | `defaultExecutionMode` | 1 | Default to local or remote test execution |
-| `autoPublishLocalResults` | 7A | Upload local results to Muggle Test cloud after run |
-| `showElectronBrowser` | 7A | Show the Electron browser window during local test execution (vs. run headless) |
+| `showElectronBrowser` | execute-local | Show the Electron browser window during local test execution (vs. run headless) |
 | `postPRVisualWalkthrough` | 9 | Post visual walkthrough to PR after results are available |
 | `autoCreatePR` | 9 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
 | `autoWatchPR` | 9.5 (if a PR exists) | Start a `muggle-pr-followup` watcher on the PR after the run |
@@ -235,148 +234,37 @@ Then show the per-case decision in one `AskUserQuestion`:
 
 If the user picks "Override one or more", let them flip the mode for any test case via a second multi-select `AskUserQuestion`. Emit a follow-up `pre-execution-classification` event with `userAction` set whenever the user overrides.
 
-## Step 7A: Execute — Local Mode
+## Step 7: Execute
 
-### Local environment readiness
+### Fetch test case details (both modes)
 
-Before anything else, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the readiness/service-start owner (idempotent; halt on what it surfaces). The URL gate below only *selects* the target; prepare is what guarantees something is listening and compiled.
+Hydrate every selected test case **once**, before dispatch: issue **all** `muggle-remote-test-case-get` calls in parallel (single message, multiple tool calls). Both paths consume the result — never re-fetch inside a path.
 
-### Pre-flight question — Local URL (gated by `autoSelectLocalHost`)
+### Dispatch by mode
 
-Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):
-- **Read the cache**: `Muggle Test Last Host: <url>` session-context line, or `muggle-local-last-host-get`. Pass as `{lastHost}` substitution.
-- **Auto-detect a suggested URL**: `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`. Pass as `{suggestedHost}`.
-- **Save the cache**: call `muggle-local-last-host-set` after the user picks (the gate file requires this on every pick).
+Run the path matching the mode confirmed in Step 1. Each path owns its own process and returns a **uniform runs list** — `[{ testCaseId, mode, runId | runtimeId, status, viewUrl? }]` — that Steps 7C–10 consume mode-agnostically.
 
-Gate `autoSelectLocalHost` per `preference-gates/README.md` + `preference-gates/autoSelectLocalHost.md`.
+- **Mode A (Local)** → [`execute-local.md`](execute-local.md). Inputs: the hydrated test cases, per-case `mode` from Step 6f, and `cwd` (the PR-branch worktree from Step 2 if one exists, else the repo root).
+- **Mode B (Remote)** → [`execute-remote.md`](execute-remote.md). Inputs: the hydrated test cases, per-case `mode` from Step 6f, `projectId` / `useCaseId`.
 
-### Pre-flight visibility (gated by `showElectronBrowser`)
+## Step 7C: Route every failed run through the debug path
 
-Gate `showElectronBrowser` (per `preference-gates/README.md`). Resolve once; apply same `showUi` to every test case.
-- `always` → omit `showUi` (defaults visible).
-- `never` → pass `showUi: false`.
-- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+For every run with `status: "failed"` (or any non-passing terminal state) returned by Step 7 (either path), route through [`_shared/debug-failed-run.md`](../_shared/debug-failed-run.md). This is **mandatory** — a failure is never reported without it. The debug path gathers evidence (attempted steps + reasoning + screenshot), diagnoses via [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) (§B replay / §C regen), shows the debug card, and presents the guaranteed selection in which **"give feedback & rerun"** is always an option and "skip" is never the default.
 
-### Fetch test case details (in parallel)
-
-Before execution, fetch full test case details for all selected test cases by issuing **all** `muggle-remote-test-case-get` calls in parallel (single message, multiple tool calls).
-
-### Run the dev loop
-
-Execute each selected test case via the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): [sequential replay/regen](../_shared/dev-loop/run.md), [`actionScript` as-is](../_shared/dev-loop/action-script.md), [`freshSession`](../_shared/dev-loop/fresh-session.md), and [`timeoutMs`](../_shared/dev-loop/timeouts.md).
-
-Caller glue:
-- `mode` per test case comes from Step 6f; `localUrl` from the pre-flight question; `showUi` from the `showElectronBrowser` resolution.
-- `cwd` = the PR-branch worktree from Step 2 if one was created, else the user's repo root — it drives the cross-worktree single-flight lock so concurrent muggle-test runs from different branches serialize.
-- On a failed run, continue the batch and route it through Step 7C after completion.
-
-### Collect results
-
-Fetch every `runId` per [`../_shared/dev-loop/failures.md`](../_shared/dev-loop/failures.md), reading structured fields and [interpreting failures](../_shared/dev-loop/failures.md) — never `execute`'s stdout tail. Issue the `muggle-local-run-result-get` calls in parallel; use `Error` as the headline for failures and route through Step 7C.
-
-### Publish each run to cloud (gated by `autoPublishLocalResults`)
-
-Gate `autoPublishLocalResults` (per `preference-gates/README.md`):
-- `always` → proceed to publish logic below.
-- `never` → skip to report summary; tell user Steps 8/9 and per-step screenshots are unavailable without publishing.
-- `ask` → run Picker 1 from `preference-gates/autoPublishLocalResults.md` via `AskUserQuestion`; map the answer back to one of the actions above.
-
-### Publish logic (when publishing is enabled)
-
-Publish every completed run per [`../_shared/dev-loop/publish.md`](../_shared/dev-loop/publish.md) — parallel `muggle-local-publish-test-script` with the zero-step `muggle-remote-local-run-upload` fallback. Store every `viewUrl`, `testScriptId`, `actionScriptId` — used in the next steps.
-
-### Report summary
-
-```
-Test Case                  Status    Duration   Steps   View Steps on Muggle AI
-─────────────────────────────────────────────────────────────────────────
-Login with valid creds     PASSED    12.3s      8       https://www.muggle-ai.com/...
-Login with invalid creds   PASSED    9.1s       6       https://www.muggle-ai.com/...
-Checkout flow              FAILED    15.7s      12      https://www.muggle-ai.com/...
-─────────────────────────────────────────────────────────────────────────
-Total: 3 tests | 2 passed | 1 failed | 37.1s
-```
-
-For failures: show which step failed, the local screenshot path, and a suggestion.
-
-## Step 7B: Execute — Remote Mode
-
-### Ask for target URL
-
-> "What's the preview/staging URL to test against?"
-
-### Fetch test case details (in parallel)
-
-Issue all `muggle-remote-test-case-get` calls in parallel (single message, multiple tool calls) to hydrate the test case bodies.
-
-### Trigger remote workflows (in parallel)
-
-Branch each test case on the mode chosen in Step 6f, then issue **all** workflow-start calls in parallel — never loop them sequentially. Mix regen and replay starts in the same parallel batch.
-
-**Regen-mode test case** — `muggle-remote-workflow-start-test-script-generation`:
-
-- `projectId`: The project ID
-- `useCaseId`: The use case ID
-- `testCaseId`: The test case ID
-- `name`: `"muggle-test: {test case title}"`
-- `url`: The preview/staging URL
-- `goal`: From the test case
-- `precondition`: From the test case (use `"None"` if empty)
-- `instructions`: From the test case
-- `expectedResult`: From the test case
-
-**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` if not already in hand from Step 6f). Tag results with `mode: "replay"` so Step 7C can route failures correctly.
-
-Store each returned workflow runtime ID along with its mode tag.
-
-### Monitor and report (in parallel)
-
-Issue all `muggle-remote-wf-get-ts-gen-latest-run` calls in parallel, one per runtime ID.
-
-```
-Test Case                  Workflow Status   Runtime ID
-────────────────────────────────────────────────────────
-Login with valid creds     RUNNING           rt-abc123
-Login with invalid creds   COMPLETED         rt-def456
-Checkout flow              QUEUED            rt-ghi789
-```
-
-## Step 7C: Route failures through the failure-mode handler
-
-For every run with `status: "failed"` (or any non-passing terminal state) from 7A or 7B, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
-
-- **Replay-mode failures** — section B (buckets: `infra` / `stale-script` / `product-defect`).
-- **Regen-mode failures** — section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
-
-For each failed run:
-1. Read the run with `muggle-local-run-result-get` (local) or `muggle-remote-wf-get-ts-gen-latest-run` / `muggle-remote-wf-get-ts-replay-latest-run` (remote) and extract signals per the heuristics in the shared doc.
-2. Emit `replay-failure-classified` or `regen-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
-3. Present the recommended action via `AskUserQuestion` along with the alternatives the shared doc lists for that bucket.
-4. After the user picks, emit the matching `*-resolved` event with `userAction` set to what they chose.
-
-Process failures one at a time so the user isn't drowning in pickers — but emit telemetry per failure regardless.
+Pass it per failed run: the `runId` (local) or workflow runtime id (remote), the `mode` that failed, `testCaseId`, `projectId`, and the execution handle (local: [`execute-local.md`](execute-local.md); remote: [`execute-remote.md`](execute-remote.md)) so a rerun re-enters the same path. Process failures one at a time so the user isn't drowning in pickers.
 
 ## Step 8: Open Results in Browser
 
-After execution and publishing are complete, open the Muggle AI dashboard so the user can visually inspect results and screenshots.
-
-### Mode A (Local) — open each published viewUrl
+After execution, open the Muggle AI dashboard so the user can inspect results and screenshots. The studio published every local run during execution, so each run result already carries its `viewUrl` (read it from `muggle-local-run-result-get`). Key off the uniform runs list:
 
-For each published run's `viewUrl`:
-```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}"
-```
-
-If there are many runs (>3), open just the project-level runs page instead of individual tabs:
-```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
-```
-
-### Mode B (Remote) — open the project runs page
-
-```bash
-open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
-```
+- **Runs carry a `viewUrl` and there are ≤3** — open each:
+  ```bash
+  open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=script-details&testCaseId={testCaseId}"
+  ```
+- **Otherwise** (more than 3 runs, or a run with no `viewUrl`) — open the project runs page:
+  ```bash
+  open "https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/runs"
+  ```
 
 Tell the user:
 > "I've opened the Muggle AI dashboard in your browser — you can see the test results, step-by-step screenshots, and action scripts there."
@@ -388,7 +276,7 @@ After reporting results:
 1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 9.5.
 2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
 3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → Step 9.5.
-4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md). Include all runs from Step 7A (passed and failed).
+4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md). Include all runs from Step 7 (passed and failed).
 5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
 ## Step 9.5: Offer to watch the PR for review follow-ups
@@ -403,27 +291,26 @@ Once a PR exists for this work, offer to keep watching its review thread.
 
 The `/mprfollowup` shortcut starts the same watcher manually at any time.
 
-## Step 10: Offer feedback on failures
-
-After the report is complete, if **any** test in the run had a `failed` or unexpected status (or the user verbally flags something looked off), suggest the feedback skill:
+## Step 10: Offer feedback on a clean pass
 
-> "Looks like `<N>` test(s) didn't go as expected. Want to leave feedback on what should've happened? It triggers regeneration on the affected scripts."
+Failures already got a guaranteed feedback-&-rerun offer in Step 7C's debug path — don't re-ask for them here.
 
-Use `AskUserQuestion`:
-- **Yes — give feedback** → invoke the `muggle-feedback` skill via the `Skill` tool. Pass the failed run's `runId` (local) or `testScriptId` (remote) as anchor context so the submit flow opens with the correct script already loaded.
+This step is only for a run that **passed** but the user flags as off (a misclick, wrong element, a summary that doesn't match intent). When that happens, use `AskUserQuestion`:
+- **Yes — give feedback** → invoke the `muggle-feedback` skill via the `Skill` tool, passing the run's `runId` (local) or `testScriptId` (remote) as anchor context so the submit flow opens with the correct script already loaded.
 - **No — skip**
 
-This is a suggestion, not automatic invocation. Skip silently if every test passed cleanly.
+Skip silently if nothing looked off.
 
 ## Non-negotiables
 
 Each rule below is covered in-step above; these are the ones this skill most often violates, kept here as reinforcement:
 
 - **Test-case shape** — never skip the generate→review cycle, never consolidate the generator's micro-tests, one atomic behavior per test case. Creating test cases directly or merging the generator's output is the single most frequent mistake.
+- **Every failure routes through the debug path** — no failed run is summarized-and-dropped. Step 7C → [`_shared/debug-failed-run.md`](../_shared/debug-failed-run.md) is mandatory, "give feedback & rerun" is always offered, and "skip" is never the default.
 - **Confirm intent before acting** — local vs remote; never guess the localhost/preview URL.
 - **PR URLs run in a dedicated worktree** — never switch the user's main checkout; pass that worktree as `cwd`.
 - **Every selection uses `AskUserQuestion`** — never ask the user to type a number; the user picks the project (never auto-select).
 - **Parallelize independent cloud jobs**; the only sequential loop is local Electron execution (one browser).
-- **Publish before opening the browser**, and delegate PR posting to `muggle-pr-visual-walkthrough` — never inline the walkthrough or call `gh pr comment` here.
+- **Read cloud refs off the run result** (the studio published during execution) and delegate PR posting to `muggle-pr-visual-walkthrough` — never inline the walkthrough or call `gh pr comment` here.
 
 Phase→tool map and multi-agent (acceptance-tester) dispatch: [`reference.md`](reference.md).

package/dist/plugin/skills/muggle-test/execute-local.md

@@ -0,0 +1,60 @@
+# Muggle Test — Local Execution Path (Mode A)
+
+> The Local execution process for the `muggle-test` router: run the selected test cases against localhost via the Electron browser and collect results. The studio publishes each run to the cloud during execution, so the run result already carries the cloud refs. Returns a uniform runs list to the router. Per-test-case mechanics are shared with [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md).
+
+## Inputs (the router passes these in)
+
+- The hydrated test cases (fetched once by the router before dispatch).
+- Per-case `mode` — `replay` or `regen`, chosen during replay-vs-regen classification.
+- `cwd` — the PR-branch worktree if one exists, else the repo root.
+
+## Local environment readiness
+
+Before anything else, invoke [`muggle-test-prepare`](../muggle-test-prepare/SKILL.md) — the readiness/service-start owner (idempotent; halt on what it surfaces). The URL gate below only *selects* the target; prepare is what guarantees something is listening and compiled.
+
+## Pre-flight question — Local URL (gated by `autoSelectLocalHost`)
+
+Skill responsibilities (the rest is in `preference-gates/autoSelectLocalHost.md`):
+- **Read the cache**: `Muggle Test Last Host: <url>` session-context line, or `muggle-local-last-host-get`. Pass as `{lastHost}` substitution.
+- **Auto-detect a suggested URL**: `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`. Pass as `{suggestedHost}`.
+- **Save the cache**: call `muggle-local-last-host-set` after the user picks (the gate file requires this on every pick).
+
+Gate `autoSelectLocalHost` per `preference-gates/README.md` + `preference-gates/autoSelectLocalHost.md`.
+
+## Pre-flight visibility (gated by `showElectronBrowser`)
+
+Gate `showElectronBrowser` (per `preference-gates/README.md`). Resolve once; apply same `showUi` to every test case.
+- `always` → omit `showUi` (defaults visible).
+- `never` → pass `showUi: false`.
+- `ask` → run Picker 1 from `preference-gates/showElectronBrowser.md` via `AskUserQuestion`; map the answer back to one of the actions above.
+
+## Run the dev loop
+
+Execute each test case via the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): [sequential replay/regen](../_shared/dev-loop/run.md), [`actionScript` as-is](../_shared/dev-loop/action-script.md), [`freshSession`](../_shared/dev-loop/fresh-session.md), and [`timeoutMs`](../_shared/dev-loop/timeouts.md).
+
+Caller glue:
+- `mode` per test case is the input from the router; `localUrl` from the pre-flight question; `showUi` from the `showElectronBrowser` resolution.
+- `cwd` is the input from the router — it drives the cross-worktree single-flight lock so concurrent muggle-test runs from different branches serialize.
+- On a failed run, continue the batch; the router routes failures through the debug path after this path returns.
+
+## Collect results
+
+Fetch every `runId` per [`../_shared/dev-loop/failures.md`](../_shared/dev-loop/failures.md), reading structured fields and [interpreting failures](../_shared/dev-loop/failures.md) — never `execute`'s stdout tail. Issue the `muggle-local-run-result-get` calls in parallel; use `Error` as the headline for failures. The studio already published each run, so the same call surfaces `viewUrl` / `cloudTestScriptId` / `cloudActionScriptId` — retain them per [`../_shared/dev-loop/publish.md`](../_shared/dev-loop/publish.md) for the dashboard and walkthrough.
+
+## Report summary
+
+```
+Test Case                  Status    Duration   Steps   View Steps on Muggle AI
+─────────────────────────────────────────────────────────────────────────
+Login with valid creds     PASSED    12.3s      8       https://www.muggle-ai.com/...
+Login with invalid creds   PASSED    9.1s       6       https://www.muggle-ai.com/...
+Checkout flow              FAILED    15.7s      12      https://www.muggle-ai.com/...
+─────────────────────────────────────────────────────────────────────────
+Total: 3 tests | 2 passed | 1 failed | 37.1s
+```
+
+For failures, don't hand-write a verdict — the router routes each through the debug path.
+
+## Output
+
+Return the uniform runs list the router consumes: `[{ testCaseId, mode, runId, status, viewUrl?, cloudTestScriptId?, cloudActionScriptId? }]`. The studio published each run during execution, so `viewUrl` / `cloudTestScriptId` / `cloudActionScriptId` come straight off the run result (`muggle-local-run-result-get`).

package/dist/plugin/skills/muggle-test/execute-remote.md

@@ -0,0 +1,49 @@
+# Muggle Test — Remote Execution Path (Mode B)
+
+> The Remote execution process for the `muggle-test` router: trigger cloud test-script generation/replay against a preview/staging URL and monitor. Returns a uniform runs list to the router.
+
+## Inputs (the router passes these in)
+
+- The hydrated test cases (fetched once by the router before dispatch).
+- Per-case `mode` — `replay` or `regen`, chosen during replay-vs-regen classification.
+- `projectId`, `useCaseId`.
+
+## Ask for target URL
+
+> "What's the preview/staging URL to test against?"
+
+## Trigger remote workflows (in parallel)
+
+Branch each test case on its `mode`, then issue **all** workflow-start calls in parallel — never loop them sequentially. Mix regen and replay starts in the same parallel batch.
+
+**Regen-mode test case** — `muggle-remote-workflow-start-test-script-generation`:
+
+- `projectId`: The project ID
+- `useCaseId`: The use case ID
+- `testCaseId`: The test case ID
+- `name`: `"muggle-test: {test case title}"`
+- `url`: The preview/staging URL
+- `goal`: From the test case
+- `precondition`: From the test case (use `"None"` if empty)
+- `instructions`: From the test case
+- `expectedResult`: From the test case
+
+**Replay-mode test case** — `muggle-remote-workflow-start-test-script-replay` against the latest replayable script for that test case (resolve via `muggle-remote-test-script-list` if not already in hand from the classification step). Tag results with `mode: "replay"` so the router routes failures correctly.
+
+Store each returned workflow runtime ID along with its mode tag.
+
+## Monitor and report (in parallel)
+
+Issue all `muggle-remote-wf-get-ts-gen-latest-run` calls in parallel, one per runtime ID.
+
+```
+Test Case                  Workflow Status   Runtime ID
+────────────────────────────────────────────────────────
+Login with valid creds     RUNNING           rt-abc123
+Login with invalid creds   COMPLETED         rt-def456
+Checkout flow              QUEUED            rt-ghi789
+```
+
+## Output
+
+Return the uniform runs list the router consumes: `[{ testCaseId, mode, runtimeId, status }]`.

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

@@ -23,9 +23,8 @@ Lookup material pulled out of `SKILL.md` to keep the always-loaded body lean. Ev
 | Execute (regen) | `muggle-remote-workflow-start-test-script-generation` | Remote |
 | Execute (replay) | `muggle-remote-workflow-start-test-script-replay` | Remote |
 | Failure-mode telemetry | `muggle-local-telemetry-event-emit` | Both |
-| Results | `muggle-local-run-result-get` | Local |
+| Results + cloud refs (studio-published `viewUrl` / `cloudTestScriptId` / `cloudActionScriptId`) | `muggle-local-run-result-get` | Local |
 | Results | `muggle-remote-wf-get-ts-gen-latest-run`, `muggle-remote-wf-get-ts-replay-latest-run` | Remote |
-| Publish | `muggle-local-publish-test-script` | Local |
 | Per-step screenshots (for walkthrough) | `muggle-remote-test-script-get` | Both |
 | Browser | `open` (shell command) | Both |
 | PR walkthrough | `muggle-pr-visual-walkthrough` (shared skill) | Both |

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

@@ -12,7 +12,7 @@ description: Run a real-browser end-to-end (E2E) acceptance test against localho
 | Scope | MCP tools |
 | :---- | :-------- |
 | Cloud (projects, cases, scripts, auth) | `muggle-remote-*` |
-| Local (Electron run, publish, results) | `muggle-local-*` |
+| Local (Electron run, results — the studio publishes during the run) | `muggle-local-*` |
 | Create new entities (preview / create) | `muggle-remote-project-create`, `muggle-remote-use-case-prompt-preview`, `muggle-remote-use-case-create-from-prompts`, `muggle-remote-test-case-generate-from-prompt`, `muggle-remote-test-case-create` |
 
 The local URL only changes where the browser opens; it does not change the remote project or test definitions.
@@ -158,11 +158,11 @@ Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse the choice
 
 `showUi` is only ever omitted or `false` — never pass `showUi: true`.
 
-### 8. Upload run to cloud (every completed run; open `viewUrl` gated by `openTestResultsAfterRun`)
+### 8. Open the run on the dashboard (`viewUrl` gated by `openTestResultsAfterRun`)
 
-Upload pass-or-fail. Failed runs still need cloud-hosted screenshots and per-step actions for the PR walkthrough — without them reviewers see only a generic "failed" link. The `status` field in the upload payload tells the backend whether to promote the run's action script as the test case's canonical replay script (passed → promote; failed → record only).
+The studio publishes every completed run — pass or fail — to the cloud during execution, so the run result already carries the cloud refs. Failed runs are published too, so reviewers get the per-step screenshots, not just a generic "failed" link.
 
-- Publish per [`../_shared/dev-loop/publish.md`](../_shared/dev-loop/publish.md) — includes the zero-step `muggle-remote-local-run-upload` fallback.
+- Read the cloud refs per [`../_shared/dev-loop/publish.md`](../_shared/dev-loop/publish.md): `viewUrl` / `cloudTestScriptId` / `cloudActionScriptId` from `muggle-local-run-result-get`.
 - Gate `openTestResultsAfterRun` (per `preference-gates/README.md`):
   - `always` → open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
   - `never` → print the URL only.
@@ -172,24 +172,15 @@ Upload pass-or-fail. Failed runs still need cloud-hosted screenshots and per-ste
 
 Read the run record per [`../_shared/dev-loop/failures.md`](../_shared/dev-loop/failures.md) and [failure interpretation](../_shared/dev-loop/failures.md) — never diagnose from `execute`'s stdout tail.
 
-- 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.
+- Include in the report: status, duration, pass/fail summary, per-step summary (passed runs), artifact paths, errors if failed, and the `viewUrl` from the run result.
 
-### 9a. Route failures through the failure-mode handler
+### 9a. Route a failed run through the debug path
 
-If the run's status is `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
+If the run's status is `failed` or any non-passing terminal state, route through [`_shared/debug-failed-run.md`](../_shared/debug-failed-run.md) — **mandatory**; a failure is never reported without it. It gathers evidence (attempted steps + reasoning + screenshot), diagnoses via [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md) (§B replay / §C regen), shows the debug card, and presents the guaranteed selection in which **"give feedback & rerun"** is always offered and "skip" is never the default.
 
-- **Replay-mode run failed** (the user picked an existing script in Step 5) → section B (buckets: `infra` / `stale-script` / `product-defect`).
-- **Regen-mode run failed** (the user picked "Generate new script" or no script existed) → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
+Pass it: the `runId`, the `mode` that failed (replay if the user picked an existing script in Step 5, else regen), `testCaseId`, `projectId`, and the local execution handle so a rerun re-enters the same path.
 
-Steps:
-1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
-2. Emit `replay-failure-classified` or `regen-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
-3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
-4. After the user picks, emit the matching `*-resolved` event with `userAction`.
-
-If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool, passing the just-finished `runId` so the submit flow opens with this run preloaded.
-
-Skip silently when the run passed cleanly — failure-mode events are by definition about failures.
+Skip only when the run passed cleanly — the debug path is by definition about failures.
 
 ### 9b. Remind the user to guide the agent (every Electron invocation)
 

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "5.0.3",
-  "buildId": "run-51-1",
-  "commitSha": "7285eaa7458b2a240299e20be18ba94590413f2e",
-  "buildTime": "2026-06-09T19:26:19Z",
+  "release": "5.1.0",
+  "buildId": "run-53-1",
+  "commitSha": "3a0e7525c2c606afb9a64c2d78baffa5b400cf50",
+  "buildTime": "2026-06-11T20:57:59Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/dist/{src-2O5UH4FA.js → src-SS2AL3O7.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-KDRSEHK5.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-MOHR7QUN.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,14 +41,14 @@
     "test:watch": "vitest"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.2.2",
+    "electronAppVersion": "1.4.0",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "45c09f605d05fc72c60fae54847a689e1858aac9e2c4acca7f25c17a8cd1ad7b",
-      "darwin-x64": "b662a57106f1d90c646180ac506d2f567bbbcea33b3fe5ecb9e83b8166426400",
-      "linux-x64": "2f86a28e2dc9c7777710c31001686596ce36c560c93e93c53c9bcc4470c07be4",
-      "win32-x64": "42f3f28e58efb207a0f2b4993cbc3f2232c30e20960b29b56a45e4c387777346"
+      "darwin-arm64": "9dd7ac0a378a1d5db908a102aec4f596741e943572a7d55b08e2a62f336981bc",
+      "darwin-x64": "70c9c6df21e03ad1529682e6cf8150ddfef306e1019e4b3bd2a4e7d025a98d64",
+      "linux-x64": "14ee27b3c22988bf72f13f3734e1594dcbb0fb94f699d5ad789ea8cf452dc7a1",
+      "win32-x64": "9e059917ba4605527b47d23b43bd78438cf59e7df38c4c9698f6b9487ed64a97"
     }
   },
   "dependencies": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "5.0.3",
+  "version": "5.1.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.0.3",
+  "version": "5.1.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

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

@@ -104,7 +104,7 @@ if [ -f "$prefs_global_file" ]; then
       const defaults = {
         autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
         showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
-        defaultExecutionMode:'ask', autoPublishLocalResults:'ask',
+        defaultExecutionMode:'ask',
         suggestRelatedUseCases:'ask', suggestRelatedTestCases:'ask', autoDetectChanges:'ask',
         postPRVisualWalkthrough:'ask', autoCreatePR:'ask',
         checkForUpdates:'ask', verboseOutput:'ask',

package/plugin/scripts/guardrails.mjs

@@ -27,14 +27,16 @@ function markPrHandled(sessionId2, prUrl, dirOverride) {
 
 // src/guardrails/prOpened.ts
 var PR_URL = /https:\/\/github\.com\/[^/\s]+\/[^/\s]+\/pull\/\d+/;
+var MR_URL = /https?:\/\/[^/\s]+\/[^\s]+\/-\/merge_requests\/\d+/;
 var CREATE_CMD = /\bgh\s+pr\s+(create|ready)\b/;
+var MR_CREATE_CMD = /\bglab\s+mr\s+create\b|\bglab\s+mr\s+update\b.*--ready\b/;
 function detectPrOpened(input2) {
   if (input2.tool_name !== "Bash") return null;
   const cmd = input2.tool_input?.command ?? "";
-  if (!CREATE_CMD.test(cmd)) return null;
+  if (!CREATE_CMD.test(cmd) && !MR_CREATE_CMD.test(cmd)) return null;
   const out = `${input2.tool_response?.stdout ?? ""}
 ${input2.tool_response?.output ?? ""}`;
-  const m = out.match(PR_URL);
+  const m = out.match(PR_URL) ?? out.match(MR_URL);
   return m ? m[0] : null;
 }
 

package/plugin/skills/_shared/debug-failed-run.md

@@ -0,0 +1,53 @@
+# Debug a Failed Run — Shared Reference
+
+> Presentation layer for a single failed run. Turns one non-passing terminal run — local or remote — into a debug path: **evidence → diagnosis → a guaranteed user choice that always offers "give feedback & rerun".** Used by `muggle-test` (Step 7C), `muggle-test-feature-local`, and the `muggle-do` e2e stage. Depends on [`failure-mode-handling.md`](./failure-mode-handling.md) for the bucket taxonomy and telemetry schema — never the reverse. Don't restate its tables; read them.
+
+## The guarantee
+
+Every non-passing terminal run MUST route through this doc before it is reported. A failure is never summarized-and-dropped: the user is always shown *what happened* and is always presented a selection in which **"give feedback & rerun" is a first-class option**. "Skip — just report" stays selectable but is never the default.
+
+The guarantee binds **interactive** callers. An autonomous caller with no user to prompt (the `acceptance-tester` agent) runs Steps 1–2 (evidence + diagnosis into its structured report) and skips Step 3's interactive offer.
+
+## Inputs (the caller passes these in)
+
+- `runId` (local) or workflow runtime id (remote).
+- `mode` — `replay` or `regen`, the mode that failed.
+- `testCaseId`, `projectId`.
+- A re-execute handle — the loop/tool the caller used to run this case, so a rerun re-enters the same execution path.
+
+## Step 1 — Gather evidence
+
+Read **structured run fields**, never the `execute` stdout tail (see [`dev-loop/failures.md`](./dev-loop/failures.md)). Assemble:
+
+- **Attempted steps + reasoning** — local: the attempted steps + `summaryStep` halt reason from `action-script.json` in `artifactsDir`; remote: the per-step list + `summaryStep` from `muggle-remote-wf-get-ts-gen-latest-run` / `muggle-remote-wf-get-ts-replay-latest-run`.
+- **Visual evidence** — a failed run already preserves the full step-by-step on disk: every per-step frame under `<artifactsDir>/electron-runtime/screenshot/` (with per-step label data under `.../dataset/`), alongside the step script at `<artifactsDir>/action-script.json`. `run-result-get` returns `artifactsDir` — read the whole set there; don't trust a step's `screenshotLocalPath`, which points at the original runtime dir. Once published — failed runs are published too, see [`dev-loop/publish.md`](./dev-loop/publish.md) — the same frames are cloud-hosted per step as `screenshotUrl`, the form remote runs expose directly.
+- **Verdict** — `Status` + `Error`.
+
+## Step 2 — Diagnose
+
+Classify into the failure bucket per [`failure-mode-handling.md`](./failure-mode-handling.md) — §B for a replay failure, §C for a regen failure. That bucket **is** the initial diagnosis. Phrase it for a human ("Looks like a **stale script** — the selectors moved; the product itself probably still works"), not as a telemetry label. Emit the `replay-failure-classified` / `regen-failure-classified` event now, before presenting anything.
+
+## Step 3 — Present the debug card, then the guaranteed offer
+
+Show the **debug card** first: attempted steps + reasoning, the failing step's screenshot (or a one-line note if a path is genuinely absent), and the one-line diagnosis.
+
+Then present one `AskUserQuestion` whose options are:
+
+1. **Give feedback & rerun** — always present. Invoke the `muggle-feedback` skill with this run's anchor (`runId` local / `testScriptId` remote) so the user says what should have happened, then re-execute per Step 4.
+2. **The bucket's recommended action** from §B/§C (regenerate, report bug, share defect, retry…). Label it `(Recommended)` — it is the classifier's pick.
+3. **Retry as-is**.
+4. **Skip — just report** — last, never the default.
+
+The bucket's recommended action and its alternatives live in `failure-mode-handling.md` §B/§C — read them there, don't restate them.
+
+**Feedback anchor by lane.** Feedback attaches to a cloud action-script id. `muggle-feedback` owns resolving it: for a **local** run it publishes/uploads first when the run isn't already published; for a **remote** run it uses the existing script. Pass `runId` (local) or `testScriptId` (remote) and let it resolve the anchor — don't resolve or upload here.
+
+## Step 4 — Rerun (always regen)
+
+On "give feedback & rerun": once `muggle-feedback` returns, re-execute the test case in **regen** mode — feedback adjusts the agent's course, so the prior script is discarded; replay is never the rerun path. Local: the regen branch of [`dev-loop/run.md`](./dev-loop/run.md). Remote: `muggle-remote-workflow-start-test-script-generation`. Read the new run's result back through this doc (Step 1) so a second failure is debugged too.
+
+## Step 5 — Resolve
+
+Emit the `replay-failure-resolved` / `regen-failure-resolved` event with `userAction` set to the pick (`feedback-rerun`, the bucket action, `retry`, or `skip`) — one `*-classified` and one `*-resolved` per failure, per [`failure-mode-handling.md`](./failure-mode-handling.md) §D.
+
+Process failures one at a time so the user isn't drowning in pickers.

package/plugin/skills/_shared/dev-loop/publish.md

@@ -1,13 +1,9 @@
-# Dev Loop — Publish & Screenshots
+# Dev Loop — Cloud Refs & Screenshots
 
-## Publish
+## Cloud refs
 
-After every completed run — pass or fail — publish: failed runs still need cloud-hosted screenshots and per-step actions for the walkthrough, and the upload `status` tells the backend whether to promote the action script as the canonical replay script (pass → promote; fail → record only).
-
-`muggle-local-publish-test-script` with `runId` and `cloudTestCaseId`. Retain `testScriptId`, `actionScriptId`, `viewUrl`. Batch publishes in parallel.
-
-If publish rejects with `has no generated actionScript steps to publish` (a true zero-step run), fall back to `muggle-remote-local-run-upload` with whatever exists (`summaryStep`, `errorMessage`, empty `actionScript`); capture `actionScriptId` and `viewUrl` the same way.
+The studio publishes every completed run — pass or fail — to the cloud during execution. There is no publish step to run. The run result already carries the cloud identifiers: read `viewUrl`, `cloudTestScriptId`, and `cloudActionScriptId` from `muggle-local-run-result-get` for the run. (`cloudTestScriptId` is absent for a failed generation — the backend records the action script and `viewUrl` but no test script.)
 
 ## Screenshots
 
-Per published script, `muggle-remote-test-script-get` with the `testScriptId` from publish → per step `operation.screenshotUrl` and `operation.action`. Retain `{ stepIndex, action, screenshotUrl }`. Batch in parallel. These feed the `E2eReport` consumed by [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) — the dev loop does not post to the PR.
+Per run, `muggle-remote-test-script-get` with the `cloudTestScriptId` from the run result → per step `operation.screenshotUrl` and `operation.action`. Retain `{ stepIndex, action, screenshotUrl }`. Batch in parallel. These feed the `E2eReport` consumed by [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) — the dev loop does not post to the PR.

package/plugin/skills/_shared/pr-followup-helpers/allow-list.md

@@ -2,7 +2,7 @@
 
 The address-reviews flow only acts on reviews submitted by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS ∪ {PR author}) − bots. Re-resolve every invocation — never cache across cycles.
 
-The PR author is implicitly a valid reviewer: in single-account workflows, the human running the agent and the PR's author are the same identity, and the agent must honor their reviews. Self-loop is prevented at the watcher's filter layer rather than here: `POST /pulls/<n>/comments/<id>/replies` does create an implicit review under the loop user's identity, and the watcher drops it via the loop-echo clause in [`../github-cli-recipes/submitted-reviews.md`](../github-cli-recipes/submitted-reviews.md) — matched by the loop signature ([`loop-signature.md`](loop-signature.md)), so the author's *genuine* reviews and thread replies still get through. Including the PR author in this allow-list is therefore safe.
+The PR author is implicitly a valid reviewer: in single-account workflows, the human running the agent and the PR's author are the same identity, and the agent must honor their reviews. Self-loop is prevented at the watcher's filter layer rather than here: `POST /pulls/<n>/comments/<id>/replies` does create an implicit review under the loop user's identity, and the watcher drops it via the loop-echo clause in [`../vcs/github/submitted-reviews.md`](../vcs/github/submitted-reviews.md) — matched by the loop signature ([`loop-signature.md`](loop-signature.md)), so the author's *genuine* reviews and thread replies still get through. Including the PR author in this allow-list is therefore safe.
 
 ## Step 1: requested reviewers