@omercnet/paseo-top 0.0.1-next.250.1 → 0.1.0

package/OVERVIEW.md

@@ -4,12 +4,12 @@ Usage always describes one host. With several hosts connected, the footer follow
 
 **Load by session** adds up the CPU and memory of everything an agent started, not only the agent process. A build, test run or dev server launched by a tool counts toward the agent that launched it. Each row shows the agent and workspace names you gave them, the busiest command in its tree, cores and memory in use, and opens the agent when pressed. A session is flagged with a flame, and counted in the footer, when it holds one busy core for 30 seconds or a quarter of the host's memory. Everything not listed is shown on one "Everything else" line.
 
-How processes are matched to agents: Paseo gives every agent session an identifier in its environment, and everything the session starts inherits it. On every scan Top reads each process's environment into memory, keeps only that identifier and drops the rest at once; nothing else from it is stored, logged or sent anywhere. A process whose environment cannot be read, such as one owned by another user, cannot be tagged. A process with no identifier is charged to the nearest ancestor that has one, since tools often clear it. Only agents that belong to the host you are viewing are listed; processes of agents that belong to other daemons on the same machine are counted under "Everything else", together with untagged processes and sessions beyond the first ten. Per-session load needs Linux. The scan covers every process `/proc` lists, so other users' processes are counted too, under "Everything else". Containers run outside the agent's process tree and show as unattributed.
+How processes are matched to agents: Paseo gives every agent session an identifier in its environment, and everything the session starts inherits it. On every scan Top reads each process's environment into memory, keeps only that identifier and drops the rest at once; nothing else from it is stored, logged or sent anywhere. A process whose environment cannot be read, such as one owned by another user, cannot be tagged. A process with no identifier is charged to the nearest ancestor that has one, since tools often clear it. Only agents that belong to the host you are viewing are listed; processes of agents that belong to other daemons on the same machine are counted under "Everything else", together with untagged processes and sessions beyond the first ten. Per-session load works on Linux, macOS and Windows. The scan covers every process the host lists, so other users' processes are counted too, under "Everything else". Containers, virtual machines and WSL run outside the agent's process tree and show as unattributed. On macOS and Windows the environment of another user's processes cannot be read, so they are never matched to an agent. Memory is the resident size on macOS and the working set on Windows, which includes pages shared with other processes (every DLL counts in every process), so a Windows session with many processes reads higher than what it really uses. If the process list cannot be read, the list says it is not available instead of showing an empty one, and the scan is retried more and more slowly.
 
 What the numbers are and are not: load is sampled every ten seconds, so a process that starts and exits between two scans is never seen, and one that is still running is charged for the CPU it used since it started. A session is flagged only when it has held a full core across three scans in a row, so a single burst does not flag it. Memory is each process's resident memory added up, so memory shared between processes of one agent is counted more than once, and the quarter-of-memory rule compares against the machine's memory, not a container's limit. Sessions plus "Everything else" cover the processes that were scanned, not the whole host: kernel time, finished processes and the page cache are outside them.
 
 CPU is the share of non-idle time over the last couple of seconds. Memory excludes reclaimable cache on Linux. Disk is the filesystem that holds the daemon user's home directory. Disk I/O is bytes read plus written per second across the physical disks, on Linux. History is kept by the daemon in memory, so it survives a page refresh and is shared by every client, but starts over when the plugin or daemon restarts. A reading the host cannot give shows `--`; if the plugin cannot be reached, the footer says unavailable.
 
-The plugin only reads usage counters and process tables. It has no settings and runs no commands.
+The plugin only reads usage counters and process tables. It has no settings. On Linux it reads `/proc`. On macOS it runs `ps` twice every ten seconds, and on Windows it runs one PowerShell command, to list processes and read the Paseo identifier from each one's environment; it changes nothing and runs nothing else. On Windows that command declares native functions and reads other processes' memory, which endpoint-security tools on managed machines may flag. Set `PASEO_TOP_SESSIONS=off` in the daemon's environment to list no processes on any platform; the rest of Top is unaffected.
 
 Requires Paseo ^0.11.0.

package/README.md

@@ -25,8 +25,9 @@ Verify against an isolated daemon, never the default one:
 
 - `shared/usage.ts`: the `top.usage` RPC contract and history constants.
 - `server/usage.ts`: CPU, memory, disk and I/O readers, and the sampler with its history ring.
