@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/linear-tasks.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/** Fetch issue content without sending the Linear API key or description to the control plane. */
+export async function getLinearIssue(apiKey, id, fetchImpl = fetch) {
+    if (!apiKey.trim() || !id.trim())
+        return undefined;
+    const res = await fetchImpl("https://api.linear.app/graphql", {
+        method: "POST",
+        headers: { authorization: apiKey, "content-type": "application/json" },
+        body: JSON.stringify({
+            query: "query BivyLinearIssue($id: String!) { issue(id: $id) { id identifier title description url } }",
+            variables: { id },
+        }),
+    });
+    if (!res.ok)
+        return undefined;
+    const raw = (await res.json().catch(() => undefined));
+    const issue = raw?.data?.issue;
+    if (!issue || raw?.errors?.length)
+        return undefined;
+    const identifier = String(issue.identifier ?? "").trim();
+    const title = String(issue.title ?? "").trim();
+    if (!identifier || !title)
+        return undefined;
+    return {
+        id: String(issue.id ?? id),
+        identifier,
+        title,
+        description: String(issue.description ?? ""),
+        url: String(issue.url ?? ""),
+    };
+}
+export function linearBranchName(identifier) {
+    const slug = identifier.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return `bivy/linear-${slug || "issue"}`;
+}
+export function buildLinearTaskPrompt(issue) {
+    return [
+        `You are working on Linear issue ${issue.identifier}: ${issue.title}`,
+        "",
+        issue.description.trim() || "(no description provided)",
+        "",
+        issue.url ? `Issue: ${issue.url}` : "",
+        "",
+        "Understand the issue and surrounding codebase, implement it completely, and run the project's tests, linter, and type-checker.",
+        "",
+        `When finished, commit and push your changes and open a pull request yourself. Include a link to ${issue.identifier} in the pull request description.`,
+    ].filter((part, index, all) => part !== "" || all[index - 1] !== "").join("\n");
+}

