@omercnet/paseo-top 0.0.1-alpha → 0.0.1-next.252.1

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. Top reads only that identifier from each process, never the rest of the environment. A process whose environment was cleared by a tool is charged to the nearest ancestor that has one. 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 processes of no agent and sessions beyond the first ten. Per-session load needs Linux and only sees processes owned by the daemon's user. 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

@@ -2,6 +2,10 @@
 
 A Paseo plugin that shows CPU, memory, disk and disk I/O of a host in the sidebar footer, and which agent sessions are responsible. See [OVERVIEW.md](OVERVIEW.md) for behavior.
 
+## Screenshots
+
+![Top screen with host resource gauges and per-session load](https://raw.githubusercontent.com/omercnet/paseo-plugins/pr-assets-top/top-screen.jpg)
+
 ## Develop
 
 ```sh
@@ -21,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/footer.tsx

@@ -2,19 +2,26 @@ import type { PluginSidebarItemProps } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
 import { SidebarRow } from "@getpaseo/plugin/client/ui";
 import { Text, View } from "react-native";
-import { formatPercent, formatRate, levelColor } from "./format";
+import { formatPercent, formatRate, type Level, levelColor, loadLevel } from "./format";
 import { SCREEN_ID, useUsage } from "./usage";
 
+const LEVEL_NAME: Record<Level, string> = { ok: "", warn: ", high", hot: ", critical" };
+
+/** What a screen reader says: the reading in words, with the level spelled out, not just coloured. */
+function metricLabel(name: string, text: string, level: Level): string {
+  return text === "--" ? `${name} unavailable` : `${name} ${text}${LEVEL_NAME[level]}`;
+}
+
 export function TopFooter({ theme, host, currentScreen, openScreen }: PluginSidebarItemProps) {
   const usage = useUsage(host.id);
   const heavy = usage.data?.sessions?.filter((session) => session.heavy).length ?? 0;
   const metrics =
     usage.data &&
     ([
-      ["Cpu", formatPercent(usage.data.cpu), usage.data.cpu],
-      ["MemoryStick", formatPercent(usage.data.memory), usage.data.memory],
-      ["HardDrive", formatPercent(usage.data.disk), usage.data.disk],
-      ["Gauge", formatRate(usage.data.io), null],
+      ["Cpu", "CPU", formatPercent(usage.data.cpu), usage.data.cpu],
+      ["MemoryStick", "Memory", formatPercent(usage.data.memory), usage.data.memory],
+      ["HardDrive", "Disk", formatPercent(usage.data.disk), usage.data.disk],
+      ["Gauge", "Disk I/O", formatRate(usage.data.io), null],
     ] as const);
 
   return (
@@ -29,15 +36,25 @@ export function TopFooter({ theme, host, currentScreen, openScreen }: PluginSide
             <Text style={{ color: theme.colors.statusDanger, fontSize: 11 }}>unavailable</Text>
           )}
           {heavy > 0 && (
-            <View style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
+            <View
+              accessible
+              accessibilityLabel={`${heavy} heavy ${heavy === 1 ? "session" : "sessions"}`}
+              style={{ flexDirection: "row", alignItems: "center", gap: 2 }}
+            >
               <Icon name="Flame" size={11} color={theme.colors.statusDanger} />
               <Text style={{ color: theme.colors.statusDanger, fontSize: 11 }}>{heavy}</Text>
             </View>
           )}
-          {metrics?.map(([icon, text, percent]) => {
+          {metrics?.map(([icon, name, text, percent]) => {
             const color = levelColor(theme, percent);
+            const level = loadLevel(percent);
             return (
-              <View key={icon} style={{ flexDirection: "row", alignItems: "center", gap: 2 }}>
+              <View
+                key={icon}
+                accessible
+                accessibilityLabel={metricLabel(name, text, level)}
+                style={{ flexDirection: "row", alignItems: "center", gap: 2 }}
+              >
                 <Icon name={icon} size={11} color={color} />
                 <Text
                   numberOfLines={1}

package/client/gauge.tsx

@@ -31,12 +31,14 @@ export function Dial({ theme, size, icon, label, value, text }: DialProps) {
   const needleLength = radius * 0.72;
   const degrees = useRef(new Animated.Value(needleDegrees(value))).current;
   useEffect(() => {
-    Animated.timing(degrees, {
+    const animation = Animated.timing(degrees, {
       toValue: needleDegrees(value),
       duration: 700,
       easing: Easing.out(Easing.cubic),
       useNativeDriver: false,
-    }).start();
+    });
+    animation.start();
+    return () => animation.stop();
   }, [degrees, value]);
   const rotate = degrees.interpolate({
     inputRange: [-SWEEP / 2, SWEEP / 2],

package/client/screen.tsx

@@ -68,6 +68,10 @@ export function TopScreen({ theme, layout, host, navigation }: PluginScreenProps
           {host.label}
         </Text>
         <View
+          accessible
+          accessibilityLabel={
+            usage.isError ? "Usage unavailable" : usage.data ? "Usage live" : "Usage loading"
+          }
           style={{
             width: 8,
             height: 8,

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/index.server.ts

@@ -11,5 +11,8 @@ export default function contribute(server: PluginServerContext) {
     if (!usage.sessions) return usage;
     return { ...usage, ...(await ownSessions(paseo, usage.sessions, usage.other)) };
   });
-  return sampler.stop;
+  return () => {
+    sampler.stop();
+    ownSessions.stop();
+  };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-top",
-  "version": "0.0.1-alpha",
+  "version": "0.0.1-next.252.1",
   "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/paseo-plugin.json

@@ -1,5 +1,8 @@
 {
   "id": "top",
   "description": "CPU, memory and disk usage of the selected host in the sidebar footer.",
+  "media": [
+    "https://raw.githubusercontent.com/omercnet/paseo-plugins/pr-assets-top/top-screen.jpg"
+  ],
   "requirements": { "paseo": "^0.11.0" }
 }

package/server/names.ts

@@ -7,6 +7,8 @@ const FULL_REFRESH_MS = 30_000;
 const EARLY_REFRESH_MS = 5000;
 /** Only the first ever fetch is waited for, and not forever. */
 const FIRST_FETCH_TIMEOUT_MS = 3000;
+/** A read that has not settled by now is abandoned and cancelled, so a hung daemon cannot block later reads. */
+const REFRESH_LIFETIME_MS = 20_000;
 const PAGE_SIZE = 200;
 export const MAX_PAGES = 25;
 export const MAX_SESSIONS = 10;
@@ -26,12 +28,23 @@ interface Page<T> {
   pageInfo: { hasMore: boolean; nextCursor: string | null };
 }
 
-/** The daemon pages its lists, and an agent left off the first page must still be recognised. */
-async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>) {
+/**
+ * The daemon pages its lists, and an agent left off the first page must still be recognised. Aborting
+ * ends the read even when the daemon never answers the page in flight, which is then ignored.
+ */
+async function collect<T>(
+  signal: AbortSignal,
+  fetchPage: (cursor: string | undefined) => Promise<Page<T>>,
+) {
+  const aborted = new Promise<never>((_, reject) => {
+    const cancel = () => reject(new Error("Daemon read cancelled"));
+    if (signal.aborted) cancel();
+    else signal.addEventListener("abort", cancel, { once: true });
+  });
   const entries: T[] = [];
   let cursor: string | undefined;
   for (let page = 0; page < MAX_PAGES; page++) {
-    const result = await fetchPage(cursor);
+    const result = await Promise.race([fetchPage(cursor), aborted]);
     entries.push(...result.entries);
     if (!result.pageInfo.hasMore || !result.pageInfo.nextCursor) break;
     cursor = result.pageInfo.nextCursor;
@@ -40,7 +53,7 @@ async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Pag
 }
 
 /**
- * The process scan sees every process the daemon's user owns, including agents that belong to other
+ * The process scan sees every readable process /proc lists, including agents that belong to other
  * daemons on the same machine. This keeps only the sessions of agents this daemon knows, names them
  * with the user's own agent and workspace names, and folds everything else into `other` so the
  * numbers still add up to the processes that were scanned.
@@ -48,34 +61,48 @@ async function collect<T>(fetchPage: (cursor: string | undefined) => Promise<Pag
  * The daemon's lists are read in the background and shared between callers, so a slow daemon never
  * holds up the readings. Only the very first read is waited for, for a few seconds at most. Until
  * then, and whenever the lists have never been available, no session can be shown as this host's and
- * all of its load is reported as other load. Once read, a failed refresh keeps the last lists.
+ * all of its load is reported as other load. Once read, a failed refresh keeps the last lists. A read
+ * that outlives `REFRESH_LIFETIME_MS` is cancelled and replaced by the next one, and whatever the
+ * abandoned read later returns is discarded. `stop` cancels the read in flight.
  */
 export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETCH_TIMEOUT_MS) {
   let known: Known | null = null;
   /** Agents confirmed absent from the latest read, so they do not trigger another one. */
   let foreign = new Set<string>();
   let fetchedAt = Number.NEGATIVE_INFINITY;
-  let inflight: Promise<void> | null = null;
+  let inflight: { done: Promise<void>; startedAt: number; abort: AbortController } | null = null;
 
   const refresh = (paseo: PaseoApi, candidates: string[]) => {
-    if (inflight) return inflight;
+    if (inflight && now() - inflight.startedAt >= REFRESH_LIFETIME_MS) {
+      inflight.abort.abort();
+      inflight = null;
+    }
+    if (inflight) return inflight.done;
     fetchedAt = now();
-    inflight = (async () => {
+    const abort = new AbortController();
+    const { signal } = abort;
+    const run = { done: Promise.resolve(), startedAt: fetchedAt, abort };
+    inflight = run;
+    run.done = (async () => {
       try {
         const [agents, workspaces] = await Promise.all([
-          collect((cursor) =>
+          collect(signal, (cursor) =>
             paseo.agents.list({
               filter: { includeArchived: true },
               // Oldest first: an agent's creation time never changes, so paging cannot skip one that
               // is busy and being updated while the pages are read.
               sort: [{ key: "created_at", direction: "asc" }],
               page: { limit: PAGE_SIZE, ...(cursor ? { cursor } : {}) },
+              signal,
             }),
           ),
-          collect((cursor) =>
+          // The SDK's workspace list takes no signal; the abort stops the paging between pages.
+          collect(signal, (cursor) =>
             paseo.workspaces.list({ page: { limit: PAGE_SIZE, ...(cursor ? { cursor } : {}) } }),
           ),
         ]);
+        // An abandoned read must not overwrite what a newer one stored.
+        if (inflight !== run) return;
         const next: Known = {
           agents: new Map(
             agents.map(({ agent }) => [
@@ -91,14 +118,14 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
         foreign = new Set(candidates.filter((id) => !next.agents.has(id)));
       } catch {
         // Keep the previous lists.
+      } finally {
+        if (inflight === run) inflight = null;
       }
-    })().finally(() => {
-      inflight = null;
-    });
-    return inflight;
+    })();
+    return run.done;
   };
 
-  return async (paseo: PaseoApi, sessions: Session[], other: Load) => {
+  const ownership = async (paseo: PaseoApi, sessions: Session[], other: Load) => {
     if (sessions.length === 0) return { sessions, other };
 
     const ids = sessions.map((session) => session.agentId);
@@ -107,7 +134,7 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
     const pending =
       age >= FULL_REFRESH_MS || (unseen && age >= EARLY_REFRESH_MS)
         ? refresh(paseo, ids)
-        : inflight;
+        : inflight?.done;
     if (known === null && pending) {
       await new Promise<void>((resolve) => {
         const timer = setTimeout(resolve, firstFetchTimeoutMs);
@@ -140,4 +167,11 @@ export function createOwnership(now = Date.now, firstFetchTimeoutMs = FIRST_FETC
     }
     return { sessions: own.slice(0, MAX_SESSIONS), other: rest };
   };
+
+  return Object.assign(ownership, {
+    stop: () => {
+      inflight?.abort.abort();
+      inflight = null;
+    },
+  });
 }

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

@@ -68,7 +68,7 @@ export function parseStat(text: string): Stat | null {
   return { comm: text.slice(open + 1, close), ...numbers, rss: Math.max(0, numbers.rss) };
 }
 
-/** Only the agent id is read out of the environment; the rest of it can hold secrets and is dropped. */
+/** The whole environment is read, but only the agent id is kept; the rest can hold secrets and is dropped. */
 export function parseAgentId(environ: string): string | null {
   for (const entry of environ.split("\0")) {
     if (entry.startsWith("PASEO_AGENT_ID=")) return entry.slice("PASEO_AGENT_ID=".length) || null;
@@ -77,34 +77,29 @@ export function parseAgentId(environ: string): string | null {
 }
 
 /**
- * Every process the daemon's user can see. A process's environment never changes after it starts, so
- * it is read once and remembered in `agentIds`; entries for processes that are gone are dropped.
+ * Every process listed under /proc, which includes other users' that are readable. The environment
+ * is read whole but only `PASEO_AGENT_ID` is kept, and it is read again on every scan, because a
+ * process can replace its environment when it execs without changing its pid or start time. A
+ * process whose environment cannot be read (another user's) has no agent.
  */
-export function readProcs(agentIds: Map<string, string | null>, root = "/proc"): ProcInfo[] {
+export function readProcs(root = "/proc"): ProcInfo[] {
   const procs: ProcInfo[] = [];
-  const seen = new Set<string>();
   for (const name of readdirSync(root)) {
     if (!/^\d+$/.test(name)) continue;
     try {
       const stat = parseStat(readFileSync(`${root}/${name}/stat`, "utf8"));
       if (!stat) continue;
-      const key = `${name}:${stat.start}`;
-      seen.add(key);
-      let agentId = agentIds.get(key);
-      if (agentId === undefined) {
-        try {
-          agentId = parseAgentId(readFileSync(`${root}/${name}/environ`, "utf8"));
-        } catch {
-          agentId = null; // another user's process
-        }
-        agentIds.set(key, agentId);
+      let agentId: string | null;
+      try {
+        agentId = parseAgentId(readFileSync(`${root}/${name}/environ`, "utf8"));
+      } catch {
+        agentId = null;
       }
-      procs.push({ key, pid: Number(name), agentId, ...stat });
+      procs.push({ key: `${name}:${stat.start}`, pid: Number(name), agentId, ...stat });
     } catch {
       // The process exited while it was being read.
     }
   }
-  for (const key of agentIds.keys()) if (!seen.has(key)) agentIds.delete(key);
   return procs;
 }
 
@@ -203,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;
@@ -18,10 +19,11 @@ export function readCpuTimes(cpus: ReadonlyArray<Pick<os.CpuInfo, "times">> = os
   return { idle, total };
 }
 
-/** Busy share between two readings, or null when no time elapsed or the counters went backwards. */
+/** Busy share between two readings, or null when no time elapsed, the counters went backwards or are not numbers. */
 export function cpuPercent(previous: CpuTimes, current: CpuTimes): number | null {
   const total = current.total - previous.total;
   const idle = current.idle - previous.idle;
+  if (!Number.isFinite(total) || !Number.isFinite(idle)) return null;
   if (total <= 0 || idle < 0 || idle > total) return null;
   return (1 - idle / total) * 100;
 }
@@ -35,13 +37,18 @@ export function diskPercent(
     const { blocks, bfree, bavail } = stat(path);
     const used = blocks - bfree;
     const usable = used + bavail;
-    return usable > 0 ? (used / usable) * 100 : null;
+    const percent = (used / usable) * 100;
+    return usable > 0 && Number.isFinite(percent) ? Math.min(100, Math.max(0, percent)) : null;
   } catch {
     return null;
   }
 }
 
-/** Whole-disk bytes read plus written since boot (Linux only); null where /proc is unavailable. */
+/**
+ * Whole-disk bytes read plus written since boot (Linux only). Null where /proc is unavailable, and
+ * when any whole disk has a malformed counter: a partial total would show up as a throughput spike
+ * once the counter reads again.
+ */
 export function readDiskBytes(
   sysBlock = "/sys/block",
   diskstats = "/proc/diskstats",
@@ -52,34 +59,56 @@ export function readDiskBytes(
       readdirSync(sysBlock).filter((name) => !/^(loop|ram|dm-|zram|md)/.test(name)),
     );
     let sectors = 0;
+    let matched = false;
     for (const line of readFileSync(diskstats, "utf8").split("\n")) {
       const fields = line.trim().split(/\s+/);
-      if (disks.has(fields[2] ?? "")) sectors += Number(fields[5]) + Number(fields[9]);
+      if (!disks.has(fields[2] ?? "")) continue;
+      const read = Number(fields[5]);
+      const written = Number(fields[9]);
+      if (!(Number.isFinite(read) && read >= 0 && Number.isFinite(written) && written >= 0)) {
+        return null;
+      }
+      sectors += read + written;
+      matched = true;
     }
-    return sectors * 512;
+    return matched && Number.isFinite(sectors) ? sectors * 512 : null;
   } catch {
     return null;
   }
 }
 
-/** Bytes per second between two readings, or null when the counter is missing or went backwards. */
+/** Bytes per second between two readings, or null when a counter is missing, not finite, or went backwards. */
 export function bytesPerSecond(
   previous: number | null,
   current: number | null,
   elapsedMs: number,
 ): number | null {
-  if (previous === null || current === null || current < previous || elapsedMs <= 0) return null;
-  return ((current - previous) * 1000) / elapsedMs;
+  if (previous === null || current === null) return null;
+  if (!(Number.isFinite(previous) && Number.isFinite(current) && Number.isFinite(elapsedMs))) {
+    return null;
+  }
+  if (current < previous || elapsedMs <= 0) return null;
+  const rate = ((current - previous) * 1000) / elapsedMs;
+  return Number.isFinite(rate) ? rate : null;
+}
+
+/**
+ * Used share of memory, clamped to 0-100; null when the host reports no usable total. Linux reports
+ * reclaimable cache as free, so this is memory programs cannot get back.
+ */
+export function memoryPercent(total = os.totalmem(), free = os.freemem()): number | null {
+  if (!Number.isFinite(total) || !Number.isFinite(free) || total <= 0) return null;
+  return Math.min(100, Math.max(0, (1 - free / total) * 100));
 }
 
 interface SamplerOptions {
   intervalMs?: number;
   readCpu?: () => CpuTimes;
   readIo?: () => number | null;
-  readMemory?: () => number;
+  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;
 }
@@ -92,8 +121,7 @@ export function startSampler({
   intervalMs = 2000,
   readCpu = readCpuTimes,
   readIo = readDiskBytes,
-  // Linux reports reclaimable cache as free, so this is memory programs cannot get back.
-  readMemory = () => (1 - os.freemem() / os.totalmem()) * 100,
+  readMemory = memoryPercent,
   readDisk = diskPercent,
   scan = defaultScan(),
   totalMemory = os.totalmem,
@@ -135,15 +163,3 @@ export function startSampler({
     stop: () => clearInterval(timer),
   };
 }
-
-/** Reads /proc; the environment cache lives as long as the sampler. */
-function defaultScan(): () => ProcInfo[] | null {
-  const agentIds = new Map<string, string | null>();
-  return () => {
-    try {
-      return readProcs(agentIds);
-    } catch {
-      return null;
-    }
-  };
-}

package/shared/usage.ts

@@ -10,7 +10,7 @@ const percent = z.number().min(0).max(100);
 /** Usage of the daemon host. Percentages are 0-100; `null` means the host cannot report it yet. */
 const sample = z.object({
   cpu: percent.nullable(),
-  memory: percent,
+  memory: percent.nullable(),
   disk: percent.nullable(),
   /** Disk read plus write throughput in bytes per second. */
   io: z.number().min(0).nullable(),
@@ -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'