@muggleai/works 5.27.0-staging.243 → 5.27.0-staging.245

package/.claude-plugin/marketplace.json

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

package/dist/{chunk-EPIM27JX.js → chunk-SJBYMBC2.js}

@@ -5375,7 +5375,7 @@ function readProcessTable(platform4, runCommand, nowMs) {
 function resumeOnReconcile(target, runCommand, waitForExit) {
   if (target.runningShortId !== void 0) {
     runCommand("claude", ["stop", target.runningShortId]);
-    if (!waitForExit(target.sessionId)) return false;
+    if (!waitForExit(target.runningSessionId ?? target.sessionId)) return false;
   }
   const resumed = runCommand("claude", ["--resume", target.sessionId, "--bg", RECOVERY_RESUME_PROMPT], { cwd: target.cwd });
   return resumed?.exitCode === 0;
@@ -5383,17 +5383,21 @@ function resumeOnReconcile(target, runCommand, waitForExit) {
 
 // src/watch/recovery.ts
 function isRecoverable(assessment, ownerSession) {
-  const isOwnerRestartable = assessment.isOwnerSessionActive === false || assessment.isOwnerSessionActive === true && ownerSession !== void 0 && isIdleBackgroundSession(ownerSession);
+  const isOwnerRestartable = ownerSession === void 0 ? assessment.isOwnerSessionActive === false : isIdleBackgroundSession(ownerSession);
   return assessment.isRegistered && assessment.watcher === "dead" /* Dead */ && assessment.live?.state === "OPEN" /* Open */ && assessment.ownerSessionId !== void 0 && isOwnerRestartable;
 }
 function isSlotCloseOutDue(assessment) {
   return isTerminalPrState(assessment.live?.state) && assessment.watcher === "dead" /* Dead */ && assessment.isOwnerSessionActive !== true;
 }
+function findRunningOwner(sessionsById, ownerSessionId) {
+  const ownerShortId = shortSessionId(ownerSessionId);
+  return sessionsById.get(ownerSessionId) ?? [...sessionsById.values()].find((session) => session.shortId === ownerShortId);
+}
 function planWatcherRecoveries(assessments, attemptsByOwner, nowMs, isPollingDisabled, sessionsById = /* @__PURE__ */ new Map(), isStoppedAtUsageLimit2 = () => false) {
   if (isPollingDisabled) return [];
   const slugsByOwner = /* @__PURE__ */ new Map();
   for (const assessment of assessments) {
-    const ownerSession = assessment.ownerSessionId === void 0 ? void 0 : sessionsById.get(assessment.ownerSessionId);
+    const ownerSession = assessment.ownerSessionId === void 0 ? void 0 : findRunningOwner(sessionsById, assessment.ownerSessionId);
     if (!isRecoverable(assessment, ownerSession)) continue;
     const ownerSessionId = assessment.ownerSessionId;
     const slugs = slugsByOwner.get(ownerSessionId) ?? /* @__PURE__ */ new Set();
@@ -5405,18 +5409,20 @@ function planWatcherRecoveries(assessments, attemptsByOwner, nowMs, isPollingDis
   for (const ownerSessionId of [...slugsByOwner.keys()].sort()) {
     const recentAttemptsMs = (attemptsByOwner[ownerSessionId] ?? []).map((attemptedAt) => Date.parse(attemptedAt)).filter((attemptedAtMs) => !Number.isNaN(attemptedAtMs) && nowMs - attemptedAtMs < RECOVERY_ATTEMPT_WINDOW_MS);
     const lastAttemptMs = Math.max(-Infinity, ...recentAttemptsMs);
-    const isCapReached = recentAttemptsMs.length >= RECOVERY_MAX_ATTEMPTS && !isStoppedAtUsageLimit2(ownerSessionId);
+    const runningOwner = findRunningOwner(sessionsById, ownerSessionId);
+    const isRunningAtUsageLimit = runningOwner !== void 0 && [ownerSessionId, runningOwner.sessionId].some((sessionId) => isStoppedAtUsageLimit2(sessionId));
     let outcome = "resume-due" /* ResumeDue */;
-    if (isCapReached) outcome = "attempts-exhausted" /* AttemptsExhausted */;
+    if (isRunningAtUsageLimit) outcome = "awaiting-usage-limit-reset" /* AwaitingUsageLimitReset */;
+    else if (recentAttemptsMs.length >= RECOVERY_MAX_ATTEMPTS) outcome = "attempts-exhausted" /* AttemptsExhausted */;
     else if (nowMs - lastAttemptMs < RECOVERY_COOLDOWN_MS) outcome = "cooling-down" /* CoolingDown */;
     else if (resumesPlanned >= MAX_RESUMES_PER_TICK) outcome = "deferred-by-tick-cap" /* DeferredByTickCap */;
     if (outcome === "resume-due" /* ResumeDue */) resumesPlanned++;
-    const runningOwner = sessionsById.get(ownerSessionId);
     recoveries.push({
       ownerSessionId,
       slotSlugs: [...slugsByOwner.get(ownerSessionId) ?? []].sort(),
       outcome,
-      ...runningOwner?.shortId === void 0 ? {} : { ownerShortId: runningOwner.shortId }
+      ...runningOwner?.shortId === void 0 ? {} : { ownerShortId: runningOwner.shortId },
+      ...runningOwner === void 0 || runningOwner.sessionId === ownerSessionId ? {} : { ownerRunningSessionId: runningOwner.sessionId }
     });
   }
   return recoveries;
@@ -5444,7 +5450,7 @@ function executeWatcherRecoveries(planned, attemptsByOwner, deps) {
       return { ...recovery, cwd, outcome: "restart-refused" /* RestartRefused */ };
     }
     const isResumed = resumeOnReconcile(
-      { sessionId: recovery.ownerSessionId, cwd, runningShortId: recovery.ownerShortId },
+      { sessionId: recovery.ownerSessionId, cwd, runningShortId: recovery.ownerShortId, runningSessionId: recovery.ownerRunningSessionId },
       deps.runCommand,
       deps.waitForExit
     );

package/dist/cli.js

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

package/dist/index.js

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

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

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

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

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.27.0-staging.243",
+        "@muggleai/works@5.27.0-staging.245",
         "serve"
       ],
       "env": {

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

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

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

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

package/dist/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.27.0-staging.243",
+        "@muggleai/works@5.27.0-staging.245",
         "serve"
       ]
     }

package/dist/plugin/hooks/README.md

@@ -42,7 +42,7 @@ Pre-filters are bash builtins only (`guardrail-lib.sh`), so an irrelevant event
 | `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
 | `PostToolUse` (Agent, Task) | `guardrail-record-delegation.sh` | record | a `muggle:acceptance-tester` was launched into the background — its response carries no finished report yet | — | append to `e2eDelegations` with the PR URLs its brief names; for a bounded window the E2E and debug-path gates hold off, and the walkthrough gate sets those PRs aside, so the session is never steered into a second browser run alongside the agent's. Shares the AskUserQuestion group's dispatch |
 | `PostToolUse` (Skill + muggle telemetry-skill-emit) | `guardrail-skill-stages.sh` | advise | a skill this plugin ships was invoked; its `SKILL.md` frontmatter may declare `mandatoryStages`. Registered on the skill's own MCP announcement too, so the declaration still lands if the Skill payload ever stops carrying a name. A muggle-test announcement is also an E2E run (the clean SKIP verdict), recorded here alone, so the skill, its stages and the run land in one commit; a write that cannot take the session's lock in time is saved beside the state file and committed by a detached job once the lock frees | — | record `lastInvokedSkillName` + `mandatoryStages` (and `e2eRun` for a muggle-test announcement), and name the declared files as required reading at the moment of use |
-| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped |
+| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped; a route entry file in the plugin's skills tree, opened while a skill runs, also adds the `mandatoryStages` its frontmatter declares |
 | `PostToolUse` (Bash + muggle telemetry-event-emit / user-feedback-create) | `guardrail-record-stage-signals.sh` | record | a Step 6f `pre-execution-classification` emit, debug-path evidence for a failed run (a `*-failure-classified\|resolved` emit or feedback naming it), or a `MUGGLE_STAGE_SKIP` / `MUGGLE_CLASSIFY_SKIP` / `MUGGLE_DEBUG_SKIP` marker | — | set `classifiedTestCaseIds` / `debuggedRuns` / the matching skip flag |
 | `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 |

package/dist/plugin/scripts/guardrail-record-stage-read.sh

@@ -4,6 +4,8 @@ set -uo pipefail
 # stage-read observer (PostToolUse/Read, and PostToolUse/Bash through the
 # dispatcher). Records that a file in the skills tree was opened, which is how
 # the Stop gate tells a mandatory stage that was read from one that was skipped.
+# A route's entry file that declares `mandatoryStages` adds that route's stages
+# when it is opened during a skill's run.
 # A host with no Read tool (Codex) opens stage files through the shell — `cat`,
 # `sed -n` — so a shell command that prints one counts as a read too. Emits no
 # directive.

package/dist/plugin/scripts/guardrails.mjs

@@ -1464,6 +1464,7 @@ var SEQUENCE_ENTRY = /^\s*-\s*(.+?)\s*$/;
 var FLOW_LIST = /^\s*\[(.*)\]\s*$/;
 var STAGE_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_STAGE_SKIP\b/;
 var SKILLS_DIR_NAME = "skills";
+var SKILL_ENTRY_FILE_NAME = "SKILL.md";
 var SKILLS_PATH_SEGMENT = `/${SKILLS_DIR_NAME}/`;
 var SINGLE_PATH_SEGMENT = /^[A-Za-z0-9._-]+$/;
 var SHELL_VARIABLE_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
@@ -1513,17 +1514,15 @@ function resolveSkillNameFromToolInput(toolInput) {
   }
   return void 0;
 }
-function resolveSkillStagePaths(skillName, skillsRootDir) {
-  const skillDir = join(skillsRootDir, skillName);
-  const skillFile = join(skillDir, "SKILL.md");
-  if (!existsSync(skillFile)) return [];
-  const normalizedRoot = normalizeStagePath(skillsRootDir);
-  const staysInsideSkillsTree = (candidate) => normalizeStagePath(candidate).startsWith(`${normalizedRoot}/`);
+var isInsideDirectory = (candidatePath, directory) => normalizeStagePath(candidatePath).startsWith(`${normalizeStagePath(directory)}/`);
+function resolveDeclaredStagePaths(declaringFile, skillsRootDir) {
+  if (!existsSync(declaringFile)) return [];
+  const declaringDir = dirname(declaringFile);
   const resolved = [];
-  for (const declared of parseDeclaredStages(readFileSync(skillFile, "utf-8"))) {
+  for (const declared of parseDeclaredStages(readFileSync(declaringFile, "utf-8"))) {
     if (isAbsolute(declared)) continue;
-    const stagePath = [resolve(skillDir, declared), resolve(skillsRootDir, declared)].find(
-      (candidate) => staysInsideSkillsTree(candidate) && existsSync(candidate)
+    const stagePath = [resolve(declaringDir, declared), resolve(skillsRootDir, declared)].find(
+      (candidate) => isInsideDirectory(candidate, skillsRootDir) && existsSync(candidate)
     );
     if (!stagePath) continue;
     const normalized = normalizeStagePath(stagePath);
@@ -1531,13 +1530,27 @@ function resolveSkillStagePaths(skillName, skillsRootDir) {
   }
   return resolved;
 }
+function resolveSkillStagePaths(skillName, skillsRootDir) {
+  return resolveDeclaredStagePaths(join(skillsRootDir, skillName, SKILL_ENTRY_FILE_NAME), skillsRootDir);
+}
+function resolveRouteStagePaths(state, readPath, skillsRootDir) {
+  if (!state.lastInvokedSkillName) return [];
+  if (basename(readPath).toLowerCase() === SKILL_ENTRY_FILE_NAME.toLowerCase()) return [];
+  if (!isInsideDirectory(readPath, skillsRootDir)) return [];
+  return resolveDeclaredStagePaths(readPath, skillsRootDir);
+}
+function applyDeclaredStages(state, stagePaths) {
+  const owed = state.mandatoryStages ?? [];
+  const added = stagePaths.filter(
+    (stagePath, index) => !owed.includes(stagePath) && stagePaths.indexOf(stagePath) === index
+  );
+  if (added.length === 0) return state;
+  return { ...state, mandatoryStages: [...owed, ...added] };
+}
 function applySkillInvocation(state, skillName, stagePaths) {
-  const merged = [...state.mandatoryStages ?? []];
-  for (const stagePath of stagePaths) if (!merged.includes(stagePath)) merged.push(stagePath);
-  if (state.lastInvokedSkillName === skillName && merged.length === (state.mandatoryStages?.length ?? 0)) {
-    return state;
-  }
-  return { ...state, lastInvokedSkillName: skillName, mandatoryStages: merged };
+  const declared = applyDeclaredStages(state, stagePaths);
+  if (declared === state && state.lastInvokedSkillName === skillName) return state;
+  return { ...declared, lastInvokedSkillName: skillName };
 }
 function isSkillTreeMarkdown(filePath) {
   const normalized = normalizeStagePath(filePath);
@@ -1589,8 +1602,10 @@ function detectShellStageReads(command, cwd, env = process.env) {
     if (!FILE_PRINTING_PROGRAMS.includes(program)) continue;
     for (const argument of argumentWords) {
       if (argument.startsWith("-") || !MARKDOWN_FILE.test(argument)) continue;
-      const readPath = normalizeStagePath(resolveShellPath(argument, workingDirectory));
-      if (isSkillTreeMarkdown(readPath) && !readPaths.includes(readPath)) readPaths.push(readPath);
+      const readPath = resolveShellPath(argument, workingDirectory);
+      const readKey = normalizeStagePath(readPath);
+      const isRecorded = readPaths.some((recordedPath) => normalizeStagePath(recordedPath) === readKey);
+      if (isSkillTreeMarkdown(readPath) && !isRecorded) readPaths.push(readPath);
     }
   }
   return readPaths;
@@ -1782,8 +1797,13 @@ function applyStateMutation(state, mutation) {
       return applyE2eDelegation(state, mutation.delegation);
     case "watch-follow-through" /* WatchFollowThrough */:
       return { ...applyWatchHolds(state, mutation.heldPrNumbers), watchFollowThroughBlockCount: mutation.blockCount };
-    case "stage-reads" /* StageReads */:
-      return mutation.readPaths.reduce(applyStageRead, state);
+    case "stage-reads" /* StageReads */: {
+      const withReads = mutation.readPaths.reduce(applyStageRead, state);
+      const skillsRootDir = mutation.skillsRootDir;
+      if (!skillsRootDir) return withReads;
+      const routeStagePaths = mutation.readPaths.flatMap((readPath) => resolveRouteStagePaths(withReads, readPath, skillsRootDir));
+      return applyDeclaredStages(withReads, routeStagePaths);
+    }
     case "stage-signals" /* StageSignals */:
       return applyStageSignals(state, mutation);
     case "fields" /* Fields */:
@@ -2794,7 +2814,11 @@ function recordStageRead() {
   const readPaths = filePath ? [filePath].filter(isSkillTreeMarkdown) : isShellToolCall(input) ? detectShellStageReads(input.tool_input?.command ?? "", input.cwd) : [];
   if (readPaths.length === 0) return "{}";
   if (callFailed(input)) return "{}";
-  commitStateMutation(sessionId, { kind: "stage-reads" /* StageReads */, readPaths }, readState(sessionId));
+  commitStateMutation(
+    sessionId,
+    { kind: "stage-reads" /* StageReads */, readPaths, skillsRootDir: resolvePluginSkillsRoot() },
+    readState(sessionId)
+  );
   return "{}";
 }
 function recordStageSignals() {

package/dist/plugin/skills/CLAUDE.md

@@ -36,6 +36,8 @@ Invoking the skill names those files as required reading, and a Stop gate holds
 
 The bar is "must be **read** before the skill runs", not "must be executed". A failure protocol qualifies: by the time a run fails, a skill that never read it is already improvising. What does not qualify is a file only one branch consults for its content — the gate cannot tell that the branch was not taken, so it would block work that legitimately never needed it. Aliases declare nothing; they invoke the canonical skill, which carries the declaration.
 
+A skill whose router sends runs down different routes declares per route. Its `SKILL.md` lists only what every run opens — the router — and each route's entry file carries its own `mandatoryStages` frontmatter, paths relative to that file. Opening the entry file while the skill runs adds its set; a `SKILL.md` declares only when invoked, never when read. A route lists only the files every run of that route opens, so a branch inside a route still stays out.
+
 ## Host compatibility
 
 Skills are written against Claude Code's tools and ship unchanged to Codex. [`_shared/host-tool-equivalents.md`](_shared/host-tool-equivalents.md) maps each Claude Code name a skill uses — `AskUserQuestion`, the `Skill` tool, `${CLAUDE_PLUGIN_ROOT}`, the PR watcher's monitor — to what plays its part in Codex. Every top-level `SKILL.md` links it right after its telemetry line, and the Codex SessionStart hook names it too.

package/dist/plugin/skills/do/address-reviews.md

@@ -1,3 +1,9 @@
+---
+mandatoryStages:
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Address-Reviews Orchestrator
 
 The entry procedure for `/muggle-do`'s **address-reviews** mode — invoked by the watcher loop ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)) when new submitted reviews land on a PR. Orchestrates the cycle: read reviews → classify → execute work on actionables → escalate ambiguous → push and refresh PR → reply per comment → resolve-reminder → respawn watcher.

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

@@ -1,3 +1,10 @@
+---
+mandatoryStages:
+  - ../_shared/session-state-writes.md
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Fix-CI (watcher-dispatched)
 
 Resolve red CI on a PR's head — lint/format, typecheck, failing unit tests, and a red Muggle E2E walkthrough check — verifying green before re-push. A dumb-pipe dispatch like address-reviews: the executor receives a PR URL, slug, and the failing check names, and fixes them — it owns the fix, not the decision to dispatch.

package/dist/plugin/skills/do/pre-flight.md

@@ -1,3 +1,14 @@
+---
+mandatoryStages:
+  - requirements.md
+  - build.md
+  - impact-analysis.md
+  - unit-tests.md
+  - e2e-acceptance.md
+  - open-prs/forward.md
+  - e2e-repair.md
+---
+
 # Pre-flight Agent (Stage 1)
 
 You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.

package/dist/plugin/skills/do/resolve-conflicts.md

@@ -1,3 +1,10 @@
+---
+mandatoryStages:
+  - ../_shared/session-state-writes.md
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Rebase (watcher-dispatched)
 
 Rebase a PR's branch onto its base — whether it's merely **behind** (out of date, no conflict) or actually **conflicting** — behind a verify-or-rollback gate, then force-push, so a PR doesn't sit stale or un-mergeable forever. A dumb-pipe dispatch like fix-ci: the watcher detects the branch is behind or conflicting and hands off; the executor owns the rebase (and any conflict resolution), never the decision to dispatch.

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

@@ -1,6 +1,8 @@
 ---
 name: muggle-do
 description: Take a feature request, spec, design, bug, or ticket and carry it autonomously to an opened pull request — write the code, test it, raise the PR. The PR carries real-browser proof: email-gated flows run through live test inboxes, logins through encrypted secrets, and prerequisite flows in test-graph order, with screenshots attached. Use whenever the user wants something built, implemented, added, or fixed with a PR opened, raised, or put up at the end — "implement rate limiting and raise a PR", "build the CSV export and put up a PR", "take this Jira ticket and run with it, ping me when the PR is up", "fix this bug and open a pr", or "muggle do …". Also handles the internal `address-reviews` directive the muggle-pr-followup watcher dispatches when new reviews land. Not for testing or validating existing changes (use muggle-test), nor watching a PR's incoming reviews (use muggle-pr-followup).
+mandatoryStages:
+  - ../do/input-routing.md
 ---
 
 # Muggle Test Do
@@ -42,7 +44,7 @@ The pipeline table lists **pointers, not summaries**. Open each stage's file and
 2. Create `~/.muggle-ai/muggle-do/sessions/<slug>/` with `state.md` + `iterations/001.md` (pre-flight owns this; do it even when running unattended).
 3. `TodoWrite` one item per stage 1–8, Stage 7.5 included — these stages are the checklist; never swap in your own decomposition. Several changes → one set of stage items per change.
 
-**Per stage:** read the file → execute it → append a marker to `iterations/<NNN>.md` citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
+**Per stage:** read the file → execute it → append one marker line to `iterations/<NNN>.md`, always in the form `Stage <N> done — <evidence>`, citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
 
 ### "Autonomous" / "without my intervention" collapses exactly one thing
 Best-effort the Stage-1 questionnaire and don't ask. It does **not** license skipping telemetry, session artifacts, requirements, unit tests, E2E (`autoE2ETest` defaults to `always`), browser verification, the gate below, the Stage-7.5 repair loop, or the watcher hand-off. Stage 7.5 investigates and repairs unattended too; only its user decision collapses, into an automatic waive. Run the whole pipeline silently — never a shortcut.
@@ -94,5 +96,6 @@ When invoked with the directive (PR URL + slug + review ids), routes to [`../do/
 
 - Stage 1 and Stage 7.5's user decision are the only user-facing forward stages. Stages 2–7 don't ask mid-cycle; blocker → pre-flight bug.
 - Same stage failing 3× → escalate.
+- Each route's entry file declares the stage files every run of that route opens, and a Stop gate holds the turn until they are read. A turn that ends before its route's last stage — a readiness halt, an escalation, a pause for a background run — records why with `echo "MUGGLE_STAGE_SKIP: <reason>"`.
 - 3 repair iterations reach E2E with failures → waive, ship with `[E2E FAILING]`, and hand to the watcher.
 - Address-reviews escalation (ambiguous or design-adjustment) does not block the watcher; user resolves on GitHub.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.26.0",
-  "buildId": "run-243-1",
-  "commitSha": "794d5f8d369c432b2843204503c101ff1ee71483",
-  "buildTime": "2026-10-28T04:24:25Z",
+  "buildId": "run-245-1",
+  "commitSha": "d4e56d068786541b25d22819c6336d5c5f5baf6b",
+  "buildTime": "2026-10-29T16:50:53Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.27.0-staging.243",
+  "version": "5.27.0-staging.245",
   "description": "13 years of Microsoft hyperscale engineering, packaged as a harness for your AI coding agent.",
   "type": "module",
   "main": "dist/index.js",

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.27.0-staging.243",
+  "version": "5.27.0-staging.245",
   "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.27.0-staging.243",
+        "@muggleai/works@5.27.0-staging.245",
         "serve"
       ],
       "env": {

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

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.27.0-staging.243",
+  "version": "5.27.0-staging.245",
   "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.27.0-staging.243",
+  "version": "5.27.0-staging.245",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.27.0-staging.243",
+        "@muggleai/works@5.27.0-staging.245",
         "serve"
       ]
     }

package/plugin/hooks/README.md

@@ -42,7 +42,7 @@ Pre-filters are bash builtins only (`guardrail-lib.sh`), so an irrelevant event
 | `PostToolUse` (AskUserQuestion) | `guardrail-offer-ran.sh` | record | a next-options offer ran while a terminal PR was pending | — | clear `terminalPending` — the only exit for the post-merge Stop gate |
 | `PostToolUse` (Agent, Task) | `guardrail-record-delegation.sh` | record | a `muggle:acceptance-tester` was launched into the background — its response carries no finished report yet | — | append to `e2eDelegations` with the PR URLs its brief names; for a bounded window the E2E and debug-path gates hold off, and the walkthrough gate sets those PRs aside, so the session is never steered into a second browser run alongside the agent's. Shares the AskUserQuestion group's dispatch |
 | `PostToolUse` (Skill + muggle telemetry-skill-emit) | `guardrail-skill-stages.sh` | advise | a skill this plugin ships was invoked; its `SKILL.md` frontmatter may declare `mandatoryStages`. Registered on the skill's own MCP announcement too, so the declaration still lands if the Skill payload ever stops carrying a name. A muggle-test announcement is also an E2E run (the clean SKIP verdict), recorded here alone, so the skill, its stages and the run land in one commit; a write that cannot take the session's lock in time is saved beside the state file and committed by a detached job once the lock frees | — | record `lastInvokedSkillName` + `mandatoryStages` (and `e2eRun` for a muggle-test announcement), and name the declared files as required reading at the moment of use |
-| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped |
+| `PostToolUse` (Read) | `guardrail-record-stage-read.sh` | record | a markdown file under a `skills/` directory was opened | — | append to `stagesRead` — how the stage gate tells a stage that was read from one that was skipped; a route entry file in the plugin's skills tree, opened while a skill runs, also adds the `mandatoryStages` its frontmatter declares |
 | `PostToolUse` (Bash + muggle telemetry-event-emit / user-feedback-create) | `guardrail-record-stage-signals.sh` | record | a Step 6f `pre-execution-classification` emit, debug-path evidence for a failed run (a `*-failure-classified\|resolved` emit or feedback naming it), or a `MUGGLE_STAGE_SKIP` / `MUGGLE_CLASSIFY_SKIP` / `MUGGLE_DEBUG_SKIP` marker | — | set `classifiedTestCaseIds` / `debuggedRuns` / the matching skip flag |
 | `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 |

package/plugin/scripts/guardrail-record-stage-read.sh

@@ -4,6 +4,8 @@ set -uo pipefail
 # stage-read observer (PostToolUse/Read, and PostToolUse/Bash through the
 # dispatcher). Records that a file in the skills tree was opened, which is how
 # the Stop gate tells a mandatory stage that was read from one that was skipped.
+# A route's entry file that declares `mandatoryStages` adds that route's stages
+# when it is opened during a skill's run.
 # A host with no Read tool (Codex) opens stage files through the shell — `cat`,
 # `sed -n` — so a shell command that prints one counts as a read too. Emits no
 # directive.

package/plugin/scripts/guardrails.mjs

@@ -1464,6 +1464,7 @@ var SEQUENCE_ENTRY = /^\s*-\s*(.+?)\s*$/;
 var FLOW_LIST = /^\s*\[(.*)\]\s*$/;
 var STAGE_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_STAGE_SKIP\b/;
 var SKILLS_DIR_NAME = "skills";
+var SKILL_ENTRY_FILE_NAME = "SKILL.md";
 var SKILLS_PATH_SEGMENT = `/${SKILLS_DIR_NAME}/`;
 var SINGLE_PATH_SEGMENT = /^[A-Za-z0-9._-]+$/;
 var SHELL_VARIABLE_REFERENCE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
@@ -1513,17 +1514,15 @@ function resolveSkillNameFromToolInput(toolInput) {
   }
   return void 0;
 }
-function resolveSkillStagePaths(skillName, skillsRootDir) {
-  const skillDir = join(skillsRootDir, skillName);
-  const skillFile = join(skillDir, "SKILL.md");
-  if (!existsSync(skillFile)) return [];
-  const normalizedRoot = normalizeStagePath(skillsRootDir);
-  const staysInsideSkillsTree = (candidate) => normalizeStagePath(candidate).startsWith(`${normalizedRoot}/`);
+var isInsideDirectory = (candidatePath, directory) => normalizeStagePath(candidatePath).startsWith(`${normalizeStagePath(directory)}/`);
+function resolveDeclaredStagePaths(declaringFile, skillsRootDir) {
+  if (!existsSync(declaringFile)) return [];
+  const declaringDir = dirname(declaringFile);
   const resolved = [];
-  for (const declared of parseDeclaredStages(readFileSync(skillFile, "utf-8"))) {
+  for (const declared of parseDeclaredStages(readFileSync(declaringFile, "utf-8"))) {
     if (isAbsolute(declared)) continue;
-    const stagePath = [resolve(skillDir, declared), resolve(skillsRootDir, declared)].find(
-      (candidate) => staysInsideSkillsTree(candidate) && existsSync(candidate)
+    const stagePath = [resolve(declaringDir, declared), resolve(skillsRootDir, declared)].find(
+      (candidate) => isInsideDirectory(candidate, skillsRootDir) && existsSync(candidate)
     );
     if (!stagePath) continue;
     const normalized = normalizeStagePath(stagePath);
@@ -1531,13 +1530,27 @@ function resolveSkillStagePaths(skillName, skillsRootDir) {
   }
   return resolved;
 }
+function resolveSkillStagePaths(skillName, skillsRootDir) {
+  return resolveDeclaredStagePaths(join(skillsRootDir, skillName, SKILL_ENTRY_FILE_NAME), skillsRootDir);
+}
+function resolveRouteStagePaths(state, readPath, skillsRootDir) {
+  if (!state.lastInvokedSkillName) return [];
+  if (basename(readPath).toLowerCase() === SKILL_ENTRY_FILE_NAME.toLowerCase()) return [];
+  if (!isInsideDirectory(readPath, skillsRootDir)) return [];
+  return resolveDeclaredStagePaths(readPath, skillsRootDir);
+}
+function applyDeclaredStages(state, stagePaths) {
+  const owed = state.mandatoryStages ?? [];
+  const added = stagePaths.filter(
+    (stagePath, index) => !owed.includes(stagePath) && stagePaths.indexOf(stagePath) === index
+  );
+  if (added.length === 0) return state;
+  return { ...state, mandatoryStages: [...owed, ...added] };
+}
 function applySkillInvocation(state, skillName, stagePaths) {
-  const merged = [...state.mandatoryStages ?? []];
-  for (const stagePath of stagePaths) if (!merged.includes(stagePath)) merged.push(stagePath);
-  if (state.lastInvokedSkillName === skillName && merged.length === (state.mandatoryStages?.length ?? 0)) {
-    return state;
-  }
-  return { ...state, lastInvokedSkillName: skillName, mandatoryStages: merged };
+  const declared = applyDeclaredStages(state, stagePaths);
+  if (declared === state && state.lastInvokedSkillName === skillName) return state;
+  return { ...declared, lastInvokedSkillName: skillName };
 }
 function isSkillTreeMarkdown(filePath) {
   const normalized = normalizeStagePath(filePath);
@@ -1589,8 +1602,10 @@ function detectShellStageReads(command, cwd, env = process.env) {
     if (!FILE_PRINTING_PROGRAMS.includes(program)) continue;
     for (const argument of argumentWords) {
       if (argument.startsWith("-") || !MARKDOWN_FILE.test(argument)) continue;
-      const readPath = normalizeStagePath(resolveShellPath(argument, workingDirectory));
-      if (isSkillTreeMarkdown(readPath) && !readPaths.includes(readPath)) readPaths.push(readPath);
+      const readPath = resolveShellPath(argument, workingDirectory);
+      const readKey = normalizeStagePath(readPath);
+      const isRecorded = readPaths.some((recordedPath) => normalizeStagePath(recordedPath) === readKey);
+      if (isSkillTreeMarkdown(readPath) && !isRecorded) readPaths.push(readPath);
     }
   }
   return readPaths;
@@ -1782,8 +1797,13 @@ function applyStateMutation(state, mutation) {
       return applyE2eDelegation(state, mutation.delegation);
     case "watch-follow-through" /* WatchFollowThrough */:
       return { ...applyWatchHolds(state, mutation.heldPrNumbers), watchFollowThroughBlockCount: mutation.blockCount };
-    case "stage-reads" /* StageReads */:
-      return mutation.readPaths.reduce(applyStageRead, state);
+    case "stage-reads" /* StageReads */: {
+      const withReads = mutation.readPaths.reduce(applyStageRead, state);
+      const skillsRootDir = mutation.skillsRootDir;
+      if (!skillsRootDir) return withReads;
+      const routeStagePaths = mutation.readPaths.flatMap((readPath) => resolveRouteStagePaths(withReads, readPath, skillsRootDir));
+      return applyDeclaredStages(withReads, routeStagePaths);
+    }
     case "stage-signals" /* StageSignals */:
       return applyStageSignals(state, mutation);
     case "fields" /* Fields */:
@@ -2794,7 +2814,11 @@ function recordStageRead() {
   const readPaths = filePath ? [filePath].filter(isSkillTreeMarkdown) : isShellToolCall(input) ? detectShellStageReads(input.tool_input?.command ?? "", input.cwd) : [];
   if (readPaths.length === 0) return "{}";
   if (callFailed(input)) return "{}";
-  commitStateMutation(sessionId, { kind: "stage-reads" /* StageReads */, readPaths }, readState(sessionId));
+  commitStateMutation(
+    sessionId,
+    { kind: "stage-reads" /* StageReads */, readPaths, skillsRootDir: resolvePluginSkillsRoot() },
+    readState(sessionId)
+  );
   return "{}";
 }
 function recordStageSignals() {

package/plugin/skills/CLAUDE.md

@@ -36,6 +36,8 @@ Invoking the skill names those files as required reading, and a Stop gate holds
 
 The bar is "must be **read** before the skill runs", not "must be executed". A failure protocol qualifies: by the time a run fails, a skill that never read it is already improvising. What does not qualify is a file only one branch consults for its content — the gate cannot tell that the branch was not taken, so it would block work that legitimately never needed it. Aliases declare nothing; they invoke the canonical skill, which carries the declaration.
 
+A skill whose router sends runs down different routes declares per route. Its `SKILL.md` lists only what every run opens — the router — and each route's entry file carries its own `mandatoryStages` frontmatter, paths relative to that file. Opening the entry file while the skill runs adds its set; a `SKILL.md` declares only when invoked, never when read. A route lists only the files every run of that route opens, so a branch inside a route still stays out.
+
 ## Host compatibility
 
 Skills are written against Claude Code's tools and ship unchanged to Codex. [`_shared/host-tool-equivalents.md`](_shared/host-tool-equivalents.md) maps each Claude Code name a skill uses — `AskUserQuestion`, the `Skill` tool, `${CLAUDE_PLUGIN_ROOT}`, the PR watcher's monitor — to what plays its part in Codex. Every top-level `SKILL.md` links it right after its telemetry line, and the Codex SessionStart hook names it too.

package/plugin/skills/do/address-reviews.md

@@ -1,3 +1,9 @@
+---
+mandatoryStages:
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Address-Reviews Orchestrator
 
 The entry procedure for `/muggle-do`'s **address-reviews** mode — invoked by the watcher loop ([`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)) when new submitted reviews land on a PR. Orchestrates the cycle: read reviews → classify → execute work on actionables → escalate ambiguous → push and refresh PR → reply per comment → resolve-reminder → respawn watcher.

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

@@ -1,3 +1,10 @@
+---
+mandatoryStages:
+  - ../_shared/session-state-writes.md
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Fix-CI (watcher-dispatched)
 
 Resolve red CI on a PR's head — lint/format, typecheck, failing unit tests, and a red Muggle E2E walkthrough check — verifying green before re-push. A dumb-pipe dispatch like address-reviews: the executor receives a PR URL, slug, and the failing check names, and fixes them — it owns the fix, not the decision to dispatch.

package/plugin/skills/do/pre-flight.md

@@ -1,3 +1,14 @@
+---
+mandatoryStages:
+  - requirements.md
+  - build.md
+  - impact-analysis.md
+  - unit-tests.md
+  - e2e-acceptance.md
+  - open-prs/forward.md
+  - e2e-repair.md
+---
+
 # Pre-flight Agent (Stage 1)
 
 You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.

package/plugin/skills/do/resolve-conflicts.md

@@ -1,3 +1,10 @@
+---
+mandatoryStages:
+  - ../_shared/session-state-writes.md
+  - respawn-watcher.md
+  - ../_shared/telemetry-events/muggle-do-cycle.md
+---
+
 # Rebase (watcher-dispatched)
 
 Rebase a PR's branch onto its base — whether it's merely **behind** (out of date, no conflict) or actually **conflicting** — behind a verify-or-rollback gate, then force-push, so a PR doesn't sit stale or un-mergeable forever. A dumb-pipe dispatch like fix-ci: the watcher detects the branch is behind or conflicting and hands off; the executor owns the rebase (and any conflict resolution), never the decision to dispatch.

package/plugin/skills/muggle-do/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: muggle-do
 description: Take a feature request, spec, design, bug, or ticket and carry it autonomously to an opened pull request — write the code, test it, raise the PR. The PR carries real-browser proof: email-gated flows run through live test inboxes, logins through encrypted secrets, and prerequisite flows in test-graph order, with screenshots attached. Use whenever the user wants something built, implemented, added, or fixed with a PR opened, raised, or put up at the end — "implement rate limiting and raise a PR", "build the CSV export and put up a PR", "take this Jira ticket and run with it, ping me when the PR is up", "fix this bug and open a pr", or "muggle do …". Also handles the internal `address-reviews` directive the muggle-pr-followup watcher dispatches when new reviews land. Not for testing or validating existing changes (use muggle-test), nor watching a PR's incoming reviews (use muggle-pr-followup).
+mandatoryStages:
+  - ../do/input-routing.md
 ---
 
 # Muggle Test Do
@@ -42,7 +44,7 @@ The pipeline table lists **pointers, not summaries**. Open each stage's file and
 2. Create `~/.muggle-ai/muggle-do/sessions/<slug>/` with `state.md` + `iterations/001.md` (pre-flight owns this; do it even when running unattended).
 3. `TodoWrite` one item per stage 1–8, Stage 7.5 included — these stages are the checklist; never swap in your own decomposition. Several changes → one set of stage items per change.
 
-**Per stage:** read the file → execute it → append a marker to `iterations/<NNN>.md` citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
+**Per stage:** read the file → execute it → append one marker line to `iterations/<NNN>.md`, always in the form `Stage <N> done — <evidence>`, citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
 
 ### "Autonomous" / "without my intervention" collapses exactly one thing
 Best-effort the Stage-1 questionnaire and don't ask. It does **not** license skipping telemetry, session artifacts, requirements, unit tests, E2E (`autoE2ETest` defaults to `always`), browser verification, the gate below, the Stage-7.5 repair loop, or the watcher hand-off. Stage 7.5 investigates and repairs unattended too; only its user decision collapses, into an automatic waive. Run the whole pipeline silently — never a shortcut.
@@ -94,5 +96,6 @@ When invoked with the directive (PR URL + slug + review ids), routes to [`../do/
 
 - Stage 1 and Stage 7.5's user decision are the only user-facing forward stages. Stages 2–7 don't ask mid-cycle; blocker → pre-flight bug.
 - Same stage failing 3× → escalate.
+- Each route's entry file declares the stage files every run of that route opens, and a Stop gate holds the turn until they are read. A turn that ends before its route's last stage — a readiness halt, an escalation, a pause for a background run — records why with `echo "MUGGLE_STAGE_SKIP: <reason>"`.
 - 3 repair iterations reach E2E with failures → waive, ship with `[E2E FAILING]`, and hand to the watcher.
 - Address-reviews escalation (ambiguous or design-adjustment) does not block the watcher; user resolves on GitHub.