@nredd/pi-resource-sampler 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Redd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# Resource sampler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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. 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';
+const sampler = createResourceSampler();
+try {
+  const snapshot = await sampler.sample();
+  // Caller schedules subsequent samples and renders typed metrics.
+} finally {
+  await sampler.dispose();
+}
+```
+
+`sample(signal?)` returns `ResourceSnapshot` v1. Concurrent calls reject. Cancellation rejects and
+awaits cleanup; `dispose()` aborts and awaits any active sample, is idempotent, and forbids future
+samples. Importing/constructing the library does not collect data. Each instance owns its baseline.
+
+Semantics:
+
+- `cpu`: aggregate host CPU counter delta, 0..100. Core count/model changes, individual counter
+  rollback, initial samples, invalid intervals and counters that have not advanced are `warming`,
+  never fabricated zero. Uses Node's native `os.cpus()` counters, not load average.
+- `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/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.
+- `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.
+  RSS/name/parent PID remain useful. No native helper until this limitation justifies one separately.
+- `wallTimeMs` labels the start; `monotonicTimeMs` controls intervals. Per-process reads have their own
+  monotonic timestamps internally; the scan is not atomic. `durationMs` includes collection.
+- `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.
+- `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.
+- Deadline is a monotonic admission/child-kill bound, not a real-time guarantee: event-loop scheduling,
+  native `os.cpus()` and in-flight filesystem calls cannot be preempted. Cleanup is always awaited.
+  Helpers spawn no descendants, use no shell, stdin ignored, fixed environment, bounded stdout/stderr,
+  immediate SIGKILL on abort/deadline/cap, and resolve only on close. No persistent children or workers.
+- Unsupported platforms keep native host metrics but report process coverage unavailable.
+
+Local overhead observation (2026-10-22, Darwin arm64, Node 26.12.0, 10 logical CPUs, 16GiB RAM,
+load about 6, not a quiet-runner benchmark): ten scans of 557 processes took 17.5-24.9ms each,
+about 41.3KB captured, all complete. The Node collector consumed 25.7ms CPU total across ten
+scans (2.6ms/sample, excludes helper CPU); a separate fixed `ps` invocation measured 0.02s wall,
+0.01s system CPU and 3.0MB peak RSS at `/usr/bin/time -lp` precision. Consumers should poll around
+1s, not every render frame. Linux cost is not inferred from macOS; native Linux CI runs the same
+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). `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
+2FA/staged publication and trusted-publisher setup; nothing is published automatically by this PR.

package/dist/collect.d.ts

