@ravefox/space 0.2.0 → 0.3.0

package/node_modules/@commonlyai/seats/src/harness-plan.js

@@ -1,329 +0,0 @@
-/**
- * Which harness a seat runs a turn on, and what it does when that harness
- * cannot serve.
- *
- * A seat declares a run config: a primary entry {harness, model, effort?} and
- * an ordered fallback list of the same shape. `runTurnWithFallback` tries the
- * active entry. When the attempt fails with one of FALLBACK_KINDS (the harness
- * cannot serve anyone right now: not signed in, out of quota, the provider
- * does not take this model), it moves to the next entry in the same turn, so
- * the turn is still served. Every other failure is thrown unchanged and no
- * switch happens. A content refusal in particular never switches: re-sending
- * refused content through another provider is refusal-shopping.
- *
- * While a fallback is active, the next turn after the failed entry's cooldown
- * starts from the primary again. That turn is the probe: if the primary
- * answers, the seat is back on it. If it fails with a fallback kind or a
- * retryable liveness kind (PROBE_CARRY_KINDS), the same turn carries on down
- * the list. Any other failure, an unnamed one included, ends the turn there:
- * an adapter's upstream refusal reaches this module as an unnamed error, and
- * carrying it on would be the same refusal-shopping. Either way the cooldown
- * restarts, so the next turn stays on the seat's own entry.
- *
- * An entry the host's policy blocks is skipped and never attempted. An entry
- * the host cannot take right now (a per-model concurrency cap, a stop file;
- * the caller's `acquire`) is skipped for this turn only. If no entry served,
- * the turn fails visibly; nothing substitutes a harness the config does not
- * list.
- *
- * Pure: state goes in and comes out as plain data, persisted by the caller,
- * and time is passed in. Nothing here reads a file or the clock.
- */
-import { RunFailure, failureKindOf } from './failures.js';
-
-/** The failure kinds that move a turn to the next entry. Nothing else does. */
-export const FALLBACK_KINDS = Object.freeze(['not_authenticated', 'quota', 'provider_unsupported']);
-
-/**
- * The failure kinds on which a failed probe carries on to the seat's own
- * entry: the fallback kinds, and the retryable kinds that say the primary
- * never produced an answer. An allowlist, so a kind added later ends a probe
- * turn until someone decides otherwise.
- */
-export const PROBE_CARRY_KINDS = Object.freeze([...FALLBACK_KINDS, 'stuck', 'timeout', 'exited']);
-
-/** How long a failed entry rests before a turn probes it again, per kind. */
-export const PROBE_COOLDOWN_MS = Object.freeze({
-  quota: 15 * 60 * 1000,
-  not_authenticated: 30 * 60 * 1000,
-  provider_unsupported: 60 * 60 * 1000,
-});
-
-/**
- * Why a seat's active entry changed, as `harness.switched` records it:
- * a fallback kind, `blocked` (the active entry is blocked by policy), `probe`
- * (a probe moved back up the list) and `operator` (`commonly agent use`).
- */
-export const SWITCH_REASONS = Object.freeze([...FALLBACK_KINDS, 'blocked', 'probe', 'operator']);
-
-/** Fallback entries a config may list after its primary. */
-export const MAX_FALLBACK = 5;
-/** Switches kept in state.history, newest last. */
-export const HISTORY_LIMIT = 20;
-
-const HARNESS = /^[a-z][a-z0-9-]{0,31}$/;
-// No '@' and no whitespace: '@' separates the effort in the short form.
-const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,127}$/;
-const EFFORT = /^[a-z]{1,16}$/;
-const REASON = /^[A-Za-z0-9][A-Za-z0-9 ._:/#()-]{0,119}$/;
-
-const fail = (message) => { throw new Error(`harness plan: ${message}`); };
-const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-const refuseUnknownKeys = (value, allowed, where) => {
-  for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`unknown field ${where}${key}`);
-};
-
-/**
- * One entry, as an object or the short form `harness/model[@effort]`
- * (`claude/claude-sonnet-5-5@high`). The harness is everything before the first '/',
- * so a model may itself contain '/' (`opencode/litellm/deepseek-flash-1017`).
- */
-export const parseEntry = (value, where = 'entry') => {
-  let entry = value;
-  if (typeof value === 'string') {
-    const slash = value.indexOf('/');
-    if (slash < 1) fail(`${where} must read harness/model[@effort], got ${JSON.stringify(value)}`);
-    const rest = value.slice(slash + 1);
-    const at = rest.lastIndexOf('@');
-    entry = at === -1
-      ? { harness: value.slice(0, slash), model: rest }
-      : { harness: value.slice(0, slash), model: rest.slice(0, at), effort: rest.slice(at + 1) };
-  }
-  if (!isPlainObject(entry)) fail(`${where} must be an object or harness/model[@effort]`);
-  refuseUnknownKeys(entry, ['harness', 'model', 'effort'], `${where}.`);
-  if (typeof entry.harness !== 'string' || !HARNESS.test(entry.harness)) fail(`${where}.harness must match ${HARNESS}`);
-  if (typeof entry.model !== 'string' || !MODEL.test(entry.model)) fail(`${where}.model must match ${MODEL}`);
-  if (entry.effort !== undefined && (typeof entry.effort !== 'string' || !EFFORT.test(entry.effort))) {
-    fail(`${where}.effort must match ${EFFORT}, or be absent`);
-  }
-  return Object.freeze({ harness: entry.harness, model: entry.model, ...(entry.effort ? { effort: entry.effort } : {}) });
-};
-
-export const entryLabel = (entry) => `${entry.harness}/${entry.model}${entry.effort ? `@${entry.effort}` : ''}`;
-
-/**
- * `{harness, model, effort?, fallback?: [entry, …]}` → `{primary, fallback, chain, key}`.
- * Refuses unknown fields, a fallback longer than MAX_FALLBACK and a repeated
- * entry (an entry listed twice would be retried under another position).
- */
-export const validateRunConfig = (config) => {
-  if (!isPlainObject(config)) fail('run config must be an object');
-  refuseUnknownKeys(config, ['harness', 'model', 'effort', 'fallback'], 'config.');
-  const primary = parseEntry({
-    harness: config.harness, model: config.model, ...(config.effort !== undefined ? { effort: config.effort } : {}),
-  }, 'config');
-  const list = config.fallback ?? [];
-  if (!Array.isArray(list)) fail('config.fallback must be an array');
-  if (list.length > MAX_FALLBACK) fail(`config.fallback lists at most ${MAX_FALLBACK} entries`);
-  const fallback = list.map((item, index) => parseEntry(item, `config.fallback[${index}]`));
-  const chain = [primary, ...fallback];
-  const labels = chain.map(entryLabel);
-  const repeated = labels.find((label, index) => labels.indexOf(label) !== index);
-  if (repeated) fail(`config lists ${repeated} twice`);
-  return Object.freeze({ primary, fallback: Object.freeze(fallback), chain: Object.freeze(chain), key: labels.join(' > ') });
-};
-
-/**
- * Host policy: `{blocked?: [{harness?, model?, reason}], limits?: [{model, maxConcurrent}]}`.
- * A blocked rule names a harness, a model or both, and matches an entry when
- * every field it names is equal. The reason is a short operator word (a task
- * id), recorded with each skip. A limit caps how many turns on this host run
- * one model at once; it is enforced by the caller's `acquire`, which this
- * module only consults. Absent or empty policy blocks and caps nothing.
- */
-export const validatePolicy = (policy) => {
-  if (policy === undefined || policy === null) return Object.freeze({ blocked: Object.freeze([]), limits: Object.freeze([]) });
-  if (!isPlainObject(policy)) fail('policy must be an object');
-  refuseUnknownKeys(policy, ['blocked', 'limits'], 'policy.');
-  const list = policy.blocked ?? [];
-  if (!Array.isArray(list)) fail('policy.blocked must be an array');
-  const blocked = list.map((rule, index) => {
-    const where = `policy.blocked[${index}]`;
-    if (!isPlainObject(rule)) fail(`${where} must be an object`);
-    refuseUnknownKeys(rule, ['harness', 'model', 'reason'], `${where}.`);
-    if (rule.harness === undefined && rule.model === undefined) fail(`${where} names a harness, a model or both`);
-    if (rule.harness !== undefined && (typeof rule.harness !== 'string' || !HARNESS.test(rule.harness))) fail(`${where}.harness must match ${HARNESS}`);
-    if (rule.model !== undefined && (typeof rule.model !== 'string' || !MODEL.test(rule.model))) fail(`${where}.model must match ${MODEL}`);
-    if (typeof rule.reason !== 'string' || !REASON.test(rule.reason)) fail(`${where}.reason must match ${REASON}`);
-    return Object.freeze({ ...rule });
-  });
-  const capList = policy.limits ?? [];
-  if (!Array.isArray(capList)) fail('policy.limits must be an array');
-  const limits = capList.map((limit, index) => {
-    const where = `policy.limits[${index}]`;
-    if (!isPlainObject(limit)) fail(`${where} must be an object`);
-    refuseUnknownKeys(limit, ['model', 'maxConcurrent'], `${where}.`);
-    if (typeof limit.model !== 'string' || !MODEL.test(limit.model)) fail(`${where}.model must match ${MODEL}`);
-    if (!Number.isInteger(limit.maxConcurrent) || limit.maxConcurrent < 1) fail(`${where}.maxConcurrent must be an integer >= 1`);
-    return Object.freeze({ model: limit.model, maxConcurrent: limit.maxConcurrent });
-  });
-  const models = limits.map((limit) => limit.model);
-  const twice = models.find((model, index) => models.indexOf(model) !== index);
-  if (twice) fail(`policy.limits lists ${twice} twice`);
-  return Object.freeze({ blocked: Object.freeze(blocked), limits: Object.freeze(limits) });
-};
-
-/** The concurrency cap for this entry's model, or null. */
-export const limitFor = (entry, policy) => (policy?.limits || []).find((limit) => limit.model === entry.model) || null;
-
-/** The rule that blocks this entry, or null. */
-export const blockedBy = (entry, policy) => (policy?.blocked || []).find((rule) => (
-  (rule.harness === undefined || rule.harness === entry.harness)
-  && (rule.model === undefined || rule.model === entry.model)
-)) || null;
-
-/** State for a config that has never run: on the primary, nothing to probe. */
-export const initialState = (plan) => ({
-  v: 1, configKey: plan.key, active: 0, since: null, reason: null, nextProbeAt: null, history: [],
-});
-
-// A persisted probe time as ms. An ISO string (a hand-edited or foreign
-// state file) is read as its time; anything unreadable means the probe is due.
-const probeTimeOf = (value) => {
-  if (Number.isFinite(value)) return value;
-  const parsed = typeof value === 'string' ? Date.parse(value) : NaN;
-  return Number.isFinite(parsed) ? parsed : null;
-};
-
-// State written by another version starts over. State for another config
-// (the operator switched the seat) starts over on the new primary and keeps
-// its history; the operator command records its own switch.
-const stateFor = (plan, state) => {
-  if (!isPlainObject(state) || state.v !== 1) return initialState(plan);
-  if (state.configKey !== plan.key) {
-    return { ...initialState(plan), history: Array.isArray(state.history) ? state.history.slice(-HISTORY_LIMIT) : [] };
-  }
-  const active = Number.isInteger(state.active) && state.active >= 0 && state.active < plan.chain.length ? state.active : 0;
-  return {
-    ...initialState(plan), ...state, active, nextProbeAt: probeTimeOf(state.nextProbeAt),
-    history: Array.isArray(state.history) ? state.history : [],
-  };
-};
-
-/**
- * The entry indices this turn tries, in order. From the active entry down;
- * from the primary when a fallback is active and its probe is due.
- */
-export const turnOrder = (plan, state, now) => {
-  const current = stateFor(plan, state);
-  const probing = current.active > 0 && (current.nextProbeAt === null || now >= current.nextProbeAt);
-  const start = probing ? 0 : current.active;
-  return { probing, order: plan.chain.map((_, index) => index).slice(start) };
-};
-
-const iso = (ms) => new Date(ms).toISOString();
-
-/**
- * Run one turn on the plan.
- *
- * @param {object} args
- * @param {ReturnType<typeof validateRunConfig>} args.plan
- * @param {ReturnType<typeof validatePolicy>} [args.policy]
- * @param {object} [args.state]     what the last turn returned; absent for a first run
- * @param {number} args.now         ms since the epoch
- * @param {(entry, info: {index, fresh, probing, switch}) => Promise<any>} args.attempt
- *   runs the turn on one entry. `fresh` is true when the entry is not the one
- *   the seat was on, so the caller starts a new session for it. `switch` is
- *   then `{from, to, reason}` (reason in SWITCH_REASONS) for the caller to
- *   write into that attempt's trace as `harness.switched`; null otherwise.
- * @param {(entry, {limit}) => Promise<{release?: Function}|{unavailable: string}>} [args.acquire]
- *   asked before each attempt; `{unavailable}` skips the entry for this turn
- *   (its cap is full, the host holds it). `release` runs when the attempt
- *   settles. Default: every entry is available.
- * @param {(error) => string|null} [args.classify]  the failure kind; default failureKindOf
- * @param {(skip: {entry, reason, blocked}) => void} [args.onSkip]  per skipped entry
- * @returns {Promise<{result, entry, index, state, attempts}>}
- *   On failure it rejects with the failure that ended the turn, carrying
- *   `harnessState` (persist it as on success) and `harnessAttempts`.
- */
-export const runTurnWithFallback = async ({
-  plan, policy, state, now, attempt, acquire = async () => ({}), classify = failureKindOf, onSkip = () => {},
-}) => {
-  if (!plan?.chain?.length) fail('runTurnWithFallback needs a validated plan');
-  if (!Number.isFinite(now)) fail('runTurnWithFallback needs now');
-  const current = stateFor(plan, state);
-  const { probing, order } = turnOrder(plan, current, now);
-  const was = plan.chain[current.active];
-  const attempts = [];
-  let lastKind = null;
-  let probeKind = null;
-  let lastError = null;
-  const skip = (entry, reason, blocked) => {
-    attempts.push({ entry: entryLabel(entry), outcome: blocked ? 'blocked' : 'unavailable', reason });
-    try { onSkip({ entry, reason, blocked }); } catch { /* a listener never fails a turn */ }
-  };
-
-  const cooldownOf = (kind) => PROBE_COOLDOWN_MS[kind] ?? PROBE_COOLDOWN_MS.quota;
-  const failWith = (error, next) => {
-    error.harnessState = next;
-    error.harnessAttempts = attempts;
-    return error;
-  };
-
-  for (const index of order) {
-    const entry = plan.chain[index];
-    const rule = blockedBy(entry, policy);
-    if (rule) { skip(entry, rule.reason, true); continue; }
-    // eslint-disable-next-line no-await-in-loop
-    const slot = await acquire(entry, { limit: limitFor(entry, policy) });
-    if (typeof slot?.unavailable === 'string') { skip(entry, slot.unavailable, false); continue; }
-    const fresh = index !== current.active;
-    // Why this attempt is not on the seat's entry: what failed above it, a
-    // probe moving up, or the entries above it skipped.
-    let reason = null;
-    if (fresh) reason = index < current.active ? 'probe' : (lastKind || 'blocked');
-    try {
-      // eslint-disable-next-line no-await-in-loop
-      const result = await attempt(entry, {
-        index, fresh, probing, switch: fresh ? { from: was, to: entry, reason } : null,
-      });
-      attempts.push({ entry: entryLabel(entry), outcome: 'ok' });
-      const next = { ...current, active: index };
-      if (fresh) {
-        const why = index < current.active ? 'recovered' : reason;
-        next.since = iso(now);
-        next.reason = why;
-        next.history = [...current.history, { at: iso(now), from: entryLabel(was), to: entryLabel(entry), reason: why }]
-          .slice(-HISTORY_LIMIT);
-      }
-      // Back on the primary there is nothing to probe. On a fallback, the
-      // next probe waits out the cooldown of what failed above it this turn;
-      // a turn that simply stayed put keeps the probe time it had.
-      if (index === 0) next.nextProbeAt = null;
-      else if (probeKind || fresh) next.nextProbeAt = now + cooldownOf(probeKind || lastKind);
-      return { result, entry, index, attempts, state: next };
-    } catch (error) {
-      const kind = classify(error);
-      attempts.push({ entry: entryLabel(entry), outcome: 'failed', kind: kind || null });
-      const probeFailed = probing && index < current.active;
-      if (probeFailed && probeKind === null) probeKind = kind || 'unnamed';
-      // Not a reason to change harness: the turn fails as it would have with
-      // no fallback configured, and the seat stays where it was. A probe that
-      // failed only for want of an answer (PROBE_CARRY_KINDS) carries on to
-      // the seat's own entry; any other probe failure ends the turn too.
-      const carries = probeFailed ? PROBE_CARRY_KINDS.includes(kind) : FALLBACK_KINDS.includes(kind);
-      if (!carries) {
-        // A probe failed this turn, so the primary rests again whatever ended
-        // the turn; otherwise the next turn would probe it straight away.
-        const next = probeKind ? { ...current, nextProbeAt: now + cooldownOf(probeKind) } : current;
-        throw failWith(error, next);
-      }
-      // Only a failure at or below the seat's entry is a reason to move down
-      // from it; a probe's failures above it are the probe's own (probeKind).
-      if (FALLBACK_KINDS.includes(kind) && index >= current.active) lastKind = kind;
-      lastError = error;
-    } finally {
-      try { slot?.release?.(); } catch { /* releasing never fails a turn */ }
-    }
-  }
-  // Nothing served. Stay on the entry the seat was on and push the probe out,
-  // so the next turn does not go straight back to an entry that just failed.
-  const next = { ...current };
-  if (current.active > 0 && (lastKind || probeKind)) next.nextProbeAt = now + cooldownOf(probeKind || lastKind);
-  const summary = attempts.map((a) => (a.outcome === 'failed' ? `${a.entry} ${a.kind || 'failed'}` : `${a.entry} ${a.outcome} (${a.reason})`)).join(', ');
-  if (lastError) throw failWith(lastError, next);
-  // Every entry was skipped: by policy alone it cannot run at all; with any
-  // entry merely unavailable it may run once a slot frees, and is retryable.
-  const onlyBlocked = attempts.every((a) => a.outcome === 'blocked');
-  throw failWith(new RunFailure(onlyBlocked ? 'unsupported' : 'capacity', `no entry in the run config could run: ${summary}`), next);
-};

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

@@ -1,22 +0,0 @@
-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

@@ -1,269 +0,0 @@
-/**
- * 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 ──────────────────────────────────────────────────────
-
-// lstart is printed in local time with no offset, which repeats an hour when
-// daylight saving ends. In UTC it never repeats; `startedMs` reads it as UTC.
-const PS_ENV = { ...process.env, LC_ALL: 'C', TZ: 'UTC' };
-
-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; }
-};
-
-/** A row's `started` as epoch ms. */
-export const startedMs = (started) => Date.parse(`${started} GMT`);
-
-/** 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;
-
-/** Several processes as they are now, in one ps call; a gone pid has no row. null when ps is unavailable. */
-export const readProcesses = (pids) => (pids.length ? ps(['-o', 'pid=,ppid=,lstart=', '-p', pids.join(',')]) : []);
-
-/** 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;