@volter/supercode-health 0.1.17 → 0.1.18

package/bin/health.mjs

@@ -7,6 +7,8 @@
 //   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
+//   promises [--json] [--last]  the core promises (promises.json) read now, each with its time and the pass's total;
+//                               --last prints the probe's last pass instead. Exits 1 when one is false.
 //   subscribe <address> | unsubscribe <address>   alarm mail for an agent (sc:<machine>:agent:<name>), session or board
 //   config                      where the config lives and what it currently resolves to
 import { readFileSync } from 'node:fs';
@@ -15,7 +17,7 @@ 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 { values, positionals } = parseArgs({ allowPositionals: true, options: { last: { type: 'boolean' }, json: { type: 'boolean' }, all: { type: 'boolean' }, machine: { type: 'string' }, help: { type: 'boolean' } } });
 const verb = positionals[0] ?? 'status';
 const dir = healthDir();
 const f = files(dir);
@@ -60,12 +62,17 @@ if (values.help || verb === 'help') {
 } 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 === 'promises') {
+  const { readPromises, formatPromises } = await import('../lib/promises.mjs');
+  const pass = values.last ? latest()?.readings?.promises ?? null : await readPromises({ config: loadConfig(f.config), machine: values.machine });
+  print(pass, formatPromises(pass));
+  if (!pass) process.exitCode = 4; else if (pass.items.some((item) => item.state === 'false')) process.exitCode = 1;
 } 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.stderr.write(`supercode-health: unknown verb ${verb} (run, once, status, features, alarms, promises, subscribe, unsubscribe, config)\n`);
   process.exit(2);
 }

package/index.mjs

@@ -4,3 +4,4 @@ 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';
+export { readPromises, lastPromises, comparePromises, promiseList, formatPromises } from './lib/promises.mjs';

package/lib/features.mjs