@@ -0,0 +1,40 @@
+import { type ProcessCounter } from "./counters.js";
+import type { ResourceSnapshot } from "./types.js";
+/** Per-scan mutable budget, never shared between sampler instances. */
+export declare class Budget {
+    readonly deadline: number;
+    readonly maxBytes: number;
+    readonly maxPids: number;
+    readonly signal: AbortSignal;
+    bytesRead: number;
+    enumerated: number;
+    skipped: number;
+    readonly reasons: Set<string>;
+    constructor(deadline: number, maxBytes: number, maxPids: number, signal: AbortSignal);
+    remaining(): number;
+    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<{
+    text: string;
+    complete: boolean;
+}>;
+/** 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. `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

@@ -0,0 +1,231 @@
+import { spawn } from "node:child_process";
+import { open, opendir, readlink } from "node:fs/promises";
+import { performance } from "node:perf_hooks";
+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;
+    maxBytes;
+    maxPids;
+    signal;
+    bytesRead = 0;
+    enumerated = 0;
+    skipped = 0;
+    reasons = new Set();
+    constructor(deadline, maxBytes, maxPids, signal) {
+        this.deadline = deadline;
+        this.maxBytes = maxBytes;
+        this.maxPids = maxPids;
+        this.signal = signal;
+    }
+    remaining() {
+        this.signal.throwIfAborted();
+        return Math.max(0, this.deadline - performance.now());
+    }
+    ready() {
+        if (this.remaining() <= 0)
+            this.reasons.add("deadline");
+        if (this.bytesRead >= this.maxBytes)
+            this.reasons.add("byte-limit");
+        return this.remaining() > 0 && this.bytesRead < this.maxBytes;
+    }
+    /** Fixed-size proc read: no unbounded readFile allocation, and always await handle closure. */
+    async read(path) {
+        if (!this.ready())
+            throw new Error("budget exhausted");
+        const capacity = Math.min(8192, this.maxBytes - this.bytesRead);
+        const file = await open(path, "r");
+        try {
+            if (!this.ready())
+                throw new Error("budget exhausted while opening proc file");
+            const buffer = Buffer.alloc(capacity);
+            const { bytesRead } = await file.read(buffer, 0, capacity, 0);
+            this.bytesRead += bytesRead;
+            this.signal.throwIfAborted();
+            if (bytesRead === capacity) {
+                this.reasons.add("file-byte-limit");
+                throw new Error("proc file may be truncated");
+            }
+            return buffer.toString("utf8", 0, bytesRead);
+        }
+        finally {
+            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) {
+    if (!budget.ready())
+        return { text: "", complete: false };
+    return new Promise((resolve) => {
+        const child = spawn(executable, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { LC_ALL: "C", PATH: "/usr/bin:/bin" },
+        });
+        const buffers = [];
+        let complete = true;
+        let lines = 0;
+        const stop = (reason) => {
+            complete = false;
+            budget.reasons.add(reason);
+            child.kill("SIGKILL");
+        };
+        const abort = () => stop("cancelled");
+        const timer = setTimeout(() => stop("deadline"), budget.remaining());
+        budget.signal.addEventListener("abort", abort, { once: true });
+        // Close the race between the ready check and listener registration.
+        if (budget.signal.aborted)
+            abort();
+        child.stdout.on("data", (data) => {
+            if (!complete)
+                return;
+            const remaining = budget.maxBytes - budget.bytesRead;
+            const kept = data.subarray(0, remaining);
+            budget.bytesRead += kept.length;
+            let end = kept.length;
+            for (let i = 0; i < kept.length; i++) {
+                if (kept[i] === 10 && ++lines > maxLines) {
+                    end = i + 1;
+                    stop("pid-limit");
+                    break;
+                }
+            }
+            buffers.push(kept.subarray(0, end));
+            if (data.length >= remaining)
+                stop("byte-limit");
+        });
+        child.stderr.on("data", (data) => {
+            const remaining = budget.maxBytes - budget.bytesRead;
+            budget.bytesRead += Math.min(remaining, data.length);
+            if (data.length >= remaining)
+                stop("byte-limit");
+        });
+        child.on("error", () => {
+            complete = false;
+            budget.reasons.add("command-unavailable");
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            budget.signal.removeEventListener("abort", abort);
+            if (code !== 0 && complete) {
+                complete = false;
+                budget.reasons.add("command-failed");
+            }
+            let text = Buffer.concat(buffers).toString("utf8");
+            if (!complete)
+                text = text.slice(0, text.lastIndexOf("\n") + 1);
+            resolve({ text, complete });
+        });
+    });
+}
+/** Linux scan is sequential and closes the directory even on cancellation. */
+export async function linuxProcesses(budget, hz) {
+    const result = [];
+    const directory = await opendir("/proc");
+    for await (const entry of directory) {
+        if (!/^\d+$/.test(entry.name))
+            continue;
+        if (!budget.ready())
+            break;
+        if (budget.enumerated >= budget.maxPids) {
+            budget.reasons.add("pid-limit");
+            break;
+        }
+        budget.enumerated++;
+        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());
+            // 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, name, rssBytes });
+        }
+        catch {
+            budget.signal.throwIfAborted();
+            budget.skipped++;
+            budget.reasons.add("process-unreadable-or-changed");
+        }
+    }
+    return result;
+}
+/**
+ * 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", "-o", "pid=,ppid=,lstart=,time=,rss=,ucomm="], budget, budget.maxPids);
+    const result = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        if (budget.enumerated >= budget.maxPids) {
+            budget.reasons.add("pid-limit");
+            break;
+        }
+        budget.enumerated++;
+        const parsed = darwinProcess(line, performance.now());
+        if (parsed)
+            result.push(parsed);
+        else {
+            budget.skipped++;
+            budget.reasons.add("malformed-process-row");
+        }
+    }
+    return result;
+}
+/** PSI is optional and platform-specific; absence is not zero pressure. */
+export async function pressure(budget, platform) {
+    if (platform !== "linux")
+        return { source: "unsupported", reason: "no comparable native PSI metric on this platform" };
+    try {
+        const value = psi(await budget.read("/proc/pressure/memory"));
+        if (value)
+            return { source: "linux-psi", memory: { state: "available", value } };
+    }
+    catch {
+        budget.signal.throwIfAborted();
+    }
+    return {
+        source: "linux-psi",
+        memory: { state: "unavailable", reason: "PSI absent, invalid or scan budget exhausted" },
+    };
+}

