@volter/supercode-teams 0.3.1 → 0.3.3

package/bin/teams.mjs

@@ -20,6 +20,9 @@
 //   attention ls | rank | request <pane> [--urgency now|soon|whenever] [--reason text] | clear <pane>
 //   watch [--interval ms] [--for ms]
 //   launches get <key> | cancel <key> | list   operators: keyed receipts; cancel only unissued keys
+//   health [status|features|alarms] [--json] [--all]   the machine's vitals (the machine-health pack)
+//   health subscribe|unsubscribe <address>    operators: alarm mail for a session or board address
+//   health run | once | config                this machine only: the pack's own probe verbs
 //   rpc <harness.v1 method> [json-params]   operators: one harness.v1 request
 //   log verify
 //
@@ -28,6 +31,7 @@
 // CLI in ./workspace.mjs.
 import { createWriteStream, readFileSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SupercodeHarnessClient } from '@volter/supercode-harness-sdk';
 
 // A Windows scheduled task keeps no output (launchd and systemd name log files), so its unit names one here.
@@ -45,9 +49,9 @@ import { moveWorkspace } from '../workspace-move.mjs';
 import { teamsHome, paths, readJson, AccountLog, parseHostPort } from '@volter/teams/home';
 import { NODE_PROTOCOL } from '@volter/teams/channel';
 
-const MACHINE_VERBS = new Set(['machine', 'describe', 'panes', 'input', 'suspend', 'resume', 'files', 'ports', 'port', 'browser', 'stream', 'jobs', 'workspace', 'title', 'attention', 'watch', 'rpc', 'launches', 'log', 'mail']);
+const MACHINE_VERBS = new Set(['machine', 'describe', 'panes', 'input', 'suspend', 'resume', 'files', 'ports', 'port', 'browser', 'stream', 'jobs', 'workspace', 'title', 'attention', 'watch', 'rpc', 'launches', 'log', 'mail', 'health']);
 // Every flag a machine verb reads; any other is refused rather than silently ignored.
-const KNOWN_FLAGS = new Set(['home', 'machine', 'context', 'floor', 'supercode', 'tmux-socket', 'verbose', 'lines', 'input', 'name', 'for', 'urgency', 'reason', 'interrupt', 'query', 'out', 'in', 'interval', 'no-enter', 'when-composer-empty', 'key', 'listen', 'list', 'from', 'to', 'path', 'to-path', 'repo', 'branch', 'solo', 'card', 'create', 'presence-only', 'clear-draft', 'message-ids']);
+const KNOWN_FLAGS = new Set(['home', 'machine', 'context', 'floor', 'supercode', 'tmux-socket', 'verbose', 'lines', 'input', 'name', 'for', 'urgency', 'reason', 'interrupt', 'query', 'out', 'in', 'interval', 'no-enter', 'when-composer-empty', 'key', 'listen', 'list', 'from', 'to', 'path', 'to-path', 'repo', 'branch', 'solo', 'card', 'create', 'presence-only', 'clear-draft', 'message-ids', 'json', 'all']);
 
 const argv = process.argv.slice(2);
 const flags = {};
@@ -65,7 +69,7 @@ for (let i = 0; i < argv.length; i += 1) {
 }
 const [verb, sub, ...rest] = positional;
 
-const MACHINE_HELP = 'machine verbs: machine start|status, describe, panes, input, suspend, resume, files, ports, port, stream, jobs, workspace, title, attention, watch, rpc, launches, log, browser (add --machine NAME for an enrolled machine)';
+const MACHINE_HELP = 'machine verbs: machine start|status, describe, panes, input, suspend, resume, files, ports, port, stream, jobs, workspace, title, attention, watch, rpc, launches, log, health, browser (add --machine NAME for an enrolled machine)';
 
 if (verb === undefined || verb === 'help') {
   process.stdout.write(`supercode teams: ${MACHINE_HELP}\n`);
@@ -133,6 +137,15 @@ async function withNode(fn) {
   }
 }
 
