@volter/supercode-health 0.1.14 → 0.1.16

package/lib/drift.mjs

@@ -71,7 +71,18 @@ export async function staleSupercode({ rows = null } = {}) {
     } else if (Number.isNaN(started) || installed <= started + 1000) continue; // ps says a start to the second
     stale.push({ pid: Number(pid), command: command.slice(0, 200), file, startedAt: new Date(started).toISOString(), installedAt: new Date(installed).toISOString() });
   }
-  return stale.sort((a, b) => b.installedAt.localeCompare(a.installedAt));
+  return moved(stale).sort((a, b) => b.installedAt.localeCompare(a.installedAt));
+}
+
+/** Less the processes that answer through the release on disk: an MCP server's pump says so in `<home>/run/mcp/<pid>`
+ *  once a child of the release an install put there answers for it (lib/mcp.mjs), at or after that install. */
+function moved(stale) {
+  const home = process.env.SUPERCODE_HOME || (process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, 'supercode') : join(homedir(), '.config', 'supercode'));
+  return stale.filter((row) => {
+    let said = null;
+    try { said = JSON.parse(readFileSync(join(home, 'run', 'mcp', String(row.pid)), 'utf8')); } catch { return true; }
+    return !(said?.pid === row.pid && Date.parse(said.at) >= Date.parse(row.installedAt));
+  });
 }
 
 /**

package/lib/features.mjs

@@ -14,6 +14,7 @@ export const FEATURES = [
   { 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: 'recorded', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'every command supercode recorded outside itself (harness configs, hooks baked into live sessions), one of each program and verb run as its consumer runs it' },
+  { id: 'markers', barrier: 'none', platforms: ['darwin', 'linux'], reads: "terminal windows and tmux processes carrying a harness's child-session mark; Claude Code on a terminal with no file in its session registry (one ps)" },
   { id: 'drift', barrier: 'none', platforms: ['darwin', 'linux'], reads: 'running supercode processes whose install was replaced after they started (one ps)' },
   { 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" },

package/lib/markers.mjs

@@ -0,0 +1,59 @@
+// Harness marks where no session is (R75): a coding harness marks what its tools run (Claude Code's CLAUDECODE and
+// CLAUDE_CODE_CHILD_SESSION), and a terminal window or tmux process that carries the marks hands them to every shell a
+// person opens there. Claude Code started in such a shell takes itself for a nested session: it saves no transcript,
+// writes no file in its session registry, and supercode's mail cannot tell who it is. Twelve windows on
+// yuerans-macbook-pro carried the marks from 2026-10-07 to 10-09 and nothing read them. Two readings, one ps:
+// - every terminal app and tmux process whose own environment holds a child-session mark with a value;
+// - every Claude Code process on a terminal with no file in its session registry (`<claude home>/sessions/<pid>.json`).
+// Only names and pids are kept: an environment's values never leave this function.
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run, clockSeconds } from './run.mjs';
+
+/** The marks a harness takes itself for a nested session by: the terminal SDK's list, the one home of it. */
+export function childSessionMarkers() {
+  const file = createRequire(import.meta.url).resolve('@volter/supercode-terminal/harness-markers.json');
+  return JSON.parse(readFileSync(file, 'utf8')).child_session;
+}
+
+const TERMINALS = new Set(['wezterm-gui', 'wezterm', 'kitty', 'ghostty', 'alacritty', 'iTerm2', 'Terminal', 'xterm', 'tmux']);
+const CLAUDE = new Set(['claude', 'claude.exe']);
+const program = (command) => (command.split(/\s+/u)[0] ?? '').split('/').pop();
+
+/** One process's environment as [name, value] pairs: Linux's own file for it; on macOS `ps -E` printed it after the command. */
+function environmentOf(pid, printed) {
+  if (process.platform === 'linux') {
+    try { return readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0').map((entry) => entry.split(/=(.*)/su)); } catch { return []; }
+  }
+  return [...printed.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=(\S*)/gu)].map((match) => [match[1], match[2]]);
+}
+
+/**
+ * { marked: [{ pid, program, markers }], unregistered: [{ pid, tty, ageSec, registry }] }. `minAgeSec` leaves a Claude
+ * Code process time to write its registry file.
+ */
+export async function harnessMarks({ markers = childSessionMarkers(), minAgeSec = 120, ps = null } = {}) {
+  const listed = ps ?? await run('/bin/ps', [process.platform === 'linux' ? '-axww' : '-axEww', '-o', 'pid=,tty=,etime=,command='], { timeoutMs: 10_000 });
+  if (!listed.ok) throw new Error(`ps: ${listed.error}`);
+  const marked = [], unregistered = [];
+  for (const line of listed.stdout.split('\n')) {
+    const row = /^\s*(\d+)\s+(\S+)\s+(\S+)\s+(.*)$/u.exec(line);
+    if (!row) continue;
+    const [, pid, tty, etime, command] = row, name = program(command);
+    if (!TERMINALS.has(name) && !CLAUDE.has(name)) continue;
+    const environment = new Map(environmentOf(pid, command));
+    if (TERMINALS.has(name)) {
+      const carried = markers.filter((marker) => environment.get(marker));
+      if (carried.length) marked.push({ pid: Number(pid), program: name, markers: carried });
+      continue;
+    }
+    // a Claude Code process with no terminal is a tool's own child (a subagent, a print run): nobody resumes or mails it
+    if (/^\?+$|^-$/u.test(tty) || clockSeconds(etime) < minAgeSec) continue;
+    const home = environment.get('CLAUDE_CONFIG_DIR') || join(environment.get('HOME') || homedir(), '.claude');
+    const registry = join(home, 'sessions', `${pid}.json`);
+    if (!existsSync(registry)) unregistered.push({ pid: Number(pid), tty, ageSec: clockSeconds(etime), registry });
+  }
+  return { marked, unregistered };
+}