package/dist/metadata.js

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+function nowIso() { return new Date().toISOString(); }
+function iso(value, fallback = Date.now()) {
+    const ms = new Date(value).getTime();
+    return new Date(Number.isFinite(ms) ? ms : fallback).toISOString();
+}
+function empty() { return { version: 1, sessions: {}, workspaces: {}, approvals: {}, devices: {} }; }
+// Coalescing window for the metadata file. A streaming agent fires a metadata
+// mutation (touchSession/upsertSession) per output line; without debouncing,
+// each did a synchronous whole-file fsync rewrite whose cost is O(all sessions).
+// At many writes/sec × many sessions that is O(sessions²) of blocking work on
+// the single event loop — enough to peg a core. Coalescing collapses a burst
+// into at most one fsync per window. Durability is bounded to this window: a
+// clean shutdown calls flushSync(), and any 'working' row left stale by a hard
+// crash is reconciled on restart (resetStaleWorking), so the trade is safe.
+const SAVE_DEBOUNCE_MS = 150;
+export class MetadataStore {
+    filePath;
+    data;
+    /** True when an in-memory mutation has not yet been persisted to disk. */
+    dirty = false;
+    /** Pending coalesced-write timer, or null when nothing is queued. */
+    saveTimer = null;
+    constructor(filePath, data) {
+        this.filePath = filePath;
+        this.data = data;
+    }
+    static load(appDir) {
+        const filePath = path.join(appDir, "metadata.json");
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            return new MetadataStore(filePath, {
+                version: 1,
+                sessions: parsed.sessions && typeof parsed.sessions === "object" ? parsed.sessions : {},
+                workspaces: parsed.workspaces && typeof parsed.workspaces === "object" ? parsed.workspaces : {},
+                approvals: parsed.approvals && typeof parsed.approvals === "object" ? parsed.approvals : {},
+                devices: parsed.devices && typeof parsed.devices === "object" ? parsed.devices : {},
+            });
+        }
+        catch {
+            const store = new MetadataStore(filePath, empty());
+            store.persistNow();
+            return store;
+        }
+    }
+    /**
+     * Request a persist. Coalesces a burst of mutations into at most one fsync
+     * per SAVE_DEBOUNCE_MS instead of a synchronous whole-file fsync per call —
+     * the hot-path cost that pegged the event loop. The mutation is already live
+     * in memory (the store is the source of truth); only the disk write is
+     * deferred. A clean shutdown must call flushSync() to persist the tail.
+     */
+    save() {
+        this.dirty = true;
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            if (this.dirty)
+                this.persistNow();
+        }, SAVE_DEBOUNCE_MS);
+        // Don't keep the process alive just to flush metadata — a pending write is
+        // flushed synchronously on shutdown via flushSync().
+        this.saveTimer.unref?.();
+    }
+    /**
+     * Synchronously flush any pending debounced write. Call on shutdown so an
+     * in-flight coalesced change isn't lost, or when a caller needs the on-disk
+     * file to immediately reflect a just-made mutation.
+     */
+    flushSync() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        if (this.dirty)
+            this.persistNow();
+    }
+    /** Atomically write the metadata blob (temp file, fsync, rename). Synchronous
+     *  and O(all sessions) — reached only through the debounced `save()` or an
+     *  explicit `flushSync()`, never once per hot-path mutation. */
+    persistNow() {
+        this.dirty = false;
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const tmp = `${this.filePath}.tmp`;
+        // fsync the temp file before the atomic rename. Without it the rename can be
+        // persisted before the data blocks, so a power cut can surface a zero-length
+        // metadata.json and lose the entire session index.
+        const fd = fs.openSync(tmp, "w", 0o600);
+        try {
+            fs.writeSync(fd, `${JSON.stringify(this.data, null, 2)}\n`);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, this.filePath);
+    }
+    upsertSession(input) {
+        const prev = this.data.sessions[input.id];
+        const createdAt = input.createdAt ?? prev?.createdAt ?? nowIso();
+        const updatedAt = input.updatedAt ?? nowIso();
+        this.data.sessions[input.id] = { ...prev, ...input, createdAt, updatedAt };
+        this.save();
+    }
+    touchSession(id, status) {
+        const prev = this.data.sessions[id];
+        if (!prev)
+            return;
+        const at = nowIso();
+        this.data.sessions[id] = { ...prev, ...(status ? { status } : {}), updatedAt: at, lastActivityAt: at };
+        this.save();
+    }
+    removeSession(id, sessionPath) {
+        if (id && this.data.sessions[id])
+            delete this.data.sessions[id];
+        if (sessionPath) {
+            const resolved = path.resolve(sessionPath);
+            for (const [key, session] of Object.entries(this.data.sessions)) {
+                if (session.path && path.resolve(session.path) === resolved)
+                    delete this.data.sessions[key];
+            }
+        }
+        this.save();
+    }
+    markWorktreePruned(id) {
+        const prev = this.data.sessions[id];
+        if (!prev?.worktree)
+            return;
+        this.data.sessions[id] = { ...prev, worktree: undefined, updatedAt: nowIso() };
+        this.save();
+    }
+    listSessions() {
+        return Object.values(this.data.sessions).sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
+    }
+    /**
+     * Clear transient "working" status left over from a crash/kill. Call once at
+     * boot, before any session is resumed: a fresh process has no live runtimes,
+     * so any persisted "working" row is stale. Leaving it set permanently exempts
+     * the session's worktree from cleanup (an unbounded disk leak). Returns the
+     * ids of the sessions that were reset — i.e. the ones cut off mid-turn by the
+     * process death, which the resume reconciler picks up (auto-continue or offer
+     * a manual "Resume").
+     */
+    resetStaleWorking() {
+        const reset = [];
+        for (const [id, session] of Object.entries(this.data.sessions)) {
+            if (session.status === "working") {
+                this.data.sessions[id] = { ...session, status: "idle" };
+                reset.push(id);
+            }
+        }
+        if (reset.length > 0)
+            this.save();
+        return reset;
+    }
+    /** Set/clear the durable "resume pending" flag (manual resume mode). No-op when
+     *  the row is missing or already in the requested state, so it never churns the
+     *  file on the hot turn-completion path. */
+    setResumePending(id, pending) {
+        const prev = this.data.sessions[id];
+        if (!prev)
+            return;
+        if ((prev.resumePending ?? false) === pending)
+            return;
+        this.data.sessions[id] = { ...prev, resumePending: pending, updatedAt: nowIso() };
+        this.save();
+    }
+    /** Look up a session's durable metadata by id, or by session-file path. */
+    getSession(idOrPath) {
+        if (!idOrPath)
+            return undefined;
+        const direct = this.data.sessions[idOrPath];
+        if (direct)
+            return direct;
+        const resolved = path.resolve(idOrPath);
+        return Object.values(this.data.sessions).find((session) => session.path && path.resolve(session.path) === resolved);
+    }
+    rememberWorkspace(workspace) {
+        const resolved = path.resolve(workspace);
+        this.data.workspaces[resolved] = { path: resolved, lastUsedAt: nowIso() };
+        this.save();
+    }
+    listWorkspaces() {
+        return Object.values(this.data.workspaces).sort((a, b) => new Date(b.lastUsedAt).getTime() - new Date(a.lastUsedAt).getTime()).map((w) => w.path);
+    }
+    removeWorkspace(workspace) {
+        delete this.data.workspaces[path.resolve(workspace)];
+        this.save();
+    }
+    recordApproval(input) {
+        this.data.approvals[input.id] = {
+            id: input.id,
+            sessionId: input.sessionId,
+            toolName: input.toolName,
+            reason: input.reason,
+            risk: input.risk,
+            status: input.status,
+            createdAt: iso(input.createdAt),
+            resolvedAt: input.resolvedAt ? iso(input.resolvedAt) : undefined,
+            workspace: input.workspace,
+            repo: input.repo,
+            branch: input.branch,
+        };
+        const entries = Object.entries(this.data.approvals).sort((a, b) => new Date(b[1].createdAt).getTime() - new Date(a[1].createdAt).getTime()).slice(0, 1000);
+        this.data.approvals = Object.fromEntries(entries);
+        this.save();
+    }
+    listApprovals(limit = 100) {
+        return Object.values(this.data.approvals).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()).slice(0, limit);
+    }
+    upsertDevice(input) {
+        const prev = this.data.devices[input.id];
+        this.data.devices[input.id] = { ...prev, ...input, firstSeenAt: input.firstSeenAt ?? prev?.firstSeenAt ?? nowIso(), lastSeenAt: input.lastSeenAt ?? prev?.lastSeenAt };
+        this.save();
+    }
+    revokeDevice(id) {
+        const prev = this.data.devices[id] ?? { id };
+        this.data.devices[id] = { ...prev, revokedAt: nowIso() };
+        this.save();
+    }
+    listDevices() { return Object.values(this.data.devices).sort((a, b) => String(b.lastSeenAt ?? b.firstSeenAt ?? "").localeCompare(String(a.lastSeenAt ?? a.firstSeenAt ?? ""))); }
+}

