@muggleai/works 4.13.1 → 4.15.0

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

@@ -0,0 +1,33 @@
+# Reconcile Procedure
+
+The procedure for the **reconcile mode** of `muggle-pr-followup` — a sweep that finalizes session slots whose PR went terminal while polling was lapsed. Routing is in [`SKILL.md`](SKILL.md#routing).
+
+Termination is otherwise tick-driven ([`contract.md`](contract.md) Step 2): a slot finalizes only when a tick fires and observes `MERGED` / `CLOSED`. If the tick stream stops first — the recurring `/loop` cron auto-expires after 7 days, the session ends, or the machine is off when the PR merges — no tick catches the transition, and the slot is left un-finalized: no `result.md`, no post-merge cleanup, and a surviving cron would keep polling a dead PR. Reconcile is the catch-up.
+
+## Input
+
+`$ARGUMENTS` is `reconcile` (or `sweep`), optionally followed by a `<slug>` to scope the sweep to one slot.
+
+## Procedure
+
+### Step 1 — Enumerate slots
+
+List `~/.muggle-ai/muggle-do/sessions/*/` dirs that contain a `prs.json`. Skip any that already have a `result.md` — those are finalized. Scope to a single `<slug>` if the arg gave one.
+
+### Step 2 — Refresh live state
+
+For each candidate, fetch the PR per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md) using `prs.json[0].url`. A `gh` failure on one slot (deleted repo, missing auth) → log it to that slot's `followup.log` and skip; never abort the whole sweep.
+
+### Step 3 — Finalize the terminal ones
+
+For each candidate whose live `state` is `MERGED` or `CLOSED`, run [`finalize.md`](finalize.md). `finalize.md` dispatches nothing, so a backfilled merge gets no post-merge cleanup — its branch is typically long gone, and the `autoCleanup` gate governs if the user runs cleanup later. Slots still `open` are left untouched — reconcile finalizes, it does not re-arm a watcher (re-arming an open PR is [`auto-track.md`](auto-track.md)'s job).
+
+### Step 4 — Report
+
+One line: slots scanned, finalized (with final state each), and left open. Silent only when zero slots exist.
+
+## Invariants
+
+- **Idempotent.** A slot with `result.md` is never re-finalized; once everything terminal is swept, re-running is a no-op.
+- **Finalize-only.** Reconcile never seeds, re-arms, or dispatches a watcher. Open slots pass through untouched.
+- **Per-slot isolation.** One slot's `gh` failure never blocks finalizing the others.

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

@@ -1,9 +1,13 @@
 # Session State Schemas
 
-Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `.muggle-do/sessions/<slug>/` (the caller's session dir; `muggle-do` is the current and only caller).
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; `muggle-do` is the current and only caller).
 
 All files are atomic writes — the caller rewrites the whole file each time, never mutates in place. Use a temp file + rename if the platform supports it.
 
+## Legacy location
+
+Before the move to the user's home, slots lived at the repo-relative `.muggle-do/sessions/<slug>/` (one per working tree, still gitignored). Bootstrap's Step 5 migrates a legacy slot to the home-dir location on the next run for that PR; nothing else reads the old path. The state is ephemeral and reconstructible from GitHub, so an un-migrated slot costs only a re-bootstrap, not data.
+
 ## `prs.json`
 
 A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)
@@ -35,7 +39,9 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
     "idle_tick_count": <int>,
     "cycles_completed": <int>,
     "escalated_review_ids": [<int>, ...],