@@ -18,6 +18,7 @@ export const FEATURES = [
   { 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" },
+  { id: 'promises', barrier: 'integration:machine-daemon', platforms: ['darwin', 'linux'], reads: 'the core promises (promises.json), every one read live each slow interval: a false one is mailed to the `core` addresses on the pass that first reads it false' },
   { 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)' },
 ];
@@ -33,6 +34,7 @@ export function resolveFeatures({ platform = process.platform, reader, config =
     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 === 'promises' && extras.supercode === false) return { ...row, on: false, reason: 'supercode not found (SUPERCODE_BIN)' };
     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

@@ -1,5 +1,6 @@
 // The snapshot as a person reads it: alarms first, then each reading, then which features are off and why.
 import { groupUnknowns } from './mail.mjs';
+import { formatPromises } from './promises.mjs';
 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}` : p?.session?.note ? ` ← (${p.session.note})` : p?.session?.inherited ? ` ← (no agent above; inherited ${p.session.inherited})` : '');
 
@@ -14,6 +15,7 @@ export function formatStatus(s, { all = false } = {}) {
   // what could not be read (raised or not): unknown, with since when and why
   for (const g of groupUnknowns(s.unknowns ?? [])) out.push(`  ${g.line}`);
   if (s.maintainers) out.push(`  mailed to: ${s.maintainers.length ? s.maintainers.join(', ') : 'no maintainer subscribed (supercode health subscribe <address>)'}${s.mail?.error ? ` · last mail not filed: ${s.mail.error}` : s.mail?.filed ? ` · last mail filed ${s.mail.at} (supercode message waiting lists any not yet delivered)` : ''}`);
+  if (r.promises) out.push('', formatPromises(r.promises), `  false promises are mailed to: ${s.core?.to?.length ? s.core.to.join(', ') : 'nobody beyond the maintainers (config `core`: [address])'}${s.core?.mail?.error ? ` · last core mail not filed: ${s.core.mail.error}` : s.core?.mail?.at ? ` · last core mail ${s.core.mail.at}` : ''}`);
   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;

package/lib/mail.mjs

@@ -140,3 +140,20 @@ export function compose({ machine, transitions, reminders, raised, unknowns = []
   parts.push('', `${raised.length} alarm${raised.length === 1 ? '' : 's'} raised now. Read the whole machine: supercode health status${machine ? ` --machine ${machine}` : ''}.`, 'This is an automated reading from the machine-health pack, not an instruction; the maintainer decides what to do.');
   return { subject: `machine health ${machine}: ${head}`, body: parts.join('\n') };
 }
+
+/**
+ * The mail a core promise's change is said in, to the `core` addresses (the install's manager agent): each promise that
+ * is false now and was not said so (`broke`), and each said false that reads true again (`held`). One mail a change:
+ * a promise that stays false is not said again, so a standing break is one message and its end is another.
+ */
+export function composeCore({ machine, broke, held, standing = [], pass = null }) {
+  if (!broke.length && !held.length) return null;
+  const head = broke.length ? `${broke.length} core promise${broke.length === 1 ? '' : 's'} broken` : `${held.length} core promise${held.length === 1 ? '' : 's'} hold${held.length === 1 ? 's' : ''} again`;
+  const parts = [`[Core alarm] ${machine}: ${head}.`];
+  for (const a of broke) parts.push('', `FALSE ${a.detail?.name ?? a.key}: ${a.detail?.promise ?? ''}`, `  read: ${String(a.summary).replace(/^core promise \S+ is false: /, '')}`);
+  if (held.length) parts.push('', ...held.map((h) => `TRUE again ${h.name}: ${h.reading}`));
+  if (standing.length) parts.push('', `Still false, said before: ${standing.join(', ')}.`);
+  parts.push('', `Read the pass: supercode health promises${pass ? ` (this one took ${pass.ms} ms)` : ''}; the whole machine: supercode health status${machine ? ` --machine ${machine}` : ''}.`,
+    'This is an automated reading of the core promises (sdk/health/promises.json), not an instruction. It is said once when a promise breaks and once when it holds again.');
+  return { subject: `core alarm ${machine}: ${head}`, body: parts.join('\n') };
+}

package/lib/probe.mjs

@@ -8,7 +8,7 @@ import { healthDir, files as healthFiles, machineName } from './paths.mjs';
 import { DEFAULTS, merge, judge, raised } from './thresholds.mjs';
 import { resolveFeatures } from './features.mjs';
 import { Sampler } from './sample.mjs';
-import { fileAlarm, compose, composeState, unknownKind } from './mail.mjs';
+import { fileAlarm, compose, composeState, composeCore, unknownKind } from './mail.mjs';
 import { run } from './run.mjs';
 
 export async function platformReader(platform = process.platform) {
@@ -55,6 +55,9 @@ export class Probe {
     // 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
+    // the core promises said false to the `core` addresses (key → name): a promise is said when it breaks and when it
+    // holds again, never while it stays as it was said
+    this.coreSaid = new Map(); this.lastCoreMail = null;
     this.lastHistory = 0;
     this.sampleMs = null;
   }
@@ -103,6 +106,8 @@ export class Probe {
     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 });
+    for (const [key, name] of Object.entries(previous?.core?.said ?? {})) this.coreSaid.set(key, name);
+    this.lastCoreMail = previous?.core?.mail ?? null;
   }
 
   /** Remove an earlier pack's outbox; answers how many mails it held, logged by recipient. */
@@ -203,6 +208,17 @@ export class Probe {
       if (composedState || changes.length) this.changesMailAt = now;
       this.log(`${mail.subject}${to.length ? '' : ' (no maintainer subscribed)'}\n${mail.body}`);
     }
+    // A core promise read false is the install's manager's to know at once (config `core`), beside the maintainers'
+    // mail above: said on the cycle its alarm raises (its pass's own reading: no window), and once more when it reads
+    // true again. A promise held unknown stays raised and is not said to hold.
+    const core = [...new Set(this.config.core ?? [])];
+    const falseNow = alarms.filter((a) => a.family === 'promise');
+    const falseKeys = new Set(falseNow.map((a) => a.key));
+    const broke = falseNow.filter((a) => !this.coreSaid.has(a.key));
+    const pass = readings.promises ?? null;
+    const held = [...this.coreSaid].filter(([key]) => !falseKeys.has(key)).map(([key, name]) => ({ key, name, reading: pass?.items?.find((item) => item.name === name)?.reading ?? 'its alarm cleared' }));
+    const coreMail = core.length ? composeCore({ machine: this.machine, broke, held, standing: falseNow.filter((a) => this.coreSaid.has(a.key)).map((a) => a.detail?.name ?? a.key), pass }) : null;
+    if (!core.length && (broke.length || held.length) && !this.coreUnsaid) { this.coreUnsaid = true; this.log(`${broke.length} core promise(s) false and no \`core\` address is configured: said to the maintainers only`); }
     const snapshot = {
       version: 1, machine: this.machine, platform: this.platform, at: new Date(now).toISOString(),
       probe: { pid: process.pid, intervalSec: this.config.intervalSec, slowIntervalSec: this.config.slowIntervalSec, sampleMs: this.sampleMs, user: this.env.USER ?? null, root: this.reader.isRoot?.() ?? false, config: this.config.source },
@@ -213,6 +229,7 @@ export class Probe {
       transitions: transitions.map((t) => ({ key: t.key, from: t.from, to: t.to, summary: t.summary })),
       maintainers: to,
       mail: this.lastMail ?? null,
+      core: { to: core, said: Object.fromEntries(this.coreSaid), mail: this.lastCoreMail },
       readings,
     };
     // The reading is written first; the mail is filed after it, and what the filing did is written beside it.
@@ -224,6 +241,18 @@ export class Probe {
       snapshot.mail = this.lastMail;
       writeAtomic(this.f.latest, snapshot);
     }
+    if (coreMail) {
+      const result = await fileAlarm({ machine: this.machine, env: this.env, to: core, key: `core-${this.machine}-${now}`, subject: coreMail.subject, body: coreMail.body });
+      this.lastCoreMail = { at: new Date(now).toISOString(), filed: result.filed.length, to: result.filed.map((f) => f.to), error: result.error, ms: Date.now() - now };
+      // said once it is filed for someone: a mail that could not be filed is tried again on the next cycle
+      if (result.filed.length) {
+        for (const a of broke) this.coreSaid.set(a.key, a.detail?.name ?? a.key);
+        for (const h of held) this.coreSaid.delete(h.key);
+      }
+      this.log(`${coreMail.subject}${result.error ? ` (${result.error})` : ''}\n${coreMail.body}`);
+      snapshot.core = { to: core, said: Object.fromEntries(this.coreSaid), mail: this.lastCoreMail };
+      writeAtomic(this.f.latest, snapshot);
+    }
     if (now - this.lastHistory >= 60_000) { this.#history(snapshot, now); this.lastHistory = now; }
     return snapshot;
   }

package/lib/promises.mjs

@@ -0,0 +1,274 @@
+// The core promises, read live (promises.json is the list). One pass reads every promise at once, each inside its own
+// hard bound, and says of each `true`, `false` or `unknown` with the reading behind it and the milliseconds it took.
+// A pass changes nothing: it reads files, this machine's daemon socket, two process listings, the server's machine
+// list and the installed release's own restart check. Where another program has to be started the reason is beside
+// it; nothing here starts a shell to read what a file or a socket answers. No reading carries an environment's values,
+// a credential or a message's text.
+//
+// Why a pass and not only alarms: each of 2026-10-09's later breaks was one of these promises false on a live machine
+// for hours (the server listing a linked machine offline, a restart refused for a day, two Codex installs, a disk at
+// zero) and readable there the whole time. The probe (probe.mjs) runs the pass every slow interval and mails a false
+// promise to the `core` addresses on the pass that first reads it false; a release's activation watch runs the same
+// pass once the new daemon serves and compares it with the last pass before it.
+import { readFileSync, realpathSync, statfsSync, statSync, accessSync, constants } from 'node:fs';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { run } from './run.mjs';
+import { daemonCall } from './mail.mjs';
+import { healthDir, machineName } from './paths.mjs';
+import { staleSupercode } from './drift.mjs';
+import { harnessMarks } from './markers.mjs';
+
+const json = (file) => { try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; } };
+const supercodeHome = (env) => env.SUPERCODE_HOME || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode');
+const teamsHome = (env) => env.SUPERCODE_TEAMS_HOME ?? join(supercodeHome(env), 'teams');
+const ago = (ms) => (ms < 90_000 ? `${Math.round(ms / 1000)} s` : ms < 5_400_000 ? `${Math.round(ms / 60_000)} min` : `${Math.round(ms / 360_000) / 10} h`);
+const yes = (reading, detail) => ({ state: 'true', reading, ...(detail ? { detail } : {}) });
+const no = (reading, detail) => ({ state: 'false', reading, ...(detail ? { detail } : {}) });
+const unknown = (reading) => ({ state: 'unknown', reading });
+
+/** The list: `{ version, promises: [{ name, promise, probe, bound_ms, activation }] }`. */
+export function promiseList() {
+  return JSON.parse(readFileSync(new URL('../promises.json', import.meta.url), 'utf8'));
+}
+
+/** What the pass's lines are set by; a machine's config overrides any (`promises.<name>`). */
+export const PROMISE_DEFAULTS = Object.freeze({
+  mailExpiryMin: 15,       // mail that expired undelivered this recently says delivery is failing now
+  staleReleaseHours: 2,    // extrapolated: a service restarts with its install; two hours is past any restart in hand
+  boardRoundMin: 10,       // extrapolated from a round's own length (about 30 s here) and the maintainer's 5 min line
+  diskFreeGB: 5,           // extrapolated: admission's copy of an 800 MB mailbox and an install both need room
+  fleetSeenHours: 24,      // a machine silent longer than this is taken to be off, not broken
+  harnesses: ['codex', 'claude'],
+});
+
+/** The server's machine list, asked once a pass and shared by the two promises that read it. The server alone can say
+ *  what it sees, and the credential that asks it stays inside the CLI: this is the pass's one call through `supercode`
+ *  beside the restart check. */
+function machineList(context) {
+  context.machines ??= run(context.bin, ['teams', 'machines', 'list', '--json'], { timeoutMs: 2800, env: context.env }).then((answer) => {
+    if (!answer.ok) throw new Error(`the server's machine list was not read: ${answer.error}`);
+    const body = JSON.parse(answer.stdout);
+    const items = body.items ?? body.data?.items;
+    if (!Array.isArray(items)) throw new Error('the server answered no machine list');
+    return items;
+  });
+  return context.machines;
+}
+
+/** Every `name` an absolute folder of `search` holds as an executable file, in order, one per real file. */
+function installs(name, search) {
+  const found = [], seen = new Set();
+  for (const folder of String(search ?? '').split(delimiter)) {
+    if (!folder || !isAbsolute(folder)) continue;
+    const candidate = join(folder, name);
+    try { if (!statSync(candidate).isFile()) continue; accessSync(candidate, constants.X_OK); } catch { continue; }
+    let real = candidate; try { real = realpathSync(candidate); } catch { /* as named */ }
+    if (seen.has(real)) continue;
+    seen.add(real); found.push(candidate);
+  }
+  return found;
+}
+
+const PROBES = {
+  async server(context) {
+    const items = await machineList(context);
+    const mine = items.filter((m) => m.enrollment === 'active' && machineName(m.name) === context.machine);
+    if (!mine.length) return unknown(`the server lists no active machine named ${context.machine}`);
+    const machine = mine.sort((a, b) => (b.last_seen_at ?? 0) - (a.last_seen_at ?? 0))[0];
+    const heard = machine.last_seen_at == null ? 'never heard from' : `last heard ${ago(context.now - machine.last_seen_at)} ago`;
+    const detail = { connection: machine.connection, last_seen_at: machine.last_seen_at ?? null, revision: machine.revision ?? null };
+    return machine.connection === 'online' ? yes(`the server lists ${context.machine} online, ${heard}`, detail)
+      : no(`the server lists ${context.machine} ${machine.connection}, ${heard}`, detail);
+  },
+
+  async fleet(context) {
+    const items = await machineList(context);
+    const window = context.lines.fleetSeenHours * 3_600_000;
+    const peers = items.filter((m) => m.enrollment === 'active' && machineName(m.name) !== context.machine && m.last_seen_at != null && context.now - m.last_seen_at <= window);
+    const down = peers.filter((m) => m.connection !== 'online');
+    const detail = { peers: peers.length, down: down.map((m) => ({ name: m.name, connection: m.connection, last_seen_at: m.last_seen_at })) };
+    return down.length ? no(`${down.length} of ${peers.length} machine(s) heard from in the last ${context.lines.fleetSeenHours} h are not online: ${down.map((m) => `${m.name} (${m.connection}, last heard ${ago(context.now - m.last_seen_at)} ago)`).join(', ')}`, detail)
+      : yes(`${peers.length} other machine(s) heard from in the last ${context.lines.fleetSeenHours} h, all online`, detail);
+  },
+
+  // The installed release's own check, as its restart would run it: the code that decides is the teams package's, and
+  // this pack depends on nothing, so it is asked through the release's CLI (one node start, no shell).
+  async restart(context) {
+    const answer = await run(context.bin, ['teams', 'mail', 'restart-check', '--json'], { timeoutMs: 2800, env: context.env });
+    let receipt = null; try { receipt = JSON.parse(answer.stdout); } catch { /* no receipt */ }
+    if (receipt?.stage !== 'restart_standing') return unknown(`the restart check gave no receipt: ${(answer.error || answer.stderr || 'no output').trim().split('\n')[0].slice(0, 200)}`);
+    return receipt.admitted ? yes(`no standing refusal (${receipt.checks?.legacy_wrappers?.live ?? 0} pane wrapper(s) read; the mailbox import itself is not run)`, receipt.checks)
+      : no(`a restart would be refused: ${receipt.refusals.join('; ')}`, receipt.checks);
+  },
+
+  async mail(context) {
+    const record = json(join(teamsHome(context.env), 'machine.json'));
+    if (!record?.pid) return no('no machine daemon has a record on this machine');
+    const answer = await daemonCall('harness.v1.mail.expired', {}, { env: context.env, timeoutMs: 1300 });
+    if (!Array.isArray(answer?.rows)) return no('the daemon answered its mail door with no list of expiries');
+    if (record.mail_ready !== true) return no(`the daemon (pid ${record.pid}) answers and does not serve mail`);
+    const since = context.now - context.lines.mailExpiryMin * 60_000;
+    const recent = answer.rows.filter((row) => Number(row?.expired_at_ms) >= since);
+    const reasons = [...new Set(recent.map((row) => String(row.reason ?? 'no reason given').slice(0, 80)))];
+    const detail = { pid: record.pid, expired_recently: recent.length, reasons };
+    return recent.length ? no(`${recent.length} mail(s) expired undelivered in the last ${context.lines.mailExpiryMin} min (${reasons.join(', ')})`, detail)
+      : yes(`the daemon (pid ${record.pid}) serves mail; none expired undelivered in the last ${context.lines.mailExpiryMin} min`, detail);
+  },
+
+  // The login shell is started because only it can say its PATH (its profile builds it), and each install is asked its
+  // own version because only it knows: the two things a launch does. Codex's background server names its version in
+  // the folder it runs from, which is read from the process list.
+  async harness(context) {
+    const env = context.env;
+    const shell = env.SHELL?.trim() || (() => { try { return userInfo().shell; } catch { return null; } })() || '/bin/sh';
+    const asked = process.platform === 'win32' ? { ok: false } : await run(shell, ['-lc', 'printf "\\n<supercode-path>%s</supercode-path>\\n" "$PATH"'], { timeoutMs: 2000, env });
+    const login = /<supercode-path>([^\n]*)<\/supercode-path>/.exec(asked.stdout ?? '')?.[1]?.trim() ?? null;
+    const search = [...new Set([...String(login ?? '').split(delimiter), ...String(env.PATH ?? '').split(delimiter)].filter(Boolean))].join(delimiter);
+    const rows = [], disagreements = [];
+    await Promise.all(context.lines.harnesses.map(async (name) => {
+      const found = installs(name, search);
+      const versions = await Promise.all(found.map(async (program) => {
+        const said = await run(program, ['--version'], { timeoutMs: 1800, env });
+        return { program, version: said.ok ? said.stdout.trim().split('\n')[0].slice(0, 60) : 'version unreadable' };
+      }));
+      rows.push({ harness: name, installs: versions });
+      if (new Set(versions.map((v) => v.version)).size > 1) disagreements.push(`${name}: ${versions.map((v) => `${v.program} is ${v.version}`).join(', ')} (a launch runs the first)`);
+      if (name === 'codex' && versions.length) {
+        const launched = /(\d+\.\d+\.\d+\S*)/.exec(versions[0].version)?.[1] ?? null;
+        const listed = await run('/bin/ps', ['-axww', '-o', 'command='], { timeoutMs: 1500 });
+        const servers = new Set([...String(listed.stdout ?? '').matchAll(/\/app-server-daemon\/releases\/(\d+\.\d+\.\d+[^-/\s]*)-[^/\s]*\/bin\/codex\s+app-server/g)].map((m) => m[1]));
+        rows.push({ harness: 'codex background server', versions: [...servers] });
+        const other = [...servers].filter((version) => version !== launched);
+        if (launched && other.length) disagreements.push(`codex: its background server runs ${other.join(', ')} while a launch runs ${launched}`);
+      }
+    }));
+    if (login == null && process.platform !== 'win32') return unknown(`the login shell (${shell}) gave no PATH within 2 s`);
+    return disagreements.length ? no(disagreements.join('; '), rows)
+      : yes(rows.filter((r) => r.installs).map((r) => `${r.harness}: ${r.installs.length ? `${r.installs.length} install(s), ${r.installs[0].version}` : 'not installed'}`).join('; '), rows);
+  },
+
+  async marks() {
+    const { marked } = await harnessMarks({ ps: await run('/bin/ps', [process.platform === 'linux' ? '-axww' : '-axEww', '-o', 'pid=,tty=,etime=,command='], { timeoutMs: 1800 }) });
+    return marked.length ? no(`${marked.length} terminal process(es) carry a harness's child-session marks: ${marked.slice(0, 6).map((m) => `${m.program} ${m.pid} (${m.markers.join(', ')})`).join(', ')}`, marked)
+      : yes('no terminal window or tmux server carries a child-session mark');
+  },
+
+  async stale(context) {
+    const line = context.lines.staleReleaseHours * 3_600_000;
+    const stale = await staleSupercode();
+    const over = stale.filter((row) => context.now - Date.parse(row.installedAt) > line);
+    // what each runs, for the name: its program's last two path parts and its verb, never its arguments
+    const named = new Map();
+    for (const row of over) {
+      const words = row.command.split(/\s+/u), node = /(^|\/)node$/u.test(words[0]);
+      const program = (node ? words[1] : words[0]).split('/').slice(-2).join('/');
+      const verb = words.slice(node ? 2 : 1).filter((word) => /^[a-z][a-z-]*$/u.test(word)).slice(0, 2).join(' ');
+      const key = verb ? `${program} ${verb}` : program;
+      named.set(key, (named.get(key) ?? 0) + 1);
+    }
+    const detail = { stale: stale.length, over: over.length, by: Object.fromEntries(named), oldest_start: over.map((row) => row.startedAt).sort()[0] ?? null, pids: over.slice(0, 40).map((row) => row.pid) };
+    return over.length ? no(`${over.length} process(es) still run a release replaced more than ${context.lines.staleReleaseHours} h ago: ${[...named].sort((a, b) => b[1] - a[1]).map(([what, count]) => `${count} ${what}`).join(', ')}; the oldest started ${detail.oldest_start}`, detail)
+      : yes(stale.length ? `${stale.length} process(es) run a release replaced in the last ${context.lines.staleReleaseHours} h, none longer` : 'every supercode process runs the release on disk', detail);
+  },
+
+  async board(context) {
+    const held = json(join(supercodeHome(context.env), 'board-homes.json')) ?? {};
+    const line = context.lines.boardRoundMin * 60_000, rounds = [], broken = [];
+    for (const root of new Set(Object.values(held).filter((value) => typeof value === 'string'))) {
+      const beat = json(join(root, 'dispatcher-heartbeat.json'));
+      if (!beat?.at) continue; // no dispatcher has run a round in this home
+      const age = context.now - Date.parse(beat.at);
+      const failed = (beat.boards ?? []).reduce((sum, board) => sum + (Number(board.failed) || 0), 0), errors = (beat.errors ?? []).length;
+      rounds.push({ home: root, round: beat.round ?? null, at: beat.at, failed, errors });
+      if (!(age <= line)) broken.push(`${root}: its last round (${beat.round ?? '?'}) ended ${ago(age)} ago`);
+      else if (failed || errors) broken.push(`${root}: round ${beat.round ?? '?'} failed ${failed} and raised ${errors} error(s)`);
+    }
+    if (!rounds.length) return yes('no board dispatcher has run a round on this machine');
+    return broken.length ? no(broken.join('; '), rounds) : yes(rounds.map((r) => `${r.home}: round ${r.round ?? '?'} ${ago(context.now - Date.parse(r.at))} ago, failed 0`).join('; '), rounds);
+  },
+
+  async disk(context) {
+    const volumes = new Map();
+    for (const folder of [supercodeHome(context.env), homedir(), tmpdir()]) {
+      let stat; try { stat = statfsSync(folder); } catch { continue; }
+      // one volume is told from another by its size and free space together: folders on the same one read the same
+      const key = `${stat.blocks}:${stat.bsize}:${stat.bavail}`;
+      if (!volumes.has(key)) volumes.set(key, { folder, freeGB: Math.round((Number(stat.bavail) * Number(stat.bsize)) / 2 ** 30 * 10) / 10 });
+    }
+    if (!volumes.size) return unknown('no volume could be read');
+    const rows = [...volumes.values()], low = rows.filter((row) => row.freeGB <= context.lines.diskFreeGB);
+    return low.length ? no(low.map((row) => `the volume of ${row.folder} has ${row.freeGB} GB free (the line is ${context.lines.diskFreeGB} GB)`).join('; '), rows)
+      : yes(rows.map((row) => `${row.folder}: ${row.freeGB} GB free`).join('; '), rows);
+  },
+
+  async activation(context) {
+    const verdict = json(join(teamsHome(context.env), 'service', 'last-activation.json'));
+    if (!verdict?.state) return yes('no activation is recorded on this machine');
+    const release = verdict.candidate?.release ?? verdict.release ?? 'a release';
+    const at = verdict.at_ms ? new Date(verdict.at_ms).toISOString() : 'an unrecorded time';
+    if (['rolled_back', 'restore_failed', 'restarted'].includes(verdict.state)) {
+      return no(`${release} was ${verdict.state === 'rolled_back' ? `put back at ${at}; ${verdict.restored?.release ?? 'the release before'} serves` : verdict.state === 'restarted' ? `stopped and started again at ${at}` : `stopped at ${at} and nothing was restored`}: ${verdict.reason ?? verdict.detail ?? 'no reason recorded'}`,
+        { state: verdict.state, at_ms: verdict.at_ms ?? null, broken: verdict.promises?.broken ?? [] });
+    }
+    const broken = verdict.promises?.broken ?? [];
+    if (broken.length) return no(`${release} was kept at ${at} and broke ${broken.map((b) => b.name).join(', ')}: ${verdict.promises.kept_because ?? 'it was not put back'}`, { state: verdict.state, at_ms: verdict.at_ms ?? null, broken });
+    return yes(`${release} ${verdict.state} at ${at}`);
+  },
+};
+
+/**
+ * One pass: `{ version, at, machine, ms, items: [{ name, promise, state, reading, detail?, ms, bound_ms, activation }] }`.
+ * Every probe runs at once; one that has not answered inside its bound is `unknown` and says so, and the pass ends
+ * with the slowest probe. `only` reads some of the list by name.
+ */
+export async function readPromises({ env = process.env, config = {}, machine = null, only = null, now = Date.now() } = {}) {
+  const started = performance.now();
+  const context = { env, now, bin: env.SUPERCODE_BIN || 'supercode', machine: machineName(machine || env.SUPERCODE_HEALTH_MACHINE || undefined), lines: { ...PROMISE_DEFAULTS, ...(config.promises ?? {}) }, machines: null };
+  const list = promiseList().promises.filter((entry) => !only || only.includes(entry.name));
+  const items = await Promise.all(list.map(async (entry) => {
+    const t0 = performance.now();
+    let timer;
+    const bound = new Promise((resolve) => { timer = setTimeout(() => resolve(unknown(`not read within its ${entry.bound_ms} ms bound`)), entry.bound_ms); });
+    const probe = PROBES[entry.probe];
+    const read = probe ? Promise.resolve().then(() => probe(context)).catch((error) => unknown(`could not be read: ${String(error.message ?? error).split('\n')[0].slice(0, 240)}`))
+      : Promise.resolve(unknown(`this release has no probe named ${entry.probe}`));
+    const result = await Promise.race([read, bound]);
+    clearTimeout(timer);
+    return { name: entry.name, promise: entry.promise, ...result, ms: Math.round(performance.now() - t0), bound_ms: entry.bound_ms, activation: entry.activation };
+  }));
+  return { version: 1, at: new Date(now).toISOString(), machine: context.machine, ms: Math.round(performance.now() - started), items };
+}
+
+/** The last pass the probe wrote into its snapshot (`latest.json`), when it is no older than `maxAgeMs`; else null. */
+export function lastPromises({ env = process.env, maxAgeMs = 300_000, now = Date.now() } = {}) {
+  const pass = json(join(healthDir(env), 'latest.json'))?.readings?.promises;
+  return pass?.at && now - Date.parse(pass.at) <= maxAgeMs ? pass : null;
+}
+
+/**
+ * A pass against the one before it: `broken` are the promises true before and false now, `standing` false both times
+ * or false now with no true reading before, `unread` unknown now. With no pass before, nothing is `broken`.
+ */
+export function comparePromises(before, after) {
+  const was = new Map((before?.items ?? []).map((item) => [item.name, item.state]));
+  const broken = [], standing = [], unread = [];
+  for (const item of after?.items ?? []) {
+    const row = { name: item.name, activation: item.activation, reading: item.reading, before: was.get(item.name) ?? 'unread' };
+    if (item.state === 'unknown') unread.push(row);
+    else if (item.state === 'false') (row.before === 'true' ? broken : standing).push(row);
+  }
+  return { broken, standing, unread };
+}
+
+/** A pass as a person reads it: one line a promise, its state, its reading and its time, then the pass's total. */
+export function formatPromises(pass) {
+  if (!pass) return 'promises: no pass yet';
+  const width = Math.max(...pass.items.map((item) => item.name.length));
+  const lines = pass.items.map((item) => `  ${item.state === 'true' ? 'true   ' : item.state === 'false' ? 'FALSE  ' : 'unknown'} ${item.name.padEnd(width)}  ${String(item.ms).padStart(4)} ms  ${item.reading}`);
+  const count = (state) => pass.items.filter((item) => item.state === state).length;
+  return [`core promises · ${pass.machine} · ${pass.at} · ${count('false')} false, ${count('unknown')} unknown, ${count('true')} true · whole pass ${pass.ms} ms`, ...lines].join('\n');
+}
+
+export const promisesFile = fileURLToPath(new URL('../promises.json', import.meta.url));

