@volter/supercode-health 0.1.0 → 0.1.2

package/lib/darwin.mjs

@@ -156,14 +156,20 @@ export async function diskIO() {
 }
 
 /** 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);
+/** The user's launchd jobs: label → { pid, lastExit, runs }. `runs` counts every spawn since the job was loaded,
+ *  so a KeepAlive job that crashes and respawns between two readings shows as runs rising with a failed last exit,
+ *  where `launchctl list` alone shows a pid and looks running (12 ms per `launchctl print`). */
+export async function services(labels = []) {
   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) });
-  }
+  const uid = process.getuid?.();
+  await Promise.all(labels.map(async (label) => {
+    const r = await run('/bin/launchctl', ['print', `gui/${uid}/${label}`], { timeoutMs: 5000 });
+    if (!r.ok) return; // not loaded
+    const field = (name) => new RegExp(`^\\t${name} = (.+)$`, 'm').exec(r.stdout)?.[1];
+    const pid = Number(field('pid')) || null;
+    const lastExit = field('last exit code');
+    map.set(label, { pid, lastExit: lastExit == null || /never exited/.test(lastExit) ? 0 : Number.parseInt(lastExit, 10), runs: Number(field('runs')) || 0 });
+  }));
   return map;
 }
 

package/lib/format.mjs

@@ -1,6 +1,6 @@
 // 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}` : '');
+const who = (p) => (p?.session?.address ? ` ← ${p.session.address}` : p?.session?.harness ? ` ← ${p.session.harness} pid ${p.session.agentPid}` : p?.session?.note ? ` ← (${p.session.note})` : p?.session?.inherited ? ` ← (no agent above; inherited ${p.session.inherited})` : '');
 
 export function formatStatus(s, { all = false } = {}) {
   if (!s) return 'machine health: no reading yet (is the probe running? `supercode health run`)';
@@ -25,6 +25,10 @@ export function formatStatus(s, { all = false } = {}) {
   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'}`);
+    // Chrome names no renderer per tab (CDP's TargetInfo has no pid): a renderer that holds no storage bucket
+    // cannot be matched, so the tabs no renderer was matched to are listed with their owners instead.
+    const unmatched = (r.browserTabs?.tabs ?? []).filter((t) => !t.renderers.length);
+    if (r.renderers.top.slice(0, 3).some((p) => !p.tab) && unmatched.length) out.push(`  unmatched tabs (one may be served by an unmatched renderer above): ${unmatched.map((t) => `${t.url.slice(0, 50)} · ${t.owner}${who(t.server)}`).join(' | ')}`);
   }
   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(', ')})` : ''}`);
