@bli-cockpit/cli 0.2.281 → 0.2.283

package/dist/commands/notes-review.js

@@ -0,0 +1,204 @@
+/**
+ * `cockpit notes review [<note-id>] [--submit|--accept-all] [--json]` (BLI-22350): the attendee's meeting review in
+ * the terminal. Sibling of `notes.ts`, named in its header. Owner doc: `docs/runbooks/meeting-review-screen.md`.
+ *
+ *   review                       the reviews waiting for me (GET /api/notes/review)
+ *   review <id>                  one review, in the screen's order (GET /api/notes/review/<id>); --json is the raw read
+ *   review <id> --submit         `{ raw_hash, answers }` JSON from stdin (POST /api/notes/review/<id>)
+ *   review <id> --accept-all     read, then submit every item's default answer, and print what it accepted
+ *
+ * The same doors the web screen and the `notes_review_*` MCP tools call; the database decides who is a reviewer. This
+ * file holds no rule about answers: the door checks them and its refusal (reason and sentence) is relayed verbatim.
+ */
+import { isInteractiveStdin, readPipedText, writeLine } from "./cli-io.js";
+import { ask, emit, errorText, fail, READ_DEADLINE_MS } from "./notes-door.js";
+const WRITE_DEADLINE_MS = 60_000;
+/** A review's answers are a few dozen short objects; this is far above any real one. */
+const SUBMIT_MAX_CHARS = 512_000;
+/** The dashboard's `review-words.ts` sentence, repeated here: this package does not import the dashboard. */
+const AS_TRANSCRIBED_LINE = "This meeting is kept as transcribed; only the speakers need confirming.";
+/** The web screen's plain label per meaning-check issue, repeated here for the same reason. */
+const MEANING_ISSUE_WORDS = {
+    number: "A number may have changed",
+    negation_or_pronoun: "A 'not' or a 'we/you' may have flipped",
+    hedge_or_correction: "A 'maybe' or a correction may have been dropped",
+    added_words: "Words may have been added",
+    unclear_made_sensible: "An unclear bit may have been made to sound sensible",
+    speaker_moved: "A line may have been moved to another speaker",
+    passage_left_out: "A passage may have been left out",
+    other: "The meaning may have changed",
+};
+const STATE_WORDS = {
+    queued: "waiting for Tower to prepare it",
+    preparing: "being prepared (transcript cleaned and checked)",
+    awaiting_attendee: "waiting for your answers",
+    applying: "answered; Tower is applying the answers",
+    cleared: "cleared",
+    failed: "stuck; an engineer has been told",
+};
+const reviewPath = (noteId) => `/api/notes/review/${encodeURIComponent(noteId)}`;
+export async function runNotesReview(command, door) {
+    if (!command.noteId)
+        return listReviews(door);
+    if (command.submit)
+        return submitFromStdin(command.noteId, door);
+    if (command.acceptAll)
+        return acceptAll(command.noteId, door);
+    return showReview(command.noteId, door);
+}
+async function listReviews(door) {
+    const answer = await ask(door, { path: "/api/notes/review", method: "GET", label: "notes review", timeoutMs: READ_DEADLINE_MS });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const body = answer.body;
+    if (door.json)
+        return emit(door, { ok: true, ...body });
+    const out = door.io.stdout;
+    if (body.reviews.length === 0) {
+        writeLine(out, "No meeting reviews for you: nothing waits, and nothing was cleared in the last 7 days.");
+        return 0;
+    }
+    writeLine(out, `${body.waiting} meeting(s) wait for your review.`);
+    for (const row of body.reviews) {
+        writeLine(out, `${row.note_id}  ${row.meeting_date}  ${row.item_count} item(s)  ${STATE_WORDS[row.state] ?? row.state}  ${row.note_title ?? "(untitled meeting)"}`);
+    }
+    writeLine(out, `Open one: cockpit notes review <note-id>, or ${door.dashboardUrl}/meeting-notes/<note-id>/review in a browser.`);
+    return 0;
+}
+async function readOne(noteId, door) {
+    return ask(door, { path: reviewPath(noteId), method: "GET", label: "notes review", timeoutMs: READ_DEADLINE_MS });
+}
+function lines(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (typeof value === "string")
+        return value.trim() ? [value.trim()] : [];
+    if (Array.isArray(value))
+        return value.flatMap((entry) => (typeof entry === "string" ? [entry] : [JSON.stringify(entry)]));
+    return [JSON.stringify(value)];
+}
+/**
+ * The review in the screen's order: who's who, lines under the wrong speaker, unclear words, meaning checks,
+ * sensitive moments.
+ */
+/** A meaning check's stretch is one or more transcript lines: the label on the first, the rest indented under it. */
+function stretch(label, text) {
+    const [first = "", ...rest] = text.split(/\r?\n/);
+    const pad = " ".repeat(label.length + 5);
+    return [`    ${label} ${first}`, ...rest.map((line) => `${pad}${line}`)];
+}
+export function renderReview(body, dashboardUrl) {
+    const out = [];
+    out.push(`${body.note_title ?? "Meeting"}${body.meeting_date ? `, ${body.meeting_date}` : ""}: ${STATE_WORDS[body.state] ?? body.state}.`);
+    const of = (kind) => body.items.filter((item) => item.kind === kind);
+    const speakers = of("speaker");
+    if (speakers.length)
+        out.push("", "Who's who (the name you confirm or correct):");
+    for (const item of speakers) {
+        out.push(`  ${item.label}: ${item.guess || "(no guess; leave empty to keep the label)"} [${item.id}]`, `    why: ${item.reasoning}`);
+        for (const quote of item.quotes ?? [])
+            out.push(`    ${quote.timestamp} "${quote.text}"`);
+    }
+    const moved = of("speaker_line");
+    if (moved.length)
+        out.push("", "Lines that may be under the wrong speaker (default: keep):");
+    for (const item of moved)
+        out.push(`  ${item.timestamp} under ${item.guess || "(no speaker)"}: "${item.quote.text}" [${item.id}]`);
+    const unclear = of("unclear");
+    if (unclear.length)
+        out.push("", "Unclear words (default: the best guess):");
+    for (const item of unclear) {
+        out.push(`  ${item.timestamp} "${item.words}" -> ${item.guess || "(keep marked unclear)"}${item.changesMeaning ? "  CHANGES THE MEANING" : ""} [${item.id}]`, `    context: ${item.context}`);
+    }
+    const meaning = of("meaning_check");
+    if (meaning.length)
+        out.push("", "Did the clean-up change the meaning? (default: keep the words as said; answer \"raw\" or \"cleaned\"):");
+    for (const item of meaning) {
+        out.push(`  ${item.timestamp} ${MEANING_ISSUE_WORDS[item.issue] ?? MEANING_ISSUE_WORDS.other} [${item.id}]`);
+        if (item.said || item.written)
+            out.push(`    "${item.said}" -> "${item.written}"`);
+        out.push(...stretch("as said:      ", item.raw), ...stretch("as cleaned up:", item.cleaned));
+    }
+    const sensitive = of("sensitive");
+    if (sensitive.length)
+        out.push("", "Sensitive moments (default: attendees only):");
+    for (const item of sensitive)
+        out.push(`  ${item.timestamp} ${item.what} [${item.id}]`);
+    if (body.as_transcribed)
+        out.push("", AS_TRANSCRIBED_LINE);
+    else {
+        for (const [heading, value] of [["Summary", body.summary], ["Decisions", body.decisions], ["Action items", body.action_items]]) {
+            const said = lines(value);
+            if (said.length)
+                out.push("", `${heading}:`, ...said.map((line) => `  ${line}`));
+        }
+    }
+    if (body.state === "cleared" && body.attendee_notes)
+        out.push("", "Kept for the attendees only:", ...body.attendee_notes.split("\n").map((line) => `  ${line}`));
+    if (body.state === "awaiting_attendee") {
+        out.push("", `Answer: cockpit notes review ${body.note_id} --accept-all (every default above), or edit the defaults from`, `cockpit notes review ${body.note_id} --json and pipe { "raw_hash", "answers" } to cockpit notes review ${body.note_id} --submit.`, `Or open ${dashboardUrl}/meeting-notes/${body.note_id}/review.`);
+    }
+    return out;
+}
+async function showReview(noteId, door) {
+    const answer = await readOne(noteId, door);
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    if (door.json)
+        return emit(door, answer.body);
+    for (const line of renderReview(answer.body, door.dashboardUrl))
+        writeLine(door.io.stdout, line);
+    return 0;
+}
+async function post(noteId, door, body, accepted) {
+    const answer = await ask(door, { path: reviewPath(noteId), method: "POST", label: "notes review submit", timeoutMs: WRITE_DEADLINE_MS, body });
+    if (!answer.ok)
+        return fail(door, answer.reason, answer.detail);
+    const done = answer.body;
+    if (door.json)
+        return emit(door, { ok: true, ...done, ...(accepted ? { accepted } : {}) });
+    writeLine(door.io.stdout, `Submitted ${done.answers} answer(s). Tower is applying them; the meeting is released to the team once its privacy check passes.`);
+    return 0;
+}
+async function submitFromStdin(noteId, door) {
+    if (isInteractiveStdin(door.io)) {
+        return fail(door, "nothing_piped", `Pipe { "raw_hash": ..., "answers": [...] } in: cockpit notes review ${noteId} --json, edit the defaults, then pipe them to cockpit notes review ${noteId} --submit.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readPipedText(door.io.stdin, { maxChars: SUBMIT_MAX_CHARS, overflowMessage: "The answers piped in are far larger than any review." }));
+    }
+    catch (error) {
+        return fail(door, "invalid_body", `The answers piped in are not JSON (${errorText(error)}). Send { "raw_hash": ..., "answers": [...] }.`);
+    }
+    return post(noteId, door, parsed);
+}
+function acceptedWords(answer) {
+    const value = answer.answer;
+    if (answer.kind === "speaker")
+        return `speaker ${answer.guess || "(no guess)"} -> ${value === "" ? "keep the label" : String(value)}`;
+    if (answer.kind === "speaker_line")
+        return "line stays where it is";
+    if (answer.kind === "unclear") {
+        const reading = value.reading;
+        return reading === null ? "unclear word stays marked" : `unclear word -> ${reading}`;
+    }
+    if (answer.kind === "meaning_check")
+        return value === "cleaned" ? "meaning check -> keep the clean-up's words" : "meaning check -> keep the words as said";
+    return `sensitive moment -> ${String(value) === "keep_in" ? "kept in" : "attendees only"}`;
+}
+async function acceptAll(noteId, door) {
+    const read = await readOne(noteId, door);
+    if (!read.ok)
+        return fail(door, read.reason, read.detail);
+    const review = read.body;
+    if (review.state !== "awaiting_attendee") {
+        return fail(door, "review_not_awaiting_attendee", `This review is ${STATE_WORDS[review.state] ?? review.state}, so there is nothing to answer.`);
+    }
+    if (!door.json) {
+        writeLine(door.io.stdout, `Accepting ${review.defaults.length} default answer(s):`);
+        for (const answer of review.defaults)
+            writeLine(door.io.stdout, `  ${answer.item_id}: ${acceptedWords(answer)}`);
+    }
+    return post(noteId, door, { raw_hash: review.raw_hash, answers: review.defaults }, review.defaults);
+}

package/dist/commands/notes.js

@@ -40,6 +40,8 @@
  *    Notetaker app on this Mac or Windows PC (Mac LaunchAgent: `notes-app-plist.ts`; Windows: `notes-app-windows.ts`).
  *  - `notes-transcription-stats.ts` — BLI-18003: what meeting transcription
  *    cost and did per provider for a month, and the spend against the cap.
+ *  - `notes-review.ts` — BLI-22350: the meeting reviews waiting for me, one
+ *    review, and answering it (`--submit` from stdin, `--accept-all`).
  *
  * Every public name is still importable from this file.
  */
@@ -52,6 +54,7 @@ import { armNotesWebhook, connectNotetaker, detachNotetaker, listNotesAccounts,
 import { showBotUpcoming } from "./notes-bot-upcoming.js";
 import { showGranolaStatus } from "./notes-granola-status.js";
 import { showTranscriptionStats } from "./notes-transcription-stats.js";
+import { runNotesReview } from "./notes-review.js";
 import { listRecordings, showRecording } from "./notes-recordings.js";
 import { defaultRecordDeps, runNotesRecord } from "./notes-record.js";
 import { runNotesApp } from "./notes-app.js";
@@ -94,6 +97,7 @@ const NOTES_VERBS = {
     "bot-upcoming": showBotUpcoming,
     "granola-status": showGranolaStatus,
     "transcription-stats": showTranscriptionStats,
+    review: runNotesReview,
 };
 export async function runNotes(command, io) {
     // BLI-22979: recording is local until `stop` uploads, so only the upload needs the paired session.

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.281");
+    writeLine(io?.stdout ?? process.stdout, "0.2.283");
     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");
+}