@volter/supercode-health 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @volter/supercode-health
 
-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.
+The machine-health pack is an optional supercode machine pack. It runs a cheap,
+deterministic probe of a machine's vitals and mails the machine's maintainer when a
+threshold is crossed. It decides nothing and changes nothing on the machine. The
+[ADR](../../docs/adr/0006-machine-health-pack.md) covers what it measures and why:
+prior art, instruments and their cost, each alert window and its basis, and each
+feature's permission barrier.
+
+## Running
+
+An enrolled machine's connector (`supercode teams connect`) starts the probe as a child
+when the pack is installed. `SUPERCODE_HEALTH=0` turns it off. The pack runs one probe
+per OS user and holds a pidfile so it stays one. Run it by hand with `supercode health
+run`, or `supercode-health run`.
+
+## Reading
+
+```
+supercode health status [--all] [--json]        this machine
+supercode health status --machine NAME          an enrolled machine, through its doors
+supercode health features                       every feature: on/off, barrier, why
+supercode health alarms
+supercode health once                           two samples 5 s apart, without the loop
+```
+
+The machine daemon's node doors are `health.read` and `health.subscribe` /
+`health.unsubscribe`. A read needs an operator or `view *`; a subscription needs an
+operator. The probe writes `latest.json` (each reading), `history.jsonl` (one summary
+a minute, 24 h) and `probe.log` to `$SUPERCODE_HOME/health`, which defaults to
+`~/.config/supercode/health`. `SUPERCODE_HEALTH_DIR` overrides that directory.
+
+## Alarms
+
+`supercode health subscribe sc:<machine>:<harness>:<id>` subscribes a session or board.
+Each raise, escalation and clear mails the subscribers. A still-raised alarm mails again
+every `repeatMin` (60). Mail comes from `sc:<machine>:operator:machine-health` through
+`supercode message remote-deliver`. Undelivered mail is kept and retried for a day.
+
+## Config
+
+The config is `config.json` in the health directory. The machine's maintainer owns it
+(RFC 0022: the values are the org's, not the pack's). Any default in
+[`lib/thresholds.mjs`](lib/thresholds.mjs) can be overridden:
+
+```json
+{
+  "maintainers": ["sc:my-mac:claude-code:<session-id>"],
+  "alarms": { "memory.free": { "warn": 20, "crit": 10 }, "tcp.timeWaitTarget": { "warn": 25 } },
+  "volumes": { "/System/Volumes/Data": { "warnGB": 50, "critGB": 20, "clearGB": 100 } },
+  "services": [{ "label": "ai.example.worker", "name": "worker", "log": "/path/to/worker.log", "maxSilentMin": 30 }],
+  "integrations": { "browserController": { "portFile": "/tmp/controller-port.txt" } },
+  "features": { "disk-io": false }
+}
+```
+
+## Permission barriers
+
+| Barrier | Features |
+|---|---|
+| none | load, memory, processes, process-footprint (this user's processes; python3 on macOS), renderers, daemons, disk, disk-io, tcp, files, services |
+| root | all-users-footprint, power |
+| integration | supercode (the machine daemon), browser-tabs (a browser controller's `/tabs`) |
+
+With no extra permission, every `none` feature runs. `features` lists every other
+feature as off and names what it needs. The pack never asks for a permission or
+escalates. A root feature turns on only when the probe already runs as root.

package/bin/health.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// supercode-health: the machine-health pack's own CLI. On a connected machine the connector runs `run`;
+// people and maintainers read it through `supercode health …`, which also reaches other machines.
+//
+//   run [--machine NAME]        the probe loop (one per OS user; exits 3 when one already runs)
+//   once [--json]               two samples 5 s apart, judged and printed, without the loop or mail
+//   status [--json] [--all]     this machine's latest reading (latest.json)
+//   features [--json]           every feature, on or off, its permission barrier and why
+//   alarms [--json]             the alarms raised now
+//   subscribe <address> | unsubscribe <address>   alarm mail for a session or board address
+//   config                      where the config lives and what it currently resolves to
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { Probe, subscribe, loadConfig } from '../lib/probe.mjs';
+import { healthDir, files } from '../lib/paths.mjs';
+import { formatStatus, formatFeatures } from '../lib/format.mjs';
+
+const { values, positionals } = parseArgs({ allowPositionals: true, options: { json: { type: 'boolean' }, all: { type: 'boolean' }, machine: { type: 'string' }, help: { type: 'boolean' } } });
+const verb = positionals[0] ?? 'status';
+const dir = healthDir();
+const f = files(dir);
+const print = (value, text) => process.stdout.write((values.json ? JSON.stringify(value, null, 2) : text) + '\n');
+const latest = () => { try { return JSON.parse(readFileSync(f.latest, 'utf8')); } catch { return null; } };
+
+if (values.help || verb === 'help') {
+  process.stdout.write(readFileSync(new URL(import.meta.url), 'utf8').split('\n').filter((l) => l.startsWith('//')).map((l) => l.slice(3)).join('\n') + '\n');
+} else if (verb === 'run') {
+  const probe = new Probe({ machine: values.machine });
+  if (!probe.lock()) { process.stderr.write(`supercode-health: a probe already runs here (pid ${probe.holder})\n`); process.exit(3); }
+  const abort = new AbortController();
+  const stop = () => abort.abort();
+  process.on('SIGTERM', stop); process.on('SIGINT', stop);
+  process.on('exit', () => probe.unlock());
+  await probe.run({ signal: abort.signal });
+  probe.unlock();
+} else if (verb === 'once') {
+  const probe = new Probe({ machine: values.machine, dir: `${dir}/once-${process.pid}` });
+  await probe.init();
+  await probe.sampler.sample(probe.features(), Date.now(), { wait: true });
+  await new Promise((r) => setTimeout(r, 5_000));
+  const now = Date.now();
+  const { readings, observations, families, errors } = await probe.sampler.sample(probe.features(), now, { wait: true });
+  const { judge, raised } = await import('../lib/thresholds.mjs');
+  // A single look has no windows behind it: report what each threshold meets right now.
+  for (const o of observations) o.def = { ...o.def, forSec: 0, critForSec: 0 };
+  judge(probe.state, observations, families, now);
+  const snapshot = { version: 1, machine: probe.machine, platform: probe.platform, at: new Date(now).toISOString(), probe: { pid: process.pid, intervalSec: 15, once: true }, features: probe.features().map((x) => ({ ...x, ...(errors[x.id] ? { error: errors[x.id] } : {}) })), alarms: raised(probe.state), readings };
+  (await import('node:fs')).rmSync(probe.dir, { recursive: true, force: true });
+  print(snapshot, formatStatus(snapshot, { all: values.all }));
+} else if (verb === 'status') {
+  const s = latest();
+  print(s, formatStatus(s, { all: values.all }));
+  if (!s) process.exitCode = 4;
+} else if (verb === 'features') {
+  const s = latest();
+  let features = s?.features;
+  if (!features) { const probe = new Probe({ dir: `${dir}/features-${process.pid}` }); await probe.init(); features = probe.features(); (await import('node:fs')).rmSync(probe.dir, { recursive: true, force: true }); }
+  print(features, formatFeatures(features));
+} else if (verb === 'alarms') {
+  const s = latest();
+  print(s?.alarms ?? [], s?.alarms?.length ? s.alarms.map((a) => `${a.level.toUpperCase()} ${a.key}: ${a.summary} (since ${a.since})`).join('\n') : 'no alarms raised');
+} else if (verb === 'subscribe' || verb === 'unsubscribe') {
+  print(subscribe(dir, positionals[1], verb === 'unsubscribe'), `${verb}d ${positionals[1]}`);
+} else if (verb === 'config') {
+  const config = loadConfig(f.config);
+  print({ file: f.config, config }, `config file: ${f.config}${config.source ? '' : ' (absent: defaults)'}\n${JSON.stringify(config, null, 2)}`);
+} else {
+  process.stderr.write(`supercode-health: unknown verb ${verb} (run, once, status, features, alarms, subscribe, unsubscribe, config)\n`);
+  process.exit(2);
+}

package/index.mjs

@@ -0,0 +1,6 @@
+export { Probe, loadConfig, subscribe, subscribers, platformReader } from './lib/probe.mjs';
+export { Sampler } from './lib/sample.mjs';
+export { FEATURES, resolveFeatures } from './lib/features.mjs';
+export { DEFAULTS, judge, meets, raised } from './lib/thresholds.mjs';
+export { healthDir, machineName } from './lib/paths.mjs';
+export { formatStatus, formatFeatures } from './lib/format.mjs';

package/lib/chrome.mjs

@@ -0,0 +1,68 @@
+// Which tab a Chrome renderer serves, and who owns each tab. A renderer serving an origin that uses the
+// origin-private file system holds that origin's bucket open (`<profile>/File System/<nnn>/`), and each profile's
+// `File System/Origins` index names the origin of every bucket. A tab on a local port is owned by whatever
+// process serves that port (an editor, a dev server), and so by that process's session.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run } from './run.mjs';
+
+const ROOTS = { darwin: join(homedir(), 'Library/Application Support/Google/Chrome'), linux: join(homedir(), '.config/google-chrome') };
+let cache = { key: '', map: new Map() };
+
+/** `<profile>/File System/<nnn>` → origin, from every profile's Origins index (re-read when an index changes). */
+export function bucketOrigins(platform = process.platform) {
+  const root = ROOTS[platform];
+  if (!root) return new Map();
+  const files = [];
+  let profiles = [];
+  try { profiles = readdirSync(root).filter((name) => name === 'Default' || name.startsWith('Profile ')); } catch { return new Map(); }
+  for (const profile of profiles) {
+    const dir = join(root, profile, 'File System', 'Origins');
+    let names = [];
+    try { names = readdirSync(dir).filter((name) => /\.(log|ldb)$/.test(name)); } catch { continue; }
+    for (const name of names) { try { files.push([profile, join(dir, name), statSync(join(dir, name)).mtimeMs]); } catch { /* rotated */ } }
+  }
+  const key = files.map(([, file, mtime]) => `${file}:${mtime}`).join('|');
+  if (key === cache.key) return cache.map;
+  const map = new Map();
+  for (const [profile, file] of files) {
+    const text = readFileSync(file).toString('latin1');
+    for (const m of text.matchAll(/ORIGIN:(https?)_([a-z0-9.\-[\]:]+?)_(\d+)[\x00-\x1f]{1,3}(\d{3})/g)) {
+      const port = m[3] === '0' ? '' : `:${m[3]}`;
+      map.set(`${profile}/File System/${m[4]}`, `${m[1]}://${m[2]}${port}`);
+    }
+  }
+  cache = { key, map };
+  return map;
+}
+
+/** pid → origins whose storage buckets the renderer holds open (one lsof for every pid asked). */
+export async function rendererOrigins(pids, platform = process.platform) {
+  const out = new Map();
+  if (!pids.length) return out;
+  const buckets = bucketOrigins(platform);
+  const r = await run(platform === 'darwin' ? '/usr/sbin/lsof' : 'lsof', ['-nP', '-Fpn', '-p', pids.join(',')], { timeoutMs: 15_000 });
+  let pid = null;
+  for (const line of r.stdout.split('\n')) {
+    if (line[0] === 'p') pid = Number(line.slice(1));
+    else if (line[0] === 'n' && pid) {
+      const m = /\/((?:Default|Profile \d+)\/File System\/\d{3})\//.exec(line);
+      const origin = m && buckets.get(m[1]);
+      if (origin) { if (!out.has(pid)) out.set(pid, new Set()); out.get(pid).add(origin); }
+    }
+  }
+  return out;
+}
+
+export function originOf(url) {
+  try { const u = new URL(url); return u.protocol.startsWith('http') ? u.origin : null; } catch { return null; }
+}
+
+export function localPort(url) {
+  try {
+    const u = new URL(url);
+    if (!['localhost', '127.0.0.1', '[::1]'].includes(u.hostname)) return null;
+    return Number(u.port || (u.protocol === 'https:' ? 443 : 80));
+  } catch { return null; }
+}

package/lib/darwin.mjs

@@ -0,0 +1,171 @@
+// macOS readers. Every one runs unprivileged; each returns raw cumulative values and leaves rates to derive.mjs.
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { run, clockSeconds, topBytes } from './run.mjs';
+
+const RUSAGE = fileURLToPath(new URL('./rusage.py', import.meta.url));
+const PRESSURE = { 1: 'normal', 2: 'warn', 4: 'critical' }; // dispatch/source.h DISPATCH_MEMORYPRESSURE_*
+
+async function sysctl(...names) {
+  const r = await run('/usr/sbin/sysctl', ['-n', ...names], { timeoutMs: 5000 });
+  if (!r.ok) throw new Error(r.error);
+  return r.stdout.split('\n');
+}
+
+export async function memory() {
+  const [[level, memsize, swap], vm, pressure] = await Promise.all([
+    sysctl('kern.memorystatus_vm_pressure_level', 'hw.memsize', 'vm.swapusage'),
+    run('/usr/bin/vm_stat', [], { timeoutMs: 5000 }),
+    run('/usr/bin/memory_pressure', ['-Q'], { timeoutMs: 5000 }),
+  ]);
+  if (!vm.ok) throw new Error(vm.error);
+  const pageSize = Number(/page size of (\d+)/.exec(vm.stdout)?.[1] ?? 16384);
+  const counter = (name) => Number(new RegExp(`^"?${name}"?:\\s+(\\d+)`, 'm').exec(vm.stdout)?.[1] ?? NaN);
+  const mb = (key) => Number(new RegExp(`${key} = ([\\d.]+)M`).exec(swap)?.[1] ?? NaN) * 1024 * 1024;
+  return {
+    pressureLevel: PRESSURE[Number(level)] ?? null,
+    totalBytes: Number(memsize),
+    freePct: pressure.ok ? Number(/free percentage: (\d+)%/.exec(pressure.stdout)?.[1] ?? NaN) : null,
+    swapUsedBytes: mb('used'), swapTotalBytes: mb('total'),
+    counters: {
+      swapouts: counter('Swapouts'), swapins: counter('Swapins'), pageouts: counter('Pageouts'), pageins: counter('Pageins'),
+      compressions: counter('Compressions'), decompressions: counter('Decompressions'),
+    },
+    pageSize,
+  };
+}
+
+/** Every process: pid, parent, owner, cumulative CPU seconds, RSS, command line. */
+export async function processes() {
+  const r = await run('/bin/ps', ['-axww', '-o', 'pid=,ppid=,uid=,time=,rss=,command='], { timeoutMs: 10_000 });
+  if (!r.ok) throw new Error(r.error);
+  const rows = [];
+  for (const line of r.stdout.split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\d+)\s+(.*)$/.exec(line);
+    if (m) rows.push({ pid: +m[1], ppid: +m[2], uid: +m[3], cpuSec: clockSeconds(m[4]), rssBytes: +m[5] * 1024, command: m[6] });
+  }
+  return rows;
+}
+
+let python;
+/** python3 that will not raise the Command Line Tools install dialog (/usr/bin/python3 is a stub without them). */
+async function pythonPath() {
+  if (python !== undefined) return python;
+  python = null;
+  for (const candidate of ['/opt/homebrew/bin/python3', '/usr/local/bin/python3', '/Library/Frameworks/Python.framework/Versions/Current/bin/python3']) {
+    if (existsSync(candidate)) { python = candidate; return python; }
+  }
+  if (existsSync('/usr/bin/python3') && (await run('/usr/bin/xcode-select', ['-p'], { timeoutMs: 3000 })).ok) python = '/usr/bin/python3';
+  return python;
+}
+
+/** Footprint and disk I/O per readable process (this user's; every user's as root). */
+export async function rusage() {
+  const py = await pythonPath();
+  if (!py) throw Object.assign(new Error('python3 not found (needed for libproc reads)'), { barrier: 'dependency' });
+  const r = await run(py, [RUSAGE], { timeoutMs: 10_000 });
+  if (!r.ok) throw new Error(r.error);
+  const map = new Map();
+  for (const line of r.stdout.split('\n')) {
+    const [pid, phys, read, written] = line.split(' ').map(Number);
+    if (pid) map.set(pid, { footprintBytes: phys, diskReadBytes: read, diskWrittenBytes: written });
+  }
+  return map;
+}
+export async function rusageAvailable() { return Boolean(await pythonPath()); }
+
+/** The largest processes of every user by footprint (top's MEM is phys_footprint). About 2 s; run rarely. */
+export async function topFootprints(n = 25) {
+  const r = await run('/usr/bin/top', ['-l', '1', '-o', 'mem', '-n', String(n), '-stats', 'pid,mem'], { timeoutMs: 15_000 });
+  if (!r.ok) throw new Error(r.error);
+  const map = new Map();
+  for (const line of r.stdout.split('\n')) {
+    const m = /^\s*(\d+)\s+(\S+)\s*$/.exec(line);
+    if (m) { const bytes = topBytes(m[2]); if (bytes != null) map.set(+m[1], bytes); }
+  }
+  return map;
+}
+
+function splitAddress(text) {
+  const at = text.lastIndexOf('.');
+  return { addr: text.slice(0, at), port: Number(text.slice(at + 1)) || 0 };
+}
+
+/** Every TCP socket as [local, foreign, state]. netstat reads the kernel's whole table unprivileged. */
+export async function tcp() {
+  const r = await run('/usr/sbin/netstat', ['-an', '-p', 'tcp'], { timeoutMs: 15_000 });
+  if (!r.ok) throw new Error(r.error);
+  const sockets = [];
+  for (const line of r.stdout.split('\n')) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 6 || !f[0].startsWith('tcp')) continue;
+    sockets.push({ local: splitAddress(f[3]), foreign: splitAddress(f[4]), state: f[5] });
+  }
+  const [first, last] = (await sysctl('net.inet.ip.portrange.first', 'net.inet.ip.portrange.last')).map(Number);
+  const [msl] = await sysctl('net.inet.tcp.msl');
+  return { sockets, range: { first, last }, timeWaitSec: (Number(msl) * 2) / 1000 };
+}
+
+/** Which pid listens on each port (this user's listeners; every user's as root). */
+export async function listeners() {
+  const r = await run('/usr/sbin/lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fpcn'], { timeoutMs: 15_000 });
+  const map = new Map();
+  let pid = null, command = null;
+  for (const line of r.stdout.split('\n')) {
+    if (line[0] === 'p') pid = Number(line.slice(1));
+    else if (line[0] === 'c') command = line.slice(1);
+    else if (line[0] === 'n') { const port = Number(line.slice(line.lastIndexOf(':') + 1)); if (port && !map.has(port)) map.set(port, { pid, command }); }
+  }
+  return map;
+}
+
+export async function files() {
+  const [open, max] = (await sysctl('kern.num_files', 'kern.maxfiles')).map(Number);
+  return { open, max };
+}
+
+const SKIP_MOUNT = /^\/(System\/Volumes\/(?!Data$)|Library\/Developer\/CoreSimulator\/|dev$|private\/var\/vm$)/;
+export async function volumes() {
+  const r = await run('/bin/df', ['-k', '-P', '-l'], { timeoutMs: 10_000 });
+  if (!r.ok && !r.stdout) throw new Error(r.error);
+  const rows = [];
+  for (const line of r.stdout.split('\n').slice(1)) {
+    const m = /^(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+\S+\s+(\/.*)$/.exec(line);
+    if (!m || !m[1].startsWith('/dev/') || SKIP_MOUNT.test(m[5])) continue;
+    rows.push({ mount: m[5], device: m[1], totalBytes: +m[2] * 1024, freeBytes: +m[4] * 1024 });
+  }
+  // APFS volumes in one container share its free space: report the container once, by its largest volume.
+  const hasData = rows.some((row) => row.mount === '/System/Volumes/Data');
+  const kept = [];
+  for (const row of rows.sort((a, b) => b.totalBytes - a.totalBytes)) {
+    if (row.mount === '/' && hasData) continue;
+    if (kept.some((k) => k.freeBytes === row.freeBytes && k.device.replace(/s\d+(s\d+)?$/, '') === row.device.replace(/s\d+(s\d+)?$/, ''))) continue;
+    kept.push(row);
+  }
+  return kept;
+}
+
+/** Cumulative MB moved per disk since boot (`iostat -I`); the delta is device throughput. */
+export async function diskIO() {
+  const r = await run('/usr/sbin/iostat', ['-Id', '-c', '1'], { timeoutMs: 5000 });
+  if (!r.ok) throw new Error(r.error);
+  const lines = r.stdout.split('\n').filter(Boolean);
+  const names = lines[0].trim().split(/\s+/);
+  const values = lines[2].trim().split(/\s+/).map(Number);
+  return Object.fromEntries(names.map((name, i) => [name, { bytes: values[i * 3 + 2] * 1024 * 1024 }]));
+}
+
+/** The user's launchd jobs: label → { pid, lastExit }. */
+export async function services() {
+  const r = await run('/bin/launchctl', ['list'], { timeoutMs: 5000 });
+  if (!r.ok) throw new Error(r.error);
+  const map = new Map();
+  for (const line of r.stdout.split('\n').slice(1)) {
+    const [pid, status, label] = line.split('\t');
+    if (label) map.set(label, { pid: pid === '-' ? null : Number(pid), lastExit: Number(status) });
+  }
+  return map;
+}
+
+export const isRoot = () => process.getuid?.() === 0;
+export const powermetricsAvailable = () => existsSync('/usr/bin/powermetrics');

package/lib/features.mjs

@@ -0,0 +1,36 @@
+// The features, each behind its own barrier. `none` runs for any user; `root`, `full-disk-access` and
+// `accessibility` are OS grants the pack never asks for; `integration:*` needs another program to answer.
+// A feature is on when its platform has it, its barrier is met, and config does not turn it off.
+export const FEATURES = [
+  { id: 'load', barrier: 'none', platforms: ['darwin', 'linux', 'win32'], reads: 'load average per core' },
+  { id: 'memory', barrier: 'none', platforms: ['darwin', 'linux', 'win32'], reads: 'pressure level, free %, swapouts/s, compressions/s, swap used' },
+  { id: 'processes', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'every process: CPU % from CPU-time deltas, memory, growth, owning session' },
+  { id: 'process-footprint', barrier: 'none', platforms: ['darwin', 'linux'], reads: "this user's processes: phys_footprint and disk writes (libproc / /proc/<pid>/io)" },
+  { id: 'all-users-footprint', barrier: 'root', platforms: ['darwin', 'linux'], reads: "every user's processes: footprint and disk writes" },
+  { id: 'renderers', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'browser renderers: hot, runaway; orphaned headless browsers' },
+  { id: 'daemons', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'system daemons: CPU, and footprint of the largest' },
+  { id: 'disk', barrier: 'none', platforms: ['darwin', 'linux', 'win32'], reads: 'free space per volume, fill rate, time to full' },
+  { id: 'disk-io', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'device throughput; top writers per process' },
+  { id: 'tcp', barrier: 'none', platforms: ['darwin', 'linux', 'win32'], reads: 'sockets per state, ephemeral ports in use, TIME_WAIT by listener and its pid' },
+  { id: 'files', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'open files against the system limit' },
+  { id: 'services', barrier: 'none', platforms: ['darwin', 'linux'], reads: "configured launchd/systemd user jobs: running, last exit, log silence" },
+  { id: 'supercode', barrier: 'integration:machine-daemon', platforms: ['darwin', 'linux', 'win32'], reads: "this machine's supercode connector: answering, server link, stuck launches" },
+  { id: 'browser-tabs', barrier: 'integration:browser-controller', platforms: ['darwin', 'linux', 'win32'], reads: "every tab with its owner (controller holder, or the process and session serving its local port) and the renderer serving it" },
+  { id: 'power', barrier: 'root', platforms: ['darwin'], reads: 'thermal pressure (powermetrics)' },
+];
+
+/** Every feature with on/off and the reason, for this platform, this user and this config. */
+export function resolveFeatures({ platform = process.platform, reader, config = {}, root = false, extras = {} }) {
+  return FEATURES.map((feature) => {
+    const row = { id: feature.id, barrier: feature.barrier, reads: feature.reads };
+    if (!feature.platforms.includes(platform)) return { ...row, on: false, reason: `not implemented on ${platform}` };
+    if (config.features?.[feature.id] === false) return { ...row, on: false, reason: 'turned off in config (features.' + feature.id + ': false)' };
+    if (feature.barrier === 'root' && !root) return { ...row, on: false, reason: 'needs root: run the probe as root (a LaunchDaemon or system unit); the pack never escalates' };
+    if (feature.id === 'process-footprint' && extras.rusage === false) return { ...row, on: false, reason: 'needs python3 for libproc reads (python.org, Homebrew or the Command Line Tools)' };
+    if (feature.id === 'power' && !reader.powermetricsAvailable?.()) return { ...row, on: false, reason: 'powermetrics not found' };
+    if (feature.id === 'browser-tabs' && !config.integrations?.browserController) return { ...row, on: false, reason: 'no browser controller configured (integrations.browserController.portFile or .url)' };
+    if (feature.id === 'services' && !(config.services ?? []).length) return { ...row, on: false, reason: 'no services configured (services: [{label, log?, maxSilentMin?}])' };
+    if (feature.id === 'supercode' && extras.supercode === false) return { ...row, on: false, reason: 'supercode not found (SUPERCODE_BIN)' };
+    return { ...row, on: true, reason: null };
+  });
+}

package/lib/format.mjs

@@ -0,0 +1,58 @@
+// The snapshot as a person reads it: alarms first, then each reading, then which features are off and why.
+const n = (v, unit = '') => (v == null ? '-' : `${v}${unit}`);
+const who = (p) => (p?.session?.address ? ` ← ${p.session.address}` : p?.session?.harness ? ` ← ${p.session.harness} pid ${p.session.agentPid}` : '');
+
+export function formatStatus(s, { all = false } = {}) {
+  if (!s) return 'machine health: no reading yet (is the probe running? `supercode health run`)';
+  const r = s.readings ?? {};
+  const age = Math.round((Date.now() - Date.parse(s.at)) / 1000);
+  const out = [`machine health · ${s.machine} (${s.platform}) · read ${age}s ago by probe pid ${s.probe?.pid}${s.probe?.config ? ` · config ${s.probe.config}` : ''}`];
+  if (age > 3 * (s.probe?.intervalSec ?? 15)) out.push(`  STALE: the probe has not written for ${age}s; its readings below are old`);
+  out.push('', s.alarms.length ? `ALARMS (${s.alarms.length})` : 'ALARMS: none');
+  for (const a of s.alarms) out.push(`  ${a.level.toUpperCase().padEnd(4)} ${a.summary}${a.detail?.pid ? ` [${a.detail.command?.slice(0, 80)}${who(a.detail)}]` : ''}  (since ${a.since})`);
+  if (s.maintainers) out.push(`  mailed to: ${s.maintainers.length ? s.maintainers.join(', ') : 'no maintainer subscribed (supercode health subscribe <address>)'}${s.mail?.pending ? ` · ${s.mail.pending} undelivered: ${s.mail.error}` : ''}`);
+  if (r.load) out.push('', `load      ${r.load.one} / ${r.load.five} / ${r.load.fifteen} on ${r.load.cores} cores (${r.load.perCore}× per core)`);
+  if (r.memory) {
+    const m = r.memory;
+    out.push(`memory    pressure ${n(m.pressureLevel)} · free ${n(m.freePct, '%')} · swapouts ${n(m.swapoutsPerSec, '/s')} · compressions ${n(m.compressionsPerSec, '/s')} · swap ${n(m.swapUsedGB)}/${n(m.swapTotalGB)} GB · swapped ${n(m.swappedPctRamWindow, '% RAM')} in ${n(m.swappedWindowMin, ' min')}`);
+  }
+  if (r.processes) {
+    out.push(`processes ${r.processes.count}; by CPU:`);
+    for (const p of r.processes.topCpu.slice(0, all ? 10 : 5)) out.push(`  ${String(p.cpuPct ?? '-').padStart(4)}%  ${String(p.footprintMB).padStart(6)} MB  ${p.pid}  ${p.command.slice(0, 90)}${who(p)}`);
+    out.push('  by memory:');
+    for (const p of r.processes.topMemory.slice(0, all ? 10 : 5)) out.push(`  ${String(p.footprintMB).padStart(6)} MB ${p.growthMBPerMin != null ? `(${p.growthMBPerMin >= 0 ? '+' : ''}${p.growthMBPerMin}/min) ` : ''} ${p.pid}  ${p.command.slice(0, 90)}${who(p)}`);
+  }
+  if (r.renderers) {
+    out.push(`renderers ${r.renderers.count} using ${r.renderers.totalMB} MB${r.renderers.orphanedHeadless.length ? `; ${r.renderers.orphanedHeadless.length} orphaned headless browser(s): ${r.renderers.orphanedHeadless.map((p) => p.pid).join(', ')}` : ''}`);
+    for (const p of r.renderers.top.slice(0, 3)) out.push(`  ${String(p.cpuPct ?? '-').padStart(4)}%  ${String(p.footprintMB).padStart(6)} MB  ${p.pid}${who(p)}${p.tab ? ` · ${p.tab.url.slice(0, 60)} · ${p.tab.owner}${who(p.tab.server)}` : ' · tab not matched'}`);
+  }
+  if (r.browserTabs) {
+    out.push(`tabs      ${r.browserTabs.count} open${Object.keys(r.browserTabs.byHolder).length ? ` (${Object.entries(r.browserTabs.byHolder).map(([h, c]) => `${h} ${c}`).join(', ')})` : ''}`);
+    for (const t of r.browserTabs.tabs ?? []) out.push(`  ${t.url.slice(0, 70)} · ${t.owner}${who(t.server)}${t.renderers.length ? ` · renderer ${t.renderers.join(', ')}` : ''}`);
+  }
+  if (r.daemons) out.push(`daemons   ${r.daemons.filter((d) => (d.cpuPct ?? 0) >= 5 || d.footprintMB >= 512).map((d) => `${d.name} ${n(d.cpuPct, '%')} ${d.footprintMB} MB`).join(' · ') || 'all quiet'}`);
+  if (r.disk) for (const d of r.disk) out.push(`disk      ${d.mount}: ${d.freeGB} GB free of ${d.totalGB} (${d.freePct}%)${d.fillGBPerHour != null ? ` · ${d.fillGBPerHour >= 0 ? 'filling' : 'freeing'} ${Math.abs(d.fillGBPerHour)} GB/h` : ''}${d.hoursToFull != null ? ` · full in ${d.hoursToFull} h` : ''}`);
+  if (r.diskIO) out.push(`disk I/O  ${Object.entries(r.diskIO).map(([k, v]) => `${k} ${n(v.MBps, ' MB/s')}`).join(' · ')}`);
+  if (r.diskWriters?.length) out.push(`writers   ${r.diskWriters.slice(0, 3).map((w) => `${w.pid} ${w.writeMBps} MB/s ${w.command.slice(0, 50)}${who(w)}`).join(' · ')}`);
+  if (r.tcp) {
+    const t = r.tcp;
+    out.push(`tcp       ${Object.entries(t.states).sort((a, b) => b[1] - a[1]).map(([k, v]) => `${k} ${v}`).join(' · ')}`);
+    out.push(`          ephemeral range ${t.range.first}-${t.range.last} (${t.range.size}); busiest ${t.ephemeral[0] ? `${t.ephemeral[0].addr} ${t.ephemeral[0].used} (${t.ephemeral[0].pct}%)` : '-'}; TIME_WAIT lasts ${t.timeWaitSec}s`);
+    for (const g of t.timeWaitByTarget.slice(0, 3)) out.push(`          TIME_WAIT ${g.count} (${g.pct}%) against ${g.target}${g.listener ? ` · pid ${g.listener.pid} ${g.listener.command.slice(0, 60)}${who(g.listener)}` : ''}`);
+  }
+  if (r.files) out.push(`files     ${r.files.open} of ${r.files.max} open (${r.files.pct}%)`);
+  if (r.services) for (const sv of r.services) out.push(`service   ${sv.name ?? sv.label}: ${sv.running ? `running pid ${sv.pid}` : `NOT running (last exit ${sv.lastExit})`}${sv.logAgeMin != null ? ` · log written ${sv.logAgeMin} min ago` : ''}`);
+  if (r.supercode) {
+    const c = r.supercode;
+    out.push(`supercode connector ${c.connector ? `${c.connector.running ? 'running' : 'NOT running'}, server sees ${c.connector.connection ?? '-'}${c.connector.notSyncing ? `, ${c.connector.notSyncing} sessions not syncing (${c.connector.lastError})` : ''}` : (c.statusError ?? 'unknown')} · daemon ${c.daemon.answered ? `answered in ${c.daemon.ms} ms` : `NOT answering (${c.daemon.error})`} · launches ${c.launches.read ? `${c.launches.recent} in 24 h, ${c.launches.stuck.length} stuck, ${c.launches.failed.length} failed` : `unread (${c.launches.error})`}`);
+  }
+  if (r.power) out.push(`power     thermal pressure ${r.power.thermalPressure}`);
+  out.push('', formatFeatures(s.features, { offOnly: !all }));
+  return out.join('\n');
+}
+
+export function formatFeatures(features, { offOnly = false } = {}) {
+  const rows = offOnly ? features.filter((f) => !f.on || f.error) : features;
+  const head = offOnly ? (rows.length ? 'features off or failing:' : 'every feature is on') : 'features:';
+  return [head, ...rows.map((f) => `  ${f.on ? (f.error ? 'ERR' : 'on ') : 'off'} ${f.id.padEnd(20)} ${f.barrier.padEnd(31)} ${f.error ?? f.reason ?? f.reads}`)].join('\n');
+}

package/lib/linux.mjs

@@ -0,0 +1,148 @@
+// Linux readers, from /proc and statfs. Every one runs unprivileged; another user's /proc/<pid>/io needs root.
+import { readFileSync, readdirSync, readlinkSync, statfsSync } from 'node:fs';
+import { run } from './run.mjs';
+
+const read = (path) => readFileSync(path, 'utf8');
+const TICKS = 100; // USER_HZ: the unit of /proc/<pid>/stat CPU times on every mainstream architecture
+const PAGE = 4096;
+
+export async function memory() {
+  const meminfo = Object.fromEntries(read('/proc/meminfo').split('\n').filter(Boolean).map((line) => {
+    const [key, value] = line.split(':'); return [key, Number.parseInt(value, 10) * 1024];
+  }));
+  const vmstat = Object.fromEntries(read('/proc/vmstat').split('\n').filter(Boolean).map((line) => line.split(' ')).map(([k, v]) => [k, Number(v)]));
+  let psi = null;
+  try {
+    const text = read('/proc/pressure/memory');
+    psi = { someAvg10: Number(/some avg10=([\d.]+)/.exec(text)?.[1]), fullAvg10: Number(/full avg10=([\d.]+)/.exec(text)?.[1]) };
+  } catch { /* kernels without PSI */ }
+  const total = meminfo.MemTotal;
+  const level = psi ? (psi.fullAvg10 >= 10 ? 'critical' : psi.someAvg10 >= 10 ? 'warn' : 'normal') : null;
+  return {
+    pressureLevel: level, psi, totalBytes: total,
+    freePct: Math.round((meminfo.MemAvailable / total) * 100),
+    swapUsedBytes: meminfo.SwapTotal - meminfo.SwapFree, swapTotalBytes: meminfo.SwapTotal,
+    counters: { swapouts: vmstat.pswpout, swapins: vmstat.pswpin, pageouts: vmstat.pgpgout, pageins: vmstat.pgpgin, compressions: null, decompressions: null, majorFaults: vmstat.pgmajfault },
+    pageSize: PAGE,
+  };
+}
+
+export async function processes() {
+  const rows = [];
+  for (const name of readdirSync('/proc')) {
+    if (!/^\d+$/.test(name)) continue;
+    try {
+      const stat = read(`/proc/${name}/stat`);
+      const close = stat.lastIndexOf(')');
+      const f = stat.slice(close + 2).split(' ');
+      const uid = Number(/^Uid:\s+(\d+)/m.exec(read(`/proc/${name}/status`))?.[1] ?? -1);
+      let command = read(`/proc/${name}/cmdline`).replace(/\0+$/, '').replace(/\0/g, ' ');
+      if (!command) command = `[${stat.slice(stat.indexOf('(') + 1, close)}]`;
+      rows.push({ pid: Number(name), ppid: Number(f[1]), uid, cpuSec: (Number(f[11]) + Number(f[12])) / TICKS, rssBytes: Number(f[21]) * PAGE, command });
+    } catch { /* exited while read */ }
+  }
+  return rows;
+}
+
+/** Per-process disk I/O (readable for this user's processes; every user's as root). */
+export async function rusage() {
+  const map = new Map();
+  for (const name of readdirSync('/proc')) {
+    if (!/^\d+$/.test(name)) continue;
+    try {
+      const io = read(`/proc/${name}/io`);
+      const status = read(`/proc/${name}/status`);
+      const kb = (key) => Number(new RegExp(`^${key}:\\s+(\\d+)`, 'm').exec(status)?.[1] ?? 0) * 1024;
+      map.set(Number(name), {
+        footprintBytes: kb('VmRSS') + kb('VmSwap'),
+        diskReadBytes: Number(/^read_bytes: (\d+)/m.exec(io)?.[1] ?? 0),
+        diskWrittenBytes: Number(/^write_bytes: (\d+)/m.exec(io)?.[1] ?? 0),
+      });
+    } catch { /* another user's, or exited */ }
+  }
+  return map;
+}
+export async function rusageAvailable() { return true; }
+export async function topFootprints() { return new Map(); }
+
+const STATES = ['', 'ESTABLISHED', 'SYN_SENT', 'SYN_RECV', 'FIN_WAIT1', 'FIN_WAIT2', 'TIME_WAIT', 'CLOSE', 'CLOSE_WAIT', 'LAST_ACK', 'LISTEN', 'CLOSING'];
+function hexAddress(text) {
+  const [addr, port] = text.split(':');
+  return { addr: addr.length === 8 ? addr.match(/../g).reverse().map((b) => Number.parseInt(b, 16)).join('.') : addr, port: Number.parseInt(port, 16) };
+}
+export async function tcp() {
+  const sockets = [];
+  for (const file of ['/proc/net/tcp', '/proc/net/tcp6']) {
+    let text; try { text = read(file); } catch { continue; }
+    for (const line of text.split('\n').slice(1)) {
+      const f = line.trim().split(/\s+/);
+      if (f.length < 4) continue;
+      sockets.push({ local: hexAddress(f[1]), foreign: hexAddress(f[2]), state: STATES[Number.parseInt(f[3], 16)] ?? f[3], inode: f[9] });
+    }
+  }
+  const [first, last] = read('/proc/sys/net/ipv4/ip_local_port_range').trim().split(/\s+/).map(Number);
+  return { sockets, range: { first, last }, timeWaitSec: 60 };
+}
+
+/** Listening port → owning pid, through /proc/<pid>/fd socket inodes (this user's processes). */
+export async function listeners(sockets = []) {
+  const byInode = new Map(sockets.filter((s) => s.state === 'LISTEN').map((s) => [s.inode, s.local.port]));
+  const map = new Map();
+  if (!byInode.size) return map;
+  for (const name of readdirSync('/proc')) {
+    if (!/^\d+$/.test(name)) continue;
+    let fds; try { fds = readdirSync(`/proc/${name}/fd`); } catch { continue; }
+    for (const fd of fds) {
+      let target; try { target = readlinkSync(`/proc/${name}/fd/${fd}`); } catch { continue; }
+      const inode = /^socket:\[(\d+)\]$/.exec(target)?.[1];
+      if (inode && byInode.has(inode) && !map.has(byInode.get(inode))) {
+        let command = ''; try { command = read(`/proc/${name}/comm`).trim(); } catch { /* exited */ }
+        map.set(byInode.get(inode), { pid: Number(name), command });
+      }
+    }
+  }
+  return map;
+}
+
+export async function files() {
+  const [open, , max] = read('/proc/sys/fs/file-nr').trim().split(/\s+/).map(Number);
+  return { open, max };
+}
+
+const SKIP_FS = new Set(['proc', 'sysfs', 'tmpfs', 'devtmpfs', 'devpts', 'cgroup', 'cgroup2', 'overlay', 'squashfs', 'securityfs', 'debugfs', 'tracefs', 'pstore', 'bpf', 'mqueue', 'hugetlbfs', 'fusectl', 'configfs', 'autofs', 'binfmt_misc', 'nsfs', 'ramfs', 'efivarfs', 'rpc_pipefs', 'fuse.portal', '9p']);
+export async function volumes() {
+  const seen = new Set(); const rows = [];
+  for (const line of read('/proc/mounts').split('\n')) {
+    const [device, mount, type] = line.split(' ');
+    if (!mount || SKIP_FS.has(type) || seen.has(device)) continue;
+    seen.add(device);
+    try { const s = statfsSync(mount.replace(/\\040/g, ' ')); rows.push({ mount, device, totalBytes: s.blocks * s.bsize, freeBytes: s.bavail * s.bsize }); } catch { /* unreadable mount */ }
+  }
+  return rows;
+}
+
+export async function diskIO() {
+  const out = {};
+  for (const line of read('/proc/diskstats').split('\n')) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 14 || /^(loop|ram|dm-)/.test(f[2]) || /\d$/.test(f[2]) && !/nvme\d+n\d+$/.test(f[2])) continue;
+    out[f[2]] = { bytes: (Number(f[5]) + Number(f[9])) * 512 };
+  }
+  return out;
+}
+
+/** systemd --user units: name → { pid, lastExit, active }. */
+export async function services(names = []) {
+  const map = new Map();
+  if (!names.length) return map;
+  const r = await run('systemctl', ['--user', 'show', '-p', 'Id,MainPID,ExecMainStatus,ActiveState', ...names], { timeoutMs: 5000 });
+  if (!r.ok) throw new Error(r.error);
+  for (const block of r.stdout.split('\n\n')) {
+    const kv = Object.fromEntries(block.split('\n').filter(Boolean).map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]));
+    if (kv.Id) map.set(kv.Id.replace(/\.service$/, ''), { pid: Number(kv.MainPID) || null, lastExit: Number(kv.ExecMainStatus) || 0, active: kv.ActiveState });
+  }
+  return map;
+}
+
+export const isRoot = () => process.getuid?.() === 0;
+export const powermetricsAvailable = () => false;