@muggleai/works 5.28.0 → 5.29.0-staging.256

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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. |

package/dist/plugin/skills/do/e2e-acceptance.md

@@ -57,7 +57,7 @@ You receive everything from `state.md` already — pre-flight resolved it:
 
 Read `state.md`.
 
-**No `## Pre-flight answers` block at all** → the session was seeded poll-only (e.g. by auto-track, [`../muggle-pr-followup/auto-track.md`](../muggle-pr-followup/auto-track.md)). Treat `Validation` as `skip`: emit a `SKIPPED` report citing `NO_PR` and exit cleanly. The watcher owns no E2E context by design; "no context" is a clean skip, not a failure.
+**No `## Pre-flight answers` block at all** → the session was seeded poll-only (e.g. by auto-track, [`../muggle-pr-followup/auto-track.md`](../muggle-pr-followup/auto-track.md)). Treat `Validation` as `skip`: emit a `SKIPPED` report citing the code that holds — `NO_WEB_SURFACE` when the repo serves nothing to drive, `NOT_APPLICABLE` when no browser run can reach the change — and exit cleanly. Never `NO_PR`: this cycle is on a PR, so the guardrail refutes it and the walkthrough stays unsettled. When a browser run *could* reach the change, no code holds: report `SKIPPED` without declaring one and leave the walkthrough to the owner's E2E decision. The watcher owns no E2E context by design; "no context" is a clean skip, not a failure.
 
 Otherwise the block was seeded by pre-flight or bootstrap per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md) — read it the same way regardless of seeder. The persisted `Validation` field (`local-e2e`, `staging-replay`, `unit-only`, `skip`) picks execution vs early-exit below. In a forward run, [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md) `ask` was resolved by pre-flight Q13; in a watcher cycle there is no per-tick pre-flight, so `Validation` **is** the standing decision — don't re-resolve `ask`.
 

package/dist/plugin/skills/do/fix-ci.md

