@tsconfigdotjson/vibe-os 0.2.0-rc.1 → 0.3.0

package/server/doctor.ts

@@ -25,14 +25,14 @@ import {
   vncPasswordFileFromUnit,
 } from "./browser.ts";
 import type { Config } from "./config.ts";
+import { discover, harnesses, harnessProblems } from "./harness.ts";
 import {
-  CLAUDE_INSTALL,
-  CURSOR_INSTALL,
-  discoverCursor,
-  discoverHermes,
-  HERMES_INSTALL,
-  UV_INSTALL,
-} from "./harness.ts";
+  type MemoryLimits,
+  type OomState,
+  oomState,
+  type ScopeState,
+  scopeState,
+} from "./memory.ts";
 import { findLeaks } from "./reaper.ts";
 import { IS_COMPILED } from "./runtime.ts";
 import { discoverHostKey, SshCa } from "./ssh-ca.ts";
@@ -109,7 +109,7 @@ async function firewallState(): Promise<FirewallState> {
     directUdpAllowed: false,
   };
 
-  // ufw first: it is what the README documents, and its status output says
+  // ufw first: it is what docs/deploying.md documents, and its status output says
   // plainly whether it is switched on, which a raw ruleset does not.
   const ufw = await run("ufw", ["status", "verbose"], { timeout: 5000 })
     .then((r) => r.stdout)
@@ -349,114 +349,60 @@ async function browserChecks(): Promise<Check[]> {
 }
 
 /**
- * Hermes, and whether its browser tools land anywhere useful.
+ * Every harness: installed, logged in, and whatever else its adapter checks.
  *
- * Three questions, and the second two only make sense once the first is yes.
- * None of them is fatal: a box that never installs Hermes is a working box, the
- * same way one without Claude is.
+ * None of it is fatal. A box that never installs a given harness is a working
+ * box; only the profiles that use it are affected. The login check exists
+ * because its failure is quiet in exactly the way this file cares about: the
+ * window opens, the harness runs, and it sits at a login prompt.
  */
