@muggleai/works 5.28.0 → 5.29.0-staging.256

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "muggleai",
       "source": "./plugin",
       "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-      "version": "5.28.0"
+      "version": "5.29.0-staging.256"
     }
   ]
 }

package/README.md

@@ -165,7 +165,7 @@ Nested GitLab namespaces of any depth are handled — the project path is everyt
 
 ### The pull-request walkthrough check
 
-When a PR is opened from a session running this plugin, Muggle reserves a comment for the acceptance walkthrough and holds the turn open until it's settled — by the walkthrough, or by a stated reason acceptance testing doesn't apply. A PR that changes only docs, tests, lint/format config, or CI config needs neither: its comment opens already settled as skipped.
+When a PR is opened from a session running this plugin, Muggle reserves a comment for the acceptance walkthrough and holds the turn open until it's settled. The comment moves through three stages, edited in place: **waiting for the E2E feasibility check**; then **E2E running — waiting for the report** or **E2E not feasible** with the reason; then the E2E report. A PR that changes only docs, tests, lint/format config, or CI config opens straight at its reason. A session that ends without a run or a reason leaves the comment at the stage it reached, and the check stays unsettled.
 
 A PR opened any other way — the web UI, a teammate without the plugin — never passes through that session, so the same check also runs in GitHub Actions. It fails while the comment is still empty, and whenever the walkthrough reports a failed or inconclusive test case; the check's summary names each one with its failing step and a link to the run. While a new E2E run is underway on the PR, the check stays in progress until that run's walkthrough replaces the previous one. When the Muggle PR watcher sees it red, it repairs the cases, re-runs the whole suite, and re-settles the comment.
 

package/dist/{chunk-N3G4AX6M.js → chunk-XEKNDWXD.js}

