@cohortapp/agent-sdk 2.18.4 → 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/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/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;
+}

package/lib/runtime/adapter.mjs

@@ -118,6 +118,7 @@ import { buildClaudeArgs } from "../session/launch-args.mjs";
 import { cohortTierFor } from "../model-router/catalog.mjs";
 import { DEFAULT_LLM_BASE_URL, apiKeyHelperCommand } from "../org/llm-token.mjs";
 import { COHORT_BACKEND } from "../rate-guard.mjs";
+import { COLLECTIVE_CHILD_ENV } from "../collective/loop-guard.mjs";
 
 /** Engines a seat can name in `runtime.engine`. */
 export const ENGINES = Object.freeze(["claude", "cohort"]);
@@ -201,6 +202,10 @@ export function subscriptionAuth(env) {
  * fragments `x = {perm, mcp, knobs}`; `stdin` says whether the prompt is
  * written to the child's stdin instead of argv; `posture` names the env shape;
  * `retarget` says whether a router retarget is legal on the lane.
+ * `collectiveChild` marks the collective layer's own model passes: their env
+ * carries MAESTRO_COLLECTIVE_CHILD=1 so the global Stop/PreCompact hook does not
+ * capture the child's transcript (lib/collective/loop-guard.mjs) — without it,
+ * every capture spawns a session whose end spawns another capture.
  */
 const LANES = Object.freeze({
   dispatcher: {
@@ -232,15 +237,15 @@ const LANES = Object.freeze({
     argv: (i) => ["--print", "--model", i.model, "-p", i.prompt],
   },
   capture: {
-    posture: "path", stdin: true, retarget: false,
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
     argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
   },
   reflect: {
-    posture: "path", stdin: true, retarget: false,
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
     argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
   },
   curator: {
-    posture: "path", stdin: true, retarget: false,
+    posture: "path", stdin: true, retarget: false, collectiveChild: true,
     argv: (i, x) => ["--print", "--model", i.model, ...x.mcp],
   },
   enrich: {
@@ -394,7 +399,12 @@ export function buildSpawn(i = {}, deps = {}) {
     daemonArgs: deps.daemonArgs || daemonClaudeArgs,
     augmentedPath: deps.augmentedPath || augmentedPath,
   };
-  const input = { ...i, env: i.env === undefined ? process.env : i.env };
+  // A collective lane's marker rides extraEnv so both engines set it after
+  // every merge; a caller cannot drop it by passing its own extraEnv.
+  const extraEnv = spec.collectiveChild
+    ? { ...(i.extraEnv && typeof i.extraEnv === "object" ? i.extraEnv : {}), [COLLECTIVE_CHILD_ENV]: "1" }
+    : i.extraEnv;
+  const input = { ...i, env: i.env === undefined ? process.env : i.env, extraEnv };
 
   if (engine === "cohort") return buildCohortEngineSpawn(spec, input, d, deps, fail);
 
@@ -411,8 +421,8 @@ export function buildSpawn(i = {}, deps = {}) {
   const argv = spec.argv(input, x);
 
   const env = envResult.env;
-  if (i.extraEnv && typeof i.extraEnv === "object") {
-    for (const [k, v] of Object.entries(i.extraEnv)) if (v !== undefined && v !== null) env[k] = String(v);
+  if (input.extraEnv && typeof input.extraEnv === "object") {
+    for (const [k, v] of Object.entries(input.extraEnv)) if (v !== undefined && v !== null) env[k] = String(v);
   }
 
   return {

package/lib/telemetry/collect.mjs

@@ -84,7 +84,8 @@
  *       // Also on `machine` (open record), so hq's fleet view can show it next
  *       // to sdkVersion without a schema change. `ok` is the attempt's verdict:
  *       // true = healthy on `to`; false = install failed or rolled back to `from`.
- *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean },
+ *       upgrade?: { at: ISO8601, from: string, to: string, ok: boolean,
+ *                   reason?: string, healthy?: boolean },  // reason: WHY a failure failed
  *       // THE BEATING DAEMON — which process is emitting this beat, what code
  *       // it is actually running, and the last health-gate verdict on it.
  *       // Also on `machine` (open record). `sdkVersion` ABOVE is what is
@@ -1367,7 +1368,25 @@ export function upgradeSummary(last) {
   const at = typeof last.at === "string" ? last.at : "";
   const to = typeof last.to === "string" ? last.to : "";
   if (!at || !to) return null;
-  return { at, from: typeof last.from === "string" ? last.from : "", to, ok: last.ok === true };
+  // `reason` and `healthy` are the two fields autoupdate.sh has always written
+  // to state/autoupdate/last.json and this projection used to drop. Without
+  // them a failed attempt reaches the org as a bare `ok:false` — which is the
+  // state three seats were in on 2026-09-24: provably behind, provably having
+  // tried, and no way to learn WHY short of reading a file on a machine nobody
+  // could reach. "install-failed" and "unhealthy-rolled-back" are different
+  // problems with different fixes and they looked identical from here.
+  //
+  // Bounded on the way out: a reason is a short token plus at most a trimmed
+  // error line, and the beat is not a log shipper.
+  const reason = typeof last.reason === "string" ? last.reason.trim().slice(0, 300) : "";
+  return {
+    at,
+    from: typeof last.from === "string" ? last.from : "",
+    to,
+    ok: last.ok === true,
+    ...(reason ? { reason } : {}),
+    ...(typeof last.healthy === "boolean" ? { healthy: last.healthy } : {}),
+  };
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.18.4",
+  "version": "2.18.5",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {

package/scaffold/config/collective.yaml

@@ -19,6 +19,13 @@ captureOn: [Stop, PreCompact]
 minTurnsToCapture: 2
 # Hard cap on cards distilled from a single session (anti-bloat + cost guard).
 maxCardsPerSession: 12
+# Machine-wide ceiling on capture workers doing model work at once. Each worker
+# runs one or two `claude --print` passes; the ceiling keeps a burst of session
+# ends from fanning out into unbounded model processes.
+captureMaxConcurrent: 2
+# How long a worker waits for a free slot before it gives up and records a
+# skipped capture (counter `collective.capture_skipped`, reason `no-slot`).
+captureQueueWaitMs: 30000
 # Repos/paths whose sessions must NOT contribute to memory (substring or glob,
 # matched against the session cwd). Client work, secrets, anything ring-fenced.
 # Information-barrier domains are always excluded regardless of this list.

package/scripts/ci/check-durable-write-seam.mjs

@@ -42,7 +42,7 @@
  * `eslint.config.mjs`/`authz-drift.test.ts` use in the Cohort repo.
  *
  * Set equality also makes this guard self-canarying: the register is non-empty,
- * so a regex broken by a refactor yields zero matches and fails LOUDLY as three
+ * so a regex broken by a refactor yields zero matches and fails LOUDLY as
  * stale entries, rather than passing vacuously.
  *
  * Pure, dependency-light: Node builtins only. ESM.
@@ -71,6 +71,8 @@ export const SANCTIONED_DIRECT_WRITES = {
     "acquireScheduleLock: reclaim of a lock already proven stale by mtime; must land in place under the same name.",
   "lib/cadence-bus.mjs:328":
     "acquireScheduleLock: second O_EXCL attempt after the stale holder vanished.",
+  "lib/collective/capture-slots.mjs:152":
+    "tryAcquireLock: O_EXCL create of a capture slot/session lock (the machine-wide capture ceiling). A lock published by rename is not a lock — two workers could both hold one slot.",
 };
 
 /** Argument spellings that are already safe and must never be flagged. */

package/scripts/collective/hook-runner.mjs

@@ -14,6 +14,15 @@
  * this isn't an agent machine or the layer is disabled. Capture runs in a
  * DETACHED child so it never blocks session exit.
  *
+ * Loop guard: the capture worker's own model passes are Claude Code sessions,
+ * so their hooks land here too. A session of kind `collective` (env
+ * MAESTRO_COLLECTIVE_CHILD=1), or whose transcript opens with a collective
+ * prompt, is exempt from every event — no presence, no primer, no capture —
+ * so a capture can never spawn a capture (lib/collective/loop-guard.mjs).
+ * Workers are further bounded machine-wide by slot + per-session O_EXCL locks
+ * (lib/collective/capture-slots.mjs); a worker that cannot get a slot records a
+ * skipped capture rather than running.
+ *
  * The agent repo this feeds is the runner's own repo, overridable with
  * MAESTRO_COLLECTIVE_ROOT (used by tests + multi-repo setups).
  *
@@ -26,6 +35,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, join, basename } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { classifyKind, captureExemption, readTranscriptHead, COLLECTIVE_CHILD_ENV } from "../../lib/collective/loop-guard.mjs";
 
 const THIS_FILE = fileURLToPath(import.meta.url);
 const SELF_ROOT = process.env.MAESTRO_COLLECTIVE_ROOT || join(dirname(THIS_FILE), "..", "..");
@@ -60,6 +70,7 @@ async function main() {
   const cwd = input.cwd || process.cwd();
   const sessionId = input.session_id || input.sessionId || `sess-${process.pid}`;
   const transcriptPath = input.transcript_path || input.transcriptPath || "";
+  const kind = classifyKind(input, process.env);
 
   let config, presence, isEnabled, isRepoDenied;
   try {
@@ -75,8 +86,15 @@ async function main() {
   const denied = isRepoDenied(cwd, config);
   const repo = basename(cwd || "");
 
+  // The collective layer's own children: nothing on any event. A capture/
+  // reflect/curator `claude --print` must not register presence, be primed, or
+  // — above all — be captured (that is the recursion). Counted, never silent.
+  if (kind === "collective") {
+    if (event === "stop" || event === "capture") await recordExemption("collective-child-env", sessionId);
+    return;
+  }
+
   if (event === "prime") {
-    const kind = classifyKind(input);
     try { presence.register(SELF_ROOT, { sessionId, cwd, repo, kind, ...ownerFields(presence) }); } catch { /* */ }
     if (denied) return; // never inject agent memory (or the persona) into a ring-fenced/client session
     const parts = [];
@@ -118,7 +136,7 @@ async function main() {
     let beaten = false;
     try { beaten = presence.heartbeat(SELF_ROOT, sessionId); } catch { beaten = false; }
     if (!beaten) {
-      try { presence.register(SELF_ROOT, { sessionId, cwd, repo, kind: classifyKind(input), ...ownerFields(presence) }); } catch { /* */ }
+      try { presence.register(SELF_ROOT, { sessionId, cwd, repo, kind, ...ownerFields(presence) }); } catch { /* */ }
     }
     // WS3: nudge the self-learning loop's tool-use counter. Cheap, fail-open,
     // and only when the layer is enabled + the repo isn't denylisted.
@@ -133,14 +151,51 @@ async function main() {
 
   if (event === "stop") {
     try { presence.deregister(SELF_ROOT, sessionId); } catch { /* */ }
-    if (!denied) spawnCaptureWorker({ transcriptPath, cwd, sessionId });
+    if (!denied) await maybeSpawnCaptureWorker({ kind, transcriptPath, cwd, sessionId });
     return;
   }
 
   if (event === "capture") {
-    if (!denied) spawnCaptureWorker({ transcriptPath, cwd, sessionId });
+    if (!denied) await maybeSpawnCaptureWorker({ kind, transcriptPath, cwd, sessionId });
+    return;
+  }
+}
+
+/**
+ * Spawn a capture worker unless this session is the collective layer's own
+ * child. The env marker was handled before dispatch; this catches a child whose
+ * env did not propagate, by its transcript (the first user input is one of the
+ * collective prompts).
+ */
+async function maybeSpawnCaptureWorker({ kind, transcriptPath, cwd, sessionId }) {
+  const exempt = captureExemption({ kind, transcriptHead: readTranscriptHead(transcriptPath) });
+  if (exempt) {
+    await recordExemption(exempt, sessionId);
     return;
   }
+  spawnCaptureWorker({ transcriptPath, cwd, sessionId });
+}
+
+/** Count a capture the loop guard refused to start. Never rejects. */
+function recordExemption(reason, sessionId) {
+  return countCapture("collective.capture_exempt", reason, sessionId);
+}
+
+/** Count a capture a worker gave up on (lock contention). Never rejects. */
+function recordSkip(reason, sessionId, extra = {}) {
+  return countCapture("collective.capture_skipped", reason, sessionId, extra);
+}
+
+/**
+ * One durable counter row per refused/skipped capture, in the agent's
+ * logs/diagnostics/counters stream (what doctor reads). Dynamic import so a repo
+ * that predates lib/diagnostics stays silent rather than failing the hook.
+ */
+async function countCapture(name, reason, sessionId, extra = {}) {
+  try {
+    const counters = await import("../../lib/diagnostics/counters.mjs");
+    counters.bump(name, { reason, sessionId: sessionId || "", ...extra }, { agentRoot: SELF_ROOT });
+  } catch { /* a counter must never break a session exit */ }
 }
 
 /** The identity block + status line for `prime`. "" when there is nothing to say. */
@@ -178,13 +233,6 @@ function ownerFields(presence) {
   }
 }
 
-function classifyKind(input) {
-  const src = String(input.source || "").toLowerCase();
-  if (src.includes("daemon") || process.env.MAESTRO_DAEMON === "1") return "daemon";
-  if (src.includes("resume")) return "interactive";
-  return "interactive";
-}
-
 /** Spawn the detached capture pass and return immediately. */
 function spawnCaptureWorker({ transcriptPath, cwd, sessionId }) {
   try {
@@ -197,6 +245,9 @@ function spawnCaptureWorker({ transcriptPath, cwd, sessionId }) {
         MAESTRO_CAPTURE_TRANSCRIPT_PATH: transcriptPath || "",
         MAESTRO_CAPTURE_CWD: cwd || "",
         MAESTRO_CAPTURE_SESSION: sessionId || "",
+        // The worker's whole process tree is the collective layer: every
+        // `claude` it spawns inherits this, so their hooks exempt themselves.
+        [COLLECTIVE_CHILD_ENV]: "1",
       },
     });
     child.unref();
@@ -214,23 +265,68 @@ function spawnCaptureWorker({ transcriptPath, cwd, sessionId }) {
  *
  * Both passes are independently fail-open: a throw in either is swallowed, the
  * worker still exits 0, and the session was never blocked.
+ *
+ * Before either pass the worker takes two O_EXCL locks (lib/collective/
+ * capture-slots.mjs): the SESSION lock (one worker per session at a time — a
+ * PreCompact and the Stop after it never distil in parallel) and then one of
+ * `captureMaxConcurrent` machine-wide SLOTS, queueing up to
+ * `captureQueueWaitMs`. Either refusal ends the worker with a counted skip
+ * (`collective.capture_skipped`); an unwritable lock dir fails CLOSED the same
+ * way, because an unbounded capture is the failure this exists to prevent.
  */
 async function doCaptureWorker() {
+  const transcriptPath = process.env.MAESTRO_CAPTURE_TRANSCRIPT_PATH || "";
+  const cwd = process.env.MAESTRO_CAPTURE_CWD || "";
+  const sessionId = process.env.MAESTRO_CAPTURE_SESSION || "";
+  let cfg, cap, text;
   try {
-    const transcriptPath = process.env.MAESTRO_CAPTURE_TRANSCRIPT_PATH || "";
-    const cwd = process.env.MAESTRO_CAPTURE_CWD || "";
-    const sessionId = process.env.MAESTRO_CAPTURE_SESSION || "";
+    const cfgMod = await import("../../lib/collective/config.mjs");
+    cfg = await cfgMod.loadConfig(SELF_ROOT);
+    if (!cfgMod.isEnabled(cfg)) return;
     let raw = "";
     if (transcriptPath && existsSync(transcriptPath)) {
       try { raw = readFileSync(transcriptPath, "utf8"); } catch { raw = ""; }
     }
-    const cap = await import("../../lib/collective/capture.mjs");
-    const text = cap.transcriptToText(raw);
-    if (!text) return;
-    const cfgMod = await import("../../lib/collective/config.mjs");
-    const cfg = await cfgMod.loadConfig(SELF_ROOT);
-    if (!cfgMod.isEnabled(cfg)) return;
+    cap = await import("../../lib/collective/capture.mjs");
+    text = cap.transcriptToText(raw);
+    if (!text) return; // nothing to distil → no lock, no slot
+  } catch {
+    return; // libs unavailable / not an agent repo → nothing to capture into
+  }
+  let slots;
+  try {
+    slots = await import("../../lib/collective/capture-slots.mjs");
+  } catch {
+    await recordSkip("lock-unavailable", sessionId);
+    return; // no lock module → no ceiling → do not run
+  }
+  const dir = slots.captureLockDir(process.env);
+  const owner = { pid: process.pid, sessionId };
+  const session = slots.tryAcquireLock(slots.sessionLockPath(dir, sessionId), owner);
+  if (!session.ok) {
+    await recordSkip(session.error.code === "held" ? "session-busy" : "lock-io", sessionId);
+    return;
+  }
+  try {
+    const max = slots.maxConcurrentFrom(cfg);
+    const slot = await slots.acquireSlotQueued(dir, max, owner, { waitMs: slots.queueWaitFrom(cfg) });
+    if (!slot.ok) {
+      await recordSkip(slot.error.code === "no-slot" ? "no-slot" : "lock-io", sessionId, { max, waitedMs: slot.waitedMs });
+      return;
+    }
+    try {
+      await runCapturePasses({ cfg, cap, text, transcriptPath, cwd, sessionId });
+    } finally {
+      slot.release();
+    }
+  } finally {
+    session.release();
+  }
+}
 
+/** Pass A + Pass B over one read of the transcript. Runs only under both locks. */
+async function runCapturePasses({ cfg, cap, text, transcriptPath, cwd, sessionId }) {
+  try {
     // ── Pass A — collective memory cards (existing behaviour, unchanged). ──
     const res = await cap.captureSession({ agentRoot: SELF_ROOT, sessionId, cwd, transcriptText: text, cfg });
     if (res.written > 0) {

package/scripts/fleet/rollout.mjs

@@ -98,7 +98,7 @@
 
 "use strict";
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -712,9 +712,19 @@ export function npmWhoami(deps) {
   return { ok: false, error: (err || `exit ${r.code}`).trim() };
 }
 
-/** `npm view <pkg> version` → {ok,version,error?}. Needs no auth. */
+/**
+ * `npm view <pkg> version` → {ok,version,error?}. Needs no auth.
+ *
+ * `--prefer-online` is load-bearing, not tidiness. npm caches registry metadata
+ * and revalidates it lazily, so straight after a successful publish this read
+ * kept answering with the PREVIOUS version from the local cache: 2.18.4 went to
+ * the registry, and all ten read-lag retries reported 2.17.0 from ~/.npm while
+ * a fresh shell already saw 2.18.4. The run then declared the publish stage
+ * failed on a package it had just published correctly. The retry loop cannot
+ * out-wait a cache that is never re-fetched.
+ */
 export function npmLatest(pkg, deps) {
-  const r = deps.exec("npm", ["view", pkg, "version"]);
+  const r = deps.exec("npm", ["view", "--prefer-online", pkg, "version"]);
   if (r.ok && r.stdout) return { ok: true, version: r.stdout.split("\n").pop().trim() };
   return { ok: false, version: null, error: ((r.stderr || r.stdout || `exit ${r.code}`).split("\n")[0] || "").trim() };
 }
@@ -748,16 +758,57 @@ export function gitTag(version, deps) {
  * @param {object} o - { agentRoot, client?, seatWindowMs? }
  * @returns {Promise<{ok:boolean, error?:string, seats:object[], nonSeats:object[]}>}
  */
+/**
+ * Which enrolled agent directory this run reads the org through.
+ *
+ * This script lives in the SDK repo, which is NOT an agent seat: it has no
+ * config/org.yaml. Run from ~/maestro with nothing set, `loadOrgConfig(undefined)`
+ * threw `The "path" argument must be of type string`, the verify loop treated
+ * that as a transient read failure, and it retried ninety times over two hours
+ * before reporting nothing — about a fleet that had in fact taken the release.
+ *
+ * Order: an explicit --agent-root / AGENT_ROOT / AGENT_DIR, then the cwd if it
+ * is itself a seat, then the one enrolled directory under $HOME. Several
+ * candidates is ambiguity, not a default: it says so and asks for the flag.
+ *
+ * @returns {{ok:true, root:string, how:string} | {ok:false, error:string}}
+ */
+export function resolveAgentRoot(explicit, deps = {}) {
+  const exists = deps.exists || ((p) => existsSync(p));
+  const home = deps.home || process.env.HOME || "";
+  const cwd = deps.cwd || process.cwd();
+  const isSeat = (dir) => Boolean(dir) && exists(join(dir, "config", "org.yaml"));
+
+  if (explicit) {
+    if (isSeat(explicit)) return { ok: true, root: explicit, how: "given" };
+    return { ok: false, error: `--agent-root ${explicit} has no config/org.yaml — that is not an enrolled agent directory.` };
+  }
+  if (isSeat(cwd)) return { ok: true, root: cwd, how: "cwd" };
+
+  const found = (deps.listHome || (() => { try { return readdirSync(home); } catch { return []; } }))()
+    .map((name) => join(home, name))
+    .filter(isSeat);
+  if (found.length === 1) return { ok: true, root: found[0], how: "discovered under $HOME" };
+  if (found.length === 0) {
+    return { ok: false, error: `no enrolled agent directory found (looked at ${cwd} and $HOME/*/config/org.yaml) — pass --agent-root <dir>.` };
+  }
+  return { ok: false, error: `several enrolled agent directories (${found.join(", ")}) — pass --agent-root <dir> to say which one reads the fleet.` };
+}
+
 export async function readFleet(o = {}) {
   const client = o.client || (await import("../../lib/org/client.mjs"));
+  const root = resolveAgentRoot(o.agentRoot);
+  // `fatal` means polling cannot help: the fault is in how this run was invoked,
+  // not in a momentarily unreachable server. The loop stops on it.
+  if (!root.ok) return { ok: false, fatal: true, error: root.error, seats: [], nonSeats: [] };
   let cfg;
   try {
-    cfg = client.loadOrgConfig(o.agentRoot);
+    cfg = client.loadOrgConfig(root.root);
   } catch (err) {
-    return { ok: false, error: `org config unreadable (${err && err.message})`, seats: [], nonSeats: [] };
+    return { ok: false, fatal: true, error: `org config unreadable at ${root.root} (${err && err.message})`, seats: [], nonSeats: [] };
   }
   if (!client.isEnabled(cfg)) {
-    return { ok: false, error: "org integration is not enabled for this seat — cannot read the fleet", seats: [], nonSeats: [] };
+    return { ok: false, fatal: true, error: `org integration is not enabled for ${root.root} — cannot read the fleet`, seats: [], nonSeats: [] };
   }
   let r;
   try {
@@ -899,6 +950,12 @@ export async function verifyPropagation(o) {
       client: o.client,
       seatWindowMs: o.seatWindowMs,
     });
+    if (!fleet.ok && fleet.fatal) {
+      // Not transient: retrying changes nothing and the deadline would only
+      // delay the answer. Say what to do and stop.
+      deps.log(`\nfleet read cannot succeed as invoked — ${fleet.error}`);
+      return { ok: false, summary: null, rounds: round, fatal: true, error: fleet.error };
+    }
     if (!fleet.ok) {
       deps.log(`round ${round}: fleet read failed — ${fleet.error}`);
     } else {

package/scripts/local-triggers/autoupdate.sh

@@ -212,12 +212,17 @@ J=$(( RANDOM % (JITTER_MAX + 1) )); log "wake; jitter ${J}s"; [ "$J" -gt 0 ] &&
 # ── retry helper (npm view / install) ────────────────────────────────────────
 RETRIES=3
 RETRY_SLEEP="${MAESTRO_AUTOUPDATE_RETRY_SLEEP:-20}"
+# The last error line a retried command printed, for the reason the org reads.
+# Set on every failed attempt, cleared on success, and deliberately the LAST
+# npm/git line rather than the whole log: the beat is not a log shipper.
+LAST_ERROR=""
 retry(){ # $1 = label; rest = command (stdout+stderr → LOG)
   local label="$1"; shift
   local attempt=1 wait
   while :; do
-    if "$@" >> "$LOG" 2>&1; then return 0; fi
-    if [ "$attempt" -ge "$RETRIES" ]; then log "$label: failed after $attempt attempt(s)"; return 1; fi
+    if "$@" >> "$LOG" 2>&1; then LAST_ERROR=""; return 0; fi
+    LAST_ERROR="$(grep -aE "npm (error|ERR!)|^Error|EACCES|EEXIST|ENOTEMPTY|ENOSPC|ETARGET|E404|E401|ENOENT" "$LOG" 2>/dev/null | tail -1 | cut -c1-200)"
+    if [ "$attempt" -ge "$RETRIES" ]; then log "$label: failed after $attempt attempt(s)${LAST_ERROR:+ — $LAST_ERROR}"; return 1; fi
     wait=$(( RETRY_SLEEP * attempt ))
     log "$label: attempt $attempt failed; retrying in ${wait}s"
     sleep "$wait"; attempt=$(( attempt + 1 ))
@@ -598,7 +603,12 @@ failed_hold_reason(){ # prints "<reason> at <at>" when LATEST failed health with
     try {
       const j = JSON.parse(require("fs").readFileSync(file, "utf8"));
       const at = Date.parse(j.at);
-      if (j.to === latest && j.ok === false && /unhealthy/.test(String(j.reason)) && Number.isFinite(at) && Date.now() - at < Number(holdS) * 1000) process.stdout.write(`${j.reason} at ${j.at}`);
+      // Match the reason TOKEN, not the whole string: since 2.18.5 a reason may
+      // carry a trailing ": <npm error line>", and an error line that happened
+      // to contain the word "unhealthy" must not put a seat into a day-long
+      // hold it did not earn.
+      const token = String(j.reason).split(": ")[0];
+      if (j.to === latest && j.ok === false && /unhealthy/.test(token) && Number.isFinite(at) && Date.now() - at < Number(holdS) * 1000) process.stdout.write(`${j.reason} at ${j.at}`);
     } catch {}
   ' "$LAST_JSON" "$LATEST" "$FAILED_HOLD_S" 2>/dev/null
 }
@@ -646,7 +656,11 @@ migrate_poller_plist(){ # audit F6 follow-through: an older install left SLACK_U
 
 if ! apply_version "$LATEST"; then
   log "npm install FAILED; aborting, staying on $CUR"
-  write_last "$CUR" "$LATEST" false false "install-failed"
+  # Name WHAT failed, not merely that something did. Three seats sat on
+  # `ok:false` with no reason for hours on 2026-09-24 and the difference between
+  # a disk-full box, a permissions problem and an unreachable registry is the
+  # difference between three different fixes.
+  write_last "$CUR" "$LATEST" false false "install-failed${LAST_ERROR:+: $LAST_ERROR}"
   exit 1
 fi
 restart_daemon