package/dist/multiplexer.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { execFile } from "node:child_process";
+function runCmd(command, args, timeoutMs = 2500) {
+    return new Promise((resolve) => {
+        execFile(command, args, { timeout: timeoutMs, windowsHide: true }, (error, stdout, stderr) => {
+            const code = error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+            resolve({ code, stdout: String(stdout || ""), stderr: String(stderr || "") });
+        });
+    });
+}
+// Strip ANSI so multiplexers that colorize `list-sessions` (zellij) parse cleanly.
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+// Pure parsers (exported for tests) — take a multiplexer's raw stdout and return
+// sessions. Kept separate from process spawning so parsing is verifiable.
+// tmux is asked for "<attached>:<name>" — `session_attached` is a single char
+// ("1" when a client is attached), so a fixed 2-char prefix delimits the name
+// without an exotic separator (a literal tab is mishandled by tmux -F), and the
+// name may itself contain ":".
+export function parseTmux(stdout) {
+    return stdout.split("\n").filter((line) => /^[01]:/.test(line)).map((line) => {
+        const attached = line[0] === "1";
+        const name = line.slice(2);
+        return { multiplexer: "tmux", name, attached, target: `tmux:${name}` };
+    });
+}
+export function parseZellij(stdout) {
+    return stripAnsi(stdout).split("\n").map((line) => line.trim())
+        // Lines look like: "name [Created ...] (current)" or "name (EXITED ...)".
+        // Drop exited sessions — they can't be attached to.
+        .filter((line) => line && !/EXITED/i.test(line))
+        .map((line) => {
+        const name = line.split(/\s+/)[0];
+        const attached = /\(current\)/i.test(line);
+        return { multiplexer: "zellij", name, attached, target: `zellij:${name}` };
+    });
+}
+export function parseScreen(stdout) {
+    return stdout.split("\n").map((line) => line.trim()).filter((line) => /^\d+\./.test(line)).map((line) => {
+        const name = line.split(/\s+/)[0]; // e.g. "12345.work"
+        const attached = /\(Attached\)/i.test(line);
+        return { multiplexer: "screen", name, attached, target: `screen:${name}` };
+    });
+}
+export async function listTmux() {
+    // A tab-delimited format keeps parsing robust against names with spaces.
+    const { code, stdout } = await runCmd("tmux", ["list-sessions", "-F", "#{session_attached}:#{session_name}"]);
+    return code === 0 ? parseTmux(stdout) : [];
+}
+export async function listZellij() {
+    const { code, stdout } = await runCmd("zellij", ["list-sessions", "--no-formatting"]);
+    // Older zellij lacks --no-formatting; retry without it.
+    const out = code === 0 ? stdout : (await runCmd("zellij", ["list-sessions"])).stdout;
+    return parseZellij(out);
+}
+export async function listScreen() {
+    // `screen -ls` exits non-zero (1) when listing; parse stdout regardless.
+    const { stdout } = await runCmd("screen", ["-ls"]);
+    return parseScreen(stdout);
+}
+export async function listMultiplexerSessions() {
+    const [tmux, zellij, screen] = await Promise.all([
+        listTmux().catch(() => []),
+        listZellij().catch(() => []),
+        listScreen().catch(() => []),
+    ]);
+    return [...tmux, ...zellij, ...screen];
+}
+/** The PTY command that attaches to a given multiplexer session. */
+export function attachCommand(kind, name) {
+    switch (kind) {
+        case "tmux": return { command: "tmux", args: ["attach", "-t", name] };
+        case "zellij": return { command: "zellij", args: ["attach", name] };
+        case "screen": return { command: "screen", args: ["-r", name] };
+    }
+}