package/lib/sample.mjs

@@ -10,6 +10,7 @@ import { healthDir } from './paths.mjs';
 import { pinnedHomes, staleSupercode } from './drift.mjs';
 import { brokenRecorded } from './recorded.mjs';
 import { harnessMarks } from './markers.mjs';
+import { readPromises } from './promises.mjs';
 import { join } from 'node:path';
 
 const MB = 1024 * 1024;
@@ -31,9 +32,9 @@ function argvSession(command) {
     ?? /\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' };
+const SLOW_FEATURE = { promises: 'promises', promise: 'promises', 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.
-const FAMILY_FEATURE = { load: 'load', memory: 'memory', process: 'processes', browser: 'renderers', daemon: 'daemons', 'disk-writer': 'disk-io', files: 'files', tcp: 'tcp', disk: 'disk', service: 'services', supercode: 'supercode', tabs: 'browser-tabs', power: 'power' };
+const FAMILY_FEATURE = { promise: 'promises', load: 'load', memory: 'memory', process: 'processes', browser: 'renderers', daemon: 'daemons', 'disk-writer': 'disk-io', files: 'files', tcp: 'tcp', disk: 'disk', service: 'services', supercode: 'supercode', tabs: 'browser-tabs', power: 'power' };
 // The families a feature's read observes: when its read fails, each is unread (judged neither raised nor cleared).
 // `processes` also observes the renderer, daemon and disk-writer families it reads beside its own; `disk-io`'s own read
 // (device throughput) judges no family: the disk writers are the process read's, so a throughput read that fails leaves
@@ -348,6 +349,9 @@ export class Sampler {
     const alarm = (name) => cfg.alarms[name];
     const attempt = async (id, fn) => { try { await fn(); } catch (error) { errors[id] = error.message; slow.observations.push(...unreadFamilies(id, error.message)); } };
 
+    // The core promises: their own pass, every probe at once (lib/promises.mjs), started first and joined last so
+    // nothing else in the slow set holds it back or is held by it. A false promise raises on this reading (no window).
+    const promised = on.has('promises') ? readPromises({ env: this.env, config: cfg, machine: this.machine, now }) : null;
     if (on.has('disk')) await attempt('disk', async () => {
       const def = alarm('disk.free');
       const fill = alarm('disk.filling');
@@ -447,6 +451,17 @@ export class Sampler {
       });
     });
 
+    if (promised) await attempt('promises', async () => {
+      const pass = await promised;
+      slow.families.add('promise');
+      slow.readings.promises = pass;
+      for (const item of pass.items) {
+        const key = `promise:${item.name}`;
+        if (item.state === 'unknown') slow.observations.push({ unreadKey: key, family: 'promise', why: item.reading });
+        else slow.observations.push({ key, family: 'promise', def: alarm('promise'), value: item.state === 'false' ? 1 : 0, met: { warn: item.state === 'false', crit: item.state === 'false', clears: item.state === 'true' },
+          summary: item.state === 'false' ? `core promise ${item.name} is false: ${item.reading}` : `core promise ${item.name} holds: ${item.reading}`, detail: { promise: item.promise, name: item.name } });
+      }
+    });
     if (on.has('supercode')) await attempt('supercode', async () => {
       const bin = this.env.SUPERCODE_BIN || 'supercode';
       slow.families.add('supercode');

package/lib/thresholds.mjs

@@ -8,6 +8,8 @@ export const DEFAULTS = {
   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,
+  core: [],                 // the addresses a false core promise is mailed to (the install's manager agent), beside the maintainers
+  promises: {},             // the promise pass's lines (lib/promises.mjs PROMISE_DEFAULTS), any of them overridden here
   daemons: {
     darwin: ['dasd', 'fseventsd', 'mds', 'mds_stores', 'mdworker_shared', 'WindowServer', 'kernel_task', 'backupd', 'softwareupdated', 'photoanalysisd', 'cloudd', 'bird', 'nsurlsessiond', 'trustd', 'syspolicyd', 'XprotectService', 'logd', 'runningboardd', 'launchservicesd', 'coreduetd', 'spotlightknowledged'],
     linux: ['systemd-journald', 'kswapd0', 'dockerd', 'containerd', 'snapd', 'packagekitd', 'tracker-miner-fs-3', 'baloo_file', 'updatedb'],
@@ -48,6 +50,8 @@ export const DEFAULTS = {
     // one failure that keeps happening (the same command or door with the same outcome, the same mail expiry) in the
     // window; it clears when the window holds none of it (t_b3844842)
     'supercode.failing': { warn: 3, crit: 20, clear: 0, windowMin: 60, forSec: 0 },
+    // a core promise read false (promises.json): said on the pass that first reads it so, to the maintainers and to `core`
+    'promise': { forSec: 0 },
     'browser.tabs': { warn: null },
     'power.thermal': { forSec: 60 },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-health",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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",
@@ -11,13 +11,15 @@
     "./paths": "./lib/paths.mjs",
     "./drift": "./lib/drift.mjs",
     "./recorded": "./lib/recorded.mjs",
-    "./markers": "./lib/markers.mjs"
+    "./markers": "./lib/markers.mjs",
+    "./promises": "./lib/promises.mjs"
   },
   "bin": {
     "supercode-health": "./bin/health.mjs"
   },
   "files": [
     "index.mjs",
+    "promises.json",
     "lib",
     "bin",
     "README.md"

package/promises.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "about": "The core promises: what every session on a machine stands on. One list, read in three places: at the push in the clean room (checks/system), at a release's activation on each machine (sdk/teams/bin/workspace/activation-watch.mjs: one that was true before and is false after puts the release back), and on every pass of the machine-health probe (a false one is mailed to the config's `core` addresses on the pass that first reads it false). `probe` names the reading in lib/promises.mjs; `bound_ms` is the most that reading may take before it is unknown; `activation` says what a break at activation does.",
+  "promises": [
+    { "name": "server-sees-machine", "probe": "server", "bound_ms": 3000, "activation": "rollback",
+      "promise": "The Teams server lists this machine online: it heard its heartbeat in the last 45 seconds over a held link." },
+    { "name": "restart-admitted", "probe": "restart", "bound_ms": 3000, "activation": "rollback",
+      "promise": "A restart of this machine's daemon would not be refused for state already standing here (the runtime, the pane wrappers, the Maildir against its retirement receipt)." },
+    { "name": "mail-serves", "probe": "mail", "bound_ms": 1500, "activation": "report",
+      "promise": "The daemon answers on its socket, serves mail, and no mail expired undelivered in the last 15 minutes." },
+    { "name": "harness-one-install", "probe": "harness", "bound_ms": 4000, "activation": "report",
+      "promise": "Each harness CLI on this machine (codex, claude) is one version wherever a launch could find it (the login shell's PATH, then the daemon's), and Codex's background server runs that version." },
+    { "name": "no-harness-marks", "probe": "marks", "bound_ms": 2000, "activation": "report",
+      "promise": "No terminal window or tmux server carries a harness's child-session marks, so a session a person starts in one is its own session." },
+    { "name": "no-stale-release", "probe": "stale", "bound_ms": 3000, "activation": "report",
+      "promise": "No supercode process has run a release for more than two hours after an install replaced it." },
+    { "name": "board-round", "probe": "board", "bound_ms": 500, "activation": "report",
+      "promise": "Where a board's dispatcher runs, its last round ended in the last ten minutes with nothing failed." },
+    { "name": "disk-free", "probe": "disk", "bound_ms": 500, "activation": "report",
+      "promise": "The volumes supercode's home, the person's home and the temporary folder are on each have more than 5 GB free." },
+    { "name": "release-kept", "probe": "activation", "bound_ms": 200, "activation": "report",
+      "promise": "The last release activated on this machine was kept: it was not put back, and it broke no promise that held before it." },
+    { "name": "fleet-online", "probe": "fleet", "bound_ms": 3000, "activation": "report",
+      "promise": "Every other machine enrolled with this server and heard from in the last 24 hours is online now." }
+  ]
+}