@commonlyai/cli 0.1.173 → 0.1.174

package/node_modules/@commonlyai/seats/README.md

@@ -0,0 +1,11 @@
+# packages/seats
+
+The adapters that run an agent CLI as a supervised seat: one prompt in, one CLI run, one reply out. The package holds the contract, the registry, the failure naming, the spawn observation, the run supervisor (`superviseRun`: a turn with no progress signal for `stallMs` is traced as stuck, cancelled, and settled even if its adapter ignores the cancel), and the first adapters (`stub`, `hermes`).
+
+It is private and is not published on its own. `@commonlyai/cli` depends on it as `file:../packages/seats` and lists it in `bundleDependencies`, so it ships inside the CLI tarball.
+
+**Rule:** nothing here imports Commonly code. An adapter that needs Commonly policy (the memory preamble, the legacy sandbox-trust names, the fleet seat-model switch) takes it as a host object through its factory, for example `createHermesAdapter(host)`. The CLI binds that host in `cli/src/lib/adapters/<name>.js`. `cli/__tests__/seats-package.test.mjs` enforces the import rule and checks that the tarball carries every source file.
+
+The extraction plan is D62, extract-in-place.
+
+**Run record.** The trace store writes each run as a versioned, hash-chained JSONL record. It covers who granted which agent what access for which task, who approved each call, what was attempted, and the result. A tool outside this package can read, verify and export it to OTLP. The format is specified in [`docs/record-v1.md`](docs/record-v1.md), and a generated sample is in [`docs/examples/`](docs/examples/).

