@volter/supercode-health 0.1.15 → 0.1.16

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/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

@@ -39,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.15",
+  "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"