@tsconfigdotjson/vibe-os 0.2.0 → 0.3.0

package/server/memory.ts

@@ -0,0 +1,418 @@
+// Keeping agent sessions from taking the box down (#50).
+//
+// An agent session costs 300 to 700 MB and grows with age, and the boxes this
+// runs on are small. On a 4 GB VPS a handful of them push the kernel into
+// page-cache thrash: near 100% system time, heavy block reads, almost no swap
+// traffic. With swap present the kernel never decides to OOM-kill anything, so
+// the box stays unusable until a person intervenes.
+//
+// Three defences, in the order they act:
+//
+//   1. Each session starts in its own systemd user scope with MemoryHigh and
+//      MemoryMax. Past High the kernel reclaims from that scope alone, so one
+//      runaway agent slows itself down instead of the box. Past Max it is
+//      OOM-killed inside its own scope.
+//   2. The desktop shows what each window costs and what the box's memory
+//      pressure is, read from here.
+//   3. Opening another agent when the box cannot fit one asks first.
+//
+// Everything here degrades to nothing rather than failing. A container has no
+// user systemd and a Mac has no /proc; windows still open in both, without the
+// scope and without the numbers.
+
+import { execFile } from "node:child_process";
+import { access, readdir, readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import type { MemoryReport } from "../shared/wire.ts";
+import { markerFromEnviron } from "./reaper.ts";
+
+const run = promisify(execFile);
+
+/**
+ * A size systemd accepts for MemoryHigh and MemoryMax.
+ *
+ * Bytes with an optional K/M/G/T suffix, a percentage of physical memory, or
+ * `infinity`. Validated strictly because the value is pasted into the shell
+ * command a certificate forces, and because systemd-run rejects a property it
+ * cannot parse, which would mean a window that never opens.
+ */
+const SIZE = /^(\d+(?:\.\d+)?)([KMGT]?)$/;
+const PERCENT = /^(\d+)%$/;
+
+/** Normalises a size, or throws with the reason. Empty means "not set". */
+export function parseSize(raw: unknown, label: string): string | null {
+  if (raw === undefined || raw === null) return null;
+  const value = String(raw).trim().toUpperCase().replace(/B$/, "");
+  if (value === "") return null;
+  if (value === "INFINITY" || value === "NONE") return "infinity";
+  const pct = PERCENT.exec(value);
+  if (pct) {
+    const n = Number(pct[1]);
+    if (n <= 0 || n > 100)
+      throw new Error(`${label} must be between 1% and 100%`);
+    return `${pct[1]}%`;
+  }
+  const size = SIZE.exec(value);
+  if (!size || Number(size[1]) <= 0)
+    throw new Error(
+      `${label} must look like 1500M, 2G, 40% or infinity, not ${String(raw)}`,
+    );
+  return `${size[1]}${size[2]}`;
+}
+
+const UNITS: Record<string, number> = {
+  "": 1,
+  K: 1024,
+  M: 1024 ** 2,
+  G: 1024 ** 3,
+  T: 1024 ** 4,
+};
+
+/** Bytes for a parsed size, given the box's physical memory. null is no limit. */
+export function sizeToBytes(size: string | null, total: number): number | null {
+  if (size === null || size === "infinity") return null;
+  const pct = PERCENT.exec(size);
+  if (pct) return Math.floor((Number(pct[1]) / 100) * total);
+  const m = SIZE.exec(size);
+  return m ? Math.floor(Number(m[1]) * UNITS[m[2]]) : null;
+}
+
+export interface MemoryLimits {
+  high: string | null;
+  max: string | null;
+  /**
+   * MemorySwapMax. Without it MemoryMax is no limit at all on a box with swap:
+   * a scope at its maximum pushes pages out to swap instead of being killed,
+   * which is the thrash all of this exists to prevent. Measured on the
+   * reference box: a 100M scope allocated 400M and carried on. Server-wide
+   * only; a profile sets the other two.
+   */
+  swapMax: string | null;
+}
+
+/**
+ * What a session is actually started with: the profile's own value where it
+ * set one, the server's otherwise.
+ */
+export function effectiveLimits(
+  global: MemoryLimits,
+  profile?: { memoryHigh: string | null; memoryMax: string | null } | null,
+): MemoryLimits {
+  return {
+    high: profile?.memoryHigh ?? global.high,
+    max: profile?.memoryMax ?? global.max,
+    swapMax: global.swapMax,
+  };
+}
+
+/**
+ * The prefix that starts a command in its own scope, or "" for no scope.
+ *
+ * `--scope` runs the command directly rather than handing it to the manager,
+ * so it inherits this environment (the session marker included) and dtach's
+ * daemonised child stays in the scope after systemd-run's own process exits.
+ * `--collect` stops a scope that ended badly from lingering as a failed unit.
+ *
+ * Returned as argv words already quoted for the shell, because session.ts
+ * splices it into a command that is quoted twice more on its way to sshd.
+ */
+export function scopePrefix(limits: MemoryLimits, session: string): string {
+  const props: string[] = [];
+  if (limits.high !== null) props.push(`-p MemoryHigh=${limits.high}`);
+  if (limits.max !== null) props.push(`-p MemoryMax=${limits.max}`);
+  if (limits.swapMax !== null) props.push(`-p MemorySwapMax=${limits.swapMax}`);
+  if (props.length === 0) return "";
+  // The session name is `vibe-<words>-<n>`, so it needs no quoting of its own,
+  // and the description is what `systemctl --user status` shows for the scope.
+  return `systemd-run --user --scope --quiet --collect ${props.join(" ")} --description=vibe-os:${session} -- `;
+}
+
+/** Where logind records that a user lingers. */
+export const LINGER_DIR = "/var/lib/systemd/linger";
+
+/**
+ * Shell that is true when a user systemd manager is there to take a scope, and
+ * will still be there after this login ends.
+ *
+ * The second half is the one that matters. sshd gives every login a manager
+ * through pam_systemd, but without lingering logind stops that manager when the
+ * user's last login closes, and every unit under it goes too. A scope would
+ * then end each window the moment the last browser tab did: on the reference
+ * box a session died at exactly the second the only ssh login disconnected.
+ * Unscoped, the session sits in the login's own scope, which logind leaves
+ * running. So no linger, no scope; doctor says so and setup offers the fix.
+ *
+ * A container usually has no manager at all, and then the session starts the
+ * way it always did. Checked per create, not once at startup, because both are
+ * properties of the login the force-command runs in, not of the server.
+ */
+export const SCOPE_PROBE = `[ -e "${LINGER_DIR}/$(id -un)" ] && command -v systemd-run > /dev/null 2>&1 && systemctl --user show-environment > /dev/null 2>&1`;
+
+// ── what the box has ─────────────────────────────────────────────────────────
+
+export type BoxMemory = NonNullable<MemoryReport["box"]>;
+
+/** Reads `MemTotal:  3905536 kB` lines into bytes. */
+export function parseMeminfo(text: string): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const line of text.split("\n")) {
+    const m = /^(\w+):\s+(\d+)(?:\s+kB)?/.exec(line);
+    if (m) out[m[1]] = Number(m[2]) * (line.includes("kB") ? 1024 : 1);
+  }
+  return out;
+}
+
+export function parsePressure(
+  text: string,
+): { some10: number; full10: number } | null {
+  const avg = (kind: string) => {
+    const m = new RegExp(`^${kind} avg10=([\\d.]+)`, "m").exec(text);
+    return m ? Number(m[1]) : null;
+  };
+  const some10 = avg("some");
+  if (some10 === null) return null;
+  return { some10, full10: avg("full") ?? 0 };
+}
+
+export async function readBoxMemory(): Promise<BoxMemory | null> {
+  const meminfo = await readFile("/proc/meminfo", "utf8").catch(() => null);
+  if (meminfo === null) return null;
+  const m = parseMeminfo(meminfo);
+  const pressure = await readFile("/proc/pressure/memory", "utf8")
+    .then(parsePressure)
+    .catch(() => null);
+  return {
+    total: m.MemTotal ?? 0,
+    available: m.MemAvailable ?? m.MemFree ?? 0,
+    swapTotal: m.SwapTotal ?? 0,
+    swapFree: m.SwapFree ?? 0,
+    pressure,
+  };
+}
+
+// ── what each session costs ──────────────────────────────────────────────────
+
+export type SessionMemory = MemoryReport["windows"][string];
+
+/**
+ * The cgroup a process is in, from `/proc/<pid>/cgroup` on cgroup v2.
+ *
+ * Only a scope under the user manager counts as the session's own. A session
+ * started before this feature, or without user systemd, sits in the login's
+ * `session-N.scope`, which it shares with whatever else that login ran.
+ */
+export function ownScope(cgroupFile: string): string | null {
+  const m = /^0::(\/.*)$/m.exec(cgroupFile);
+  if (!m) return null;
+  const p = m[1].trim();
+  return /\/user@\d+\.service\/.*\.scope$/.test(p) ? p : null;
+}
+
+const readNumber = async (file: string): Promise<number | null> => {
+  const text = await readFile(file, "utf8").catch(() => null);
+  if (text === null) return null;
+  const n = Number(text.trim());
+  return Number.isFinite(n) ? n : null;
+};
+
+const rssBytes = (statusText: string): number => {
+  const m = /^VmRSS:\s+(\d+)\s+kB/m.exec(statusText);
+  return m ? Number(m[1]) * 1024 : 0;
+};
+
+/**
+ * Memory per session socket, for the sockets asked about.
+ *
+ * One pass over /proc. Every process that inherited the session marker is
+ * that session's, which reaches grandchildren a process tree would miss (see
+ * reaper.ts). A process owned by another user fails every read and is skipped,
+ * which is the right answer: it is not ours.
+ */
+export async function sessionMemory(
+  sockets: string[],
+): Promise<Map<string, SessionMemory>> {
+  const wanted = new Set(sockets);
+  const out = new Map<string, SessionMemory>();
+  if (wanted.size === 0) return out;
+  const pids = await readdir("/proc").catch(() => [] as string[]);
+
+  const rss = new Map<string, number>();
+  const scopes = new Map<string, string>();
+  await Promise.all(
+    pids
+      .filter((name) => /^\d+$/.test(name))
+      .map(async (pid) => {
+        const environ = await readFile(`/proc/${pid}/environ`, "utf8").catch(
+          () => "",
+        );
+        const sock = markerFromEnviron(environ);
+        if (!sock || !wanted.has(sock)) return;
+        const [status, cgroup] = await Promise.all([
+          readFile(`/proc/${pid}/status`, "utf8").catch(() => ""),
+          readFile(`/proc/${pid}/cgroup`, "utf8").catch(() => ""),
+        ]);
+        rss.set(sock, (rss.get(sock) ?? 0) + rssBytes(status));
+        const scope = ownScope(cgroup);
+        if (scope) scopes.set(sock, scope);
+      }),
+  );
+
+  for (const sock of wanted) {
+    const scope = scopes.get(sock);
+    if (scope) {
+      const dir = `/sys/fs/cgroup${scope}`;
+      const current = await readNumber(`${dir}/memory.current`);
+      if (current !== null) {
+        out.set(sock, {
+          bytes: current,
+          // "max" reads as NaN through readNumber, which is "no limit".
+          high: await readNumber(`${dir}/memory.high`),
+          max: await readNumber(`${dir}/memory.max`),
+          scoped: true,
+        });
+        continue;
+      }
+    }
+    if (rss.has(sock))
+      out.set(sock, {
+        bytes: rss.get(sock) ?? 0,
+        high: null,
+        max: null,
+        scoped: false,
+      });
+  }
+  return out;
+}
+
+// ── will another one fit? ────────────────────────────────────────────────────
+
+/**
+ * What one more agent session is budgeted at: the top of the range measured on
+ * the reference box, where a cursor-agent reached 683 MB after four hours.
+ */
+export const AGENT_BUDGET = 700 * 1024 ** 2;
+
+/** Memory left over for the kernel's page cache and everything else. */
+const RESERVE_SHARE = 0.1;
+
+/**
+ * Why opening another agent now is a bad idea, or null when it is fine.
+ *
+ * Pure, so it can be tested without a box. The budget is the agent's MemoryHigh
+ * when the profile sets an absolute one, since that is what it is allowed to
+ * grow to before being throttled, and the measured typical cost otherwise.
+ *
+ * Available memory only, not pressure. A window held at its MemoryHigh is
+ * throttled by sleeping, and the kernel counts that sleep as a memory stall:
+ * on the reference box one throttled scope put `/proc/pressure/memory` at 95%
+ * while the CPU sat 95% idle with no I/O. High pressure no longer means the box
+ * cannot take another session.
+ */
+export function capacityWarning(
+  box: BoxMemory | null,
+  high: string | null,
+): string | null {
+  if (!box || box.total === 0) return null;
+  const limit = sizeToBytes(high, box.total);
+  const budget = limit !== null ? Math.min(limit, AGENT_BUDGET) : AGENT_BUDGET;
+  const reserve = box.total * RESERVE_SHARE;
+  if (box.available - budget < reserve) {
+    return `Only ${formatBytes(box.available)} of ${formatBytes(box.total)} is free, and an agent session needs about ${formatBytes(budget)}. Opening it may make the box unresponsive.`;
+  }
+  return null;
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+  return `${Math.round(bytes / 1024 ** 2)} MB`;
+}
+
+// ── what doctor and setup look at ────────────────────────────────────────────
+
+const unitActive = async (unit: string): Promise<boolean> => {
+  try {
+    const { stdout } = await run("systemctl", ["is-active", unit], {
+      timeout: 5_000,
+    });
+    return stdout.trim() === "active";
+  } catch {
+    // is-active exits non-zero for every state but active.
+    return false;
+  }
+};
+
+const exists = (file: string) =>
+  access(file).then(
+    () => true,
+    () => false,
+  );
+
+export interface OomState {
+  oomd: boolean;
+  /** Running, installed but not running, or absent. */
+  earlyoom: "active" | "installed" | null;
+  swapTotal: number;
+}
+
+/**
+ * Whether anything will kill a process before the box thrashes.
+ *
+ * The kernel's own OOM killer acts only when reclaim has completely failed,
+ * and with swap present it practically never has: the box spends its time
+ * refaulting page cache instead. systemd-oomd and earlyoom act on pressure or
+ * free memory, early enough to matter.
+ */
+export async function oomState(): Promise<OomState> {
+  const [oomd, earlyoomActive, earlyoomBinary, meminfo] = await Promise.all([
+    unitActive("systemd-oomd"),
+    unitActive("earlyoom"),
+    exists("/usr/bin/earlyoom"),
+    readFile("/proc/meminfo", "utf8").catch(() => ""),
+  ]);
+  return {
+    oomd,
+    earlyoom: earlyoomActive ? "active" : earlyoomBinary ? "installed" : null,
+    swapTotal: parseMeminfo(meminfo).SwapTotal ?? 0,
+  };
+}
+
+export interface ScopeState {
+  /** systemd is PID 1 and systemd-run exists. */
+  systemd: boolean;
+  /** The user's manager outlives their logins, which a scope needs. */
+  linger: boolean;
+  /**
+   * The unified hierarchy. Under cgroup v1 a user manager is never delegated
+   * memory, so a scope is created and its limits silently do nothing.
+   */
+  cgroup2: boolean;
+  /**
+   * The user manager's delegated controllers, or null when they could not be
+   * read: no manager running for that user yet, or no cgroup v2.
+   */
+  controllers: string[] | null;
+}
+
+export async function scopeState(
+  user: string,
+  uid: number | null,
+): Promise<ScopeState> {
+  const systemd =
+    (await exists("/run/systemd/system")) &&
+    ((await exists("/usr/bin/systemd-run")) ||
+      (await exists("/bin/systemd-run")));
+  const linger = await exists(`${LINGER_DIR}/${user}`);
+  const cgroup2 = await exists("/sys/fs/cgroup/cgroup.controllers");
+  if (!systemd || uid === null)
+    return { systemd, linger, cgroup2, controllers: null };
+  const text = await readFile(
+    `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
+    "utf8",
+  ).catch(() => null);
+  return {
+    systemd,
+    linger,
+    cgroup2,
+    controllers: text === null ? null : text.trim().split(/\s+/),
+  };
+}

package/server/profiles.ts

@@ -9,6 +9,8 @@ import { asc, eq } from "drizzle-orm";
 import { detokenize, tokenize } from "../shared/args.ts";
 import type { Harness, Profile, ProfileInput } from "../shared/wire.ts";
 import { type Db, newId, profiles, windows } from "./db.ts";
+import { isHarness } from "./harness.ts";
+import { parseSize } from "./memory.ts";
 
 /**
  * The ten colours a profile can be.
@@ -30,18 +32,6 @@ export const PALETTE = [
   "blue",
 ] as const;
 
-/**
- * `satisfies` rather than a plain literal: it is what makes the runtime list and
- * the wire type fail to compile if they ever stop agreeing.
- */
-export const HARNESSES = [
-  "claude",
-  "hermes",
-  "cursor",
-  "shell",
-  "custom",
-] as const satisfies readonly Harness[];
-
 const MAX_NAME = 40;
 const MAX_PROMPT = 16_000;
 const MAX_ARGS = 64;
@@ -70,6 +60,8 @@ const hydrate = (row: typeof profiles.$inferSelect): Profile => ({
   command: row.command,
   args: parseStoredArgs(row.args),
   prompt: row.prompt,
+  memoryHigh: row.memoryHigh,
+  memoryMax: row.memoryMax,
   position: row.position,
   createdAt: row.createdAt,
 });
@@ -85,9 +77,17 @@ type Fields = Partial<typeof profiles.$inferInsert>;
 type CompleteFields = Fields &
   Required<Pick<typeof profiles.$inferInsert, "name" | "color" | "harness">>;
 
-function validate(input: ProfileInput, partial: true): Fields;
+function validate(
+  input: ProfileInput,
+  partial: true,
+  current?: Harness,
+): Fields;
 function validate(input: ProfileInput, partial: false): CompleteFields;
-function validate(input: ProfileInput, partial: boolean): Fields {
+function validate(
+  input: ProfileInput,
+  partial: boolean,
+  current?: Harness,
+): Fields {
   const out: Fields = {};
 
   if (input.name !== undefined || !partial) {
@@ -107,7 +107,9 @@ function validate(input: ProfileInput, partial: boolean): Fields {
 
   if (input.harness !== undefined || !partial) {
     const harness = input.harness ?? "claude";
-    if (!(HARNESSES as readonly string[]).includes(harness))
+    // The harness a profile already has stays valid even if its spec file has
+    // since gone, so the rest of the profile can still be edited.
+    if (!isHarness(harness) && harness !== current)
       throw new Error(`unknown harness ${harness}`);
     out.harness = harness;
   }
@@ -137,6 +139,13 @@ function validate(input: ProfileInput, partial: boolean): Fields {
     out.prompt = prompt;
   }
 
+  // Checked here rather than at launch: systemd-run refuses a size it cannot
+  // read, and the window would never open.
+  if (input.memoryHigh !== undefined || !partial)
+    out.memoryHigh = parseSize(input.memoryHigh, "memory high");
+  if (input.memoryMax !== undefined || !partial)
+    out.memoryMax = parseSize(input.memoryMax, "memory max");
+
   // A custom harness with no command would launch nothing at all, silently.
   const harness = out.harness ?? input.harness;
   if (harness === "custom" && out.command === null)
@@ -179,6 +188,8 @@ export function createProfile(
       command: fields.command ?? null,
       args: fields.args ?? "[]",
       prompt: fields.prompt ?? "",
+      memoryHigh: fields.memoryHigh ?? null,
+      memoryMax: fields.memoryMax ?? null,
       position: input.position ?? siblings.length,
       createdAt: Date.now(),
     })
@@ -202,6 +213,7 @@ export function updateProfile(
   const fields = validate(
     { harness: current.harness, command: current.command, ...input },
     true,
+    current.harness,
   );
   if (Object.keys(fields).length > 0) {
     db.update(profiles).set(fields).where(eq(profiles.id, id)).run();

package/server/projects.ts

@@ -574,17 +574,63 @@ async function baseForWorkspace(
   return { ref, warning: null };
 }
 
+/**
+ * Where a new workspace's branch starts when the caller named a branch.
+ *
+ * Origin's copy wins over a local branch of the same name, after a fetch, for
+ * the same reason the default does: a workspace should start from the current
+ * state of the work. A local branch or a commit is the fallback. Unlike the
+ * default, a name that resolves to nothing is an error, because the caller
+ * asked for something specific.
+ */
+async function baseFromRef(
+  repo: string,
+  projectName: string,
+  from: string,
+): Promise<{ ref: string; warning: string | null }> {
+  if (from.startsWith("-") || /\s/.test(from))
+    throw new Error(`invalid branch ${JSON.stringify(from)}`);
+
+  let warning: string | null = null;
+  const origin = await hasOrigin(repo);
+  if (origin) {
+    try {
+      await git(repo, ["fetch", "origin"], FETCH_TIMEOUT_MS);
+    } catch (err) {
+      const failure = gitReason(err);
+      log.warn(`could not fetch origin for ${projectName}: ${failure}`);
+      warning = `Could not fetch origin (${failure}). This branch starts from ${from} as it was at the last fetch.`;
+    }
+  }
+
+  const candidates = origin ? [`origin/${from}`, from] : [from];
+  for (const ref of candidates) {
+    const found = await git(repo, [
+      "rev-parse",
+      "--verify",
+      "--quiet",
+      `${ref}^{commit}`,
+    ]).then(
+      () => true,
+      () => false,
+    );
+    if (found) return { ref, warning };
+  }
+  throw new Error(`no branch or commit called ${from} in ${projectName}`);
+}
+
 /**
  * Creates a git worktree and records it as a workspace.
  *
  * The worktree gets its own branch named after the workspace, branched from a
- * freshly fetched origin — see `baseForWorkspace`.
+ * freshly fetched origin — see `baseForWorkspace` — or from `from` when given.
  */
 export async function createWorkspace(
   db: Db,
   workspaceRoot: string,
   projectId: string,
   requested?: string,
+  from?: string,
 ): Promise<{
   id: string;
   name: string;
@@ -612,11 +658,14 @@ export async function createWorkspace(
     } while (taken.has(name));
   }
 
+  // Resolved before anything is made on disk, so a bad --from leaves nothing.
+  const base = from?.trim()
+    ? await baseFromRef(project.path, project.name, from.trim())
+    : await baseForWorkspace(project.path, project.name);
+
   const target = path.join(workspaceRoot, WORKTREE_DIR, project.name, name);
   await mkdir(path.dirname(target), { recursive: true });
 
-  const base = await baseForWorkspace(project.path, project.name);
-
   // -b creates the branch; git refuses if it already exists, which is the
   // behaviour we want rather than silently reusing someone else's work.
   //

package/server/reaper.ts

@@ -106,7 +106,7 @@ export function parseEtime(value: string): number {
   );
 }
 
-async function pgrep(args: string[]): Promise<number[]> {
+export async function pgrep(args: string[]): Promise<number[]> {
   try {
     const { stdout } = await run("pgrep", args, { timeout: 10_000 });
     return stdout
@@ -174,7 +174,7 @@ export function classifyLeak(
   if (p.sock && gone(p.sock))
     return { pid: p.pid, args: p.args, reason: "its session socket is gone" };
 
-  const dtach = p.args.match(/^dtach -[nap] (\S+\.sock)\b/);
+  const dtach = p.args.match(/^(?:\S*\/)?dtach -[nap] (\S+\.sock)\b/);
   if (dtach && gone(dtach[1]))
     return { pid: p.pid, args: p.args, reason: "its session socket is gone" };
 
@@ -225,7 +225,9 @@ export async function findLeaks(config: Config): Promise<Leak[]> {
 export async function sessionProcesses(sock: string): Promise<number[]> {
   const pids = new Set<number>();
 
-  const masters = await pgrep(["-f", `^dtach -n ${sock}`]);
+  // A scoped session's master is `/usr/bin/dtach`: systemd-run execs the
+  // resolved path, so the name alone does not anchor at the start.
+  const masters = await pgrep(["-f", `^([^ ]*/)?dtach -n ${sock}`]);
   for (const pid of masters) pids.add(pid);
 
   const leaders = new Set<number>();