@frockbot/computer-host-runtime 0.3.20 → 0.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/computer-host-runtime",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "private": false,
   "type": "module",
   "exports": {

package/src/runtime.test.ts

@@ -28,10 +28,15 @@ import {
   BROWSER_ENSURE_ACTION,
   BROWSER_FOCUS_ACTION,
   BROWSER_SURVEY_ACTION,
+  browserWatchdogScript,
   CHROME_LAUNCHER,
   CHROME_PROFILE,
   chromeLauncherScript,
+  CHROMIUM_DISABLED_FEATURES,
+  CHROMIUM_FLAGS,
+  CHROMIUM_MAX_OLD_SPACE_MIB,
   CHROMIUM_PATH,
+  CHROMIUM_RENDERER_PROCESS_LIMIT,
   COMPUTER_CDP_PORT,
   COMPUTER_DISPLAY,
   DESKTOP_SLOTS,
@@ -89,6 +94,10 @@ import {
   SLOT_IDLE_SECONDS,
   UPDATE_PHASES,
   updateLaunchScript,
+  WATCHDOG_LOG,
+  WATCHDOG_MEM_AVAILABLE_FLOOR_KIB,
+  WATCHDOG_RENDERER_RSS_LIMIT_KIB,
+  WATCHDOG_SCRIPT,
   WORKSPACES_ROOT,
 } from "./runtime.ts";
 
@@ -720,6 +729,136 @@ describe("installed shell scripts", () => {
     expect(launcher).not.toContain(`rm -rf ${CHROME_PROFILE}`);
   });
 
+  test("bounds Chromium renderers without disabling background timer throttling", () => {
+    expect(CHROMIUM_FLAGS).toContain(
+      `--renderer-process-limit=${CHROMIUM_RENDERER_PROCESS_LIMIT}`,
+    );
+    expect(CHROMIUM_FLAGS).toContain(
+      `--js-flags=--max-old-space-size=${CHROMIUM_MAX_OLD_SPACE_MIB}`,
+    );
+    expect(CHROMIUM_FLAGS).toContain(
+      `--disable-features=${CHROMIUM_DISABLED_FEATURES.join(",")}`,
+    );
+    expect(CHROMIUM_DISABLED_FEATURES).not.toContain(
+      "IntensiveWakeUpThrottling",
+    );
+  });
+
+  test("the watchdog kills an oversized renderer and leaves a bounded one running", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "frockbot-watchdog-"));
+    const oversized = Bun.spawn(["sleep", "60"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const bounded = Bun.spawn(["sleep", "60"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    try {
+      const procRoot = join(directory, "proc");
+      const renderer = async (pid: number, rssKiB: number) => {
+        const root = join(procRoot, String(pid));
+        await mkdir(root, { recursive: true });
+        await writeFile(
+          join(root, "cmdline"),
+          `/home/box/bin/chromium\0--type=renderer\0--renderer-client-id=${pid}\0`,
+        );
+        await writeFile(
+          join(root, "status"),
+          `Name:\tchromium\nState:\tS (sleeping)\nVmRSS:\t${rssKiB} kB\n`,
+        );
+      };
+      await mkdir(procRoot, { recursive: true });
+      await writeFile(
+        join(procRoot, "meminfo"),
+        "MemTotal:       8388608 kB\nMemAvailable:   4194304 kB\n",
+      );
+      await renderer(oversized.pid, WATCHDOG_RENDERER_RSS_LIMIT_KIB + 524_288);
+      await renderer(bounded.pid, WATCHDOG_RENDERER_RSS_LIMIT_KIB - 1);
+      const logPath = join(directory, "watchdog.log");
+      const watchdog = Bun.spawn(["bash"], {
+        stdin: new Blob([browserWatchdogScript]),
+        stdout: "pipe",
+        stderr: "pipe",
+        env: {
+          ...process.env,
+          FROCKBOT_WATCHDOG_ONCE: "1",
+          FROCKBOT_WATCHDOG_PROC_ROOT: procRoot,
+          FROCKBOT_WATCHDOG_LOG: logPath,
+        },
+      });
+
+      const [watchdogExit, watchdogError] = await Promise.all([
+        watchdog.exited,
+        new Response(watchdog.stderr).text(),
+      ]);
+      expect(watchdogError).toBe("");
+      expect(watchdogExit).toBe(0);
+      expect(await oversized.exited).not.toBe(0);
+      expect(bounded.exitCode).toBeNull();
+      const log = await readFile(logPath, "utf8");
+      expect(log).toContain(`pid=${oversized.pid}`);
+      expect(log).toContain("reason=renderer-rss");
+      expect(log).not.toContain(`pid=${bounded.pid}`);
+    } finally {
+      oversized.kill();
+      bounded.kill();
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  test("low available memory closes only the worst renderer needed for the floor", async () => {
+    const directory = await mkdtemp(join(tmpdir(), "frockbot-low-memory-"));
+    const worst = Bun.spawn(["sleep", "60"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    const smaller = Bun.spawn(["sleep", "60"], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    try {
+      const procRoot = join(directory, "proc");
+      await mkdir(procRoot, { recursive: true });
+      await writeFile(
+        join(procRoot, "meminfo"),
+        `MemAvailable:   ${WATCHDOG_MEM_AVAILABLE_FLOOR_KIB - 262_144} kB\n`,
+      );
+      for (const [pid, rssKiB] of [
+        [worst.pid, 393_216],
+        [smaller.pid, 262_144],
+      ] as const) {
+        const root = join(procRoot, String(pid));
+        await mkdir(root, { recursive: true });
+        await writeFile(join(root, "cmdline"), `chromium\0--type=renderer\0`);
+        await writeFile(join(root, "status"), `VmRSS:\t${rssKiB} kB\n`);
+      }
+      const logPath = join(directory, "watchdog.log");
+      const watchdog = Bun.spawn(["bash"], {
+        stdin: new Blob([browserWatchdogScript]),
+        stdout: "ignore",
+        stderr: "pipe",
+        env: {
+          ...process.env,
+          FROCKBOT_WATCHDOG_ONCE: "1",
+          FROCKBOT_WATCHDOG_PROC_ROOT: procRoot,
+          FROCKBOT_WATCHDOG_LOG: logPath,
+        },
+      });
+      expect(await watchdog.exited).toBe(0);
+      expect(await worst.exited).not.toBe(0);
+      expect(smaller.exitCode).toBeNull();
+      const log = await readFile(logPath, "utf8");
+      expect(log).toContain(`pid=${worst.pid}`);
+      expect(log).toContain("reason=low-mem-available");
+      expect(log).not.toContain(`pid=${smaller.pid}`);
+    } finally {
+      worst.kill();
+      smaller.kill();
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
   test("one screen carries every slot, and each viewer is clipped to one", () => {
     const screen = installedScript(
       provisionScript,
@@ -793,6 +932,7 @@ describe("installed shell scripts", () => {
       ENSURE_AGENT_SCRIPT,
       CONTROL_SCRIPT,
       BOUNDED_LOG_SCRIPT,
+      WATCHDOG_SCRIPT,
       CHROME_LAUNCHER,
       DOCTOR_SCRIPT,
       `${RUNTIME_ROOT}/start-gateway.sh`,
@@ -1333,6 +1473,8 @@ describe("box-doctor", () => {
         "scratch",
         "desktop-gateway",
         "sync-watcher",
+        "watchdog",
+        "memory-top",
         "browser-process",
         "browser-cdp",
         "screen",

package/src/runtime.ts

@@ -386,6 +386,22 @@ export function shellGuiCommandV1(command: string): string | undefined {
 /** The one browser profile every Bot of one User shares (ADR 0012). */
 export const CHROME_PROFILE = `${HOME_ROOT}/chrome-profile`;
 
+/** Maximum Chromium renderer processes on one shared 8 GiB Computer. */
+export const CHROMIUM_RENDERER_PROCESS_LIMIT = 8;
+/** V8 old-space ceiling in each renderer; native allocations remain possible. */
+export const CHROMIUM_MAX_OLD_SPACE_MIB = 1024;
+/**
+ * Features disabled for a shared unattended desktop.
+ *
+ * Native window occlusion is meaningless under Xvfb and can stop painting a
+ * window that is visible only through VNC. Background timer throttling stays
+ * enabled: an unattended preview tab must not earn more CPU merely because a
+ * Bot left it open.
+ */
+export const CHROMIUM_DISABLED_FEATURES = [
+  "CalculateNativeWinOcclusion",
+] as const;
+
 /** The browser flags the Computer runs chromium under, in one place. */
 export const CHROMIUM_FLAGS: readonly string[] = [
   "--no-sandbox",
@@ -401,6 +417,9 @@ export const CHROMIUM_FLAGS: readonly string[] = [
   "--window-position=0,0",
   "--no-first-run",
   "--no-default-browser-check",
+  `--renderer-process-limit=${CHROMIUM_RENDERER_PROCESS_LIMIT}`,
+  `--js-flags=--max-old-space-size=${CHROMIUM_MAX_OLD_SPACE_MIB}`,
+  `--disable-features=${CHROMIUM_DISABLED_FEATURES.join(",")}`,
 ];
 
 export const CHROME_LAUNCHER = `${BIN_ROOT}/frockbot-chrome`;
@@ -550,6 +569,84 @@ fi
 exec ${CHROME_LAUNCHER} about:blank
 `;
 
+/** The renderer watchdog, supervised independently of Chromium. */
+export const WATCHDOG_SERVICE = "frockbot-browser-watchdog";
+/** The installed watchdog executable. */
+export const WATCHDOG_SCRIPT = `${RUNTIME_ROOT}/browser-watchdog.sh`;
+/** Its bounded, durable-on-the-Computer action log. */
+export const WATCHDOG_LOG = `${RUNTIME_ROOT}/watchdog.log`;
+/** 1.5 GiB RSS: one renderer may not consume a material fraction of the box. */
+export const WATCHDOG_RENDERER_RSS_LIMIT_KIB = 1_572_864;
+/** Keep 512 MiB available for the Agent transport and ordinary commands. */
+export const WATCHDOG_MEM_AVAILABLE_FLOOR_KIB = 524_288;
+/** How often the supervised watchdog samples `/proc`. */
+export const WATCHDOG_INTERVAL_SECONDS = 30;
+/** Bound the durable diagnostic log without requiring logrotate. */
+export const WATCHDOG_LOG_MAX_LINES = 200;
+
+/**
+ * Kills only Chromium renderer processes, never the shared browser process.
+ *
+ * Every renderer over the individual ceiling is killed. Under box-wide
+ * pressure, the largest remaining renderers are killed until their reclaimed
+ * RSS would restore the available-memory floor. Chromium owns renderer crash
+ * recovery, so the browser, profile, and other Bots' windows remain resident.
+ */
+export const browserWatchdogScript = `#!/usr/bin/env bash
+set -u
+PROC_ROOT="\${FROCKBOT_WATCHDOG_PROC_ROOT:-/proc}"
+LOG="\${FROCKBOT_WATCHDOG_LOG:-${WATCHDOG_LOG}}"
+mkdir -p "$(dirname "$LOG")"
+touch "$LOG"
+
+trim_log() {
+  LINES=$(wc -l < "$LOG" 2>/dev/null || echo 0)
+  if [ "$LINES" -gt ${WATCHDOG_LOG_MAX_LINES} ]; then
+    tail -n ${WATCHDOG_LOG_MAX_LINES} "$LOG" > "$LOG.tmp" && mv "$LOG.tmp" "$LOG"
+  fi
+}
+
+while true; do
+  MEM_AVAILABLE=$(awk '/^MemAvailable:/ { print $2; exit }' "$PROC_ROOT/meminfo" 2>/dev/null || true)
+  # If the kernel did not provide a reading, keep enforcing the per-renderer
+  # bound but do not infer box-wide pressure and kill otherwise healthy tabs.
+  case "$MEM_AVAILABLE" in (''|*[!0-9]*) MEM_AVAILABLE=${WATCHDOG_MEM_AVAILABLE_FLOOR_KIB};; esac
+  CANDIDATES=$(
+    for STATUS in "$PROC_ROOT"/[0-9]*/status; do
+      [ -f "$STATUS" ] || continue
+      PID=$(basename "$(dirname "$STATUS")")
+      CMDLINE=$(tr '\\000' ' ' < "$(dirname "$STATUS")/cmdline" 2>/dev/null || true)
+      printf '%s' "$CMDLINE" | grep -q -- '--type=renderer' || continue
+      RSS=$(awk '/^VmRSS:/ { print $2; exit }' "$STATUS" 2>/dev/null || true)
+      case "$RSS" in (''|*[!0-9]*) continue;; esac
+      printf '%s %s\\n' "$RSS" "$PID"
+    done | sort -rn
+  )
+  PROJECTED_AVAILABLE=$MEM_AVAILABLE
+  while read -r RSS PID; do
+    [ -n "\${PID:-}" ] || continue
+    REASON=""
+    if [ "$RSS" -gt ${WATCHDOG_RENDERER_RSS_LIMIT_KIB} ]; then
+      REASON=renderer-rss
+    elif [ "$PROJECTED_AVAILABLE" -lt ${WATCHDOG_MEM_AVAILABLE_FLOOR_KIB} ]; then
+      REASON=low-mem-available
+    else
+      break
+    fi
+    if kill -9 "$PID" 2>/dev/null; then
+      PROJECTED_AVAILABLE=$((PROJECTED_AVAILABLE + RSS))
+      printf '%s action=closed-renderer pid=%s rssMiB=%s memAvailableMiB=%s reason=%s\\n' \
+        "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$PID" "$((RSS / 1024))" "$((MEM_AVAILABLE / 1024))" "$REASON" >> "$LOG"
+    fi
+  done <<EOF
+$CANDIDATES
+EOF
+  trim_log
+  [ "\${FROCKBOT_WATCHDOG_ONCE:-}" = 1 ] && exit 0
+  sleep ${WATCHDOG_INTERVAL_SECONDS}
+done
+`;
+
 /**
  * One Bot's viewer: an `x11vnc` clipped to that Bot's slot of the one screen.
  *
@@ -1023,6 +1120,35 @@ if (action.action === "focus") {
   await done({ focused: Boolean(focusPage), ...(anchor ? { targetId: anchor.targetId } : {}) });
 }
 
+// Lifecycle cleanup from the Computer Package. Origins come from a preview
+// process's own bounded log and the action is already scoped to this Bot, but
+// enforce the window boundary again here: a shared browser profile never
+// makes another Bot's tab ours to close. If the recorded anchor was one of the
+// closed pages, adopt a surviving tab in the same window; only create a blank
+// replacement when the window has no page left.
+if (action.action === "close-origins") {
+  const origins = new Set(action.origins);
+  const candidates = anchor ? await pagesInWindow(anchor.windowId) : [];
+  let closed = 0;
+  for (const candidate of candidates) {
+    let origin = "";
+    try {
+      origin = new URL(candidate.url()).origin;
+    } catch {}
+    if (!origins.has(origin)) continue;
+    await candidate.close();
+    closed += 1;
+  }
+  const remaining = anchor ? await pagesInWindow(anchor.windowId) : [];
+  if (remaining.length > 0) {
+    const targetId = await targetIdOf(remaining.at(-1));
+    writeFileSync(targetPath(botKey), \`\${targetId}\\n\`, { mode: 0o600 });
+  } else if (anchor) {
+    await ensureWindow(botKey);
+  }
+  await done({ closed, origins: [...origins], snapshot: "" });
+}
+
 const own = anchor ? await pagesInWindow(anchor.windowId) : [];
 const page =
   own.at(-1) ??
@@ -1265,7 +1391,7 @@ export const CLOCK_FLOOR_EPOCH = 1_756_684_800;
  * corrected. The version is compared on every adoption instead, and the whole
  * set is rewritten when it moves. Bump it whenever a document below changes.
  */
-export const REFERENCE_DOCS_VERSION = "2026-09-04.1";
+export const REFERENCE_DOCS_VERSION = "2026-09-05.1";
 
 /**
  * What a Bot reads to debug its own Computer.
@@ -1398,6 +1524,16 @@ more: it holds the flag set and starts the Computer's one browser on the one
 display and the one CDP port. The \`${BROWSER_SERVICE}\` service calls it, and
 nothing else needs to know the flags exist.
 
+The launcher limits Chromium to ${CHROMIUM_RENDERER_PROCESS_LIMIT} renderer
+processes and caps each renderer's V8 old space at
+${CHROMIUM_MAX_OLD_SPACE_MIB} MiB. It disables only
+\`${CHROMIUM_DISABLED_FEATURES.join(",")}\`; background-tab timer throttling
+remains enabled. Native allocations can still exceed V8's heap ceiling, so
+the separately supervised \`${WATCHDOG_SERVICE}\` samples memory every
+${WATCHDOG_INTERVAL_SECONDS} seconds. It closes a renderer above 1.5 GiB RSS,
+or the largest renderer when the Computer has less than 512 MiB available,
+and records the action in \`${WATCHDOG_LOG}\`.
+
 ## What is never run from the shell
 
 ${COMPUTER_GUI_SHELL_COMMANDS.map((name) => `\`${name}\``).join(", ")}.
@@ -1420,7 +1556,8 @@ tools do.
 \`computer_doctor\` runs \`${DOCTOR_SCRIPT}\` and hands back a report: disk on
 \`/\` and \`${HOME_ROOT}\`, the size of \`${SCRATCH_ROOT}\`, the viewer
 gateway, the durable-root watcher, the shared screen, the one browser process
-and its CDP port, every Bot's window and whether it sits over that Bot's own
+and its CDP port, the renderer watchdog's recent actions, the top memory
+consumers, every Bot's window and whether it sits over that Bot's own
 slot, the browser build and its profile, the sync signal and any conflicting
 generations, this reference
 set's version, the launcher and its shims, the clock, DNS, and whether a
@@ -1448,6 +1585,9 @@ Computer rather than of one run.
 - **browser-process** — none, or more than one. One is the whole design: the
   profile's lock admits exactly one browser, and a second one is a Bot with a
   black screen.
+- **watchdog** — the renderer memory guard is not running. Its last actions
+  remain in \`${WATCHDOG_LOG}\`; opening the Computer repairs its supervised
+  service.
 - **reference-docs** — this set is stale and refreshes when the Computer is
   next opened. Nothing you can do on the box fixes it.
 - **browser** — the browser build is missing. It is installed by provisioning,
@@ -1469,7 +1609,7 @@ is dropped.
 
 ## Logs on the box
 
-\`${DOCTOR_LOG}\`, and per-Bot under \`${BOTS_ROOT}/<botKey>\`:
+\`${DOCTOR_LOG}\`, \`${WATCHDOG_LOG}\`, and per-Bot under \`${BOTS_ROOT}/<botKey>\`:
 \`chromium.log\`, \`fluxbox.log\`, \`x11vnc.log\`, and \`processes/<id>/log.*\`.
 Provisioning's own log is \`${RUNTIME_ROOT}/provision/provision.log\`.
 `,
@@ -1781,6 +1921,14 @@ if pgrep -f watch-workspace.sh >/dev/null 2>&1; then
 else
   record sync-watcher fail "no durable-root watcher is running; on-Computer writes will not signal a sync"
 fi
+WATCHDOG_ACTIONS=$(tail -n 5 ${WATCHDOG_LOG} 2>/dev/null | tr '\n' ';' || true)
+if pgrep -f -- ${WATCHDOG_SCRIPT} >/dev/null 2>&1; then
+  record watchdog pass "the renderer watchdog is running; recent actions: \${WATCHDOG_ACTIONS:-none}"
+else
+  record watchdog fail "the renderer watchdog is not running; recent actions: \${WATCHDOG_ACTIONS:-none}"
+fi
+TOP_MEMORY=$(ps -eo pid=,rss=,comm= --sort=-rss 2>/dev/null | head -n 5 | tr '\n' ';' || true)
+record memory-top pass "top resident-memory consumers (pid rssKiB command): \${TOP_MEMORY:-unavailable}"
 SLOT=""
 if [ -n "$KEY" ] && [ -s ${BOTS_ROOT}/"$KEY"/slot ]; then SLOT=$(cat ${BOTS_ROOT}/"$KEY"/slot); fi
 # One browser, one CDP port (ADR 0031). A second main process would mean a
@@ -1966,6 +2114,7 @@ export const COMPUTER_RUNTIME_FILES: readonly {
     content: startBrowserScript,
     mode: 0o700,
   },
+  { path: WATCHDOG_SCRIPT, content: browserWatchdogScript, mode: 0o700 },
   {
     path: `${RUNTIME_ROOT}/start-view.sh`,
     content: startViewScript,