@muggleai/works 5.8.1 → 5.10.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-5PYK7DWB.js';
-import './chunk-LVUJ4E62.js';
+import { runCli } from './chunk-7NC2DJTK.js';
+import './chunk-OCLMXAVJ.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1,2 +1,2 @@
-export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-5PYK7DWB.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-LVUJ4E62.js';
+export { src_exports as commands, createUnifiedMcpServer, server_exports as server } from './chunk-7NC2DJTK.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-OCLMXAVJ.js';

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

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "5.8.1",
+  "version": "5.10.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

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

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "5.8.1",
+  "version": "5.10.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/README.md

@@ -21,19 +21,25 @@ This updates the CLI, configures Cursor MCP (`~/.cursor/mcp.json`), and syncs `m
 
 Type `muggle` to discover the full command family.
 
-| Skill | What it does |
-|:---|:---|
-| `/muggle:muggle` | Router and menu for all Muggle Test commands. |
-| `/muggle:muggle-do` | Autonomous dev pipeline: requirements, code, unit tests, E2E acceptance tests, PR. |
-| `/muggle:muggle-test` | Change-driven E2E acceptance router: detects code changes, maps to use cases, runs test generation locally or remotely, publishes to dashboard, opens in browser, posts E2E acceptance results to PR. |
-| `/muggle:muggle-test-feature-local` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
-| `/muggle:muggle-test-import` | Import existing tests into Muggle Test — from Playwright/Cypress specs, PRDs, Gherkin feature files, test plan docs, or any test artifact. |
-| `/muggle:muggle-test-regenerate-missing` | Bulk-regenerate test scripts for every test case in a project that doesn't currently have an active script. Scans DRAFT + GENERATION_PENDING, confirms the list with the user, and dispatches remote generation workflows for each. |
-| `/muggle:muggle-status` | Health check for Electron browser test runner, MCP server, and authentication. |
-| `/muggle:muggle-repair` | Diagnose and fix broken installation automatically. |
-| `/muggle:muggle-upgrade` | Update Electron browser test runner and MCP server to latest version. |
-
-Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
+| Skill | Shorthand | What it does |
+|:---|:---|:---|
+| `/muggle:muggle` | `/m` | Router and menu for all Muggle Test commands. |
+| `/muggle:muggle-do` | `/mdo` | Autonomous dev pipeline: requirements, code, unit tests, E2E acceptance tests, PR. |
+| `/muggle:muggle-test` | `/mtest` | Change-driven E2E acceptance router: detects code changes, maps to use cases, runs test generation locally or remotely, publishes to dashboard, opens in browser, posts E2E acceptance results to PR. |
+| `/muggle:muggle-test-feature-local` | `/mtestlocal` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
+| `/muggle:muggle-test-prepare` | `/mtestprep` | Verify the dev servers and sibling services a test run needs, and start whatever is missing. |
+| `/muggle:muggle-test-import` | `/mimport` | Import existing tests into Muggle Test — from Playwright/Cypress specs, PRDs, Gherkin feature files, test plan docs, or any test artifact. |
+| `/muggle:muggle-test-regenerate-missing` | `/mregen` | Bulk-regenerate test scripts for every test case in a project that doesn't currently have an active script. Scans DRAFT + GENERATION_PENDING, confirms the list with the user, and dispatches remote generation workflows for each. |
+| `/muggle:muggle-browser-task` | `/mbt` | Perform a real action on a website from plain English — log in and submit the form, create the ticket, refund the charge. |
+| `/muggle:muggle-pr-visual-walkthrough` | `/mpr` | Post per-test-case dashboard links, step-by-step screenshots, and a pass/fail summary to a PR. |
+| `/muggle:muggle-pr-followup` | `/mprfollowup` | Watch one PR's review thread and dispatch the work to address incoming feedback. |
+| `/muggle:muggle-feedback` | `/mfeedback` | Flag a generated action script, or one step in it, as wrong so Muggle can analyze and regenerate affected scripts. |
+| `/muggle:muggle-preferences` | `/mprefs` | View, set, or reset the preferences that gate Muggle Test behavior. |
+| `/muggle:muggle-status` | `/mstatus` | Health check for Electron browser test runner, MCP server, and authentication. |
+| `/muggle:muggle-repair` | `/mrepair` | Diagnose and fix broken installation automatically. |
+| `/muggle:muggle-upgrade` | `/mupgrade` | Update Electron browser test runner and MCP server to latest version. |
+
+Every skill ships the short alias in the table above. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`). Claude Code namespaces plugin commands, so the aliases resolve as `/muggle:mtest`; mirror them into `~/.claude/commands/` to type `/mtest` bare.
 
 ## MCP Tools
 

package/dist/plugin/agents/test-prepare-runner.md

@@ -16,6 +16,7 @@ The dispatch prompt carries the resolved prepare plan:
 - `testingScope` and `excludedServices[]` (with reasons).
 - The recorded dev-server URL (from the `autoSelectLocalHost` resolution) — never invent or default a host/port; a framework default like `:3000` is not a fallback.
 - Resolved gate values the stages read (`autoRebase` outcome already applied or explicitly skipped upstream).
