@cohortapp/agent-sdk 2.17.0 → 2.18.5

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,9 +86,16 @@ 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 }); } catch { /* */ }
+    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 = [];
     try {
@@ -111,7 +129,15 @@ async function main() {
   }
 
   if (event === "beat") {
-    try { presence.heartbeat(SELF_ROOT, sessionId); } catch { /* */ }
+    // A beat on a session with no record re-registers it: a session that was
+    // running before this hook learned to record its OWNER pid (see
+    // ownerFields) was reaped on every read, and would otherwise stay
+    // invisible until it restarts.
+    let beaten = false;
+    try { beaten = presence.heartbeat(SELF_ROOT, sessionId); } catch { beaten = false; }
+    if (!beaten) {
+      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.
     if (!denied) {
@@ -125,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. */
@@ -151,11 +214,23 @@ function buildFrontDoorPrimer(agentRoot) {
     mod.buildPrimerContext({ agentJson, agentRoot, status: mod.readSessionStatus(agentRoot, { now: Date.now() }) }));
 }
 
-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";
+/**
+ * The pid, `--name` and process start of the session that RAN this hook.
+ * Without this the record carried the hook's own pid, which is dead by the
+ * time anyone reads it, so `list()` reaped every interactive session on its
+ * first read (see lib/collective/presence.mjs `owningSession`). `pid: null`
+ * when the walk finds nothing — liveness then rests on the heartbeat. The
+ * start time is the owner's `ps etime`, so a session re-registered by a late
+ * beat still says when it OPENED, not when the beat happened.
+ */
+function ownerFields(presence) {
+  try {
+    if (typeof presence.resolveOwner !== "function") return {};
+    const o = presence.resolveOwner();
+    return { pid: o.pid, agentName: o.name || "", ...(o.startedAt ? { startedAt: o.startedAt } : {}) };
+  } catch {
+    return {};
+  }
 }
 
 /** Spawn the detached capture pass and return immediately. */
@@ -170,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();
@@ -187,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/continuous-monitor.sh

@@ -9,6 +9,19 @@ set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 AGENT_REPO_DIR="${AGENT_DIR:-$(dirname "$SCRIPT_DIR")}"
+
+# Retired on engine-cohort seats (W4-E1): this lane runs claude outside the
+# runtime adapter. The guard exits 3 with the reason when runtime.engine is cohort.
+# Fail closed: when the guard cannot run (no node on PATH — launchd's
+# /usr/bin:/bin — or the guard file is missing), config/agent.json is checked
+# here and an engine-cohort seat is refused all the same.
+LEGACY_GUARD="$(dirname "$SCRIPT_DIR")/lib/runtime/legacy-shell-guard.mjs"
+if [ -f "$LEGACY_GUARD" ] && command -v node >/dev/null 2>&1; then
+    node "$LEGACY_GUARD" continuous-monitor.sh "$AGENT_REPO_DIR" || exit $?
+elif [ -f "$AGENT_REPO_DIR/config/agent.json" ] && grep -Eq '"engine"[[:space:]]*:[[:space:]]*"cohort"' "$AGENT_REPO_DIR/config/agent.json"; then
+    echo "continuous-monitor.sh is retired on this seat: runtime.engine is \"cohort\", and this legacy lane runs the claude binary directly, outside the runtime adapter (the engine guard could not run: node or $LEGACY_GUARD is unavailable)." >&2
+    exit 3
+fi
 # Load agent identity for the LLM prompt
 if [ -f "$AGENT_REPO_DIR/config/agent.env" ]; then
   # shellcheck disable=SC1091

package/scripts/cost/track-claude-usage.mjs

@@ -22,6 +22,13 @@
  *     That writes measurement:"unknown" with NULL tokens. It must never write
  *     zeros — see "MEASURED, UNKNOWN, N/A" below.
  *
+ *     A session cohort-llm served (engine cohort, or claude retargeted to the
+ *     cohort provider) is already metered by the gateway; mark it so org
+ *     cost-sync does not report it a second time:
+ *
+ *       node scripts/cost/track-claude-usage.mjs record ... \
+ *         --billed-by cohort-llm --request-ids req_1,req_2
+ *
  *  2. `summarise` — Rollup the last N days into state/dashboards/cost-summary.yaml.
  *     Called daily (cadence: nightly-cost-rollup) and on demand.
  *
@@ -266,6 +273,14 @@ function recordCmd(flags) {
   };
   if (unmeasuredReason) row.unmeasured_reason = unmeasuredReason;
   if (flags["decision-id"]) row.decision_id = String(flags["decision-id"]);
+  // Who metered this session. "cohort-llm": the gateway billed it; the row is
+  // kept for the seat's own view and reconciliation, and skipped by org
+  // cost-sync (lib/org/cost-sync.mjs) so it is never counted twice.
+  if (flags["billed-by"] && flags["billed-by"] !== "true") row.billed_by = String(flags["billed-by"]);
+  if (flags["request-ids"] && flags["request-ids"] !== "true") {
+    const ids = String(flags["request-ids"]).split(",").map((x) => x.trim()).filter(Boolean);
+    if (ids.length) row.gateway_request_ids = ids;
+  }
 
   if (measurement === "measured") {
     // Cache tokens are billed at their own rates (read 0.1x, write 1.25x) and