package/dist/native-pi.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { provisionPiAuthJson } from "./runtime/credential-provisioning.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "..");
+// Honor the same overrides as the daemon so packaged/release builds can point
+// at a writable data dir and the bundled pi CLI. Defaults match running from source.
+const dataDir = process.env.BIVY_DATA_DIR ?? path.join(repoRoot, ".bivy");
+const piDir = path.join(dataDir, "pi");
+// The shared, agent-neutral credential vault (not inside any agent's dir).
+const credsDir = path.join(dataDir, "credentials");
+const piCli = process.env.BIVY_PI_CLI ??
+    path.join(repoRoot, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "cli.js");
+const workspace = process.env.BIVY_WORKSPACE ?? repoRoot;
+const args = process.argv.slice(2);
+// Pi's CLI reads its plaintext auth.json; project Bivy's vault (refreshed) so the
+// shared logins are available to the native pi command. Best-effort.
+await provisionPiAuthJson(credsDir, piDir).catch(() => { });
+const child = spawn(process.execPath, [piCli, ...args], {
+    cwd: workspace,
+    stdio: "inherit",
+    env: {
+        ...process.env,
+        PI_CODING_AGENT_DIR: piDir,
+    },
+});
+child.on("exit", (code, signal) => {
+    if (signal)
+        process.kill(process.pid, signal);
+    process.exit(code ?? 0);
+});
+child.on("error", (error) => {
+    console.error("Failed to start terminal agent.", error);
+    process.exit(1);
+});