@@ -360,6 +360,7 @@ function parentIsAlive(pid) {
 var REPORT_SENTINEL = "muggle-pr-section";
 var WALKTHROUGH_SLOT_MARKER = "<!-- muggle-pr-walkthrough:v1 -->";
 var WALKTHROUGH_SKIPPED_MARKER = "<!-- muggle-pr-walkthrough-status:skipped -->";
+var RETIRED_UNREASONED_SKIP_HEADLINE = "**No E2E run, and no verified reason given.**";
 var WALKTHROUGH_COMMENT_HEADING = "### Muggle AI \u2014 PR visual walkthrough";
 var RERUN_NOTICE_OPENING = "<!-- muggle-pr-walkthrough-rerun -->";
 var SHORT_SHA_LENGTH = 7;
@@ -3303,14 +3304,14 @@ function renderReservedComment() {
   return `${WALKTHROUGH_SLOT_MARKER}
 ${WALKTHROUGH_COMMENT_HEADING}
 
-_Awaiting the E2E acceptance run. Muggle edits this comment in place when the run finishes \u2014 or records why E2E does not apply to this change._`;
+**Waiting for the E2E feasibility check.** This comment updates in place \u2014 next with the E2E run in progress or why E2E is not feasible for this change, then with the E2E report.`;
 }
 function renderDependencyBotComment(login) {
   return `${WALKTHROUGH_SLOT_MARKER}
 ${WALKTHROUGH_SKIPPED_MARKER}
 ${WALKTHROUGH_COMMENT_HEADING}
 
-**No E2E run \u2014 not applicable.** A dependency update opened by \`${login}\`; no coding session ran on it.`;
+**E2E not feasible.** A dependency update opened by \`${login}\`; no coding session ran on it.`;
 }
 var shortSha = (sha) => sha.slice(0, SHORT_SHA_LENGTH);
 function renderNoAppLogicChangeComment(declared, headSha, lastFullRun) {
@@ -3340,7 +3341,9 @@ function isRerunInProgress(bodies) {
 function classifyComment(body) {
   if (body.includes(REPORT_SENTINEL)) return "reported" /* Reported */;
   if (!body.includes(WALKTHROUGH_SLOT_MARKER)) return "not-designated" /* NotDesignated */;
-  if (body.includes(WALKTHROUGH_SKIPPED_MARKER)) return "skipped" /* Skipped */;
+  if (body.includes(WALKTHROUGH_SKIPPED_MARKER) && !body.includes(RETIRED_UNREASONED_SKIP_HEADLINE)) {
+    return "skipped" /* Skipped */;
+  }
   return "pending" /* Pending */;
 }
 function walkthroughVerdict(bodies) {
@@ -3514,7 +3517,7 @@ var OUTCOME_CONCLUSIONS = {
 };
 var FIXED_SUMMARIES = {
   ["settled" /* Settled */]: "This PR's Muggle AI walkthrough comment is settled \u2014 every E2E acceptance case passed, or it states why E2E does not apply.",
-  ["rerun-in-progress" /* RerunInProgress */]: "A new E2E acceptance run is in progress on this PR. The walkthrough comment still shows the previous run; this check settles when the new run's walkthrough replaces it.",
+  ["rerun-in-progress" /* RerunInProgress */]: "An E2E acceptance run is in progress on this PR. This check settles when the run's walkthrough replaces the comment.",
   ["unsettled" /* Unsettled */]: "This PR's Muggle AI walkthrough comment is still empty. Run the E2E acceptance suite and post the walkthrough into it (/muggle:muggle-test), or record why E2E does not apply to this change.",
   ["unreadable" /* Unreadable */]: "The PR's comments could not be read, so the walkthrough duty could not be judged."
 };

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-N3G4AX6M.js';
+import { runCli } from './chunk-XEKNDWXD.js';
 import './chunk-YMFQHBLJ.js';
 
 // src/cli/main.ts

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-N3G4AX6M.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-XEKNDWXD.js';
 export { createChildLogger, e2e_exports as e2e, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, e2e_exports as qa, src_exports as shared } from './chunk-YMFQHBLJ.js';

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

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0",
+  "version": "5.29.0-staging.256",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.codex-mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0",
+        "@muggleai/works@5.29.0-staging.256",
         "serve"
       ],
       "env": {

package/dist/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.28.0",
+  "version": "5.29.0-staging.256",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
   "author": {
     "name": "Muggle AI",

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0",
+  "version": "5.29.0-staging.256",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0",
+        "@muggleai/works@5.29.0-staging.256",
         "serve"
       ]
     }

package/dist/plugin/hooks/README.md

@@ -47,14 +47,14 @@ Pre-filters are bash builtins only (`guardrail-lib.sh`), so an irrelevant event
 | `PostToolUse` (Bash) | `guardrail-record-comment-replies.sh` | record | an unresolved-thread fetch named review threads still awaiting an answer (classified by the `<!-- muggle-do:bot -->` marker, never the author login), a threaded reply the provider **confirmed** answered comments in one, or a `MUGGLE_REPLY_SKIP` marker deferred them | — | claim each thread and cover the comments answered, in the per-PR ledger beside the muggle-do slot |
 | `PreToolUse` (Bash, `if` a command names `gh`/`glab`) | `guardrail-report-format.sh` | **enforce** | a `gh pr comment\|create\|edit` body — or a `gh api … issues/comments/<id>` PATCH editing one — reads like an E2E report but lacks the `build-pr-section` sentinel | — | **deny** — render via `muggle build-pr-section` instead |
 | `PreToolUse` (muggle local execute/replay) | `guardrail-classify-gate.sh` | **enforce** | `muggle-test` is the skill in play and the target test case has no `pre-execution-classification` this session | — | **deny** — run Step 6f first (it calls `muggle-remote-test-script-list`, which is where the run learns the case has never passed) or record a legitimate skip via `MUGGLE_CLASSIFY_SKIP`. Scoped to `muggle-test`, so the single-target skills that legitimately skip classification are untouched; fails open when the test case can't be resolved |
-| `PreToolUse` (muggle local execute/replay) | `guardrail-walkthrough-rerun.sh` | record | a browser run is about to start in a working tree (the tool call's `cwd`) whose branch has a PR, and that PR's walkthrough comment already shows a run or a skip | — | a detached job puts a "new E2E run in progress" banner, with its UTC start time, on top of the walkthrough the run will replace. The comment underneath is untouched; the walkthrough check stays in progress until the run's own walkthrough replaces the whole body, banner included, and the walkthrough gate counts the PR as still owing that walkthrough. A reserved placeholder or a comment already bannered is left alone |
-| `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks). Quiet while a background acceptance-tester is in flight |
+| `PreToolUse` (muggle local execute/replay) | `guardrail-walkthrough-rerun.sh` | record | a browser run is about to start in a working tree (the tool call's `cwd`) whose branch has a PR with a walkthrough comment | — | a detached job marks the comment with the run in progress and its UTC start time: a feasibility-check placeholder becomes "E2E running — waiting for the report"; a comment that already shows a run or a skip gets a "new E2E run in progress" banner on top, left untouched underneath. The walkthrough check stays in progress until the run's own walkthrough replaces the whole body, and the walkthrough gate counts the PR as still owing that walkthrough. A comment already marked is left alone |
+| `Stop` | `guardrail-e2e-gate.sh` | **enforce** | unit tests passed this session, no E2E ran yet, and no skip was recorded | `autoE2ETest` | **block** the turn until E2E runs via `muggle-test` or a `MUGGLE_E2E_SKIP` marker records a legitimate skip (full message once, one-line reminders after; releases after 3 blocks, leaving the PR's walkthrough comment unsettled). Quiet while a background acceptance-tester is in flight |
 | `Stop` | `guardrail-terminal-gate.sh` | **enforce** | a PR went terminal this session and the next-options offer hasn't run since — an AskUserQuestion, or, while the session owns an open PR's watch slot, a closing message that asks the user | — | **block** the turn until the post-merge handoff runs (full message once, one-line reminders after; releases after 3 blocks; nothing but the offer resets the counter) |
 | `Stop` | `guardrail-watch-gate.sh` | **enforce** | a PR opened this session that is still open and has no live watch — no session slot for it is terminal, stopped by its owner, or carries a `watch-heartbeat` touched within 15 minutes; a slot that is only seeded does not count | `autoWatchPR` | **block** the turn until the watch is armed per `muggle-pr-followup`'s `arm-watcher.md` or a `MUGGLE_WATCH_SKIP` marker records a legitimate skip (releases after 3 blocks). A PR clears once the session sees it go terminal or a provider lookup reports it merged or closed — what lets a PR whose slot post-merge cleanup deleted through. The lookup runs in a detached scan queued at turn end; a PR it has not reached yet still blocks, and one it could not reach fails open |
 | `Stop` | `guardrail-watch-follow-through-gate.sh` | **enforce** | a `muggle-pr-followup` watch this session owns (the slot's `owner.json`) recorded due work in `watch-due.env` — a branch behind or conflicting with its base, or a head whose checks settled red — and `last_seen.json` records no attempt for it: no `conflict_resolve_attempts` entry for the rebase key (enforced under `autoRebase=always` while catch-up budget is left), no `ci_fix_attempts` entry for the red head. An escalation entry with no attempt behind it counts for nothing, and re-arming the watch changes nothing | `autoRebase` | **block** the turn, naming each PR and its `/muggle-do rebase` or `fix ci` dispatch. No release after N blocks: only a recorded attempt, a newer head in the slot's `prs.json`, or the user's literal `HOLD WATCH #<pr-number>` clears it. The hold must come from a turn the user typed — never a tool result, a loaded skill, a hook's message, a task notification, a compaction summary, or the agent's own text — and is kept for the session once read. Reads local files only, never a provider: the pre-filter is a builtins glob for a non-empty `watch-due.env` whose `owner.json` names the session, so Node starts only when a slot has due work |
 | `Stop` | `guardrail-walkthrough-gate.sh` | **enforce** | an E2E acceptance run happened this session and a PR in play — opened this session or on the working branch — carries no walkthrough in its body or comments, or only one under a "new E2E run in progress" banner; or an E2E skip was accepted and a PR it covers still shows the empty placeholder instead of the skip's record | `postPRVisualWalkthrough` | **block** the turn until the walkthrough is posted via `muggle-pr-visual-walkthrough` or a `MUGGLE_WALKTHROUGH_SKIP` marker records a legitimate skip. For a PR an accepted E2E skip covers, the block hands over the foreground `settle-walkthrough-skipped <pr> <session>` command, which prints `{"settled":true}` once the PR reads back the skip, and re-queues the detached write; a PR the skip does not cover is a different change and is told to run its own E2E or declare its own skip from its tree (releases after 3 blocks; an unreachable PR fails open to not-owed). A skip accepted before its PR existed is written straight into the PR's slot when it opens for the same repo and branch. The provider lookups run in a detached scan, queued when the gate arms, when a PR opens, and at each turn end; the gate decides on the last scan for the session's current PRs, begun after the last observed post, and stays open until one lands. Each PR is checked for its own walkthrough: a post to one PR settles only that one, and opening another re-arms the check. A PR whose own background run is in flight is set aside |
 | `Stop` | `guardrail-stage-gate.sh` | **enforce** | a skill invoked this session declared `mandatoryStages` and one of those files was never opened | — | **block** the turn until the stages are read or a `MUGGLE_STAGE_SKIP` marker records a legitimate skip (releases after 3 blocks) |
-| `Stop` | `guardrail-debug-path-gate.sh` | **enforce** | a local execution returned a non-passing run this session and nothing routed it through `_shared/debug-failed-run.md` | — | **block** the turn until the run is diagnosed (its `*-failure-classified` emit or feedback naming it) or a `MUGGLE_DEBUG_SKIP: <runId> <reason>` marker clears that run (releases after 3 blocks). Quiet while a background acceptance-tester is in flight — its failed runs land in this session's state and it debugs them itself |
+| `Stop` | `guardrail-debug-path-gate.sh` | **enforce** | a local execution returned a non-passing run this session and nothing routed it through `_shared/debug-failed-run.md` | — | **block** the turn until the run is diagnosed (its `*-failure-classified` emit or feedback naming it) or a `MUGGLE_DEBUG_SKIP: <runId> <reason>` marker clears that run (releases after 3 blocks, leaving the PR's walkthrough comment unsettled). Quiet while a background acceptance-tester is in flight — its failed runs land in this session's state and it debugs them itself |
 | `Stop` | `guardrail-comment-reply-gate.sh` | **enforce** | this session claimed a review thread and left one of its comments uncovered | — | **block** the turn until each comment gets its threaded reply per `do/per-comment-replies.md` or a `MUGGLE_REPLY_SKIP: <comment-id> <reason>` marker defers it (releases after 3 blocks). The claim is the signal, not a push, so a round that answers a question with no code change is caught too; a thread another session claimed never blocks this one |
 | `Stop` | `guardrail-capability-claim.sh` | **enforce** | the closing turn tells the user a login- or code-gated flow can't be tested, reached, or verified | — | **block** once, citing `_shared/identity-and-inbox.md`: the managed profile's live inbox, provisioned number, stored TOTP secret, credentials, and CAPTCHA solver clear exactly that blocker. Reads the claim out of the transcript, since a Stop payload carries no message text. Per-sentence matching, and a sentence naming a voice call, an OAuth-only provider, or a deployment with no number provisioned never fires — those limits are real. Nudges once per session, then stays quiet, so a misread costs one turn |
 | `UserPromptSubmit` | `guardrail-build-router.sh` | advise | a build/implement/fix request (first one this session), or a direct `/muggle-do` / `/mdo` forward invocation | `autoRouteBuildToMuggleDo` | route the work through `muggle-do` (build delegated to superpowers); a direct invocation gets no advice. Either arms the build follow-through Stop gate |

package/dist/plugin/scripts/guardrail-dispatch.sh

@@ -23,8 +23,14 @@ guardrail_read_payload
 firing_subcommands=()
 for gate_script in "$@"; do
   GUARDRAIL_SUBCOMMAND=""
+  unset -f guardrail_shell_verdict
   . "$guardrail_script_dir/$gate_script" || continue
   if [[ -n $GUARDRAIL_SUBCOMMAND ]] && guardrail_wants; then
+    # A gate that can answer in-shell blocks the turn here, before Node's cold start can outlast the hook's cap;
+    # the gates after it run on the turn end that follows.
+    if declare -F guardrail_shell_verdict >/dev/null && guardrail_shell_verdict; then
+      exit 0
+    fi
     firing_subcommands+=("$GUARDRAIL_SUBCOMMAND")
   fi
 done

package/dist/plugin/scripts/guardrail-e2e-gate.sh

@@ -28,6 +28,30 @@ guardrail_wants() {
     && ! guardrail_state_has '"e2eRun": true'
 }
 
+# Returns the block guardrails.mjs rendered ahead of time (writeE2eStopVerdict), without starting Node, while the
+# budget it shares with Node's own blocks lasts. A Stop hook that outlives its one-second cap is dropped and the turn
+# ends unblocked, and Node's cold start alone has taken seconds on a loaded Windows machine, so a block that waits on
+# Node is one that can silently never land. Returns 1, leaving the decision and the release to Node, when nothing is
+# rendered or the budget is spent.
+guardrail_shell_verdict() {
+  local verdict_file="${GUARDRAIL_STATE_FILE%.json}.e2e-stop-verdict"
+  local shell_blocks_file="${GUARDRAIL_STATE_FILE%.json}.e2e-shell-blocks"
+  [[ -f $verdict_file ]] || return 1
+  local verdict=""
+  IFS= read -r -d '' verdict <"$verdict_file" || true
+  local max_blocks="${verdict%%$'\n'*}"
+  local hook_output="${verdict#*$'\n'}"
+  [[ $max_blocks =~ ^[0-9]+$ && -n $hook_output && $hook_output != "$verdict" ]] || return 1
+  local recorded_blocks_pattern='"e2eBlockCount"[[:space:]]*:[[:space:]]*([0-9]+)'
+  local recorded_blocks=0
+  [[ $GUARDRAIL_STATE =~ $recorded_blocks_pattern ]] && recorded_blocks="${BASH_REMATCH[1]}"
+  local shell_blocks=""
+  [[ -f $shell_blocks_file ]] && { IFS= read -r -d '' shell_blocks <"$shell_blocks_file" || true; }
+  ((recorded_blocks + ${#shell_blocks} < max_blocks)) || return 1
+  { printf 'x' >>"$shell_blocks_file"; } 2>/dev/null || return 1
+  printf '%s' "$hook_output"
+}
+
 if guardrail_is_hook_script; then
   guardrail_run_standalone "$GUARDRAIL_SUBCOMMAND"
 fi

package/dist/plugin/scripts/guardrail-lib.sh

@@ -154,6 +154,7 @@ guardrail_run_node() {
 guardrail_run_standalone() {
   guardrail_read_payload
   if guardrail_wants; then
+    declare -F guardrail_shell_verdict >/dev/null && guardrail_shell_verdict && return 0
     guardrail_run_node "$1"
   else
     printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -105,6 +105,10 @@ var SUBAGENT_DISPATCH_TOOL_NAMES = ["Agent", "Task"];
 var ACCEPTANCE_TESTER_SUBAGENT_TYPE = /(?:^|:)acceptance-tester$/;
 var ACCEPTANCE_REPORT_MARKERS = ["## Test Summary", "**Overall:**"];
 var DELEGATED_E2E_WINDOW_MS = 60 * 6e4;
+var E2E_STOP_VERDICT_SUFFIX = ".e2e-stop-verdict";
+var E2E_SHELL_BLOCKS_SUFFIX = ".e2e-shell-blocks";
+var AUTO_E2E_TEST_PREFERENCE_KEY = "autoE2ETest";
+var POST_PR_VISUAL_WALKTHROUGH_PREFERENCE_KEY = "postPRVisualWalkthrough";
 
 // src/guardrails/store/fileLock.ts
 function isProcessAlive(pid) {
@@ -220,6 +224,25 @@ function readPrStateScan(sessionId2, dirOverride) {
 function writePrStateScan(sessionId2, scan, dirOverride) {
   writeAtomically(fileFor(sessionId2, dirOverride, PR_STATE_SCAN_SUFFIX), scan, dirOverride);
 }
+function writeE2eStopVerdict(sessionId2, maxBlocks, hookOutput, dirOverride) {
+  mkdirSync(baseDir(dirOverride), { recursive: true });
+  const target = fileFor(sessionId2, dirOverride, E2E_STOP_VERDICT_SUFFIX);
+  const staging = `${target}.${process.pid}.tmp`;
+  writeFileSync(staging, `${maxBlocks}
+${hookOutput}`);
+  renameSync(staging, target);
+  writeFileSync(fileFor(sessionId2, dirOverride, E2E_SHELL_BLOCKS_SUFFIX), "", { flag: "a" });
+}
+function readE2eShellBlockCount(sessionId2, dirOverride) {
+  try {
+    return readFileSync(fileFor(sessionId2, dirOverride, E2E_SHELL_BLOCKS_SUFFIX), "utf-8").length;
+  } catch {
+    return 0;
+  }
+}
+function clearE2eShellBlocks(sessionId2, dirOverride) {
+  rmSync(fileFor(sessionId2, dirOverride, E2E_SHELL_BLOCKS_SUFFIX), { force: true });
+}
 var lockFor = (sessionId2, dirOverride) => `${fileFor(sessionId2, dirOverride)}.lock`;
 function commitUnderHeldLock(sessionId2, mutate, dirOverride) {
   const current = readState(sessionId2, dirOverride);
@@ -280,7 +303,6 @@ var GuardrailBackgroundJob = /* @__PURE__ */ ((GuardrailBackgroundJob2) => {
   GuardrailBackgroundJob2["ReserveWalkthroughComment"] = "reserve-walkthrough-comment";
   GuardrailBackgroundJob2["SettleWalkthroughSkipped"] = "settle-walkthrough-skipped";
   GuardrailBackgroundJob2["SettleBranchWalkthroughSkipped"] = "settle-branch-walkthrough-skipped";
-  GuardrailBackgroundJob2["SettleWalkthroughUnreasoned"] = "settle-walkthrough-unreasoned";
   GuardrailBackgroundJob2["SettleWalkthroughNoAppLogicChange"] = "settle-walkthrough-no-app-logic-change";
   GuardrailBackgroundJob2["NoteWalkthroughRerun"] = "note-walkthrough-rerun";
   GuardrailBackgroundJob2["ScanWatchPrStates"] = "scan-watch-pr-states";
@@ -629,6 +651,7 @@ function applyE2eSkipScope(state, verifiedChange) {
 var REPORT_SENTINEL = "muggle-pr-section";
 var WALKTHROUGH_SLOT_MARKER = "<!-- muggle-pr-walkthrough:v1 -->";
 var WALKTHROUGH_SKIPPED_MARKER = "<!-- muggle-pr-walkthrough-status:skipped -->";
+var RETIRED_UNREASONED_SKIP_HEADLINE = "**No E2E run, and no verified reason given.**";
 var WALKTHROUGH_COMMENT_HEADING = "### Muggle AI \u2014 PR visual walkthrough";
 var REPORT_SENTINEL_TAG = new RegExp(`<!--\\s*${REPORT_SENTINEL}[^>]*-->\\s*`, "g");
 var LAST_FULL_RUN_OPENING = "<details><summary>Last full E2E run on this PR</summary>";
@@ -1024,7 +1047,15 @@ function renderReservedComment() {
   return `${WALKTHROUGH_SLOT_MARKER}
 ${WALKTHROUGH_COMMENT_HEADING}
 
-_Awaiting the E2E acceptance run. Muggle edits this comment in place when the run finishes \u2014 or records why E2E does not apply to this change._`;
+**Waiting for the E2E feasibility check.** This comment updates in place \u2014 next with the E2E run in progress or why E2E is not feasible for this change, then with the E2E report.`;
+}
+function renderRunningComment(startedAt) {
+  return `${WALKTHROUGH_SLOT_MARKER}
+${WALKTHROUGH_COMMENT_HEADING}
+
+${RERUN_NOTICE_OPENING}
+**E2E running \u2014 waiting for the report.** Started ${formatUtcMinute(startedAt)}. This comment becomes the E2E report when the run finishes.
+${RERUN_NOTICE_CLOSING}`;
 }
 function renderSkippedComment(code, detail) {
   const stated = detail.trim();
@@ -1034,24 +1065,17 @@ function renderSkippedComment(code, detail) {
 ${WALKTHROUGH_SKIPPED_MARKER}
 ${WALKTHROUGH_COMMENT_HEADING}
 
-**No E2E run.** Muggle verified \`${code}\` \u2014 ${E2E_SKIP_CODE_CLAIMS[code]}${qualifier}.`;
+**E2E not feasible.** Muggle verified \`${code}\` \u2014 ${E2E_SKIP_CODE_CLAIMS[code]}${qualifier}.`;
 }
 function renderNotApplicableComment(reason) {
   return `${WALKTHROUGH_SLOT_MARKER}
 ${WALKTHROUGH_SKIPPED_MARKER}
 ${WALKTHROUGH_COMMENT_HEADING}
 
-**No E2E run \u2014 not applicable.** ${reason.replace(/\.$/, "")}.
+**E2E not feasible.** ${reason.replace(/\.$/, "")}.
 
 _The coding agent judged that a browser run cannot exercise this change (\`${"NOT_APPLICABLE" /* NotApplicable */}\`). Muggle did not verify this reason._`;
 }
-function renderUnreasonedSkipComment() {
-  return `${WALKTHROUGH_SLOT_MARKER}
-${WALKTHROUGH_SKIPPED_MARKER}
-${WALKTHROUGH_COMMENT_HEADING}
-
-**No E2E run, and no verified reason given.** The session ended still owing an acceptance run and cited no skip code that Muggle could verify. Treat this PR as unvalidated by E2E.`;
-}
 var shortSha = (sha) => sha.slice(0, SHORT_SHA_LENGTH);
 function renderNoAppLogicChangeComment(declared, headSha, lastFullRun) {
   const cycleStart = declared.preCycleSha.toLowerCase();
@@ -1101,7 +1125,9 @@ ${RERUN_NOTICE_CLOSING}
 function classifyComment(body) {
   if (body.includes(REPORT_SENTINEL)) return "reported" /* Reported */;
   if (!body.includes(WALKTHROUGH_SLOT_MARKER)) return "not-designated" /* NotDesignated */;
-  if (body.includes(WALKTHROUGH_SKIPPED_MARKER)) return "skipped" /* Skipped */;
+  if (body.includes(WALKTHROUGH_SKIPPED_MARKER) && !body.includes(RETIRED_UNREASONED_SKIP_HEADLINE)) {
+    return "skipped" /* Skipped */;
+  }
   return "pending" /* Pending */;
 }
 function walkthroughVerdict(bodies) {
@@ -1813,10 +1839,14 @@ function applyStateMutation(state, mutation) {
 function commitStateMutation(sessionId2, mutation, observedState) {
   if (observedState && applyStateMutation(observedState, mutation) === observedState) return observedState;
   const committed = commitState(sessionId2, (state) => applyStateMutation(state, mutation));
-  if (committed) return committed;
+  if (committed) return withShellBlocksReset(committed);
   deferStateMutation(sessionId2, mutation);
   startBackgroundJob("commit-deferred-state" /* CommitDeferredState */, [sessionId2]);
-  return applyStateMutation(readState(sessionId2), mutation);
+  return withShellBlocksReset(applyStateMutation(readState(sessionId2), mutation));
+}
+function withShellBlocksReset(state) {
+  if (state.e2eRun === true) clearE2eShellBlocks(state.sessionId);
+  return state;
 }
 function commitDeferredSessionState(sessionId2) {
   commitDeferredStateMutations(sessionId2, applyStateMutation);
@@ -1922,19 +1952,52 @@ function isE2ERun(input2) {
   if (MUGGLE_E2E_RUN_TOOL.test(input2.tool_name ?? "")) return true;
   return MUGGLE_SKILL_EMIT_TOOL.test(input2.tool_name ?? "") && input2.tool_input?.skillName === MUGGLE_TEST_SKILL_NAME;
 }
+
+// src/guardrails/e2eOwedReason.ts
+var describePreference = (preferenceKey, configuredValue) => `${preferenceKey}=${configuredValue ?? "unset"}`;
+function buildE2eOwedReason(input2) {
+  const isE2eMandated = input2.isE2eMandatedByUser;
+  const isWalkthroughMandated = input2.postPRVisualWalkthrough === ALWAYS_PREFERENCE_VALUE;
+  const preferenceSummary = `${describePreference(AUTO_E2E_TEST_PREFERENCE_KEY, input2.autoE2ETest)}, ${describePreference(POST_PR_VISUAL_WALKTHROUGH_PREFERENCE_KEY, input2.postPRVisualWalkthrough)} (~/.muggle-ai/preferences.json)`;
+  const walkthroughStep = isWalkthroughMandated ? `, then post the run's walkthrough to the PR via ${input2.walkthroughSkill}` : "";
+  const offeredSkipCodes = isE2eMandated ? E2E_SKIP_CODES.filter((skipCode) => skipCode !== "NOT_APPLICABLE" /* NotApplicable */) : E2E_SKIP_CODES;
+  const skipClause = `To skip, run \`echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"\` citing one of ${offeredSkipCodes.join(", ")}. Muggle verifies each code itself, so one that does not hold leaves this gate blocked.`;
+  if (input2.blockCount > 1) {
+    return `E2E acceptance run still owed (reminder ${input2.blockCount}/${input2.maxBlocks}; ${preferenceSummary}): run ${input2.muggleTestSkill}${walkthroughStep}, or cite a verifiable code via \`echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"\`.`;
+  }
+  const owedSentence = `Do not end the turn yet. This session went unit-green or opened a PR, but no E2E acceptance run has happened. Preferences: ${preferenceSummary}. `;
+  if (isE2eMandated) {
+    return owedSentence + `That is the user's standing answer: do not ask them whether to test, and do not end the turn handing the decision back. Run change-driven E2E now via ${input2.muggleTestSkill}${walkthroughStep}, then finish. ${skipClause} A judgment that the change is not worth a run is not a skip.`;
+  }
+  return owedSentence + `Run change-driven E2E now via ${input2.muggleTestSkill}${walkthroughStep}, then finish. ${skipClause} Only when no verifiable code fits and a browser run genuinely cannot exercise the change, cite ${"NOT_APPLICABLE" /* NotApplicable */} with the reason \u2014 the PR shows it as your unverified judgment.`;
+}
 function parseMaxCatchUpRebases(configuredValue) {
   if (configuredValue === UNBOUNDED_PREFERENCE_VALUE) return null;
   const spelled = typeof configuredValue === "number" ? String(configuredValue) : configuredValue;
   return typeof spelled === "string" && POSITIVE_INTEGER.test(spelled) ? Number(spelled) : void 0;
 }
+var readUserPreferences = (homeDir) => asRecord(readJsonRecord(join(homeDir, ...USER_PREFERENCES_PATH_SEGMENTS)).preferences);
+function readPreferenceLayers(homeDir, pluginRoot) {
+  return [readUserPreferences(homeDir), readJsonRecord(join(pluginRoot, ...PREFERENCE_DEFAULTS_PATH_SEGMENTS))];
+}
+function pickPreferenceValue(preferenceLayers, preferenceKey) {
+  const configuredValue = preferenceLayers.map((layer) => layer[preferenceKey]).find((layerValue) => layerValue != null);
+  return typeof configuredValue === "string" ? configuredValue : void 0;
+}
+function resolvePreferenceValue(preferenceKey, homeDir = homedir(), pluginRoot = resolvePluginRoot()) {
+  return pickPreferenceValue(readPreferenceLayers(homeDir, pluginRoot), preferenceKey);
+}
+function resolveUserPreferenceValue(preferenceKey, homeDir = homedir()) {
+  return pickPreferenceValue([readUserPreferences(homeDir)], preferenceKey);
+}
 function resolveWatchPreferences(homeDir = homedir(), pluginRoot = resolvePluginRoot()) {
-  const shippedDefaults = readJsonRecord(join(pluginRoot, ...PREFERENCE_DEFAULTS_PATH_SEGMENTS));
-  const userPreferences = asRecord(readJsonRecord(join(homeDir, ...USER_PREFERENCES_PATH_SEGMENTS)).preferences);
-  const autoRebase = userPreferences[AUTO_REBASE_PREFERENCE_KEY] ?? shippedDefaults[AUTO_REBASE_PREFERENCE_KEY];
+  const preferenceLayers = readPreferenceLayers(homeDir, pluginRoot);
+  const [userPreferences, shippedDefaults] = preferenceLayers;
+  const autoRebase = pickPreferenceValue(preferenceLayers, AUTO_REBASE_PREFERENCE_KEY);
   const userCap = parseMaxCatchUpRebases(userPreferences[MAX_CATCH_UP_REBASES_PREFERENCE_KEY]);
   const shippedCap = parseMaxCatchUpRebases(shippedDefaults[MAX_CATCH_UP_REBASES_PREFERENCE_KEY]);
   return {
-    autoRebase: typeof autoRebase === "string" ? autoRebase : void 0,
+    autoRebase,
     maxCatchUpRebases: userCap !== void 0 ? userCap : shippedCap ?? null
   };
 }
@@ -2059,19 +2122,16 @@ function settleWalkthroughCommentForNoAppLogicChange(prUrl, detail, run = defaul
   const body = renderNoAppLogicChangeComment(declared, readPrHeadSha(pr, run), lastFullRun);
   return designated ? patchPrComment(pr, designated.id, body, run) : postPrComment(pr, body, run);
 }
-function noteWalkthroughRerunStarted(prUrl, run = defaultGhRunner, startedAt = /* @__PURE__ */ new Date()) {
+function noteE2eRunStarted(prUrl, run = defaultGhRunner, startedAt = /* @__PURE__ */ new Date()) {
   const pr = parsePrUrl(prUrl);
   if (!pr) return false;
   const comments = listPrComments(pr, run);
   if (comments === null) return false;
   const designated = designatedComment(comments);
   if (!designated) return false;
-  if (classifyComment(designated.body) === "pending" /* Pending */) return false;
   if (hasRerunNotice(designated.body)) return false;
-  return patchPrComment(pr, designated.id, withRerunNotice(designated.body, startedAt), run);
-}
-function settleWalkthroughCommentAsUnreasoned(prUrl, run = defaultGhRunner) {
-  return settleWith(prUrl, renderUnreasonedSkipComment(), run);
+  const body = classifyComment(designated.body) === "pending" /* Pending */ ? renderRunningComment(startedAt) : withRerunNotice(designated.body, startedAt);
+  return patchPrComment(pr, designated.id, body, run);
 }
 
 // src/e2e-skip/parseSkipDeclaration.ts
@@ -2216,7 +2276,12 @@ var verifyNoAppLogicChange = (context, detail) => {
   if (appLogicPaths.length > 0) return refuted(`app-logic paths changed since ${sha}: ${namePaths(appLogicPaths)}`);
   return verified;
 };
-var verifyNotApplicable = (_context, detail) => {
+var verifyNotApplicable = (context, detail) => {
+  if (context.userAutoE2ETest === ALWAYS_PREFERENCE_VALUE) {
+    return refuted(
+      `autoE2ETest=always in ~/.muggle-ai/preferences.json, so a judgment that the change needs no run is not a skip the user allows \u2014 run the E2E, or cite a code Muggle can verify`
+    );
+  }
   const words = detail.trim().split(/\s+/).filter(Boolean).length;
   if (words >= MIN_NOT_APPLICABLE_REASON_WORDS) return verified;
   return refuted(
@@ -2261,12 +2326,14 @@ function explainRejection(judged) {
   return `The skip cited ${judged.claimedCode}, but that could not be verified: ${judged.failure}. E2E is still owed \u2014 cite a code that holds, or run it.`;
 }
 function judgeE2eSkip(input2, state, probes = defaultSkipProbes) {
+  const homeDir = homedir();
   return resolveSkipDeclaration(input2.tool_input?.command ?? "", {
     cwd: input2.cwd,
     prsHandled: state.prsHandled,
     transcriptPath: input2.transcript_path,
-    homeDir: homedir(),
-    probe: probes
+    homeDir,
+    probe: probes,
+    userAutoE2ETest: resolveUserPreferenceValue(AUTO_E2E_TEST_PREFERENCE_KEY, homeDir)
   });
 }
 
@@ -2688,6 +2755,7 @@ function prOpened() {
     prUrl: url,
     prChange
   });
+  renderE2eStopVerdict(stateAfterOpen);
   const declaredSkip = isPrCoveredBySkip(stateAfterOpen, url) ? stateAfterOpen.e2eSkipDeclaration : void 0;
   if (declaredSkip) {
     startBackgroundJob("settle-walkthrough-skipped" /* SettleWalkthroughSkipped */, [url, declaredSkip.code, declaredSkip.detail]);
@@ -2766,6 +2834,7 @@ function recordTests() {
     failedRunId: detectFailedRunId(input)
   };
   const next = commitStateMutation(sessionId, outcome);
+  if (outcome.run.unitTestPassed) renderE2eStopVerdict(next);
   startWalkthroughScanOnGateArming(stateBefore, next, walkthroughPosted);
   if (acceptedSkip) recordSkipReasonOnPrs(next, acceptedSkip);
   if (judgedSkip && !judgedSkip.accepted) {
@@ -2869,19 +2938,30 @@ function debugPathGate() {
   const reason = decision.blockCount === 1 ? `Do not end the turn yet. These runs failed and never went through the debug path: ${runList}. muggle-test Step 7C makes that mandatory \u2014 route each through _shared/debug-failed-run.md: gather the attempted steps and the failing screenshot, diagnose the bucket per _shared/failure-mode-handling.md \xA7B/\xA7C with its classified telemetry emit, and present the offer in which "give feedback & rerun" is always available. A summarized-and-dropped failure is the run a reviewer most needs to see. If a run genuinely cannot be debugged, run \`echo "MUGGLE_DEBUG_SKIP: <runId> <reason>"\` \u2014 that clears just that run.` : `Failed runs still owe the debug path (reminder ${decision.blockCount}/${MAX_DEBUG_BLOCKS}): ${runList}. Route each through _shared/debug-failed-run.md, or record a legitimate skip via \`echo "MUGGLE_DEBUG_SKIP: <runId> <reason>"\`.`;
   return blockStop(reason, host);
 }
+function e2eOwedReason(blockCount) {
+  return buildE2eOwedReason({
+    blockCount,
+    maxBlocks: MAX_E2E_BLOCKS,
+    autoE2ETest: resolvePreferenceValue(AUTO_E2E_TEST_PREFERENCE_KEY),
+    postPRVisualWalkthrough: resolvePreferenceValue(POST_PR_VISUAL_WALKTHROUGH_PREFERENCE_KEY),
+    isE2eMandatedByUser: resolveUserPreferenceValue(AUTO_E2E_TEST_PREFERENCE_KEY) === ALWAYS_PREFERENCE_VALUE,
+    muggleTestSkill: muggleSkill("/muggle:muggle-test"),
+    walkthroughSkill: muggleSkill("/muggle:muggle-pr-visual-walkthrough")
+  });
+}
+function renderE2eStopVerdict(state) {
+  if (!shouldRunE2E(state)) return;
+  writeE2eStopVerdict(sessionId, MAX_E2E_BLOCKS, blockStop(e2eOwedReason(1), host));
+}
 function e2eGate() {
   const state = readState(sessionId);
-  const decision = e2eGateDecision(state);
-  if (decision.action === "release" /* Release */) {
-    for (const prUrl of state.prsHandled) {
-      startBackgroundJob("settle-walkthrough-unreasoned" /* SettleWalkthroughUnreasoned */, [prUrl]);
-    }
-    return releaseGate("e2eReleased");
-  }
+  const shellBlockCount = readE2eShellBlockCount(sessionId);
+  const decision = e2eGateDecision({ ...state, e2eBlockCount: (state.e2eBlockCount ?? 0) + shellBlockCount });
+  if (decision.action === "release" /* Release */) return releaseGate("e2eReleased");
   if (decision.action === "none" /* None */) return "{}";
-  recordGateBlock("e2eBlockCount", decision.blockCount);
-  const reason = decision.blockCount === 1 ? `Do not end the turn yet. This session went unit-green or opened a PR, but no E2E acceptance run has happened. Per the autoE2ETest preference (default: always), run change-driven E2E now via ${muggleSkill("/muggle:muggle-test")}, then finish. To skip, run \`echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"\` citing one of ${E2E_SKIP_CODES.join(", ")}. Muggle verifies each code itself, so one that does not hold leaves this gate blocked. Only when no verifiable code fits and a browser run genuinely cannot exercise the change, cite ${"NOT_APPLICABLE" /* NotApplicable */} with the reason \u2014 the PR shows it as your unverified judgment.` : `E2E acceptance run still owed (reminder ${decision.blockCount}/${MAX_E2E_BLOCKS}): run ${muggleSkill("/muggle:muggle-test")}, or cite a verifiable code via \`echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"\`.`;
-  return blockStop(reason, host);
+  recordGateBlock("e2eBlockCount", decision.blockCount - shellBlockCount);
+  renderE2eStopVerdict(state);
+  return blockStop(e2eOwedReason(decision.blockCount), host);
 }
 function watchGate() {
   const state = readState(sessionId);
@@ -2933,7 +3013,7 @@ function watchFollowThroughGate() {
   const holdInstruction = `Only the user can hold it: their own message containing \`${WATCH_HOLD_PHRASE_PREFIX}<pr-number>\` for that PR. Ask if you must; never decide it for them.`;
   const reason = decision.blockCount === 1 ? `Do not end the turn yet. A muggle-pr-followup watch this session owns found work due that nothing acted on:
 ${owedList}
-autoRebase=always makes a due rebase binding, and how long a CI run or an eval takes is never a reason to wait. Act now \u2014 if the tick finds actionable review feedback it dispatches that first. A recorded attempt (conflict_resolve_attempts / ci_fix_attempts) or a new head clears this; an escalation entry with no attempt behind it does not, and neither does re-arming the watch. ${holdInstruction}` : `Watcher work still owed (reminder ${decision.blockCount}):
+autoRebase=always makes a due rebase binding, and how long a CI run or an eval takes is never a reason to wait. Act now: run the cycle the tick dispatches \u2014 if it finds actionable review feedback it dispatches that first. That cycle's first step records its attempt (conflict_resolve_attempts / ci_fix_attempts), which, like a new head, clears this. Writing the count without running the cycle \u2014 or for an E2E run queued for a different PR \u2014 leaves the PR red and the watch quiet. An escalation entry with no attempt behind it does not clear this, and neither does re-arming the watch. ${holdInstruction}` : `Watcher work still owed (reminder ${decision.blockCount}):
 ${owedList}
 ${holdInstruction}`;
   return blockStop(reason, host);
@@ -3162,11 +3242,6 @@ function settleBranchWalkthroughSkippedJob() {
   if (prUrl) settleWalkthroughCommentAsSkipped(prUrl, code, detail ?? "");
   return "{}";
 }
-function settleWalkthroughUnreasonedJob() {
-  const [prUrl] = jobArgs;
-  if (prUrl) settleWalkthroughCommentAsUnreasoned(prUrl);
-  return "{}";
-}
 function settleWalkthroughNoAppLogicChangeJob() {
   const [detail] = jobArgs;
   const prUrl = defaultPrWalkthroughLookup.branchPrUrl();
@@ -3175,7 +3250,7 @@ function settleWalkthroughNoAppLogicChangeJob() {
 }
 function noteWalkthroughRerunJob() {
   const prUrl = defaultPrWalkthroughLookup.branchPrUrl();
-  if (prUrl) noteWalkthroughRerunStarted(prUrl);
+  if (prUrl) noteE2eRunStarted(prUrl);
   return "{}";
 }
 function scanWatchPrStatesJob() {
@@ -3197,7 +3272,6 @@ var backgroundJobs = {
   ["reserve-walkthrough-comment" /* ReserveWalkthroughComment */]: reserveWalkthroughCommentJob,
   ["settle-walkthrough-skipped" /* SettleWalkthroughSkipped */]: settleWalkthroughSkippedJob,
   ["settle-branch-walkthrough-skipped" /* SettleBranchWalkthroughSkipped */]: settleBranchWalkthroughSkippedJob,
-  ["settle-walkthrough-unreasoned" /* SettleWalkthroughUnreasoned */]: settleWalkthroughUnreasonedJob,
   ["settle-walkthrough-no-app-logic-change" /* SettleWalkthroughNoAppLogicChange */]: settleWalkthroughNoAppLogicChangeJob,
   ["note-walkthrough-rerun" /* NoteWalkthroughRerun */]: noteWalkthroughRerunJob,
   ["scan-watch-pr-states" /* ScanWatchPrStates */]: scanWatchPrStatesJob,