-- `server/processes.ts`: `/proc` scan and attribution of processes to agent sessions.
+- `server/processes.ts`: `/proc` scan, attribution of processes to agent sessions, and the session tracker.
+- `server/platform.ts`: the macOS (`ps`) and Windows (PowerShell, PEB environment read) process listers.
 - `server/names.ts`: joins agent and workspace names onto sessions.
 - `index.server.ts`: wires the sampler to the RPC.
 - `client/`, `index.client.tsx`: footer row, Top screen, dials and session list.
-- `tests/`: unit tests; process tests run against a fake `/proc` tree.
+- `tests/`: unit tests; Linux process tests run against a fake `/proc` tree. `npm run test:platform` also runs on macOS and Windows runners in CI, including a live process tree.

package/client/sessions.tsx

@@ -28,7 +28,7 @@ export function Sessions({ theme, sessions, other, onOpenAgent }: SessionsProps)
   if (sessions === null) {
     rows.push(
       <Text key="unsupported" style={muted}>
-        Per-session load needs a Linux host.
+        Per-session load is not available on this host.
       </Text>,
     );
   } else if (sessions.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-top",
-  "version": "0.0.1-next.250.1",
+  "version": "0.1.0",
   "type": "module",
   "description": "A Paseo plugin that shows host CPU, memory and disk usage in the sidebar footer.",
   "license": "MIT",
@@ -42,6 +42,7 @@
     "check": "biome check .",
     "check:write": "biome check --write .",
     "test": "vitest run",
+    "test:platform": "vitest run",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

package/server/platform.ts

@@ -0,0 +1,249 @@
+import { execFile } from "node:child_process";
+import { type Listing, type ProcInfo, readProcs, type Scan } from "./processes";
+
+const TIMEOUT_MS = 15_000;
+const MAX_OUTPUT_BYTES = 64 * 1024 ** 2;
+const CLOCK_TICKS = 100;
+/** Windows counts CPU time in 100 ns units. */
+const FILETIME_PER_TICK = 100_000;
+const AGENT_ID_VARIABLE = "PASEO_AGENT_ID=";
+/** First line of the Windows output: when the process table was read, in ms after the script started. */
+const SNAPSHOT_MARK = "snapshot";
+
+type Run = (file: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<string>;
+
+const run: Run = (file, args, env) => {
+  const { promise, resolve, reject } = Promise.withResolvers<string>();
+  execFile(
+    file,
+    args,
+    {
+      timeout: TIMEOUT_MS,
+      maxBuffer: MAX_OUTPUT_BYTES,
+      windowsHide: true,
+      encoding: "utf8",
+      env: { ...process.env, ...env },
+    },
+    (error, stdout) => (error ? reject(error) : resolve(stdout)),
+  );
+  return promise;
+};
+
+/** `m:ss.cc` as `ps` prints CPU time (minutes are not capped at 59), in clock ticks. */
+export function parseCpuTime(text: string): number | null {
+  const match = /^(\d+):(\d+(?:\.\d+)?)$/.exec(text);
+  return match ? Math.round((Number(match[1]) * 60 + Number(match[2])) * CLOCK_TICKS) : null;
+}
+
+// "Tue Oct 13 06:01:17 2026": `lstart`, whose day is space padded. Pinned to the C locale by the caller.
+const LSTART = String.raw`(\S+\s+\S+\s+\d+\s+[\d:]+\s+\d+)`;
+// pid ppid lstart cputime rss comm
+const PS_ROW = new RegExp(String.raw`^\s*(\d+)\s+(\d+)\s+${LSTART}\s+(\S+)\s+(\d+)\s+(.+?)\s*$`);
+// pid lstart command-and-environment
+const PS_ENV_ROW = new RegExp(String.raw`^\s*(\d+)\s+${LSTART}\s(.*)$`);
+
+/**
+ * The agent id in one `ps -E` line. The environment follows the arguments, so the last occurrence
+ * is the environment's, and arguments that only mention the variable do not count. The whole line
+ * is read but only the id is kept; the rest can hold secrets.
+ */
+export function parsePsAgentId(line: string): string | null {
+  let id: string | null = null;
+  for (const match of line.matchAll(/(?:^|\s)PASEO_AGENT_ID=(\S+)/g)) id = match[1] ?? null;
+  return id;
+}
+
+const psKey = (pid: string, started: string) => `${pid}:${started.replace(/\s+/g, " ")}`;
+
+/**
+ * macOS: `stats` is `ps -axww -o pid=,ppid=,lstart=,cputime=,rss=,comm=`, `environment` is
+ * `ps -axww -E -o pid=,lstart=,command=`. They are separate listings because `-E` appends the
+ * environment to the command column only, and a command may hold spaces. Rows are joined on pid
+ * and start time, so a pid reused between the two listings is not given the old process's agent.
+ */
+export function parsePs(stats: string, environment: string): ProcInfo[] {
+  const agents = new Map<string, string>();
+  for (const line of environment.split("\n")) {
+    const match = PS_ENV_ROW.exec(line);
+    const id = match && parsePsAgentId(match[3] ?? "");
+    if (match && id) agents.set(psKey(match[1] ?? "", match[2] ?? ""), id);
+  }
+  const procs: ProcInfo[] = [];
+  for (const line of stats.split("\n")) {
+    const match = PS_ROW.exec(line);
+    if (!match) continue;
+    const [, pid = "", ppid = "", started = "", cpu = "", rssKib = "", path = ""] = match;
+    const ticks = parseCpuTime(cpu);
+    if (ticks === null) continue;
+    const key = psKey(pid, started);
+    procs.push({
+      key,
+      pid: Number(pid),
+      ppid: Number(ppid),
+      ticks,
+      rss: Number(rssKib) * 1024,
+      comm: path.slice(path.lastIndexOf("/") + 1),
+      agentId: agents.get(key) ?? null,
+    });
+  }
+  return procs;
+}
+
+/**
+ * The daemon is always in its own host's process list, so a listing without it is not one: empty
+ * or garbled output must fail the scan, not read as a host where nothing is running.
+ */
+function ownListing<T extends { pid: number }>(procs: T[], self: number): T[] {
+  if (!procs.some((proc) => proc.pid === self))
+    throw new Error("process list does not include this process");
+  return procs;
+}
+
+export async function readPsProcs(exec: Run = run, self = process.pid): Promise<ProcInfo[]> {
+  // `lstart` follows the locale; the parser reads the C one.
+  const env = { LC_ALL: "C" };
+  const [stats, environment] = await Promise.all([
+    exec("/bin/ps", ["-axww", "-o", "pid=,ppid=,lstart=,cputime=,rss=,comm="], env),
+    exec("/bin/ps", ["-axww", "-E", "-o", "pid=,lstart=,command="], env),
+  ]);
+  return ownListing(parsePs(stats, environment), self);
+}
+
+/**
+ * Windows has no listing that includes another process's environment, so the script reads it from
+ * the process's memory: PEB -> RTL_USER_PROCESS_PARAMETERS -> Environment (64-bit layout; checked
+ * on x64 and ARM64). The native calls are declared with Reflection.Emit because compiling C#
+ * with Add-Type costs seconds on every start. Only the agent id leaves the script. A process that
+ * cannot be opened (another user's, protected) simply has none. Anything that stops the script
+ * from working at all, such as a locked-down language mode, exits non-zero.
+ */
+export const WINDOWS_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$clock = [Diagnostics.Stopwatch]::StartNew()
+if (-not [Environment]::Is64BitProcess) { exit 3 }
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false
+$type = [AppDomain]::CurrentDomain.DefineDynamicAssembly((New-Object System.Reflection.AssemblyName 'TopNative'), 'Run').DefineDynamicModule('m').DefineType('N', 'Public,Class')
+function Import($name, $dll, $return, $params) {
+  $method = $type.DefinePInvokeMethod($name, $dll, 'Public,Static,PinvokeImpl', 'Standard', $return, $params, 'Winapi', 'Auto')
+  $method.SetImplementationFlags('PreserveSig')
+}
+Import 'OpenProcess' 'kernel32.dll' ([IntPtr]) @([uint32], [bool], [int])
+Import 'CloseHandle' 'kernel32.dll' ([bool]) @([IntPtr])
+Import 'ReadProcessMemory' 'kernel32.dll' ([bool]) @([IntPtr], [IntPtr], [byte[]], [IntPtr], [IntPtr])
+Import 'NtQueryInformationProcess' 'ntdll.dll' ([int]) @([IntPtr], [int], [byte[]], [int], [IntPtr])
+$native = $type.CreateType()
+function ReadMemory($handle, [long]$address, [int]$size) {
+  $buffer = New-Object byte[] $size
+  if ($native::ReadProcessMemory($handle, [IntPtr]$address, $buffer, [IntPtr]$size, [IntPtr]::Zero)) { , $buffer }
+}
+function AgentId([int]$id) {
+  $handle = $native::OpenProcess(0x1010, $false, $id)
+  if ($handle -eq [IntPtr]::Zero) { return }
+  try {
+    $info = New-Object byte[] 48
+    if ($native::NtQueryInformationProcess($handle, 0, $info, 48, [IntPtr]::Zero) -ne 0) { return }
+    $peb = ReadMemory $handle ([BitConverter]::ToInt64($info, 8) + 0x20) 8
+    if (-not $peb) { return }
+    $parameters = [BitConverter]::ToInt64($peb, 0)
+    $start = ReadMemory $handle ($parameters + 0x80) 8
+    $length = ReadMemory $handle ($parameters + 0x3F0) 8
+    if (-not $start -or -not $length) { return }
+    $size = [int][Math]::Min([BitConverter]::ToInt64($length, 0), 1MB)
+    if ($size -le 0) { return }
+    $block = ReadMemory $handle ([BitConverter]::ToInt64($start, 0)) $size
+    if (-not $block) { return }
+    $found = [regex]::Match([Text.Encoding]::Unicode.GetString($block), '(?:^|\\0)${AGENT_ID_VARIABLE}([^\\0\\t\\r\\n]+)')
+    if ($found.Success) { $found.Groups[1].Value }
+  } catch { return } finally { [void]$native::CloseHandle($handle) }
+}
+$all = Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate,KernelModeTime,UserModeTime,WorkingSetSize,Name
+$snapshotMs = $clock.ElapsedMilliseconds
+$lines = foreach ($p in $all) {
+  if ($p.ProcessId -eq 0) { continue }
+  try {
+    @($p.ProcessId, $p.ParentProcessId, ([DateTimeOffset]$p.CreationDate).ToUnixTimeMilliseconds(), ([uint64]$p.KernelModeTime + [uint64]$p.UserModeTime), $p.WorkingSetSize, [string](AgentId $p.ProcessId), $p.Name) -join [char]9
+  } catch { continue }
+}
+[Console]::Out.Write((@('${SNAPSHOT_MARK}' + [char]9 + $snapshotMs) + $lines) -join [char]10)
+`;
+
+/**
+ * The listing also says how long after the script started the table was read, so a slower start
+ * of PowerShell on one scan than on the last does not skew the CPU rates. Windows keeps a dead parent's pid on its children, and the number may since belong to an
+ * unrelated process. A parent that started after its child cannot be its parent.
+ */
+export function parseWindows(text: string): Listing {
+  const rows: Array<ProcInfo & { started: number }> = [];
+  let delayMs = 0;
+  for (const line of text.split("\n")) {
+    const [pid, ppid, started, cpu, workingSet, agentId, name] = line.trimEnd().split("\t");
+    if (pid === SNAPSHOT_MARK) {
+      delayMs = Number(ppid) || 0;
+      continue;
+    }
+    const numbers = [pid, ppid, started, cpu, workingSet].map(Number);
+    if (name === undefined || !numbers.every(Number.isFinite) || Number(pid) === 0) continue;
+    rows.push({
+      key: `${pid}:${started}`,
+      pid: numbers[0] as number,
+      ppid: numbers[1] as number,
+      started: numbers[2] as number,
+      ticks: Math.floor((numbers[3] as number) / FILETIME_PER_TICK),
+      rss: numbers[4] as number,
+      comm: name.replace(/\.exe$/i, ""),
+      agentId: agentId || null,
+    });
+  }
+  const started = new Map(rows.map((row) => [row.pid, row.started]));
+  const procs = rows.map(({ started: at, ...proc }) => {
+    const parent = started.get(proc.ppid);
+    return parent !== undefined && parent > at ? { ...proc, ppid: 0 } : proc;
+  });
+  return { procs, delayMs };
+}
+
+/**
+ * Windows PowerShell 5.1, which every Windows has. A 32-bit Node on a 64-bit Windows would get the
+ * 32-bit one from System32, which cannot read 64-bit processes; Sysnative reaches the real one.
+ */
+export function powershellPath(env: NodeJS.ProcessEnv = process.env, arch = process.arch): string {
+  const root = env.SystemRoot ?? "C:\\Windows";
+  const folder = arch === "ia32" && env.PROCESSOR_ARCHITEW6432 ? "Sysnative" : "System32";
+  return `${root}\\${folder}\\WindowsPowerShell\\v1.0\\powershell.exe`;
+}
+
+export async function readWindowsProcs(
+  exec: Run = run,
+  self = process.pid,
+  powershell = powershellPath(),
+): Promise<Listing> {
+  const output = await exec(powershell, [
+    "-NoProfile",
+    "-NonInteractive",
+    "-EncodedCommand",
+    Buffer.from(WINDOWS_SCRIPT, "utf16le").toString("base64"),
+  ]);
+  const listing = parseWindows(output);
+  ownListing(listing.procs, self);
+  return listing;
+}
+
+/**
+ * The process lister for this platform. A scan that fails rejects, or returns null. Set
+ * `PASEO_TOP_SESSIONS=off` to not list processes at all, which turns per-session load off.
+ */
+export function defaultScan(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): Scan {
+  if (env.PASEO_TOP_SESSIONS === "off") return () => null;
+  if (platform === "darwin") return () => readPsProcs();
+  if (platform === "win32") return () => readWindowsProcs();
+  return () => {
+    try {
+      return readProcs();
+    } catch {
+      return null;
+    }
+  };
+}

package/server/processes.ts

@@ -198,53 +198,106 @@ export const HEAVY_CORES = 1;
 export const HEAVY_SCANS = 3;
 export const HEAVY_MEMORY_SHARE = 0.25;
 
+/** A process list read some time after the scan started, which a lister that knows says. */
+export interface Listing {
+  procs: ProcInfo[];
+  delayMs: number;
+}
+
+/**
+ * Lists processes; null for a scan that failed, and a throw or rejection counts as one. macOS and
+ * Windows listers run a command, so they are async.
+ */
+export type Scan = () => ProcInfo[] | Listing | null | Promise<ProcInfo[] | Listing | null>;
+
+const NO_LOAD = { cores: 0, rss: 0 };
+/** After this many failures in a row the retries slow down, doubling up to the cap. */
+const MAX_RETRY_MS = 5 * 60_000;
+
 /**
  * Rescans every `SCAN_EVERY_MS` and remembers a short window of each session's CPU, so a one-scan
- * spike does not flag it. `scan` returns null where processes cannot be listed: for good on a host
- * that cannot do it at all (not Linux), and for one scan on a host that failed once.
+ * spike does not flag it. Until a scan has worked there is nothing to diff against, so sessions are
+ * unavailable (null) once a scan has failed; they are also unavailable after a lasting failure,
+ * never an empty list, which would claim that nothing is running. A failed scan after a good one
+ * keeps the last readings for a while. Failures are retried ever more slowly, since a lister that
+ * fails three times in a row is usually blocked, not unlucky. One scan runs at a time, timed from
+ * when it started plus the delay its lister reports.
  */
-export function trackSessions(scan: () => ProcInfo[] | null, startedAt: number) {
-  const first = scan();
-  const supported = first !== null;
-  let previous = first ? attribute(first, null, 0).ticks : new Map<string, number>();
-  let latest: Pick<Attribution, "sessions" | "other"> = {
-    sessions: [],
-    other: { cores: 0, rss: 0 },
-  };
+export function trackSessions(scan: Scan, startedAt: number) {
+  let previous: Map<string, number> | null = null;
+  let latest: Pick<Attribution, "sessions" | "other"> = { sessions: [], other: NO_LOAD };
   let scannedAt = startedAt;
+  let triedAt = startedAt;
   let failures = 0;
+  let pending = false;
+  let unavailable = false;
   let recent = new Map<string, number[]>();
 
+  const settle = (result: ProcInfo[] | Listing | null, at: number) => {
+    if (!result) {
+      // Keep the last readings through a hiccup, but not through a lasting failure. The next
+      // good scan diffs against the last good one, over the longer interval.
+      if (++failures >= HEAVY_SCANS) {
+        unavailable = true;
+        latest = { sessions: [], other: NO_LOAD };
+        recent = new Map();
+      } else if (!previous) unavailable = true;
+      return;
+    }
+    failures = 0;
+    unavailable = false;
+    const { procs, delayMs } = Array.isArray(result) ? { procs: result, delayMs: 0 } : result;
+    const readAt = at + delayMs;
+    const next = attribute(procs, previous, (readAt - scannedAt) / 1000);
+    scannedAt = readAt;
+    // The first good scan is only a baseline: it has no earlier counters to diff.
+    if (!previous) {
+      previous = next.ticks;
+      return;
+    }
+    previous = next.ticks;
+    latest = { sessions: next.sessions, other: next.other };
+    recent = new Map(
+      next.sessions.map(({ agentId, cores }) => [
+        agentId,
+        [...(recent.get(agentId) ?? []), cores].slice(-HEAVY_SCANS),
+      ]),
+    );
+  };
+
+  const start = (at: number) => {
+    triedAt = at;
+    let result: ReturnType<Scan>;
+    try {
+      result = scan();
+      if (!(result instanceof Promise)) return settle(result, at);
+    } catch {
+      return settle(null, at);
+    }
+    pending = true;
+    result
+      .catch(() => null)
+      .then((procs) => settle(procs, at))
+      .catch(() => {})
+      .finally(() => {
+        pending = false;
+      });
+  };
+  start(startedAt);
+
   return {
     update(at: number) {
-      if (!supported || at - scannedAt < SCAN_EVERY_MS) return;
-      const procs = scan();
-      if (!procs) {
-        // Keep the last readings through a hiccup, but not through a lasting failure. The next
-        // good scan diffs against the last good one, over the longer interval.
-        if (++failures >= HEAVY_SCANS) {
-          latest = { sessions: [], other: { cores: 0, rss: 0 } };
-          recent = new Map();
-        }
-        return;
-      }
-      failures = 0;
-      const next = attribute(procs, previous, (at - scannedAt) / 1000);
-      previous = next.ticks;
-      scannedAt = at;
-      latest = { sessions: next.sessions, other: next.other };
-      recent = new Map(
-        next.sessions.map(({ agentId, cores }) => [
-          agentId,
-          [...(recent.get(agentId) ?? []), cores].slice(-HEAVY_SCANS),
-        ]),
-      );
+      const wait =
+        failures < HEAVY_SCANS
+          ? SCAN_EVERY_MS
+          : Math.min(SCAN_EVERY_MS * 2 ** (failures - HEAVY_SCANS + 1), MAX_RETRY_MS);
+      if (!pending && at - triedAt >= wait) start(at);
     },
     read(totalMemory: number): {
       sessions: Session[] | null;
       other: { cores: number; rss: number };
     } {
-      if (!supported) return { sessions: null, other: { cores: 0, rss: 0 } };
+      if (unavailable) return { sessions: null, other: NO_LOAD };
       const sessions = latest.sessions
         .map((session): Session => {
           const window = recent.get(session.agentId) ?? [];

package/server/usage.ts

@@ -1,7 +1,8 @@
 import { readdirSync, readFileSync, statfsSync } from "node:fs";
 import os from "node:os";
 import { HISTORY_EVERY_MS, HISTORY_LENGTH, type Sample } from "../shared/usage";
-import { type ProcInfo, readProcs, trackSessions } from "./processes";
+import { defaultScan } from "./platform";
+import { type Scan, trackSessions } from "./processes";
 
 export interface CpuTimes {
   idle: number;
@@ -107,7 +108,7 @@ interface SamplerOptions {
   readMemory?: () => number | null;
   readDisk?: () => number | null;
   /** Lists processes, or returns null where that is not possible. */
-  scan?: () => ProcInfo[] | null;
+  scan?: Scan;
   totalMemory?: () => number;
   now?: () => number;
 }
@@ -162,14 +163,3 @@ export function startSampler({
     stop: () => clearInterval(timer),
   };
 }
-
-/** Reads /proc; returns null for a scan where it cannot be listed. */
-function defaultScan(): () => ProcInfo[] | null {
-  return () => {
-    try {
-      return readProcs();
-    } catch {
-      return null;
-    }
-  };
-}

package/shared/usage.ts

@@ -44,7 +44,7 @@ export const getUsage = defineRpc({
     /** Earlier samples, oldest first, `HISTORY_EVERY_MS` apart, so a fresh client has a timeline. */
     history: z.array(sample).max(HISTORY_LENGTH),
     totalMemory: z.number().positive(),
-    /** Busiest first. `null` where the host cannot attribute processes (anything but Linux). */
+    /** Busiest first. `null` where the host cannot attribute processes (where the process list cannot be read). */
     sessions: z.array(session).nullable(),
     /**
      * Everything scanned that is not listed in `sessions`: processes of no agent, of other daemons'