@bli-cockpit/cli 0.2.280 → 0.2.282

package/dist/autostart-contract.js

@@ -16,11 +16,21 @@ export const DEFAULT_AUTOSTART_INTERVAL_SECONDS = 15 * 60;
 export const REMIND_AUTOSTART_LABEL = "com.bli.cockpit.remind";
 export const WINDOWS_REMIND_TASK_NAME = "BLI Cockpit Remind";
 export const REMIND_INTERVAL_SECONDS = 60;
+/**
+ * BLI-23571: the THIRD job of the one autostart contract, and the only long-lived one. A resident shell
+ * guard that kills a runaway `node` before it freezes the machine. See `memory-guard-contract.ts`.
+ */
+export const MEMORY_GUARD_AUTOSTART_LABEL = "com.bli.cockpit.memguard";
+export const WINDOWS_MEMORY_GUARD_TASK_NAME = "BLI Cockpit Memory Guard";
 export const UNSUPPORTED_MESSAGE = "autostart is supported on macOS and Windows only";
 /** Where the reminder LaunchAgent lives for a given home. */
 export function remindPlistPathFor(homeDir) {
     return path.join(homeDir, "Library", "LaunchAgents", `${REMIND_AUTOSTART_LABEL}.plist`);
 }
+/** Where the memory guard LaunchAgent lives for a given home. */
+export function memoryGuardPlistPathFor(homeDir) {
+    return path.join(homeDir, "Library", "LaunchAgents", `${MEMORY_GUARD_AUTOSTART_LABEL}.plist`);
+}
 /** Where the LaunchAgent lives for a given home; also the `plist_path` every
  * result carries, including the unsupported-platform one. */
 export function plistPathFor(homeDir) {

package/dist/autostart-memory-guard.js

@@ -0,0 +1,275 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileExists, MEMORY_GUARD_AUTOSTART_LABEL, memoryGuardPlistPathFor, WINDOWS_MEMORY_GUARD_TASK_NAME, } from "./autostart-contract.js";
+import { describeDifference, renderedFileDifference, renderWindowsLauncherScript, UTF8_BOM, windowsPowerShellPath, windowsWScriptPath, } from "./autostart-windows-scripts.js";
+import { xmlEscape, decodeXmlEntities } from "./autostart-xml.js";
+import { lastKillIn, MEMORY_GUARD_DISABLED_MARKER, MEMORY_GUARD_LOG, memoryGuardLimitsFor, memoryGuardStateFile, memoryGuardTurnedOff, memoryGuardTurnedOn, } from "./memory-guard-contract.js";
+import { renderDarwinMemoryGuardScript } from "./memory-guard-script-darwin.js";
+import { renderWindowsMemoryGuardRegistration, renderWindowsMemoryGuardScript } from "./memory-guard-script-windows.js";
+/**
+ * The memory guard: the THIRD job of the one autostart contract (BLI-23571), installed, repaired and removed
+ * with the sync and reminder jobs from the same front doors in `autostart.ts`, and honouring the same
+ * opt-out marker (an operator uninstall removes it). Unlike the reminder it is a RESIDENT process:
+ * launchd `KeepAlive` on macOS, a logon task that restarts on failure with no time limit on Windows.
+ * `COCKPIT_MEMORY_GUARD=off` at install time turns only the guard off and leaves a marker the tick respects.
+ *
+ * Nothing here throws for a host problem: every function answers with a named status and a message, and
+ * every deciding branch logs its reason (metadata only, never a path).
+ */
+const TAG = "[autostart-memory-guard]";
+const GUARD_SCRIPT_DARWIN = "memory-guard.sh";
+const GUARD_OUT_LOG = "memory-guard.out.log";
+const GUARD_ERR_LOG = "memory-guard.err.log";
+const GUARD_SCRIPT_WINDOWS = "autostart-memory-guard.ps1";
+const GUARD_LAUNCHER = "autostart-memory-guard.vbs";
+const GUARD_REGISTRATION = "autostart-memory-guard-register.ps1";
+const LOG_TAIL_BYTES = 64 * 1024;
+function stateFile(options, name) {
+    return memoryGuardStateFile(options.homeDir, name);
+}
+function result(options, platform, base) {
+    return { label: MEMORY_GUARD_AUTOSTART_LABEL, limits_mb: limitsOf(options), ...base, ...(platform === "win32" ? { task_name: WINDOWS_MEMORY_GUARD_TASK_NAME } : {}) };
+}
+function limitsOf(options) {
+    return memoryGuardLimitsFor({ ...(options.env ? { env: options.env } : {}), ...(options.totalMemoryBytes ? { totalMemoryBytes: options.totalMemoryBytes } : {}) });
+}
+/** launchd's guard plist: resident, restarted by launchd within 5 s of any exit, interactive priority. */
+export function renderMemoryGuardPlist(options) {
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        "<dict>",
+        "  <key>Label</key>",
+        `  <string>${xmlEscape(MEMORY_GUARD_AUTOSTART_LABEL)}</string>`,
+        "  <key>ProgramArguments</key>",
+        "  <array>",
+        "    <string>/bin/bash</string>",
+        `    <string>${xmlEscape(options.scriptPath)}</string>`,
+        "  </array>",
+        "  <key>RunAtLoad</key>",
+        "  <true/>",
+        "  <key>KeepAlive</key>",
+        "  <true/>",
+        "  <key>ProcessType</key>",
+        "  <string>Interactive</string>",
+        "  <key>ThrottleInterval</key>",
+        "  <integer>5</integer>",
+        "  <key>StandardOutPath</key>",
+        `  <string>${xmlEscape(options.stdoutPath)}</string>`,
+        "  <key>StandardErrorPath</key>",
+        `  <string>${xmlEscape(options.stderrPath)}</string>`,
+        "</dict>",
+        "</plist>",
+        "",
+    ].join("\n");
+}
+function darwinFiles(options) {
+    const scriptPath = stateFile(options, GUARD_SCRIPT_DARWIN);
+    return {
+        scriptPath,
+        plistPath: memoryGuardPlistPathFor(options.homeDir ?? os.homedir()),
+        script: renderDarwinMemoryGuardScript({ limits: limitsOf(options), logPath: stateFile(options, MEMORY_GUARD_LOG) }),
+        plist: renderMemoryGuardPlist({ scriptPath, stdoutPath: stateFile(options, GUARD_OUT_LOG), stderrPath: stateFile(options, GUARD_ERR_LOG) }),
+    };
+}
+function windowsFiles(options) {
+    const paths = {
+        script: stateFile(options, GUARD_SCRIPT_WINDOWS),
+        launcher: stateFile(options, GUARD_LAUNCHER),
+        registration: stateFile(options, GUARD_REGISTRATION),
+    };
+    return {
+        paths,
+        script: `${UTF8_BOM}${renderWindowsMemoryGuardScript({ limits: limitsOf(options), logPath: stateFile(options, MEMORY_GUARD_LOG) })}`,
+        launcher: renderWindowsLauncherScript({ powershellPath: windowsPowerShellPath(), scriptPath: paths.script }),
+        registration: `${UTF8_BOM}${renderWindowsMemoryGuardRegistration({ taskName: WINDOWS_MEMORY_GUARD_TASK_NAME, launcherPath: paths.launcher, scriptName: GUARD_SCRIPT_WINDOWS })}`,
+    };
+}
+/** Writes the guard script and plist without touching launchd (the detached healer registers it). */
+export async function writeDarwinMemoryGuardPlist(options) {
+    const files = darwinFiles(options);
+    await mkdir(path.dirname(files.plistPath), { recursive: true });
+    await mkdir(path.dirname(files.scriptPath), { recursive: true });
+    await writeFile(files.scriptPath, files.script, { encoding: "utf8", mode: 0o755 });
+    await chmod(files.scriptPath, 0o755);
+    await writeFile(files.plistPath, files.plist, "utf8");
+    return { plist_path: files.plistPath };
+}
+/** True when the operator turned only the guard off (`COCKPIT_MEMORY_GUARD=off` at an earlier install). */
+export async function memoryGuardDisabled(options) {
+    return fileExists(stateFile(options, MEMORY_GUARD_DISABLED_MARKER));
+}
+function platformPath(options, platform) {
+    return platform === "win32" ? stateFile(options, GUARD_SCRIPT_WINDOWS) : memoryGuardPlistPathFor(options.homeDir ?? os.homedir());
+}
+/** Applies the install-time switch. Returns a finished result when the guard must stay off, else null. */
+async function applyInstallSwitch(options, platform) {
+    const marker = stateFile(options, MEMORY_GUARD_DISABLED_MARKER);
+    const env = options.env ?? process.env;
+    if (memoryGuardTurnedOff(env)) {
+        await mkdir(path.dirname(marker), { recursive: true });
+        await writeFile(marker, new Date().toISOString(), "utf8");
+        await uninstallMemoryGuard(options);
+        console.error(`${TAG} not installed`, JSON.stringify({ reason: "turned_off_by_env", env: "COCKPIT_MEMORY_GUARD=off", platform }));
+        return result(options, platform, { status: "absent", path: platformPath(options, platform), disabled: true, loaded: false, message: "memory guard turned off by COCKPIT_MEMORY_GUARD=off; set COCKPIT_MEMORY_GUARD=on and re-run `cockpit autostart install` to bring it back" });
+    }
+    if (memoryGuardTurnedOn(env)) {
+        await rm(marker, { force: true });
+        return null;
+    }
+    if (await fileExists(marker)) {
+        console.error(`${TAG} not installed`, JSON.stringify({ reason: "disabled_marker_stands", platform }));
+        return result(options, platform, { status: "absent", path: platformPath(options, platform), disabled: true, loaded: false, message: "memory guard stays off (COCKPIT_MEMORY_GUARD=off was chosen at an earlier install)" });
+    }
+    return null;
+}
+/** Installs or repairs the memory guard for this host. Never throws. */
+export async function installMemoryGuard(options) {
+    const platform = options.platform ?? process.platform;
+    try {
+        if (platform !== "darwin" && platform !== "win32")
+            return result(options, platform, { status: "unsupported", path: platformPath(options, platform) });
+        const switched = await applyInstallSwitch(options, platform);
+        if (switched)
+            return switched;
+        if (platform === "darwin") {
+            const written = await writeDarwinMemoryGuardPlist(options);
+            await options.exec("launchctl", ["unload", written.plist_path]).catch(() => undefined);
+            const load = await options.exec("launchctl", ["load", written.plist_path]);
+            console.error(`${TAG} ${load.code === 0 ? "launchd job loaded" : "launchd job not loaded"}`, JSON.stringify({ label: MEMORY_GUARD_AUTOSTART_LABEL, exit_code: load.code, hard_limit_mb: limitsOf(options).hard }));
+            return result(options, platform, { status: "installed", path: written.plist_path, loaded: load.code === 0, ...(load.code === 0 ? {} : { message: `launchctl load exited ${load.code} for the memory guard` }) });
+        }
+        return await installWindowsGuard(options);
+    }
+    catch (error) {
+        console.error(`${TAG} install failed`, JSON.stringify({ reason: "install_threw", platform, error_name: error instanceof Error ? error.name : typeof error }));
+        return result(options, platform, { status: "not_loaded", path: platformPath(options, platform), loaded: false, message: "the memory guard could not be written" });
+    }
+}
+async function installWindowsGuard(options) {
+    const files = windowsFiles(options);
+    await mkdir(path.dirname(files.paths.script), { recursive: true });
+    await writeFile(files.paths.script, files.script, "utf8");
+    await writeFile(files.paths.launcher, files.launcher, "utf8");
+    await writeFile(files.paths.registration, files.registration, "utf8");
+    const created = await options.exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File", files.paths.registration]);
+    console.error(`${TAG} ${created.code === 0 ? "scheduled task registered and started" : "scheduled task registration failed"}`, JSON.stringify({ task_name: WINDOWS_MEMORY_GUARD_TASK_NAME, exit_code: created.code, hard_limit_mb: limitsOf(options).hard }));
+    return result(options, "win32", { status: "installed", path: files.paths.script, loaded: created.code === 0, ...(created.code === 0 ? {} : { message: `PowerShell registration of the memory guard exited ${created.code}` }) });
+}
+/** Removes the guard and its files (the log stays: it is the history of what was killed). Safe to repeat. */
+export async function uninstallMemoryGuard(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "darwin") {
+        const plistPath = memoryGuardPlistPathFor(options.homeDir ?? os.homedir());
+        if (!(await fileExists(plistPath)))
+            return result(options, platform, { status: "absent", path: plistPath });
+        await options.exec("launchctl", ["unload", plistPath]).catch(() => undefined);
+        await rm(plistPath, { force: true });
+        await rm(stateFile(options, GUARD_SCRIPT_DARWIN), { force: true });
+        console.error(`${TAG} launchd job removed`, JSON.stringify({ label: MEMORY_GUARD_AUTOSTART_LABEL }));
+        return result(options, platform, { status: "uninstalled", path: plistPath });
+    }
+    if (platform === "win32") {
+        const files = windowsFiles(options);
+        const query = await options.exec("schtasks.exe", ["/Query", "/TN", WINDOWS_MEMORY_GUARD_TASK_NAME]);
+        const known = query.code === 0;
+        if (known)
+            await options.exec("schtasks.exe", ["/End", "/TN", WINDOWS_MEMORY_GUARD_TASK_NAME]).catch(() => undefined);
+        // The resident loop is a child PowerShell; ending the task does not always take it down.
+        if (known)
+            await options.exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `Get-CimInstance Win32_Process -Filter "Name='powershell.exe'" | Where-Object { $_.CommandLine -like '*${GUARD_SCRIPT_WINDOWS}*' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }`]).catch(() => undefined);
+        const removed = known ? await options.exec("schtasks.exe", ["/Delete", "/TN", WINDOWS_MEMORY_GUARD_TASK_NAME, "/F"]) : null;
+        if (removed && removed.code !== 0) {
+            console.error(`${TAG} scheduled task not removed`, JSON.stringify({ task_name: WINDOWS_MEMORY_GUARD_TASK_NAME, exit_code: removed.code }));
+            return result(options, platform, { status: "not_loaded", path: files.paths.script, message: `schtasks /Delete exited ${removed.code} for the memory guard` });
+        }
+        for (const file of Object.values(files.paths))
+            await rm(file, { force: true });
+        console.error(`${TAG} scheduled task ${known ? "removed" : "was not registered"}`, JSON.stringify({ task_name: WINDOWS_MEMORY_GUARD_TASK_NAME }));
+        return result(options, platform, { status: known ? "uninstalled" : "absent", path: files.paths.script });
+    }
+    return result(options, platform, { status: "unsupported", path: platformPath(options, platform) });
+}
+async function lastKill(options) {
+    const text = await readFile(stateFile(options, MEMORY_GUARD_LOG), "utf8").then((full) => full.slice(-LOG_TAIL_BYTES), () => "");
+    const kill = lastKillIn(text);
+    return kill ? { last_kill: kill } : {};
+}
+/**
+ * Whether the guard is registered, loaded and still says what this build would write. Content is only
+ * compared when the caller supplied roots, exactly like the sync agent (a bare `autostart status` stays permissive).
+ */
+export async function memoryGuardStatus(options) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "darwin" && platform !== "win32")
+        return result(options, platform, { status: "unsupported", path: platformPath(options, platform) });
+    if (await memoryGuardDisabled(options)) {
+        return result(options, platform, { status: "absent", path: platformPath(options, platform), disabled: true, loaded: false, message: "memory guard is turned off (COCKPIT_MEMORY_GUARD=off at install)" });
+    }
+    const compare = Boolean(options.repoRoots && options.repoRoots.length > 0);
+    const reading = platform === "darwin" ? await darwinGuardStatus(options, compare) : await windowsGuardStatus(options, compare);
+    return { ...reading, ...(await lastKill(options)) };
+}
+async function darwinGuardStatus(options, compare) {
+    const files = darwinFiles(options);
+    const onDisk = await readFile(files.plistPath, "utf8").catch(() => null);
+    if (onDisk === null)
+        return result(options, "darwin", { status: "absent", path: files.plistPath });
+    const problems = [];
+    if (compare && onDisk !== files.plist)
+        problems.push("memory guard plist does not match the current Tower runtime");
+    const scriptOnDisk = await readFile(files.scriptPath, "utf8").catch(() => null);
+    if (scriptOnDisk === null)
+        problems.push("memory guard script is missing");
+    else if (compare && scriptOnDisk !== files.script)
+        problems.push("memory guard script does not match the current Tower runtime");
+    const list = await options.exec("launchctl", ["list", MEMORY_GUARD_AUTOSTART_LABEL]);
+    if (list.code !== 0)
+        problems.unshift("memory guard is not loaded");
+    console.error(`${TAG} status`, JSON.stringify({ label: MEMORY_GUARD_AUTOSTART_LABEL, problems: problems.length }));
+    return result(options, "darwin", { status: problems.length === 0 ? "loaded" : "not_loaded", path: files.plistPath, loaded: problems.length === 0, ...(problems.length ? { message: problems.join("; ") } : {}) });
+}
+/** What Task Scheduler stored for the guard: a logon trigger, our launcher, restart on failure, no time limit. */
+export function memoryGuardTaskProblems(taskXml, expected) {
+    const xml = decodeXmlEntities(taskXml);
+    const lower = xml.toLowerCase();
+    const problems = [];
+    if (/<Enabled>\s*false\s*<\/Enabled>/iu.test(xml))
+        problems.push("memory guard task is disabled");
+    if (!/<LogonTrigger[\s/>]/iu.test(xml))
+        problems.push("memory guard task has no logon trigger");
+    if (!/<RestartOnFailure>/iu.test(xml))
+        problems.push("memory guard task does not restart on failure");
+    if (!/<ExecutionTimeLimit>\s*PT0S\s*<\/ExecutionTimeLimit>/iu.test(xml))
+        problems.push("memory guard task has an execution time limit");
+    if (!lower.includes(expected.launcherPath.toLowerCase()))
+        problems.push("memory guard task does not run the current launcher");
+    if (!lower.includes(path.win32.basename(expected.wscriptPath).toLowerCase()))
+        problems.push("memory guard task does not run through wscript");
+    return problems;
+}
+async function windowsGuardStatus(options, compare) {
+    const files = windowsFiles(options);
+    const query = await options.exec("schtasks.exe", ["/Query", "/TN", WINDOWS_MEMORY_GUARD_TASK_NAME, "/XML"]);
+    if (query.code !== 0) {
+        const absent = query.code === 1 && /cannot find|not found|does not exist/iu.test(`${query.stderr}\n${query.stdout}`);
+        console.error(`${TAG} task query failed`, JSON.stringify({ task_name: WINDOWS_MEMORY_GUARD_TASK_NAME, exit_code: query.code, status: absent ? "absent" : "not_loaded" }));
+        return result(options, "win32", { status: absent ? "absent" : "not_loaded", path: files.paths.script });
+    }
+    const problems = memoryGuardTaskProblems(query.stdout, { launcherPath: files.paths.launcher, wscriptPath: windowsWScriptPath() });
+    if (!(await fileExists(files.paths.script)))
+        problems.push("memory guard script is missing");
+    else if (!(await fileExists(files.paths.launcher)))
+        problems.push("memory guard launcher is missing");
+    else if (compare) {
+        for (const [label, file, text] of [["script", files.paths.script, files.script], ["launcher", files.paths.launcher, files.launcher]]) {
+            const difference = renderedFileDifference(await readFile(file, "utf8").catch(() => null), text);
+            if (difference)
+                problems.push(`memory guard ${label} does not match the current Tower runtime (${describeDifference(difference)})`);
+        }
+    }
+    console.error(`${TAG} status`, JSON.stringify({ task_name: WINDOWS_MEMORY_GUARD_TASK_NAME, problems: problems.length }));
+    return result(options, "win32", { status: problems.length === 0 ? "loaded" : "not_loaded", path: files.paths.script, loaded: problems.length === 0, ...(problems.length ? { message: problems.join("; ") } : {}) });
+}