+/** The machine-health pack's CLI: an explicit path, the installed package, else a source checkout's sibling. */
+async function healthPackEntry() {
+  const { existsSync } = await import('node:fs');
+  if (process.env.SUPERCODE_HEALTH_ENTRY) return existsSync(process.env.SUPERCODE_HEALTH_ENTRY) ? process.env.SUPERCODE_HEALTH_ENTRY : null;
+  try { const found = fileURLToPath(import.meta.resolve('@volter/supercode-health/bin')); if (existsSync(found)) return found; } catch { /* not installed */ }
+  const sibling = fileURLToPath(new URL('../../health/bin/health.mjs', import.meta.url));
+  return existsSync(sibling) ? sibling : null;
+}
+
 async function main() {
   switch (verb) {
     case 'machine': {
@@ -329,6 +342,34 @@ async function main() {
       die('launches get <key> | cancel <key> | list [--machine NAME]');
       return;
     }
+    case 'health': {
+      // This machine's vitals are read from the pack's own files, not through the daemon: the reading has to
+      // work when the daemon is what is sick. `--machine NAME` reads an enrolled machine through its doors.
+      const local = !flags.machine;
+      if (local || ['run', 'once', 'config'].includes(sub)) {
+        if (!local) die(`health ${sub} runs on the machine itself; read another machine with health status --machine NAME`);
+        const entry = await healthPackEntry();
+        if (!entry) die('the machine-health pack (@volter/supercode-health) is not installed; set SUPERCODE_HEALTH_ENTRY to its bin/health.mjs', 1);
+        const r = spawnSync(process.execPath, [entry, ...(sub ? [sub] : []), ...rest, ...(flags.json ? ['--json'] : []), ...(flags.all ? ['--all'] : [])], { stdio: 'inherit' });
+        process.exit(r.status ?? 1);
+      }
+      if (sub === 'subscribe' || sub === 'unsubscribe') {
+        if (!rest[0]) die(`health ${sub} <sc:machine:harness:id> --machine NAME`);
+        return withNode(async (rpc) => out(await rpc.call(`health.${sub}`, { address: rest[0] })));
+      }
+      if (sub && !['status', 'features', 'alarms'].includes(sub)) die('health [status|features|alarms] [--machine NAME] | health subscribe|unsubscribe <address> | health run|once|config');
+      return withNode(async (rpc) => {
+        const answer = await rpc.call('health.read', {});
+        const s = answer.snapshot;
+        const entry = await healthPackEntry();
+        const fmt = entry ? await import(new URL('../lib/format.mjs', pathToFileURL(entry)).href).catch(() => null) : null;
+        if (flags.json || !fmt) { out(sub === 'features' ? s?.features ?? null : sub === 'alarms' ? s?.alarms ?? null : answer); return; }
+        if (sub === 'features') { out(s ? fmt.formatFeatures(s.features) : 'no reading yet'); return; }
+        if (sub === 'alarms') { out(s?.alarms?.length ? s.alarms.map((a) => `${a.level.toUpperCase()} ${a.key}: ${a.summary} (since ${a.since})`).join('\n') : 'no alarms raised'); return; }
+        out(fmt.formatStatus(s, { all: Boolean(flags.all) }));
+        if (!answer.probe?.running) out(`probe: not run by that machine's daemon (${answer.probe?.reason ?? 'unknown'})`);
+      });
+    }
     case 'rpc': {
       const channel = await machineChannel();
       const client = new SupercodeHarnessClient({ transport: harnessTransport(channel) });

package/bin/workspace.mjs

@@ -485,6 +485,9 @@ async function sessionsCommand(sub, command) {
   if (sub === 'url') { only(flags, ['json', 'help', 'context']); requireArgs(rest, 1, 1, 'sessions url REF'); const descriptor = await session.descriptor(); return output({ version: 1, context: scope(context), data: { url: `${context.origin}/teams/${context.team_id}/sessions/${descriptor.data.id}` } }); }
   // A session view (RH2 ADR 0008): its owner lets a workplace Room's Conversation read this session with the tokens that
   // workplace signs. `bind` records it and prints what the workplace's own bind door takes; `unbind` removes it.
+  // The custodian's read of a session's view bindings, each with where a Room notice to it would be delivered now
+  // (ready, stopped and resumable, ended, unknown liveness, or unavailable with the failing predicate).
+  if (sub === 'bindings') { only(flags, ['json', 'help', 'context']); requireArgs(rest, 1, 1, 'sessions bindings REF'); return output(await command.client.request('GET', `${session.path}/view-bindings`)); }
   if (sub === 'bind' || sub === 'unbind') {
     only(flags, ['json', 'help', 'context', 'room', 'agent', 'conversation', 'rh2']); requireArgs(rest, 1, 1, `sessions ${sub} REF --room ROOM --agent PRINCIPAL --rh2 ORIGIN`);
     if (!flags.room || (!flags.agent && !flags.conversation) || (flags.agent && flags.conversation) || !flags.rh2) usage(`sessions ${sub} needs --room, --agent (or a legacy --conversation), and --rh2 (the workplace's origin)`);
@@ -994,6 +997,8 @@ async function connectorCommand(verb, { flags, rest, output, client, context, te
     const machineEvents = new MachineEvents({home:daemonHome,server:context.origin,teamId:context.team_id,credential:saved.credential.token,machineName:saved.machine.name,binary});
     const machine = new TeamsMachine({ home: daemonHome, supercode: binary, ...(flags.tmux_socket ? { tmuxSocket: String(flags.tmux_socket) } : {}), link: { server: context.origin, teamId: context.team_id, machineId: saved.machine.id, credential: saved.credential.token, incarnationId: connector.state.incarnation_id, configuration: () => connector.configuration() }, onTurn: (turn) => connector.noteTurn(turn), onTurnWithdrawn: (turn) => connector.withdrawTurn(turn) });
     machine.machineEvents = machineEvents;
+    // The machine-health probe mails as this enrolled machine (`sc:<machine>:operator:machine-health`).
+    machine.healthMachine = saved.machine.name;
     connector.closeAgentSession=async id=>{
       const channel=await openLocalMachine(paths(daemonHome).socket);
       try{const rpc=await nodeRpc(channel);return await rpc.call('harness.v1.agents.closeSession',{closure:id},{timeoutMs:60000});}

package/machine.mjs

@@ -35,7 +35,7 @@ import { Workspaces, inspectCheckout } from './workspaces.mjs';
 import { WorkspaceContexts, fromContext } from '@volter/teams/context';
 import { TeamsClient } from '@volter/teams/http-client';
 import { supercodeHome } from '@volter/teams/home';
-import { readMailHistory } from './mail-history.mjs';
+import { readMailHistory, machineName } from './mail-history.mjs';
 import { randomBytes, createHash } from 'node:crypto';
 import { WebSocket } from 'ws';
 import { TmuxTerminalHost, classifyAttentionSignal, composerHoldsDraft, composerReadyForInput } from '@volter/supercode-terminal';
@@ -259,10 +259,45 @@ export class TeamsMachine extends MachineCore {
 
   async afterListen() {
     this.#startMailWatch();
+    this.#startHealth();
     if(Object.keys(this.inputRepairs).length)this.#watchInputRepairs();
   }
 
+  // ---- the machine-health pack (docs/adr/0006-machine-health-pack.md) -------
+  // An enrolled machine runs the optional pack's probe as a child, so every connected machine is measured.
+  // The pack holds one probe per OS user (exit 3: another holds it; retried a minute later in case that one
+  // stops). SUPERCODE_HEALTH=0 turns it off. The probe only reads and mails; this daemon serves its readings.
+  #startHealth() {
+    this.healthStopped = false;
+    if (!this.link || (this.env.SUPERCODE_HEALTH ?? '1') === '0') { this.healthRun = { running: false, reason: this.link ? 'turned off (SUPERCODE_HEALTH=0)' : 'not an enrolled connector' }; return; }
+    const entry = healthEntry(this.env);
+    if (!entry) { this.healthRun = { running: false, reason: 'the machine-health pack (@volter/supercode-health) is not installed; set SUPERCODE_HEALTH_ENTRY to its bin/health.mjs' }; return; }
+    const start = () => {
+      if (this.healthStopped) return;
+      const child = spawn(process.execPath, [entry, 'run', ...(this.healthMachine ? ['--machine', this.healthMachine] : [])], { env: { ...this.env, SUPERCODE_BIN: this.supercodeBin }, stdio: 'ignore', windowsHide: true });
+      this.healthChild = child;
+      this.healthRun = { running: true, pid: child.pid, entry, since: Date.now() };
+      child.once('error', (error) => { this.healthRun = { running: false, reason: error.message, entry }; });
+      child.once('exit', (code, signal) => {
+        if (this.healthChild === child) this.healthChild = null;
+        if (this.healthStopped) return;
+        const held = code === 3;
+        this.healthBackoff = held ? 60_000 : Math.min(300_000, (this.healthBackoff ?? 2500) * 2);
+        this.healthRun = { running: false, reason: held ? 'another probe holds this user\'s pidfile' : `exited (${signal ?? code}); restarting`, entry, exitedAt: Date.now() };
+        this.healthTimer = setTimeout(start, this.healthBackoff); this.healthTimer.unref?.();
+      });
+    };
+    start();
+  }
+
+  #stopHealth() {
+    this.healthStopped = true;
+    clearTimeout(this.healthTimer);
+    this.healthChild?.kill('SIGTERM');
+  }
+
   async beforeClose() {
+    this.#stopHealth();
     clearInterval(this.terminalMailTimer); await this.terminalMailWork;
     clearInterval(this.inputRepairTimer);this.inputRepairTimer=null;
     await this.inputRepairWork;
@@ -520,7 +555,7 @@ export class TeamsMachine extends MachineCore {
   }
 
   #noticeTarget(address){
-    return sessionNoticeTarget(address,{machine:hostname().split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g,'-'),
+    return sessionNoticeTarget(address,{machine:machineName(this.env),
       mail:request=>this.#nativeMailReply(request),
       discover:params=>this.#serveRequest('harness.v1.sessions.discover',params,10000),
       recordedConfig:locator=>this.#serveRequest('harness.v1.sessions.recorded_config',{locator},15000)});
@@ -1528,6 +1563,34 @@ export class TeamsMachine extends MachineCore {
         if (!this.machineEvents || params.team_id!==this.machineEvents.teamId) throw new Error('this connector is not serving that team');
         return method==='machine.events.events'?this.machineEvents.snapshot():this.machineEvents.subscribe(params.address,method.endsWith('.unsubscribe'));
       }
+      case 'health.read': {
+        // A machine's vitals: operators, and principals granted view on the whole machine.
+        if (!operator) need('view', '*');
+        const dir = healthDirOf(this.env);
+        let snapshot = null;
+        try { snapshot = JSON.parse(readFileSync(join(dir, 'latest.json'), 'utf8')); } catch { /* no reading yet */ }
+        let subscriptions = [];
+        try { subscriptions = JSON.parse(readFileSync(join(dir, 'subscriptions.json'), 'utf8')).addresses ?? []; } catch { /* none */ }
+        return { snapshot, probe: this.healthRun ?? { running: false, reason: 'not started by this daemon' }, subscriptions, dir };
+      }
+      case 'health.subscribe':
+      case 'health.unsubscribe': {
+        // Alarm mail for a session or board address. Operators only: it decides who is woken.
+        if (!operator) throw Object.assign(new Error('subscribing to machine health requires operator authority'), { code: 403 });
+        const address = String(params.address ?? '');
+        if (!/^sc:[^:\s]+:[^:\s]+:\S+$/.test(address)) throw new Error('health.subscribe needs a full sc:<machine>:<harness>:<id> address');
+        const dir = healthDirOf(this.env);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const file = join(dir, 'subscriptions.json');
+        let addresses = [];
+        try { addresses = JSON.parse(readFileSync(file, 'utf8')).addresses ?? []; } catch { /* first */ }
+        addresses = addresses.filter((a) => a !== address);
+        if (method === 'health.subscribe') addresses.push(address);
+        writeFileSync(`${file}.${process.pid}.tmp`, JSON.stringify({ addresses }) + '\n', { mode: 0o600 });
+        renameSync(`${file}.${process.pid}.tmp`, file);
+        act(method, address);
+        return { addresses };
+      }
       case 'harness.v1.agents.bindSession': {
         if (!operator) throw Object.assign(new Error('binding an agent session requires operator authority'),{code:403});
         const {session,context}=params;
@@ -1575,7 +1638,7 @@ export class TeamsMachine extends MachineCore {
             const ended=await this.#serveRequest('harness.v1.runtimes.close',{connection:runtime.connection});
             result=ended?.closed?{state:'closed',reason:'native runtime close receipt'}:{state:'unknown',reason:'runtime returned no close receipt'};
           }else{
-            const machine=hostname().split('.')[0].toLowerCase().replace(/[^a-z0-9_-]/g,'-'),address=`sc:${machine}:${closure.harness}:${closure.native_id}`;
+            const machine=machineName(this.env),address=`sc:${machine}:${closure.harness}:${closure.native_id}`;
             const code=await new Promise((resolve,reject)=>{
               const child=spawn(this.supercodeBin,['close',address],{env:{...this.env,SUPERCODE_CALLER:address},stdio:'ignore'});
               const timer=setTimeout(()=>{child.kill('SIGTERM');resolve(null);},30000);
@@ -2293,3 +2356,17 @@ function alive(pid) {
 }
 
 export { listAnnouncedPorts };
+
+/** The machine-health pack's state directory: the pack's own rule (sdk/health/lib/paths.mjs). */
+function healthDirOf(env) {
+  if (env.SUPERCODE_HEALTH_DIR) return env.SUPERCODE_HEALTH_DIR;
+  return join(env.SUPERCODE_HOME || join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'supercode'), 'health');
+}
+
+/** The pack's probe entry: an explicit path, the installed package, else a source checkout's sibling. */
+function healthEntry(env) {
+  if (env.SUPERCODE_HEALTH_ENTRY) return existsSync(env.SUPERCODE_HEALTH_ENTRY) ? env.SUPERCODE_HEALTH_ENTRY : null;
+  try { const found = fileURLToPath(import.meta.resolve('@volter/supercode-health/bin')); if (existsSync(found)) return found; } catch { /* not installed */ }
+  const sibling = fileURLToPath(new URL('../health/bin/health.mjs', import.meta.url));
+  return existsSync(sibling) ? sibling : null;
+}

package/mail-history.mjs

@@ -71,7 +71,7 @@ async function answeredMail(rows, binary, env, signal) {
 
 // Match the CLI's local_machine_name: the native mailbox belongs to its
 // enrolled context, which can differ from a viewer connector's --home.
-function machineName(env) {
+export function machineName(env) {
   let name = hostname();
   try {
     const root = join(teamsHome(env), 'workspaces');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-teams",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "type": "module",
   "description": "A machine daemon serving this machine's doors, and a local or remote Teams server for shared session discovery, OpenTelemetry ingestion and access to enrolled machines.",
   "license": "MIT",
@@ -61,6 +61,7 @@
     "@homebridge/node-pty-prebuilt-multiarch": "^0.14.1",
     "@volter/supercode-frontend": "^0.2.2",
     "@volter/supercode-harness-sdk": "^0.3.43",
+    "@volter/supercode-health": "^0.1.0",
     "@volter/supercode-terminal": "^0.2.54",
     "@volter/identity": "^0.4.1",
     "@volter/teams": "0.2.1",