@muggleai/works 5.6.0 → 5.8.0

package/plugin/scripts/guard-run.mjs

@@ -0,0 +1,327 @@
+import { spawn, spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { extname, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// src/guard-run/cli.ts
+
+// src/guard-run/buildLaunchPlan.ts
+function quoteWindowsArgument(argument) {
+  if (argument !== "" && !/[ \t"]/.test(argument)) return argument;
+  let quoted = '"';
+  let backslashCount = 0;
+  for (const character of argument) {
+    if (character === "\\") {
+      backslashCount += 1;
+      continue;
+    }
+    if (character === '"') {
+      quoted += "\\".repeat(backslashCount * 2 + 1) + '"';
+      backslashCount = 0;
+      continue;
+    }
+    quoted += "\\".repeat(backslashCount) + character;
+    backslashCount = 0;
+  }
+  return quoted + "\\".repeat(backslashCount * 2) + '"';
+}
+function buildWindowsCommandLine(command) {
+  return command.map(quoteWindowsArgument).join(" ");
+}
+function buildWindowsJobObjectPlan(input) {
+  const bareCommandLine = buildWindowsCommandLine(input.options.command);
+  const commandLine = input.commandNeedsCmdShell ? `cmd.exe /d /s /c "${bareCommandLine}"` : bareCommandLine;
+  return {
+    executable: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-File",
+      input.jobObjectShimPath,
+      String(input.options.activeProcessLimit),
+      input.options.isServiceMode ? "persist" : "kill",
+      String(input.launcherPid),
+      // Base64 survives the node→powershell→CreateProcessW arg relays that
+      // would otherwise re-interpret quotes.
+      Buffer.from(commandLine, "utf8").toString("base64")
+    ],
+    spawnDetached: false,
+    killsProcessGroupOnExit: false,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildLinuxSystemdScopePlan(args) {
+  return {
+    // pids.max (cgroup v2): the excess fork fails with EAGAIN in the kernel.
+    executable: "systemd-run",
+    args: [
+      "--user",
+      "--scope",
+      "--quiet",
+      "--collect",
+      `--unit=${args.scopeUnitName}`,
+      "-p",
+      `TasksMax=${args.options.activeProcessLimit}`,
+      "--",
+      ...args.options.command
+    ],
+    spawnDetached: false,
+    killsProcessGroupOnExit: false,
+    // Catchable launcher death stops the scope; after an untrappable SIGKILL
+    // the scope lives on but stays TasksMax-bounded, so the cap always holds.
+    stopsScopeUnitOnExit: args.options.isServiceMode ? null : args.scopeUnitName
+  };
+}
+function buildLinuxPrlimitProcessGroupPlan(args) {
+  return {
+    executable: "prlimit",
+    args: [`--nproc=${args.nprocCeiling}`, "--", ...args.options.command],
+    spawnDetached: true,
+    killsProcessGroupOnExit: !args.options.isServiceMode,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildDarwinUlimitProcessGroupPlan(args) {
+  return {
+    executable: "/bin/sh",
+    args: ["-c", `ulimit -u ${args.nprocCeiling}; exec "$@"`, "guard-run", ...args.options.command],
+    spawnDetached: true,
+    killsProcessGroupOnExit: !args.options.isServiceMode,
+    stopsScopeUnitOnExit: null
+  };
+}
+function buildBackendLaunchPlan(args) {
+  if (args.backend === "windows-job-object" /* WindowsJobObject */) {
+    return buildWindowsJobObjectPlan({
+      options: args.options,
+      jobObjectShimPath: args.jobObjectShimPath ?? "",
+      launcherPid: args.launcherPid ?? 0,
+      commandNeedsCmdShell: args.commandNeedsCmdShell ?? false
+    });
+  }
+  if (args.backend === "linux-systemd-scope" /* LinuxSystemdScope */) {
+    return buildLinuxSystemdScopePlan({
+      options: args.options,
+      scopeUnitName: args.scopeUnitName ?? ""
+    });
+  }
+  if (args.backend === "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */) {
+    return buildLinuxPrlimitProcessGroupPlan({
+      options: args.options,
+      nprocCeiling: args.nprocCeiling ?? 0
+    });
+  }
+  return buildDarwinUlimitProcessGroupPlan({
+    options: args.options,
+    nprocCeiling: args.nprocCeiling ?? 0
+  });
+}
+
+// src/guard-run/headroom.ts
+function countProcessListLines(psOutput) {
+  return psOutput.split("\n").filter((line) => line.trim() !== "").length;
+}
+function computeNprocCeiling(args) {
+  return args.currentUserProcessCount + args.activeProcessLimit;
+}
+
+// src/guard-run/constants.ts
+var GUARD_RUN_DEFAULT_ACTIVE_PROCESS_LIMIT = 64;
+var GUARD_RUN_USAGE = "usage: guard-run [--limit N] [--service] -- <command...>\n  Runs <command> with its whole process tree kernel-capped at N processes\n  (default 64). Default mode also ties the tree to the launcher: killing\n  guard-run reaps every descendant. --service keeps the cap but lets the\n  tree outlive the launcher (for dev servers).";
+
+// src/guard-run/parseArguments.ts
+function parseError(errorMessage) {
+  return { options: null, errorMessage: `${errorMessage}
+${GUARD_RUN_USAGE}` };
+}
+function parsePositiveInteger(rawValue) {
+  if (rawValue === void 0 || !/^\d+$/.test(rawValue)) return null;
+  const parsed = Number(rawValue);
+  return parsed >= 1 ? parsed : null;
+}
+function parseGuardRunArguments(argv) {
+  let activeProcessLimit = GUARD_RUN_DEFAULT_ACTIVE_PROCESS_LIMIT;
+  let isServiceMode = false;
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === "--") {
+      index += 1;
+      break;
+    }
+    if (token === "--service") {
+      isServiceMode = true;
+      index += 1;
+      continue;
+    }
+    if (token === "--limit" || token.startsWith("--limit=")) {
+      const rawLimit = token === "--limit" ? argv[index + 1] : token.slice("--limit=".length);
+      const parsedLimit = parsePositiveInteger(rawLimit);
+      if (parsedLimit === null) return parseError("--limit requires a positive integer");
+      activeProcessLimit = parsedLimit;
+      index += token === "--limit" ? 2 : 1;
+      continue;
+    }
+    if (token.startsWith("--")) return parseError(`unknown flag: ${token}`);
+    break;
+  }
+  const command = argv.slice(index);
+  if (command.length === 0) return parseError("no command given");
+  return {
+    options: {
+      activeProcessLimit,
+      isServiceMode,
+      command
+    },
+    errorMessage: null
+  };
+}
+
+// src/guard-run/selectBackend.ts
+var SYSTEMD_USABLE_MANAGER_STATES = /* @__PURE__ */ new Set(["running", "degraded"]);
+function selectGuardRunBackend(probe) {
+  if (probe.platform === "win32") {
+    return { backend: "windows-job-object" /* WindowsJobObject */, errorMessage: null };
+  }
+  if (probe.platform === "linux") {
+    const managerState = (probe.systemdUserManagerState ?? "").trim();
+    if (probe.hasSystemdRun && SYSTEMD_USABLE_MANAGER_STATES.has(managerState)) {
+      return { backend: "linux-systemd-scope" /* LinuxSystemdScope */, errorMessage: null };
+    }
+    if (probe.hasPrlimit) {
+      return { backend: "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */, errorMessage: null };
+    }
+    return {
+      backend: null,
+      errorMessage: "no process-cap backend available (need a systemd user manager or prlimit); refusing to run the command unguarded"
+    };
+  }
+  if (probe.platform === "darwin") {
+    return { backend: "darwin-ulimit-process-group" /* DarwinUlimitProcessGroup */, errorMessage: null };
+  }
+  return {
+    backend: null,
+    errorMessage: `unsupported platform "${probe.platform}"; refusing to run the command unguarded`
+  };
+}
+
+// src/guard-run/cli.ts
+var JOB_OBJECT_SHIM_FILENAME = "guard-run-job-object.ps1";
+function fail(message) {
+  process.stderr.write(`guard-run: ${message}
+`);
+  process.exit(2);
+}
+function commandSucceeds(executable, args) {
+  const probe = spawnSync(executable, args, { stdio: "ignore", timeout: 1e4 });
+  return probe.error === void 0 && probe.status === 0;
+}
+function probedSystemdUserManagerState() {
+  const probe = spawnSync("systemctl", ["--user", "is-system-running"], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (probe.error !== void 0 || typeof probe.stdout !== "string") return null;
+  return probe.stdout.trim();
+}
+function resolveJobObjectShimPath() {
+  const bundledSibling = join(dirname(fileURLToPath(import.meta.url)), JOB_OBJECT_SHIM_FILENAME);
+  if (existsSync(bundledSibling)) return bundledSibling;
+  const pluginTreePath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "plugin",
+    "scripts",
+    JOB_OBJECT_SHIM_FILENAME
+  );
+  if (existsSync(pluginTreePath)) return pluginTreePath;
+  return fail(`cannot locate ${JOB_OBJECT_SHIM_FILENAME}; refusing to run the command unguarded`);
+}
+function windowsCommandNeedsCmdShell(firstCommandToken) {
+  const knownExtension = extname(firstCommandToken).toLowerCase();
+  if (knownExtension === ".cmd" || knownExtension === ".bat") return true;
+  if (knownExtension !== "") return false;
+  const lookup = spawnSync("where.exe", [firstCommandToken], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (lookup.error !== void 0 || lookup.status !== 0) return false;
+  const resolvedExtension = extname(lookup.stdout.split(/\r?\n/)[0] ?? "").toLowerCase();
+  return resolvedExtension === ".cmd" || resolvedExtension === ".bat";
+}
+function currentUserProcessCount() {
+  const uid = typeof process.getuid === "function" ? String(process.getuid()) : "";
+  const listing = spawnSync("ps", ["-u", uid, "-o", "pid="], {
+    encoding: "utf-8",
+    timeout: 1e4
+  });
+  if (listing.error !== void 0 || listing.status !== 0) {
+    return fail("cannot count current user processes for the nproc ceiling");
+  }
+  return countProcessListLines(listing.stdout);
+}
+function registerTreeCleanup(plan2, childPid) {
+  if (!plan2.killsProcessGroupOnExit && plan2.stopsScopeUnitOnExit === null) return;
+  let cleanedUp = false;
+  const cleanup = () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    if (plan2.killsProcessGroupOnExit && childPid !== void 0) {
+      try {
+        process.kill(-childPid, "SIGKILL");
+      } catch {
+      }
+    }
+    if (plan2.stopsScopeUnitOnExit !== null) {
+      spawnSync("systemctl", ["--user", "stop", plan2.stopsScopeUnitOnExit], {
+        stdio: "ignore",
+        timeout: 1e4
+      });
+    }
+  };
+  process.on("exit", cleanup);
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => {
+      cleanup();
+      process.exit(128 + (signal === "SIGINT" ? 2 : signal === "SIGTERM" ? 15 : 1));
+    });
+  }
+}
+var parseResult = parseGuardRunArguments(process.argv.slice(2));
+if (parseResult.options === null) fail(parseResult.errorMessage ?? "invalid arguments");
+var options = parseResult.options;
+var isLinux = process.platform === "linux";
+var selection = selectGuardRunBackend({
+  platform: process.platform,
+  hasSystemdRun: isLinux && commandSucceeds("systemd-run", ["--version"]),
+  systemdUserManagerState: isLinux ? probedSystemdUserManagerState() : null,
+  hasPrlimit: isLinux && commandSucceeds("prlimit", ["--version"])
+});
+if (selection.backend === null) fail(selection.errorMessage ?? "no backend");
+var backend = selection.backend;
+var needsNprocCeiling = backend === "linux-prlimit-process-group" /* LinuxPrlimitProcessGroup */ || backend === "darwin-ulimit-process-group" /* DarwinUlimitProcessGroup */;
+var plan = buildBackendLaunchPlan({
+  backend,
+  options,
+  jobObjectShimPath: backend === "windows-job-object" /* WindowsJobObject */ ? resolveJobObjectShimPath() : void 0,
+  launcherPid: process.pid,
+  commandNeedsCmdShell: backend === "windows-job-object" /* WindowsJobObject */ ? windowsCommandNeedsCmdShell(options.command[0]) : false,
+  scopeUnitName: `muggle-guard-${process.pid}-${Date.now()}.scope`,
+  nprocCeiling: needsNprocCeiling ? computeNprocCeiling({
+    currentUserProcessCount: currentUserProcessCount(),
+    activeProcessLimit: options.activeProcessLimit
+  }) : void 0
+});
+var child = spawn(plan.executable, plan.args, {
+  stdio: "inherit",
+  detached: plan.spawnDetached,
+  windowsHide: true
+});
+child.on("error", (error) => fail(`failed to launch backend: ${String(error)}`));
+registerTreeCleanup(plan, child.pid);
+child.on("exit", (code, signal) => {
+  process.exitCode = code ?? (signal === "SIGKILL" ? 137 : signal === "SIGTERM" ? 143 : 1);
+});

package/plugin/scripts/guardrail-offer-ran.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# Next-options-offer observer (PostToolUse/AskUserQuestion). An AskUserQuestion
+# call while a terminal PR is pending IS the post-merge handoff's exit: it
+# clears terminalPending so the Stop gate (guardrail-terminal-gate.sh)
+# releases. Emits no directive.
+#
+# Pre-filter: only spawn Node when the per-session state actually has a
+# pending terminal PR, so the ordinary AskUserQuestion (no PR merged this
+# session) never pays 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
+
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"terminalPending"' "$state_file" \
+  || grep -q '"terminalPending": \[\]' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" offer-ran 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-pr-terminal.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal guardrail (PostToolUse/Bash + Monitor). When a PR just went
+# terminal — a `gh pr merge`/`gh pr close` success line or the pr-followup
+# watch monitor's `TERMINAL pr=N` exit line — arm the post-merge handoff:
+# record the PR as pending, nudge the model to finalize/tear down and offer
+# next options, and hold the Stop gate (guardrail-terminal-gate.sh) until the
+# AskUserQuestion offer runs. Decision logic lives in the bundled guardrails.mjs.
+#
+# Fires after every Bash call, so a keyword pre-filter for the terminal output
+# shapes keeps Node off the hot path. Degrades to {} so it never blocks.
+payload="$(cat)"
+
+if ! grep -Eiq 'merged pull request|closed pull request|TERMINAL pr=' <<<"$payload"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" pr-terminal 2>/dev/null || printf '{}'

package/plugin/scripts/guardrail-record-tests.sh

@@ -9,12 +9,13 @@ set -uo pipefail
 # Fires after every Bash call and every muggle execute/replay, so a keyword
 # pre-filter for test runners and the muggle E2E tool names keeps Node off the
 # hot path. Only a `test` command (npm/pnpm/yarn/jest/vitest/pytest/go/cargo),
-# a muggle execute/replay/test-generation event, or an E2E skip marker reaches
-# guardrails.mjs, which then inspects the output for pass/fail and updates
-# state. Degrades to {}.
+# a muggle execute/replay/test-generation event, a muggle-test skill telemetry
+# emit (registers a clean-SKIP verdict as an E2E run), or an E2E skip marker
+# reaches guardrails.mjs, which then inspects the output for pass/fail and
+# updates state. Degrades to {}.
 payload="$(cat)"
 
-if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|MUGGLE_E2E_SKIP' <<<"$payload"; then
+if ! grep -Eiq '(pnpm|npm|yarn)[[:space:]]+(run[[:space:]]+)?test|jest|vitest|pytest|go[[:space:]]+test|cargo[[:space:]]+test|muggle.*(execute|test-generation|replay)|muggle-local-telemetry-skill-emit|MUGGLE_E2E_SKIP' <<<"$payload"; then
   printf '{}'
   exit 0
 fi

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# PR-terminal → post-merge handoff gate (Stop). When a PR went terminal this
+# session (merged/closed) and the next-options offer hasn't run, block the
+# turn end until the handoff — finalize, teardown, AskUserQuestion offer —
+# happens. Releases unconditionally after 3 blocks.
+#
+# This must stay synchronous (only a sync Stop hook can block the turn end),
+# and it fires on EVERY turn end. There is no command payload to key off, so
+# the pre-filter reads the same per-session state file guardrails.mjs uses and
+# only spawns Node when a terminal PR is actually pending. On the overwhelming
+# majority of turns no PR went terminal, so the state file is absent or
+# terminalPending is empty and we return {} in-shell. 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
+
+state_file="$home/.muggle-ai/guardrails/$sid.json"
+if [ ! -f "$state_file" ] \
+  || ! grep -q '"terminalPending"' "$state_file" \
+  || grep -q '"terminalPending": \[\]' "$state_file"; then
+  printf '{}'
+  exit 0
+fi
+
+root="${CLAUDE_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}"
+printf '%s' "$payload" | node "${root}/scripts/guardrails.mjs" terminal-gate 2>/dev/null || printf '{}'

package/plugin/scripts/guardrails.mjs

@@ -40,6 +40,63 @@ ${input2.tool_response?.output ?? ""}`;
   return m ? m[0] : null;
 }
 
+// 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 PR_MONITOR_TERMINAL_LINE = /\bTERMINAL pr=(\d+): (MERGED|CLOSED)\b/;
+var MAX_PR_TERMINAL_BLOCKS = 3;
+var MUGGLE_SKILL_EMIT_TOOL = /muggle-local-telemetry-skill-emit/i;
+var MUGGLE_TEST_SKILL_NAME = "muggle-test";
+
+// src/guardrails/prTerminal.ts
+function detectPrTerminal(input2) {
+  if (input2.tool_name !== "Bash" && input2.tool_name !== "Monitor") 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 mergedMatch = haystack.match(GH_PR_MERGED_LINE);
+  if (mergedMatch) {
+    return { prNumber: Number(mergedMatch[1]), verdict: "merged" /* Merged */ };
+  }
+  const closedMatch = haystack.match(GH_PR_CLOSED_LINE);
+  if (closedMatch) {
+    return { prNumber: Number(closedMatch[1]), verdict: "closed" /* Closed */ };
+  }
+  const monitorMatch = haystack.match(PR_MONITOR_TERMINAL_LINE);
+  if (monitorMatch) {
+    return {
+      prNumber: Number(monitorMatch[1]),
+      verdict: monitorMatch[2] === "MERGED" ? "merged" /* Merged */ : "closed" /* Closed */
+    };
+  }
+  return null;
+}
+function applyPrTerminalDetected(state, prNumber) {
+  const pending = state.terminalPending ?? [];
+  const handled = state.terminalHandled ?? [];
+  if (pending.includes(prNumber) || handled.includes(prNumber)) return state;
+  return { ...state, terminalPending: [...pending, prNumber] };
+}
+function applyNextOptionsOffered(state) {
+  const pending = state.terminalPending ?? [];
+  if (pending.length === 0) return state;
+  return {
+    ...state,
+    terminalPending: [],
+    terminalHandled: [...state.terminalHandled ?? [], ...pending],
+    terminalBlockCount: 0
+  };
+}
+function prTerminalGateDecision(state, maxBlocks = MAX_PR_TERMINAL_BLOCKS) {
+  const blockCount = state.terminalBlockCount ?? 0;
+  if ((state.terminalPending ?? []).length === 0) {
+    return { action: "none" /* None */, blockCount };
+  }
+  if (blockCount >= maxBlocks) {
+    return { action: "release" /* Release */, blockCount };
+  }
+  return { action: "block" /* Block */, blockCount: blockCount + 1 };
+}
+
 // src/guardrails/testsGreen.ts
 var TEST_CMD = /\b(pnpm|npm|yarn)\s+(run\s+)?test\b|\b(jest|vitest|pytest)\b|\bgo\s+test\b|\bcargo\s+test\b/;
 var FAIL = /\b\d+\s+failed\b|\bFAIL\b|✗/;
@@ -58,7 +115,8 @@ ${input2.tool_response?.stderr ?? ""}`;
   return !FAIL.test(out);
 }
 function isE2ERun(input2) {
-  return E2E_TOOL.test(input2.tool_name ?? "");
+  if (E2E_TOOL.test(input2.tool_name ?? "")) return true;
+  return MUGGLE_SKILL_EMIT_TOOL.test(input2.tool_name ?? "") && input2.tool_input?.skillName === MUGGLE_TEST_SKILL_NAME;
 }
 
 // src/guardrails/shouldRunE2E.ts
@@ -69,10 +127,10 @@ function shouldRunE2E(state) {
 function applyRecordedRun(state, run) {
   let next = state;
   if (run.unitTestPassed) {
-    next = { ...next, unitTestsGreen: true, e2eRun: false, e2eBlockCount: 0 };
+    next = { ...next, unitTestsGreen: true, e2eRun: false };
   }
   if (run.e2eRan) {
-    next = { ...next, e2eRun: true };
+    next = { ...next, e2eRun: true, e2eBlockCount: 0 };
   }
   if (run.e2eSkipped) {
     next = { ...next, e2eSkipped: true };
@@ -197,6 +255,33 @@ function prOpened() {
 Per the autoWatchPR preference, a muggle-pr-followup watcher should handle its incoming reviews. If autoWatchPR=always, start it now by invoking /muggle:muggle-pr-followup with the PR URL; if =ask, offer it to the user; if =never, do nothing.`;
   return envelope("PostToolUse", ctx, host);
 }
+function prTerminal() {
+  const terminalEvent = detectPrTerminal(input);
+  if (!terminalEvent) return "{}";
+  const state = readState(sessionId);
+  const next = applyPrTerminalDetected(state, terminalEvent.prNumber);
+  if (next === state) return "{}";
+  writeState(next);
+  const ctx = `PR #${terminalEvent.prNumber} went terminal (${terminalEvent.verdict}). Run the post-merge handoff now: finalize the watcher slot, tear down per autoCleanup, then OFFER NEXT OPTIONS to the user (AskUserQuestion) \u2014 release, queued work, deferred items. The stop gate holds until the offer runs.`;
+  return envelope("PostToolUse", ctx, host);
+}
+function offerRan() {
+  if (input.tool_name !== "AskUserQuestion") return "{}";
+  const state = readState(sessionId);
+  const next = applyNextOptionsOffered(state);
+  if (next !== state) writeState(next);
+  return "{}";
+}
+function terminalGate() {
+  const state = readState(sessionId);
+  const decision = prTerminalGateDecision(state);
+  if (decision.action !== "block" /* Block */) return "{}";
+  state.terminalBlockCount = decision.blockCount;
+  writeState(state);
+  const pendingPrList = (state.terminalPending ?? []).map((prNumber) => `#${prNumber}`).join(", ");
+  const reason = decision.blockCount === 1 ? `Do not end the turn yet. PR ${pendingPrList} went terminal (merged/closed) but the post-merge handoff has not run. Finalize the watcher slot, tear down per autoCleanup, then offer next options to the user via AskUserQuestion \u2014 release, queued work, deferred items. Only the AskUserQuestion offer clears this gate.` : `Post-merge handoff still owed for PR ${pendingPrList} (reminder ${decision.blockCount}/${MAX_PR_TERMINAL_BLOCKS}): finalize + tear down, then run the AskUserQuestion next-options offer.`;
+  return blockStop(reason, host);
+}
 function recordTests() {
   const cmd = input.tool_input?.command ?? "";
   const state = readState(sessionId);
@@ -233,8 +318,11 @@ function buildRouter() {
 }
 var handlers = {
   "pr-opened": prOpened,
+  "pr-terminal": prTerminal,
+  "offer-ran": offerRan,
   "record-tests": recordTests,
   "e2e-gate": e2eGate,
+  "terminal-gate": terminalGate,
   "report-gate": reportGate,
   "build-router": buildRouter
 };

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+
+# Self-termination guards for the muggle-pr-followup watch loop. Sourced by the
+# per-slot watch.sh that arm-watcher writes, and the single source of truth for
+# the two conditions that stop a watcher from leaking across sessions.
+#
+# A bare `while true` monitor leaks on Windows: the OS does not stop a detached
+# Git Bash loop when the Claude session that launched it ends, so orphaned
+# watchers accumulate and each keeps spawning gh calls forever. Two guards bound
+# that, and together with arm-watcher's pre-arm dedup keep at most one live
+# watcher per PR:
+#
+#   watcher_superseded    — <slot>/watch.pid holds the PID of the watcher that
+#                           owns the slot. A loop whose PID no longer matches has
+#                           been replaced by a newer arm and must exit.
+#   watcher_lifetime_exceeded — a loop exits after MUGGLE_PR_WATCH_MAX_LIFETIME
+#                           regardless, so an orphan nothing supersedes still dies
+#                           on its own; reconcile re-arms an open PR inside a live
+#                           session.
+
+MUGGLE_PR_WATCH_MAX_LIFETIME="${MUGGLE_PR_WATCH_MAX_LIFETIME:-21600}"
+MUGGLE_PR_WATCH_POLL_INTERVAL="${MUGGLE_PR_WATCH_POLL_INTERVAL:-60}"
+
+# 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
+# loop that has not yet claimed the slot keeps running.
+watcher_superseded() {
+    local slot="$1" mypid="$2" owner
+    [ -f "${slot}/watch.pid" ] || return 1
+    owner=$(cat "${slot}/watch.pid" 2>/dev/null)
+    [ -n "$owner" ] && [ "$owner" != "$mypid" ]
+}
+
+watcher_lifetime_exceeded() {
+    local started="$1" now="$2" max="${3:-$MUGGLE_PR_WATCH_MAX_LIFETIME}"
+    [ $((now - started)) -ge "$max" ]
+}
+
+# True when pid names a running process. `kill -0` sends no signal; EPERM means
+# the process exists but is foreign, which still counts as alive. Used by
+# arm-watcher's pre-arm dedup to decide whether a watcher already owns the slot.
+watcher_pid_alive() {
+    local pid="$1"
+    [ -n "$pid" ] || return 1
+    kill -0 "$pid" 2>/dev/null
+}

package/plugin/skills/_shared/pr-followup-helpers/loop-signature.md

@@ -8,11 +8,11 @@ Append these two lines as the end of every loop-posted comment body:
 
 ```
 <!-- muggle-do:bot -->
-🤖 _Automated reply from muggle-do._
+🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_
 ```
 
-- `<!-- muggle-do:bot -->` — hidden HTML marker; GitHub renders it invisibly and humans never type it. This is the **detection token**.
-- The visible line makes the automation clear to a reader.
+- `<!-- muggle-do:bot -->` — hidden HTML marker; GitHub renders it invisibly and humans never type it. This is the **detection token**. It must stay exactly as written — echo-protection and addressed-by-loop classification read this literal string.
+- The visible line is the shared Muggle Works signature ([`../vcs/post-signature.md`](../vcs/post-signature.md)) with `/muggle-do` as the command. It links a reader back to the tool and names the command that posted the comment.
 
 ## Detection
 

package/plugin/skills/_shared/vcs/CLAUDE.md

@@ -1,9 +1,10 @@
 # VCS provider recipes
 
-Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves one provider token via [`detect-vcs.md`](detect-vcs.md) — `github` (`gh`) or `gitlab` (`glab`) — then loads the matching provider's recipe for each agnostic step. The two recipe sets mirror each other call-for-call; callers branch on the token, never fork procedure.
+Provider-agnostic seam for the watcher and dev-cycle skills. A caller resolves one provider token via [`detect-vcs.md`](detect-vcs.md) — `github` (`gh`) or `gitlab` (`glab`) — then loads the matching provider's recipe for each agnostic step. The two recipe sets mirror each other call-for-call; callers branch on the token, never fork procedure. Provider-agnostic entry points live once in `common/`, indexed by both TOCs: a **dispatcher** owns the `github`-vs-`gitlab` branch so a caller links it alone instead of naming both recipes side by side (`ci-rollup`, `branch-standing`, `push-to-branch`), and a recipe with no provider-specific procedure lives there too (`verify-working-tree`).
 
 ## Index
 
 - [`detect-vcs.md`](detect-vcs.md) — resolve `github` | `gitlab` from a URL argument or the origin remote.
 - [`github.md`](github.md) — `gh` / `git` recipe TOC; per-recipe files in [`github/`](github/).
 - [`gitlab.md`](gitlab.md) — `glab` / `git` recipe TOC; per-recipe files in [`gitlab/`](gitlab/).
+- `common/` — provider-agnostic entry points (`ci-rollup`, `branch-standing`, `push-to-branch`, `verify-working-tree`), indexed by both provider TOCs.

package/plugin/skills/_shared/vcs/common/branch-standing.md

@@ -0,0 +1,19 @@
+# Branch standing vs base (tool-agnostic)
+
+The single instruction the rebase trigger references for **conflict** and **out-of-date** detection — sites link here and never name a provider's metadata recipe inline. Both signals read from the metadata snapshot the caller already fetched; this file only says which field each provider reads.
+
+Resolve the provider per [`../detect-vcs.md`](../detect-vcs.md).
+
+## Conflict with the base
+
+- `github` → `mergeable == CONFLICTING`, corroborated by `mergeStateStatus == DIRTY` ([`../github/pr-metadata.md`](../github/pr-metadata.md)).
+- `gitlab` → `detailed_merge_status` in `{broken_status, conflict}` ([`../gitlab/mr-metadata.md`](../gitlab/mr-metadata.md)).
+
+A still-computing state — `github`'s `mergeable == UNKNOWN`, `gitlab`'s `checking` / `unchecked` — counts as **not conflicting** this tick.
+
+## Out of date (behind the base)
+
+Read from **commit ancestry**, never from the merge-state field: GitHub masks `BEHIND` behind `DIRTY` / `BLOCKED`, and GitLab reports `need_rebase` only under fast-forward-merge — both hide a stale branch. The compare is exact even while the conflict state is still computing.
+
+- `github` → the compare call in [`../github/pr-metadata.md`](../github/pr-metadata.md#behind-by-out-of-date-detection); `behind_by > 0` ⇒ out of date.
+- `gitlab` → the compare call in [`../gitlab/mr-metadata.md`](../gitlab/mr-metadata.md#behind-by-out-of-date-detection); any base commit the head lacks ⇒ out of date.