package/dist/node-stats.js

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// System-resource snapshot for the node the current session runs on.
+//
+// Surfaced to the web app's "Node stats" panel (header ⋯ menu). For each of
+// memory, CPU, and storage it reports three tiers:
+//
+//   * session — the active session's live agent subprocess tree. Agents spawn
+//     per-turn and exit, so this is non-zero only while a turn is running (and
+//     only for runtimes with a separable OS process — Pi runs in-process, and
+//     Claude Code's process lives inside its SDK). `measurable` says whether a
+//     figure could be attributed at all.
+//   * bivy — the whole Bivy node process tree (server + every live agent child +
+//     PTYs). Uniform across runtimes; this is "everything Bivy is using".
+//   * node — the machine total (what's available), so the other two can be shown
+//     as both an absolute figure and a percentage of the whole node.
+import os from "node:os";
+import { promises as fs } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+const pct = (part, whole) => whole > 0 ? Math.min(100, Math.max(0, (part / whole) * 100)) : 0;
+async function psSnapshot() {
+    const table = new Map();
+    try {
+        const { stdout } = await execFileP("ps", ["-Ao", "pid=,ppid=,rss=,pcpu="], {
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: 4000,
+        });
+        for (const line of stdout.split("\n")) {
+            const parts = line.trim().split(/\s+/);
+            if (parts.length < 4)
+                continue;
+            const pid = Number(parts[0]);
+            const ppid = Number(parts[1]);
+            const rssKb = Number(parts[2]);
+            const pcpu = Number(parts[3]);
+            if (!Number.isFinite(pid))
+                continue;
+            table.set(pid, { pid, ppid, rssBytes: (Number.isFinite(rssKb) ? rssKb : 0) * 1024, pcpu: Number.isFinite(pcpu) ? pcpu : 0 });
+        }
+    }
+    catch {
+        // ps missing/blocked — subtree sums degrade to empty (tiers report null).
+    }
+    return table;
+}
+/** All entries in the subtree rooted at `rootPid` (inclusive), by ppid links. */
+function subtree(table, rootPid) {
+    const kids = new Map();
+    for (const p of table.values()) {
+        const list = kids.get(p.ppid);
+        if (list)
+            list.push(p.pid);
+        else
+            kids.set(p.ppid, [p.pid]);
+    }
+    const out = [];
+    const seen = new Set();
+    const stack = [rootPid];
+    while (stack.length) {
+        const pid = stack.pop();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        const entry = table.get(pid);
+        if (entry)
+            out.push(entry);
+        for (const child of kids.get(pid) ?? [])
+            stack.push(child);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// CPU sampling
+// ---------------------------------------------------------------------------
+function sumCpuTimes() {
+    let idle = 0;
+    let total = 0;
+    for (const cpu of os.cpus()) {
+        const t = cpu.times;
+        idle += t.idle;
+        total += t.user + t.nice + t.sys + t.idle + t.irq;
+    }
+    return { idle, total };
+}
+/** Sample node-wide busy% and this process's own busy% over one window. The
+ *  main process's CPU is measured accurately via process.cpuUsage() (the `ps`
+ *  lifetime-average would badly under-report a long-lived server), while agent
+ *  children are attributed from the `ps` snapshot. */
+async function sampleCpu(cores, ms = 150) {
+    const startCpus = sumCpuTimes();
+    const startProc = process.cpuUsage();
+    const startAt = Date.now();
+    await new Promise((r) => setTimeout(r, ms));
+    const endCpus = sumCpuTimes();
+    const endProc = process.cpuUsage(startProc);
+    const elapsedMs = Math.max(1, Date.now() - startAt);
+    const idleDelta = endCpus.idle - startCpus.idle;
+    const totalDelta = endCpus.total - startCpus.total;
+    const nodePct = totalDelta > 0 ? Math.min(100, Math.max(0, (1 - idleDelta / totalDelta) * 100)) : 0;
+    // process.cpuUsage() is microseconds of user+system across all cores this
+    // process used in the window. Convert to a share of one core, then of the node.
+    const procMicros = endProc.user + endProc.system;
+    const mainCorePct = (procMicros / 1000 / elapsedMs) * 100;
+    const mainNodePct = cores > 0 ? Math.min(100, mainCorePct / cores) : 0;
+    return { nodePct, mainNodePct };
+}
+const duCache = new Map();
+async function measureDir(pathStr) {
+    try {
+        // -s summary, -k KiB, -x stay on one filesystem (don't wander into mounts).
+        const { stdout } = await execFileP("du", ["-skx", pathStr], { timeout: 8000, maxBuffer: 1024 * 1024 });
+        const kb = Number(stdout.trim().split(/\s+/)[0]);
+        return Number.isFinite(kb) ? kb * 1024 : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Directory size in bytes, cached for `ttlMs`. `du` can be slow on big trees,
+ *  so a stale value is returned immediately while a refresh runs in the
+ *  background; only the very first call for a path awaits (bounded by du's own
+ *  timeout) so the panel isn't blank on open. */
+async function dirSizeCached(pathStr, ttlMs = 20000) {
+    const now = Date.now();
+    const cached = duCache.get(pathStr);
+    if (cached && now - cached.at < ttlMs)
+        return cached.bytes;
+    const entry = cached ?? { bytes: null, at: 0 };
+    duCache.set(pathStr, entry);
+    if (!entry.inflight) {
+        entry.inflight = (async () => {
+            const bytes = await measureDir(pathStr);
+            entry.bytes = bytes;
+            entry.at = Date.now();
+            entry.inflight = undefined;
+        })();
+    }
+    if (!cached) {
+        try {
+            await entry.inflight;
+        }
+        catch {
+            /* measured to null */
+        }
+    }
+    return entry.bytes;
+}
+async function measureFilesystem(pathStr) {
+    try {
+        const s = await fs.statfs(pathStr);
+        const bsize = Number(s.bsize) || 0;
+        const total = Number(s.blocks) * bsize;
+        const free = Number(s.bavail) * bsize; // available to this unprivileged user
+        const used = Math.max(0, total - Number(s.bfree) * bsize);
+        return { total, free, used };
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectNodeStats(opts) {
+    const cores = os.cpus().length;
+    const cpuModel = os.cpus()[0]?.model?.trim() || null;
+    const [table, cpuSample, fsInfo] = await Promise.all([
+        psSnapshot(),
+        sampleCpu(cores),
+        measureFilesystem(opts.workspacePath),
+    ]);
+    // --- Memory & CPU: Bivy = this process's whole subtree ---
+    const bivyProcs = subtree(table, process.pid);
+    let bivyRss = 0;
+    let bivyChildPcpu = 0;
+    for (const p of bivyProcs) {
+        bivyRss += p.rssBytes;
+        if (p.pid !== process.pid)
+            bivyChildPcpu += p.pcpu;
+    }
+    // If ps gave us nothing (no table), fall back to this process's own RSS.
+    if (bivyProcs.length === 0)
+        bivyRss = process.memoryUsage().rss;
+    const bivyCpuNodePct = Math.min(100, cpuSample.mainNodePct + (cores > 0 ? bivyChildPcpu / cores : 0));
+    // --- Session tier (only when a live, separable agent process exists) ---
+    let sessionMem = null;
+    let sessionCpu = null;
+    let sessionMeasurable = false;
+    if (typeof opts.sessionPid === "number" && table.has(opts.sessionPid)) {
+        const procs = subtree(table, opts.sessionPid);
+        let rss = 0;
+        let pcpu = 0;
+        for (const p of procs) {
+            rss += p.rssBytes;
+            pcpu += p.pcpu;
+        }
+        sessionMeasurable = true;
+        sessionMem = { bytes: rss, pct: pct(rss, os.totalmem()) };
+        sessionCpu = { pct: Math.min(100, cores > 0 ? pcpu / cores : 0) };
+    }
+    const totalMem = os.totalmem();
+    const freeMem = os.freemem();
+    const usedMem = Math.max(0, totalMem - freeMem);
+    // --- Storage ---
+    const [bivyDir, sessionDir] = await Promise.all([
+        opts.appDir ? dirSizeCached(opts.appDir) : Promise.resolve(null),
+        opts.sessionWorkspace ? dirSizeCached(opts.sessionWorkspace) : Promise.resolve(null),
+    ]);
+    const storageTotal = fsInfo?.total ?? 0;
+    return {
+        nodeId: opts.nodeId,
+        name: opts.name ?? null,
+        uptime: os.uptime(),
+        cores,
+        cpuModel,
+        load: (() => {
+            const l = os.loadavg();
+            return [l[0] ?? 0, l[1] ?? 0, l[2] ?? 0];
+        })(),
+        sessionMeasurable,
+        memory: {
+            node: { used: usedMem, total: totalMem, free: freeMem, usedPct: pct(usedMem, totalMem) },
+            bivy: { bytes: bivyRss, pct: pct(bivyRss, totalMem) },
+            session: sessionMem,
+        },
+        cpu: {
+            node: { usedPct: cpuSample.nodePct },
+            bivy: { pct: bivyCpuNodePct },
+            session: sessionCpu,
+        },
+        storage: {
+            node: fsInfo ? { path: opts.workspacePath, used: fsInfo.used, total: fsInfo.total, free: fsInfo.free, usedPct: pct(fsInfo.used, fsInfo.total) } : null,
+            bivy: bivyDir != null ? { bytes: bivyDir, pct: pct(bivyDir, storageTotal) } : null,
+            session: sessionDir != null ? { bytes: sessionDir, pct: pct(sessionDir, storageTotal) } : null,
+        },
+        at: new Date().toISOString(),
+    };
+}