@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/collective/capture-slots.mjs

@@ -0,0 +1,234 @@
+/**
+ * lib/collective/capture-slots.mjs — bound the capture workers a machine runs.
+ *
+ * Every Stop/PreCompact on the machine spawns a detached capture worker, and
+ * each worker runs one or two `claude --print` passes (hundreds of MB of RSS
+ * apiece). With no ceiling, a burst of session ends — or any loop that feeds
+ * the hook — becomes an unbounded fan-out of model processes. Two locks keep it
+ * bounded:
+ *
+ *   - SLOT locks — `slot-<i>.lock` for i < max. A worker must hold one to run
+ *     its passes, so at most `max` capture workers do model work machine-wide.
+ *   - SESSION locks — `session-<id>.lock`. One session is captured by at most
+ *     one worker at a time (a PreCompact and the Stop that follows it must not
+ *     distil the same transcript twice in parallel).
+ *
+ * Both are O_EXCL files (`{flag:"wx"}` — the lock idiom registered in
+ * scripts/ci/check-durable-write-seam.mjs) under ONE machine-wide directory, so
+ * two agent installs on a machine share the ceiling. A lock records its holder's
+ * pid; a lock whose pid is dead (or which is older than `maxAgeMs`, covering
+ * pid reuse) is reclaimed. Reclaim re-reads the lock and deletes it only if it
+ * still holds the exact bytes judged stale, so a lock freshly re-taken by
+ * another reclaimer is not deleted; the residual window between that read and
+ * the unlink can at worst admit one extra worker, never lose the ceiling.
+ *
+ * Expected failure is a returned `{ok:false, error}`; nothing here throws.
+ *
+ * @module lib/collective/capture-slots
+ */
+
+"use strict";
+
+import { mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Default machine-wide ceiling on capture workers doing model work. */
+export const DEFAULT_MAX_CONCURRENT = 2;
+/** Default time a worker waits for a slot before recording a skipped capture. */
+export const DEFAULT_QUEUE_WAIT_MS = 30_000;
+/** Poll interval while queued for a slot. */
+export const DEFAULT_POLL_MS = 1_000;
+/**
+ * A lock older than this is stale even if its pid is alive (the pid was
+ * reused). Well above a worker's worst case: distil (60s) + reflect (90s) +
+ * index + queue wait.
+ */
+export const DEFAULT_LOCK_MAX_AGE_MS = 15 * 60_000;
+/** A lock with unreadable content younger than this is a holder mid-write, not a corpse. */
+const UNREADABLE_GRACE_MS = 10_000;
+
+/**
+ * The machine-wide lock directory. `MAESTRO_CAPTURE_LOCK_DIR` overrides it
+ * (tests, and a machine that wants the locks elsewhere).
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string}
+ */
+export function captureLockDir(env = process.env) {
+  const override = env && env.MAESTRO_CAPTURE_LOCK_DIR;
+  return override && String(override).trim() ? String(override) : join(homedir(), ".claude", "maestro-capture-locks");
+}
+
+/**
+ * The configured ceiling, clamped to a positive integer. Absent/invalid → default.
+ * @param {object} [cfg] collective config
+ * @returns {number}
+ */
+export function maxConcurrentFrom(cfg) {
+  const n = Number(cfg && cfg.captureMaxConcurrent);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_MAX_CONCURRENT;
+}
+
+/**
+ * The configured queue wait in ms, clamped to >= 0. Absent/invalid → default.
+ * @param {object} [cfg] collective config
+ * @returns {number}
+ */
+export function queueWaitFrom(cfg) {
+  const n = Number(cfg && cfg.captureQueueWaitMs);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_QUEUE_WAIT_MS;
+}
+
+/** Is `pid` a live process? EPERM means alive (someone else's process). */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return !!err && err.code === "EPERM";
+  }
+}
+
+function sanitize(id) {
+  const s = String(id || "").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128);
+  return s || "unknown";
+}
+
+/** Path of the session lock for `sessionId`. */
+export function sessionLockPath(dir, sessionId) {
+  return join(dir, `session-${sanitize(sessionId)}.lock`);
+}
+
+/** Path of slot `i`. */
+export function slotLockPath(dir, i) {
+  return join(dir, `slot-${i}.lock`);
+}
+
+/**
+ * Is the lock whose raw bytes are `raw` (mtime `mtimeMs`) stale at `nowMs`?
+ * @returns {boolean}
+ */
+function isStale(raw, mtimeMs, nowMs, deps) {
+  let holder = null;
+  try { holder = JSON.parse(raw); } catch { holder = null; }
+  if (!holder || !Number.isInteger(holder.pid)) {
+    // Empty/corrupt: a holder between open(wx) and write, or a crashed one.
+    return nowMs - mtimeMs > UNREADABLE_GRACE_MS;
+  }
+  const acquired = Date.parse(holder.acquiredAt || "");
+  const ageMs = Number.isFinite(acquired) ? nowMs - acquired : nowMs - mtimeMs;
+  if (ageMs > deps.maxAgeMs) return true;
+  return !deps.isAlive(holder.pid);
+}
+
+/**
+ * Try once to take the O_EXCL lock at `lockPath`, reclaiming a stale one.
+ *
+ * @param {string} lockPath
+ * @param {{pid?:number, sessionId?:string}} [owner]
+ * @param {{now?:()=>number, isAlive?:(pid:number)=>boolean, maxAgeMs?:number}} [deps]
+ * @returns {{ok:true, lockPath:string, release:()=>boolean, reclaimed:boolean} |
+ *           {ok:false, error:{code:"held"|"io", message:string, holder?:object}}}
+ */
+export function tryAcquireLock(lockPath, owner = {}, deps = {}) {
+  const d = {
+    now: typeof deps.now === "function" ? deps.now : Date.now,
+    isAlive: typeof deps.isAlive === "function" ? deps.isAlive : pidAlive,
+    maxAgeMs: Number.isFinite(deps.maxAgeMs) ? deps.maxAgeMs : DEFAULT_LOCK_MAX_AGE_MS,
+  };
+  const pid = Number.isInteger(owner.pid) ? owner.pid : process.pid;
+  const token = randomBytes(8).toString("hex");
+  const dir = dirname(lockPath);
+  try { mkdirSync(dir, { recursive: true }); } catch (err) {
+    return { ok: false, error: { code: "io", message: `lock dir: ${err && err.message}` } };
+  }
+  let reclaimed = false;
+  // Two attempts: the first may find a stale lock and reclaim it; the second
+  // takes the freed name (or loses it to a concurrent reclaimer, which is "held").
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      writeFileSync(lockPath, JSON.stringify({ pid, sessionId: owner.sessionId || "", token, acquiredAt: new Date(d.now()).toISOString() }), { flag: "wx" });
+      const release = () => {
+        try {
+          const cur = JSON.parse(readFileSync(lockPath, "utf8"));
+          if (!cur || cur.token !== token) return false; // reclaimed from us after we went stale — not ours to delete
+          unlinkSync(lockPath);
+          return true;
+        } catch {
+          return false; // already gone (reclaimed or cleaned) — nothing to release
+        }
+      };
+      return { ok: true, lockPath, release, reclaimed };
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") {
+        return { ok: false, error: { code: "io", message: `lock ${lockPath}: ${err && err.message}` } };
+      }
+    }
+    let raw = "";
+    let mtimeMs = 0;
+    try {
+      raw = readFileSync(lockPath, "utf8");
+      mtimeMs = statSync(lockPath).mtimeMs;
+    } catch {
+      continue; // the holder released between our create and read — retry the create
+    }
+    if (!isStale(raw, mtimeMs, d.now(), d)) {
+      let holder = null;
+      try { holder = JSON.parse(raw); } catch { holder = null; }
+      return { ok: false, error: { code: "held", message: `lock ${lockPath} is held`, holder: holder || undefined } };
+    }
+    try {
+      // Delete only the exact stale bytes we judged; a lock re-taken since is left alone.
+      if (readFileSync(lockPath, "utf8") === raw) { unlinkSync(lockPath); reclaimed = true; }
+    } catch { /* someone else reclaimed it first — the retry below races for the name fairly */ }
+  }
+  return { ok: false, error: { code: "held", message: `lock ${lockPath} is held (lost the reclaim race)` } };
+}
+
+/**
+ * Take any free slot among `max`, once.
+ * @param {string} dir
+ * @param {number} max
+ * @param {object} [owner]
+ * @param {object} [deps] as {@link tryAcquireLock}
+ * @returns {{ok:true, slot:number, release:()=>boolean, reclaimed:boolean} |
+ *           {ok:false, error:{code:"no-slot"|"io", message:string}}}
+ */
+export function tryAcquireSlot(dir, max, owner = {}, deps = {}) {
+  let ioError = null;
+  for (let i = 0; i < max; i++) {
+    const r = tryAcquireLock(slotLockPath(dir, i), owner, deps);
+    if (r.ok) return { ok: true, slot: i, release: r.release, reclaimed: r.reclaimed };
+    if (r.error.code === "io") ioError = r.error;
+  }
+  if (ioError) return { ok: false, error: ioError };
+  return { ok: false, error: { code: "no-slot", message: `all ${max} capture slots are held` } };
+}
+
+/**
+ * Wait up to `waitMs` for a slot, polling. Resolves `{ok:false, error:{code:"no-slot"}}`
+ * when the wait runs out — the caller records the skipped capture.
+ * @param {string} dir
+ * @param {number} max
+ * @param {object} [owner]
+ * @param {{waitMs?:number, pollMs?:number, sleep?:(ms:number)=>Promise<void>, now?:()=>number}} [opts]
+ *        plus the {@link tryAcquireLock} deps
+ * @returns {Promise<{ok:true, slot:number, release:()=>boolean, waitedMs:number} |
+ *                   {ok:false, error:{code:string, message:string}, waitedMs:number}>}
+ */
+export async function acquireSlotQueued(dir, max, owner = {}, opts = {}) {
+  const now = typeof opts.now === "function" ? opts.now : Date.now;
+  const sleep = typeof opts.sleep === "function" ? opts.sleep : (ms) => new Promise((r) => setTimeout(r, ms));
+  const waitMs = Number.isFinite(opts.waitMs) ? Math.max(0, opts.waitMs) : DEFAULT_QUEUE_WAIT_MS;
+  const pollMs = Number.isFinite(opts.pollMs) && opts.pollMs > 0 ? opts.pollMs : DEFAULT_POLL_MS;
+  const start = now();
+  for (;;) {
+    const r = tryAcquireSlot(dir, max, owner, opts);
+    if (r.ok) return { ...r, waitedMs: now() - start };
+    if (r.error.code !== "no-slot") return { ...r, waitedMs: now() - start };
+    if (now() - start >= waitMs) return { ...r, waitedMs: now() - start };
+    await sleep(pollMs);
+  }
+}

