@bli-cockpit/cli 0.2.281 → 0.2.283

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/local-args-tower-notes.js

@@ -55,6 +55,7 @@ const NOTES_ACTIONS = new Set([
     "bot-upcoming",
     "record",
     "app",
+    "review",
 ]);
 /** Actions whose first positional is the note it acts on. */
 const NOTES_ACTIONS_NEEDING_A_NOTE = new Set([
@@ -110,6 +111,9 @@ const NOTES_ALLOWED_FLAGS = [
     // transcript was stored cut short. A FLAG, not a verb: it is the same sync
     // door with a different request.
     "--repair-truncated",
+    // BLI-22350. `review <note-id> --submit` reads `{ raw_hash, answers }` from stdin; `--accept-all` sends the defaults.
+    "--submit",
+    "--accept-all",
 ];
 const NOTES_VALUE_FLAGS = [
     "--home",
@@ -150,6 +154,7 @@ export function parseNotesArgs(args) {
         throw new Error("notes rename needs --name <name>.");
     const { to, clearShelf } = readNotesShelfTarget(action, values);
     const repairTruncated = readRepairTruncated(action, values);
+    const review = readReviewRequest(action, values, rest);
     const { limit, month, offset } = readNotesWindow(action, values);
     return {
         kind: "notes",
@@ -184,6 +189,7 @@ export function parseNotesArgs(args) {
         ...(month ? { month } : {}),
         ...(offset === undefined ? {} : { offset }),
         ...(repairTruncated ? { repairTruncated: true } : {}),
+        ...review,
         yes,
         json,
     };
@@ -193,7 +199,7 @@ function readNotesAction(first) {
     // almost always wants — same reasoning as bare `cockpit` running convergence.
     const action = (first === undefined ? "list" : first);
     if (!NOTES_ACTIONS.has(action)) {
-        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, summarize, move, place, accounts, connect, detach, sync, sync-status, recordings, recording, webhook, granola-status, or transcription-stats (and record start|stop|status|cancel, app install|uninstall|status).`);
+        throw new Error(`Unknown notes command: ${first}. Try list, show, shelf, shelves, upload, paste, share, unshare, summarize, move, place, accounts, connect, detach, sync, sync-status, recordings, recording, webhook, granola-status, transcription-stats, or review (and record start|stop|status|cancel, app install|uninstall|status).`);
     }
     return action;
 }
@@ -220,6 +226,23 @@ function readAppRequest(rest) {
         throw new Error(`notes app ${verb} does not take "${rest[1]}".`);
     return { appAction: verb };
 }
+/** BLI-22350: `review [<note-id>] [--submit|--accept-all]`. Bare lists mine; an id shows one; a flag answers it. */
+function readReviewRequest(action, values, rest) {
+    const flag = values.booleans.has("--submit") ? "--submit" : values.booleans.has("--accept-all") ? "--accept-all" : null;
+    if (action !== "review") {
+        if (flag)
+            throw new Error(`${flag} belongs to \`cockpit notes review <note-id> ${flag}\`.`);
+        return {};
+    }
+    if (rest.length > 1)
+        throw new Error(`notes review takes one note id, not ${rest.length}.`);
+    const noteId = optionalNonEmpty(rest[0]);
+    if (values.booleans.has("--submit") && values.booleans.has("--accept-all"))
+        throw new Error("notes review takes --submit or --accept-all, not both.");
+    if (flag && !noteId)
+        throw new Error(`notes review ${flag} needs a note id: cockpit notes review <note-id> ${flag}.`);
+    return { ...(noteId ? { noteId } : {}), ...(flag === "--submit" ? { submit: true } : {}), ...(flag === "--accept-all" ? { acceptAll: true } : {}) };
+}
 function readRepairTruncated(action, values) {
     const repairTruncated = values.booleans.has("--repair-truncated");
     if (repairTruncated && action !== "sync") {
@@ -328,6 +351,7 @@ function readNotesPaths(action, rest) {
     const takesNoPositional = action !== "paste"
         && action !== "record"
         && action !== "app"
+        && action !== "review"
         && action !== "connect"
         && action !== "sync"
         && action !== "sync-status"

package/dist/commands/local-help-notes.js

@@ -3,7 +3,7 @@ export const NOTES_HELP = [
     [
         "notes",
         [
-            "Usage: cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|summarize <id>|move <id>|accounts|connect|detach <id>|sync <id>|sync-status [<id>]|recordings <note-id>|recording <id>|record start|stop|status|cancel|app install|uninstall|status] [flags]",
+            "Usage: cockpit notes [list|show <id>|shelf|shelves|folders|mkdir <path>|rmdir <path>|rename <path>|upload <paths...> [--wait]|paste|share <id>|unshare <id>|summarize <id>|move <id>|accounts|connect|detach <id>|sync <id>|sync-status [<id>]|recordings <note-id>|recording <id>|record start|stop|status|cancel|app install|uninstall|status|review [<note-id>] [--submit|--accept-all]] [flags]",
             "Audio uploads: MP3, M4A, WAV, WebM and OGG, up to 1 GB. Over 4 MB (a whole meeting) the file goes straight to storage and is transcribed in the background; --wait then polls for up to 4 hours and prints progress, otherwise for at most 330 seconds.",
             "",
             "record start|stop [<session-id>]|status|cancel — record a meeting in a room from this machine's microphone (Apple Silicon macOS and Windows; Linux says it is not supported). On Windows the microphone needs Settings > Privacy & security > Microphone on, including Let desktop apps access your microphone. Nothing leaves the machine while recording; the recorder stops by itself after 8 hours (under the 1 GB upload limit). `stop` uploads the whole original recording, silence included, and Tower writes a note with Speaker 1, Speaker 2... lines, or says no speech was detected (add --wait to watch the transcription). `cancel` stops and KEEPS the file; `status` lists what is recording and every session waiting for upload (`needs_upload`); `stop <session-id>` uploads a cancelled, crashed or auto-stopped session. The BLI Notetaker app uploads waiting sessions by itself. The recording also stays on this machine.",
@@ -42,6 +42,7 @@ export const NOTES_HELP = [
             "bot-upcoming [--json] — your own Google Meet meetings today that the bot will join, with claim state. Decline or mark private to opt out.",
             "granola-status [--limit <n>] [--json] — the Granola cron's own last several runs (ticket 10718): reason, counts, model, spend and which lookback it used. Granola runs on a shared server-side key, not a connected account, so this is its own read rather than `accounts`.",
             "transcription-stats [--month YYYY-MM] [--json] — what meeting transcription cost and did (BLI-18003): minutes, dollars (list and real), requests, failures and fallbacks per provider for the UTC month (default: this one), the spend against the monthly cap and how close the 80% message and the hold are, how many meetings are waiting for budget, which provider keys the deploy holds (by name), and how old the numbers are. Switch providers or move the cap with `cockpit settings switches set transcription.provider|transcription.fallback_chain|transcription.monthly_cap_usd <value>`.",
+            "review [<note-id>] [--submit|--accept-all] [--json] — the meeting reviews waiting for you (BLI-22350). A recorded meeting stays with its attendees until one of them clears one review screen: who's who, lines the raw transcript may have put under the wrong speaker, unclear words, spots where the clean-up may have changed the meaning, sensitive moments. Bare `review` lists yours (waiting, being applied, cleared in the last 7 days). `review <note-id>` shows one in that order with every default answer; --json prints the raw read (raw_hash, items, defaults). `--accept-all` submits every default (names as guessed, lines kept, best-guess readings, the words as said where the meaning may have changed, sensitive moments to attendees only) and prints what it accepted. `--submit` reads { \"raw_hash\": ..., \"answers\": [...] } from stdin: edit the defaults from --json and pipe them in. A refusal says to reload when the review changed (stale_raw_hash, stale_guess) or names what is wrong with the answers. Same door as the web screen (/meeting-notes/<note-id>/review) and the notes_review_* MCP tools.",
             "A large note is read by a model on the server and can take a couple of minutes; the terminal says so before it waits.",
             "--json writes one machine-readable object to stdout; every reason, receipt and progress line stays on stderr.",
             "Sharing and moving need a signed-in session the database can see. If this deployment cannot mint one, they are refused as needs_signed_in_session rather than done with no permission check — and reads say when they came back narrower than the browser's.",