@smartmemory/compose 0.4.1 → 0.5.1

package/lib/maya-identity.js

@@ -136,12 +136,26 @@ export async function provisionIdentity({ smBaseUrl, fetchFn = fetch }) {
   };
 }
 
+/** The oldest NDA version this client knows; the server names a newer one. */
+const NDA_VERSION_FLOOR = 'v1';
+
 /** Accept the beta NDA for a provisioned identity (403 `nda_required` gates
  *  every memory route until this runs — FOH-4 ledger prereq 3). */
 export async function acceptNda({ smBaseUrl, token, fetchFn = fetch }) {
-  const res = await requestJson(`${smBaseUrl}/memory/beta/nda/accept`, {
-    body: { version: 'v1' }, token, fetchFn,
+  const attempt = (version) => requestJson(`${smBaseUrl}/memory/beta/nda/accept`, {
+    body: { version }, token, fetchFn,
   });
+  let res = await attempt(NDA_VERSION_FLOOR);
+  // The NDA version is upstream's to bump, not ours to track: a 409
+  // `version_mismatch` names the version currently in force, and accepting the
+  // one the server names is the only answer that survives the next bump.
+  // FOH-7 live-fire (2026-09-06) found v1 hardcoded after upstream moved to v2 —
+  // every provisioned colleague identity failed its first turn.
+  const named = res.status === 409 && res.body?.detail?.code === 'version_mismatch'
+    ? res.body.detail.current_version : null;
+  if (typeof named === 'string' && named && named !== NDA_VERSION_FLOOR) {
+    res = await attempt(named);
+  }
   if (res.status < 200 || res.status >= 300) {
     throw new MayaIdentityError(`maya: NDA accept failed (HTTP ${res.status})`);
   }

package/lib/model-pricing.js

@@ -1,7 +1,7 @@
 /**
  * model-pricing.js — Token cost lookup and USD calculation.
  *
- * Prices are per-million tokens (MTok) as of 2025.
+ * Prices are per-million tokens (MTok) updated for COMP-FABLE-ASTRA slice 1 (2026-09).
  * Input price includes standard prompt tokens.
  * Cache write tokens (cache_creation_input_tokens) are billed at 1.25x input rate.
  * Cache read tokens (cache_read_input_tokens) are billed at 0.1x input rate.
@@ -12,6 +12,9 @@
  * Keys are matched by prefix so 'claude-sonnet-4-6' matches 'claude-sonnet-4-6-20250514' etc.
  */
 export const MODEL_PRICING = {
+  'claude-fable-5-1':  { inputPerMTok: 10,  outputPerMTok: 50 },
+  'claude-opus-5':     { inputPerMTok: 5,   outputPerMTok: 25 },
+  'claude-sonnet-5':   { inputPerMTok: 2,   outputPerMTok: 10 },
   'claude-opus-4-7':    { inputPerMTok: 5,   outputPerMTok: 25 },
   'claude-opus-4-6':    { inputPerMTok: 5,   outputPerMTok: 25 },
   'claude-sonnet-4-6':  { inputPerMTok: 3,   outputPerMTok: 15 },

package/lib/output-gate.js

@@ -0,0 +1,81 @@
+/** Pure output-gate decision. Callers supply current recorded step states. */
+import { ownField, normalizeOwnedPath, validateGateConfig, validateWaveAdmission, profilesDigest } from './pipeline-profiles.js';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const strings = value => Array.isArray(value) && value.every(v => typeof v === 'string');
+function validateDecision(decision, review, validator, { executeProfile, executeProvider }) {
+  const findings = [];
+  const add = (code, message) => findings.push({ code, message });
+  const tasks = ownField(decision, validator.tasks_field ?? 'tasks');
+  const findingShape = f => object(f) && typeof f.severity === 'string' && strings(f.files)
+    && typeof f.claim === 'string' && typeof f.evidence === 'string';
+  const taskShape = t => object(t) && typeof t.id === 'string' && t.id.length > 0
+    && typeof t.description === 'string' && strings(t.files_owned) && strings(t.files_read)
+    && strings(t.depends_on) && (t.tier_rationale === undefined || typeof t.tier_rationale === 'string');
+  if (!object(decision) || !['repair', 'implement', 'complete', 'blocked'].includes(decision.action)
+    || typeof decision.rationale !== 'string' || typeof decision.blocking !== 'boolean'
+    || !Number.isInteger(decision.open_count) || decision.open_count < 0
+    || !Array.isArray(decision.open_findings) || !decision.open_findings.every(findingShape)
+    || !Array.isArray(decision.addressed_findings) || !decision.addressed_findings.every(findingShape)
+    || !Array.isArray(tasks) || !tasks.every(taskShape)) {
+    add('WAVE_DECISION_SHAPE', 'Invalid WaveDecision/task/finding shape');
+    return findings;
+  }
+  if (decision.open_count !== decision.open_findings.length) add('WAVE_OPEN_COUNT_MISMATCH', 'open_count differs from open_findings length');
+  if (typeof review?.blocking !== 'boolean' || review.blocking !== decision.blocking) add('WAVE_BLOCKING_MISMATCH', 'blocking differs from recorded review');
+  if (decision.action === 'complete' && (decision.open_count !== 0 || decision.blocking)) add('WAVE_COMPLETE_WITH_OPEN_FINDINGS', 'Complete requires no open findings and no blocking');
+  if (decision.action === 'blocked' && decision.open_count === 0) add('WAVE_BLOCKED_WITHOUT_FINDINGS', 'Blocked requires open findings');
+  if (['repair', 'implement'].includes(decision.action)) {
+    if (tasks.length < 1 || tasks.length > 6) add('WAVE_REPAIR_EMPTY', 'Implementation/repair requires 1–6 tasks');
+    findings.push(...validateWaveAdmission(executeProfile, tasks,
+      { provider: executeProvider, ownership: true, independent: true }).findings);
+  }
+  if (decision.action === 'repair') {
+    try {
+      const files = new Set(decision.open_findings.flatMap(f => f.files.map(normalizeOwnedPath)));
+      for (const task of tasks) if (!task.files_owned.some(file => files.has(normalizeOwnedPath(file)))) {
+        add('WAVE_REPAIR_UNOWNED_FINDING', `Repair task ${task.id} owns no open finding file`);
+      }
+    } catch (error) { add('WAVE_DECISION_SHAPE', error.message); }
+  }
+  return findings;
+}
+/**
+ * Resolve only from current recorded source, waiting gate and configured review states.
+ * executeProfile (the configured execute entry) and executeProvider are required.
+ * reviewOutput is ignored; validators always use the configured review step's recorded output.
+ */
+export function decideGateFromOutput(config, stepOutputs, { gateStepId, gateToken, reviewOutput, ceiling, executeProfile, executeProvider } = {}) {
+  const hold = (reason, extra = {}) => ({ outcome: null, reason, ...extra });
+  try { validateGateConfig(config); }
+  catch (error) { return hold('GATE_CONFIG_INVALID', { findings: [{ code: 'GATE_CONFIG_INVALID', message: error.message }] }); }
+  if (!executeProfile || typeof executeProvider !== 'string' || !executeProvider.trim()) return hold('GATE_CONFIG_INVALID');
+  if (ceiling !== undefined) {
+    if (!Number.isFinite(ceiling.spent) || ceiling.spent < 0 || !Number.isFinite(ceiling.ceiling) || ceiling.ceiling <= 0) return hold('COST_CEILING_INVALID');
+    if (ceiling.spent > ceiling.ceiling) return hold('COST_CEILING_BREACHED', { breach: { spent: ceiling.spent, ceiling: ceiling.ceiling } });
+  }
+  const sourceState = stepOutputs?.[config.decide_from.step];
+  if (!object(sourceState) || sourceState.status !== 'succeeded' || !object(sourceState.output)) return hold('GATE_SOURCE_MISSING');
+  const gate = stepOutputs?.[gateStepId];
+  if (!object(gate) || gate.status !== 'waiting_gate' || typeof gateToken !== 'string' || !gateToken
+    || gate.gateToken !== gateToken || !Number.isInteger(gate.epoch) || gate.epoch < 0
+    || sourceState.epoch !== gate.epoch) return hold('GATE_SOURCE_STALE');
+  const output = sourceState.output;
+  const action = ownField(output, config.decide_from.field);
+  const outcome = ['approve', 'revise', 'kill'].find(key => config.decide_from[key].includes(action));
+  if (!outcome) return hold('GATE_ACTION_UNKNOWN');
+  const findings = [];
+  for (const validator of config.validators ?? []) {
+    const reviewState = stepOutputs?.[validator.review_step];
+    const review = reviewState?.status === 'succeeded' ? reviewState.output : undefined;
+    if (reviewState && reviewState.epoch !== gate.epoch) return hold('GATE_SOURCE_STALE');
+    findings.push(...validateDecision(output, review, validator, { executeProfile, executeProvider }));
+  }
+  if (findings.length) return hold('GATE_VALIDATION_FAILED', { findings });
+  return {
+    outcome, rationale: output.rationale ?? `Mapped ${String(action)} to ${outcome}`,
+    source: { step: config.decide_from.step, field: config.decide_from.field, action, gateStepId, gateToken,
+      epoch: sourceState.epoch, acceptedDispatchToken: sourceState.acceptedDispatchToken,
+      outputDigest: profilesDigest(output), output: structuredClone(output) },
+  };
+}

package/lib/pipeline-profiles.js

@@ -0,0 +1,200 @@
+/** Compose-owned sidecar schema and whole-wave admission. No dispatch or I/O. */
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import YAML from 'yaml';
+import { validateAgentString, resolveAgentConfig } from './agent-string.js';
+
+export class PipelineProfileError extends Error {
+  constructor(code, message) { super(message); this.name = 'PipelineProfileError'; this.code = code; }
+}
+const fail = (message, code = 'PIPELINE_PROFILE_INVALID') => { throw new PipelineProfileError(code, message); };
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const keys = (value, allowed) => {
+  if (!object(value) || Object.keys(value).some(key => !allowed.includes(key))) fail(`Invalid configuration fields: ${JSON.stringify(value)}`);
+};
+export function ownField(value, path) {
+  if (typeof path !== 'string' || !/^[A-Za-z_][\w]*(\.[A-Za-z_][\w]*)*$/.test(path)
+    || path.split('.').some(key => ['__proto__', 'prototype', 'constructor'].includes(key))) fail('Invalid field path');
+  for (const key of path.split('.')) {
+    if (!object(value) || !Object.hasOwn(value, key)) return undefined;
+    value = value[key];
+  }
+  return value;
+}
+export function normalizeOwnedPath(path) {
+  if (typeof path !== 'string' || !path.length || /^[\\/]|^[A-Za-z]:/.test(path)
+    || /[\0*?\[\]{}]/.test(path)) fail('Ownership requires literal repository-relative file paths', 'WAVE_OWNERSHIP_INVALID');
+  const parts = path.replaceAll('\\', '/').split('/');
+  if (parts.includes('..') || parts.some(part => part.toLowerCase() === '.git')) fail(`Unsafe ownership path: ${path}`, 'WAVE_OWNERSHIP_INVALID');
+  const normalized = posix.normalize(parts.join('/'));
+  if (normalized === '.' || normalized.endsWith('/')) fail(`Not a file path: ${path}`, 'WAVE_OWNERSHIP_INVALID');
+  return normalized;
+}
+function agent(profile, provider) {
+  if (typeof profile !== 'string' || !profile.trim() || profile.split(':').length > 3) fail('Profile must be a non-empty agent string');
+  validateAgentString(profile);
+  const resolved = resolveAgentConfig(profile);
+  if (provider && resolved.provider !== provider) fail(`Profile provider ${resolved.provider} differs from stage ${provider}`);
+  return { ...resolved, profile };
+}
+export function validateGateConfig(entry) {
+  keys(entry, ['decide_from', 'validators']);
+  keys(entry.decide_from, ['step', 'field', 'approve', 'revise', 'kill']);
+  const mapping = entry.decide_from;
+  if (typeof mapping.step !== 'string' || !mapping.step) fail('decide_from.step is required');
+  ownField({}, mapping.field);
+  const seen = new Set();
+  for (const outcome of ['approve', 'revise', 'kill']) {
+    if (!Array.isArray(mapping[outcome])) fail(`${outcome} must be a value array`);
+    for (const value of mapping[outcome]) {
+      if (typeof value !== 'string' || !value || seen.has(value)) fail('Gate values must be nonempty, disjoint strings');
+      seen.add(value);
+    }
+  }
+  if (entry.validators !== undefined && !Array.isArray(entry.validators)) fail('validators must be an array');
+  for (const validator of entry.validators ?? []) {
+    keys(validator, ['name', 'review_step', 'tasks_field']);
+    if (validator.name !== 'WaveDecision' || typeof validator.review_step !== 'string' || !validator.review_step) fail('Unknown validator or missing review_step');
+    ownField({}, validator.tasks_field ?? 'tasks');
+  }
+  return entry;
+}
+function ancestor(steps, from, gate, visited = new Set()) {
+  if (visited.has(gate)) return false;
+  visited.add(gate);
+  return (steps.find(step => step.id === gate)?.after ?? []).some(id => id === from || ancestor(steps, from, id, visited));
+}
+export function normalizePipelineProfiles(raw, spec) {
+  if (!object(raw)) fail('Profiles must be an object');
+  const parsed = typeof spec === 'string' ? YAML.parse(spec) : spec;
+  const flows = Object.values(parsed?.flows ?? {}).filter(flow => Array.isArray(flow?.steps));
+  const steps = flows.flatMap(flow => flow.steps);
+  const normalized = structuredClone(raw);
+  for (const [id, entry] of Object.entries(raw)) {
+    if (id.startsWith('_')) continue;
+    const matches = steps.filter(step => step.id === id);
+    if (!matches.length) fail(`Step ${id} not found in spec`);
+    for (const step of matches) {
+      if (object(entry) && Object.hasOwn(entry, 'decide_from')) {
+        validateGateConfig(entry);
+        if (!step.gate || step.agent || step.fanout || id === 'review_gate') fail(`Step ${id} is not an available output gate`);
+        const flowSteps = flows.find(flow => flow.steps.includes(step)).steps;
+        for (const source of [entry.decide_from.step, ...(entry.validators ?? []).map(v => v.review_step)]) {
+          if (!ancestor(flowSteps, source, id)) fail(`Source ${source} must be an ancestor of ${id}`);
+        }
+        continue;
+      }
+      if (step.gate && !step.agent && !step.fanout) fail(`Gate ${id} requires decide_from`);
+      if (object(entry)) {
+        keys(entry, ['default', 'tier_from']);
+        if (entry.tier_from !== undefined && (entry.tier_from !== 'item.tier' || step.fanout?.dispatch !== 'consumer')) fail('tier_from requires a consumer fanout and item.tier');
+      } else if (typeof entry !== 'string') fail(`Invalid profile for ${id}`);
+      for (const stage of step.fanout?.steps ?? [step]) {
+        const resolved = agent(typeof entry === 'string' ? entry : entry.default, stage.agent ?? 'claude');
+        if (step.fanout?.dispatch === 'engine' && (resolved.tier || resolved.template)) fail('Engine dispatch cannot apply Compose templates or tiers');
+        if (entry.tier_from) for (const tier of ['critical', 'standard', 'fast']) resolveConsumerProfile(entry, { tier }, resolved.provider);
+      }
+    }
+  }
+  if (raw._consumer !== undefined) {
+    if (!object(raw._consumer)) fail('_consumer must be an object');
+    for (const [id, policy] of Object.entries(raw._consumer)) {
+      keys(policy, ['ownership', 'independent', 'checkpoint_gate']);
+      if (policy.ownership !== undefined && policy.ownership !== 'item.files_owned') fail('ownership must be item.files_owned');
+      if (policy.independent !== undefined && typeof policy.independent !== 'boolean') fail('independent must be boolean');
+      const matches = steps.filter(step => step.id === id);
+      if (!matches.length) fail(`Consumer ${id} not found`);
+      for (const step of matches) {
+        if (step.fanout?.dispatch !== 'consumer') fail(`${id} is not consumer-dispatched`);
+        if ((policy.ownership || policy.checkpoint_gate) && step.fanout.isolation !== 'worktree') fail('Ownership/checkpoints require worktree isolation');
+        if (policy.checkpoint_gate !== undefined) {
+          const flow = flows.find(flow => flow.steps.includes(step));
+          const gate = flow.steps.find(s => s.id === policy.checkpoint_gate);
+          if (!gate?.gate || gate.after?.length !== 1 || gate.after[0] !== id || gate.when) fail('checkpoint_gate must be the direct unconditional merge gate');
+        }
+      }
+    }
+  }
+  if (raw._costCeiling !== undefined) {
+    const c = raw._costCeiling;
+    keys(c, ['input', 'default', 'gates']);
+    if (typeof c.input !== 'string' || !/^[A-Za-z_]\w*$/.test(c.input)
+      || !Number.isFinite(c.default) || c.default <= 0 || !Array.isArray(c.gates) || !c.gates.length
+      || c.gates.some(id => !steps.some(s => s.id === id && s.gate))) fail('Invalid _costCeiling');
+  }
+  return normalized;
+}
+/** Replacing a default must never erase the per-item routing policy. Re-preflight the result. */
+export function mergeRuntimeProfiles(normalized, runtime = {}) {
+  const result = structuredClone(normalized);
+  for (const [id, override] of Object.entries(runtime)) {
+    if (id.startsWith('_') || object(result[id]) && result[id].decide_from) fail(`Runtime override is not an agent profile: ${id}`);
+    const previous = result[id];
+    if (object(override)) {
+      keys(override, ['default', 'tier_from']);
+      if (override.tier_from !== undefined && override.tier_from !== previous?.tier_from) fail('Runtime overrides cannot change tier_from');
+    } else if (typeof override !== 'string') fail('Runtime override must be an agent profile');
+    result[id] = object(previous) ? { ...previous, default: typeof override === 'string' ? override : override.default } : structuredClone(override);
+    agent(typeof result[id] === 'string' ? result[id] : result[id].default);
+  }
+  return result;
+}
+export function resolveConsumerProfile(entry, item, provider) {
+  const resolved = agent(typeof entry === 'string' ? entry : entry?.default, provider);
+  if (!entry?.tier_from) return resolved;
+  if (entry.tier_from !== 'item.tier') fail('Unsupported tier_from');
+  const tier = ownField({ item }, entry.tier_from);
+  if (tier === undefined && !Object.hasOwn(item ?? {}, 'tier')) return resolved;
+  if (!['critical', 'standard', 'fast'].includes(tier)) fail(`Unknown item tier: ${String(tier)}`, 'WAVE_TIER_INVALID');
+  return agent(`${resolved.provider}:${resolved.template ?? ''}:${tier}`, provider);
+}
+export function validateWaveAdmission(entry, items, opts = {}) {
+  const findings = [];
+  const profiles = [];
+  const owners = new Map();
+  const add = (code, itemIndex, message) => findings.push({ code, itemIndex, message, severity: 'error' });
+  if (!Array.isArray(items)) return { ok: false, findings: [{ code: 'WAVE_INPUT_INVALID', message: 'Recorded wave input must be an array' }] };
+  items.forEach((item, itemIndex) => {
+    try { profiles.push(resolveConsumerProfile(entry, item, opts.provider)); }
+    catch (error) { add(error.code ?? 'WAVE_TIER_INVALID', itemIndex, error.message); }
+    if (opts.independent && (!Array.isArray(item?.depends_on) || item.depends_on.length)) add('WAVE_DEPENDENCIES_NOT_EMPTY', itemIndex, 'Independent tasks require empty depends_on');
+    if (opts.ownership || Object.hasOwn(item ?? {}, 'files_owned')) {
+      try {
+        if (!Array.isArray(item?.files_owned)) fail('files_owned is required', 'WAVE_OWNERSHIP_INVALID');
+        for (const file of item.files_owned.map(normalizeOwnedPath)) {
+          if (owners.has(file) && owners.get(file) !== itemIndex) add('WAVE_OWNERSHIP_CONFLICT', itemIndex, `Multiple tasks own ${file}`);
+          owners.set(file, itemIndex);
+        }
+      } catch (error) { add(error.code, itemIndex, error.message); }
+    }
+  });
+  return { ok: findings.length === 0, findings, profiles };
+}
+export function profilesDigest(normalized) {
+  const canonical = value => Array.isArray(value) ? value.map(canonical) : object(value)
+    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+  return createHash('sha256').update(JSON.stringify(canonical(normalized))).digest('hex');
+}
+/** Dispatch 2 replaces the string-only wrapper with this, after resolving spec inputs. */
+export function preflightPipelineProfiles(raw, spec, runtime = {}) {
+  const normalized = normalizePipelineProfiles(mergeRuntimeProfiles(normalizePipelineProfiles(raw, spec), runtime), spec);
+  const resolved = {};
+  const overrides = {};
+  for (const [id, entry] of Object.entries(normalized)) {
+    if (!id.startsWith('_') && !entry?.decide_from) {
+      resolved[id] = resolveConsumerProfile(entry, {});
+      if (entry.tier_from) overrides[id] = ['critical', 'standard', 'fast'].map(tier => resolveConsumerProfile(entry, { tier }));
+    }
+  }
+  const parsed = typeof spec === 'string' ? YAML.parse(spec) : spec;
+  for (const step of Object.values(parsed?.flows ?? {}).flatMap(flow => flow?.steps ?? [])) {
+    if (Object.hasOwn(normalized, step.id)) continue;
+    const stages = step.fanout?.steps ?? (step.agent ? [step] : []);
+    for (const [index, stage] of stages.entries()) {
+      const resolution = agent(stage.agent ?? 'claude');
+      if (step.fanout?.dispatch === 'engine' && (resolution.template || resolution.tier)) fail('Engine dispatch cannot apply Compose templates or tiers');
+      resolved[stages.length === 1 ? step.id : `${step.id}/${index}`] = resolution;
+    }
+  }
+  return { ok: true, normalized, resolved, profilesDigest: profilesDigest({ normalized, resolved, overrides }) };
+}

package/lib/process-termination.js

@@ -11,8 +11,35 @@
  *   alive → await leader close and group disappearance (bounded at 2 seconds).
  *
  * Grace period: `COMPOSE_CANCEL_GRACE_MS` (default 5000ms).
+ *
+ * D-TERM-1 (2026-09-07): `-pid` IS still signalled after the leader is reaped.
+ * ------------------------------------------------------------------------
+ * The open question was whether signalling the group after `close` aims at a
+ * pgid the kernel may have recycled to a stranger. It does not, for the whole
+ * window that matters:
+ *
+ *   POSIX 4.13 — "if there exists a process group whose process group ID is
+ *   equal to that process ID, the process ID shall not be reused until the
+ *   process group lifetime ends" — and a group's lifetime ends only when its
+ *   LAST member leaves.
+ *
+ * So while our group has any living member, `-pid` provably names OUR group,
+ * and a living member is exactly the condition teardown is waiting on.
+ * Measured on Darwin 25.6.0 rather than taken on faith: with the leader reaped
+ * and one grandchild left, 400,000 fork/exit cycles never got the pgid handed
+ * back (the pid space is ~100k, so that is four wraps). Emptying the group
+ * first, the same pid came back at iteration 98,102 — one full wrap.
+ *
+ * That measurement RETIRES the fear rather than confirming it: the recycled
+ * pgid needs roughly 98,000 process creations between our group emptying and
+ * our probe, inside a 2s reap deadline. It is not a millisecond race, and it
+ * is the LEAST likely reading of a group-signal failure, not the diagnosis.
+ * Keep signalling the group after close — "the group outlives the leader" is
+ * correct and load-bearing.
  */
 
+import { execFileSync } from 'node:child_process';
+
 const DEFAULT_GRACE_MS = 5000;
 
 /** Read the configured cancellation grace period. */
@@ -35,6 +62,89 @@ function graceMsFromEnv(env = process.env) {
  * @param {number} [graceMs]
  * @returns {{ close: Promise<void>, terminate: () => Promise<void>, finish: () => Promise<void> }}
  */
+/**
+ * Every process currently in `pgid`, so a group-signal failure can be
+ * attributed instead of argued about.
+ *
+ * `ps -g` is NOT portable — BSD reads it as a pgid list, procps as a
+ * session/group list — so the whole table is read and filtered here.
+ *
+ * @returns {Array<object> | {error: string}} never throws: this runs on an
+ *   error path, where a second failure would replace the first one.
+ */
+function groupMembers(pgid) {
+  try {
+    const table = execFileSync('ps', ['-eo', 'pid=,pgid=,ppid=,uid=,comm='], {
+      encoding: 'utf8', timeout: 2000, maxBuffer: 4 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return table.split('\n')
+      .map((line) => line.trim().split(/\s+/))
+      .filter((f) => f.length >= 5 && Number(f[1]) === pgid)
+      // `comm` is last and may contain spaces (it is a path), so it takes the tail.
+      .map((f) => ({ pid: Number(f[0]), ppid: Number(f[2]), uid: Number(f[3]), comm: f.slice(4).join(' ') }));
+  } catch (e) {
+    return { error: e?.code ?? e?.message ?? 'unknown' };
+  }
+}
+
+/**
+ * Why a group signal failed, stamped on the error itself.
+ *
+ * A non-ESRCH failure here is rethrown, relabelled `CANCELLATION_UNCONFIRMED`
+ * by `terminate`, and reaches the caller carrying only Node's bare message —
+ * `kill EPERM` and nothing else, which is unattributable after the fact: two
+ * call sites send group signals.
+ *
+ * WHAT EPERM MEANS HERE. Measured on Darwin 25.6.0: `kill(-pgid, 0)` against a
+ * group of processes we may not signal answers EPERM, not ESRCH. So EPERM says
+ * exactly one thing — *a group with this pgid exists and every member refused
+ * our signal*. Three sub-causes, deliberately unranked except for the last:
+ *
+ *   1. a member runs as another uid (a tool child that escalated), or
+ *   2. a policy — MAC / sandbox — refused the signal for a member that shares
+ *      our uid, so "same uid" does NOT rule this out, or
+ *   3. our group is gone and a stranger holds a recycled pgid.
+ *
+ * (3) was the original hypothesis and is the LEAST likely of the three: per
+ * D-TERM-1 above it needs ~98,000 process creations inside a 2s deadline.
+ *
+ * `killGroupMembers` is what actually separates them, and it is why this
+ * function exists at all: uids other than ours point at (1) or (2), and
+ * processes plainly unrelated to the run point at (3).
+ *
+ * `killLeader` is kept but is NOT the discriminator it shipped as. After
+ * `close` the leader has been reaped, so it reads `gone` in every realistic
+ * recurrence; `ours` / `not-ours` need the same implausible wrap as (3). Do not
+ * read `not-ours` as "recycled pgid confirmed" — that inference was wrong.
+ *
+ * Diagnostic only: it changes no control flow and rethrows the same error.
+ */
+function describeGroupSignalFailure(error, { site, pid, signal }) {
+  error.killSite = site;
+  error.killTarget = -pid;
+  error.killSignal = signal;
+  error.killerPgid = typeof process.getpgrp === 'function' ? process.getpgrp() : null;
+  try {
+    // The LEADER as a plain pid, not the group. Probing must never throw out of
+    // an error path, so every outcome is recorded rather than raised.
+    process.kill(pid, 0);
+    error.killLeader = 'ours';
+  } catch (probe) {
+    error.killLeader = probe.code === 'EPERM' ? 'not-ours' : (probe.code === 'ESRCH' ? 'gone' : probe.code);
+  }
+  error.killGroupMembers = groupMembers(pid);
+  const members = Array.isArray(error.killGroupMembers)
+    ? (error.killGroupMembers.length
+      ? error.killGroupMembers.map((m) => `${m.pid}/uid ${m.uid} ${m.comm}`).join(', ')
+      : 'none')
+    : `unreadable (${error.killGroupMembers.error})`;
+  error.message = `${error.message} (${site} ${String(signal)} → pgid ${pid}; `
+    + `leader ${error.killLeader}; our pgid ${error.killerPgid}; our uid ${process.getuid?.() ?? '?'}; `
+    + `group members: ${members})`;
+  return error;
+}
+
 export function processTermination(child, group, graceMs = graceMsFromEnv(), reapTimeoutMs = 2000) {
   let closed = false;
   const close = new Promise((resolve) => child.once('close', () => { closed = true; resolve(); }));
@@ -45,7 +155,9 @@ export function processTermination(child, group, graceMs = graceMsFromEnv(), rea
       try {
         process.kill(-child.pid, signal);
       } catch (error) {
-        if (error.code !== 'ESRCH') throw error;
+        if (error.code !== 'ESRCH') {
+          throw describeGroupSignalFailure(error, { site: 'send', pid: child.pid, signal });
+        }
       }
     } else if (!closed) {
       child.kill(signal);
@@ -61,15 +173,21 @@ export function processTermination(child, group, graceMs = graceMsFromEnv(), rea
       return true;
     } catch (error) {
       if (error.code === 'ESRCH') return false;
-      throw error;
+      throw describeGroupSignalFailure(error, { site: 'alive', pid: child.pid, signal: 0 });
     }
   };
 
   const terminate = () => {
     teardown ??= (async () => {
-      send('SIGTERM');
       let timer;
       try {
+        // INSIDE the try. Outside it, a refused opening SIGTERM escaped with
+        // Node's bare `EPERM` as its code, so the one failure the caller is
+        // told to expect from a group signal — CANCELLATION_UNCONFIRMED, per
+        // `describeGroupSignalFailure` — was the one code it never got. Only
+        // the later `alive()` and SIGKILL sites were ever labelled. Found by
+        // the D-TERM-1 test below, which is the first test this path ever had.
+        send('SIGTERM');
         await Promise.race([
           new Promise((resolve) => { timer = setTimeout(resolve, graceMs); }),
           // A leader that closed while its group lives must still wait out the