@muggleai/works 5.28.0 → 5.29.0-staging.256

package/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/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/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,

package/plugin/scripts/pr-watch-arm.sh

@@ -13,10 +13,12 @@
 # seen without ever being reported. A re-arm keeps the review, comment and thread
 # floors the session already holds, for the same reason.
 #
-# A stale branch or a red head is floored only when the slot proves a cycle ran
-# for it. Flooring whatever was outstanding at arm time let a session that never
-# rebased or fixed anything re-arm at every rollover and silence the loop each
-# time; the drain line said "handled" and nothing checked.
+# A stale branch is floored only when the slot proves a rebase ran for it, and a
+# red head only once fix-ci is finished with it — escalated, or out of attempts.
+# Flooring whatever was outstanding at arm time let a session that never rebased
+# or fixed anything re-arm at every rollover and silence the loop each time; the
+# drain line said "handled" and nothing checked. A bare attempt count is no
+# better proof for CI: writing it costs nothing and changes nothing on the PR.
 set -uo pipefail
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -77,6 +79,7 @@ latest_comment="${STATE_FIELDS[5]-}"
 unresolved_threads="${STATE_FIELDS[6]-}"
 pending_checks="${STATE_FIELDS[7]-}"
 failed_checks="${STATE_FIELDS[8]-}"
+ci_red_key="$(watch_ci_red_key "$head_sha" "${STATE_FIELDS[10]-}")"
 
 if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then
     echo "TERMINAL pr=$pr_number state=$pr_state — nothing to arm"
@@ -92,7 +95,8 @@ rebase_due_key=""
 behind_count="$(watch_fetch_behind_count "$repo" "$base_branch" "$head_sha" "$slot")"
 watch_branch_needs_rebase "$mergeable" "$behind_count" && rebase_due_key="$rebase_key"
 
-# Whether a cycle already ran for this key and this head, and the blocked
+# Whether a rebase already ran for this key, whether fix-ci is done with this
+# head, and the blocked
 # fingerprint's digest. A slot re-armed while blocked keeps its resume probe
 # live: empty is the not-blocked state, so seeding it empty would leave the loop
 # asleep through the very CI move the block is waiting on.
@@ -105,14 +109,14 @@ watch_branch_needs_rebase "$mergeable" "$behind_count" && rebase_due_key="$rebas
 last_seen_file="${slot}/last_seen.json"
 [ -f "$last_seen_file" ] || last_seen_file=/dev/null
 rebase_attempted=0
-ci_attempted=0
+ci_settled=0
 blocked_digest_floor=""
 rebase_budget_exhausted=0
 while IFS= read -r evidence_line; do
     evidence_line="${evidence_line%$'\r'}"
     case "$evidence_line" in
         REBASE_ATTEMPTED=*) rebase_attempted="${evidence_line#REBASE_ATTEMPTED=}" ;;
-        CI_ATTEMPTED=*) ci_attempted="${evidence_line#CI_ATTEMPTED=}" ;;
+        CI_SETTLED=*) ci_settled="${evidence_line#CI_SETTLED=}" ;;
         BLOCKED_CIDIGEST=*) blocked_digest_floor="${evidence_line#BLOCKED_CIDIGEST=}" ;;
         REBASE_BUDGET_EXHAUSTED=*) rebase_budget_exhausted="${evidence_line#REBASE_BUDGET_EXHAUSTED=}" ;;
     esac
@@ -120,7 +124,7 @@ done < <(node "${script_dir}/pr-watch-verdict.mjs" arm-floors --pr-key "${repo}#
     --head "$head_sha" --rebase-key "$rebase_key" < "$last_seen_file" 2>/dev/null)
 
 ci_red_floor=""
-[ -n "$ci_red_head" ] && [ "$ci_attempted" = "1" ] && ci_red_floor="$ci_red_head"
+[ -n "$ci_red_head" ] && [ "$ci_settled" = "1" ] && ci_red_floor="$ci_red_key"
 rebase_floor=""
 [ -n "$rebase_due_key" ] && [ "$rebase_attempted" = "1" ] && rebase_floor="$rebase_due_key"
 
@@ -145,9 +149,9 @@ echo "DRAIN unresolved-threads=$thread_count latest-review=${latest_review:-0} l
 echo "DRAIN checks pending=${pending_checks:-0} failed=${failed_checks:-0} behind-base=${behind_count:-unknown} mergeable=${mergeable:-UNKNOWN}"
 if [ -n "$ci_red_head" ]; then
     if [ -n "$ci_red_floor" ]; then