-    "pushed_shas": ["<sha>", ...]
+    "pushed_shas": ["<sha>", ...],
+    "ci_fix_attempts": { "<sha>": <int> },
+    "ci_escalated_shas": ["<sha>", ...]
   }
 }
 ```
@@ -46,6 +52,8 @@ Keyed by `"<owner>/<repo>#<n>"`. One key per PR in the slot.
 - `cycles_completed`: incremented each time `/muggle-do` completes an address-reviews invocation (regardless of actionable/ambiguous/mixed).
 - `escalated_review_ids`: review ids classified as ambiguous by `/muggle-do`. The watcher excludes these from future review fetches so the same ambiguous review is never re-dispatched.
 - `pushed_shas`: every SHA `/muggle-do` has pushed for this PR. Append-only. Used by the resolve-reminder stage to recognize threads addressed by the loop.
+- `ci_fix_attempts`: per-SHA count of fix-ci cycles `/muggle-do` has run. The watcher stops dispatching fix-ci for a SHA once its count reaches 3. Keyed by head SHA.
+- `ci_escalated_shas`: head SHAs whose CI the fix-ci stage gave up on (attempts exhausted or only out-of-scope checks). The watcher excludes these from CI dispatch so a hopeless SHA is never re-fixed.
 
 ## `state.md`
 

package/dist/plugin/skills/muggle-preferences/ops/configure.md

@@ -28,7 +28,8 @@ For each option: label = key name, description = first paragraph of `preference-
 - `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
 - `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`
 - `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`, `autoPublishLocalResults`
-- `multiSelect: true`, `header: "Suggestions & PR"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`, `postPRVisualWalkthrough`, `autoCreatePR`
+- `multiSelect: true`, `header: "Suggestions"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`
+- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`
 - `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
 - `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
 - `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).

package/dist/plugin/skills/muggle-preferences/preference-gates/autoResolveConflicts.md

@@ -0,0 +1,11 @@
+# `autoResolveConflicts`
+
+When a rebase onto `origin/{default}` hits conflicts, resolve them autonomously behind a verify-or-rollback gate, or stop and escalate. Default `never` — the loop aborts the rebase and escalates exactly as before. Opt in with `always` to resolve conflicts without a human.
+
+**Picker 1** — header `Resolve rebase conflicts?`, question `"Rebase onto origin/{default} hit conflicts in {conflicted} file(s) — resolve them autonomously?"`
+- `Resolve autonomously` — `Resolve the conflicts, then re-verify (build + unit + E2E) before any push; roll back and escalate if verification fails.` → `always`
+- `Stop and escalate` — `Abort the rebase, restore the branch, and hand the conflict to me.` → `never`
+
+**Silent action**
+- `always` → `Resolving rebase conflicts autonomously (verify-or-rollback)`
+- `never` → `Aborting rebase and escalating — conflicts in {conflicted} file(s)`

package/dist/plugin/skills/muggle-preferences/preference-gates/autoWatchPR.md

@@ -0,0 +1,13 @@
+# `autoWatchPR`
+
+After a PR is sent at the end of a test run, controls whether Muggle starts a `muggle-pr-followup` watcher on it — a loop that polls the PR for newly submitted reviews and hands them to `/muggle-do` to address — or leaves you to start one yourself with `/mprfollowup`. Fires once a PR exists (muggle-test, muggle-test-feature-local), reusing the E2E validation context from that run so the watcher never re-prompts. Substitute `{pr}`.
+
+**Picker 1** — header `Watch PR?`, question `"Watch '{pr}' for review follow-ups and address them as they land?"`
+- `Watch it` — `Start a muggle-pr-followup loop on this PR.` → `always`
+- `Ask me next time` — `Decide per run.` → `ask`
+- `Skip — I'll watch it myself` — `Leave it; run /mprfollowup later if you want.` → `never`
+
+**Silent action**
+- `always` → `Watching {pr} for review follow-ups`
+- `ask` → `Asking about PR watching`
+- `never` → `Not watching {pr}`

package/dist/plugin/skills/muggle-preferences/preference-gates/reusePreparePlan.md

