@nredd/pi-resource-sampler 0.1.0 → 0.1.1

package/README.md

@@ -2,7 +2,12 @@
 
 Pi-independent, dependency-free ESM library for passive host resource dashboards and snapshots.
 `@nredd/pi-resource-sampler` is not a Pi extension. No tools, timers, hooks, output or policy are
-registered. Initial implementation only; no consumer migration or npm publication in this PR.
+registered. Runs on Node >=22.14 and Bun.
+
+Upgrade from `0.1.0`, which is unsafe: on Darwin it reported `ps -c -o comm`, the basename of argv[0],
+so a launcher-chosen argv[0] or Node `process.title` (e.g. `npm exec <package> mcp`) leaked into
+`processes[].name`. On Bun, host `cpu` read lazily populated `os.cpus()` objects, so the second sample
+was `warming` and the third could be a fictional 0 or 100. `0.1.1` keeps the same TypeScript interface.
 
 ```ts
 import { createResourceSampler } from '@nredd/pi-resource-sampler';
@@ -27,10 +32,12 @@ Semantics:
 - `processes[].cpu`: Linux user+system counter delta divided by monotonic elapsed milliseconds.
   100 means one logical core, multi-threaded processes can exceed 100. Linux `CLK_TCK` is read
   once with fixed `/usr/bin/getconf CLK_TCK`; no assumed tick rate or RSS page size.
-- Linux identity includes the exact `/proc/PID/stat` start tick string. Read stat/status/stat and
+- Linux identity includes the exact `/proc/PID/stat` start tick string. Read stat/exe/status/stat and
   reject identity changes during RSS collection. Missing or inaccessible processes are skipped and
   invalidate their old baselines. New/reused PIDs and counter resets warm rather than showing zero.
-- Darwin uses only `/bin/ps -A -c -o pid=,ppid=,lstart=,time=,rss=,comm=` with `LC_ALL=C`.
+- `cpu` copies every `os.cpus()` counter when sampled. Bun returns lazy placeholders that read native
+  counters on first property access; an unread stored baseline would describe a later instant.
+- Darwin uses only `/bin/ps -A -o pid=,ppid=,lstart=,time=,rss=,ucomm=` with `LC_ALL=C`.
   Actual macOS observation: `time` prints hundredths (e.g. `185:32.40`), but `lstart` prints only
   seconds (`Sat Oct 3 01:49:05 2026`). That cannot rule out PID reuse within one second, so Darwin
   process interval CPU is explicitly `unavailable`. No decaying `%cpu` is relabelled as an interval.
@@ -40,15 +47,34 @@ Semantics:
 - `memory.freeBytes` means free, NOT available or pressure. `loadAverage` is load, NOT percent.
   Linux memory PSI preserves native `some`/optional `full`, avg10/60/300 percentages and cumulative
   stall microseconds. Missing/invalid PSI is unavailable. Other platforms explicitly have no PSI.
-- Names are bounded basenames with control characters removed; no arguments, environments,
-  user names, executable paths or agent attribution are collected. Process names remain untrusted
-  display strings; consumers must not execute or interpret them.
+- `processes[].name` is an executable basename from kernel metadata. It excludes argv, environment,
+  process title and Linux comm, but it is still untrusted metadata that the process or its launcher can
+  choose (see the last item). `""` means unavailable, not a process called nothing:
+  - Darwin: `ucomm`, which `ps` prints from kinfo `p_comm`. XNU writes it only at exec, from the
+    looked-up executable file name, truncated to 16 bytes (`Google Chrome He`). `ps -c -o comm` is
+    argv[0] and is NOT used.
+  - Linux: basename of `readlink /proc/PID/exe` (` (deleted)` marker removed), read between the two
+    identity-checked stat reads. The kernel gates that link by ptrace read access, so other users'
+    processes are usually `""` without privileges. `/proc/PID/stat` comm is NOT used:
+    `prctl(PR_SET_NAME)`, `/proc/self/comm` and Node's `process.title` rewrite it. Kernel threads
+    have no `VmRSS`, so they are skipped (`process-unreadable-or-changed`) and never named.
+  - Whoever names, links or copies the executable file chooses the name. On Linux a process can also
+    exec a `memfd_create` file it named itself (`memfd:<name>`), and a privileged one can replace its
+    exe link with `prctl(PR_SET_MM_EXE_FILE)`. Names are bounded to 128 code points with control
+    characters replaced, no user names, paths or agent attribution are collected, and consumers must
+    treat them as untrusted display text, never execute or interpret them.
 
 Bounds:
 
 - Default scan budget 250ms, 2048 PIDs, 2MiB captured bytes; options allow at most 5s, 16384 PIDs,
   16MiB. Linux proc files read sequentially (concurrency one), at most 8KiB each. Directory iteration
   stops at the budget; Darwin output stops at the PID/output budget and reaps the fixed helper.
+- `/proc/PID/exe` is a `readlink`, which Node and Bun cannot cap: each call copies up to PATH_MAX
+  (4096) bytes into a fixed runtime buffer before the length is known. That fixed per-call syscall
+  copy can exceed the remaining budget; the logical budget cannot. A target longer than the remainder
+  is charged the remainder and its name dropped (`""`, `byte-limit`), so `bytesRead <= maxBytes`. A
+  target filling the 4096-byte buffer may be truncated: Node returns it silently and the name is
+  dropped too (`file-byte-limit`); Bun refuses it with `ENAMETOOLONG`, so the name is `""`.
 - `coverage.complete`, `enumerated`, `sampled`, `skipped`, `bytesRead` and reasons describe partial
   coverage explicitly. `enumerated` is encountered rows, not total processes when partial. Truncation
   is not a host-wide top-process ranking. OS enumeration order may favor the same subset each time.
@@ -67,7 +93,10 @@ scans (2.6ms/sample, excludes helper CPU); a separate fixed `ps` invocation meas
 real-input gate and reports its snapshot duration/coverage.
 
 Development: `npm run check --workspace @nredd/pi-resource-sampler` (single-worker tests, including
-actual host samples and child cleanup); `make check-resource-sampler-contract` builds and exercises
+actual host samples and child cleanup). `test/runtime.test.ts` runs under both Vitest (Node) and
+`bun test`: it starts a child whose argv[0], argv, environment, process title and (Linux) comm hold a
+random secret, proves the 0.1.0 source exposes it, then requires no 12-character fragment in the
+snapshot, plus three real CPU samples. `make check-resource-sampler-contract` builds and exercises
 an isolated installed tarball, with no Pi or siblings. Both run on existing macOS/Linux CI jobs.
 `dist` contains compiled ESM and declarations; the exact packed payload is contract-pinned. No install
 scripts or runtime dependencies. New npm-name ownership bootstrap requires the owner's interactive

package/dist/collect.d.ts

@@ -15,6 +15,14 @@ export declare class Budget {
     ready(): boolean;
     /** Fixed-size proc read: no unbounded readFile allocation, and always await handle closure. */
     read(path: string): Promise<string>;
+    /**
+     * Linux executable basename, or "" when the exe link is unreadable (other users' processes without
+     * ptrace read access, exited processes), over budget or possibly truncated. Errors carry no detail
+     * outward. Node and Bun cannot cap readlink below their fixed PATH_MAX buffer, so the length is only
+     * known after the syscall: a target beyond the remaining budget is charged the remainder and dropped,
+     * keeping `bytesRead <= maxBytes`. Node returns a full buffer silently truncated, so that is dropped too.
+     */
+    executable(path: string): Promise<string>;
 }
 /** Fixed executable/argv only. Bound capture, kill on cancellation/deadline, await close/reaping. */
 export declare function command(executable: string, args: string[], budget: Budget, maxLines?: number): Promise<{
@@ -23,7 +31,10 @@ export declare function command(executable: string, args: string[], budget: Budg
 }>;
 /** Linux scan is sequential and closes the directory even on cancellation. */
 export declare function linuxProcesses(budget: Budget, hz: number): Promise<ProcessCounter[]>;
-/** Fixed metadata-only ps format; -c suppresses executable paths and arguments on Darwin. */
+/**
+ * Fixed metadata-only ps format. `ucomm` prints kinfo `p_comm`, never `comm`: `ps -c -o comm` shows the
+ * basename of argv[0], which any launcher picks and Node's `process.title` rewrites in place.
+ */
 export declare function darwinProcesses(budget: Budget): Promise<ProcessCounter[]>;
 /** PSI is optional and platform-specific; absence is not zero pressure. */
 export declare function pressure(budget: Budget, platform: string): Promise<ResourceSnapshot["pressure"]>;

package/dist/collect.js

@@ -1,7 +1,9 @@
 import { spawn } from "node:child_process";
-import { open, opendir } from "node:fs/promises";
+import { open, opendir, readlink } from "node:fs/promises";
 import { performance } from "node:perf_hooks";
-import { darwinProcess, linuxRss, linuxStat, psi } from "./counters.js";
+import { darwinProcess, executableName, linuxRss, linuxStat, psi } from "./counters.js";
+/** Linux PATH_MAX: Node (libuv `pathconf`) and Bun (`PathBuffer`) readlink buffer size on Linux. */
+const LINK_BUFFER_BYTES = 4096;
 /** Per-scan mutable budget, never shared between sampler instances. */
 export class Budget {
     deadline;
@@ -52,6 +54,38 @@ export class Budget {
             await file.close();
         }
     }
+    /**
+     * Linux executable basename, or "" when the exe link is unreadable (other users' processes without
+     * ptrace read access, exited processes), over budget or possibly truncated. Errors carry no detail
+     * outward. Node and Bun cannot cap readlink below their fixed PATH_MAX buffer, so the length is only
+     * known after the syscall: a target beyond the remaining budget is charged the remainder and dropped,
+     * keeping `bytesRead <= maxBytes`. Node returns a full buffer silently truncated, so that is dropped too.
+     */
+    async executable(path) {
+        if (!this.ready())
+            return "";
+        let target;
+        try {
+            target = await readlink(path, { encoding: "buffer" });
+        }
+        catch {
+            this.signal.throwIfAborted();
+            return "";
+        }
+        this.signal.throwIfAborted();
+        const remaining = this.maxBytes - this.bytesRead;
+        if (target.length > remaining) {
+            this.bytesRead = this.maxBytes;
+            this.reasons.add("byte-limit");
+            return "";
+        }
+        this.bytesRead += target.length;
+        if (target.length >= LINK_BUFFER_BYTES) {
+            this.reasons.add("file-byte-limit");
+            return "";
+        }
+        return executableName(target.toString("utf8"));
+    }
 }
 /** Fixed executable/argv only. Bound capture, kill on cancellation/deadline, await close/reaping. */
 export async function command(executable, args, budget, maxLines = Number.POSITIVE_INFINITY) {
@@ -135,11 +169,15 @@ export async function linuxProcesses(budget, hz) {
         try {
             const path = `/proc/${entry.name}`;
             const first = linuxStat(await budget.read(`${path}/stat`), hz, performance.now());
+            if (!first)
+                throw new Error("process incomplete");
+            const name = await budget.executable(`${path}/exe`);
             const rssBytes = linuxRss(await budget.read(`${path}/status`));
             const last = linuxStat(await budget.read(`${path}/stat`), hz, performance.now());
-            if (!first || !last || first.pid !== Number(entry.name) || first.identity !== last.identity || rssBytes === null)
+            // The name and RSS reads sit between two stat reads, so PID reuse rejects both.
+            if (!last || first.pid !== Number(entry.name) || first.identity !== last.identity || rssBytes === null)
                 throw new Error("process changed or incomplete");
-            result.push({ ...last, rssBytes });
+            result.push({ ...last, name, rssBytes });
         }
         catch {
             budget.signal.throwIfAborted();
@@ -149,9 +187,12 @@ export async function linuxProcesses(budget, hz) {
     }
     return result;
 }
-/** Fixed metadata-only ps format; -c suppresses executable paths and arguments on Darwin. */
+/**
+ * Fixed metadata-only ps format. `ucomm` prints kinfo `p_comm`, never `comm`: `ps -c -o comm` shows the
+ * basename of argv[0], which any launcher picks and Node's `process.title` rewrites in place.
+ */
 export async function darwinProcesses(budget) {
-    const { text } = await command("/bin/ps", ["-A", "-c", "-o", "pid=,ppid=,lstart=,time=,rss=,comm="], budget, budget.maxPids);
+    const { text } = await command("/bin/ps", ["-A", "-o", "pid=,ppid=,lstart=,time=,rss=,ucomm="], budget, budget.maxPids);
     const result = [];
     for (const line of text.split("\n")) {
         if (!line.trim())

package/dist/counters.d.ts

@@ -10,17 +10,32 @@ export interface ProcessCounter {
     cpuMs: number;
     at: number;
 }
+/**
+ * Copy counters immediately. Bun's `os.cpus()` returns lazy placeholders that read native counters on
+ * first property access, so a stored but unread array would silently describe a later instant.
+ */
+export declare function cpuSnapshot(list: readonly CpuInfo[]): CpuInfo[];
 /** Compute an aggregate interval, validating each core and each counter before summing. */
 export declare function hostCpu(previous: CpuInfo[] | undefined, current: CpuInfo[]): Metric<number>;
 /** CPU milliseconds divided by monotonic wall milliseconds, not a lifetime/decaying ps average. */
 export declare function processCpu(previous: ProcessCounter | undefined, current: ProcessCounter): Metric<number>;
-/** Bound display names and strip terminal controls; paths/arguments never leave the parser. */
+/** Bound display names by code point and replace terminal controls; directories never leave the parser. */
 export declare function safeName(value: string): string;
-/** Parse Linux stat's parenthesized comm safely, including embedded spaces and ')' characters. */
+/** Basename of a Linux `/proc/PID/exe` target, without the kernel's unlinked-file marker. */
+export declare function executableName(target: string): string;
+/**
+ * Parse Linux stat, skipping the parenthesized comm safely (embedded spaces and ')' characters). comm is
+ * NOT a name source: processes rewrite it (`prctl(PR_SET_NAME)`, `/proc/self/comm`, Node's
+ * `process.title`). `name` stays ""; callers derive it from `/proc/PID/exe`.
+ */
 export declare function linuxStat(text: string, hz: number, at: number): ProcessCounter | null;
 /** RSS comes from status in KiB, avoiding an assumed host page size. */
 export declare function linuxRss(text: string): number | null;
-/** Darwin lstart has only one-second identity precision; do not derive interval CPU from it. */
+/**
+ * Parse `ps -o pid=,ppid=,lstart=,time=,rss=,ucomm=`. `ucomm` is the kernel's `p_comm`, written only at
+ * exec from the executable file name (at most 16 bytes); it is not argv[0] or the process title.
+ * Darwin lstart has only one-second identity precision; do not derive interval CPU from it.
+ */
 export declare function darwinProcess(line: string, at: number): ProcessCounter | null;
 /** Parse native PSI percentages and cumulative stall microseconds, rejecting malformed values. */
 export declare function psi(text: string): {

package/dist/counters.js

@@ -1,4 +1,15 @@
 import { basename } from "node:path";
+/**
+ * Copy counters immediately. Bun's `os.cpus()` returns lazy placeholders that read native counters on
+ * first property access, so a stored but unread array would silently describe a later instant.
+ */
+export function cpuSnapshot(list) {
+    return list.map(({ model, speed, times }) => ({
+        model,
+        speed,
+        times: { user: times.user, nice: times.nice, sys: times.sys, idle: times.idle, irq: times.irq },
+    }));
+}
 /** Compute an aggregate interval, validating each core and each counter before summing. */
 export function hostCpu(previous, current) {
     if (!previous || previous.length !== current.length || current.length === 0) {
@@ -40,13 +51,21 @@ export function processCpu(previous, current) {
     }
     return { state: "available", value: (cpu / elapsed) * 100 };
 }
-/** Bound display names and strip terminal controls; paths/arguments never leave the parser. */
+/** Bound display names by code point and replace terminal controls; directories never leave the parser. */
 export function safeName(value) {
-    return basename(value)
-        .replace(/[\p{C}]/gu, "?")
-        .slice(0, 128);
+    return Array.from(basename(value).replace(/[\p{C}]/gu, "?"))
+        .slice(0, 128)
+        .join("");
+}
+/** Basename of a Linux `/proc/PID/exe` target, without the kernel's unlinked-file marker. */
+export function executableName(target) {
+    return safeName(target.endsWith(" (deleted)") ? target.slice(0, -" (deleted)".length) : target);
 }
-/** Parse Linux stat's parenthesized comm safely, including embedded spaces and ')' characters. */
+/**
+ * Parse Linux stat, skipping the parenthesized comm safely (embedded spaces and ')' characters). comm is
+ * NOT a name source: processes rewrite it (`prctl(PR_SET_NAME)`, `/proc/self/comm`, Node's
+ * `process.title`). `name` stays ""; callers derive it from `/proc/PID/exe`.
+ */
 export function linuxStat(text, hz, at) {
     const start = text.indexOf("(");
     const end = text.lastIndexOf(")");
@@ -69,7 +88,7 @@ export function linuxStat(text, hz, at) {
     return {
         pid,
         parentPid,
-        name: safeName(text.slice(start + 1, end)),
+        name: "",
         identity: `${pid}:${identity}`,
         rssBytes: 0,
         cpuMs: ((user + system) / hz) * 1000,
@@ -84,7 +103,11 @@ export function linuxRss(text) {
     const bytes = Number(match[1]) * 1024;
     return Number.isSafeInteger(bytes) ? bytes : null;
 }
-/** Darwin lstart has only one-second identity precision; do not derive interval CPU from it. */
+/**
+ * Parse `ps -o pid=,ppid=,lstart=,time=,rss=,ucomm=`. `ucomm` is the kernel's `p_comm`, written only at
+ * exec from the executable file name (at most 16 bytes); it is not argv[0] or the process title.
+ * Darwin lstart has only one-second identity precision; do not derive interval CPU from it.
+ */
 export function darwinProcess(line, at) {
     const match = /^\s*(\d+)\s+(\d+)\s+(\w{3}\s+\w{3}\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(\S+)\s+(\d+)\s+(.*?)\s*$/.exec(line);
     if (!match?.[1] || !match[2] || !match[3] || !match[5] || match[6] === undefined)

package/dist/index.js

@@ -1,7 +1,7 @@
 import { cpus, freemem, loadavg, platform, totalmem } from "node:os";
 import { performance } from "node:perf_hooks";
 import { Budget, command, darwinProcesses, linuxProcesses, pressure } from "./collect.js";
-import { hostCpu, processCpu } from "./counters.js";
+import { cpuSnapshot, hostCpu, processCpu } from "./counters.js";
 /** Validate bounded integers before collecting any host information. */
 function bounded(value, fallback, min, max) {
     const result = value ?? fallback;
@@ -27,7 +27,7 @@ export function createResourceSampler(options = {}) {
         const wallTimeMs = Date.now();
         const budget = new Budget(start + duration, maxBytes, maxPids, signal);
         signal.throwIfAborted();
-        const currentCpus = cpus();
+        const currentCpus = cpuSnapshot(cpus());
         const cpu = previousTime !== undefined && start <= previousTime
             ? { state: "warming", reason: "invalid monotonic interval" }
             : hostCpu(previousCpus, currentCpus);

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export type Metric<T> = {
 export interface ProcessSample {
     pid: number;
     parentPid: number;
+    /**
+     * Executable basename from kernel metadata, never argv, environment, process title or Linux comm:
+     * Darwin `p_comm` (at most 16 bytes), Linux `/proc/PID/exe` basename. "" means unavailable,
+     * e.g. another user's Linux process. Untrusted display text: whoever names the file chooses it, and
+     * a Linux process can exec a `memfd_create` file it named itself.
+     */
     name: string;
     identity: string;
     rssBytes: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-resource-sampler",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Bounded, privacy-safe host resource interval sampling without Pi dependencies.",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,8 @@
     "lint": "biome check src test",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --maxWorkers=1",
-    "check": "npm run lint && npm run typecheck && npm run build && npm test"
+    "test:bun": "bun test test/runtime.test.ts",
+    "check": "npm run lint && npm run typecheck && npm run build && npm test && npm run test:bun"
   },
   "devDependencies": { "@biomejs/biome": "2.5.15", "@types/node": "26.6.5", "typescript": "7.0.2", "vitest": "5.0.3" }
 }