-        echo "DRAIN ci red at arm time — a fix-ci cycle already ran for head ${head_sha:0:8}, floored"
+        echo "DRAIN ci red at arm time — fix-ci escalated or spent its attempts on head ${head_sha:0:8}, floored"
     else
-        echo "DRAIN ci red at arm time — no fix-ci attempt recorded for head ${head_sha:0:8}, not floored: dispatch fix-ci"
+        echo "DRAIN ci red at arm time — fix-ci not finished with head ${head_sha:0:8}, not floored: dispatch fix-ci"
     fi
 fi
 if [ -n "$rebase_due_key" ]; then

package/plugin/scripts/pr-watch-events.sh

@@ -80,15 +80,24 @@ watch_checks_settled_red() {
     [ "${failed_count:-0}" -gt 0 ] 2>/dev/null
 }
 
+# The identity of one red verdict: the head plus the run ids of its failed
+# checks (the state line's red-check-runs).
+watch_ci_red_key() {
+    printf '%s@%s' "$1" "$2"
+}
+
 # The head's checks having settled red (watch_checks_settled_red).
 #
-# The floor is the head SHA rather than a monotonic id because a check rollup is
-# not monotonic: it flips green to red and resets on every push. Keying on the
-# red head fires once per red head and re-arms on the next push.
+# The floor is a red key (watch_ci_red_key) rather than a monotonic id because a
+# check rollup is not monotonic: it flips green to red and resets on every push.
+# The head alone is not enough: a fix-ci cycle that settles the walkthrough or
+# reruns a check keeps the head, and when that new run comes back red too it is
+# news the cycle is waiting on. A head-only floor swallowed it, so the re-run's
+# verdict never reached anyone.
 watch_wake_ci_red() {
-    local pr="$1" pending_count="$2" failed_count="$3" head_sha="$4" floor="$5"
+    local pr="$1" pending_count="$2" failed_count="$3" head_sha="$4" red_key="$5" floor="$6"
     [ -n "$head_sha" ] || return 1
-    [ "$head_sha" != "$floor" ] || return 1
+    [ "$red_key" != "$floor" ] || return 1
     watch_checks_settled_red "$pending_count" "$failed_count" || return 1
     echo "EVENT pr=$pr checks settled red head=$head_sha"
 }

package/plugin/scripts/pr-watch-fetch.sh

