@bridge4dev/runner 0.70.1 → 0.71.0

package/dist/host-load.d.ts

@@ -6,11 +6,13 @@
  * is on its knees», so it said nothing, and the first symptom a user saw was a
  * session that had gone quiet (plan `agent-sessions-host-resources.md` §5.3).
  *
- * Two files and nothing else. That is a security property, not an
- * implementation detail: this runner reports to a server, so what it may read
- * for telemetry is listed here in full — `/proc/loadavg` and `/proc/meminfo`,
- * both world-readable, neither containing a path, a command line, an
- * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
+ * Two files and one filesystem call, and nothing else. That is a security
+ * property, not an implementation detail: this runner reports to a server, so
+ * what it may read for telemetry is listed here in full — `/proc/loadavg` and
+ * `/proc/meminfo`, both world-readable, neither containing a path, a command
+ * line, an environment variable or a process name; and `statfs('/')` (0.71.0,
+ * #485), which answers four sizes of the root filesystem and nothing about what
+ * is on it. No `/proc/<pid>` walk, no `ps`, no directory listing, no `du`.
  *
  * **One module is allowed past that line, and it is named here so the rule and
  * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
@@ -89,6 +91,13 @@ export interface HostLoadFrame {
     /** Zero on a machine with no swap; consumers must not divide blindly. */
     swapTotalBytes: number;
     swapFreeBytes: number;
+    /**
+     * The root filesystem (0.71.0, #485) – or `null` when it could not be read,
+     * which is «disk unknown» and never a reason to hold the rest of the frame
+     * back. It rides the same minute-long heartbeat as everything else here: a
+     * disk fills over hours, and a trigger of its own would buy nothing.
+     */
+    disk: HostDiskFrame | null;
     /**
      * When THIS MACHINE measured it, ISO.
      *
@@ -98,6 +107,31 @@ export interface HostLoadFrame {
      */
     at: string;
 }
+/**
+ * Free space on the root filesystem – what a full disk stops the machine at.
+ *
+ * Mirror of `HostDiskFrameSchema` in `@devbridge/shared`. The same arithmetic as
+ * the DevBridge host's own reading (`admin-host.service.ts`), so «free» means one
+ * thing on the Fleet screen whichever machine it describes: `freeBytes` is
+ * `bavail` (what an unprivileged writer can still use, not `bfree`), `usedBytes`
+ * is total − `bfree` (what `df` calls used).
+ */
+export interface HostDiskFrame {
+    /** Always {@link HOST_DISK_PATH} today; carried so the reading describes itself. */
+    path: string;
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+}
+/** The filesystem measured: the root, where running out stops everything. */
+export declare const HOST_DISK_PATH = "/";
+/** What `fs.statfsSync` answers, as far as a size is concerned. */
+export interface DiskStats {
+    bsize: number;
+    blocks: number;
+    bfree: number;
+    bavail: number;
+}
 /** Test seams. Production calls `readHostLoad()` with nothing. */
 export interface HostLoadSources {
     /**
@@ -111,7 +145,21 @@ export interface HostLoadSources {
     cpuCount?: number;
     /** The clock behind `at`. */
     now?: () => Date;
+    /**
+     * `statfs`, for the same reason as `procDir`: a full disk, a filesystem that
+     * refuses the call and a reading that does not add up are exactly the states a
+     * test machine is not in.
+     */
+    statfs?: (target: string) => DiskStats;
 }
+/**
+ * Measure the root filesystem, or say honestly that we cannot.
+ *
+ * Every number has to be a whole, non-negative, safely representable count of
+ * bytes that fits inside the total – the API's schema holds the same line, and a
+ * reading it would refuse is better not sent than sent. Any doubt is `null`.
+ */
+export declare function readRootDisk(statfs?: (target: string) => DiskStats): HostDiskFrame | null;
 /**
  * Measure this machine, or say honestly that we cannot.
  *

package/dist/host-load.js

@@ -9,11 +9,13 @@ import path from 'node:path';
  * is on its knees», so it said nothing, and the first symptom a user saw was a
  * session that had gone quiet (plan `agent-sessions-host-resources.md` §5.3).
  *
- * Two files and nothing else. That is a security property, not an
- * implementation detail: this runner reports to a server, so what it may read
- * for telemetry is listed here in full — `/proc/loadavg` and `/proc/meminfo`,
- * both world-readable, neither containing a path, a command line, an
- * environment variable or a process name. No `/proc/<pid>` walk, no `ps`.
+ * Two files and one filesystem call, and nothing else. That is a security
+ * property, not an implementation detail: this runner reports to a server, so
+ * what it may read for telemetry is listed here in full — `/proc/loadavg` and
+ * `/proc/meminfo`, both world-readable, neither containing a path, a command
+ * line, an environment variable or a process name; and `statfs('/')` (0.71.0,
+ * #485), which answers four sizes of the root filesystem and nothing about what
+ * is on it. No `/proc/<pid>` walk, no `ps`, no directory listing, no `du`.
  *
  * **One module is allowed past that line, and it is named here so the rule and
  * the code cannot drift apart:** `session-stall.ts` reads `/proc/<pid>` for the
@@ -66,7 +68,36 @@ export const HOST_LOAD_HEARTBEAT_MS = 60_000;
 export const HOST_LOAD_MIN_DELTA_LOAD1 = 0.5;
 /** The same idea for memory, as a fraction — see `hostLoadChangedEnough`. */
 export const HOST_LOAD_MIN_DELTA_MEM_RATIO = 0.05;
+/** The filesystem measured: the root, where running out stops everything. */
+export const HOST_DISK_PATH = '/';
 const PROC_DIR = '/proc';
+/**
+ * Measure the root filesystem, or say honestly that we cannot.
+ *
+ * Every number has to be a whole, non-negative, safely representable count of
+ * bytes that fits inside the total – the API's schema holds the same line, and a
+ * reading it would refuse is better not sent than sent. Any doubt is `null`.
+ */
+export function readRootDisk(statfs = fs.statfsSync) {
+    try {
+        const stat = statfs(HOST_DISK_PATH);
+        const totalBytes = stat.blocks * stat.bsize;
+        const freeBytes = stat.bavail * stat.bsize;
+        const usedBytes = Math.max(0, totalBytes - stat.bfree * stat.bsize);
+        const whole = (value) => Number.isSafeInteger(value) && value >= 0;
+        if (!whole(totalBytes) || totalBytes === 0 || !whole(freeBytes) || !whole(usedBytes)) {
+            return null;
+        }
+        if (freeBytes > totalBytes || usedBytes > totalBytes)
+            return null;
+        return { path: HOST_DISK_PATH, totalBytes, freeBytes, usedBytes };
+    }
+    catch {
+        // ENOSYS in an odd container, EACCES under a locked-down profile: the disk
+        // is unknown, and the load beside it is still worth sending.
+        return null;
+    }
+}
 /** kB in `/proc/meminfo` means kibibytes, and has since the field was added. */
 const MEMINFO_UNIT_BYTES = 1024;
 /**
@@ -158,6 +189,9 @@ export function readHostLoad(sources = {}) {
             memAvailableBytes,
             swapTotalBytes,
             swapFreeBytes,
+            // Its own failure is `null` inside the frame, never a missing frame: a
+            // machine whose filesystem refuses `statfs` still has a load worth showing.
+            disk: readRootDisk(sources.statfs),
             at,
         };
     }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const RUNNER_VERSION = "0.70.1";
+export declare const RUNNER_VERSION = "0.71.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in sync with package.json by the release script (manual for now).
-export const RUNNER_VERSION = '0.70.1';
+export const RUNNER_VERSION = '0.71.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge4dev/runner",
-  "version": "0.70.1",
+  "version": "0.71.0",
   "description": "DevBridge dev runner — connects a dev server to DevBridge and runs agent sessions (Claude Code / Codex)",
   "homepage": "https://bridge4.dev",
   "license": "MIT",