package/dist/autostart-self-heal.js

@@ -67,7 +67,12 @@ async function readAutostartProblem(paths, options, platform) {
     const remindProblem = status.status === "loaded" && status.remind && status.remind.status !== "loaded" && status.remind.status !== "unsupported"
         ? [`reminder job ${status.remind.status === "absent" ? "absent" : status.remind.message ?? "not loaded"}`]
         : [];
-    if (!absent && status.status !== "not_loaded" && runtimeProblems.length === 0 && upgradeProblems.length === 0 && remindProblem.length === 0) {
+    // BLI-23571: the memory guard is repaired the same way. A guard the operator turned off stays off.
+    const guard = status.memory_guard;
+    const guardProblem = status.status === "loaded" && guard && !guard.disabled && guard.status !== "loaded" && guard.status !== "unsupported"
+        ? [`memory guard ${guard.status === "absent" ? "absent" : guard.message ?? "not loaded"}`]
+        : [];
+    if (!absent && status.status !== "not_loaded" && runtimeProblems.length === 0 && upgradeProblems.length === 0 && remindProblem.length === 0 && guardProblem.length === 0) {
         // Healthy is the steady state and stays silent. A marker left by an
         // earlier attempt is spent: that repair worked, so the next break starts
         // fresh instead of waiting out a retry window.
@@ -80,6 +85,7 @@ async function readAutostartProblem(paths, options, platform) {
         ...runtimeProblems,
         ...upgradeProblems,
         ...remindProblem,
+        ...guardProblem,
     ]
         .join("; ")
         .slice(0, DETAIL_MAX_CHARS) || "registration not loaded";
@@ -135,6 +141,14 @@ async function repairWindowsAutostart(options, platform, absent, problem) {
             step: "autostart_repair",
         };
     }
+    if (repaired.loaded && repaired.memory_guard?.loaded === false && !repaired.memory_guard.disabled) {
+        return {
+            status: "fail",
+            reason: "memory_guard_repair_failed",
+            detail: (repaired.memory_guard.message ?? problem).slice(0, DETAIL_MAX_CHARS),
+            step: "autostart_repair",
+        };
+    }
     if (repaired.loaded) {
         return {
             status: "ok",

package/dist/autostart.js

@@ -5,6 +5,7 @@ import { readRegisteredDarwinRuntimePaths } from "./autostart-darwin-plist.js";
 import { installWindowsTask, uninstallWindowsTask, windowsTaskStatus, } from "./autostart-windows.js";
 import { readRegisteredWindowsRuntimePaths } from "./autostart-windows-scripts.js";
 import { installRemindAgent, remindAgentStatus, uninstallRemindAgent } from "./autostart-remind.js";
+import { installMemoryGuard, memoryGuardStatus, uninstallMemoryGuard } from "./autostart-memory-guard.js";
 /**
  * Background collection's front door: install, uninstall, and status for the
  * OS scheduler, whichever OS this is.
@@ -21,7 +22,7 @@ import { installRemindAgent, remindAgentStatus, uninstallRemindAgent } from "./a
  * autostart-contract.ts and is re-exported here because this module is the
  * import site the rest of the collector already knows (BLI-3571).
  */
-export { AUTOSTART_LABEL, DEFAULT_AUTOSTART_INTERVAL_SECONDS, WINDOWS_AUTOSTART_TASK_NAME, REMIND_AUTOSTART_LABEL, WINDOWS_REMIND_TASK_NAME, } from "./autostart-contract.js";
+export { AUTOSTART_LABEL, DEFAULT_AUTOSTART_INTERVAL_SECONDS, WINDOWS_AUTOSTART_TASK_NAME, REMIND_AUTOSTART_LABEL, WINDOWS_REMIND_TASK_NAME, MEMORY_GUARD_AUTOSTART_LABEL, WINDOWS_MEMORY_GUARD_TASK_NAME, } from "./autostart-contract.js";
 export { DARWIN_MIN_SECONDS_BETWEEN_TICKS, DARWIN_NETWORK_CHANGE_SIGNAL, DARWIN_NODE_MISSING_MESSAGE, writeDarwinAutostartPlist, } from "./autostart-darwin-plist.js";
 export { launchdUserDomain, reregisterDarwinAgent, } from "./autostart-darwin.js";
 /**
@@ -35,7 +36,9 @@ export async function installAutostartAgent(options) {
         return unsupportedResult(options.homeDir);
     const sync = platform === "win32" ? await installWindowsTask(options) : await installDarwinAgent(options);
     // BLI-21564: the reminder job is the second job of the same contract, installed and repaired with the sync agent.
-    return { ...sync, remind: await installRemindAgent(options) };
+    const remind = await installRemindAgent(options);
+    // BLI-23571: the memory guard is the third job; `COCKPIT_MEMORY_GUARD=off` at install skips only this one.
+    return { ...sync, remind, memory_guard: await installMemoryGuard(options) };
 }
 /**
  * Removes the scheduled sync and the reminder job. Reports `absent` when there
@@ -46,7 +49,8 @@ export async function uninstallAutostartAgent(options) {
     if (platform !== "win32" && platform !== "darwin")
         return unsupportedResult(options.homeDir);
     const sync = platform === "win32" ? await uninstallWindowsTask(options) : await uninstallDarwinAgent(options);
-    return { ...sync, remind: await uninstallRemindAgent(options) };
+    const remind = await uninstallRemindAgent(options);
+    return { ...sync, remind, memory_guard: await uninstallMemoryGuard(options) };
 }
 /**
  * Reports whether the scheduled sync is installed, registered, and still
@@ -59,7 +63,8 @@ export async function autostartStatus(options) {
     if (platform !== "win32" && platform !== "darwin")
         return unsupportedResult(options.homeDir);
     const sync = platform === "win32" ? await windowsTaskStatus(options) : await darwinAgentStatus(options);
-    return { ...sync, remind: await remindAgentStatus(options) };
+    const remind = await remindAgentStatus(options);
+    return { ...sync, remind, memory_guard: await memoryGuardStatus(options) };
 }
 /**
  * What the platform says it will run, parsed out of the registration itself

package/dist/commands/autostart-command.js

@@ -53,6 +53,7 @@ export async function runAutostart(command, io) {
     }
     writeAutostartResult(io, result);
     writeRemindLine(io, result);
+    writeMemoryGuardLine(io, result);
     return autostartExitCode(command.action, result);
 }
 /** BLI-21564: the reminder job's own line beside the sync agent's, with its message when it needs attention. */
@@ -64,6 +65,20 @@ function writeRemindLine(io, result) {
     if (remind.message)
         writeLine(io.stderr, remind.message);
 }
+/** BLI-23571: the memory guard's line: loaded or not, its limits, and the last thing it killed. */
+function writeMemoryGuardLine(io, result) {
+    const guard = result.memory_guard;
+    if (!guard || guard.status === "unsupported")
+        return;
+    const state = guard.disabled
+        ? "turned off"
+        : guard.status === "installed" ? (guard.loaded ? "installed and loaded" : "installed, not loaded") : guard.status.replace("_", " ");
+    const limits = guard.limits_mb ? `; kills node over ${guard.limits_mb.hard} MB (${guard.limits_mb.warning} under memory pressure, ${guard.limits_mb.critical} when critical)` : "";
+    const kill = guard.last_kill ? `; last kill ${guard.last_kill.ts} (${guard.last_kill.kind}, ${guard.last_kill.footprint_mb} MB, ${guard.last_kill.reason})` : "";
+    writeLine(io.stdout, `Memory guard (${guard.task_name ?? guard.label}): ${state}${guard.disabled ? "" : limits}${kill}`);
+    if (guard.message)
+        writeLine(io.stderr, guard.message);
+}
 function autostartExitCode(action, result) {
     if (result.status === "unsupported")
         return 1;

package/dist/commands/autostart-heal.js

@@ -1,8 +1,9 @@
 import path from "node:path";
 import { appendFile } from "node:fs/promises";
-import { AUTOSTART_LABEL, autostartStatus, REMIND_AUTOSTART_LABEL, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
+import { AUTOSTART_LABEL, autostartStatus, MEMORY_GUARD_AUTOSTART_LABEL, REMIND_AUTOSTART_LABEL, reregisterDarwinAgent, writeDarwinAutostartPlist, } from "../autostart.js";
 import { isAutostartOptedOut } from "../autostart-opt-out.js";
 import { writeDarwinRemindPlist } from "../autostart-remind.js";
+import { memoryGuardDisabled, writeDarwinMemoryGuardPlist } from "../autostart-memory-guard.js";
 import { redactedHealthDetail } from "../health-detail.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
@@ -138,8 +139,35 @@ async function writeAndVerifyRegistration(command, exec, platform, roots, before
             detail: redactedHealthDetail(remindRegistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
         };
     }
+    const guardFailure = await healMemoryGuard(command, exec, platform, roots);
+    if (guardFailure)
+        return guardFailure;
     return verifyRegistration(command, exec, platform, roots, beforeStatus, written.node_path_reason);
 }
+/** BLI-23571: the memory guard is healed with the sync agent by the same two steps, unless the operator turned it off. */
+async function healMemoryGuard(command, exec, platform, roots) {
+    const guardOptions = { homeDir: command.homeDir, repoRoot: roots[0], repoRoots: roots, dashboardUrl: command.dashboardUrl, exec, platform };
+    if (await memoryGuardDisabled(guardOptions)) {
+        console.error("[autostart-heal] memory guard left off", JSON.stringify({ reason: "turned_off_by_operator", platform }));
+        return null;
+    }
+    let guardPlist;
+    try {
+        guardPlist = await writeDarwinMemoryGuardPlist(guardOptions);
+    }
+    catch (error) {
+        return {
+            status: "fail",
+            reason: "memory_guard_plist_write_failed",
+            detail: redactedHealthDetail(error instanceof Error ? error.message : String(error)).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
+    const registered = await reregisterDarwinAgent({ exec, plistPath: guardPlist.plist_path, label: MEMORY_GUARD_AUTOSTART_LABEL });
+    if (!registered.ok) {
+        return { status: "fail", reason: `memory_guard_${registered.reason}`, detail: redactedHealthDetail(registered.detail ?? "").slice(0, DETAIL_MAX_CHARS) };
+    }
+    return null;
+}
 async function verifyRegistration(command, exec, platform, roots, beforeStatus, nodePathReason) {
     // Verify against what launchd returns, not against what we sent it
     // (BLI-2541). A bootstrap that exits 0 and a registration that reads back
@@ -159,6 +187,13 @@ async function verifyRegistration(command, exec, platform, roots, beforeStatus,
             detail: redactedHealthDetail(after.remind.message ?? after.remind.status).slice(0, DETAIL_MAX_CHARS),
         };
     }
+    if (after.status === "loaded" && after.memory_guard && !after.memory_guard.disabled && after.memory_guard.status !== "loaded" && after.memory_guard.status !== "unsupported") {
+        return {
+            status: "fail",
+            reason: "memory_guard_reregistered_but_still_broken",
+            detail: redactedHealthDetail(after.memory_guard.message ?? after.memory_guard.status).slice(0, DETAIL_MAX_CHARS),
+        };
+    }
     if (after.status !== "loaded") {
         return {
             status: "fail",

package/dist/commands/autostart-reading.js

@@ -117,9 +117,9 @@ async function stateFor(result, roots, options) {
             ...detail,
         };
     }
-    return readRegisteredRuntime(roots, options);
+    return readRegisteredRuntime(roots, options, result.memory_guard);
 }
-async function readRegisteredRuntime(roots, options) {
+async function readRegisteredRuntime(roots, options, guard) {
     // BLI-3553: "loaded" only means the scheduler accepted the registration. It
     // says nothing about whether the binary that registration names still exists
     // — and `brew upgrade node` deletes exactly that. Ask the filesystem about
@@ -142,10 +142,24 @@ async function readRegisteredRuntime(roots, options) {
     return {
         state: "loaded",
         reason: "autostart_loaded",
-        message: "background sync is running",
+        message: `background sync is running; ${memoryGuardWords(guard)}`,
         roots,
     };
 }
+/**
+ * BLI-23571: the memory guard rides on the `autostart-alive` row's words rather than a row of its own
+ * (a new doctor step id would reach the server schema). Path-free: it is logged and uploaded.
+ */
+function memoryGuardWords(guard) {
+    if (!guard || guard.status === "unsupported")
+        return "memory guard not applicable on this host";
+    if (guard.disabled)
+        return "memory guard turned off";
+    const kill = guard.last_kill ? `, last kill ${guard.last_kill.ts} (${guard.last_kill.kind})` : "";
+    if (guard.status !== "loaded")
+        return `memory guard ${guard.status === "absent" ? "absent" : "not loaded"} (the next sync tick repairs it)`;
+    return `memory guard loaded (limit ${guard.limits_mb?.hard ?? "?"} MB${kill})`;
+}
 /**
  * The setup receipt's `collector autostart` word (BLI-3731).
  *

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.280");
+    writeLine(io?.stdout ?? process.stdout, "0.2.282");
     return 0;
   }
 

package/dist/commands/sync-followups-memory-guard.js

@@ -0,0 +1,13 @@
+import { reportInstallEventsBestEffort } from "./install-receipts.js";
+import { forwardMemoryGuardReceipts } from "../memory-guard-forward.js";
+export async function runMemoryGuardForwardAfterSync(command, io, dashboardUrl) {
+    try {
+        await forwardMemoryGuardReceipts({
+            homeDir: command.homeDir,
+            report: (events) => reportInstallEventsBestEffort({ homeDir: command.homeDir, dashboardUrl, command: "sync", events, json: command.json, io }),
+        });
+    }
+    catch (error) {
+        console.error("[memory-guard-forward] forwarding threw; collection is unaffected", JSON.stringify({ reason: "forward_threw", error_name: error instanceof Error ? error.name : typeof error }));
+    }
+}

package/dist/commands/sync.js

@@ -41,6 +41,7 @@ import { envWithNodeRuntimeOnPath } from "../scheduled-self-update.js";
 import { runMemoryExperienceAfterSync } from "./memory-log.js";
 import { classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
 import { runMachineHealAfterSync } from "./sync-heal.js";
+import { runMemoryGuardForwardAfterSync } from "./sync-followups-memory-guard.js";
 import { sendSyncHeartbeat } from "./sync-heartbeat.js";
 import { runSyncWithHealthReceipt } from "./sync-receipt.js";
 import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, runStagingPruneAfterSync, } from "./sync-followups.js";
@@ -211,6 +212,8 @@ async function reportTickThrew(command, io, dashboardUrl, error, errorCode) {
 async function convergeAfterTick(command, io, dashboardUrl, facts) {
     await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
     await runMemoryInstallAfterSync(command, io, dashboardUrl);
+    // BLI-23571: carry the resident memory guard's kills to the fleet.
+    await runMemoryGuardForwardAfterSync(command, io, dashboardUrl);
     // BLI-12828: the repairs `cockpit doctor` also makes (agent rules, a lapsed
     // sign-in), so nobody has to be told to run it.
     await runMachineHealAfterSync(command, io, dashboardUrl);

package/dist/memory-guard-contract.js

@@ -0,0 +1,121 @@
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { getCollectorRuntimePaths } from "./local-state.js";
+/**
+ * The resident memory guard's vocabulary (BLI-23571): limits, the log line, the process kinds.
+ *
+ * Why it exists: on 2026-10-28 a `node (vitest 2)` worker reached 166 GB of macOS footprint
+ * (compressed + swap, which `ps` RSS does not show) and froze a 16 GB Mac. `command-guard.ts` only caps
+ * the collector's own commands; nothing protected the machine from any OTHER runaway node (test workers,
+ * dev servers, agent tools). The guard is a SHELL script on purpose: it keeps running while node is
+ * wedged, costs about 2 MB, and spawns no node per tick.
+ *
+ * What it kills: only a process whose executable is `node`, never itself, never anything else.
+ */
+export const MEMORY_GUARD_LOG = "memory-guard.log";
+export const MEMORY_GUARD_CURSOR = "memory-guard.cursor.json";
+export const MEMORY_GUARD_DISABLED_MARKER = "memory-guard.disabled";
+export const MEMORY_GUARD_LOG_LIMIT_BYTES = 1024 * 1024;
+/** Lines kept when the log is trimmed past its cap. */
+export const MEMORY_GUARD_LOG_KEEP_LINES = 200;
+export const MEMORY_GUARD_ORPHAN_MIN_AGE_SECONDS = 300;
+export const MEMORY_GUARD_STEP = "memory_guard";
+export const MEMORY_GUARD_REASONS = [
+    "footprint_over_limit",
+    "rss_over_limit",
+    "pressure_warning",
+    "pressure_critical",
+    "orphan_vitest_worker",
+];
+export const MEMORY_GUARD_EVENTS = ["killed", "kill_failed", "orphan_reaped", "started"];
+const MB = 1024 * 1024;
+/**
+ * hard = min(6144 MB, 40% of RAM); warning tier = min(4096, 25%); critical tier = min(2048, 12.5%).
+ * `COCKPIT_MEMORY_GUARD_LIMIT_MB` replaces the hard limit and can only pull the other tiers down with it.
+ */
+export function resolveMemoryGuardLimits(totalMemoryBytes, env = {}) {
+    const totalMb = Math.max(1, Math.floor(totalMemoryBytes / MB));
+    const base = {
+        hard: Math.min(6144, Math.floor(totalMb * 0.4)),
+        warning: Math.min(4096, Math.floor(totalMb * 0.25)),
+        critical: Math.min(2048, Math.floor(totalMb * 0.125)),
+    };
+    const override = Number(env["COCKPIT_MEMORY_GUARD_LIMIT_MB"]);
+    if (!Number.isFinite(override) || override <= 0)
+        return base;
+    const hard = Math.floor(override);
+    return { hard, warning: Math.min(base.warning, hard), critical: Math.min(base.critical, hard) };
+}
+export function memoryGuardLimitsFor(options) {
+    return resolveMemoryGuardLimits(options.totalMemoryBytes ?? os.totalmem(), options.env ?? process.env);
+}
+/** `COCKPIT_MEMORY_GUARD=off` (or 0/false/no) at install time turns only the guard off. */
+export function memoryGuardTurnedOff(env) {
+    return /^(off|0|false|no)$/iu.test((env?.["COCKPIT_MEMORY_GUARD"] ?? "").trim());
+}
+export function memoryGuardTurnedOn(env) {
+    return /^(on|1|true|yes)$/iu.test((env?.["COCKPIT_MEMORY_GUARD"] ?? "").trim());
+}
+export function memoryGuardStateFile(homeDir, name) {
+    return path.join(getCollectorRuntimePaths(homeDir ?? os.homedir()).state_dir, name);
+}
+/**
+ * The coarse label a log line carries instead of the command line. ONE table; the bash and PowerShell
+ * guards embed these exact patterns (POSIX ERE, JS and .NET read the same text), so a kind means the
+ * same thing on every host. Order matters: first match wins, "other" is the floor.
+ */
+export const MEMORY_GUARD_KIND_PATTERNS = [
+    ["vitest", "vitest"],
+    ["next", "next[/ \\\\](dev|build|start|dist|server)|next-server"],
+    ["tsc", "(^|[/ \\\\])(tsc|tsserver)(\\.js)?( |$)|typescript[/\\\\]lib[/\\\\]tsc"],
+    ["eslint", "eslint"],
+    ["cockpit", "@bli-cockpit[/\\\\]cli|cockpit-cli[/\\\\]dist|[/\\\\]bin[/\\\\]cockpit( |$)"],
+];
+export function classifyProcessKind(commandLine) {
+    for (const [kind, pattern] of MEMORY_GUARD_KIND_PATTERNS)
+        if (new RegExp(pattern, "u").test(commandLine))
+            return kind;
+    return "other";
+}
+/** First 12 hex of the command line's sha256: enough to group identical runaways, useless to read back. */
+export function commandSha12(commandLine) {
+    return crypto.createHash("sha256").update(commandLine).digest("hex").slice(0, 12);
+}
+export function parseMemoryGuardLogLine(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object")
+        return null;
+    const line = value;
+    const event = line["event"];
+    if (typeof line["ts"] !== "string" || !MEMORY_GUARD_EVENTS.includes(event))
+        return null;
+    const num = (key) => (typeof line[key] === "number" && Number.isFinite(line[key]) ? line[key] : 0);
+    const str = (key) => (typeof line[key] === "string" ? line[key].slice(0, 64) : "");
+    return {
+        ts: line["ts"],
+        event: event,
+        pid: num("pid"),
+        footprint_mb: num("footprint_mb"),
+        limit_mb: num("limit_mb"),
+        reason: str("reason"),
+        kind: str("kind"),
+        cmd_sha256: str("cmd_sha256"),
+    };
+}
+/** The last kill (any event but "started") in a log's text, newest wins. */
+export function lastKillIn(logText) {
+    let found;
+    for (const raw of logText.split("\n")) {
+        const line = raw.trim() ? parseMemoryGuardLogLine(raw) : null;
+        if (line && line.event !== "started")
+            found = { ts: line.ts, kind: line.kind, reason: line.reason, footprint_mb: line.footprint_mb };
+    }
+    return found;
+}

package/dist/memory-guard-forward.js

@@ -0,0 +1,82 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { MEMORY_GUARD_CURSOR, MEMORY_GUARD_LOG, MEMORY_GUARD_STEP, memoryGuardStateFile, parseMemoryGuardLogLine, } from "./memory-guard-contract.js";
+/**
+ * Turns the memory guard's kills into fleet receipts (BLI-23571).
+ *
+ * The guard is a shell loop with no network; the sync tick is the courier. Each tick reads the log lines
+ * added since a cursor and queues one install-event receipt per kill (`step: memory_guard`,
+ * `status: fail`, `error_code: <reason>`, `error_detail: <the JSON metadata>`), the same outbox
+ * `command-guard.ts` uses for its own ceiling trips. The cursor is a timestamp plus how many lines at that
+ * exact second were already sent, so the log can be trimmed without re-sending and two kills in one second
+ * are both counted. It is written LAST: a crash between queueing and the write re-sends, never loses.
+ */
+const TAG = "[memory-guard-forward]";
+const MAX_LINES_PER_TICK = 40;
+const FORWARDED_EVENTS = new Set(["killed", "kill_failed", "orphan_reaped"]);
+function parseCursor(raw) {
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return typeof value["ts"] === "string" && typeof value["ts_lines"] === "number" ? { ts: value["ts"], ts_lines: value["ts_lines"] } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The receipt for one log line. Metadata only: the line never held a command line to begin with. */
+export function memoryGuardReceipt(line) {
+    return {
+        step: MEMORY_GUARD_STEP,
+        status: "fail",
+        error_code: line.reason || line.event,
+        error_detail: JSON.stringify({ ts: line.ts, event: line.event, pid: line.pid, footprint_mb: line.footprint_mb, limit_mb: line.limit_mb, reason: line.reason, kind: line.kind, cmd_sha256: line.cmd_sha256 }),
+        at: line.ts,
+    };
+}
+/** Reads new log lines, hands their receipts to `report`, then moves the cursor. Never throws. */
+export async function forwardMemoryGuardReceipts(options) {
+    const logPath = memoryGuardStateFile(options.homeDir, MEMORY_GUARD_LOG);
+    const cursorPath = memoryGuardStateFile(options.homeDir, MEMORY_GUARD_CURSOR);
+    const text = await readFile(logPath, "utf8").catch(() => null);
+    if (text === null)
+        return { forwarded: 0, reason: "no_log" };
+    const lines = text.split("\n").flatMap((raw) => (raw.trim() ? [parseMemoryGuardLogLine(raw)] : [])).filter((line) => line !== null);
+    const cursor = parseCursor(await readFile(cursorPath, "utf8").catch(() => null));
+    let skippedAtCursor = 0;
+    const fresh = [];
+    lines.forEach((line, index) => {
+        if (cursor && line.ts < cursor.ts)
+            return;
+        if (cursor && line.ts === cursor.ts && skippedAtCursor < cursor.ts_lines) {
+            skippedAtCursor += 1;
+            return;
+        }
+        fresh.push({ line, index });
+    });
+    if (fresh.length === 0)
+        return { forwarded: 0, reason: "nothing_new" };
+    const taken = fresh.slice(0, MAX_LINES_PER_TICK);
+    const events = taken.filter(({ line }) => FORWARDED_EVENTS.has(line.event)).map(({ line }) => memoryGuardReceipt(line));
+    try {
+        if (events.length > 0)
+            await options.report(events);
+    }
+    catch (error) {
+        console.error(`${TAG} receipts not queued; the cursor stays and the next tick retries`, JSON.stringify({ reason: "report_threw", count: events.length, error_name: error instanceof Error ? error.name : typeof error }));
+        return { forwarded: 0, reason: "report_threw" };
+    }
+    const last = taken[taken.length - 1];
+    const next = { ts: last.line.ts, ts_lines: lines.filter((line, index) => line.ts === last.line.ts && index <= last.index).length };
+    try {
+        await mkdir(path.dirname(cursorPath), { recursive: true });
+        await writeFile(`${cursorPath}.tmp`, JSON.stringify(next), "utf8");
+        await rename(`${cursorPath}.tmp`, cursorPath);
+    }
+    catch (error) {
+        console.error(`${TAG} cursor not written; the next tick re-sends these receipts`, JSON.stringify({ reason: "cursor_write_failed", error_name: error instanceof Error ? error.name : typeof error }));
+    }
+    console.error(`${TAG} forwarded`, JSON.stringify({ reason: "forwarded", receipts: events.length, lines: taken.length, remaining: fresh.length - taken.length }));
+    return { forwarded: events.length, reason: "forwarded" };
+}

package/dist/memory-guard-script-darwin.js

@@ -0,0 +1,128 @@
+import { MEMORY_GUARD_KIND_PATTERNS, MEMORY_GUARD_LOG_KEEP_LINES, MEMORY_GUARD_LOG_LIMIT_BYTES, MEMORY_GUARD_ORPHAN_MIN_AGE_SECONDS, } from "./memory-guard-contract.js";
+import { shellQuote } from "./autostart-darwin-plist.js";
+/**
+ * The macOS memory guard (BLI-23571): a bash loop launchd keeps alive.
+ *
+ * Every 2 s it reads the kernel's memory-pressure level and a cheap `ps` RSS check. Every 10 s (every 2 s
+ * under critical pressure) it scans real memory FOOTPRINT with `top -o mem`, because RSS alone misses
+ * runaways: swapped and compressed pages leave RSS, and an 800 MB buffer showed 12 MB RSS. The limit
+ * tightens with pressure. Every 60 s it reaps vitest workers orphaned by a dead runner (ppid 1, older than
+ * 5 minutes). Only a process whose executable is `node` is ever touched; the guard never kills itself.
+ *
+ * It logs one JSON line per decision to the state dir: ids, sizes and a sha256 prefix, never a command
+ * line (those carry tokens). Test seams, all env: `MEMGUARD_SOURCE_ONLY=1` defines the functions and
+ * returns, `MEMGUARD_ONCE=1` runs one tick and exits, `MEMGUARD_NO_NOTIFY=1` skips the notification,
+ * `MEMGUARD_ONLY_PID=<pid>` restricts kills to one process so a test cannot shoot its own runner.
+ */
+export function renderDarwinMemoryGuardScript(options) {
+    const kindChecks = MEMORY_GUARD_KIND_PATTERNS.map(([kind, pattern]) => `  re=${shellQuote(pattern)}; [[ "$1" =~ $re ]] && { echo ${kind}; return; }`);
+    return [
+        "#!/bin/bash",
+        "# BLI Cockpit memory guard (BLI-23571). Rendered by `cockpit autostart install`; do not edit, it is rewritten.",
+        "# Kills a runaway node process by memory footprint. Log: memory-guard.log in the collector state dir.",
+        `LIMIT_MB=${options.limits.hard}`,
+        `WARN_LIMIT_MB=${options.limits.warning}`,
+        `CRITICAL_LIMIT_MB=${options.limits.critical}`,
+        `ORPHAN_MIN_AGE_S=${MEMORY_GUARD_ORPHAN_MIN_AGE_SECONDS}`,
+        `LOG=${shellQuote(options.logPath)}`,
+        `LOG_LIMIT_BYTES=${MEMORY_GUARD_LOG_LIMIT_BYTES}`,
+        `LOG_KEEP_LINES=${MEMORY_GUARD_LOG_KEEP_LINES}`,
+        'mkdir -p "$(dirname "$LOG")"',
+        "",
+        "now_iso() { date -u +%Y-%m-%dT%H:%M:%SZ; }",
+        "",
+        "# event pid footprint_mb limit_mb reason kind cmd_sha256. Every value is a number or a fixed token.",
+        "log_json() {",
+        `  printf '{"ts":"%s","event":"%s","pid":%s,"footprint_mb":%s,"limit_mb":%s,"reason":"%s","kind":"%s","cmd_sha256":"%s"}\\n' \\`,
+        '    "$(now_iso)" "$1" "$2" "$3" "$4" "$5" "$6" "$7" >> "$LOG"',
+        "}",
+        "",
+        "notify() { [ \"${MEMGUARD_NO_NOTIFY:-}\" = 1 ] || osascript -e \"display notification \\\"$1\\\" with title \\\"Tower\\\"\" >/dev/null 2>&1 & }",
+        "",
+        "# The coarse label for a command line. The same table as the Windows guard and the CLI's tests.",
+        "classify_kind() {",
+        "  local re",
+        ...kindChecks,
+        "  echo other",
+        "}",
+        "",
+        "cmd_sha() { printf '%s' \"$1\" | shasum -a 256 | cut -c1-12; }",
+        "",
+        "to_mb() { # top MEM like 470M, 69G, 512K, 1024B, with an optional +/- suffix",
+        '  local v="${1%[+-]}" n u',
+        '  n="${v%[BKMGT]}"; u="${v: -1}"',
+        '  case "$u" in B) echo $((n / 1048576)) ;; K) echo $((n / 1024)) ;; M) echo "$n" ;; G) echo $((n * 1024)) ;; T) echo $((n * 1048576)) ;; *) echo 0 ;; esac',
+        "}",
+        "",
+        "kill_node() { # pid footprint_mb limit_mb reason",
+        '  local cmd kind sha result',
+        '  [ "$1" = "$$" ] && return',
+        '  [ -n "${MEMGUARD_ONLY_PID:-}" ] && [ "$1" != "$MEMGUARD_ONLY_PID" ] && return',
+        '  cmd="$(ps -o command= -p "$1" 2>/dev/null | cut -c1-2000)"',
+        '  kind="$(classify_kind "$cmd")"; sha="$(cmd_sha "$cmd")"',
+        "  kill -9 \"$1\" 2>/dev/null && result=killed || result=kill_failed",
+        '  log_json "$result" "$1" "$2" "$3" "$4" "$kind" "$sha"',
+        '  if [ "$result" = killed ]; then',
+        '    if [ "$2" -ge 1024 ]; then notify "Tower killed a runaway node process ($(( ($2 + 512) / 1024 )) GB, $kind)"; else notify "Tower killed a runaway node process ($2 MB, $kind)"; fi',
+        "  fi",
+        "}",
+        "",
+        "# 1 normal, 2 warning, 4 critical",
+        "pressure_level() { sysctl -n kern.memorystatus_vm_pressure_level 2>/dev/null || echo 1; }",
+        "",
+        "footprint_scan() { # limit_mb reason",
+        "  top -l 1 -o mem -n 25 -stats pid,mem,command 2>/dev/null | awk 'NR>1 && $1 ~ /^[0-9]+$/' |",
+        "    while read -r pid mem comm _; do",
+        '      case "$comm" in node) ;; *) continue ;; esac',
+        '      mb="$(to_mb "$mem")"',
+        '      [ "$mb" -gt "$1" ] 2>/dev/null && kill_node "$pid" "$mb" "$1" "$2"',
+        "    done",
+        "}",
+        "",
+        "rss_scan() { # limit_mb; the cheap every-tick check on resident memory alone",
+        `  ps -axo pid=,rss=,comm= | awk -v lim="$(($1 * 1024))" '$3 ~ /(^|\\/)node$/ && $2 > lim {print $1, int($2/1024)}' |`,
+        '    while read -r pid mb; do kill_node "$pid" "$mb" "$1" rss_over_limit; done',
+        "}",
+        "",
+        "orphan_vitest_scan() { # vitest workers whose runner died (ppid 1) and that outlived the grace period",
+        "  ps -axo pid=,ppid=,etime=,command= | awk '$2 == 1 && $4 ~ /(^|\\/)node$/ && $0 ~ /vitest\\/dist\\/workers\\/forks|vitest\\/dist\\/workers\\/threads|node \\(vitest/ {print $1, $3}' |",
+        "    while read -r pid etime; do",
+        `      secs="$(echo "$etime" | awk -F'[-:]' '{n=NF; s=$n+($(n-1))*60; if(n>=3)s+=$(n-2)*3600; if(n==4)s+=$1*86400; print s}')"`,
+        '      [ "$secs" -ge "$ORPHAN_MIN_AGE_S" ] 2>/dev/null || continue',
+        '      [ -n "${MEMGUARD_ONLY_PID:-}" ] && [ "$pid" != "$MEMGUARD_ONLY_PID" ] && continue',
+        '      cmd="$(ps -o command= -p "$pid" 2>/dev/null | cut -c1-2000)"',
+        '      kill -9 "$pid" 2>/dev/null && log_json orphan_reaped "$pid" 0 0 orphan_vitest_worker "$(classify_kind "$cmd")" "$(cmd_sha "$cmd")"',
+        "    done",
+        "}",
+        "",
+        "trim_log() { # keep the log small: past the cap, keep the newest lines",
+        '  local size; size="$(wc -c < "$LOG" 2>/dev/null | tr -d \' \')"',
+        '  [ "${size:-0}" -gt "$LOG_LIMIT_BYTES" ] 2>/dev/null || return 0',
+        '  tail -n "$LOG_KEEP_LINES" "$LOG" > "$LOG.tmp" 2>/dev/null && mv "$LOG.tmp" "$LOG"',
+        "}",
+        "",
+        '[ "${MEMGUARD_SOURCE_ONLY:-}" = 1 ] && return 0 2>/dev/null',
+        "",
+        'log_json started "$$" 0 "$LIMIT_MB" started guard ""',
+        "tick=0",
+        "while :; do",
+        '  level="$(pressure_level)"',
+        '  if [ "$level" -ge 4 ] 2>/dev/null; then',
+        '    rss_scan "$CRITICAL_LIMIT_MB"',
+        '    footprint_scan "$CRITICAL_LIMIT_MB" pressure_critical',
+        '  elif [ "$level" -ge 2 ] 2>/dev/null; then',
+        '    rss_scan "$WARN_LIMIT_MB"',
+        '    [ $((tick % 5)) -eq 0 ] && footprint_scan "$WARN_LIMIT_MB" pressure_warning',
+        "  else",
+        '    rss_scan "$LIMIT_MB"',
+        '    [ $((tick % 5)) -eq 0 ] && footprint_scan "$LIMIT_MB" footprint_over_limit',
+        "  fi",
+        '  [ $((tick % 30)) -eq 0 ] && orphan_vitest_scan',
+        '  [ $((tick % 30)) -eq 15 ] && trim_log',
+        '  [ "${MEMGUARD_ONCE:-}" = 1 ] && exit 0',
+        "  tick=$((tick + 1))",
+        "  sleep 2",
+        "done",
+        "",
+    ].join("\n");
+}

package/dist/memory-guard-script-windows.js

@@ -0,0 +1,144 @@
+import { MEMORY_GUARD_KIND_PATTERNS, MEMORY_GUARD_LOG_KEEP_LINES, MEMORY_GUARD_LOG_LIMIT_BYTES, MEMORY_GUARD_ORPHAN_MIN_AGE_SECONDS, } from "./memory-guard-contract.js";
+import { powershellLiteral } from "./autostart-windows-scripts.js";
+/**
+ * The Windows memory guard (BLI-23571): a resident PowerShell loop behind the same hidden wscript launcher
+ * the sync job uses. Windows has no `top -o mem` footprint, so the analogue is PrivateMemorySize64 (the
+ * commit charge, which counts pages swapped to the pagefile). Pressure comes from free physical memory:
+ * under 10% free is a warning, under 5% is critical, read at most every 10 s. Only `node` processes are
+ * touched, never the guard's own PID. Orphaned vitest workers (parent PID no longer alive, command line
+ * contains `vitest`, older than 5 minutes) are reaped once a minute through Win32_Process.
+ *
+ * Same log contract as the macOS guard: one JSON line per decision, a kind label and a sha256 prefix of
+ * the command line, never the command line. NOT proven on a real Windows host from this repo's CI: the
+ * rendering is tested, the live behaviour is not.
+ */
+export function renderWindowsMemoryGuardScript(options) {
+    const kindChecks = MEMORY_GUARD_KIND_PATTERNS.map(([kind, pattern]) => `  if ($Command -match ${powershellLiteral(pattern)}) { return '${kind}' }`);
+    return [
+        "$ErrorActionPreference = 'Continue'",
+        `$limitMb = ${options.limits.hard}`,
+        `$warnLimitMb = ${options.limits.warning}`,
+        `$criticalLimitMb = ${options.limits.critical}`,
+        `$orphanMinAgeSeconds = ${MEMORY_GUARD_ORPHAN_MIN_AGE_SECONDS}`,
+        `$logPath = ${powershellLiteral(options.logPath)}`,
+        `$logLimitBytes = ${MEMORY_GUARD_LOG_LIMIT_BYTES}`,
+        `$logKeepLines = ${MEMORY_GUARD_LOG_KEEP_LINES}`,
+        "# One resident copy per user session; a second instance leaves quietly.",
+        "$guardMutex = New-Object System.Threading.Mutex($false, 'Local\\BLICockpitMemoryGuard')",
+        "if (-not $guardMutex.WaitOne(0)) { exit 0 }",
+        "",
+        "function Write-GuardLog([string]$EventName, [int]$ProcessId, [int]$FootprintMb, [int]$LimitMb, [string]$Reason, [string]$Kind, [string]$Sha) {",
+        "  $ts = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')",
+        '  $line = \'{"ts":"\' + $ts + \'","event":"\' + $EventName + \'","pid":\' + $ProcessId + \',"footprint_mb":\' + $FootprintMb + \',"limit_mb":\' + $LimitMb + \',"reason":"\' + $Reason + \'","kind":"\' + $Kind + \'","cmd_sha256":"\' + $Sha + \'"}\'',
+        "  Add-Content -LiteralPath $logPath -Encoding UTF8 -Value $line",
+        "}",
+        "",
+        "# The coarse label for a command line. The same table as the macOS guard and the CLI's tests.",
+        "function Get-GuardKind([string]$Command) {",
+        ...kindChecks,
+        "  return 'other'",
+        "}",
+        "",
+        "function Get-GuardSha([string]$Command) {",
+        "  $sha = [System.Security.Cryptography.SHA256]::Create()",
+        "  $bytes = $sha.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($Command))",
+        "  return (($bytes | ForEach-Object { $_.ToString('x2') }) -join '').Substring(0, 12)",
+        "}",
+        "",
+        "function Stop-Runaway($Process, [int]$FootprintMb, [int]$LimitMb, [string]$Reason) {",
+        "  if ($Process.Id -eq $PID) { return }",
+        "  $command = ''",
+        "  try { $command = [string](Get-CimInstance Win32_Process -Filter \"ProcessId=$($Process.Id)\" -ErrorAction Stop).CommandLine } catch { $command = '' } # an unreadable command line only loses the kind label (other)",
+        "  $kind = Get-GuardKind $command",
+        "  $sha = Get-GuardSha $command",
+        "  try {",
+        "    Stop-Process -Id $Process.Id -Force -ErrorAction Stop",
+        "    Write-GuardLog 'killed' $Process.Id $FootprintMb $LimitMb $Reason $kind $sha",
+        "  } catch {",
+        "    Write-GuardLog 'kill_failed' $Process.Id $FootprintMb $LimitMb $Reason $kind $sha",
+        "  }",
+        "}",
+        "",
+        "# 1 normal, 2 warning (<10% free physical memory), 4 critical (<5%).",
+        "function Get-PressureLevel {",
+        "  try {",
+        "    $os = Get-CimInstance Win32_OperatingSystem -ErrorAction Stop",
+        "    $freePercent = ($os.FreePhysicalMemory / $os.TotalVisibleMemorySize) * 100",
+        "    if ($freePercent -lt 5) { return 4 }",
+        "    if ($freePercent -lt 10) { return 2 }",
+        "  } catch { return 1 } # pressure unreadable: judge by the normal limit",
+        "  return 1",
+        "}",
+        "",
+        "function Remove-OrphanVitest {",
+        "  $alive = @{}",
+        "  Get-Process -ErrorAction SilentlyContinue | ForEach-Object { $alive[[int]$_.Id] = $true }",
+        "  $now = Get-Date",
+        "  Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" -ErrorAction SilentlyContinue | ForEach-Object {",
+        "    if ($_.ProcessId -eq $PID) { return }",
+        "    if (-not $_.CommandLine -or $_.CommandLine -notmatch 'vitest') { return }",
+        "    if ($alive.ContainsKey([int]$_.ParentProcessId)) { return }",
+        "    if (-not $_.CreationDate -or ($now - $_.CreationDate).TotalSeconds -lt $orphanMinAgeSeconds) { return }",
+        "    try {",
+        "      Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop",
+        "      Write-GuardLog 'orphan_reaped' $_.ProcessId 0 0 'orphan_vitest_worker' (Get-GuardKind $_.CommandLine) (Get-GuardSha $_.CommandLine)",
+        "    } catch {",
+        "      Write-GuardLog 'kill_failed' $_.ProcessId 0 0 'orphan_vitest_worker' (Get-GuardKind $_.CommandLine) (Get-GuardSha $_.CommandLine)",
+        "    }",
+        "  }",
+        "}",
+        "",
+        "function Limit-GuardLog {",
+        "  $file = Get-Item -LiteralPath $logPath -ErrorAction SilentlyContinue",
+        "  if ($file -and $file.Length -gt $logLimitBytes) {",
+        "    $keep = Get-Content -LiteralPath $logPath -Tail $logKeepLines",
+        "    Set-Content -LiteralPath $logPath -Value $keep -Encoding UTF8",
+        "  }",
+        "}",
+        "",
+        "New-Item -ItemType Directory -Force -Path (Split-Path -Parent $logPath) | Out-Null",
+        "Write-GuardLog 'started' $PID 0 $limitMb 'started' 'guard' ''",
+        "$level = 1",
+        "$lastPressure = [DateTime]::MinValue",
+        "$lastOrphan = Get-Date",
+        "while ($true) {",
+        "  $now = Get-Date",
+        "  if (($now - $lastPressure).TotalSeconds -ge 10) { $level = Get-PressureLevel; $lastPressure = $now }",
+        "  $limit = $limitMb; $footprintReason = 'footprint_over_limit'",
+        "  if ($level -ge 4) { $limit = $criticalLimitMb; $footprintReason = 'pressure_critical' }",
+        "  elseif ($level -ge 2) { $limit = $warnLimitMb; $footprintReason = 'pressure_warning' }",
+        "  foreach ($p in @(Get-Process -Name node -ErrorAction SilentlyContinue)) {",
+        "    $workingMb = [int]($p.WorkingSet64 / 1MB)",
+        "    $privateMb = [int]($p.PrivateMemorySize64 / 1MB)",
+        "    if ($workingMb -gt $limit) { Stop-Runaway $p $workingMb $limit 'rss_over_limit' }",
+        "    elseif ($privateMb -gt $limit) { Stop-Runaway $p $privateMb $limit $footprintReason }",
+        "  }",
+        "  if (($now - $lastOrphan).TotalSeconds -ge 60) { Remove-OrphanVitest; Limit-GuardLog; $lastOrphan = $now }",
+        "  Start-Sleep -Seconds 5",
+        "}",
+        "",
+    ].join("\r\n");
+}
+/**
+ * Registers the guard as a logon task that restarts on failure, has no execution time limit, and starts
+ * immediately. Any older resident copy is stopped first so a re-install runs the new script, not the old.
+ */
+export function renderWindowsMemoryGuardRegistration(options) {
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        `$taskName = ${powershellLiteral(options.taskName)}`,
+        `$launcherPath = ${powershellLiteral(options.launcherPath)}`,
+        "$wscriptPath = Join-Path (Join-Path $env:SystemRoot 'System32') 'wscript.exe'",
+        "$identity = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name",
+        "$action = New-ScheduledTaskAction -Execute $wscriptPath -Argument ('//B \"' + $launcherPath + '\"')",
+        "$trigger = New-ScheduledTaskTrigger -AtLogOn -User $identity",
+        "$principal = New-ScheduledTaskPrincipal -UserId $identity -LogonType Interactive -RunLevel Limited",
+        "$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable -MultipleInstances IgnoreNew -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -ExecutionTimeLimit (New-TimeSpan -Seconds 0)",
+        "Register-ScheduledTask -TaskName $taskName -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force | Out-Null",
+        `# A running older copy keeps the old limits and script: stop it, then start the registered one.`,
+        "Stop-ScheduledTask -TaskName $taskName -ErrorAction SilentlyContinue",
+        `Get-CimInstance Win32_Process -Filter "Name='powershell.exe'" -ErrorAction SilentlyContinue | Where-Object { $_.CommandLine -like '*${options.scriptName}*' -and $_.ProcessId -ne $PID } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }`,
+        "Start-ScheduledTask -TaskName $taskName",
+        "",
+    ].join("\r\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.280",
+  "version": "0.2.282",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-surface-doors.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-exit-contract.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-cli-doctor-json.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.87",
+    "@bli-cockpit/memory-mcp": "0.1.88",
     "@bli-cockpit/mcp": "0.1.171",
     "@bli-cockpit/telemetry-core": "0.1.94",
     "unpdf": "1.8.1"