package/node_modules/@commonlyai/seats/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@commonlyai/seats",
+  "version": "0.0.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "description": "Adapters that run agent CLIs as supervised seats. Bundled inside @commonlyai/cli; not published on its own.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./*": "./src/*.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  }
+}

package/node_modules/@commonlyai/seats/src/adapters/hermes.js

@@ -0,0 +1,206 @@
+/** Hermes 0.22.2 local CLI wrapper. Hermes owns provider I/O; this file only spawns it. */
+import { spawn as childSpawn, spawnSync } from 'child_process';
+import { createHash } from 'crypto';
+import { mkdir } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+import { StringDecoder } from 'string_decoder';
+import { observeSpawn, controlsFromArguments } from '../runtime-observation.js';
+import { requireSeatModel } from '../seat-model.js';
+import { adapterFailure, spawnCredentials } from '../upstream-refusal.js';
+
+export const TESTED_HERMES_VERSION = '0.22.2';
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+const VERSION_TIMEOUT_MS = 15000;
+const MAX_STDERR_CHARS = 4096;
+const MAX_LINE_CHARS = 1024 * 1024;
+
+const readVersion = (env, spawnSyncImpl = spawnSync) => {
+  let probe;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    probe = spawnSyncImpl('hermes', ['--version'], {
+      encoding: 'utf8', env, timeout: VERSION_TIMEOUT_MS,
+    });
+    if (probe.error?.code === 'ENOENT') return null;
+    if (probe.error || probe.status !== 0) continue;
+    const version = String(probe.stdout || '').match(/Hermes Agent v([^\s]+)/i)?.[1];
+    if (version !== TESTED_HERMES_VERSION) {
+      throw new Error(`Hermes ${version || 'unknown'} is unsupported; this adapter requires ${TESTED_HERMES_VERSION}`);
+    }
+    return version;
+  }
+  const status = probe.status ?? 'none';
+  const signal = probe.signal ?? 'none';
+  const code = probe.error?.code ?? 'none';
+  throw new Error(`Hermes version probe failed after 2 attempts (status=${status}, signal=${signal}, code=${code}, timeout=${VERSION_TIMEOUT_MS}ms); check the Hermes installation or startup log`);
+};
+
+export const readHermesJsonl = (line, state) => {
+  let event;
+  try { event = JSON.parse(line); } catch { throw new Error('Hermes emitted invalid JSONL'); }
+  if (state.result) throw new Error('Hermes emitted data after its terminal result');
+  if (event?.type === 'system' && event.subtype === 'init') {
+    state.started = true;
+  } else if (event?.type === 'result') {
+    state.result = event;
+  } else if (!state.started) {
+    throw new Error('Hermes emitted an event before init');
+  }
+};
+
+const runHermes = ({ args, prompt, cwd, env, timeoutMs, spawnImpl, credentials, onSpawn, controls = {} }) => new Promise((resolve, reject) => {
+  const child = (spawnImpl || childSpawn)('hermes', args, {
+    cwd, env, stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  observeSpawn(child, onSpawn, controls);
+  const state = { started: false, result: null };
+  const decoder = new StringDecoder('utf8');
+  let buffer = '';
+  let stderr = '';
+  let timedOut = false;
+  let settled = false;
+  let closed = false;
+  let stopping = false;
+  let killTimer;
+  const finish = (error, result) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    if (error) reject(error); else resolve(result);
+  };
+  const stop = () => {
+    if (stopping || closed) return;
+    stopping = true;
+    child.kill('SIGTERM');
+    killTimer = setTimeout(() => {
+      if (!closed) child.kill('SIGKILL');
+    }, 5000);
+  };
+  const failAndStop = (error) => {
+    stop();
+    finish(error);
+  };
+  const timer = setTimeout(() => {
+    timedOut = true;
+    stop();
+  }, timeoutMs);
+  child.on('error', (error) => failAndStop(adapterFailure('Hermes', error?.message || 'spawn failed', { credentials })));
+  child.stdout.on('data', (chunk) => {
+    if (settled) return;
+    buffer += decoder.write(chunk);
+    let newline = buffer.indexOf('\n');
+    while (newline !== -1) {
+      if (newline > MAX_LINE_CHARS) {
+        failAndStop(new Error('Hermes JSONL line exceeded 1 MiB'));
+        return;
+      }
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (line) {
+        try { readHermesJsonl(line, state); } catch (error) {
+          failAndStop(error);
+          return;
+        }
+      }
+      newline = buffer.indexOf('\n');
+    }
+    if (buffer.length > MAX_LINE_CHARS) {
+      failAndStop(new Error('Hermes JSONL line exceeded 1 MiB'));
+    }
+  });
+  child.stdout.on('error', (error) => failAndStop(adapterFailure('Hermes stdout', error?.message || 'read failed', { credentials })));
+  child.stderr.on('data', (chunk) => {
+    stderr = `${stderr}${chunk.toString()}`.slice(-MAX_STDERR_CHARS);
+  });
+  child.on('close', (code) => {
+    closed = true;
+    clearTimeout(killTimer);
+    if (settled) return;
+    if (timedOut) return finish(new Error(`Hermes timed out after ${timeoutMs}ms`));
+    buffer += decoder.end();
+    if (buffer.trim()) {
+      try { readHermesJsonl(buffer.trim(), state); } catch (error) { return finish(error); }
+    }
+    const result = state.result;
+    if (!result || !state.started) return finish(new Error('Hermes exited without a complete JSONL result'));
+    if (code !== 0 || result.exit_code !== 0) {
+      return finish(adapterFailure('Hermes', result.error || stderr || `exit ${code}`, {
+        credentials, exitCode: code,
+      }));
+    }
+    if (typeof result.text !== 'string' || !result.session_id) {
+      return finish(new Error('Hermes result omitted text or session_id'));
+    }
+    return finish(null, { text: result.text, newSessionId: result.session_id });
+  });
+  child.stdin.on('error', (error) => failAndStop(adapterFailure('Hermes stdin', error?.message || 'write failed', { credentials })));
+  child.stdin.end(prompt);
+});
+
+/**
+ * @param {import('../contract.js').SeatHost & { profileRoot?: string }} [host]
+ *   profileRoot is where each seat's isolated HERMES_HOME is created.
+ */
+export const createHermesAdapter = ({
+  memoryPreamble = (prompt) => prompt,
+  effectiveTrust = (trust) => trust,
+  seatModelRequired = () => false,
+  profileRoot = join(homedir(), '.seats', 'hermes', 'profiles'),
+} = {}) => ({
+  get requiresModel() { return seatModelRequired(); },
+  name: 'hermes',
+  runtimeType: 'hermes',
+  supportsProvider: false,
+  providerKeyEnv: 'OPENROUTER_API_KEY',
+
+  async validateEnvironment(environment) {
+    if (environment?.provider !== undefined) {
+      throw new Error('Hermes adapter does not consume environment.provider; supply OPENROUTER_API_KEY in the host environment');
+    }
+    if (environment?.mcp?.length) {
+      throw new Error('Hermes adapter does not yet consume environment.mcp declarations');
+    }
+    if (effectiveTrust(environment?.sandbox?.trust) === 'public'
+      || (environment?.sandbox?.mode && environment.sandbox.mode !== 'none')) {
+      throw new Error('Hermes public or sandbox-declared seats are unsupported: no enforced confinement adapter exists');
+    }
+  },
+
+  async detect() {
+    const version = readVersion(process.env);
+    return version ? { path: 'hermes', version } : null;
+  },
+
+  async spawn(prompt, ctx = {}) {
+    const seatModel = requireSeatModel(ctx.environment, 'hermes', seatModelRequired());
+    await this.validateEnvironment(ctx.environment);
+    // Keep Hermes away from the operator's default profile, including any
+    // Nous Portal/Cloud credentials there. The wrapper provides the sole key.
+    const seat = `${ctx.agentName || ''}\0${ctx.cwd || ''}`;
+    const home = ctx._hermesHome || join(profileRoot,
+      createHash('sha256').update(seat).digest('hex').slice(0, 24));
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    const env = { ...(ctx.env || process.env), HERMES_HOME: home };
+    if (!readVersion(env, ctx._spawnSyncImpl)) {
+      throw new Error('Hermes Agent 0.22.2 is not on PATH');
+    }
+    if (!env.OPENROUTER_API_KEY) {
+      throw new Error('Supply the operator OPENROUTER_API_KEY through Secret Manager before running Hermes');
+    }
+    const args = ['chat', '--oneshot', '--query-file', '-', '--format', 'stream-json',
+      '--provider', 'openrouter', '--source', 'tool', '--no-restore-cwd'];
+    if (seatModel) args.push('--model', seatModel);
+    if (ctx.sessionId) args.push('--resume', ctx.sessionId);
+    const fullPrompt = memoryPreamble(prompt, ctx.memoryLongTerm, {
+      freshSession: !ctx.sessionId,
+    });
+    const requestedTimeout = Number(ctx.timeoutMs);
+    const timeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+      ? Math.min(requestedTimeout, DEFAULT_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS;
+    return runHermes({
+      args, prompt: fullPrompt, cwd: ctx.cwd, env, timeoutMs,
+      spawnImpl: ctx._spawnImpl, onSpawn: ctx.onSpawn, controls: controlsFromArguments(args, { modelFlag: '--model', valueFlags: ['--query-file', '--format', '--provider', '--source', '--resume'] }),
+      credentials: spawnCredentials(ctx, ['OPENROUTER_API_KEY']),
+    });
+  },
+});

package/node_modules/@commonlyai/seats/src/adapters/stub.js

@@ -0,0 +1,24 @@
+/**
+ * Stub adapter — the no-op reference implementation of the ADR-005 adapter
+ * contract. Used by `commonly agent attach stub` and the Phase-1a test
+ * harness so the run loop can be reviewed end-to-end without a real CLI
+ * on PATH.
+ *
+ * Contract (ADR-005 §Adapter pattern):
+ *   detect(): Promise<{ path, version } | null>
+ *   spawn(prompt, ctx): Promise<{ text, newSessionId?, memorySummary? }>
+ *
+ * The adapter MUST be pure: input (argv + env + prompt) → output (text + optional
+ * next session-id + optional memory summary). No direct network, no direct API
+ * calls, no hidden state. The run loop handles all Commonly-facing I/O.
+ */
+
+export default {
+  name: 'stub',
+  async detect() {
+    return { path: '(builtin)', version: '0.0.0' };
+  },
+  async spawn(prompt, _ctx) {
+    return { text: `(stub) received: ${String(prompt ?? '').slice(0, 200)}` };
+  },
+};

package/node_modules/@commonlyai/seats/src/contract.js

@@ -0,0 +1,48 @@
+/**
+ * The adapter contract (ADR-005 §Adapter pattern). An adapter turns one prompt
+ * into one CLI run and one reply. It owns argv, env and output parsing for its
+ * CLI; the caller owns everything that talks to a Commonly instance.
+ *
+ * @typedef {object} Adapter
+ * @property {string} name
+ * @property {string} [runtimeType]
+ * @property {string} [providerKeyEnv]  host env var the adapter's provider key arrives in
+ * @property {() => Promise<{ path: string, version: string } | null>} detect
+ * @property {(environment: object) => Promise<void>} [validateEnvironment]  refuse before spawn
+ * @property {(prompt: string, ctx: object) => Promise<SpawnResult>} spawn
+ *
+ * @typedef {object} SpawnResult
+ * @property {string} text
+ * @property {string} [newSessionId]
+ * @property {number} [contextTokens]
+ * @property {string} [memorySummary]
+ *
+ * Adapters that need host policy are built by a factory that takes a SeatHost.
+ * Every field is optional; an absent field takes the neutral default named.
+ *
+ * @typedef {object} SeatHost
+ * @property {(prompt: string, longTerm: string | null | undefined, opts: { freshSession: boolean }) => string} [memoryPreamble]  default: the prompt unchanged
+ * @property {(trust: string | undefined) => string | undefined} [effectiveTrust]  default: the declared trust unchanged
+ * @property {() => boolean} [seatModelRequired]  default: false
+ */
+
+/**
+ * @param {Adapter[]} adapters
+ */
+export const createRegistry = (adapters) => {
+  const byName = {};
+  for (const adapter of adapters) {
+    if (!adapter?.name) throw new Error('every adapter needs a name');
+    if (byName[adapter.name]) throw new Error(`duplicate adapter name: ${adapter.name}`);
+    byName[adapter.name] = adapter;
+  }
+  return {
+    adapters: byName,
+    names: () => Object.keys(byName),
+    get: (name) => byName[name] || null,
+  };
+};
+
+export const providerKeyEnvNames = (adapters) => [...new Set(
+  Object.values(adapters).map((adapter) => adapter.providerKeyEnv).filter(Boolean),
+)];

package/node_modules/@commonlyai/seats/src/failures.js

@@ -0,0 +1,38 @@
+/**
+ * Named run failures. Every way a run can end badly has one kind, so a trace,
+ * a retry policy and a dashboard all read the same word. A kind is a contract:
+ * add one here, never mint one at a call site.
+ */
+import { scrubAdapterFailure } from './upstream-refusal.js';
+
+export const FAILURE_KINDS = Object.freeze({
+  stuck: { retryable: true, meaning: 'no progress signal within the liveness window' },
+  timeout: { retryable: true, meaning: 'the run exceeded its wall-clock budget' },
+  exited: { retryable: true, meaning: 'the CLI process ended before the turn settled' },
+  protocol: { retryable: false, meaning: 'the CLI broke its wire protocol' },
+  refusal: { retryable: false, meaning: 'the model or provider refused; never retried' },
+  max_tokens: { retryable: false, meaning: 'the turn hit its token limit' },
+  max_turn_requests: { retryable: false, meaning: 'the turn hit its request limit' },
+  cancelled: { retryable: false, meaning: 'the run was cancelled' },
+  credential_denied: { retryable: false, meaning: 'the run asked for a credential its grant does not allow' },
+  unsupported: { retryable: false, meaning: 'the CLI or its version is outside what this adapter supports' },
+});
+
+export class RunFailure extends Error {
+  constructor(kind, detail, { cause } = {}) {
+    if (!FAILURE_KINDS[kind]) throw new Error(`unknown failure kind: ${kind}`);
+    super(detail ? `${kind}: ${detail}` : kind, cause ? { cause } : undefined);
+    this.name = 'RunFailure';
+    this.kind = kind;
+    this.retryable = FAILURE_KINDS[kind].retryable;
+    this.detail = detail || '';
+  }
+}
+
+/** Build a failure whose detail has known credentials and secret shapes scrubbed. */
+export const runFailure = (kind, text, { credentials = [], limit } = {}) => {
+  const { detail } = scrubAdapterFailure(String(text ?? ''), { credentials, limit });
+  return new RunFailure(kind, detail);
+};
+
+export const failureKindOf = (error) => (error instanceof RunFailure ? error.kind : null);

package/node_modules/@commonlyai/seats/src/index.js

@@ -0,0 +1,22 @@
+export { createRegistry, providerKeyEnvNames } from './contract.js';
+export { requireSeatModel } from './seat-model.js';
+export { controlsFromArguments, observeSpawn } from './runtime-observation.js';
+export {
+  LEADS_PROCESS_GROUP, OWN_PROCESS_GROUP, spawnInOwnGroup, wantsOwnProcessGroup, leadsOwnGroup, killProcessTree,
+  trackSupervisedGroup, killSupervisedGroups, armSupervisedGroupDeadline,
+  readProcessTable, readProcess, descendantsOf, killDescendants,
+} from './process-group.js';
+export { adapterFailure, spawnCredentials } from './upstream-refusal.js';
+export { default as stub } from './adapters/stub.js';
+export { createHermesAdapter } from './adapters/hermes.js';
+export { RunFailure, runFailure, failureKindOf, FAILURE_KINDS } from './failures.js';
+export { EVENT_TYPES, isEventType, traceOf, NULL_TRACE } from './trace/events.js';
+export { createTraceStore } from './trace/store.js';
+export { validateGrant, matchToolCall, TOOL_KINDS, CREDENTIAL_SOURCES } from './valet/grant.js';
+export { prepareRunEnv, BASE_ENV_ALLOWLIST } from './valet/env.js';
+export { createPermissionPolicy, DEFAULT_APPROVE_TIMEOUT_MS } from './valet/permissions.js';
+export {
+  RECORD_VERSION, RECORD_SCHEMA, KINDS, canonicalLine, appendEntry, verifyRecord, readRecord, hashLine, toolSurfaceOf, argsDigestOf,
+} from './record/format.js';
+export { toOtlpJson } from './record/otel.js';
+export { superviseRun, SUPERVISOR_DEFAULTS, DEFAULT_RETRY_ON } from './supervisor.js';

package/node_modules/@commonlyai/seats/src/process-group.js

@@ -0,0 +1,261 @@
+/**
+ * Process groups for supervised children.
+ *
+ * An agent CLI spawns its own children: MCP servers through `npx`, a native
+ * binary behind a node launcher, shells for tools. Killing only the CLI leaves
+ * those running, holding the run's work and keys on a shared host. A child the
+ * supervisor will kill is therefore started as the leader of its own process
+ * group, and killed as a group.
+ *
+ * Leading a group is never inferred. The spawner that passed `detached` marks
+ * the child, and only a marked child that is still alive is ever signalled by
+ * negative pid: signalling `-pid` for a process that does not lead its group
+ * can reach an unrelated group.
+ *
+ * A group kill misses a descendant that moved to a group of its own (codex
+ * starts every MCP server and tool command that way; claude's Bash tool does
+ * too). So before any signal, the kill also snapshots the process table and
+ * walks the child's descendants, deepest first. Each pid is re-read right
+ * before it is signalled and killed only if its parent and start time still
+ * match the snapshot: a pid that exited and was reused by another process on
+ * this host is left alone. Leaves go first so a pid's parent is still alive,
+ * and its ppid still meaningful, when it is checked.
+ *
+ * What the walk does not catch, by design, because each case would need the
+ * ppid match loosened:
+ *   (a) a descendant reparented to 1 (its parent died) between the snapshot
+ *       and its re-read is skipped: its ppid no longer matches;
+ *   (b) a process started after the snapshot is not in it, and one that calls
+ *       setsid after the snapshot leaves the group the group kill signals;
+ *       either is missed.
+ *
+ * A child in its own group is outside the wrapper's group, so launchd's kill
+ * of the seat's group on exit no longer reaches it. `trackSupervisedGroup`
+ * covers that: while any tracked group is live, the wrapper kills them all
+ * when it exits, and on SIGTERM, SIGINT or SIGHUP when nothing else handles
+ * the signal. A host that handles the signal itself (`agent run` finishes the
+ * in-flight turn on SIGTERM) owns the timing: it calls
+ * `armSupervisedGroupDeadline` so the groups die before launchd's SIGKILL,
+ * which no handler can catch, and the exit hook covers the clean case.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** Set on a child by the code that spawned it with `detached: true`. */
+export const LEADS_PROCESS_GROUP = Symbol.for('@commonlyai/seats.leadsProcessGroup');
+
+/** Whether a child can lead its own group here (POSIX only). */
+export const PROCESS_GROUPS_SUPPORTED = process.platform !== 'win32';
+
+/**
+ * The ctx key the supervisor sets to tell an adapter it will kill the child's
+ * group, so the adapter may start the child in one. Unset, an adapter spawns
+ * exactly as it would unsupervised.
+ */
+export const OWN_PROCESS_GROUP = 'ownProcessGroup';
+
+export const wantsOwnProcessGroup = (ctx) => ctx?.[OWN_PROCESS_GROUP] === true && PROCESS_GROUPS_SUPPORTED;
+
+/**
+ * Spawn through `spawnImpl`. With `ownGroup`, the child is started detached
+ * (it calls setsid, so it leads a new group whose id is its pid) and marked.
+ * Without it, `options` reach `spawnImpl` untouched.
+ */
+export const spawnInOwnGroup = (spawnImpl, command, args, options, { ownGroup = false } = {}) => {
+  if (!ownGroup || !PROCESS_GROUPS_SUPPORTED) return spawnImpl(command, args, options);
+  const child = spawnImpl(command, args, { ...options, detached: true });
+  if (child && typeof child === 'object') child[LEADS_PROCESS_GROUP] = true;
+  return child;
+};
+
+const isAlive = (child) => child.exitCode === null && child.signalCode === null;
+
+/**
+ * True only for a child its spawner marked, with a real pid, that has not been
+ * reaped. Node sets exitCode/signalCode in the same tick it reaps, so while
+ * this holds the pid (and so the group id) cannot have been reused.
+ */
+export const leadsOwnGroup = (child) => !!child
+  && child[LEADS_PROCESS_GROUP] === true
+  && Number.isInteger(child.pid) && child.pid > 0
+  && isAlive(child);
+
+// ── The process table ──────────────────────────────────────────────────────
+
+const PS_ENV = { ...process.env, LC_ALL: 'C' };
+
+const parseTable = (text) => {
+  const rows = [];
+  for (const line of String(text || '').split('\n')) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S.*?)\s*$/.exec(line);
+    if (match) rows.push({ pid: Number(match[1]), ppid: Number(match[2]), started: match[3] });
+  }
+  return rows;
+};
+
+const ps = (args) => {
+  try {
+    const out = spawnSync('ps', args, { encoding: 'utf8', env: PS_ENV, timeout: 5000 });
+    return out.error ? null : parseTable(out.stdout);
+  } catch { return null; }
+};
+
+/** Every process: { pid, ppid, started }. null when ps is unavailable. */
+export const readProcessTable = () => ps(['-A', '-o', 'pid=,ppid=,lstart=']);
+
+/** One process as it is now, or null when it is gone. */
+export const readProcess = (pid) => (ps(['-o', 'pid=,ppid=,lstart=', '-p', String(pid)]) || [])
+  .find((row) => row.pid === pid) || null;
+
+/** The descendants of `root` in `table`, deepest first. The root is not included. */
+export const descendantsOf = (table, root) => {
+  const byParent = new Map();
+  for (const row of table || []) {
+    if (row.pid === row.ppid) continue;
+    if (!byParent.has(row.ppid)) byParent.set(row.ppid, []);
+    byParent.get(row.ppid).push(row);
+  }
+  const out = [];
+  const seen = new Set([root]);
+  let level = [root];
+  for (let depth = 1; level.length; depth += 1) {
+    const next = [];
+    for (const parent of level) {
+      for (const row of byParent.get(parent) || []) {
+        if (seen.has(row.pid)) continue;
+        seen.add(row.pid);
+        out.push({ ...row, depth });
+        next.push(row.pid);
+      }
+    }
+    level = next;
+  }
+  return out.sort((a, b) => b.depth - a.depth);
+};
+
+const DEFAULT_IO = Object.freeze({ table: readProcessTable, read: readProcess });
+
+/**
+ * Signal each snapshotted descendant, deepest first, re-reading it just
+ * before: it is signalled only while its ppid and start time still match.
+ * Returns the pids signalled.
+ */
+export const killDescendants = (descendants, signal = 'SIGKILL', { read = readProcess } = {}) => {
+  const killed = [];
+  for (const row of descendants) {
+    const now = read(row.pid);
+    if (!now || now.ppid !== row.ppid || now.started !== row.started) continue;
+    try { process.kill(row.pid, signal); killed.push(row.pid); } catch { /* gone */ }
+  }
+  return killed;
+};
+
+const liveRoot = (child) => !!child && Number.isInteger(child.pid) && child.pid > 0 && isAlive(child);
+
+const killOne = (child, signal, table, io) => {
+  // The root must be alive, so unreaped, so its pid still names this child.
+  if (table && liveRoot(child)) killDescendants(descendantsOf(table, child.pid), signal, io);
+  if (leadsOwnGroup(child)) {
+    try { process.kill(-child.pid, signal); return true; } catch { /* fall back to the leader */ }
+  }
+  try { return child.kill(signal) !== false; } catch { return false; }
+};
+
+/**
+ * Kill a child, its verified descendants, and its whole group when it leads
+ * one. The table is read before any signal. Falls back to `child.kill` when
+ * the child does not lead a group, or the group signal fails. Returns whether
+ * the child was signalled. `io` is a test seam ({ table, read }).
+ */
+export const killProcessTree = (child, signal = 'SIGKILL', io = {}) => {
+  const seam = { ...DEFAULT_IO, ...io };
+  return killOne(child, signal, liveRoot(child) ? seam.table() : null, seam);
+};
+
+// ── Wrapper-exit cleanup ────────────────────────────────────────────────────
+
+const EXIT_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+const tracked = new Set();
+const handlers = new Map();
+let onExit = null;
+let deadline = null;
+
+/** SIGKILL every tracked group still led by a live child, with its verified descendants. Synchronous. */
+export const killSupervisedGroups = (signal = 'SIGKILL', io = {}) => {
+  const live = [...tracked].filter(leadsOwnGroup);
+  if (live.length === 0) return 0;
+  const seam = { ...DEFAULT_IO, ...io };
+  const table = seam.table();
+  let killed = 0;
+  for (const child of live) if (killOne(child, signal, table, seam)) killed += 1;
+  return killed;
+};
+
+/**
+ * Kill the tracked groups in `ms`, for a host that keeps running after a
+ * signal (to finish a turn) but will be SIGKILLed at a known deadline. The
+ * earliest deadline armed wins. The timer does not hold the process open.
+ * Returns a function that disarms it.
+ */
+export const armSupervisedGroupDeadline = (ms) => {
+  const wait = Math.max(0, Number(ms) || 0);
+  const at = Date.now() + wait;
+  if (deadline && deadline.at <= at) return deadline.cancel;
+  if (deadline) deadline.cancel();
+  const timer = setTimeout(() => { deadline = null; killSupervisedGroups(); }, wait);
+  timer.unref?.();
+  const entry = { at, cancel: () => { clearTimeout(timer); if (deadline === entry) deadline = null; } };
+  deadline = entry;
+  return entry.cancel;
+};
+
+const uninstall = () => {
+  for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  handlers.clear();
+  if (onExit) process.removeListener('exit', onExit);
+  onExit = null;
+};
+
+const install = () => {
+  if (onExit) return;
+  onExit = () => { killSupervisedGroups(); };
+  process.on('exit', onExit);
+  for (const signal of EXIT_SIGNALS) {
+    const handler = () => {
+      // A host that handles this signal has taken over shutdown: it may be
+      // finishing the turn these groups belong to, so they are left alone and
+      // the host's deadline or exit kills them.
+      if (process.listenerCount(signal) !== 1) return;
+      killSupervisedGroups();
+      // Listening for a signal replaces its default action. With nothing else
+      // handling it, restore that action and re-raise, so the wrapper still
+      // terminates exactly as it would have without this module.
+      uninstall();
+      process.kill(process.pid, signal);
+    };
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+};
+
+const untrack = (child) => {
+  tracked.delete(child);
+  if (tracked.size === 0) uninstall();
+};
+
+/**
+ * Track a group-leading child until it exits. The handlers exist only while a
+ * tracked child is live, so a wrapper with no supervised group in flight keeps
+ * its signal behaviour unchanged. A child that does not lead a group is
+ * ignored: launchd's group kill already reaches it.
+ */
+export const trackSupervisedGroup = (child) => {
+  if (!leadsOwnGroup(child) || tracked.has(child)) return false;
+  tracked.add(child);
+  install();
+  child.once?.('exit', () => untrack(child));
+  return true;
+};
+
+/** For tests: how many groups are tracked. */
+export const trackedGroupCount = () => tracked.size;