package/lib/probe.mjs

@@ -51,6 +51,9 @@ export class Probe {
     this.f = healthFiles(dir);
     this.machine = machineName(machine || env.SUPERCODE_HEALTH_MACHINE || hostname());
     this.state = {};
+    // what the last mail said of each alarm (key → its level, summary, detail): a mail says what changed since, never each
+    // flip in between (t_be880329: disk and memory flapping mailed the maintainer ~1,200 times a day on yuerans)
+    this.said = new Map(); this.changesMailAt = 0; this.raisedLastAt = new Map(); // key → when it was last seen raised
     this.unknowns = {}; this.unknownMailAt = {}; // unknownMailAt: a kind of unknown (unknownKind: its key's prefix) → last mailed
     this.lastHistory = 0;
     this.sampleMs = null;
@@ -99,6 +102,7 @@ export class Probe {
     // A raised alarm whose reading was unknown keeps its unknown since across the restart, as its unknowns entry does.
     for (const a of (previous?.alarms ?? []).filter((x) => !x.detail?.pid || alive(x.detail.pid))) this.state[a.key] = { key: a.key, family: a.family, level: a.level, warnSince: null, critSince: null, raisedAt: a.since ? Date.parse(a.since) : Date.now(), lastMailAt: this.droppedOutbox ? 0 : Date.now(), restoredUntil: Date.now() + 2 * 60_000, value: a.value, unit: a.unit, summary: a.summary, detail: a.detail,
       ...(a.unknown?.since ? { unread: a.unknown.why, unreadAt: Date.parse(a.unknown.since) } : {}) };
+    for (const a of (previous?.alarms ?? [])) this.said.set(a.key, { level: a.level, summary: a.summary, detail: a.detail ?? null });
   }
 
   /** Remove an earlier pack's outbox; answers how many mails it held, logged by recipient. */
@@ -138,7 +142,26 @@ export class Probe {
     const repeatMs = this.config.repeatMin * 60_000;
     // A raised alarm is reminded each repeatMin after it was last said: in a mail of its own transition or reminder, never
     // pushed back by a mail about something else.
-    const raisedNow = new Set(transitions.filter((t) => t.to !== 'none').map((t) => t.key));
+    // What changed since the last mail said it (net of every raise and clear between): said at most once each quietMin,
+    // a new crit at once, and with any mail going anyway (a reminder, an unknown due). A key that raised and cleared
+    // between two mails is never said.
+    const quietMs = (this.config.quietMin ?? 15) * 60_000;
+    const levels = new Map(alarms.map((a) => [a.key, a]));
+    const lastTransition = new Map(transitions.map((t) => [t.key, t]));
+    const net = [];
+    for (const a of alarms) {
+      const was = this.said.get(a.key)?.level ?? 'none';
+      if (was !== a.level) net.push({ key: a.key, from: was, to: a.level, value: a.value, unit: a.unit ?? null, summary: a.summary, detail: a.detail ?? null });
+    }
+    for (const a of alarms) this.raisedLastAt.set(a.key, now);
+    for (const [key, was] of this.said) {
+      if (levels.has(key)) continue;
+      // a clear is said once it has held a whole quiet window: an alarm that flaps is said raised once, never each clear
+      if (now - (this.raisedLastAt.get(key) ?? 0) < quietMs) continue;
+      const t = lastTransition.get(key);
+      net.push({ key, from: was.level, to: 'none', value: null, summary: t?.to === 'none' ? t.summary : `${was.summary} — cleared`, detail: t?.detail ?? was.detail });
+    }
+    const raisedNow = new Set(net.filter((t) => t.to !== 'none').map((t) => t.key));
     const reminders = alarms.filter((a) => !raisedNow.has(a.key) && now - (this.state[a.key].lastMailAt ?? 0) >= repeatMs);
     // A reading unknown for unknownMin is the maintainers' to know (raised or not), and again each repeatMin until read.
     // Timed per kind (a key's prefix; a family's whole key): a kind is due once its earliest key has been unknown
@@ -159,14 +182,25 @@ export class Probe {
     const to = subscribers(this.f, this.config);
     // after dropping an earlier pack's undelivered mail, the first mail states the whole current state, clears included
     const composedState = Boolean(this.droppedOutbox && to.length);
-    const mail = composedState ? composeState({ machine: this.machine, raised: alarms }) : compose({ machine: this.machine, transitions, reminders, raised: alarms, unknowns: unknownsDue });
+    const changesDue = net.length > 0 && (now - this.changesMailAt >= quietMs || net.some((t) => t.to === 'crit' && t.from !== 'crit') || reminders.length > 0 || unknownsDue.length > 0);
+    const changes = changesDue ? net : [];
+    const mail = composedState ? composeState({ machine: this.machine, raised: alarms }) : compose({ machine: this.machine, transitions: changes, reminders: reminders.filter((a) => !changes.some((t) => t.key === a.key)), raised: alarms, unknowns: unknownsDue });
     if (composedState) this.droppedOutbox = 0;
     if (mail) {
       // the kinds of unknown this mail said (the whole-state mail says none: they stay due)
       if (!composedState) for (const [kind] of dueKinds) this.unknownMailAt[kind] = now;
       // only the alarms this mail said: raised by it, or reminded (the whole-state mail says every one)
-      const said = composedState ? alarms : alarms.filter((a) => raisedNow.has(a.key) || reminders.includes(a));
+      const said = composedState ? alarms : alarms.filter((a) => (changes.length && raisedNow.has(a.key)) || reminders.includes(a));
       for (const a of said) this.state[a.key].lastMailAt = now;
+      // the state this mail said is what the next mail is measured from: the whole state, or the last one said with this
+      // mail's changes applied. A clear still in its hold was not said, so its alarm stays said raised until a mail
+      // says the clear (#1268 review P1: replacing it with the alarms raised now lost that clear for good)
+      if (composedState) this.said = new Map(alarms.map((a) => [a.key, { level: a.level, summary: a.summary, detail: a.detail ?? null }]));
+      else for (const t of changes) {
+        if (t.to === 'none') this.said.delete(t.key);
+        else this.said.set(t.key, { level: t.to, summary: t.summary, detail: t.detail ?? null });
+      }
+      if (composedState || changes.length) this.changesMailAt = now;
       this.log(`${mail.subject}${to.length ? '' : ' (no maintainer subscribed)'}\n${mail.body}`);
     }
     const snapshot = {

package/lib/sample.mjs

@@ -9,6 +9,7 @@ import { expiredFailures, failureSummary, keyFor, Ledger, runningRelease, sayOnC
 import { healthDir } from './paths.mjs';
 import { pinnedHomes, staleSupercode } from './drift.mjs';
 import { brokenRecorded } from './recorded.mjs';
+import { harnessMarks } from './markers.mjs';
 import { join } from 'node:path';
 
 const MB = 1024 * 1024;
@@ -408,6 +409,17 @@ export class Sampler {
       slow.readings.recorded = broken;
       for (const b of broken) slow.observations.push({ key: `recorded.broken:${b.shape}`, family: 'recorded', def: alarm('recorded.broken'), value: b.count, met: { warn: true, crit: true, clears: false }, summary: `${b.count} recorded command(s) cannot run (${b.where.slice(0, 3).join(', ')}): ${b.error}; ${b.command.slice(0, 120)}`, detail: b });
     });
+    if (on.has('markers')) await attempt('markers', async () => {
+      const def = alarm('harness.unregistered');
+      const { marked, unregistered } = await harnessMarks({ minAgeSec: def.minAgeSec });
+      slow.families.add('marked'); slow.families.add('unregistered');
+      // every marked window and unregistered session this pass found; one no longer found is cleared
+      slow.observations.push({ enumerated: 'marked', family: 'marked', by: 'suffix', entities: new Set(marked.map((m) => String(m.pid))) });
+      slow.observations.push({ enumerated: 'unregistered', family: 'unregistered', by: 'suffix', entities: new Set(unregistered.map((u) => String(u.pid))) });
+      slow.readings.markers = { marked, unregistered };
+      for (const m of marked) slow.observations.push({ key: `harness.marked:${m.pid}`, family: 'marked', def: alarm('harness.marked'), value: 1, met: { warn: true, crit: true, clears: false }, summary: `${m.program} ${m.pid} carries a harness's child-session mark (${m.markers.join(', ')}): Claude Code started in any shell it opens saves no transcript and gets no mail; replace that window`, detail: m });
+      for (const u of unregistered) slow.observations.push({ key: `harness.unregistered:${u.pid}`, family: 'unregistered', def, value: 1, met: { warn: true, crit: true, clears: false }, summary: `Claude Code ${u.pid} on ${u.tty} has no ${u.registry}: it saves nothing and no mail reaches it`, detail: u });
+    });
     if (on.has('services')) await attempt('services', async () => {
       const list = cfg.services ?? [];
       const jobs = await this.reader.services(list.map((s) => s.label));

package/lib/thresholds.mjs

@@ -5,6 +5,7 @@ export const DEFAULTS = {
   slowIntervalSec: 60,      // disk space, services, the connector, tabs
   footprintTopEverySec: 300, // macOS: every user's largest footprints through top (about 2 s of top per run)
   repeatMin: 60,            // a raised alarm mails again this often (netdata's repeat cap)
+  quietMin: 15,             // what changed is mailed at most this often (a new crit at once): a flapping alarm is no stream
   unknownMin: 15,           // a reading unknown this long (raised or not) is mailed to the maintainers, and again each repeatMin
   historyHours: 24,
   daemons: {
@@ -38,6 +39,10 @@ export const DEFAULTS = {
     'release.pinned': { forSec: 300 },
     // a recorded command that cannot run fails its harness on every use (a hook on every tool call): said at once
     'recorded.broken': { forSec: 0 },
+    // a window whose shells start Claude Code as a nested session, and a session that saves nothing: said at once (a
+    // Claude Code process is read only once it has run minAgeSec, the time it has to write its registry file)
+    'harness.marked': { forSec: 0 },
+    'harness.unregistered': { forSec: 0, minAgeSec: 120 },
     'supercode.connector': { forSec: 60 },
     'supercode.launch': { stuckMin: 5, failedWithinMin: 30 },
     // one failure that keeps happening (the same command or door with the same outcome, the same mail expiry) in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-health",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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,7 +10,8 @@
     "./format": "./lib/format.mjs",
     "./paths": "./lib/paths.mjs",
     "./drift": "./lib/drift.mjs",
-    "./recorded": "./lib/recorded.mjs"
+    "./recorded": "./lib/recorded.mjs",
+    "./markers": "./lib/markers.mjs"
   },
   "bin": {
     "supercode-health": "./bin/health.mjs"