@@ -0,0 +1,11 @@
+# `reusePreparePlan`
+
+Reuse the saved prepare plan for this stack (skip scope / viability / service-selection / start-commands and jump straight to check-running + smoke-test), or rediscover from scratch. Substitute `{services}` with a comma-separated list of saved service names.
+
+**Picker 1** — header `Reuse prepare plan`, question `"Found a saved plan for this stack ({services}) — reuse it, or rediscover from scratch?"`
+- `Reuse this plan` — `Skip the discovery questions; verify and start what's missing.` → `always`
+- `Rediscover from scratch` — `Re-ask scope, services, and start commands.` → `never`
+
+**Silent action**
+- `always` → `Reusing saved prepare plan ({services})`
+- `never` → `Rediscovering this stack from scratch`

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-status
-description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle Test health, MCP health, or auth validity.
+description: Use this skill to check the health of the user's Muggle AI installation and diagnose why it's misbehaving — MCP server connectivity, tool loading, login/auth validity, and overall setup. Engage on an explicit "muggle status", but also on any diagnostic question about Muggle itself: "is muggle working / healthy / set up right?", "why does muggle keep failing / timing out / saying it can't connect?", "are the muggle MCP tools actually loading?", "is my muggle login/auth still valid?", "muggle's been acting up — take a look / what's wrong?", "muggle commands fail silently — is the install unhealthy?". This is diagnosis and reporting: prefer it over answering from memory whenever the user is unsure Muggle itself is functioning. Boundary: checking/diagnosing is muggle-status; actually fixing a broken install is muggle-repair (a clear "fix it" goes there). Not for the health of the user's own app, CI, or infrastructure.
 ---
 
 # Muggle Test Status

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test
-description: "Run change-driven E2E acceptance testing using Muggle AI — detects local code changes, maps them to use cases, and generates test scripts either locally (real browser on localhost) or remotely (cloud execution on a preview/staging URL). Publishes results to Muggle Test dashboard, opens them in the browser, and posts E2E acceptance summaries with screenshots to the PR. Use this skill whenever the user wants to test their changes, run E2E acceptance tests on recent work, validate what they've been working on, or check if their code changes broke anything. Triggers on: 'test my changes', 'run tests on my changes', 'acceptance test my work', 'check my changes', 'validate my changes', 'test before I push', 'make sure my changes work', 'regression test my changes', 'test on preview', 'test on staging'. This is the go-to skill for change-driven E2E acceptance testing — it handles everything from change detection to test execution to result reporting."
+description: "Run change-driven E2E acceptance testing using Muggle AI — detect the user's recent code changes (local diff or a PR), map them to affected user flows, then run real-browser acceptance tests on localhost or a deployed preview/staging URL, publish results to the dashboard, and post a screenshot summary to the PR. Use this whenever the user wants to test, validate, check, or regression-test their own changes or work — 'test my changes', 'validate my changes', 'regression test my work', 'make sure I didn't break anything', 'did my recent commits/changes break anything or any user flows?', 'test before I push' — and especially as the acceptance-test gate before opening a pull request or merging (e.g. 'validate my changes before I open the PR' means run the acceptance suite, not just a completion checklist). The defining signal is change-driven validation of in-progress work tied to a commit, push, PR, or merge. For testing one specific named feature/flow use muggle-test-feature-local; this is not importing existing tests, configuring preferences, or replaying a single named script."
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
@@ -49,6 +49,7 @@ Gates run per `preference-gates/README.md`.
 | `showElectronBrowser` | 7A | 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 |
 
 ## Step 1: Confirm Scope of Work (Always First)
 
@@ -234,6 +235,10 @@ If the user picks "Override one or more", let them flip the mode for any test ca
 
 ## Step 7A: Execute — Local Mode
 
+### 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`):
@@ -254,45 +259,18 @@ Gate `showElectronBrowser` (per `preference-gates/README.md`). Resolve once; app
 
 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).
 
-### Determine `freshSession` per test case
-
-Before executing each test case, inspect its content (title, goal, instructions, preconditions) for signals that it requires a **clean browser state** — no prior cookies, localStorage, or logged-in session. Set `freshSession: true` when the test case involves any of:
-
-- **Registration / sign-up** — creating a new account
-- **Login / authentication** — verifying the login flow itself (not a test that merely *uses* login as a prerequisite)
-- **Cookie consent / GDPR banners** — verifying first-visit consent prompts
-- **Onboarding flows** — first-time user experiences that only appear on a fresh session
-
-If none of the above apply, omit `freshSession` (defaults to `false`, preserving any existing session state). Evaluate this per test case — in a batch, some may need it and others may not.
-
-### Run sequentially (Electron constraint)
-
-Execution itself **must** be sequential because there is only one local Electron browser. For each test case, in the order chosen, branch on the mode picked in Step 6f:
-
-**Regen-mode test case:**
-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"`.
+### Run the dev loop
 