@@ -25,7 +25,7 @@ query($owner: String!, $name: String!, $number: Int!) {
               contexts(first: 100) {
                 nodes {
                   __typename
-                  ... on CheckRun { name status conclusion }
+                  ... on CheckRun { databaseId name status conclusion }
                   ... on StatusContext { context state }
                 }
               }

package/plugin/scripts/pr-watch-loop.sh

@@ -178,6 +178,7 @@ while :; do
     pending_checks="${STATE_FIELDS[7]-}"
     failed_checks="${STATE_FIELDS[8]-}"
     ci_digest="${STATE_FIELDS[9]-}"
+    ci_red_key="$(watch_ci_red_key "$head_sha" "${STATE_FIELDS[10]-}")"
 
     if [ "$pr_state" = "MERGED" ] || [ "$pr_state" = "CLOSED" ]; then
         echo "TERMINAL pr=$pr_number state=$pr_state"
@@ -206,12 +207,12 @@ while :; do
         done
     fi
 
-    # Either floor quiets the head: the watermark's when a fix already ran for
-    # it, the reported one when a loop already told the session it went red.
+    # Either floor quiets the red verdict: the watermark's when fix-ci settled
+    # it, the reported one when a loop already told the session about it.
     ci_red_floor="$watermark_ci_red"
-    [ "$floor_ci_red" = "$head_sha" ] && ci_red_floor="$floor_ci_red"
-    if watch_wake_ci_red "$pr_number" "$pending_checks" "$failed_checks" "$head_sha" "$ci_red_floor"; then
-        floor_ci_red="$head_sha"
+    [ "$floor_ci_red" = "$ci_red_key" ] && ci_red_floor="$floor_ci_red"
+    if watch_wake_ci_red "$pr_number" "$pending_checks" "$failed_checks" "$head_sha" "$ci_red_key" "$ci_red_floor"; then
+        floor_ci_red="$ci_red_key"
         has_reported=1
     fi
 

package/plugin/scripts/pr-watch-state.jq

@@ -5,7 +5,14 @@
 #
 # Field order is the contract pr-watch-loop.sh reads positionally:
 #   state, headRefOid, base-tip, mergeable, latest-review, latest-comment,
-#   unresolved-thread-ids, pending-checks, failed-checks, check-digest
+#   unresolved-thread-ids, pending-checks, failed-checks, check-digest,
+#   red-check-runs
+#
+# red-check-runs names each failed check with its run id (`name#id`, sorted).
+# A settle, a rerun or a comment-triggered re-check publishes a new run on the
+# same head, so this is what tells a fresh red verdict from the one already
+# reported. check-digest cannot carry the ids: it must equal the digest the
+# blocked tick builds from `gh pr checks`, which has none.
 #
 # base-tip is where the base branch points now, the base half of the rebase key.
 # Not baseRefOid: GitHub moves that only when the head is pushed, so a key built
@@ -19,9 +26,11 @@ def loop_marked: ((.body // "") | contains("<!-- muggle-do:bot -->"));
 | (($pr.commits.nodes[0].commit.statusCheckRollup.contexts.nodes) // []) as $contexts
 | ($contexts | map(
     if .__typename == "CheckRun"
-    then {name: .name, verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
-    else {name: .context, verdict: (.state // "PENDING")}
+    then {name: .name, runId: (.databaseId // ""), verdict: (if .status != "COMPLETED" then "PENDING" else (.conclusion // "NEUTRAL") end)}
+    else {name: .context, runId: "", verdict: (.state // "PENDING")}
     end)) as $checks
+| ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")))
+    as $failedChecks
 
 # Every comment on a live thread that belongs to a submitted review. A PENDING
 # review is the reviewer's own draft and is not feedback yet.
@@ -53,6 +62,7 @@ def loop_marked: ((.body // "") | contains("<!-- muggle-do:bot -->"));
   ([$pr.reviewThreads.nodes[] | select(.isResolved == false) | select(.isOutdated == false)
     | select((.comments.nodes[0].pullRequestReview.state // "SUBMITTED") != "PENDING") | .id] | join(";")),
   ($checks | map(select(.verdict == "PENDING")) | length),
-  ($checks | map(select(.verdict == "FAILURE" or .verdict == "ERROR" or .verdict == "TIMED_OUT" or .verdict == "STARTUP_FAILURE")) | length),
-  ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(","))
+  ($failedChecks | length),
+  ($checks | sort_by(.name) | map(.name + ":" + .verdict) | join(",")),
+  ($failedChecks | map(.name + "#" + (.runId | tostring)) | sort | join(","))
 ] | @tsv

package/plugin/scripts/pr-watch-verdict.mjs

@@ -48,6 +48,12 @@ function isRebaseKeyEscalated(lastSeenEntry, rebaseKey) {
 function isCiHeadEscalated(lastSeenEntry, headSha) {
   return (lastSeenEntry.ci_escalated_shas ?? []).includes(headSha) && isCiHeadAttempted(lastSeenEntry, headSha);
 }
+function isCiHeadBudgetSpent(lastSeenEntry, headSha) {
+  return ciFixAttemptsFor(lastSeenEntry, headSha) >= MAX_CI_FIX_ATTEMPTS_PER_HEAD;
+}
+function isCiHeadSettled(lastSeenEntry, headSha) {
+  return isCiHeadEscalated(lastSeenEntry, headSha) || isCiHeadBudgetSpent(lastSeenEntry, headSha);
+}
 function isRebaseBudgetExhausted(lastSeenEntry, maxCatchUpRebases) {
   const catchUpRebases = lastSeenEntry.catch_up_rebases;
   return maxCatchUpRebases !== null && typeof catchUpRebases === "number" && catchUpRebases >= maxCatchUpRebases;
@@ -58,7 +64,7 @@ function resolveArmFloorEvidence(lastSeenEntry, headSha, rebaseKey, maxCatchUpRe
   const blockedCiDigest = lastSeenEntry.blocked?.fingerprint?.ci_digest;
   return {
     isRebaseKeyAttempted: rebaseKey !== "" && isRebaseKeyAttempted(lastSeenEntry, rebaseKey),
-    isCiHeadAttempted: headSha !== "" && isCiHeadAttempted(lastSeenEntry, headSha),
+    isCiHeadSettled: headSha !== "" && isCiHeadSettled(lastSeenEntry, headSha),
     isRebaseBudgetExhausted: isRebaseBudgetExhausted(lastSeenEntry, maxCatchUpRebases),
     blockedCiDigest: typeof blockedCiDigest === "string" && !LINE_BREAK.test(blockedCiDigest) ? blockedCiDigest : ""
   };
@@ -104,7 +110,8 @@ function resolveWatchTickVerdict(lastSeenEntry, observation, preferences) {
     if (isCiHeadBudgetLeft && !isCiHeadEscalated(lastSeenEntry, headSha)) return "dispatch-fix-ci" /* DispatchFixCi */;
   }
   if (isRebaseKeyEscalated(lastSeenEntry, rebaseKey)) return "block-conflict-escalated" /* BlockConflictEscalated */;
-  if (isCiHeadEscalated(lastSeenEntry, headSha)) return "block-ci-escalated" /* BlockCiEscalated */;
+  const isRedHeadOutOfAttempts = observation.ciBucket === "red" /* Red */ && isCiHeadBudgetSpent(lastSeenEntry, headSha);
+  if (isCiHeadEscalated(lastSeenEntry, headSha) || isRedHeadOutOfAttempts) return "block-ci-escalated" /* BlockCiEscalated */;
   if ((lastSeenEntry.escalated_review_ids ?? []).length > 0) return "block-reviews-escalated" /* BlockReviewsEscalated */;
   return "idle" /* Idle */;
 }
@@ -141,7 +148,7 @@ function runPrWatchVerdictCommand(commandLine, lastSeenJson, resolvePreferences)
     const evidence = resolveArmFloorEvidence(lastSeenEntry, headSha, rebaseKey, resolvePreferences().maxCatchUpRebases);
     return {
       stdout: `REBASE_ATTEMPTED=${evidence.isRebaseKeyAttempted ? 1 : 0}
-CI_ATTEMPTED=${evidence.isCiHeadAttempted ? 1 : 0}
+CI_SETTLED=${evidence.isCiHeadSettled ? 1 : 0}
 BLOCKED_CIDIGEST=${evidence.blockedCiDigest}
 REBASE_BUDGET_EXHAUSTED=${evidence.isRebaseBudgetExhausted ? 1 : 0}
 `,
@@ -173,14 +180,22 @@ function parseMaxCatchUpRebases(configuredValue) {
   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 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
   };
 }

package/plugin/skills/_shared/ci-check-to-command.md

@@ -7,6 +7,6 @@ Map a red CI check to the local command that reproduces and fixes it. Repo-agnos
 | lint / format | Run the repo's lint `--fix` / formatter; restage. |
 | typecheck | Run the typecheck script; read the errors; edit the types. |
 | unit / test | Run the suite; read the failures; fix the code or the test. |
-| `muggle-walkthrough` — the Muggle E2E walkthrough check | In scope. Its check-run summary names each failed or inconclusive case with the failing step and a link to the run; the walkthrough comment's hidden `muggle-e2e-result` record carries the same cases with their test case ids. Repair each, re-run the **whole** E2E suite, and settle the walkthrough comment with the new result — editing the comment re-runs the check. A summary saying the comment is still empty means no run was ever posted: run the suite and post it. |
+| `muggle-walkthrough` — the Muggle E2E walkthrough check | In scope. Its check-run summary names each failed or inconclusive case with the failing step and a link to the run; the walkthrough comment's hidden `muggle-e2e-result` record carries the same cases with their test case ids. Repair each, re-run the **whole** E2E suite, and settle the walkthrough comment with the new result — editing the comment re-runs the check. A summary saying the comment is still empty means no run was ever posted: run the suite and post it, or — when the session holds no E2E plan or a `unit-only`/`skip` one — settle it with the verified skip code that holds. Deterministic: it reads the comment, so re-running it unchanged returns the same verdict. |
 | non-deterministic — an LLM-judged eval gate (e.g. `skill-routing-eval`, `skill-gate-eval`, `agent-gate-eval`) or another check whose verdict can flip with nothing changed | Re-run its failed jobs once per head, without a push: `gh run rerun <run-id> --failed` (GitLab: retry the failed job). The re-run counts as a fix attempt. Escalate only if it fails again on the same head. How long the check takes is never a reason to skip the re-run. |
 | out of scope — any other E2E-in-CI, build/deploy infra, or unknown | Do **not** attempt; record for escalation. |