-async function hermesChecks(): Promise<Check[]> {
-  // Cheap when it is missing — this returns as soon as the binary is not found,
-  // which is the answer on most boxes.
-  const hermes = await discoverHermes();
-  if (!hermes.available) {
-    return [
-      bad(
-        "hermes",
-        "not on PATH — profiles using the Hermes harness fall back to a shell",
-        HERMES_INSTALL,
-      ),
-    ];
-  }
-
-  const checks: Check[] = [
-    ok(
-      "hermes",
-      `${hermes.version ?? "installed"} — the Hermes harness will run`,
+async function harnessChecks(): Promise<Check[]> {
+  const checks: Check[] = [];
+  for (const { file, error } of harnessProblems())
+    checks.push(bad("harness file", `${file}: ${error} — skipped`));
+
+  // Concurrently: each is its own few process starts, and the slow ones go to
+  // the network.
+  const adapters = harnesses();
+  const found = await Promise.all(
+    adapters.map(
+      (a) => discover(a.spec.id) as NonNullable<ReturnType<typeof discover>>,
     ),
-  ];
-
-  // Without the CLI, Browser Use mode silently does not engage. Hermes keeps
-  // working with its twelve built-in browser tools, so nothing looks wrong;
-  // you just pay for a dozen tool schemas in every request and never find out.
-  checks.push(
-    hermes.browser.browserUse
-      ? ok("browser-use", "runnable — Hermes gets the single browser_exec tool")
-      : bad(
-          "browser-use",
-          "no browser-use or uvx on PATH — Hermes keeps its twelve built-in browser tools",
-          UV_INSTALL,
-        ),
   );
-
-  // Only worth asking when there is a browser here to be pointed at. On a box
-  // with no `install-browser`, an unset cdp_url is the correct configuration.
-  if (hermes.browser.cdpPort !== null) {
-    checks.push(
-      hermes.browser.connected
-        ? ok(
-            "hermes browser",
-            `driving this box's Chrome on 127.0.0.1:${hermes.browser.cdpPort}`,
-          )
-        : bad(
-            "hermes browser",
-            hermes.browser.cdpUrl
-              ? `browser.cdp_url is ${hermes.browser.cdpUrl}, not this box's Chrome on ${hermes.browser.cdpPort}`
-              : "browser.cdp_url is unset — Hermes will not use the browser running here",
-            "vibe-os connect-hermes",
-          ),
-    );
-  }
-
-  return checks;
-}
-
-/**
- * Cursor, and whether a window opened as it would get past the login prompt.
- *
- * Two questions. Neither is fatal, for the reason the Hermes checks give: a box
- * that never installs Cursor is a working box. The login check exists because
- * its failure is quiet in exactly the way this file cares about — the window
- * opens, the harness runs, and it sits asking for a browser login on a box that
- * may not have one attached.
- */
-async function cursorChecks(): Promise<Check[]> {
-  const cursor = await discoverCursor();
-  if (!cursor.available) {
-    return [
-      bad(
-        "cursor",
-        "not on PATH — profiles using the Cursor harness fall back to a shell",
-        CURSOR_INSTALL,
-      ),
-    ];
-  }
-
-  const checks: Check[] = [
-    ok(
-      "cursor",
-      `${cursor.version ?? "installed"} — the Cursor harness will run`,
-    ),
-  ];
-
-  if (cursor.loggedIn === false) {
-    checks.push(
-      bad(
-        "cursor login",
-        "not logged in — Cursor windows will sit at a login prompt",
-        "cursor-agent login",
-      ),
-    );
-  } else if (cursor.loggedIn === true) {
+  adapters.forEach((adapter, i) => {
+    const { spec } = adapter;
+    const { report, detail } = found[i];
+    if (!report.available) {
+      checks.push(
+        bad(
+          spec.id,
+          `not on PATH — profiles using the ${spec.label} harness open a window that closes immediately`,
+          spec.install,
+        ),
+      );
+      return;
+    }
     checks.push(
       ok(
-        "cursor login",
-        `logged in${cursor.models.length > 0 ? `, ${cursor.models.length} models offered` : ""}`,
+        spec.id,
+        `${report.version ?? "installed"} — the ${spec.label} harness will run`,
       ),
     );
-  }
-  // null stays silent: status output this build cannot read is not a finding.
-
+    if (spec.login && report.loggedIn === false) {
+      checks.push(
+        bad(
+          `${spec.id} login`,
+          `not logged in — ${spec.label} windows will sit at a login prompt`,
+          spec.login.fix,
+        ),
+      );
+    } else if (spec.login && report.loggedIn === true) {
+      checks.push(ok(`${spec.id} login`, "logged in"));
+    }
+    // null stays silent: status output this build cannot read is not a finding.
+    for (const c of adapter.checks?.(report, detail) ?? [])
+      checks.push(c.ok ? ok(c.label, c.detail) : bad(c.label, c.detail, c.fix));
+  });
   return checks;
 }
 
@@ -591,6 +537,110 @@ async function tailscaleAddress(): Promise<string | null> {
   return null;
 }
 
+/**
+ * Whether one session can take the box down, and whether anything would stop
+ * it if one did. Pure, so every combination is testable off a real box.
+ */
+export function memoryChecks(
+  user: string,
+  limits: MemoryLimits,
+  scope: ScopeState,
+  oom: OomState,
+): Check[] {
+  const checks: Check[] = [];
+  const set = [
+    limits.high !== null ? `MemoryHigh=${limits.high}` : null,
+    limits.max !== null ? `MemoryMax=${limits.max}` : null,
+    limits.swapMax !== null ? `MemorySwapMax=${limits.swapMax}` : null,
+  ].filter(Boolean);
+
+  if (set.length === 0) {
+    checks.push(
+      ok("memory limits", "off (--no-memory-limit): windows start unscoped"),
+    );
+  } else if (!scope.systemd) {
+    checks.push(
+      bad(
+        "memory limits",
+        "no systemd here, so windows start without their memory limits and one runaway agent can take the box down",
+        "run on a systemd host, or rely on the OOM daemon below",
+      ),
+    );
+  } else if (!scope.linger) {
+    checks.push(
+      bad(
+        "memory limits",
+        `lingering is off for ${user}, so windows start without their memory limits (a scope would end when the last login did)`,
+        `sudo loginctl enable-linger ${user}   # or vibe-os setup`,
+      ),
+    );
+  } else if (!scope.cgroup2) {
+    checks.push(
+      bad(
+        "memory limits",
+        `this box uses cgroup v1, where a user's scopes cannot be limited, so ${set.join(" ")} is set but not enforced`,
+        "boot with systemd.unified_cgroup_hierarchy=1, or rely on the OOM daemon below",
+      ),
+    );
+  } else if (scope.controllers && !scope.controllers.includes("memory")) {
+    checks.push(
+      bad(
+        "memory limits",
+        `the user manager is not delegated the memory controller (it has: ${scope.controllers.join(" ") || "none"}), so ${set.join(" ")} is set but not enforced`,
+        "sudo systemctl edit user@.service   # [Service] Delegate=pids memory cpu",
+      ),
+    );
+  } else {
+    checks.push(
+      ok(
+        "memory limits",
+        `each window runs in its own scope: ${set.join(" ")}`,
+      ),
+    );
+  }
+
+  const swap = oom.swapTotal > 0;
+  if (oom.oomd || oom.earlyoom === "active") {
+    checks.push(
+      ok(
+        "oom daemon",
+        `${oom.oomd ? "systemd-oomd" : "earlyoom"} is running, so a box out of memory recovers on its own`,
+      ),
+    );
+  } else if (oom.earlyoom === "installed") {
+    checks.push(
+      bad(
+        "oom daemon",
+        "earlyoom is installed but not running",
+        "sudo systemctl enable --now earlyoom",
+      ),
+    );
+  } else {
+    checks.push(
+      bad(
+        "oom daemon",
+        swap
+          ? "swap and no OOM daemon: out of memory, this box thrashes for as long as it takes someone to notice, instead of killing one process"
+          : "no OOM daemon: out of memory, the kernel kills something only after the box has stalled",
+        "sudo apt install earlyoom   # or vibe-os setup",
+      ),
+    );
+  }
+  return checks;
+}
+
+/** A user's uid, or null when there is no such user. */
+async function uidOf(user: string): Promise<number | null> {
+  if (user === os.userInfo().username) return process.getuid?.() ?? null;
+  try {
+    const { stdout } = await run("id", ["-u", user], { timeout: 5_000 });
+    const uid = Number(stdout.trim());
+    return Number.isInteger(uid) ? uid : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function runDoctor(config: Config): Promise<Check[]> {
   const checks: Check[] = [];
   const user = config.user;
@@ -643,19 +693,7 @@ export async function runDoctor(config: Config): Promise<Check[]> {
         ),
   );
 
-  const claude = await onPath("claude");
-  checks.push(
-    claude
-      ? ok("claude", "on PATH — the Claude harness will run")
-      : bad(
-          "claude",
-          "not on PATH — profiles using the Claude harness fall back to a shell",
-          CLAUDE_INSTALL,
-        ),
-  );
-
-  checks.push(...(await hermesChecks()));
-  checks.push(...(await cursorChecks()));
+  checks.push(...(await harnessChecks()));
 
   // ── can a browser actually log in? ───────────────────────────────────────
   const sshdUp = await probeTcp(config.sshHost, config.sshPort);
@@ -866,7 +904,7 @@ export async function runDoctor(config: Config): Promise<Check[]> {
       bad(
         "firewall",
         "could not read any firewall — needs root, or none is installed",
-        "sudo vibe-os doctor    (and see the firewall rules in the README)",
+        "sudo vibe-os doctor    (firewall rules: https://github.com/tsconfigdotjson/vibe-os/blob/main/docs/deploying.md#firewall)",
       ),
     );
   } else if (!fw.active) {
@@ -913,6 +951,21 @@ export async function runDoctor(config: Config): Promise<Check[]> {
   // not be told about four things it does not have.
   checks.push(...(await browserChecks()));
 
+  // ── memory ───────────────────────────────────────────────────────────────
+  //
+  // Linux only: the scope and both daemons are systemd and /proc things, and a
+  // Mac running vibe-os locally has none of them to report on.
+  if (process.platform === "linux") {
+    checks.push(
+      ...memoryChecks(
+        user,
+        config.memory,
+        await scopeState(user, await uidOf(user)),
+        await oomState(),
+      ),
+    );
+  }
+
   // ── leaked processes ─────────────────────────────────────────────────────
   //
   // Processes that outlived their workspace or session: a cwd that is a
@@ -960,7 +1013,7 @@ export async function runDoctor(config: Config): Promise<Check[]> {
       bad(
         "exposure",
         `no token and bound to every interface — Tailscale is up (${tailnet}), but so is any public address`,
-        `bind to the tailnet only:  --host ${tailnet}   (and see the firewall rules in the README)`,
+        `bind to the tailnet only:  --host ${tailnet}   (firewall rules: https://github.com/tsconfigdotjson/vibe-os/blob/main/docs/deploying.md#firewall)`,
       ),
     );
   } else {