-**Replay-mode test case:**
-1. Fetch the action script: `muggle-remote-test-script-get` (latest replayable script id) → `muggle-remote-action-script-get` (full `actionScript` — use as-is, never edit). For batches, fan these calls out in parallel before the sequential execution loop begins.
-2. Call `muggle-local-execute-replay`:
-   - `testScript`: from `muggle-remote-test-script-get`
-   - `actionScript`: from `muggle-remote-action-script-get`
-   - `localUrl`, `cwd`, `showUi`, `freshSession`: same resolution as regen
-3. Store the returned `runId` and tag the result `mode: "replay"`.
+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).
 
-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.
+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 (in parallel)
+### Collect results
 
-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.
+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`)
 
@@ -303,15 +281,7 @@ Gate `autoPublishLocalResults` (per `preference-gates/README.md`):
 
 ### Publish logic (when publishing is enabled)
 
-For every completed run, issue all `muggle-local-publish-test-script` calls in parallel (single message, multiple tool calls):
-- `runId`: The local run ID
-- `cloudTestCaseId`: The cloud test case ID
-
-This returns:
-- `viewUrl`: Direct link to view this test run on the Muggle AI dashboard
-- `testScriptId`, `actionScriptId`, `workflowRuntimeId`
-
-Store every `viewUrl` — these are used in the next steps.
+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
 
@@ -413,12 +383,24 @@ Tell the user:
 
 After reporting results:
 
-1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 10.
+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 10.
+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).
 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
+
+Once a PR exists for this work, offer to keep watching its review thread.
+
+1. Identify the PR — reuse the `gh pr view --json number,title,url` result from Step 9 if available, else run it now. No PR (none exists, none created) → Step 10.
+2. Fire [`autoWatchPR`](../muggle-preferences/preference-gates/autoWatchPR.md) with `{pr}` = `<owner>/<repo>#<number>`. On skip → Step 10.
+3. On proceed: start the watcher reusing this run's context so it never re-prompts —
+   - Seed the `muggle-pr-followup` session slot and dispatch its loop per the stage-8 seeding in [`../do/open-prs/forward.md`](../do/open-prs/forward.md) (default slug `<repo>-pr<number>`).
+   - Additionally write `state.md`'s `## Pre-flight answers` block from the context resolved this run — validation strategy, local URL, project, credentials, auth, working tree — per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields). Strategy = `local-e2e` (local run), `staging-replay` (remote), or `unit-only`/`skip` if no E2E ran.
+
+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:
@@ -462,7 +444,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.
+- **PR URLs always run in a dedicated worktree** — never switch the user's main checkout. Materialize per [`_shared/pr-branch-worktree.md`](../_shared/pr-branch-worktree.md) and pass that path as `cwd` to local execute tools; the cross-worktree single-flight lock relies on it 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/dist/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -51,6 +51,7 @@ Gates run per `preference-gates/README.md`.
 | `openTestResultsAfterRun` | 8 | Open results page on Muggle Test dashboard after run |
 | `postPRVisualWalkthrough` | 10 | Post visual walkthrough to PR after results |
 | `autoCreatePR` | 10 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
+| `autoWatchPR` | 10.5 (if a PR exists) | Start a `muggle-pr-followup` watcher on the PR after the run |
 | `autoCleanup` | post-merge | Run cleanup after the PR for this work is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)) |
 
 ## Workflow
@@ -142,41 +143,9 @@ Before deciding the target's script, resolve its prerequisite chain from the bac
 
 ### 6. Load data for the chosen path
 
-**Determine `freshSession`**
+Run the shared loop in [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md): [`freshSession`](../_shared/dev-loop/fresh-session.md), [replay vs regen](../_shared/dev-loop/run.md), [`actionScript` as-is](../_shared/dev-loop/action-script.md), [`timeoutMs`](../_shared/dev-loop/timeouts.md), and [failure interpretation](../_shared/dev-loop/failures.md).
 