package/dist/counters.d.ts

@@ -0,0 +1,44 @@
+import type { CpuInfo } from "node:os";
+import type { Metric, PsiLine } from "./types.js";
+/** Internal raw process counter with a per-read monotonic timestamp. */
+export interface ProcessCounter {
+    pid: number;
+    parentPid: number;
+    name: string;
+    identity: string;
+    rssBytes: number;
+    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 by code point and replace terminal controls; directories never leave the parser. */
+export declare function safeName(value: string): string;
+/** 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;
+/**
+ * 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): {
+    some: PsiLine;
+    full: PsiLine | null;
+} | null;

package/dist/counters.js

@@ -0,0 +1,141 @@
+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) {
+        return { state: "warming", reason: "initial sample or CPU topology changed" };
+    }
+    let total = 0;
+    let idle = 0;
+    for (let i = 0; i < current.length; i++) {
+        const before = previous[i];
+        const after = current[i];
+        if (!before || !after || before.model !== after.model)
+            return { state: "warming", reason: "CPU topology changed" };
+        for (const key of ["user", "nice", "sys", "idle", "irq"]) {
+            const delta = after.times[key] - before.times[key];
+            if (!Number.isFinite(delta) || before.times[key] < 0 || after.times[key] < 0 || delta < 0)
+                return { state: "warming", reason: "CPU counter reset or invalid" };
+            total += delta;
+            if (key === "idle")
+                idle += delta;
+        }
+    }
+    return total > 0
+        ? { state: "available", value: ((total - idle) / total) * 100 }
+        : { state: "warming", reason: "CPU counters have not advanced" };
+}
+/** CPU milliseconds divided by monotonic wall milliseconds, not a lifetime/decaying ps average. */
+export function processCpu(previous, current) {
+    if (!previous || previous.identity !== current.identity)
+        return { state: "warming", reason: "initial sample or PID reused" };
+    const elapsed = current.at - previous.at;
+    const cpu = current.cpuMs - previous.cpuMs;
+    if (!Number.isFinite(elapsed) ||
+        elapsed <= 0 ||
+        !Number.isFinite(cpu) ||
+        previous.cpuMs < 0 ||
+        current.cpuMs < 0 ||
+        cpu < 0) {
+        return { state: "warming", reason: "invalid interval or counter reset" };
+    }
+    return { state: "available", value: (cpu / elapsed) * 100 };
+}
+/** Bound display names by code point and replace terminal controls; directories never leave the parser. */
+export function safeName(value) {
+    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, 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(")");
+    if (start < 1 || end <= start || !Number.isFinite(hz) || hz <= 0)
+        return null;
+    const pid = Number(text.slice(0, start).trim());
+    const fields = text
+        .slice(end + 1)
+        .trim()
+        .split(/\s+/);
+    const parentPid = Number(fields[1]);
+    const user = Number(fields[11]);
+    const system = Number(fields[12]);
+    const identity = fields[19];
+    if (!identity ||
+        !/^\d+$/.test(identity) ||
+        ![pid, parentPid, user, system].every((n) => Number.isSafeInteger(n) && n >= 0) ||
+        pid === 0)
+        return null;
+    return {
+        pid,
+        parentPid,
+        name: "",
+        identity: `${pid}:${identity}`,
+        rssBytes: 0,
+        cpuMs: ((user + system) / hz) * 1000,
+        at,
+    };
+}
+/** RSS comes from status in KiB, avoiding an assumed host page size. */
+export function linuxRss(text) {
+    const match = /^VmRSS:\s+(\d+)\s+kB$/m.exec(text);
+    if (!match?.[1])
+        return null;
+    const bytes = Number(match[1]) * 1024;
+    return Number.isSafeInteger(bytes) ? bytes : null;
+}
+/**
+ * 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)
+        return null;
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const rssBytes = Number(match[5]) * 1024;
+    if (![pid, parentPid, rssBytes].every(Number.isSafeInteger))
+        return null;
+    return { pid, parentPid, rssBytes, identity: `${pid}:${match[3]}`, name: safeName(match[6]), cpuMs: 0, at };
+}
+/** Parse native PSI percentages and cumulative stall microseconds, rejecting malformed values. */
+export function psi(text) {
+    const rows = new Map();
+    for (const line of text.trim().split("\n")) {
+        const match = /^(some|full) avg10=(\d+(?:\.\d+)?) avg60=(\d+(?:\.\d+)?) avg300=(\d+(?:\.\d+)?) total=(\d+)$/.exec(line);
+        if (!match?.[1])
+            return null;
+        const [avg10, avg60, avg300, total] = match.slice(2).map(Number);
+        if (avg10 === undefined ||
+            avg60 === undefined ||
+            avg300 === undefined ||
+            total === undefined ||
+            ![avg10, avg60, avg300].every((n) => Number.isFinite(n) && n >= 0 && n <= 100) ||
+            !Number.isSafeInteger(total))
+            return null;
+        rows.set(match[1], { avg10, avg60, avg300, total });
+    }
+    const some = rows.get("some");
+    return some ? { some, full: rows.get("full") ?? null } : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { ResourceSampler, SamplerOptions } from "./types.js";
+export type { Metric, ProcessSample, PsiLine, ResourceSampler, ResourceSnapshot, SamplerOptions } from "./types.js";
+/** Create an isolated, passive sampler. No timers or child processes exist until sample(). */
+export declare function createResourceSampler(options?: SamplerOptions): ResourceSampler;

package/dist/index.js

@@ -0,0 +1,132 @@
+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 { cpuSnapshot, hostCpu, processCpu } from "./counters.js";
+/** Validate bounded integers before collecting any host information. */
+function bounded(value, fallback, min, max) {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < min || result > max)
+        throw new RangeError(`Sampler bound must be an integer from ${min} to ${max}`);
+    return result;
+}
+/** Create an isolated, passive sampler. No timers or child processes exist until sample(). */
+export function createResourceSampler(options = {}) {
+    const duration = bounded(options.maxDurationMs, 250, 10, 5000);
+    const maxPids = bounded(options.maxPids, 2048, 1, 16384);
+    const maxBytes = bounded(options.maxBytes, 2_097_152, 4096, 16_777_216);
+    const host = platform();
+    let previousCpus;
+    let previousTime;
+    let previousProcesses = new Map();
+    let hz;
+    let active;
+    let controller;
+    let disposed = false;
+    async function collect(signal) {
+        const start = performance.now();
+        const wallTimeMs = Date.now();
+        const budget = new Budget(start + duration, maxBytes, maxPids, signal);
+        signal.throwIfAborted();
+        const currentCpus = cpuSnapshot(cpus());
+        const cpu = previousTime !== undefined && start <= previousTime
+            ? { state: "warming", reason: "invalid monotonic interval" }
+            : hostCpu(previousCpus, currentCpus);
+        const nativePressure = await pressure(budget, host);
+        let counters = [];
+        try {
+            if (host === "linux") {
+                if (hz === undefined) {
+                    const result = await command("/usr/bin/getconf", ["CLK_TCK"], budget);
+                    const value = Number(result.text.trim());
+                    if (result.complete && Number.isSafeInteger(value) && value > 0)
+                        hz = value;
+                }
+                if (hz !== undefined && budget.ready())
+                    counters = await linuxProcesses(budget, hz);
+                else
+                    budget.reasons.add("clock-ticks-unavailable");
+            }
+            else if (host === "darwin")
+                counters = await darwinProcesses(budget);
+            else
+                budget.reasons.add("unsupported-platform");
+        }
+        catch {
+            signal.throwIfAborted();
+            budget.reasons.add("process-collection-unavailable");
+        }
+        signal.throwIfAborted();
+        const processes = counters.map((counter) => ({
+            pid: counter.pid,
+            parentPid: counter.parentPid,
+            name: counter.name,
+            identity: counter.identity,
+            rssBytes: counter.rssBytes,
+            cpu: host === "darwin"
+                ? {
+                    state: "unavailable",
+                    reason: "ps start identity precision is one second; PID reuse cannot be excluded",
+                }
+                : processCpu(previousProcesses.get(counter.pid), counter),
+        }));
+        // Only successfully completed scans advance baselines. Missing processes lose their baselines.
+        previousCpus = currentCpus;
+        previousTime = start;
+        previousProcesses = new Map(counters.map((counter) => [counter.pid, counter]));
+        if (performance.now() > budget.deadline)
+            budget.reasons.add("deadline");
+        return {
+            version: 1,
+            platform: host,
+            wallTimeMs,
+            monotonicTimeMs: start,
+            durationMs: performance.now() - start,
+            cpu,
+            logicalCpus: currentCpus.length,
+            loadAverage: host === "win32" ? [] : loadavg(),
+            memory: { totalBytes: totalmem(), freeBytes: freemem() },
+            processes,
+            coverage: {
+                complete: budget.reasons.size === 0,
+                enumerated: budget.enumerated,
+                sampled: processes.length,
+                skipped: budget.skipped,
+                bytesRead: budget.bytesRead,
+                reasons: [...budget.reasons],
+            },
+            pressure: nativePressure,
+        };
+    }
+    return {
+        sample(signal) {
+            if (disposed)
+                return Promise.reject(new Error("Resource sampler is disposed"));
+            if (active)
+                return Promise.reject(new Error("Resource sampler already has an active sample"));
+            controller = new AbortController();
+            const local = controller;
+            const abort = () => local.abort(signal?.reason);
+            if (signal?.aborted)
+                abort();
+            signal?.addEventListener("abort", abort, { once: true });
+            active = collect(local.signal).finally(() => {
+                signal?.removeEventListener("abort", abort);
+                active = undefined;
+                controller = undefined;
+            });
+            return active;
+        },
+        async dispose() {
+            disposed = true;
+            controller?.abort();
+            try {
+                await active;
+            }
+            catch {
+                /* The sample caller receives the cancellation. Disposal waits for cleanup. */
+            }
+            previousCpus = undefined;
+            previousProcesses.clear();
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/** An absent measurement is never encoded as a zero. */
+export type Metric<T> = {
+    state: "available";
+    value: T;
+} | {
+    state: "warming" | "unavailable";
+    reason: string;
+};
+/** One process observed without command arguments, environment or agent attribution. */
+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;
+    /** Interval utilization: 100 is one logical core, values may exceed 100. */
+    cpu: Metric<number>;
+}
+/** Linux pressure stall information, not memory utilization or a universal pressure score. */
+export interface PsiLine {
+    avg10: number;
+    avg60: number;
+    avg300: number;
+    /** Cumulative microseconds stalled. */
+    total: number;
+}
+/** Snapshot captured over a bounded, non-atomic scan. */
+export interface ResourceSnapshot {
+    version: 1;
+    platform: string;
+    wallTimeMs: number;
+    monotonicTimeMs: number;
+    durationMs: number;
+    /** Aggregate host interval utilization, 0..100. */
+    cpu: Metric<number>;
+    logicalCpus: number;
+    loadAverage: number[];
+    memory: {
+        totalBytes: number;
+        freeBytes: number;
+    };
+    processes: ProcessSample[];
+    coverage: {
+        complete: boolean;
+        /** Entries encountered, not a claimed host-wide process count when incomplete. */
+        enumerated: number;
+        sampled: number;
+        skipped: number;
+        bytesRead: number;
+        reasons: string[];
+    };
+    pressure: {
+        source: "linux-psi";
+        memory: Metric<{
+            some: PsiLine;
+            full: PsiLine | null;
+        }>;
+    } | {
+        source: "unsupported";
+        reason: string;
+    };
+}
+/** Bounds per sample; filesystem/kernel scheduling can delay completion past the deadline. */
+export interface SamplerOptions {
+    /** Default 250ms, range 10..5000. No new work after this monotonic deadline. */
+    maxDurationMs?: number;
+    /** Default 2048, range 1..16384. Sequential Linux reads (concurrency one). */
+    maxPids?: number;
+    /** Default 2MiB, range 4096..16MiB, includes helper stdout/stderr and proc contents. */
+    maxBytes?: number;
+}
+/** Caller owns cadence. No background polling, caching across instances or Pi dependency. */
+export interface ResourceSampler {
+    /** Rejects concurrent calls, disposal and caller cancellation. */
+    sample(signal?: AbortSignal): Promise<ResourceSnapshot>;
+    /** Aborts and awaits any collection and child reaping. Idempotent. */
+    dispose(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@nredd/pi-resource-sampler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Bounded, privacy-safe host resource interval sampling without Pi dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "author": "nredd",
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=22.14.0" },
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "LICENSE", "README.md"],
+  "repository": { "type": "git", "url": "git+https://github.com/nredd/pi-harness.git", "directory": "packages/resource-sampler" },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "biome check src test",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --maxWorkers=1",
+    "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" }
+}