package/lib/collective/capture.mjs

@@ -22,7 +22,7 @@
 import { spawnSync } from "node:child_process";
 import { normalizeCard, appendCards, repoLabel } from "./cards.mjs";
 import { isRepoDenied } from "./config.mjs";
-import { resolveClaudeBin, daemonClaudeArgs, augmentedPath } from "../claude-bin.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
 
 const DISTILL_TIMEOUT_MS = 60_000;
 const MAX_TRANSCRIPT_CHARS = 16_000;
@@ -118,13 +118,15 @@ export function extractCardsFromModelOutput(text) {
 /** Default distiller: spawn a cheap `claude --print` pass. Fail-open → "". */
 export function defaultDistiller(prompt, opts = {}) {
   try {
-    const model = opts.model || "haiku";
-    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
-    const res = spawnSync(resolveClaudeBin(), args, {
-      input: prompt,
+    // argv + env from the runtime adapter (lane "capture"): --print --model <m>
+    // <daemon MCP args>, prompt on stdin, PATH augmented.
+    const spec = buildSpawn({ lane: "capture", model: opts.model || "haiku", prompt, mcp: {}, env: process.env });
+    if (!spec.ok) return "";
+    const res = spawnSync(spec.bin, spec.argv, {
+      input: spec.stdin,
       encoding: "utf8",
       timeout: DISTILL_TIMEOUT_MS,
-      env: { ...process.env, PATH: augmentedPath() },
+      env: spec.env,
       maxBuffer: 8 * 1024 * 1024,
     });
     if (res.status === 0 && res.stdout) return res.stdout;

package/lib/collective/config.mjs

@@ -27,6 +27,8 @@ export const DEFAULTS = Object.freeze({
   captureOn: ["Stop", "PreCompact"],
   minTurnsToCapture: 2,
   maxCardsPerSession: 12,
+  captureMaxConcurrent: 2,
+  captureQueueWaitMs: 30000,
   repoDenylist: [],
   digestBudgetTokens: 1500,
   recencyHalfLifeDays: 30,

package/lib/collective/global-config.mjs

@@ -200,14 +200,25 @@ export function buildIdentityClaudeMd(agentJson, o = {}) {
  * Default command is the bare `cohort-mcp` (the global npm install); a caller
  * that knows it is not on PATH passes `{command, args}` (e.g. the current node
  * + this package's bin/cohort-mcp.mjs) so the server still starts. Pure.
+ *
+ * `inheritEnv` (CF-22, W5-B): the Cohort Engine gives no MCP server a
+ * credential its entry does not name, so the entry names the org credential
+ * cohort-mcp resolves from the environment (lib/org/client.mjs, both brands —
+ * bin/cohort-mcp.mjs bridges NEOLITH_* at boot). An enrolled seat's cohort-mcp
+ * reads its token from config/org.yaml first; the list keeps an env-only seat
+ * working. The claude binary tolerates the key; `claude mcp add-json` drops it,
+ * so global-setup's verify step falls back to the JSON merge, which keeps it.
  * @param {string} agentRoot @param {{command?:string, args?:string[]}} [o]
  */
 export function cohortMcpEntry(agentRoot, o = {}) {
   const command = o.command ? String(o.command) : "cohort-mcp";
   const args = Array.isArray(o.args) ? o.args.map(String) : [];
-  return { command, args, env: { COHORT_AGENT_ROOT: String(agentRoot || "") } };
+  return { command, args, env: { COHORT_AGENT_ROOT: String(agentRoot || "") }, inheritEnv: [...COHORT_MCP_INHERIT_ENV] };
 }
 
+/** The org credential names cohort-mcp's entry inherits (= lib/engine/context/child-env.mjs ORG_CREDENTIAL_ENV). */
+export const COHORT_MCP_INHERIT_ENV = Object.freeze(["COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "NEOLITH_API_TOKEN", "NEOLITH_TOKEN", "NEOLITH_API_KEY"]);
+
 function clone(v) { return JSON.parse(JSON.stringify(v)); }
 function isObj(v) { return v && typeof v === "object" && !Array.isArray(v); }
 
@@ -305,6 +316,57 @@ export function mergeSessionSettings(settings, o = {}) {
   return { settings: out, changes };
 }
 
+// ---------------------------------------------------------------------------
+// State-YAML gates (2026-09): the two hooks that keep an agent's state/queues,
+// state/dashboards and state/indexes YAML parseable and un-clobbered. They live
+// in the SEAT's .claude/settings.json (commands are seat-relative and only make
+// sense inside an agent repo), never in ~/.claude. A hand edit to that file does
+// not survive a fresh checkout (the scaffold copy is what `create` ships) or an
+// upgrade (settings.json is not on the upgrade path), so the scaffold carries
+// them for new seats and `global-setup` — which `upgrade` runs as a post-step —
+// merges them onto existing ones with this helper. Pure; I/O is in bin/maestro.
+// ---------------------------------------------------------------------------
+
+/** The two hook groups, in the exact shape the scaffold .claude/settings.json carries. */
+export const STATE_YAML_GATE_HOOKS = Object.freeze([
+  Object.freeze({
+    event: "PreToolUse",
+    matcher: "Write|Edit",
+    marker: "scripts/hooks/pre-write-yaml-validate.mjs",
+    command: "node ./scripts/hooks/pre-write-yaml-validate.mjs",
+  }),
+  Object.freeze({
+    event: "PostToolUse",
+    matcher: "Bash|Write|Edit",
+    marker: "scripts/hooks/validate-state-yaml.sh",
+    command: "./scripts/hooks/validate-state-yaml.sh",
+  }),
+]);
+
+/**
+ * Merge the state-YAML gate hook groups into a seat's settings.json object, once.
+ * Presence is judged by the script marker anywhere under the event (any matcher),
+ * so an operator who already wired the script by hand is left alone. Existing
+ * groups, permissions and every other key are preserved. Idempotent. Pure.
+ *
+ * @param {object} settings  parsed .claude/settings.json ({} / null when absent)
+ * @returns {{ settings: object, added: string[] }}  added = "PreToolUse:pre-write-yaml-validate" ...
+ */
+export function mergeStateYamlGateHooks(settings) {
+  const out = isObj(settings) ? clone(settings) : {};
+  const added = [];
+  if (!isObj(out.hooks)) out.hooks = {};
+  for (const g of STATE_YAML_GATE_HOOKS) {
+    if (!Array.isArray(out.hooks[g.event])) out.hooks[g.event] = [];
+    const present = out.hooks[g.event].some((grp) =>
+      grp && Array.isArray(grp.hooks) && grp.hooks.some((h) => h && typeof h.command === "string" && h.command.includes(g.marker)));
+    if (present) continue;
+    out.hooks[g.event].push({ matcher: g.matcher, hooks: [{ type: "command", command: g.command }] });
+    added.push(`${g.event}:${basename(g.marker).replace(/\.(mjs|sh)$/, "")}`);
+  }
+  return { settings: out, added };
+}
+
 /** Build the machine pointer object. */
 export function buildPointer(repoRoot, agentName, nowMs) {
   return {

package/lib/collective/loop-guard.mjs

@@ -0,0 +1,155 @@
+/**
+ * lib/collective/loop-guard.mjs — keep the collective layer from capturing itself.
+ *
+ * The global hooks (`maestro global-setup`) fire on EVERY Claude Code session on
+ * the machine, and the capture worker's distiller, the reflect reviewer and the
+ * skill curator are themselves `claude --print` sessions. Without an exemption
+ * each of those children's Stop hook captures ITS OWN transcript — whose content
+ * is the capture prompt — which spawns another worker, whose children stop and
+ * capture again. That is a fork-bomb: nothing in the chain terminates it.
+ *
+ * Two independent signals mark a session as the collective layer's own child:
+ *
+ *   1. ENV — every collective spawn carries {@link COLLECTIVE_CHILD_ENV}=1
+ *      (set by the runtime adapter for the capture/reflect/curator lanes, and by
+ *      the capture worker for its whole process tree). The hook classifies such
+ *      a session as kind `collective` and does nothing for it.
+ *   2. CONTENT — if the env did not propagate (an older runtime, a wrapper that
+ *      scrubs the environment), the transcript's FIRST user message is one of
+ *      the collective prompts. Those prompts are this module's own text, so the
+ *      opener is a reliable fingerprint; a human session does not open with it.
+ *
+ * Pure except {@link readTranscriptHead}, which reads a bounded prefix of a file.
+ *
+ * @module lib/collective/loop-guard
+ */
+
+"use strict";
+
+import { openSync, readSync, closeSync } from "node:fs";
+
+/** The env marker every `claude` process spawned by the collective layer carries. */
+export const COLLECTIVE_CHILD_ENV = "MAESTRO_COLLECTIVE_CHILD";
+
+/**
+ * The opening line of each collective prompt. A drift test pins each one to its
+ * prompt builder (capture.buildDistillPrompt, reflect.buildReviewPrompt,
+ * curator.buildConsolidationPrompt), so a reworded prompt cannot silently disarm
+ * the content fallback.
+ */
+export const COLLECTIVE_PROMPT_SENTINELS = Object.freeze([
+  "You distil a finished work session into durable MEMORY CARDS",
+  "You are the self-improvement reviewer for an autonomous AI agent",
+  "You are the skill CURATOR for an autonomous AI agent",
+]);
+
+/**
+ * How much of a transcript the content fallback reads. The prompt is the first
+ * user input; SessionStart attachments (skill listings, digests) can precede it
+ * by tens of KB, so the window is generous — and one bounded read per stop.
+ */
+export const TRANSCRIPT_HEAD_BYTES = 512 * 1024;
+
+/** How far into the first user message a sentinel may start (tolerates a harness preamble). */
+const SENTINEL_WINDOW_CHARS = 2000;
+
+/**
+ * Does this environment mark a collective child?
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {boolean}
+ */
+export function isCollectiveChildEnv(env = process.env) {
+  return !!env && String(env[COLLECTIVE_CHILD_ENV] || "").trim() === "1";
+}
+
+/**
+ * The session kind the hooks act on. `collective` wins over `daemon`: a
+ * collective child spawned from a daemon session inherits MAESTRO_DAEMON=1 and
+ * must still be exempt from capture.
+ * @param {{source?:string}} [input] the hook's stdin payload
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {"collective"|"daemon"|"interactive"}
+ */
+export function classifyKind(input = {}, env = process.env) {
+  if (isCollectiveChildEnv(env)) return "collective";
+  const src = String((input && input.source) || "").toLowerCase();
+  if (src.includes("daemon") || (env && env.MAESTRO_DAEMON === "1")) return "daemon";
+  return "interactive";
+}
+
+function messageText(obj) {
+  const c = obj.content ?? (obj.message && obj.message.content);
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) {
+    return c.map((p) => (typeof p === "string" ? p : p && typeof p.text === "string" ? p.text : "")).filter(Boolean).join(" ");
+  }
+  return "";
+}
+
+/**
+ * The text of the first user message in a JSONL transcript prefix, or "".
+ * A truncated last line is simply skipped.
+ * @param {string} head
+ * @returns {string}
+ */
+export function firstUserMessage(head) {
+  if (!head) return "";
+  for (const raw of String(head).split("\n")) {
+    const line = raw.trim();
+    if (!line.startsWith("{")) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; /* a truncated/partial line is not a message */ }
+    // A `--print` prompt is recorded twice: first as the queued input
+    // (`queue-operation`/`enqueue`, ahead of any attachment lines), then as the
+    // first `user` message. Either one is the session's first user input.
+    const queued = obj.type === "queue-operation" && obj.operation === "enqueue";
+    const role = (obj.message && obj.message.role) || obj.role || obj.type || "";
+    if (role !== "user" && !queued) continue;
+    const text = messageText(obj);
+    if (text) return text;
+  }
+  return "";
+}
+
+/**
+ * Is this transcript a collective child's (its first user turn is a collective prompt)?
+ * @param {string} head a prefix of the transcript JSONL
+ * @returns {boolean}
+ */
+export function isCollectivePromptTranscript(head) {
+  const first = firstUserMessage(head).slice(0, SENTINEL_WINDOW_CHARS);
+  if (!first) return false;
+  return COLLECTIVE_PROMPT_SENTINELS.some((s) => first.includes(s));
+}
+
+/**
+ * Read at most `bytes` from the start of a file. "" when absent/unreadable.
+ * @param {string} path
+ * @param {number} [bytes]
+ * @returns {string}
+ */
+export function readTranscriptHead(path, bytes = TRANSCRIPT_HEAD_BYTES) {
+  if (!path) return "";
+  let fd = null;
+  try {
+    fd = openSync(path, "r");
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.subarray(0, n).toString("utf8");
+  } catch {
+    return ""; // no transcript → the content fallback has nothing to say; the env signal still governs
+  } finally {
+    if (fd !== null) { try { closeSync(fd); } catch { /* the read already completed or failed */ } }
+  }
+}
+
+/**
+ * Why a stop/capture event must NOT spawn a capture worker, or null when it may.
+ * @param {{kind:string, transcriptHead?:string}} o
+ * @returns {null|"collective-child-env"|"collective-child-transcript"}
+ */
+export function captureExemption({ kind, transcriptHead = "" } = {}) {
+  if (kind === "collective") return "collective-child-env";
+  if (isCollectivePromptTranscript(transcriptHead)) return "collective-child-transcript";
+  return null;
+}