-Before calling either execution tool, inspect the test case content (title, goal, instructions, preconditions) for signals that the test requires a **clean browser state** — no prior cookies, localStorage, or logged-in session. Pass `freshSession: true` when the test case involves any of:
-
-- **Registration / sign-up** — creating a new account
-- **Login / authentication** — verifying the login flow itself (not a test that merely *uses* login as a prerequisite)
-- **Cookie consent / GDPR banners** — verifying first-visit consent prompts
-- **Onboarding flows** — first-time user experiences that only appear on a fresh session
-
-If none of the above apply, omit `freshSession` (defaults to `false`, preserving any existing session state).
-
-**Generate**
-
-1. `muggle-remote-test-case-get`
-2. `muggle-local-execute-test-generation` with that test case + `localUrl` (optional: `showUi: false` for headless — defaults to visible; **`freshSession`** — see above; **`timeoutMs`** — see below)
-
-**Replay**
-
-1. `muggle-remote-test-script-get` — note `actionScriptId`
-2. `muggle-remote-action-script-get` with that id — full `actionScript`
-   **Use the API response as-is.** Do not edit, shorten, or rebuild `actionScript`; replay needs full `label` paths for element lookup.
-3. `muggle-local-execute-replay` with `testScript`, `actionScript`, `localUrl` (optional: `showUi: false` for headless — defaults to visible; **`freshSession`** — see above; **`timeoutMs`** — see below)
-
-### Local execution timeout (`timeoutMs`)
-
-The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggle-local-execute-test-generation` and `muggle-local-execute-replay`. **Exploratory script generation** (Auth0 login, dashboards, multi-step wizards, many LLM iterations) routinely **runs longer than 5 minutes** while Electron is still healthy.
-
-- **Always pass `timeoutMs`** for flows that may be long — for example **`600000` (10 min)** or **`900000` (15 min)** — unless the user explicitly wants a short cap.
-- If the tool reports **`Electron execution timed out after 300000ms`** (or similar) **but** Electron logs show the run still progressing (steps, screenshots, LLM calls), treat it as **orchestration timeout**, not an Electron app defect: **increase `timeoutMs` and retry**.
-- **Test case design:** Preconditions like "a test run has already completed" on an **empty account** can force many steps (sign-up, new project, crawl). Prefer an account/project that **already has** the needed state, or narrow the test goal so generation does not try to create a full project from scratch unless that is intentional.
-
-### Interpreting `failed` / non-zero Electron exit
-
-- **`Electron execution timed out after 300000ms`:** Orchestration wait too short — see **`timeoutMs`** above.
-- **Exit code 26** (and messages like **LLM failed to generate / replay action script**): Often corresponds to a completed exploration whose **outcome was goal not achievable** (`goal_not_achievable`, summary with `halt`) — e.g. verifying "view script after a successful run" when **no run or script exists yet** in the UI. Use `muggle-local-run-result-get` and read the **summary / structured summary**; do not assume an Electron crash. **Fix:** choose a **project that already has** completed runs and scripts, or **change the test case** so preconditions match what localhost can satisfy (e.g. include steps to create and run a test first, or assert only empty-state UI when no runs exist).
+Caller glue: `mode` is the path chosen in §5; `localUrl` from §4; `cwd` = the repo root, or the prepared worktree when one is in use.
 
 ### 7. Execute (no approval prompt; `showUi` gated by `showElectronBrowser`)
 
@@ -191,21 +160,16 @@ Gate `showElectronBrowser` (per `preference-gates/README.md`). Reuse choice with
 
 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).
 
-- `muggle-local-publish-test-script`
+- Publish per [`../_shared/dev-loop/publish.md`](../_shared/dev-loop/publish.md) — includes the zero-step `muggle-remote-local-run-upload` fallback.
 - Gate `openTestResultsAfterRun` (per `preference-gates/README.md`):
   - `always` → open `viewUrl` automatically (`open "<viewUrl>"` on macOS or OS equivalent).
   - `never` → print the URL only.
   - `ask` → run Picker 1 from `preference-gates/openTestResultsAfterRun.md` via `AskUserQuestion`; map the answer back to one of the actions above.
 
-If publish rejects with `has no generated actionScript steps to publish` (true zero-step runs — Electron never produced an action), fall back to `muggle-remote-local-run-upload` directly with whatever data exists (`summaryStep`, `errorMessage`, empty `actionScript`). This still gets the failure summary and any goal-not-achievable verdict onto the dashboard so reviewers can see why the run failed. Capture the returned `actionScriptId` and `viewUrl` from this fallback path the same way you would from publish.
-
 ### 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.
+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.
 
-- `muggle-local-run-result-get` with the run id from execute.
-- **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,12 +206,24 @@ Non-blocking — one click to dismiss. Do not re-ask for the same `runId` within
 
 After reporting results:
 
-1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → end.
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → 10.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 → end.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → 10.5.
 4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md).
 5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
+### 10.5. Offer to watch the PR for review follow-ups
+
+Once a PR exists for this work, offer to keep watching its review thread.
+
+1. Identify the PR — reuse the `gh pr view --json number,title,url` result from section 10 if available, else run it now. No PR (none exists, none created) → end.
+2. Fire [`autoWatchPR`](../muggle-preferences/preference-gates/autoWatchPR.md) with `{pr}` = `<owner>/<repo>#<number>`. On skip → end.
+3. On proceed: start the watcher reusing this run's context so it never re-prompts —
+   - Seed the `muggle-pr-followup` session slot and dispatch its loop per the stage-8 seeding in [`../do/open-prs/forward.md`](../do/open-prs/forward.md) (default slug `<repo>-pr<number>`).
+   - Additionally write `state.md`'s `## Pre-flight answers` block from the context resolved this run — validation strategy, local URL, project, credentials, auth, working tree — per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields). Strategy = `local-e2e` for this local E2E run.
+
+The `/mprfollowup` shortcut starts the same watcher manually at any time.
+
 ## Non-negotiables
 
 - No silent auth skip.
