@muggleai/works 5.17.0 → 5.18.0-staging.118

package/dist/plugin/scripts/guardrails.mjs

@@ -12,6 +12,7 @@ var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
 var GH_PR_REOPENED_LINE = /\bReopened pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
+var SHELL_TOOL_NAMES = ["Bash", "PowerShell"];
 var MAX_WATCH_BLOCKS = 3;
 var MAX_BUILD_BLOCKS = 3;
 var MAX_WALKTHROUGH_BLOCKS = 3;
@@ -153,13 +154,18 @@ function markPrHandled(sessionId2, prUrl, dirOverride) {
   writeState(state, dirOverride);
 }
 
+// src/guardrails/shellTool.ts
+function isShellToolCall(input2) {
+  return SHELL_TOOL_NAMES.includes(input2.tool_name ?? "");
+}
+
 // 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;
+  if (!isShellToolCall(input2)) return null;
   const cmd = input2.tool_input?.command ?? "";
   if (!CREATE_CMD.test(cmd) && !MR_CREATE_CMD.test(cmd)) return null;
   const out = `${input2.tool_response?.stdout ?? ""}
@@ -178,7 +184,7 @@ function terminalProvenance(input2) {
   };
 }
 function detectPrTerminal(input2) {
-  if (input2.tool_name !== "Bash" && input2.tool_name !== "Monitor") return null;
+  if (!isShellToolCall(input2) && input2.tool_name !== "Monitor") return null;
   const response = input2.tool_response;
   const provenance = terminalProvenance(input2);
   const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
@@ -200,7 +206,7 @@ function detectPrTerminal(input2) {
   return null;
 }
 function detectPrReopened(input2) {
-  if (input2.tool_name !== "Bash") return null;
+  if (!isShellToolCall(input2)) return null;
   if (!terminalProvenance(input2).acceptsForgeLine) return null;
   const response = input2.tool_response;
   const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
@@ -521,7 +527,8 @@ function isE2ERun(input2) {
 // src/guardrails/shouldRunE2E.ts
 var MAX_E2E_BLOCKS = 3;
 function shouldRunE2E(state) {
-  return state.unitTestsGreen === true && state.e2eRun !== true && state.e2eSkipped !== true;
+  const owed = state.unitTestsGreen === true || state.prsHandled.length > 0;
+  return owed && state.e2eRun !== true && state.e2eSkipped !== true;
 }
 function applyRecordedRun(state, run) {
   let next = state;
@@ -603,7 +610,15 @@ function buildFollowthroughDecision(state, maxBlocks = MAX_BUILD_BLOCKS) {
   }
   return { action: "block" /* Block */, blockCount: blockCount + 1 };
 }
+
+// src/pr-walkthrough/constants.ts
 var REPORT_SENTINEL = "muggle-pr-section";
+var WALKTHROUGH_SLOT_MARKER = "<!-- muggle-pr-walkthrough:v1 -->";
+var WALKTHROUGH_SKIPPED_MARKER = "<!-- muggle-pr-walkthrough-status:skipped -->";
+var WALKTHROUGH_COMMENT_HEADING = "### Muggle AI \u2014 PR visual walkthrough";
+var GH_COMMENT_TIMEOUT_MS = 1e4;
+
+// src/guardrails/prReportPost.ts
 var PR_PROSE_CMD = /\bgh\s+pr\s+(comment|create|edit)\b/;
 var GH_API_CMD = /\bgh\s+api\b/;
 var ISSUE_COMMENT_PATH = /\bissues\/comments\/\d+/;
@@ -652,7 +667,7 @@ function isWalkthroughSkipMarker(cmd) {
   return WALKTHROUGH_SKIP_MARKER.test(cmd);
 }
 function detectWalkthroughPost(input2, read = defaultFileReader) {
-  if (input2.tool_name !== "Bash") return false;
+  if (!isShellToolCall(input2)) return false;
   const cmd = input2.tool_input?.command ?? "";
   if (!isPrReportPostCommand(cmd)) return false;
   if (callFailed(input2)) return false;
@@ -715,6 +730,125 @@ function walkthroughGateDecision(state, owedPrUrls, maxBlocks = MAX_WALKTHROUGH_
   return { action: "block" /* Block */, blockCount: blockCount + 1, owed: owedPrUrls };
 }
 
+// src/pr-walkthrough/comment.ts
+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._`;
+}
+function renderSkippedComment(reason) {
+  const stated = reason.trim();
+  if (!stated) return renderReservedComment();
+  return `${WALKTHROUGH_SLOT_MARKER}
+${WALKTHROUGH_SKIPPED_MARKER}
+${WALKTHROUGH_COMMENT_HEADING}
+
+**E2E skipped** \u2014 ${stated}`;
+}
+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 */;
+  return "pending" /* Pending */;
+}
+var GITHUB_PR_URL = /^https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/(\d+)/;
+var GH_CALLS_ENV = "MUGGLE_GUARDRAIL_GH_CALLS";
+var defaultGhRunner = (args, input2) => {
+  if (process.env[GH_CALLS_ENV] === "off") return null;
+  try {
+    return execFileSync("gh", args, {
+      encoding: "utf-8",
+      input: input2,
+      timeout: GH_COMMENT_TIMEOUT_MS,
+      stdio: ["pipe", "pipe", "ignore"]
+    });
+  } catch {
+    return null;
+  }
+};
+function parsePrUrl(prUrl) {
+  const parts = prUrl.match(GITHUB_PR_URL);
+  if (!parts) return null;
+  return { repo: `${parts[1]}/${parts[2]}`, prNumber: Number(parts[3]) };
+}
+function listPrComments(pr, run) {
+  let raw;
+  try {
+    raw = run(["api", "--paginate", `repos/${pr.repo}/issues/${pr.prNumber}/comments`]);
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function writeJson(args, payload, run) {
+  try {
+    return run(args, JSON.stringify(payload)) !== null;
+  } catch {
+    return false;
+  }
+}
+function postPrComment(pr, body, run) {
+  return writeJson(
+    ["api", "--method", "POST", `repos/${pr.repo}/issues/${pr.prNumber}/comments`, "--input", "-"],
+    { body },
+    run
+  );
+}
+function patchPrComment(pr, commentId, body, run) {
+  return writeJson(
+    ["api", "--method", "PATCH", `repos/${pr.repo}/issues/comments/${commentId}`, "--input", "-"],
+    { body },
+    run
+  );
+}
+
+// src/pr-walkthrough/reserve.ts
+function commentWithStatus(comments, status) {
+  return comments.find((comment) => classifyComment(comment.body) === status);
+}
+function reserveComment(pr, comments, run) {
+  const claimed = comments.some(
+    (comment) => classifyComment(comment.body) !== "not-designated" /* NotDesignated */
+  );
+  if (claimed) return false;
+  return postPrComment(pr, renderReservedComment(), run);
+}
+function reserveWalkthroughComment(prUrl, run = defaultGhRunner) {
+  const pr = parsePrUrl(prUrl);
+  if (!pr) return false;
+  const comments = listPrComments(pr, run);
+  if (comments === null) return false;
+  return reserveComment(pr, comments, run);
+}
+function settleWalkthroughCommentAsSkipped(prUrl, reason, run = defaultGhRunner) {
+  if (!reason.trim()) return false;
+  const pr = parsePrUrl(prUrl);
+  if (!pr) return false;
+  const comments = listPrComments(pr, run);
+  if (comments === null) return false;
+  if (commentWithStatus(comments, "reported" /* Reported */)) return false;
+  if (commentWithStatus(comments, "skipped" /* Skipped */)) return false;
+  const body = renderSkippedComment(reason);
+  const reserved = commentWithStatus(comments, "pending" /* Pending */);
+  return reserved ? patchPrComment(pr, reserved.id, body, run) : postPrComment(pr, body, run);
+}
+
+// src/guardrails/skipReason.ts
+var SKIP_DECLARATION = /^\s*echo\s+["']?MUGGLE_(?:E2E|WALKTHROUGH)_SKIP:\s*(.+)$/;
+function skipReasonFrom(cmd) {
+  const declared = cmd.match(SKIP_DECLARATION);
+  if (!declared) return null;
+  const reason = declared[1].replace(/["']\s*$/, "").trim();
+  return reason || null;
+}
+
 // src/guardrails/ledger/constants.ts
 var LEDGER_FILE_NAME = "comment-ledger.json";
 var LEDGER_VERSION = 1;
@@ -874,14 +1008,14 @@ function gitlabThread(thread) {
   };
 }
 function detectUnansweredThreads(input2) {
-  if (input2.tool_name !== "Bash") return [];
+  if (!isShellToolCall(input2)) return [];
   if (!REVIEW_THREAD_FETCH_COMMAND.test(input2.tool_input?.command ?? "")) return [];
   const threads = [];
   collectThreads(parsedResponse(input2), threads);
   return threads.map((thread) => Array.isArray(thread.notes) ? gitlabThread(thread) : githubThread(thread)).filter((thread) => thread !== void 0);
 }
 function detectConfirmedReplies(input2) {
-  if (input2.tool_name !== "Bash") return [];
+  if (!isShellToolCall(input2)) return [];
   const command = input2.tool_input?.command ?? "";
   const targets = [...command.matchAll(THREADED_REPLY_TARGET)].map(
     ([, githubCommentId, gitlabDiscussionId]) => githubCommentId ?? gitlabDiscussionId
@@ -976,7 +1110,7 @@ function looksLikeE2EReport(text) {
   return resultsStructure && muggleContext;
 }
 function evaluateReportPost(input2, read = defaultFileReader) {
-  if (input2.tool_name !== "Bash") return { deny: false };
+  if (!isShellToolCall(input2)) return { deny: false };
   const cmd = input2.tool_input?.command ?? "";
   if (!isPrReportPostCommand(cmd)) return { deny: false };
   const text = collectPrPostText(cmd, input2.cwd, read);
@@ -997,7 +1131,7 @@ function detectResolveCall(command) {
 }
 var RESOLVE_DENIAL = "Blocked: resolving a review thread is the reviewer's call, not the loop's. Reply to the thread instead \u2014 the `<!-- muggle-do:bot -->` marker on that reply is what retires it (a thread is actionable only while it is unresolved AND its newest comment is unmarked), so resolving buys no echo protection and costs the reviewer their record of what is still unverified. The loop has twice hidden threads carrying fixes that were partly wrong. If a thread genuinely warrants resolving, say so and let the reviewer close it in the UI; to nudge, run the resolve-reminder stage, which lists addressed-but-open threads without touching them.";
 function evaluateReviewThreadResolve(input2) {
-  if (input2.tool_name !== "Bash") return { deny: false };
+  if (!isShellToolCall(input2)) return { deny: false };
   const provider = detectResolveCall(input2.tool_input?.command ?? "");
   if (!provider) return { deny: false };
   return { deny: true, reason: RESOLVE_DENIAL };
@@ -1052,7 +1186,9 @@ function prOpened() {
   if (!url) return "{}";
   if (readState(sessionId).prsHandled.includes(url)) return "{}";
   markPrHandled(sessionId, url);
+  reserveWalkthroughComment(url);
   const ctx = `A pull request was just opened: ${url}
+Its Muggle AI visual-walkthrough comment is reserved and empty \u2014 settle it by posting the walkthrough there once E2E runs, or by recording why E2E does not apply.
 Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its incoming reviews. If autoWatchPR=always, start it now by invoking /muggle:muggle-pr-followup with the PR URL; if =ask, offer it to the user; if =never, do nothing.`;
   return envelope("PostToolUse", ctx, host);
 }
@@ -1106,8 +1242,16 @@ function recordTests() {
   const failedRunId = detectFailedRunId(input);
   const next = failedRunId ? applyFailedRun(withWalkthroughSkip, failedRunId) : withWalkthroughSkip;
   if (next !== state) writeState(next);
+  recordSkipReasonOnPrs(next, cmd);
   return "{}";
 }
+function recordSkipReasonOnPrs(state, cmd) {
+  const reason = skipReasonFrom(cmd);
+  if (!reason) return;
+  for (const prUrl of state.prsHandled) {
+    settleWalkthroughCommentAsSkipped(prUrl, reason);
+  }
+}
 function skillStages() {
   const skillName = resolveSkillNameFromToolInput(input.tool_input);
   if (!skillName) return "{}";
@@ -1185,7 +1329,7 @@ function e2eGate() {
   if (decision.action === "none" /* None */) return "{}";
   state.e2eBlockCount = decision.blockCount;
   writeState(state);
-  const reason = decision.blockCount === 1 ? `Do not end the turn yet. Unit tests passed this session but no E2E acceptance run has happened. Per the autoE2ETest preference (default: always), run change-driven E2E now via /muggle:muggle-test, then finish. If E2E genuinely cannot run here (no app to drive, services down, no PR), tell the user why and run \`echo "MUGGLE_E2E_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `E2E acceptance run still owed (reminder ${decision.blockCount}/${MAX_E2E_BLOCKS}): run /muggle:muggle-test, or record a legitimate skip via \`echo "MUGGLE_E2E_SKIP: <reason>"\`.`;
+  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 /muggle:muggle-test, then finish. If E2E genuinely cannot run here (no app to drive, services down, no PR), tell the user why and run \`echo "MUGGLE_E2E_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `E2E acceptance run still owed (reminder ${decision.blockCount}/${MAX_E2E_BLOCKS}): run /muggle:muggle-test, or record a legitimate skip via \`echo "MUGGLE_E2E_SKIP: <reason>"\`.`;
   return blockStop(reason, host);
 }
 function watchGate() {

package/dist/plugin/skills/do/open-prs/forward.md

@@ -32,14 +32,18 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
    - `## Acceptance Criteria` — bulleted; omit if empty.
    - `## Changes` — summary of what changed in this repo.
    - `## Validation` — one line: link to E2E report, `unit-only`, or `skip — <reason>`.
-   - **Walkthrough block** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md); on skip, omit this block. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode B and embed the returned `body` verbatim. No report → skip the block.
+   - The walkthrough does **not** go in the body. It settles the PR's designated walkthrough comment in Step 6, so a rerun updates one comment instead of rewriting the description.
    - **Signature** — write the assembled body to a file and sign it with `--command /muggle-do --mode editable` per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). The signature lands last, after the walkthrough block; `editable` is the mode a description carries so later refreshes replace it instead of stacking.
 
 5. **Create:** resolve the provider per [`../../_shared/vcs/detect-vcs.md`](../../_shared/vcs/detect-vcs.md).
    - `github` → `gh pr create --title "..." --body-file <signed-file> --head <branch>`, passing the file signed in Step 4. Capture the PR URL and number.
    - `gitlab` → open the change via [`../../_shared/vcs/gitlab/mr-create.md`](../../_shared/vcs/gitlab/mr-create.md): `glab mr create --source-branch <branch> --target-branch <base> --title "..." --description "..."`. Capture the MR URL and iid.
 
-6. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 5 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). Never post when `comment` is `null`.
+6. **Settle the designated walkthrough comment.** Creating the PR reserves one comment for the walkthrough, marked `muggle-pr-walkthrough` and empty until settled — the PR's walkthrough check fails while it stays that way.
+   - E2E report exists → fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md); on skip, leave the comment to the gate's own skip record. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the PR number — it fills the reserved comment in place.
+   - No E2E report (validation was `unit-only` or `skip`) → state the reason on the PR with `echo "MUGGLE_E2E_SKIP: <reason>"`, which settles the comment as a declared skip. A PR whose title says `[UNIT-ONLY]` still owes reviewers the why.
+
+7. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once using the provider resolved in Step 5 — `github` per [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md), `gitlab` per [`../../_shared/vcs/gitlab/mr-note.md`](../../_shared/vcs/gitlab/mr-note.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md). Never post when `comment` is `null`.
 
 ## Stage 7.5 gate
 
@@ -68,7 +72,7 @@ If `prs.json` is empty, **do not dispatch** — record the reason in `result.md`
 
 ## Invariants
 
-- Branch synced with its base before the push, never after; PR creation per non-skipped repo; walkthrough block via Mode B; `prs.json`+`last_seen.json` seeded (no `cycle.json`, no `requirements.md`); Stage 7.5 cleared before the dispatch; `/loop` dispatch is the last action.
+- Branch synced with its base before the push, never after; PR creation per non-skipped repo; designated walkthrough comment settled via Mode A, or its skip reason stated; `prs.json`+`last_seen.json` seeded (no `cycle.json`, no `requirements.md`); Stage 7.5 cleared before the dispatch; `/loop` dispatch is the last action.
 
 ## Output
 

package/dist/plugin/skills/do/open-prs/update.md

@@ -40,7 +40,7 @@ Resolve the provider once per [`../../_shared/vcs/detect-vcs.md`](../../_shared/
 
 4. **Refresh body when validation outcome changed** — only when the `## Validation` section's content differs from what's in the body. Use the `--body-file` form in [`../../_shared/vcs/github/pr-edit.md`](../../_shared/vcs/github/pr-edit.md). Preserve `## Goal` and `## Acceptance Criteria` verbatim. Re-stamp the signature: delete the existing block from the `<!-- muggle-works:signature -->` marker to the end, then append the editable-body signature (command `/muggle-do`) as the last thing in the body per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md) — this keeps exactly one signature across refreshes.
 
-5. **Visual walkthrough comment** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md) (PR number from `prs.json`); on skip, record `skipped (gate)` and continue. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A — a fresh comment per cycle; do not edit prior walkthrough comments.
+5. **Visual walkthrough comment** — only when an E2E report exists. Fire [`postPRVisualWalkthrough`](../../muggle-preferences/preference-gates/postPRVisualWalkthrough.md) (PR number from `prs.json`); on skip, record `skipped (gate)` and continue. Otherwise invoke [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md) Mode A, which settles the PR's designated walkthrough comment in place — one walkthrough per PR, always reflecting the latest run.
 
 6. **Overflow comment** — same rule as forward mode: post when the walkthrough skill returns non-null `comment`, via [`../../_shared/vcs/github/top-level-comment.md`](../../_shared/vcs/github/top-level-comment.md). End the posted body with the signature line (command `/muggle-do`) per [`../../_shared/vcs/post-signature.md`](../../_shared/vcs/post-signature.md).
 

package/dist/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -18,7 +18,7 @@ This is the **canonical PR-walkthrough workflow** shared across every Muggle Tes
 | :--- | :--- | :--- |
 | `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
 | `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
-| `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in the PR create call and posts `comment` as follow-up |
+| `muggle-do` / `open-prs.md` | **Mode A** (settle the designated comment) | Right after PR creation — the walkthrough fills the comment the PR reserved for it, and `comment` posts as follow-up |
 | `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside an open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment |
 
 ## Preferences
@@ -27,7 +27,7 @@ Callers consult the `postPRVisualWalkthrough` gate **before** invoking this skil
 
 ## Procedure
 
-1. **Resolve the mode.** Chosen by the caller, never the user: top-level `muggle-test`/`muggle-test-feature-local` → `post` (Mode A); `muggle-do` PR creation → `render-for-new-pr` (Mode B); an orchestrator passing `mode: "embed"` → Mode C.
+1. **Resolve the mode.** Chosen by the caller, never the user: top-level `muggle-test`/`muggle-test-feature-local` and `muggle-do` PR creation → `post` (Mode A); a caller that needs the block rendered without posting → `render-for-new-pr` (Mode B); an orchestrator passing `mode: "embed"` → Mode C.
 2. **Mode A only — find the PR** with `gh pr view --json number,url,title`. No PR on the branch → `AskUserQuestion`: create a new PR with the walkthrough in the body (switch to Mode B and hand the rendered block back to the caller), or skip posting. `gh` missing/unauthenticated → tell the user, suggest `gh auth login`, stop. This is the skill's only interactive branch — resolve it **before** dispatching.
 3. **Gather the inputs.** The `E2eReport` JSON if the caller already assembled it (see [`e2e-report-assembly.md`](e2e-report-assembly.md)), else the run identifiers (`projectId`, per-test `runId`/`testCaseId`) the agent needs to assemble it.
 4. **Dispatch** the `visual-walkthrough-builder` agent (subagent type `muggle:visual-walkthrough-builder`; bare `visual-walkthrough-builder` where the plugin namespace is absent), synchronously, passing: mode, PR number + repo (Mode A), and the report JSON or identifiers. In a harness with no agent/subagent facility, execute `plugin/agents/visual-walkthrough-builder.md` inline instead.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.13.1",
-  "buildId": "run-116-1",
-  "commitSha": "4739cd18232aea59096ce70e569d1abf4674dc5c",
-  "buildTime": "2026-09-16T19:07:37Z",
+  "buildId": "run-118-1",
+  "commitSha": "f5fd018bf455519cab67f84dc8840339e1c4a061",
+  "buildTime": "2026-09-18T06:00:32Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.17.0",
+  "version": "5.18.0-staging.118",
   "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",
@@ -52,21 +52,21 @@
     "typecheck:browser-bench": "tsc --noEmit -p internal/browser-bench/tsconfig.json"
   },
   "muggleConfig": {
-    "electronAppVersion": "1.10.3",
+    "electronAppVersion": "1.10.6",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
-    "runtimeTargetDefault": "production",
+    "runtimeTargetDefault": "staging",
     "checksumsByStream": {
       "production": {
-        "win32-x64": "58e2238b1609ceff65b836b4b724b1c4c341d737a15debaa8a71af21b70bc436",
-        "linux-x64": "731c2ab093ef77202191d0fec8e98f19ef895019d3e7817bacef197c7197a358",
-        "darwin-arm64": "a3f8229678d4c6cd7514726b480fa97dc9dffed7ac45c2ff76e6abf220e1709f",
-        "darwin-x64": "b193c2fc02174636bee3fbb3b1041b301639315f2af55fb0352f09e7454a5694"
+        "win32-x64": "c20acdc2fd7a05039c62f9e5b079e3068d1b3a23a1b3b37b75e2a650b5401de6",
+        "linux-x64": "5167eaed4b82fdf57b09c0525437f9c1e0942bc05418a4f993d3b7fc9c807d1f",
+        "darwin-arm64": "f3f41d4fcd8dc9669d79215d349e9ec1e3dff82d34dce75b028ab30715530835",
+        "darwin-x64": "eeb41783e9c1e6ca8afebd480623ccc194c9aba4349dd52992f0e514fa19f168"
       },
       "staging": {
-        "darwin-arm64": "0769b8b146b393fbf582b995a1bf7d2e1b9a8ee8fbc08a2108ad9be283291d37",
-        "linux-x64": "5bdf0e98f3eb95c6cd9461cbddefa19e5361354f3faefaba7bead9ea4feabca7",
-        "win32-x64": "d029700622445ab2dab931b2cd206922cf20cf16137ccc7f164ef5c195b45ac5",
-        "darwin-x64": "db29f8fbddd4e1f1f3098aca33e3ecf6ea1a0647de6d17a0ac809a09524e7464"
+        "darwin-arm64": "58fab257672df1fe34c9bd787a4892c6bf4a62dc930794bd5b51b2491080967d",
+        "linux-x64": "e2daf1ac47d33fb7a3c02b59abf0a29eaa9e346966fc21cd5ffa3dbd62494244",
+        "win32-x64": "978328942eea108396917e9a0796141b588983118c45034c97f3db6431637ddc",
+        "darwin-x64": "8892a29a91b318811012c1d74bb3f5668ed4481ce1e739e7283cb783e0b54e54"
       }
     },
     "electronAppSignedFromVersion": "1.10.0",

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

@@ -33,18 +33,18 @@ echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
 
 **Mode A (`post`)** — deliver `body`, then `comment` only if non-null. Sign each posted body per [`../skills/_shared/vcs/post-signature.md`](../skills/_shared/vcs/post-signature.md) with `--mode plain` — this post is the walkthrough's own, so the command it names is `/muggle-pr-visual-walkthrough`.
 
-**Update in place when this PR already carries a walkthrough.** A rerun after a failure must leave the PR with **one** walkthrough reflecting latest state, not a comment per attempt. Resolve which comment to update by reading the PR — never by remembering an id — so the behavior is idempotent across sessions and survives a lost session or a forgotten handle:
+**Settle the designated comment.** Every PR carries one comment reserved for this walkthrough — posted the moment the PR opened, marked `muggle-pr-walkthrough`, and empty until a run settles it. Fill that comment rather than adding another: a rerun after a failure must leave the PR with **one** walkthrough reflecting latest state, and a fresh post would strand the reserved slot pending, which is what the PR's walkthrough check fails on. Resolve which comment to fill by reading the PR — never by remembering an id — so the behavior is idempotent across sessions and survives a lost session or a forgotten handle:
 
 ```bash
 sign() { bash "${CLAUDE_PLUGIN_ROOT}/scripts/sign-body.sh" --command /muggle-pr-visual-walkthrough --mode plain; }
 existing=$(gh api "repos/<owner>/<repo>/issues/<prNumber>/comments" \
-  --jq '[.[] | select(.body | contains("muggle-pr-section")) | .id] | join(" ")')
+  --jq '[.[] | select(.body | contains("muggle-pr-section") or contains("muggle-pr-walkthrough")) | .id] | join(" ")')
 ```
 
 - `existing` empty → post fresh: `jq -r '.body' … | sign | gh pr comment <prNumber> --body-file -`, then the same for `.comment` when non-null.
 - `existing` non-empty → update the first id with `body` via `gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@-`, feeding the same signed text on stdin. Handle `comment` against the second id when both exist; post it fresh when the overflow is new, and delete a now-surplus overflow comment (`gh api --method DELETE …`) so a stale tail never outlives the run it described.
 
-Match only comments carrying the sentinel — never every comment the loop user wrote — so an unrelated reply is never overwritten.
+Match only comments carrying one of those markers — never every comment the loop user wrote — so an unrelated reply is never overwritten.
 
 Report back: PR URL, whether an overflow comment was involved, and whether this was a fresh post or an update.
 

package/plugin/hooks/hooks.json

@@ -27,7 +27,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",
@@ -57,13 +57,13 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-pr-opened.sh\"",
             "async": false,
-            "timeout": 10
+            "timeout": 25
           },
           {
             "type": "command",

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

@@ -1,17 +1,19 @@
 #!/usr/bin/env bash
 set -uo pipefail
 
-# tests-green → E2E gate (Stop). When unit tests passed this session and no E2E
-# acceptance run has happened, offer to run change-driven E2E (gated by
-# autoE2ETest). Fires once per session.
+# tests-green-or-PR-opened → E2E gate (Stop). When unit tests passed this
+# session or a PR was opened, and no E2E acceptance run has happened, offer to
+# run change-driven E2E (gated by autoE2ETest). Fires once per session.
 #
 # This must stay synchronous (only a sync Stop hook can block the turn end), and
 # it fires on EVERY turn end. There is no command payload to key off, so the
 # pre-filter reads the same per-session state file guardrails.mjs uses and only
-# spawns Node when the gate could actually fire — i.e. shouldRunE2E: unit tests
-# went green and no E2E run is recorded yet. On the overwhelming majority of
-# turns (no test run this session) the state file is absent or unitTestsGreen is
-# unset, so we return {} in-shell and never pay Node cold-start. Degrades to {}.
+# spawns Node when the gate could actually fire — i.e. shouldRunE2E's two
+# triggers, with no E2E run recorded yet. It must track that predicate exactly:
+# a pre-filter narrower than the gate retires the gate silently. On the
+# overwhelming majority of turns (no test run, no PR) the state file is absent,
+# or unitTestsGreen is unset while prsHandled is empty, so we return {} in-shell
+# and never pay Node cold-start. Degrades to {}.
 payload="$(cat)"
 
 raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
@@ -28,7 +30,7 @@ fi
 
 state_file="$home/.muggle-ai/guardrails/$sid.json"
 if [ ! -f "$state_file" ] \
-  || ! grep -q '"unitTestsGreen": true' "$state_file" \
+  || { ! grep -q '"unitTestsGreen": true' "$state_file" && grep -q '"prsHandled": \[\]' "$state_file"; } \
   || grep -q '"e2eReleased": true' "$state_file" \
   || grep -q '"e2eRun": true' "$state_file"; then
   printf '{}'