@@ -31,6 +31,8 @@ Check out the PR branch in the session's working tree (per `state.md`). Capture
 
 Then increment `last_seen.ci_fix_attempts[red_sha]` — before any fix, re-run or escalation, as a whole-file rewrite (Read → change field → Write) per [`../_shared/session-state-writes.md`](../_shared/session-state-writes.md), never the Edit tool. Every dispatched cycle is an attempt, including one that only re-runs a check or escalates without pushing. That count is the only record the watcher and its turn-end gate accept that this red head was acted on; an escalation written without it is ignored and fix-ci is dispatched again ([`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md#last_seenjson)).
 
+The increment opens a cycle this turn carries through Step 5 or Step 6 — it never stands in for one. The single exception is a red `muggle-walkthrough` whose E2E run for **this** PR is already queued or running (its `state.md` shows `E2E dispatch: queued` or `running`): that run is the cycle, and its report settles the comment. Writing the count for a PR with no such run, or because another PR's run is in flight, clears the turn-end gate while the PR stays red; the watch never asks again until the head moves, and the PR can merge red.
+
 ### Step 2 — Map each failing check to a local command
 
 Per [`../_shared/ci-check-to-command.md`](../_shared/ci-check-to-command.md). Fix the in-scope checks in the working tree; record out-of-scope checks for escalation (Step 6). A red `muggle-walkthrough` check takes Step 2.5; a red non-deterministic check takes Step 2.6.
@@ -45,7 +47,13 @@ How long a check takes to run — a 45-minute eval included — is never a reaso
 4. **Order the settle after the push.** If Step 2 changed code, run Steps 3–4 below first, so the new head carries the fix. Then settle the walkthrough comment with the re-run's report via [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A; editing the comment re-runs the check against the head. With no code change (only retries and regenerations) there is nothing to push — the comment edit alone re-runs the check.
 5. **Wait for the fresh verdict** before Step 5's respawn: poll the check run until one completes later than the `completed_at` recorded in item 1, for up to 5 minutes. A watcher respawned sooner reads the stale red verdict and spends a fix attempt on a run already repaired. On timeout, respawn anyway — the per-SHA budget still bounds it.
 
-An empty-comment failure (no run ever posted) skips items 1–2: run the suite and settle the comment. Under a `unit-only` or `skip` validation in `state.md`, settle it with the verified skip code instead.
+An empty-comment failure (no run ever posted) skips items 1–2. Pick the branch from `state.md`:
+
+- **`local-e2e` or `staging-replay`** → run the suite and settle the comment with its report.
+- **`unit-only`, `skip`, or no `## Pre-flight answers` block at all** (a poll-only session — auto-track, or bootstrap on a PR it found no testable surface for) → settle it with the skip code that holds per [`e2e-acceptance.md`](e2e-acceptance.md): `NO_WEB_SURFACE` when the repo serves nothing to drive, `NO_APP_LOGIC_CHANGE` (detail opening with the PR's merge-base commit) when every path the PR changed is docs, tests, lint or CI config, else `NOT_APPLICABLE` with the reason no browser run can reach the change. Run `echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"` from the PR's working tree. The write runs detached, so confirm it landed: run the foreground command the walkthrough gate's block names until it prints `{"settled":true}`, never a hand-written PATCH. Never `NO_PR`: the guardrail refutes it whenever the session handled a PR.
+- **A poll-only PR whose change a browser run *can* reach** → no code holds, so do not cite one. Escalate per Step 6, naming the missing E2E decision; the owner chooses run, project or waive.
+
+`muggle-walkthrough` is never a Step 2.6 check: it reads the comment, so re-running it without editing the comment returns the same verdict.
 
 ### Step 2.6 — Red non-deterministic check: re-run once per head
 

package/dist/plugin/skills/muggle-pr-followup/arm-watcher.md

@@ -13,7 +13,7 @@ The same argument that forbids authoring a per-slot `watch.sh` applies to arming
 The `DRAIN` lines it prints, in the watch's output, are the outstanding work as of the arm. Review ids and threads the drain read are floored, so the loop will *not* tell you about those again. A stale branch or a red head is floored only when `last_seen.json` records a rebase or fix-ci cycle already attempted for that key or head ([`state-schemas.md`](state-schemas.md#watch-watermarkenv)); otherwise the drain line says `not floored: dispatch …` and the loop's first poll reports it as an event. A PR that spent its catch-up rebase budget is the exception: its drain line says the rebase is `held for the owner`, and nothing is dispatched — the tick would refuse it — until the owner raises [`maxCatchUpRebases`](../muggle-preferences/preference-gates/maxCatchUpRebases.md). Re-arming is never a way to set work aside — it neither handles nor silences anything. Steps 1-3 below are what the script does, and why.
 
 1. **Drain.** Run one tick per [`contract.md`](contract.md). It acts on everything already outstanding — actionable threads (`gitlab`: discussions), body-only reviews past the watermark (GitHub-only — GitLab has no review envelope), a stale branch, red CI — and finalizes a terminal PR. If the tick dispatched a cycle, stop here: the cycle's exit path settles the watch when it finishes.
-2. **Seed the watermark.** *(`pr-watch-arm.sh` does this; the reasoning is kept because the floors are subtle and wrong ones are quiet.)* Resolve the provider once per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md) — every fetch in this sequence uses that provider's recipes. Write the slot's watch watermark ([`state-schemas.md`](state-schemas.md#watch-watermarkenv)) to the ids the **drain itself read** — the max review-id and comment-id observed at the drain's own fetch (Step 1), snapshotted at that read. Never let the loop capture its own baseline — the arming session writes it; and **never** from a fresh fetch taken after the drain, which would include a comment that arrived after the drain read the wave and mark it seen unread. Seeded to the drain's floor, anything landing after that read stays above the watermark and the loop's first iteration surfaces it. Seed the CI floor (`CIRED`) from the same drain read: set it to the head SHA only when the checks have **already settled red** at that read (no check pending, one or more in the `fail` bucket per [`../_shared/vcs/common/ci-rollup.md`](../_shared/vcs/common/ci-rollup.md)) **and** `last_seen.json` records a fix-ci attempt for that head — a cycle already ran for that red, so its escalation or retry is not news — and empty otherwise. Seed the rebase floor (`REBASED`) the same way, from the drain's branch-standing read per [`../_shared/vcs/common/branch-standing.md`](../_shared/vcs/common/branch-standing.md): the current `rebase_key` (`<head_sha>..<base_tip_sha>`) only when the drain found the branch behind or conflicting **and** a rebase attempt is recorded for that key, empty otherwise. An escalation entry alone never floors anything: one with no attempt behind it records a decision nobody acted on, and flooring it is how a re-arming session once kept a stale branch and a red head silent for a day ([`state-schemas.md`](state-schemas.md#watch-watermarkenv) names the fields). Seed the blocked-CI floor (`BLOCKED_CIDIGEST`) to the blocked fingerprint's `ci_digest` when arming while `last_seen.blocked` is already set, and empty otherwise — empty is the not-blocked state, in which the loop's blocked-resume probe stays dormant. Seed the rebase hold (`REBASE_HELD`) to `1` when `last_seen.json`'s `catch_up_rebases` has reached `maxCatchUpRebases` — the same check the tick's verdict blocks on — and empty otherwise: while it is set the loop raises no rebase wake on any base move. The script reads all four facts from `last_seen.json` through [`../../scripts/pr-watch-verdict.mjs`](../../scripts/pr-watch-verdict.mjs) `arm-floors`, and records what it found due in `watch-due.env` ([`state-schemas.md`](state-schemas.md#watch-dueenv)).
+2. **Seed the watermark.** *(`pr-watch-arm.sh` does this; the reasoning is kept because the floors are subtle and wrong ones are quiet.)* Resolve the provider once per [`../_shared/vcs/detect-vcs.md`](../_shared/vcs/detect-vcs.md) — every fetch in this sequence uses that provider's recipes. Write the slot's watch watermark ([`state-schemas.md`](state-schemas.md#watch-watermarkenv)) to the ids the **drain itself read** — the max review-id and comment-id observed at the drain's own fetch (Step 1), snapshotted at that read. Never let the loop capture its own baseline — the arming session writes it; and **never** from a fresh fetch taken after the drain, which would include a comment that arrived after the drain read the wave and mark it seen unread. Seeded to the drain's floor, anything landing after that read stays above the watermark and the loop's first iteration surfaces it. Seed the CI floor (`CIRED`) from the same drain read: set it to the red key (`<head_sha>@<red-check-runs>`) only when the checks have **already settled red** at that read (no check pending, one or more in the `fail` bucket per [`../_shared/vcs/common/ci-rollup.md`](../_shared/vcs/common/ci-rollup.md)) **and** fix-ci is finished with that head — it escalated, or spent the tick's per-head budget — and empty otherwise. A lone attempt does not floor: the count is written before the fix runs, so a cycle that recorded it and changed nothing would otherwise leave the red silent. Seed the rebase floor (`REBASED`) the same way, from the drain's branch-standing read per [`../_shared/vcs/common/branch-standing.md`](../_shared/vcs/common/branch-standing.md): the current `rebase_key` (`<head_sha>..<base_tip_sha>`) only when the drain found the branch behind or conflicting **and** a rebase attempt is recorded for that key, empty otherwise. An escalation entry alone never floors anything: one with no attempt behind it records a decision nobody acted on, and flooring it is how a re-arming session once kept a stale branch and a red head silent for a day ([`state-schemas.md`](state-schemas.md#watch-watermarkenv) names the fields). Seed the blocked-CI floor (`BLOCKED_CIDIGEST`) to the blocked fingerprint's `ci_digest` when arming while `last_seen.blocked` is already set, and empty otherwise — empty is the not-blocked state, in which the loop's blocked-resume probe stays dormant. Seed the rebase hold (`REBASE_HELD`) to `1` when `last_seen.json`'s `catch_up_rebases` has reached `maxCatchUpRebases` — the same check the tick's verdict blocks on — and empty otherwise: while it is set the loop raises no rebase wake on any base move. The script reads all four facts from `last_seen.json` through [`../../scripts/pr-watch-verdict.mjs`](../../scripts/pr-watch-verdict.mjs) `arm-floors`, and records what it found due in `watch-due.env` ([`state-schemas.md`](state-schemas.md#watch-dueenv)).
 3. **Dedup, then watch.** First read `<slot>/watch.pid` ([`state-schemas.md`](state-schemas.md#watchpid)): if it names a live process (`kill -0 "$pid"` succeeds) **and `owner.json` records this session**, a watcher already owns this slot — **skip arming, do not start a second**. This is what stops orphaned watchers from accumulating: the in-session task dying does not stop the OS loop it launched (on Windows a detached Git Bash loop keeps running and polling `gh` forever after the session ends), so checking a live task list is not enough — the PID lease is.
 
    **A live lease owned by a different session does not count as owned** — check it with `watcher_lease_is_foreign` from [`../../scripts/pr-watch-guards.sh`](../../scripts/pr-watch-guards.sh). A live PID proves the loop is running, never that anything is listening: an orphan left by a dead session keeps polling and keeps touching its heartbeat while its stdout is that session's closed pipe, so every liveness signal reads healthy and the events reach nobody. Skipping on the PID alone let such a corpse block this session from arming the PR for the whole lifetime cap — seven days, since the default moved off six hours. When the guard reports a foreign lease, kill that PID, delete `watch.pid`, and arm fresh; note it in the slot's `followup.log` so the reclaim is visible.
@@ -36,7 +36,7 @@ The `DRAIN` lines it prints, in the watch's output, are the outstanding work as
 
    **Never author a per-slot `watch.sh`.** The loop ships as [`../../scripts/pr-watch-loop.sh`](../../scripts/pr-watch-loop.sh), with its wake conditions in [`../../scripts/pr-watch-events.sh`](../../scripts/pr-watch-events.sh) and its state projection in [`../../scripts/pr-watch-state.jq`](../../scripts/pr-watch-state.jq); arming runs it and passes arguments. Writing the loop from this prose was how it drifted — each arm produced an independent derivation, and a derivation that quietly dropped a wake still ran, still heartbeat, still logged, and simply never fired for the signal it lost. Two slots on one machine ended up without the behind-base wake, which left their PRs unmergeable under watchers that looked healthy. The prose below says *why* each wake exists; the shipped files are the only definition of *what* fires. A slot holding a legacy generated `watch.sh` keeps it until re-armed, at which point the supersede guard retires the old loop.
 
-   The task's description is `PR #<n> — <title>`. Description and command both matter: some task surfaces show one, some the other, and a slot-bearing command keeps the watch identifiable everywhere a raw script blob would not. One background task per PR at a time: it is the watch's visible handle, showing as a running task while the PR is polled, and replaced by a fresh one after each report. Its loop checks about every 60 seconds, re-reading the watermark and touching the slot's `watch-heartbeat` file each iteration — the liveness beacon that tells [`reconcile.md`](reconcile.md) a quiet watch is still alive; on a newer submitted review, a newer thread comment (`gitlab`: a newer discussion note), a thread newly unresolved (`gitlab`: discussion), **the head SHA's checks settling red** (no check pending and one or more in the `fail` bucket per [`../_shared/vcs/common/ci-rollup.md`](../_shared/vcs/common/ci-rollup.md)), **the branch falling behind or conflicting with its base** (`behind_by > 0` or the conflict signal per [`../_shared/vcs/common/branch-standing.md`](../_shared/vcs/common/branch-standing.md)), or — **only while the watch is blocked** (`BLOCKED_CIDIGEST` non-empty) — **the head's CI digest changing in any way** (not just to red) — it prints one line per finding and **exits**, recording what it reported in `watch-reported.env` ([`state-schemas.md`](state-schemas.md#watch-reportedenv)) so no later loop reports the same occurrence again. The review and thread floors are monotonic ids; the other three are not. The CI-red floor is the **head SHA**, because the check rollup is non-monotonic — it flips green↔red and resets on every push — so recording the red head SHA fires CI once per red head, and a later push re-arms it on the new SHA. The rebase floor (`REBASED`) is the **`rebase_key`** — `<head_sha>..<base_tip_sha>` — because staleness is a function of both sides: keying on the pair fires once per newly-due pair and re-arms when either the head or the base moves, where a head-only key would wedge permanently the first time the base advances (the head cannot change while nobody pushes). A head whose checks are still **pending** is never a red wake, and a branch with `behind_by == 0` and `mergeable == UNKNOWN` is never a rebase wake: pending checks may yet go green and conflict state is still computing, and the tick would idle on either (Steps 5–6) regardless. The blocked-CI signal is different in kind — a **resume** probe, live only while the watch is blocked: it wakes on any move of the head's CI digest (the same bucket-plus-sorted-name/conclusion signature the blocked fingerprint records — [`blocked-tick.md`](blocked-tick.md)) away from `BLOCKED_CIDIGEST`, so a block waiting on a green pass, a rerun, or an external deploy check resumes as promptly as one waiting on red. Quiet iterations print nothing and cost nothing — no model tokens are spent while the watch is quiet.
+   The task's description is `PR #<n> — <title>`. Description and command both matter: some task surfaces show one, some the other, and a slot-bearing command keeps the watch identifiable everywhere a raw script blob would not. One background task per PR at a time: it is the watch's visible handle, showing as a running task while the PR is polled, and replaced by a fresh one after each report. Its loop checks about every 60 seconds, re-reading the watermark and touching the slot's `watch-heartbeat` file each iteration — the liveness beacon that tells [`reconcile.md`](reconcile.md) a quiet watch is still alive; on a newer submitted review, a newer thread comment (`gitlab`: a newer discussion note), a thread newly unresolved (`gitlab`: discussion), **the head SHA's checks settling red** (no check pending and one or more in the `fail` bucket per [`../_shared/vcs/common/ci-rollup.md`](../_shared/vcs/common/ci-rollup.md)), **the branch falling behind or conflicting with its base** (`behind_by > 0` or the conflict signal per [`../_shared/vcs/common/branch-standing.md`](../_shared/vcs/common/branch-standing.md)), or — **only while the watch is blocked** (`BLOCKED_CIDIGEST` non-empty) — **the head's CI digest changing in any way** (not just to red) — it prints one line per finding and **exits**, recording what it reported in `watch-reported.env` ([`state-schemas.md`](state-schemas.md#watch-reportedenv)) so no later loop reports the same occurrence again. The review and thread floors are monotonic ids; the other three are not. The CI-red floor is the **red key** — the head SHA plus each failed check's run id — because the check rollup is non-monotonic: it flips green↔red and resets on every push, so the key fires once per red verdict and a later push re-arms it on the new SHA. The run ids matter because a settled walkthrough comment or a rerun publishes a new run on the same head; when that run is red too, it is the verdict fix-ci is waiting on, and a head-only floor swallowed it. The rebase floor (`REBASED`) is the **`rebase_key`** — `<head_sha>..<base_tip_sha>` — because staleness is a function of both sides: keying on the pair fires once per newly-due pair and re-arms when either the head or the base moves, where a head-only key would wedge permanently the first time the base advances (the head cannot change while nobody pushes). A head whose checks are still **pending** is never a red wake, and a branch with `behind_by == 0` and `mergeable == UNKNOWN` is never a rebase wake: pending checks may yet go green and conflict state is still computing, and the tick would idle on either (Steps 5–6) regardless. The blocked-CI signal is different in kind — a **resume** probe, live only while the watch is blocked: it wakes on any move of the head's CI digest (the same bucket-plus-sorted-name/conclusion signature the blocked fingerprint records — [`blocked-tick.md`](blocked-tick.md)) away from `BLOCKED_CIDIGEST`, so a block waiting on a green pass, a rerun, or an external deploy check resumes as promptly as one waiting on red. Quiet iterations print nothing and cost nothing — no model tokens are spent while the watch is quiet.
 
    Each poll also rewrites the slot's `watch-due.env` whenever the due work changes — the rebase key found due and the head whose checks settled red, or an empty file when neither — so the session's turn-end gate can see work the watch reported without a provider call ([`state-schemas.md`](state-schemas.md#watch-dueenv)).
 

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

@@ -61,6 +61,8 @@ Line-comment threads need no seeding — the watcher derives them from live thre
 
 The only step that may prompt the user, and only when the PR has a testable surface. Run silent detection from [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md) first. If it finds **no dev server / no testable surface** — a docs, config, skill, or library change, or a non-web repo — seed the watcher **poll-only**: no prompt, no `## Pre-flight answers` block, continue to Step 7 (same as [`auto-track`](auto-track.md)).
 
+Detection just established why E2E does not apply, so record it on the PR before arming. If the PR's walkthrough comment is still the placeholder, run `echo "MUGGLE_E2E_SKIP: <CODE>: <detail>"` from Step 3's working tree: `NO_WEB_SURFACE` when the repo serves nothing to drive, `NO_APP_LOGIC_CHANGE` (detail opening with the PR's merge-base commit) when every changed path is docs, tests, lint or CI config, else `NOT_APPLICABLE` naming why no browser run reaches the change. Never `NO_PR` — the guardrail refutes it on a PR. Then run the foreground command the walkthrough gate's block names until it prints `{"settled":true}`. Left unsettled, the walkthrough check sits red with nothing in this watch able to clear it, and the PR can merge that way.
+
 Otherwise resolve the context per that file: reuse an existing one (gated by `autoReuseValidationContext`), else one `AskUserQuestion` (strategy, local URL, backend, project, credentials, re-auth) with detected values as defaults; record Step 3's verified working tree as `Working tree`. The user may pick `skip`/`unit-only` or decline the prompt outright — either way, seed poll-only and continue. Never abort the watcher over validation.
 
 Capture any resolved fields for Step 7. Do **not** run E2E now — the first watcher tick that dispatches `/muggle-do` does that.

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

@@ -135,7 +135,7 @@ It prints one line, `VERDICT=<verdict>`. A non-zero exit is a broken install: re
 
 1. A rebase is due and `catch_up_rebases >= maxCatchUpRebases` (the cap from the user's preferences; the `rebase_budget_exhausted` flag is not consulted) → `block-rebase-budget-exhausted`.
 2. A rebase is due, `conflict_resolve_attempts[rebase_key] < 2`, and `rebase_key` ∉ `conflict_escalated_keys` → `dispatch-rebase`. With the per-key budget spent — `conflict_resolve_attempts[rebase_key] >= 2` or `rebase_key` ∈ `conflict_escalated_keys` — it falls through to CI.
-3. CI is `red`, `ci_fix_attempts[head_sha] < 3`, and `head_sha` ∉ `ci_escalated_shas` → `dispatch-fix-ci`. Red with `ci_fix_attempts[head_sha] >= 3` or `head_sha` ∈ `ci_escalated_shas` dispatches nothing — the fix budget is spent and the watcher does not re-dispatch. A check still pending (`bucket == "pending"`) never dispatches: the tick idles until CI settles, and a green head idles too.
+3. CI is `red`, `ci_fix_attempts[head_sha] < 3`, and `head_sha` ∉ `ci_escalated_shas` → `dispatch-fix-ci`. Red with `ci_fix_attempts[head_sha] >= 3` or `head_sha` ∈ `ci_escalated_shas` dispatches nothing — the fix budget is spent and the watcher does not re-dispatch; it holds as `block-ci-escalated` (Step 4) even when fix-ci never wrote the escalation, because idling there leaves a red PR with nobody told. A check still pending (`bucket == "pending"`) never dispatches: the tick idles until CI settles, and a green head idles too.
 4. Otherwise `block-conflict-escalated`, `block-ci-escalated`, or `block-reviews-escalated` when the matching escalation stands, else `idle`.
 
 **An escalation counts only with an attempt behind it.** An entry in `conflict_escalated_keys` suppresses a rebase only when `conflict_resolve_attempts[rebase_key] >= 1`, and an entry in `ci_escalated_shas` suppresses fix-ci only when `ci_fix_attempts[head_sha] >= 1`: a cycle ran and gave up. An entry with no attempt is ignored, and the work dispatches. Those fields are the executor's record of what its cycles did — never write an escalation entry or an attempt counter by hand.
@@ -172,7 +172,7 @@ Act on the verdict:
 Any tick that did not dispatch. The Step 6 verdict says **why** it idled. It is **blocked pending a human** on a `block-*` verdict, a durable block only the user can clear:
 
 - `block-conflict-escalated` — a rebase `/muggle-do` attempted and gave up on (a semantic conflict, or `autoResolveConflicts=never`), reason `conflict_escalated`. This block clears on its own when the base moves: the new `base_tip_sha` yields a key the set does not contain, and the branch re-arms for a fresh rebase attempt;
-- `block-ci-escalated` — CI the fix-ci stage attempted and gave up on, reason `ci_escalated`;
+- `block-ci-escalated` — CI the fix-ci stage gave up on, or a red head that spent all 3 fix-ci attempts, reason `ci_escalated`;
 - `block-reviews-escalated` — an ambiguous review in `last_seen.escalated_review_ids` awaiting the user's direction, with the actionable set empty, reason `reviews_escalated`;
 - `block-rebase-budget-exhausted` — reason `rebase_budget_exhausted` (Step 6).
 

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

@@ -217,7 +217,7 @@ The watch loop's comparison floor — plain `KEY=VALUE` lines, one file per slot
 - `REV` — highest submitted-review id already handled
 - `COM` — highest thread-comment id already handled
 - `THREADS` — semicolon-joined ids of threads already known unresolved
-- `CIRED` — head SHA whose settled-red CI a fix-ci cycle already attempted (`ci_fix_attempts[sha] >= 1`); empty when the checks are green, still pending, unseen, or red with no attempt — the last so the loop reports it. The CI floor is a SHA rather than a monotonic id because the check rollup flips green↔red and resets on each push — keying on the head SHA fires the loop once per red head and re-arms on the next push ([`arm-watcher.md`](arm-watcher.md)).
+- `CIRED` — the red key `<head_sha>@<red-check-runs>` (each failed check's `name#run-id`, sorted — the last field of [`../../scripts/pr-watch-state.jq`](../../scripts/pr-watch-state.jq)) of a red verdict fix-ci is finished with: `head_sha` ∈ `ci_escalated_shas` with an attempt behind it, or `ci_fix_attempts[sha] >= 3`. Empty when the checks are green, still pending, unseen, or red with fix-ci not finished — the last so the loop reports it. A lone attempt never floors: the count is written before the fix runs, so it proves a cycle started, not that anything on the PR changed. The floor is a red key rather than a monotonic id because the rollup flips green↔red and resets on each push, and it carries run ids because a settled walkthrough comment or a rerun publishes a new run on the **same** head — a red verdict from that run is what fix-ci waits on, so it wakes the loop again ([`arm-watcher.md`](arm-watcher.md)).
 - `REBASED` — the `rebase_key` (`<head_sha>..<base_tip_sha>`) whose behind/conflicting state a rebase cycle already attempted (`conflict_resolve_attempts[key] >= 1`); empty when the branch is current with its base, unseen, or stale with no attempt. Keyed on the pair, not a monotonic id, because staleness depends on both sides — the loop fires once per newly-due pair and re-arms when the head or the base moves. Same key [`contract.md`](contract.md) Steps 5–6 dedup rebase dispatch on; the loop only signals a due rebase, the tick's verdict applies the budgets.
 - `BLOCKED_CIDIGEST` — the head's `ci_digest` at the moment a block was flagged (the same signature `blocked.fingerprint.ci_digest` carries); empty whenever the watch is not blocked. Non-empty arms the loop's blocked-resume probe: while set, the loop wakes on any move of the live digest away from this value, so a block resumes on a green pass, a rerun, or an external deploy check — not only on red. Written by [`blocked-tick.md`](blocked-tick.md) when a block is flagged and cleared to empty when it resumes.
 - `REBASE_HELD` — `1` when the PR has spent its catch-up rebase budget (`catch_up_rebases` has reached [`maxCatchUpRebases`](../muggle-preferences/preference-gates/maxCatchUpRebases.md)), empty otherwise. While set, the loop raises no rebase wake and records no rebase as due however far the base moves: the tick's verdict refuses every rebase until the owner raises the cap, so a wake would only ask for work it turns down. Every arm recomputes it, so a raised cap lifts the hold at the next re-arm.
@@ -236,17 +236,17 @@ The work the watch last saw due on its PR, for the owning session's turn-end gat
 
 The file is **empty** when nothing is due. Written by [`../../scripts/pr-watch-arm.sh`](../../scripts/pr-watch-arm.sh) from the drain's read and rewritten by the loop whenever what is due changes; the session never writes it. The follow-through Stop gate ([`../../hooks/README.md`](../../hooks/README.md)) blocks the turn end while a non-empty record in a slot this session owns names work with no matching attempt in `last_seen.json`: a `REBASE_DUE` key with no `conflict_resolve_attempts` entry (under `autoRebase=always`, budget left), or a `CI_RED_HEAD` with no `ci_fix_attempts` entry. A later tick's `prs.json` naming another head supersedes the record.
 
-## `watch-reported.env`
-
-What the slot's loops already reported to the session — `KEY="value"` lines like the watermark's, written only by the loop, and only on the poll that ends it with a report:
-
-- `REV` / `COM` — the newest review and comment ids that poll saw; each one at or below them was reported or already floored.
-- `THREADS` — the threads unresolved at that poll.
-- `CIRED` / `REBASED` — the red head and the rebase key a loop reported.
-- `BLOCKED_CIDIGEST` / `BLOCKED_FOR` — the CI digest a blocked-resume wake reported, and the watermark's `BLOCKED_CIDIGEST` it was reported under. It quiets only that block, so the same digest can resume a later one.
-
-A loop fires only on what sits above both this file and [`watch-watermark.env`](#watch-watermarkenv). Every report ends a loop, so no floor can live in its memory: without this file, anything the session saw and chose not to act on — a comment needing no reply, a red check under `HOLD WATCH` — would end every fresh loop on its first poll. Read it as the watermark is read, never by `source`.
-
+## `watch-reported.env`
+
+What the slot's loops already reported to the session — `KEY="value"` lines like the watermark's, written only by the loop, and only on the poll that ends it with a report:
+
+- `REV` / `COM` — the newest review and comment ids that poll saw; each one at or below them was reported or already floored.
+- `THREADS` — the threads unresolved at that poll.
+- `CIRED` / `REBASED` — the red key and the rebase key a loop reported.
+- `BLOCKED_CIDIGEST` / `BLOCKED_FOR` — the CI digest a blocked-resume wake reported, and the watermark's `BLOCKED_CIDIGEST` it was reported under. It quiets only that block, so the same digest can resume a later one.
+
+A loop fires only on what sits above both this file and [`watch-watermark.env`](#watch-watermarkenv). Every report ends a loop, so no floor can live in its memory: without this file, anything the session saw and chose not to act on — a comment needing no reply, a red check under `HOLD WATCH` — would end every fresh loop on its first poll. Read it as the watermark is read, never by `source`.
+
 ## `watch.pid`
 
 A single line: the process id of the watch loop that currently owns this slot. Written once by the loop itself on start (`echo "$$" > watch.pid`); read by two parties, never rewritten in place:

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.26.0",
-  "buildId": "run-254-1",
-  "commitSha": "827f3558e259bf1905d25d297bdb875478a1a9e0",
-  "buildTime": "2026-10-30T07:03:59Z",
+  "buildId": "run-256-1",
+  "commitSha": "5838b08d25aebf0dda3aee280e619ba96c5799bc",
+  "buildTime": "2026-10-30T20:31:46Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.28.0",
+  "version": "5.29.0-staging.256",
   "description": "13 years of Microsoft hyperscale engineering, packaged as a harness for your AI coding agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -64,7 +64,7 @@
   "muggleConfig": {
     "electronAppVersion": "1.17.0",
     "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
-    "runtimeTargetDefault": "production",
+    "runtimeTargetDefault": "staging",
     "checksumsByStream": {
       "production": {
         "win32-x64": "03687e6c511f407875354954cb1b0f8e95d4ad0602174d76388a52d1aa1554e4",

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