@@ -257,7 +233,7 @@ After reporting results:
 - 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.
-- Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
+- Replay/timeout discipline per [`../_shared/dev-loop/run.md`](../_shared/dev-loop/run.md) — never hand-build `actionScript`; always pass `timeoutMs`.
 - Use `AskUserQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.
 - PR posting is always optional and always delegated to the `muggle:muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-prepare
-description: "Make sure dev servers and sibling services are ready on the user's machine before running E2E acceptance tests. Checks which services need to be running, discovers sibling directories by folder name, verifies what's already listening, and offers to start anything that's missing — with the user's approval at every step. Use this skill whenever the user needs to prepare their local environment for E2E testing, verify their services are up, get their local dev stack ready, or when other muggle skills detect that required services are not listening on common ports. Triggers on: 'prepare for testing', 'make sure my services are running', 'check my local env', 'get ready for tests', 'are my services up', 'prepare local environment', 'spin up services', 'set up for E2E', 'verify my setup'. Also use when muggle-test, muggle-do, or muggle-test-feature-local need services running."
+description: "Use this skill to get a user's local environment ready before running E2E acceptance tests — verifying that the dev servers, APIs, and sibling services they need are actually up and responding, and offering to start whatever is missing (with approval at each step). Trigger whenever the user wants to confirm that specific ports or localhost URLs are listening/up before testing (e.g. 'check if localhost:3000 and the api on 8080 are listening', 'are my services up?'), make sure required services are running, spin up or prepare their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not listening on the expected ports. This is environment readiness and service startup, not running the tests themselves."
 ---
 
 # Muggle Test Prepare
@@ -45,6 +45,8 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 
 `testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
 
+This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge.
+
 **On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
 - Option 1: "Keep them running — skip to testing"
 - Option 2: "Tear down and start fresh"
@@ -59,6 +61,7 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 | Preference | Gates |
 |------------|-------|
 | `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
+| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
 
 ## Workflow
 
@@ -66,6 +69,7 @@ Run the stages in this order. The sequence number is display-only — it lives o
 
 | # | Stage | Summary |
 |:--|:------|:--------|
+| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); short-circuits to check-running on reuse |
 | 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
 | 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
 | 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |

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

@@ -6,7 +6,7 @@ Run port detection and (when an app declares a backend URL) backend-health probe
 
 If **all** required services are running, skip straight to [smoke-test](./smoke-test.md) — don't trust port-listening alone.
 