@@ -41,7 +45,7 @@ export function formatStatus(s, { all = false } = {}) {
     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.services) for (const sv of r.services) out.push(`service   ${sv.name ?? sv.label}: ${sv.crashing ? `CRASH-LOOPING: ${sv.restarts} restarts since the last reading, last exit ${sv.lastExit}, ${sv.runs} runs` : 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})`}`);

package/lib/linux.mjs

@@ -135,11 +135,11 @@ export async function diskIO() {
 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 });
+  const r = await run('systemctl', ['--user', 'show', '-p', 'Id,MainPID,ExecMainStatus,ActiveState,NRestarts', ...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 });
+    if (kv.Id) map.set(kv.Id.replace(/\.service$/, ''), { pid: Number(kv.MainPID) || null, lastExit: Number(kv.ExecMainStatus) || 0, active: kv.ActiveState, runs: (Number(kv.NRestarts) || 0) + 1 });
   }
   return map;
 }

package/lib/mail.mjs

@@ -44,7 +44,7 @@ export class Outbox {
 const LEVEL = { warn: 'WARN', crit: 'CRIT', none: 'clear' };
 function line(t) {
   const d = t.detail;
-  const who = d?.session?.address ? `; session ${d.session.address}` : d?.session?.harness ? `; under ${d.session.harness} pid ${d.session.agentPid}` : d?.pid ? '; no agent session above it' : '';
+  const who = d?.session?.address ? `; session ${d.session.address}` : d?.session?.harness ? `; under ${d.session.harness} pid ${d.session.agentPid}` : d?.session?.note ? `; ${d.session.note}` : d?.session?.inherited ? `; no agent above it (environment inherited from ${d.session.inherited}, unverified)` : d?.pid ? '; no agent session above it' : '';
   const proc = d?.pid ? ` [pid ${d.pid}: ${d.command}${who}]` : d?.listener ? ` [listener pid ${d.listener.pid}: ${d.listener.command}${d.listener.session?.address ? `; session ${d.listener.session.address}` : ''}]` : '';
   return `${LEVEL[t.to] ?? t.to}${t.from !== 'none' && t.to !== 'none' ? ` (was ${t.from})` : ''} ${t.key}: ${t.summary}${proc}`;
 }

package/lib/sample.mjs

@@ -18,6 +18,11 @@ const HARNESS = { claude: 'claude-code', codex: 'codex', gemini: 'gemini', goose
 const RENDERER = /Helper \(Renderer\)|--type=renderer/;
 const BROWSER_MAIN = /(Google Chrome|Chromium|chrome-headless-shell|chrome)(\s|$)/i;
 const LOOPBACK = /^(127\.|::1$|localhost$)/;
+/** The session an agent names on its own command line: `--resume <id>`, `--session-id <id>`, `-r <id>`, `codex resume <id>`. */
+function argvSession(command) {
+  return /(?:--resume|--session-id|\s-r)[=\s]+([0-9a-f]{8}-[0-9a-f-]{27,})/.exec(command)?.[1]
+    ?? /\bresume\s+([0-9a-zA-Z][0-9a-zA-Z-]{7,})/.exec(command)?.[1] ?? null;
+}
 // The slow set's readings and alarm families, by the feature that produces them.
 const SLOW_FEATURE = { disk: 'disk', services: 'services', service: 'services', supercode: 'supercode', browserTabs: 'browser-tabs', tabs: 'browser-tabs', power: 'power' };
 // Every alarm family, by the feature that observes it.
@@ -32,6 +37,8 @@ export class Sampler {
     this.swapRing = [];          // [[at, swapouts]] for the 30-minute sum
     this.diskRing = new Map();   // mount → [[at, freeBytes]] for the fill rate
     this.sessionCache = new Map(); // pid:command → session
+    this.serviceRuns = new Map(); // service label → spawn count at the last reading
+    this.recentListeners = new Map(); // port → when it was last seen listening (its TIME_WAITs outlive it)
     this.topFoot = { at: 0, map: new Map() };
     this.slow = { at: 0, readings: {}, observations: [], families: new Set(), errors: {} };
     this.slowStarted = 0;
@@ -110,8 +117,11 @@ export class Sampler {
         r.footprintSource = ru ? 'footprint' : top != null ? 'footprint (top)' : 'rss';
         r.writeBps = same && dt && ru && prev.written != null && ru.diskWrittenBytes >= prev.written ? (ru.diskWrittenBytes - prev.written) / dt : null;
         nextPrev.set(r.pid, { cpuSec: r.cpuSec, command: r.command, written: ru?.diskWrittenBytes ?? null });
-        const hist = same ? (this.footHistory.get(r.pid) ?? []) : [];
-        hist.push([now, r.footprintBytes]);
+        // Growth compares like with like: a footprint read through a different instrument than the last reading
+        // (another user's process alternates between top's 5-minute map and RSS) starts a new history.
+        let hist = same ? (this.footHistory.get(r.pid) ?? []) : [];
+        if (hist.length && hist.at(-1)[2] !== r.footprintSource) hist = [];
+        hist.push([now, r.footprintBytes, r.footprintSource]);
         while (hist.length && now - hist[0][0] > 130_000) hist.shift();
         this.footHistory.set(r.pid, hist);
         const ago = hist.findLast?.(([at]) => now - at >= 55_000) ?? [...hist].reverse().find(([at]) => now - at >= 55_000);
@@ -225,6 +235,10 @@ export class Sampler {
         if (!['*', '0.0.0.0', '::', '[::]'].includes(s.local.addr)) local.add(s.local.addr);
       }
       const inRange = (port) => port >= range.first && port <= range.last;
+      for (const port of listening) this.recentListeners.set(port, now);
+      const hold = Math.max(4 * timeWaitSec * 1000, 120_000);
+      for (const [port, at] of this.recentListeners) if (now - at > hold) this.recentListeners.delete(port);
+      const wasListening = (port) => this.recentListeners.has(port);
       const wildcard = new Set();
       const used = new Map();
       const add = (addr, port) => { if (!used.has(addr)) used.set(addr, new Set()); used.get(addr).add(port); };
@@ -236,9 +250,11 @@ export class Sampler {
         if (local.has(s.foreign.addr) && inRange(s.foreign.port)) add(s.foreign.addr, s.foreign.port);
         if (s.state !== 'TIME_WAIT') continue;
         // Group each TIME_WAIT by the endpoint it churned against: a listener here (either side), else the remote.
+        // A listener that exited still owns its TIME_WAITs until they drain, so a port counts as a listener for
+        // a while after it was last seen listening; otherwise its alarm would clear while the sockets remain.
         let target;
-        if (listening.has(s.local.port)) target = `:${s.local.port}`;
-        else if ((local.has(s.foreign.addr) || LOOPBACK.test(s.foreign.addr)) && listening.has(s.foreign.port)) target = `:${s.foreign.port}`;
+        if (wasListening(s.local.port)) target = `:${s.local.port}`;
+        else if ((local.has(s.foreign.addr) || LOOPBACK.test(s.foreign.addr)) && wasListening(s.foreign.port)) target = `:${s.foreign.port}`;
         else target = `${s.foreign.addr}:${s.foreign.port}`;
         targets.set(target, (targets.get(target) ?? 0) + 1);
       }
@@ -255,12 +271,13 @@ export class Sampler {
       } else owners = this.owners ?? new Map();
       const timeWaitByTarget = top.map(([target, count]) => {
         const owner = target.startsWith(':') ? owners.get(Number(target.slice(1))) : null;
-        return { target, count, pct: round((count / size) * 100), ...(owner ? { listener: { pid: owner.pid, command: short(owner.command) } } : {}) };
+        const exited = target.startsWith(':') && !listening.has(Number(target.slice(1)));
+        return { target, count, pct: round((count / size) * 100), ...(exited ? { exited: true } : {}), ...(owner ? { listener: { pid: owner.pid, command: short(owner.command) } } : {}) };
       });
       readings.tcp = { states, timeWait: states.TIME_WAIT ?? 0, range: { ...range, size }, timeWaitSec, ephemeral, timeWaitByTarget };
       families.add('tcp');
       for (const e of ephemeral) observations.push({ key: `tcp.ephemeral:${e.addr}`, family: 'tcp', def: alarm('tcp.ephemeral'), value: e.pct, unit: '% of ports', summary: `${e.used} of ${size} ephemeral ports in use on ${e.addr}` });
-      for (const t of timeWaitByTarget) observations.push({ key: `tcp.timeWaitTarget:${t.target}`, family: 'tcp', def, value: t.pct, unit: '% of ports', summary: `${t.count} TIME_WAIT against ${t.target.startsWith(':') ? `listener ${t.target}` : t.target}${t.listener ? ` (pid ${t.listener.pid})` : ''}; range ${size}, TIME_WAIT lasts ${timeWaitSec} s`, detail: t });
+      for (const t of timeWaitByTarget) observations.push({ key: `tcp.timeWaitTarget:${t.target}`, family: 'tcp', def, value: t.pct, unit: '% of ports', summary: `${t.count} TIME_WAIT against ${t.target.startsWith(':') ? `listener ${t.target}${t.exited ? ' (listener has exited; its TIME_WAITs are draining)' : ''}` : t.target}${t.listener ? ` (pid ${t.listener.pid})` : ''}; range ${size}, TIME_WAIT lasts ${timeWaitSec} s`, detail: t });
     });
 
     // ---- the slow set ---------------------------------------------------------------------------------
@@ -327,12 +344,18 @@ export class Sampler {
         const log = s.log?.replace(/^~(?=\/)/, homedir());
         if (log) try { logAgeMin = Math.max(0, round((now - statSync(log).mtimeMs) / 60_000)); } catch { logAgeMin = null; }
         const running = Boolean(job?.pid);
-        const down = !job || (!running && (job.lastExit !== 0 || s.keepAlive !== false));
-        const why = !job ? 'not loaded' : !running ? `not running (last exit ${job.lastExit})` : null;
+        // Down (ADR 0006): not loaded, not running, or failing. A KeepAlive job that crashes and is respawned
+        // always has a pid when read, so failing is runs rising since the last reading with a non-zero last exit.
+        const before = this.serviceRuns.get(s.label);
+        const restarts = job && before != null && job.runs >= before ? job.runs - before : 0;
+        if (job) this.serviceRuns.set(s.label, job.runs);
+        const crashing = Boolean(job && restarts > 0 && job.lastExit !== 0);
+        const down = !job || (!running && (job.lastExit !== 0 || s.keepAlive !== false)) || crashing;
+        const why = !job ? 'not loaded' : !running ? `not running (last exit ${job.lastExit})` : crashing ? `crash-looping: ${restarts} restart${restarts === 1 ? '' : 's'} since the last reading, last exit ${job.lastExit} (${job.runs} runs since loaded)` : null;
         if (down) slow.observations.push({ key: `service.down:${s.label}`, family: 'service', def: alarm('service.down'), value: 1, met: { warn: true, crit: false, clears: false }, summary: `service ${s.name ?? s.label} is ${why}` });
         else slow.observations.push({ key: `service.down:${s.label}`, family: 'service', def: alarm('service.down'), value: 0, met: { warn: false, crit: false, clears: true }, summary: `service ${s.name ?? s.label} running` });
         if (s.log && s.maxSilentMin) slow.observations.push({ key: `service.deaf:${s.label}`, family: 'service', def: { warn: s.maxSilentMin, forSec: 0 }, value: logAgeMin ?? Infinity, unit: 'min silent', summary: logAgeMin == null ? `service ${s.name ?? s.label}: its log ${log} is missing` : `service ${s.name ?? s.label} has written nothing to its log for ${logAgeMin} min` });
-        return { label: s.label, name: s.name ?? null, running, pid: job?.pid ?? null, lastExit: job?.lastExit ?? null, ...(s.log ? { logAgeMin } : {}) };
+        return { label: s.label, name: s.name ?? null, running, pid: job?.pid ?? null, lastExit: job?.lastExit ?? null, runs: job?.runs ?? null, restarts, crashing, ...(s.log ? { logAgeMin } : {}) };
       });
     });
 
@@ -435,27 +458,44 @@ export class Sampler {
       for (let i = 0; i < 40 && p > 1; i += 1) { const r = byPid.get(p); if (!r) break; out.push(r); p = r.ppid; }
       return out;
     };
+    // Who owns a process is the agent above it, named by the agent itself: the session id on its own command
+    // line (`--resume`/`--session-id`, `codex resume`), else the id it sets in its own children's environment.
+    // An environment is never trusted across a tmux server: every pane inherits the variables of whichever
+    // session started that server (measured 2026-10-02: one tmux server credited one Claude session with
+    // dozens of unrelated panes). Above no agent, an inherited id is reported as inherited, never as owner.
     const need = new Set();
     const plan = new Map();
+    const childOf = (pid) => this.procs.rows.find((x) => x.ppid === pid && !AGENT.test(base(x.command)));
     for (const pid of wanted) {
       const r = byPid.get(pid);
       if (!r) continue;
       const cacheKey = `${pid}:${r.command}`;
       if (this.sessionCache.has(cacheKey)) { plan.set(pid, { cacheKey }); continue; }
       const up = chain(pid);
-      const agentIndex = up.findIndex((x) => AGENT.test(base(x.command)));
-      const lineage = agentIndex >= 0 ? up.slice(0, agentIndex + 1) : up.slice(0, 3);
-      for (const x of lineage) need.add(x.pid);
-      plan.set(pid, { cacheKey, lineage, agent: agentIndex >= 0 ? up[agentIndex] : null });
+      const stop = up.findIndex((x) => AGENT.test(base(x.command)) || base(x.command) === 'tmux');
+      const top = stop >= 0 ? up[stop] : null;
+      const agent = top && AGENT.test(base(top.command)) ? top : null;
+      // The agent's direct child on this lineage carries the variables the agent set; for the agent itself, any child.
+      const witness = agent ? (stop > 0 ? up[stop - 1] : childOf(agent.pid)) : (top ? null : r);
+      if (witness) need.add(witness.pid);
+      plan.set(pid, { cacheKey, agent, witness, pane: Boolean(top && !agent) });
     }
     const env = need.size ? await this.#environments([...need]) : new Map();
     for (const [pid, p] of plan) {
       if (!this.sessionCache.has(p.cacheKey)) {
-        let found = null;
-        for (const x of p.lineage) { found = env.get(x.pid); if (found) break; }
-        const harness = p.agent ? (HARNESS[base(p.agent.command)] ?? base(p.agent.command)) : found?.harness ?? null;
-        const session = found ? { harness: found.harness ?? harness, id: found.id, address: found.address ?? `sc:${this.machine}:${found.harness ?? harness}:${found.id}`, agentPid: p.agent?.pid ?? null }
-          : p.agent ? { harness, id: null, address: null, agentPid: p.agent.pid } : null;
+        let session = null;
+        if (p.agent) {
+          const harness = HARNESS[base(p.agent.command)] ?? base(p.agent.command);
+          const seen = p.witness ? env.get(p.witness.pid) : null;
+          const id = argvSession(p.agent.command) ?? (harness === 'codex' ? seen?.codex : harness === 'claude-code' ? seen?.claude : null) ?? null;
+          session = { harness, id, address: id ? `sc:${this.machine}:${harness}:${id}` : null, agentPid: p.agent.pid };
+        } else if (p.pane) {
+          session = { harness: null, id: null, address: null, agentPid: null, note: 'in a tmux pane with no agent above it' };
+        } else {
+          const seen = p.witness ? env.get(p.witness.pid) : null;
+          const inherited = seen?.supercode ?? (seen?.claude ? `sc:${this.machine}:claude-code:${seen.claude}` : seen?.codex ? `sc:${this.machine}:codex:${seen.codex}` : null);
+          if (inherited) session = { harness: null, id: null, address: null, agentPid: null, inherited };
+        }
         this.sessionCache.set(p.cacheKey, session);
         if (this.sessionCache.size > 5000) this.sessionCache.delete(this.sessionCache.keys().next().value);
       }
@@ -471,10 +511,7 @@ export class Sampler {
       const supercode = /(?:^|\s|\0)SUPERCODE_CALLER=(sc:[^\s\0]+)/.exec(text)?.[1];
       const claude = /(?:^|\s|\0)CLAUDE_CODE_SESSION_ID=([0-9a-f-]{36})/.exec(text)?.[1];
       const codex = /(?:^|\s|\0)CODEX_THREAD_ID=([0-9a-zA-Z-]{8,})/.exec(text)?.[1];
-      if (claude) return { harness: 'claude-code', id: claude };
-      if (codex) return { harness: 'codex', id: codex };
-      if (supercode) { const [, , harness, id] = supercode.split(':'); return { harness, id, address: supercode }; }
-      return null;
+      return supercode || claude || codex ? { supercode, claude, codex } : null;
     };
     if (this.platform === 'linux') {
       for (const pid of pids) { try { const found = pick(readFileSync(`/proc/${pid}/environ`, 'utf8')); if (found) map.set(pid, found); } catch { /* another user's */ } }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-health",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Optional machine pack: a cheap, deterministic probe of a machine's vitals that mails the machine's maintainer when a threshold is crossed. Each feature sits behind its own permission barrier.",
   "license": "MIT",
@@ -10,8 +10,17 @@
     "./format": "./lib/format.mjs",
     "./paths": "./lib/paths.mjs"
   },
-  "bin": { "supercode-health": "./bin/health.mjs" },
-  "files": ["index.mjs", "lib", "bin", "README.md"],
-  "engines": { "node": ">=20" },
+  "bin": {
+    "supercode-health": "./bin/health.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "lib",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "dependencies": {}
 }