+- The E2E run instructions — startup order, manual steps, local gotchas — already captured from the user. Honour the recorded startup order when starting services, and write the instructions out per the readiness-report stage. Absent means the skill had nothing to record; never invent them.
 
 ## Stages
 

package/dist/plugin/hooks/hooks.json

@@ -110,6 +110,12 @@
             "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-terminal-gate.sh\"",
             "async": false,
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/guardrail-watch-gate.sh\"",
+            "async": false,
+            "timeout": 10
           }
         ]
       }

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -110,6 +110,10 @@ version_check() {
 version_check || true
 
 # --- Preferences injection ---
+# Preferences are user-level: defaults overlaid by the global file only. A legacy
+# <cwd>/.muggle-ai/preferences.json is left on disk but no longer read, so the
+# keys it can no longer apply are named once — the stamp file suppresses the
+# repeat until that key set changes.
 prefs_global_file="${HOME}/.muggle-ai/preferences.json"
 prefs_line=""
 prefs_file_note=""
@@ -119,8 +123,13 @@ if [ -f "$prefs_global_file" ]; then
   # Uses node for reliable JSON parsing (already required for muggle).
   prefs_line=$(node -e "
     const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
     try {
-      const g = JSON.parse(fs.readFileSync('${prefs_global_file}', 'utf-8')).preferences || {};
+      // Resolved through node, not the shell's \$HOME: under Git Bash the shell
+      // reports a POSIX path that Windows node cannot open.
+      const globalFile = path.join(os.homedir(), '.muggle-ai', 'preferences.json');
+      const g = JSON.parse(fs.readFileSync(globalFile, 'utf-8')).preferences || {};
       const defaults = {
         autoLogin:'ask', autoSelectProject:'ask', autoSelectLocalHost:'ask',
         showElectronBrowser:'ask', openTestResultsAfterRun:'ask',
@@ -131,15 +140,30 @@ if [ -f "$prefs_global_file" ]; then
         autoUseWorktree:'ask', autoRebase:'ask', autoCleanup:'ask',
         autoE2ETest:'always', autoRouteBuildToMuggleDo:'ask'
       };
+      const resolved = { ...defaults, ...g };
+      const line = Object.entries(resolved).map(([k,v]) => k+'='+v).join(' ');
+      const blocks = ['Muggle Test Preferences (~/.muggle-ai/preferences.json):\\\\n' + line];
+
       const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-      const pPath = require('path').join(cwd, '.muggle-ai', 'preferences.json');
+      const pPath = path.join(cwd, '.muggle-ai', 'preferences.json');
       let p = {};
       try { p = JSON.parse(fs.readFileSync(pPath, 'utf-8')).preferences || {}; } catch {}
-      const merged = { ...defaults, ...g, ...p };
-      const hasProject = Object.keys(p).length > 0;
-      const note = hasProject ? ', project overrides active' : '';
-      const line = Object.entries(merged).map(([k,v]) => k+'='+v).join(' ');
-      console.log('Muggle Test Preferences (~/.muggle-ai/preferences.json' + note + '):\\\\n' + line);
+      const inertKeys = Object.keys(p).filter((k) => p[k] !== resolved[k]).sort();
+      if (inertKeys.length > 0) {
+        const stampDir = path.join(os.homedir(), '.cache', 'muggle');
+        const stampFile = path.join(stampDir, 'project-prefs-inert');
+        const stamp = cwd + '|' + inertKeys.join(',');
+        let lastStamp = '';
+        try { lastStamp = fs.readFileSync(stampFile, 'utf-8'); } catch {}
+        if (lastStamp !== stamp) {
+          try { fs.mkdirSync(stampDir, { recursive: true }); fs.writeFileSync(stampFile, stamp); } catch {}
+          blocks.push(
+            'Muggle Test: per-project preferences were removed — ' + pPath + ' is no longer read, so these keys no longer take effect: ' + inertKeys.join(', ') + '.\\\\n' +
+            'Tell the user to re-apply any they want everywhere with \`/muggle-preferences\`; the file is safe to delete.'
+          );
+        }
+      }
+      console.log(blocks.join('\\\\n\\\\n'));
     } catch { console.log(''); }
   " 2>/dev/null || true)
   if [ -n "$prefs_line" ]; then
@@ -149,53 +173,44 @@ else
   prefs_file_note="\\n\\nMuggle Test Preferences: not configured. Run \\\`muggle setup\\\` or tell the agent to set preferences."
 fi
 
-# --- Last-project cache injection ---
-# Per-repo "last used Muggle Test project" cache. Lives at <cwd>/.muggle-ai/last-project.json
-# and is honored by skills when autoSelectProject = always.
-last_project_line=""
-last_project_note=""
-last_project_line=$(node -e "
-  const fs = require('fs');
-  const path = require('path');
-  try {
-    const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-    const lpPath = path.join(cwd, '.muggle-ai', 'last-project.json');
-    if (!fs.existsSync(lpPath)) { console.log(''); return; }
-    const raw = JSON.parse(fs.readFileSync(lpPath, 'utf-8'));
-    const lp = raw && raw.lastProject;
-    if (!lp || !lp.projectId) { console.log(''); return; }
-    const safeName = String(lp.projectName || '').replace(/\"/g, '\\\\\"');
-    console.log('Muggle Test Last Project: id=' + lp.projectId + ' url=' + lp.projectUrl + ' name=\"' + safeName + '\"');
-  } catch { console.log(''); }
-" 2>/dev/null || true)
-if [ -n "$last_project_line" ]; then
-  last_project_note="\\n\\n${last_project_line}"
-fi
-
-# --- Last-host cache injection ---
-# Per-repo cache of the local dev server URL the user picked on the previous
-# run. Lives at <cwd>/.muggle-ai/last-host.json. Skills silently reuse it
-# when the user has set the autoSelectLocalHost preference to "always".
-last_host_line=""
-last_host_note=""
-last_host_line=$(node -e "
+# --- Last-used cache injection ---
+# The "last used Muggle Test project" and "last used local dev server URL"
+# caches live in ~/.muggle-ai/, keyed by working directory, and are honored by
+# skills when autoSelectProject / autoSelectLocalHost = always. A cache written
+# before the move to the home directory still sits in <cwd>/.muggle-ai/ and is
+# read as a fallback, so those sessions keep their context lines.
+last_cache_notes=""
+last_cache_notes=$(node -e "
   const fs = require('fs');
+  const os = require('os');
   const path = require('path');
   try {
     const cwd = process.env.CLAUDE_CWD || process.env.CURSOR_CWD || process.cwd();
-    const lhPath = path.join(cwd, '.muggle-ai', 'last-host.json');
-    if (!fs.existsSync(lhPath)) { console.log(''); return; }
-    const raw = JSON.parse(fs.readFileSync(lhPath, 'utf-8'));
-    const lh = raw && raw.lastHost;
-    if (!lh || !lh.host) { console.log(''); return; }
-    console.log('Muggle Test Last Host: ' + lh.host);
+    const parseFile = (filePath) => {
+      try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); } catch { return null; }
+    };
+    const readEntry = (fileName, legacyEntryKey) => {
+      const home = parseFile(path.join(os.homedir(), '.muggle-ai', fileName));
+      const homeEntry = home && home.entries && home.entries[path.resolve(cwd)];
+      if (homeEntry) { return homeEntry; }
+      const legacy = parseFile(path.join(cwd, '.muggle-ai', fileName));
+      return (legacy && legacy[legacyEntryKey]) || null;
+    };
+    const lines = [];
+    const lastProject = readEntry('last-project.json', 'lastProject');
+    if (lastProject && lastProject.projectId) {
+      const safeName = String(lastProject.projectName || '').replace(/\"/g, '\\\\\"');
+      lines.push('Muggle Test Last Project: id=' + lastProject.projectId + ' url=' + lastProject.projectUrl + ' name=\"' + safeName + '\"');
+    }
+    const lastHost = readEntry('last-host.json', 'lastHost');
+    if (lastHost && lastHost.host) {
+      lines.push('Muggle Test Last Host: ' + lastHost.host);
+    }
+    console.log(lines.map((line) => '\\\\n\\\\n' + line).join(''));
   } catch { console.log(''); }
 " 2>/dev/null || true)
-if [ -n "$last_host_line" ]; then
-  last_host_note="\\n\\n${last_host_line}"
-fi
 
-context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle Test launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}${last_project_note}${last_host_note}"
+context="<EXTREMELY_IMPORTANT>\nYou have access to Muggle AI — a real-browser E2E acceptance testing tool.\n\nWhenever the user asks you to test, validate, verify, or check if their web app works — use the muggle MCP tools. This includes:\n- Testing user flows (signup, login, checkout, forms, dashboards)\n- Verifying UI changes didn't break anything\n- Running regression tests after code changes\n- Validating frontend behavior on localhost or a dev server\n- Checking if a feature works before merging a PR\n\nMuggle Test launches a real Electron browser that clicks buttons, fills forms, navigates pages, and captures screenshots. It generates replayable test scripts that persist across sessions.\n\nDo NOT write test code (Playwright, Cypress, Selenium) or try to test UI manually when muggle tools are available. Use the muggle skill or muggle MCP tools instead — they are faster, capture visual evidence, and produce reusable test scripts.\n\nTrigger phrases: 'test my app', 'check if it works', 'run E2E acceptance tests', 'validate the UI', 'verify the flow', 'regression test', 'make sure it still works', 'test before merging'.\n</EXTREMELY_IMPORTANT>${upgrade_notice}${prefs_file_note}${last_cache_notes}"
 
 escaped_context=$(escape_for_json "$context")
 

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# watcher-arm gate (Stop). When a PR was opened this session but no watcher was
+# armed for it, block the turn end and point at the Stage-8 hand-off (or the
+# MUGGLE_WATCH_SKIP escape hatch). Mirrors guardrail-e2e-gate.sh: synchronous
+# (only a sync Stop hook can block the turn end), fires on EVERY turn end, and
+# pre-filters in shell so Node spawns only when a PR was opened this session and
+# no skip was recorded. The real owed-vs-armed decision (a sessions/*/ slot scan)
+# runs in guardrails.mjs. On the overwhelming majority of turns no PR was opened,
+# so the state file is absent or prsHandled is empty and we return {} in-shell,
+# never paying Node cold-start. Degrades to {}.
+payload="$(cat)"
+
+raw_sid="$(printf '%s' "$payload" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"([^"]*)".*/\1/')"
+[ -n "$raw_sid" ] || raw_sid="unknown"
+sid="$(printf '%s' "$raw_sid" | sed 's/[^A-Za-z0-9_-]/_/g')"
+
+# Resolve the same home dir Node's os.homedir() uses. HOME is correct on
+# macOS/Linux and on most Git Bash setups; fall back to converting USERPROFILE
+# when HOME doesn't hold the state dir (some Windows shells point HOME elsewhere).
+home="${HOME:-}"
+if [ ! -d "$home/.muggle-ai" ] && command -v cygpath >/dev/null 2>&1 && [ -n "${USERPROFILE:-}" ]; then
+  home="$(cygpath -u "$USERPROFILE" 2>/dev/null || printf '%s' "$home")"
+fi
+
+# Empty array serializes as `"prsHandled": []` (one line); a non-empty array spans
+# lines, so the empty match reliably tells them apart. Skip Node unless a PR was
+# opened this session and no watcher skip was recorded.
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"prsHandled"' "$state_file" \
+  || grep -q '"prsHandled": \[\]' "$state_file" \
+  || grep -q '"watchSkipped": true' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" watch-gate 2>/dev/null || printf '{}'

package/dist/plugin/scripts/guardrails.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
 import { isAbsolute, resolve, join } from 'path';
 import { homedir } from 'os';
 
@@ -43,8 +43,10 @@ ${input2.tool_response?.output ?? ""}`;
 // src/guardrails/constants.ts
 var GH_PR_MERGED_LINE = /\b(?:Merged|Squashed and merged|Rebased and merged) pull request [\w./-]*#(\d+)/;
 var GH_PR_CLOSED_LINE = /\bClosed pull request [\w./-]*#(\d+)/;
+var GH_PR_REOPENED_LINE = /\bReopened pull request [\w./-]*#(\d+)/;
 var PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
 var MAX_PR_TERMINAL_BLOCKS = 3;
+var MAX_WATCH_BLOCKS = 3;
 var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
 var MUGGLE_TEST_SKILL_NAME = "muggle-test";
 
@@ -70,6 +72,23 @@ function detectPrTerminal(input2) {
   }
   return null;
 }
+function detectPrReopened(input2) {
+  if (input2.tool_name !== "Bash") return null;
+  const response = input2.tool_response;
+  const haystack = [response?.stdout, response?.stderr, response?.output, response?.content].filter((part) => typeof part === "string").join("\n");
+  const reopenedMatch = haystack.match(GH_PR_REOPENED_LINE);
+  return reopenedMatch ? Number(reopenedMatch[1]) : null;
+}
+function applyPrReopened(state, prNumber) {
+  const pending = state.terminalPending ?? [];
+  const handled = state.terminalHandled ?? [];
+  if (!pending.includes(prNumber) && !handled.includes(prNumber)) return state;
+  return {
+    ...state,
+    terminalPending: pending.filter((number) => number !== prNumber),
+    terminalHandled: handled.filter((number) => number !== prNumber)
+  };
+}
 function applyPrTerminalDetected(state, prNumber) {
   const pending = state.terminalPending ?? [];
   const handled = state.terminalHandled ?? [];
@@ -143,6 +162,48 @@ function e2eGateDecision(state, maxBlocks = MAX_E2E_BLOCKS) {
   if (blockCount >= maxBlocks) return { action: "release" /* Release */, blockCount };
   return { action: "block" /* Block */, blockCount: blockCount + 1 };
 }
+var WATCH_SKIP_MARKER = /^\s*echo\s+["']?MUGGLE_WATCH_SKIP\b/;
+function isWatchSkipMarker(cmd) {
+  return WATCH_SKIP_MARKER.test(cmd);
+}
+function applyWatchSkip(state, skipped) {
+  if (!skipped || state.watchSkipped === true) return state;
+  return { ...state, watchSkipped: true };
+}
+function findUntrackedHandledPrs(handledUrls, sessionsDirOverride) {
+  if (handledUrls.length === 0) return [];
+  const sessionsDir = join(homedir(), ".muggle-ai", "muggle-do", "sessions");
+  if (!existsSync(sessionsDir)) return [...handledUrls];
+  const trackedUrls = /* @__PURE__ */ new Set();
+  for (const slug of readdirSync(sessionsDir)) {
+    const prsFile = join(sessionsDir, slug, "prs.json");
+    if (!existsSync(prsFile)) continue;
+    let slotUrl;
+    try {
+      const parsed = JSON.parse(readFileSync(prsFile, "utf-8"));
+      const entry = Array.isArray(parsed) ? parsed[0] : parsed;
+      slotUrl = entry?.url;
+    } catch {
+      continue;
+    }
+    if (slotUrl) trackedUrls.add(slotUrl);
+  }
+  return handledUrls.filter((url) => !trackedUrls.has(url));
+}
+function watchGateDecision(state, untrackedPrUrls, maxBlocks = MAX_WATCH_BLOCKS) {
+  const blockCount = state.watchBlockCount ?? 0;
+  if (state.watchSkipped === true || untrackedPrUrls.length === 0) {
+    return { action: "none" /* None */, blockCount, untracked: untrackedPrUrls };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount, untracked: untrackedPrUrls };
+  }
+  return {
+    action: "block" /* Block */,
+    blockCount: blockCount + 1,
+    untracked: untrackedPrUrls
+  };
+}
 
 // src/guardrails/detectBuildIntent.ts
 var BUILD = /\b(implement|build|add|create|write|fix|refactor|wire up|hook up|make (a|the|it)|change the)\b/i;
@@ -256,6 +317,13 @@ Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its i
   return envelope("PostToolUse", ctx, host);
 }
 function prTerminal() {
+  const reopenedPrNumber = detectPrReopened(input);
+  if (reopenedPrNumber !== null) {
+    const state2 = readState(sessionId);
+    const next2 = applyPrReopened(state2, reopenedPrNumber);
+    if (next2 !== state2) writeState(next2);
+    return "{}";
+  }
   const terminalEvent = detectPrTerminal(input);
   if (!terminalEvent) return "{}";
   const state = readState(sessionId);
@@ -285,11 +353,12 @@ function terminalGate() {
 function recordTests() {
   const cmd = input.tool_input?.command ?? "";
   const state = readState(sessionId);
-  const next = applyRecordedRun(state, {
+  const recorded = applyRecordedRun(state, {
     unitTestPassed: isTestCommand(cmd) && testsPassed(input),
     e2eRan: isE2ERun(input),
     e2eSkipped: isE2ESkipMarker(cmd)
   });
+  const next = applyWatchSkip(recorded, isWatchSkipMarker(cmd));
   if (next !== state) writeState(next);
   return "{}";
 }
@@ -302,10 +371,23 @@ function e2eGate() {
   const reason = decision.blockCount === 1 ? `Do not end the turn yet. Unit tests passed this session but no E2E acceptance run has happened. Per the autoE2ETest preference (default: always), run change-driven E2E now via /muggle:muggle-test, then finish. If E2E genuinely cannot run here (no app to drive, services down, no PR), tell the user why and run \`echo "MUGGLE_E2E_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `E2E acceptance run still owed (reminder ${decision.blockCount}/${MAX_E2E_BLOCKS}): run /muggle:muggle-test, or record a legitimate skip via \`echo "MUGGLE_E2E_SKIP: <reason>"\`.`;
   return blockStop(reason, host);
 }
+function watchGate() {
+  const state = readState(sessionId);
+  const untrackedPrUrls = findUntrackedHandledPrs(state.prsHandled);
+  const decision = watchGateDecision(state, untrackedPrUrls);
+  if (decision.action === "none" /* None */ || decision.action === "release" /* Release */) {
+    return "{}";
+  }
+  state.watchBlockCount = decision.blockCount;
+  writeState(state);
+  const prList = decision.untracked.join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. A PR was opened this session but no muggle-do session slot tracks it: ${prList}. Seed the slot and hand off per muggle-do Stage 8 \u2014 /muggle:muggle-pr-followup ${decision.untracked[0]} does both. Seeding is what matters: once a slot exists, reconcile arms it at the next session start and finalizes it when the PR goes terminal, so an unarmed slot is fine but no slot means nothing ever picks this PR up. If it genuinely should not be tracked (autoWatchPR=never, handed off elsewhere), tell the user why and run \`echo "MUGGLE_WATCH_SKIP: <reason>"\` \u2014 that records the skip and keeps this gate quiet for the rest of the session.` : `PR hand-off still owed for ${prList} (reminder ${decision.blockCount}/${MAX_WATCH_BLOCKS}): seed a slot via /muggle:muggle-pr-followup, or record a legitimate skip via \`echo "MUGGLE_WATCH_SKIP: <reason>"\`.`;
+  return blockStop(reason, host);
+}
 function reportGate() {
-  const result = evaluateReportPost(input);
-  if (!result.deny || !result.reason) return "{}";
-  return denyTool(result.reason, host);
+  const reportPostVerdict = evaluateReportPost(input);
+  if (!reportPostVerdict.deny || !reportPostVerdict.reason) return "{}";
+  return denyTool(reportPostVerdict.reason, host);
 }
 function buildRouter() {
   if (!detectBuildIntent(input.prompt ?? "")) return "{}";
@@ -323,6 +405,7 @@ var handlers = {
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
   "terminal-gate": terminalGate,
+  "watch-gate": watchGate,
   "report-gate": reportGate,
   "build-router": buildRouter
 };

package/dist/plugin/scripts/pr-watch-guards.sh

@@ -20,6 +20,23 @@
 
 MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-21600}"
 MUGGLE_PR_WATCH_POLL_INTERVAL="${MUGGLE_PR_WATCH_POLL_INTERVAL:-60}"
+# Consecutive failed fetches before a loop gives up. A watcher must ride through
+# a GitHub / network outage — an observed drop lasted ~8 minutes — not die and
+# leave the PR unwatched until the next session start. With the backoff below, 60
+# spans hours; only a genuinely persistent unreachable slot (deleted repo,
+# revoked auth) exhausts it.
+MUGGLE_PR_WATCH_MAX_FETCH_FAILURES="${MUGGLE_PR_WATCH_MAX_FETCH_FAILURES:-60}"
+
+# Seconds to sleep after `fails` consecutive failed fetches: the poll interval,
+# then a linear back-off capped at 5 minutes so a sustained outage is retried
+# calmly rather than hammered every 60s.
+watcher_fetch_backoff() {
+    local fails="$1" base="${MUGGLE_PR_WATCH_POLL_INTERVAL}" step secs
+    step=$((fails * 30))
+    secs=$((base + step))
+    [ "$secs" -gt 300 ] && secs=300
+    echo "$secs"
+}
 
 # True when watch.pid exists and names a PID other than this loop's — a newer arm
 # has taken ownership of the slot. Absent/empty watch.pid is not superseded: a

package/dist/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -25,6 +25,7 @@ Resolve without prompting; use as questionnaire defaults:
 3. Candidate projects — `muggle-remote-project-list`, ranked against the repo's dev URL and the PR title.
 4. Existing test-user secrets — `muggle-remote-secret-list` per candidate project (`managed_profile_email` / `managed_profile_password`).
 5. Auth0 tenant for local dev — grep the repo env file for `*AUTH0_DOMAIN*`.
+6. E2E run instructions — read `~/.muggle-ai/e2e-instructions/<key>.md` when it exists, keyed on this stack's identity. It records startup order, manual steps, and local gotchas. Treat it as read-only input: surface its gotchas rather than re-deriving them, and never re-ask what it already answers. Absent is normal — proceed without it.
 
 ## Questions
 

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

@@ -12,7 +12,7 @@ Use this as the top-level Muggle Test command router.
 
 ## Preferences
 
-User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json` (global) → `<repo>/.muggle-ai/preferences.json` (project). Treat absent prefs as `ask`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json`. Preferences are user-level and apply to every repo. Treat absent prefs as `ask`.
 
 This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 

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

@@ -3,10 +3,10 @@
 How an orchestrating session starts the watch on one PR. Every arming point runs this same sequence: [`bootstrap.md`](bootstrap.md) Step 8, [`auto-track.md`](auto-track.md) Step 6, and the executor's post-cycle settle.
 
 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.** 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 monitor's first iteration surfaces it. Seed the CI floor (`CIRED`) from the same drain read: set it to the head SHA 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)) — that red is what the drain just handled — and empty otherwise, so an escalated red head the drain already saw does not re-fire on the loop's first iteration.
+2. **Seed the watermark.** 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 monitor's first iteration surfaces it. Seed the CI floor (`CIRED`) from the same drain read: set it to the head SHA 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)) — that red is what the drain just handled — and empty otherwise, so an escalated red head the drain already saw does not re-fire on the loop's first iteration. 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): set it to the current `rebase_key` (`<head_sha>..<base_tip_sha>`) when the drain found the branch already behind or conflicting — that staleness is what the drain just handled — and empty otherwise, so a branch the drain already rebased or escalated does not re-fire on the loop's first iteration. 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.
 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), a watcher already owns this slot — **skip arming, do not start a second**. This is what stops orphaned watchers from accumulating: the in-session monitor 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.
 
-   Otherwise write the loop as `watch.sh` in the slot and start it as a **persistent background monitor** in the orchestrating session — the command is the one-line script path, and the label is `PR #<n> — <title>`. Both matter: some task surfaces show the label, others show the command, and a slot-path command keeps the watch identifiable everywhere a raw script blob would not. One monitor per PR, alive from arm to terminal: it is the watch's visible handle, showing as a running task the entire time the PR is polled. 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), or **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) — it prints one line and **keeps watching**, advancing its in-memory floor so each event fires the tick exactly once. The review and thread floors are monotonic ids; the CI 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. A head whose checks are still **pending** is never a wake: pending checks may yet go green, and the tick would idle on them (Step 6) regardless. Quiet iterations print nothing and cost nothing — no model tokens are spent while the watch is quiet.
+   Otherwise write the loop as `watch.sh` in the slot and start it as a **persistent background monitor** in the orchestrating session — the command is the one-line script path, and the label is `PR #<n> — <title>`. Both matter: some task surfaces show the label, others show the command, and a slot-path command keeps the watch identifiable everywhere a raw script blob would not. One monitor per PR, alive from arm to terminal: it is the watch's visible handle, showing as a running task the entire time the PR is polled. 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 and **keeps watching**, advancing its in-memory floor so each event fires the tick exactly once. 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 loop is **self-terminating**, so it never becomes one of those orphans. It begins by sourcing the shipped guard library and claiming the slot, with the guard path resolved to an **absolute** path at arm time (from `${CLAUDE_PLUGIN_ROOT}/scripts/pr-watch-guards.sh`) so it still resolves after the arming session is gone:
 
@@ -17,6 +17,8 @@ How an orchestrating session starts the watch on one PR. Every arming point runs
    started=$(date +%s)
    ```
 
+   A failed fetch — a GitHub or network outage, which reaches the loop as an empty result and a `dial tcp … / error connecting to api.github.com` line — must not be mistaken for a terminal PR: the loop counts it toward `MUGGLE_PR_WATCH_MAX_FETCH_FAILURES` (60), sleeping `watcher_fetch_backoff "$fails"` between tries so a sustained outage is retried calmly, and appends the error to `<slot>/watch-fetch.log`. 60 backed-off failures span hours; only a genuinely persistent unreachable slot (deleted repo, revoked auth) exhausts the budget, and a successful fetch resets the counter. Terminal exit stays reserved for an observed `MERGED`/`CLOSED`.
+
    and the top of every iteration, before any `gh` call, checks the two guards from [`../../scripts/pr-watch-guards.sh`](../../scripts/pr-watch-guards.sh):
 
    ```sh
@@ -24,7 +26,7 @@ How an orchestrating session starts the watch on one PR. Every arming point runs
    watcher_lifetime_exceeded "$started" "$(date +%s)" && exit 0   # 6h cap → any orphan dies on its own; reconcile re-arms an open PR in a live session
    ```
 
-   So it exits when the PR goes terminal, after five consecutive failed fetches, when a newer arm supersedes it, or once it passes the lifetime cap — never `while true` unbounded.
+   So it exits when the PR goes terminal, after `MUGGLE_PR_WATCH_MAX_FETCH_FAILURES` consecutive failed fetches (default 60, back-off between each — hours of outage tolerance), when a newer arm supersedes it, or once it passes the lifetime cap — never `while true` unbounded.
 4. **On event.** Polling never enters the session: the cadence lives entirely in the detached monitor loop (step 3), and the only thing the session ever receives is the monitor's one event line. That line wakes the session: the wake turn runs the tick (step 1) with `--wake=<event>` — the flag that tells routing's live-watcher gate this poll was prompted, not idle curiosity ([`SKILL.md`](SKILL.md#routing)) — and whatever cycle the tick produces runs **inline in the owning session** — never in a subagent. The session's full history is part of the cycle's context (decisions, review nuance, owner phrasing); a subagent only knows its briefing plus disk/provider state, and anything the briefing omits is silently missing from the cycle. The token cost of inline cycles is accepted — context beats cost. The tick still derives everything from live provider state; a terminal PR finalizes there while the monitor exits on its own. Persistent fetch failure → surface the reason; [`reconcile.md`](reconcile.md) re-arms the slot at the next session start.
 
 **After a cycle** — advance the watermark to the **handled wave's snapshot**, in the same dispatched context that ran the cycle. Capture the max review-id and comment-id **at the start of handling** — the ids the cycle actually read when it derived the wave, before any reply is posted — and advance the watermark to exactly those. **Never** re-derive it from a live-max fetched after the replies land: a reviewer comment that arrives during the handling window — between reading the wave and posting the replies — lands below that post-reply max and is marked seen without ever being read. Snapshotting at the start-of-handling read keeps such a comment above the watermark, so the next tick surfaces it. That advance is also what stops the loop from reporting its own reply; a cycle that skips it leaves the watermark stale, and the next event is an echo.

package/dist/plugin/skills/muggle-pr-followup/blocked-tick.md

@@ -19,7 +19,7 @@ Any component moving means the block may have cleared — a new push (`head_sha`
 When an idle tick is a durable human-block and `last_seen.blocked` is not already set:
 
 1. Increment `last_seen.idle_tick_count`.
-2. Write `last_seen.blocked = { reason, since: <now>, fingerprint }` (reuse the `latest_review_id` / `ci_digest` already fetched this tick).
+2. Write `last_seen.blocked = { reason, since: <now>, fingerprint }` (reuse the `latest_review_id` / `ci_digest` already fetched this tick). Mirror the fingerprint's `ci_digest` into the watch-watermark's `BLOCKED_CIDIGEST` ([`state-schemas.md`](state-schemas.md#watch-watermarkenv)) — a whole-file rewrite of `watch-watermark.env` that leaves the other floors untouched. That non-empty value is what arms the monitor's blocked-resume probe, so a block resumes on any CI move ([`arm-watcher.md`](arm-watcher.md)), not just red — without it the probe stays dormant.
 3. **Remind the owner** — emit the one-line reminder per [`output-templates/blocked-reminder.md`](output-templates/blocked-reminder.md): the pending act plus a reference back to the decision context. This is the block's **only** reminder.
 4. Append a `blocked reason=<reason>` line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md); emit a `tick` event with `idle: true`, `blocked: true`, and the same other fields as a transient idle. Exit.
 
@@ -28,7 +28,7 @@ When an idle tick is a durable human-block and `last_seen.blocked` is not alread
 Every subsequent tick while `last_seen.blocked` is present: recompute the fingerprint and compare to `last_seen.blocked.fingerprint`.
 
 - **Unchanged** → still blocked. Stay **silent** — the reminder went out when the block was flagged. Increment `last_seen.idle_tick_count`, append a `blocked reason=<reason>` line to `followup.log`, emit a `tick` event with `idle: true`, `blocked: true`. Exit.
-- **Changed** → clear `last_seen.blocked` and **fall through to [`contract.md`](contract.md) Step 3** to re-evaluate against the moved state this same tick: a dispatch hands the PR to the cycle (its exit settles the watch); a transient idle changes nothing; idling back into a block re-flags per Step 7 — a new block, which sends its own single reminder.
+- **Changed** → clear `last_seen.blocked`, clear the watch-watermark's `BLOCKED_CIDIGEST` to empty (whole-file rewrite — disarms the monitor's blocked-resume probe now that the watch is unblocked), and **fall through to [`contract.md`](contract.md) Step 3** to re-evaluate against the moved state this same tick: a dispatch hands the PR to the cycle (its exit settles the watch); a transient idle changes nothing; idling back into a block re-flags per Step 7 — a new block, which sends its own single reminder (and re-arms `BLOCKED_CIDIGEST` afresh).
 
 ## Invariants
 

package/dist/plugin/skills/muggle-pr-followup/cancel-cron.md

@@ -6,7 +6,9 @@ Deletes this slot's watcher cron, and nothing more — the caller owns whatever
 
 Two lookups, recorded-id first so the delete still works when `CronList` has gone blind to the cron (survived a session continue / compaction — see [`state-schemas.md`](state-schemas.md#cronjson)):
 
-1. **By recorded id.** Read `cron.json` ([`state-schemas.md`](state-schemas.md#cronjson)). If `cron_id` is non-null, call `CronDelete` with it. This is the only handle that survives `CronList` blindness.
-2. **By `CronList` match (fallback).** Call `CronList`, find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` — the exact two-arg match for this slot's PR — and `CronDelete` its id. This catches a stale recorded id (a since-respawned cron whose new id no tick has recorded yet) and the case where `cron.json` is absent.
+1. **By recorded id.** Read `cron.json` ([`state-schemas.md`](state-schemas.md#cronjson)). If `cron_id` is non-null, call `CronDelete` with it. This is the only handle that survives `CronList` blindness. It **finds** a cron when the id names a live scheduled cron the delete removes; a `cron_id` that is null or already gone is a harmless no-op that finds nothing.
+2. **By `CronList` match (fallback).** Call `CronList`, find the job whose command ends with `/muggle:muggle-pr-followup <slug> <n>` — the exact two-arg match for this slot's PR — and `CronDelete` its id. This catches a stale recorded id (a since-respawned cron whose new id no tick has recorded yet) and the case where `cron.json` is absent. It **finds** a cron when the match surfaces a live job to delete; an empty `CronList` (already blind) or no matching job finds nothing.
 
-Both lookups are no-ops when nothing matches — a manually-run tick, or a cron that already expired. Deleting an already-gone id is harmless. Do **not** delete `cron.json` itself here; a terminal slot keeps it as a record, and reconcile ([`reconcile.md`](reconcile.md)) may still read it to sweep a straggler.
+**Reported result — `found` or `not-found`.** cancel-cron reports **found** when either lookup located and cancelled a live cron: the cron was reachable in this runtime, so any stale fires that follow are just the finite queued-drain backlog emptying. It reports **not-found** when both lookups found nothing to cancel. A **not-found** that keeps recurring — the cron fires again yet no cancel can reach it — is the orphan signal the stale-fire guard keys on ([`contract.md`](contract.md) Step 0). Callers that only tear down (finalize [`finalize.md`](finalize.md), the single-thread stops in [`contract.md`](contract.md) Steps 4–6) do not branch on the result; only Step 0's orphan gate consults it. Deleting an already-gone id is harmless either way.
+
+Do **not** delete `cron.json` itself here; a terminal slot keeps it as a record, and reconcile ([`reconcile.md`](reconcile.md)) may still read it to sweep a straggler.