-If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. For already-running services:
+If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. **Exception:** when this stage is entered via the [reuse-plan](./reuse-plan.md) short-circuit, the missing entries already have their `command` populated in `/tmp/muggle-test-prepare.json` from the reused plan — skip `start-commands` and go straight to [env-file](./env-file.md). For already-running services:
 - Option 1: "It's fine, keep it"
 - Option 2: "Restart it"
 
@@ -16,11 +16,13 @@ Mark kept services as `external: true` in the tracking file so cleanup leaves th
 
 When the user wants a port held by a process they did **not** select (typically a stale dev server from a sibling worktree):
 
-> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+The held process is likely something the user is still using — a current test or dev server they value more than this prepare run. Don't auto-decide; leave the kill-vs-pause call to them.
 
-- Option 1: "Use the next available port" (recommended — non-destructive)
-- Option 2: "Force-kill PID 87421 and claim port 3999"
-- Option 3: "Abort"
+> "Port 3999 is held by PID 87421 (you didn't select this process — it may be a test or dev server you're still using). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive, leaves the existing process running)
+- Option 2: "Force-kill PID 87421 and claim port 3999" (kill-switch — only if you don't need that process)
+- Option 3: "Pause — leave it running, I'll finish up and re-run prepare later"
 
 **Option 1**: probe `3999 + N` for `N = 1, 2, …` until nothing listens. Record the new port and any env file edit (`PORT=` in `.env.local` etc.). Dev server may need restart to pick up.
 

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

@@ -1,5 +1,7 @@
 # Identify required services & startup mode
 
+> Skipped when [reuse-plan](./reuse-plan.md) short-circuits — a reused plan supplies the service list and startup mode.
+
 List folder names in the **parent directory** of the current working directory:
 
 ```bash

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

@@ -24,3 +24,33 @@ If you launched the services:
 Logs: /tmp/muggle-prepare-*.log
 Cleanup: say "stop services" or re-invoke this skill.
 ```
+
+## Save the plan
+
+If this run came through discovery (i.e. Stage 0 [reuse-plan](./reuse-plan.md) did **not** short-circuit), persist the plan so the next run can skip the questions.
+
+Build the JSON from the in-memory tracking file, dropping runtime fields:
+
+```bash
+jq '{
+  version: 1,
+  updated: now | todate,
+  testing_scope: .testing_scope,
+  excluded_services: .excluded_services,
+  services: [.services[] | {name, dir, command, port}]
+}' /tmp/muggle-test-prepare.json
+```
+
+Resolve the write location:
+
+- If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) → write `$REPO/.muggle-ai/prepare-plan.json`. Create `$REPO/.muggle-ai/` if missing.
+- Else → upsert the entry under key `$(dirname "$PWD")` (absolute) in `~/.muggle-ai/prepare-plans.json`. Create the file as `{}` if missing.
+
+Then print, once:
+
+```
+✓ Saved this stack as your prepare plan — next run can skip the questions.
+  (Disable with `/muggle-preferences reusePreparePlan`.)
+```
+
+If this run short-circuited via [reuse-plan](./reuse-plan.md), don't rewrite — but **do** refresh `updated` and any `command` that was re-derived during validation. Skip the announcement on the refresh path.

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

