@muggleai/works 5.7.0 → 5.8.0

package/plugin/scripts/gc-state.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+# Prune ephemeral muggle state that nothing else garbage-collects, so it does not
+# grow without bound (observed: hundreds of dead per-session files). Runs from a
+# SessionStart hook, TTL-gated to once/day unless MUGGLE_STATE_GC_FORCE=1. Silent
+# and best-effort: it never blocks session start and never prints context.
+#
+# Collection is keyed on INACTIVITY, never creation age, so a session that lasts
+# months is never collected while it is still in use:
+#
+#   guardrails/<session>.json   one per Claude session. An in-use session keeps
+#       rewriting it (guardrails.mjs on every guarded tool call) and refreshes it
+#       on resume (below), so its mtime tracks last activity — only a session gone
+#       quiet for the whole window is collected, and by then it has ended.
+#   muggle-do/sessions/<slug>/  a PR-follow-up slot. Pruned only once finalized
+#       (result.md present — the terminal marker); an OPEN slot, a PR watched for
+#       any length of time, has no result.md and is never touched.
+#
+# Age tests use `find -mmin/-mtime` (portable across GNU and BSD) rather than
+# `date -r`, whose file-mtime meaning is GNU-only.
+
+home="${HOME}"
+guardrails_dir="${home}/.muggle-ai/guardrails"
+sessions_dir="${home}/.muggle-ai/muggle-do/sessions"
+marker_dir="${home}/.cache/muggle"
+marker="${marker_dir}/state-gc-checked"
+guardrails_ttl_days="${MUGGLE_GUARDRAILS_TTL_DAYS:-14}"
+slot_ttl_days="${MUGGLE_SLOT_TTL_DAYS:-30}"
+
+# Refresh this session's own guardrails file before anything else, every start
+# (not behind the daily gate — a resume on an already-swept day must still mark
+# the session live). This is what makes a long-lived or resumed session immune to
+# the inactivity sweep, whatever its age. Filename sanitization mirrors
+# guardrails.mjs fileFor().
+session_id=$(cat 2>/dev/null | sed -n 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+if [ -n "${session_id}" ]; then
+    safe_id="${session_id//[^A-Za-z0-9_-]/_}"
+    [ -f "${guardrails_dir}/${safe_id}.json" ] && touch "${guardrails_dir}/${safe_id}.json" 2>/dev/null || true
+fi
+
+# TTL gate: skip when the marker exists and is younger than 24h (1440 min).
+if [ -z "${MUGGLE_STATE_GC_FORCE:-}" ] && [ -f "$marker" ] \
+    && [ -z "$(find "$marker" -mmin +1440 2>/dev/null)" ]; then
+    exit 0
+fi
+
+if [ -d "$guardrails_dir" ]; then
+    find "$guardrails_dir" -maxdepth 1 -type f -name '*.json' \
+        -mtime "+${guardrails_ttl_days}" -delete 2>/dev/null || true
+fi
+
+if [ -d "$sessions_dir" ]; then
+    for slot in "$sessions_dir"/*/; do
+        [ -d "$slot" ] || continue
+        [ -f "${slot}result.md" ] || continue
+        if [ -n "$(find "${slot}result.md" -mtime "+${slot_ttl_days}" 2>/dev/null)" ]; then
+            rm -rf "$slot" 2>/dev/null || true
+        fi
+    done
+fi
+
+mkdir -p "$marker_dir" 2>/dev/null || true
+touch "$marker" 2>/dev/null || true
+exit 0

package/plugin/scripts/guard-run-job-object.ps1

@@ -0,0 +1,256 @@
+# Windows backend for guard-run. Callers never invoke this file: the portable
+# entry point is guard-run.mjs (plain node, runs everywhere), which probes the
+# platform and dispatches to one backend — this Job Object shim on win32,
+# systemd scope / prlimit on linux, ulimit + process group on darwin. So skill
+# instructions stay OS-agnostic by referencing guard-run.mjs only; PowerShell
+# exists solely inside this win32 backend. guard-run.mjs invokes it as:
+#
+#   powershell -File guard-run-job-object.ps1 <limit> <kill|persist> <launcherPid> <base64CommandLine>
+#
+# The child is created CREATE_SUSPENDED, assigned to a fresh Job Object, then
+# resumed — so it and every descendant are inside the job from their first
+# instruction. JOB_OBJECT_LIMIT_ACTIVE_PROCESS makes the process past the limit
+# fail at creation in the kernel (nothing to clean up), which is what stops a
+# fork storm: a sweeper that reacts after enumeration always loses that race.
+#
+# kill mode adds JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE — this shim holds the only
+# job handle, so when it exits or is killed the kernel destroys the entire tree
+# — and watches the launcher: if the node launcher dies first, the shim
+# terminates the job so orphans are impossible. persist mode (guard-run
+# --service) keeps only the cap; the tree may outlive the launcher.
+
+$ErrorActionPreference = "Stop"
+
+if ($args.Count -ne 4) {
+    [Console]::Error.WriteLine("usage: guard-run-job-object.ps1 <limit> <kill|persist> <launcherPid> <base64CommandLine>")
+    exit 2
+}
+
+$activeProcessLimit = 0
+if (-not [int]::TryParse($args[0], [ref]$activeProcessLimit) -or $activeProcessLimit -lt 1) {
+    [Console]::Error.WriteLine("guard-run-job-object: limit must be a positive integer")
+    exit 2
+}
+if ($args[1] -notin @("kill", "persist")) {
+    [Console]::Error.WriteLine("guard-run-job-object: mode must be 'kill' or 'persist'")
+    exit 2
+}
+$killOnClose = $args[1] -eq "kill"
+$launcherPid = 0
+if (-not [int]::TryParse($args[2], [ref]$launcherPid)) {
+    [Console]::Error.WriteLine("guard-run-job-object: launcherPid must be an integer")
+    exit 2
+}
+try {
+    $commandLine = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($args[3]))
+} catch {
+    [Console]::Error.WriteLine("guard-run-job-object: command line is not valid base64")
+    exit 2
+}
+
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+
+namespace MuggleGuardRun
+{
+    [StructLayout(LayoutKind.Sequential)]
+    public struct JOBOBJECT_BASIC_LIMIT_INFORMATION
+    {
+        public long PerProcessUserTimeLimit;
+        public long PerJobUserTimeLimit;
+        public uint LimitFlags;
+        public UIntPtr MinimumWorkingSetSize;
+        public UIntPtr MaximumWorkingSetSize;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint PriorityClass;
+        public uint SchedulingClass;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct IO_COUNTERS
+    {
+        public ulong ReadOperationCount;
+        public ulong WriteOperationCount;
+        public ulong OtherOperationCount;
+        public ulong ReadTransferCount;
+        public ulong WriteTransferCount;
+        public ulong OtherTransferCount;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+    {
+        public JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation;
+        public IO_COUNTERS IoInfo;
+        public UIntPtr ProcessMemoryLimit;
+        public UIntPtr JobMemoryLimit;
+        public UIntPtr PeakProcessMemoryUsed;
+        public UIntPtr PeakJobMemoryUsed;
+    }
+
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    public struct STARTUPINFO
+    {
+        public uint cb;
+        public string lpReserved;
+        public string lpDesktop;
+        public string lpTitle;
+        public uint dwX;
+        public uint dwY;
+        public uint dwXSize;
+        public uint dwYSize;
+        public uint dwXCountChars;
+        public uint dwYCountChars;
+        public uint dwFillAttribute;
+        public uint dwFlags;
+        public ushort wShowWindow;
+        public ushort cbReserved2;
+        public IntPtr lpReserved2;
+        public IntPtr hStdInput;
+        public IntPtr hStdOutput;
+        public IntPtr hStdError;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    public struct PROCESS_INFORMATION
+    {
+        public IntPtr hProcess;
+        public IntPtr hThread;
+        public uint dwProcessId;
+        public uint dwThreadId;
+    }
+
+    public static class JobObjectLauncher
+    {
+        const uint JOB_OBJECT_LIMIT_ACTIVE_PROCESS = 0x00000008;
+        const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000;
+        const int JobObjectExtendedLimitInformation = 9;
+        const uint CREATE_SUSPENDED = 0x00000004;
+        const uint SYNCHRONIZE = 0x00100000;
+        const uint INFINITE = 0xFFFFFFFF;
+        const uint WAIT_OBJECT_0 = 0;
+        const int LAUNCHER_DEATH_EXIT_CODE = 137;
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern IntPtr CreateJobObject(IntPtr lpJobAttributes, string lpName);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern bool SetInformationJobObject(IntPtr hJob, int jobObjectInfoClass,
+            ref JOBOBJECT_EXTENDED_LIMIT_INFORMATION lpJobObjectInfo, uint cbJobObjectInfoLength);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern bool AssignProcessToJobObject(IntPtr hJob, IntPtr hProcess);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern bool TerminateJobObject(IntPtr hJob, uint uExitCode);
+
+        [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+        static extern bool CreateProcess(string lpApplicationName, StringBuilder lpCommandLine,
+            IntPtr lpProcessAttributes, IntPtr lpThreadAttributes, bool bInheritHandles,
+            uint dwCreationFlags, IntPtr lpEnvironment, string lpCurrentDirectory,
+            ref STARTUPINFO lpStartupInfo, out PROCESS_INFORMATION lpProcessInformation);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern uint ResumeThread(IntPtr hThread);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern bool TerminateProcess(IntPtr hProcess, uint uExitCode);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern uint WaitForSingleObject(IntPtr hHandle, uint dwMilliseconds);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern uint WaitForMultipleObjects(uint nCount, IntPtr[] lpHandles, bool bWaitAll,
+            uint dwMilliseconds);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern bool GetExitCodeProcess(IntPtr hProcess, out uint lpExitCode);
+
+        [DllImport("kernel32.dll", SetLastError = true)]
+        static extern IntPtr OpenProcess(uint dwDesiredAccess, bool bInheritHandle, uint dwProcessId);
+
+        static Exception LastError(string operation)
+        {
+            return new Exception(operation + " failed (Win32 error " +
+                Marshal.GetLastWin32Error() + ")");
+        }
+
+        public static int Run(string commandLine, int activeProcessLimit, bool killOnClose,
+            int launcherPid)
+        {
+            IntPtr job = CreateJobObject(IntPtr.Zero, null);
+            if (job == IntPtr.Zero) throw LastError("CreateJobObject");
+
+            JOBOBJECT_EXTENDED_LIMIT_INFORMATION limits =
+                new JOBOBJECT_EXTENDED_LIMIT_INFORMATION();
+            limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_ACTIVE_PROCESS
+                | (killOnClose ? JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE : 0);
+            limits.BasicLimitInformation.ActiveProcessLimit = (uint)activeProcessLimit;
+            uint limitsSize = (uint)Marshal.SizeOf(typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
+            if (!SetInformationJobObject(job, JobObjectExtendedLimitInformation, ref limits,
+                limitsSize))
+            {
+                throw LastError("SetInformationJobObject");
+            }
+
+            STARTUPINFO startupInfo = new STARTUPINFO();
+            startupInfo.cb = (uint)Marshal.SizeOf(typeof(STARTUPINFO));
+            PROCESS_INFORMATION processInfo;
+            StringBuilder mutableCommandLine = new StringBuilder(commandLine);
+            if (!CreateProcess(null, mutableCommandLine, IntPtr.Zero, IntPtr.Zero, true,
+                CREATE_SUSPENDED, IntPtr.Zero, null, ref startupInfo, out processInfo))
+            {
+                throw LastError("CreateProcess for [" + commandLine + "]");
+            }
+            if (!AssignProcessToJobObject(job, processInfo.hProcess))
+            {
+                TerminateProcess(processInfo.hProcess, 1);
+                throw LastError("AssignProcessToJobObject");
+            }
+            ResumeThread(processInfo.hThread);
+
+            if (killOnClose)
+            {
+                IntPtr launcher = OpenProcess(SYNCHRONIZE, false, (uint)launcherPid);
+                if (launcher == IntPtr.Zero)
+                {
+                    // Launcher already gone: the tree is orphaned at birth — reap it.
+                    TerminateJobObject(job, LAUNCHER_DEATH_EXIT_CODE);
+                    return LAUNCHER_DEATH_EXIT_CODE;
+                }
+                IntPtr[] handles = new IntPtr[] { processInfo.hProcess, launcher };
+                uint signaled = WaitForMultipleObjects(2, handles, false, INFINITE);
+                if (signaled == WAIT_OBJECT_0 + 1)
+                {
+                    TerminateJobObject(job, LAUNCHER_DEATH_EXIT_CODE);
+                    return LAUNCHER_DEATH_EXIT_CODE;
+                }
+            }
+            else
+            {
+                WaitForSingleObject(processInfo.hProcess, INFINITE);
+            }
+
+            uint exitCode;
+            if (!GetExitCodeProcess(processInfo.hProcess, out exitCode))
+            {
+                throw LastError("GetExitCodeProcess");
+            }
+            // The job handle is deliberately never closed here: in kill mode this
+            // process's death is what closes it, and that close is the kernel's
+            // cue to destroy any stragglers.
+            return (int)exitCode;
+        }
+    }
+}
+'@
+
+try {
+    exit ([MuggleGuardRun.JobObjectLauncher]::Run($commandLine, $activeProcessLimit, $killOnClose, $launcherPid))
+} catch {
+    [Console]::Error.WriteLine("guard-run-job-object: $($_.Exception.Message)")
+    exit 1
+}

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