@@ -0,0 +1,44 @@
+# Stage 0 — reuse saved plan (or fall through)
+
+A previously saved **prepare plan** is the durable recipe for this stack. Distinct from the ephemeral `/tmp/muggle-test-prepare.json` tracker — that file holds live PIDs/logs and is rebuilt every run.
+
+## Resolve
+
+In order; first hit wins.
+
+1. **Project plan.** If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) and `$REPO/.muggle-ai/prepare-plan.json` exists → load it.
+2. **Global plan.** Else if `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed by `$(dirname "$PWD")` (absolute path). If present → load that entry's value.
+3. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
+
+A loaded plan is a JSON object with `version`, `updated`, `testing_scope`, `excluded_services`, `services`. Reject and treat as "no plan" if `version != 1` or `services` is empty.
+
+## Gate `reusePreparePlan`
+
+Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
+
+- `always` → silently take the **reuse path** (below). Print the silent footer (substitute `{services}` with the comma-separated names from the loaded plan).
+- `never` → take the **rediscover path**: exit this step; continue at [rebase-check](./rebase-check.md).
+- `ask` → print the loaded plan as a table:
+
+  ```
+  Service              Directory                          Command          Port
+  ──────────────────────────────────────────────────────────────────────────────
+  backend-api          ~/Github/backend-api               npm run dev      3001
+  …
+  ──────────────────────────────────────────────────────────────────────────────
+  ```
+
+  Run Picker 1 from the gate file (substitute `{services}`). Then Picker 2 ("Remember this choice?") per the shared template. Branch by Picker 1.
+
+## Reuse path
+
+1. **Validate per service entry.** For each `{name, dir, command, port}`:
+   - `dir` exists → keep. Else drop the entry and log `"Dropped <name>: directory <dir> no longer exists"`.
+   - The indicator file that produced `command` still exists in `dir` (e.g. `package.json` for an `npm`/`node` command; see the indicator table in [start-commands](./start-commands.md)) → keep. Else re-derive **just that one entry** by running the indicator-detection from [start-commands](./start-commands.md) against `dir`, and replace its `command`. Log `"Re-derived <name>: <old> → <new>"`.
+2. **All entries dropped** → discard the plan; continue at [rebase-check](./rebase-check.md). Otherwise proceed with surviving + re-derived entries.
+3. **Hydrate** `/tmp/muggle-test-prepare.json` with the surviving entries (no PIDs yet, `testing_scope` from the plan, `excluded_services` from the plan).
+4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md) — the reused plan supplies their answers. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
+
+## Rediscover path
+
+Continue at [rebase-check](./rebase-check.md). The full normal flow runs.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.13.1",
-  "buildId": "run-44-1",
-  "commitSha": "2a73f80aae062cd7e19babb81f87727ccbd9aff7",
-  "buildTime": "2026-05-28T07:33:33Z",
+  "release": "4.15.0",
+  "buildId": "run-46-1",
+  "commitSha": "59c2e1e75b899d5bbf78e7bbb2e2a0318c2e7e96",
+  "buildTime": "2026-06-02T05:38:12Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "4.13.1",
+  "version": "4.15.0",
   "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
   "type": "module",
   "main": "dist/index.js",
@@ -41,14 +41,14 @@
     "test:watch": "vitest"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.0.101",
+    "electronAppVersion": "1.0.109",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
     "runtimeTargetDefault": "production",
     "checksums": {
-      "darwin-arm64": "2c73d9aa22740b6fc90f8dadccdc137c6fa87f1ce17ad5bcfd3f721b305c4807",
-      "darwin-x64": "dcc5e05b8382a15058c691c109af313b07f91e6470bc4a5b7f789ba82e6b7fa3",
-      "linux-x64": "24eeb304e5d302372984f1d2d0a15e337dcf949f7cfcd7b8c351c7d0d9d6e784",
-      "win32-x64": "6a391b516eaf30052f84277b90fa12393d32c1428e3f87c2f0eca241e6504a93"
+      "darwin-arm64": "9c2fa21b4e090c8b6f1acedf1bdbd824f0032a5d91d6f9abd3ca25cebee7f417",
+      "darwin-x64": "3369988c627be5d362d5d9c8312f9902063a98a53d308695b40873211960501c",
+      "linux-x64": "a986757132b45a4299a44c3dd1f3945ba6814d299e677380e2061f18da44b511",
+      "win32-x64": "29ab5400d7dca049e4a3e75b76bc3e06398b88743f0a49d38fa6ae531fc980fe"
     }
   },
   "dependencies": {
@@ -71,6 +71,7 @@
     "@types/uuid": "^11.0.0",
     "@typescript-eslint/eslint-plugin": "^8.34.0",
     "@typescript-eslint/parser": "^8.34.0",
+    "@vitest/coverage-v8": "4.1.5",
     "eslint": "^10.2.0",
     "eslint-plugin-unused-imports": "^4.2.0",
     "rimraf": "^6.0.1",