@cohortapp/agent-sdk 2.11.11 → 2.11.13

package/lib/claude-bin.mjs

@@ -129,9 +129,26 @@ export function daemonClaudeArgs(agentRoot, deps = {}) {
   const env = deps.env || process.env;
   if (env.DAEMON_LOAD_MCPS === "1") return [];
   const ex = deps.existsSync || existsSync;
+  const source = deps.source || null;
 
   const args = ["--strict-mcp-config"];
 
+  // MCP BY SOURCE — the biggest cheap per-spawn token saving. A classify or a
+  // quick-reply generates TEXT and calls NO org tools, so re-paying the ~107-tool
+  // org MCP definitions on every one of those high-frequency spawns is pure
+  // waste. Those sources get a BARE spawn (`--strict-mcp-config` with no
+  // `--mcp-config` loads zero MCP servers); only full work sessions
+  // (dispatcher/cadence — source unset) load the org toolset, so the API/tool-
+  // parity bar is honoured exactly where real work happens. Override per source
+  // with DAEMON_<SOURCE>_MCP=full|bare (e.g. DAEMON_CLASSIFIER_MCP=full).
+  const BARE_SOURCES = new Set(["classifier", "responder"]);
+  const perSource = source ? env[`DAEMON_${source.toUpperCase()}_MCP`] : null;
+  const bare = perSource === "bare" || (perSource !== "full" && BARE_SOURCES.has(source));
+  if (bare) {
+    if (env.DAEMON_BARE_MODE === "1") args.unshift("--bare");
+    return args;
+  }
+
   const root = agentRoot || env.AGENT_ROOT || process.cwd();
   try {
     const cfg = join(root, ".mcp.json");

package/lib/claude-bin.test.mjs

@@ -107,3 +107,25 @@ test("daemonClaudeArgs never throws on a bad root (a daemon must still spawn)",
   const args = daemonClaudeArgs("/agent", { existsSync: () => { throw new Error("EACCES"); }, env: {} });
   assert.deepEqual(args, ["--strict-mcp-config"]);
 });
+
+// ---------------------------------------------------------------------------
+// MCP by source — bare for tool-free spawns (classifier / responder)
+// ---------------------------------------------------------------------------
+
+test("daemonClaudeArgs: classifier + responder are BARE (no org MCP re-paid)", () => {
+  for (const source of ["classifier", "responder"]) {
+    const args = daemonClaudeArgs("/agent", { existsSync: () => true, env: {}, source });
+    assert.ok(args.includes("--strict-mcp-config"), `${source} keeps strict-mcp-config`);
+    assert.ok(!args.includes("--mcp-config"), `${source} must NOT load the org MCP`);
+  }
+});
+
+test("daemonClaudeArgs: a full work session (no source) still loads the org MCP", () => {
+  const args = daemonClaudeArgs("/agent", { existsSync: () => true, env: {} });
+  assert.ok(args.includes("--mcp-config"), "dispatcher/cadence session keeps full org tools");
+});
+
+test("daemonClaudeArgs: DAEMON_<SOURCE>_MCP=full overrides bare for that source", () => {
+  const args = daemonClaudeArgs("/agent", { existsSync: () => true, env: { DAEMON_CLASSIFIER_MCP: "full" }, source: "classifier" });
+  assert.ok(args.includes("--mcp-config"), "explicit override restores the org MCP for the classifier");
+});

package/lib/rate-guard.mjs

@@ -243,4 +243,70 @@ export function classifyStderr(text) {
   return /\b429\b|rate[\s_-]?limit|overloaded|too many requests/i.test(text);
 }
 
-export const _internals = { RATE_BASE_BACKOFF_MS, RATE_MAX_BACKOFF_MS, RATE_BACKOFF_FACTOR };
+// A Max/subscription USAGE or SESSION limit is NOT a transient 429 — the pool is
+// drained until the window RESETS, so hammering it with decorrelated-jitter
+// retries just burns the moment it re-opens. We detect it separately and hold
+// the breaker until the reset (parsed from the message when present, else a
+// conservative default) so the seat backs off to the reset instead of storming.
+const USAGE_LIMIT_RE =
+  /\b(?:usage|session|weekly|5[\s-]?hour)\s+limit\b|limit reached|reached your (?:usage|session|monthly|weekly|plan)?\s*limit|you'?ve hit your [^.]*limit|approaching (?:your )?[^.]*usage limit|out of (?:usage|credits|messages)/i;
+
+/** How long to hold the breaker when a usage limit is hit but no reset time is parseable. */
+export const RATE_USAGE_LIMIT_HOLD_MS = num(process.env.RATE_USAGE_LIMIT_HOLD_MS, 30 * 60 * 1000);
+
+/**
+ * Best-effort parse of a reset time out of a usage-limit message —
+ * "resets 9:40pm", "resets at 9pm", "try again at 10:15am", "available again at
+ * 3pm" — into the epoch ms of its NEXT occurrence (today, or tomorrow if already
+ * past). The daemon runs in the seat's local timezone, which is the timezone the
+ * message states, so a local Date is correct. Returns null when unparseable.
+ */
+export function parseResetAt(text, deps) {
+  if (!text || typeof text !== "string") return null;
+  const m = /(?:reset|resets|resets at|resets in|try again at|available again at)\s+(\d{1,2})(?::(\d{2}))?\s*([ap])\.?\s?m\.?/i.exec(text);
+  if (!m) return null;
+  const nowMs = clock(deps)();
+  let hr = parseInt(m[1], 10) % 12;
+  if (/p/i.test(m[3])) hr += 12;
+  const min = m[2] ? parseInt(m[2], 10) : 0;
+  const cand = new Date(nowMs);
+  cand.setHours(hr, min, 0, 0);
+  let t = cand.getTime();
+  if (t <= nowMs) t += 24 * 60 * 60 * 1000; // already past today → next occurrence
+  return t;
+}
+
+/**
+ * Does this text look like a Max/subscription USAGE / SESSION limit (as opposed
+ * to a transient 429)? When it names a reset time, resetAt is the epoch ms to
+ * hold the breaker until.
+ *
+ * @returns {{ isLimit: boolean, resetAt: number|null }}
+ */
+export function classifyUsageLimit(text, deps) {
+  if (!text || typeof text !== "string") return { isLimit: false, resetAt: null };
+  if (!USAGE_LIMIT_RE.test(text)) return { isLimit: false, resetAt: null };
+  return { isLimit: true, resetAt: parseResetAt(text, deps) };
+}
+
+/**
+ * Open the breaker until a usage window RESETS. Uses resetAt when known, else a
+ * conservative default hold. Never shortens an already-longer open window.
+ *
+ * @returns {{ openUntil:number, resetAt:number|null }}
+ */
+export function recordUsageLimit(provider, resetAt, deps) {
+  const now = clock(deps)();
+  const until =
+    typeof resetAt === "number" && resetAt > now ? resetAt : now + RATE_USAGE_LIMIT_HOLD_MS;
+  const prev = readState(provider, deps);
+  const next = {
+    openUntil: Math.max(prev.openUntil, until),
+    consecutive429: prev.consecutive429,
+    lastBackoffMs: prev.lastBackoffMs,
+  };
+  writeState(provider, next, deps);
+  return { openUntil: next.openUntil, resetAt: typeof resetAt === "number" && resetAt > now ? resetAt : null };
+}
+
+export const _internals = { RATE_BASE_BACKOFF_MS, RATE_MAX_BACKOFF_MS, RATE_BACKOFF_FACTOR, RATE_USAGE_LIMIT_HOLD_MS };

package/lib/rate-guard.test.mjs

@@ -18,11 +18,15 @@ import {
   recordSuccess,
   decorrelatedBackoff,
   classifyStderr,
+  classifyUsageLimit,
+  parseResetAt,
+  recordUsageLimit,
   readState,
   sanitizeProvider,
   RATE_BASE_BACKOFF_MS,
   RATE_MAX_BACKOFF_MS,
   RATE_BACKOFF_FACTOR,
+  RATE_USAGE_LIMIT_HOLD_MS,
 } from "./rate-guard.mjs";
 
 async function makeStateDir() {
@@ -199,3 +203,70 @@ test("readState tolerates a corrupt file (fails closed-to-empty, never throws)",
     assert.equal(checkRateLimit("anthropic", { stateDir: dir }).allowed, true);
   } finally { await rm(dir); }
 });
+
+// ---------------------------------------------------------------------------
+// classifyUsageLimit / parseResetAt / recordUsageLimit  (Max session-limit)
+// ---------------------------------------------------------------------------
+
+test("classifyUsageLimit detects session/usage limits, not plain 429s", () => {
+  assert.equal(classifyUsageLimit("You've hit your session limit · resets 9:40pm (Australia/Sydney)").isLimit, true);
+  assert.equal(classifyUsageLimit("usage limit reached").isLimit, true);
+  assert.equal(classifyUsageLimit("You have reached your weekly limit").isLimit, true);
+  assert.equal(classifyUsageLimit("out of usage for now").isLimit, true);
+  // A plain transient 429 is NOT a usage-window limit
+  assert.equal(classifyUsageLimit("HTTP 429 Too Many Requests").isLimit, false);
+  assert.equal(classifyUsageLimit("overloaded").isLimit, false);
+  assert.equal(classifyUsageLimit("").isLimit, false);
+  assert.equal(classifyUsageLimit(null).isLimit, false);
+});
+
+test("parseResetAt resolves a stated reset time to the next occurrence", () => {
+  // now = 2026-08-26 08:00 local; "resets 9:40pm" is later today
+  const now = new Date(2026, 7, 26, 8, 0, 0, 0).getTime();
+  const t = parseResetAt("resets 9:40pm", { now: () => now });
+  const d = new Date(t);
+  assert.equal(d.getHours(), 21);
+  assert.equal(d.getMinutes(), 40);
+  assert.ok(t > now, "reset is in the future");
+  // A time already past today rolls to tomorrow
+  const now2 = new Date(2026, 7, 26, 22, 0, 0, 0).getTime(); // 10pm
+  const t2 = parseResetAt("try again at 9pm", { now: () => now2 });
+  assert.ok(t2 > now2 && t2 - now2 <= 24 * 60 * 60 * 1000, "rolls to next day");
+  assert.equal(parseResetAt("no time here", { now: () => now }), null);
+});
+
+test("recordUsageLimit holds the breaker until the parsed reset time", async () => {
+  const dir = await makeStateDir();
+  try {
+    const now = new Date(2026, 7, 26, 8, 0, 0, 0).getTime();
+    const { resetAt } = classifyUsageLimit("session limit · resets 9:40pm", { now: () => now });
+    const rec = recordUsageLimit("anthropic", resetAt, { stateDir: dir, now: () => now });
+    assert.equal(rec.openUntil, resetAt);
+    // blocked before reset, allowed after
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => now + 1000 }).allowed, false);
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => resetAt + 1 }).allowed, true);
+  } finally { await rm(dir); }
+});
+
+test("recordUsageLimit falls back to a default hold when no reset is known", async () => {
+  const dir = await makeStateDir();
+  try {
+    const now = 1_000_000;
+    const rec = recordUsageLimit("anthropic", null, { stateDir: dir, now: () => now });
+    assert.equal(rec.openUntil, now + RATE_USAGE_LIMIT_HOLD_MS);
+    assert.equal(rec.resetAt, null);
+    assert.equal(checkRateLimit("anthropic", { stateDir: dir, now: () => now + 1000 }).allowed, false);
+  } finally { await rm(dir); }
+});
+
+test("recordUsageLimit never shortens an already-longer open window", async () => {
+  const dir = await makeStateDir();
+  try {
+    const now = 1_000_000;
+    const far = now + 10 * 60 * 60 * 1000; // 10h out
+    recordUsageLimit("anthropic", far, { stateDir: dir, now: () => now });
+    // a later, SHORTER hold must not pull the window in
+    const rec = recordUsageLimit("anthropic", now + 5 * 60 * 1000, { stateDir: dir, now: () => now });
+    assert.equal(rec.openUntil, far);
+  } finally { await rm(dir); }
+});

package/lib/reactive-gate.mjs

@@ -0,0 +1,58 @@
+/**
+ * reactive-gate — a process-local signal that a REACTIVE turn (a human or peer
+ * agent is waiting on a reply) is actively consuming the shared Max subscription.
+ *
+ * WHY THIS EXISTS. The scarce resource on a mini is not a dispatch slot — it is
+ * the ONE Max subscription's inference throughput, which tracks the number of
+ * concurrent `claude --print` processes. When several heavy autonomous BACKLOG
+ * sessions run at once they saturate that subscription, and the next reactive
+ * reply's own claude call is starved: a quick reply measured 19s and a classify
+ * actually timed out at 30s while three opus backlog sessions held the line.
+ *
+ * The governor reads {@link reactiveInFlight} to YIELD the subscription: while
+ * any reactive turn is in flight, self-directed backlog admission is held to
+ * REACTIVE_INFLIGHT_BACKLOG_MAX so a reply is never starved. The dispatcher
+ * reads the same signal to evict already-running backlog down to that cap.
+ *
+ * A COUNTER, not a boolean, so concurrent reactive turns nest correctly and
+ * backlog only resumes when the LAST reply has landed. Process-local by design:
+ * the daemon, dispatcher, and governor share one Node process, so a module-level
+ * count is visible to all three with no IPC. `claude --print` children are
+ * separate processes and are governed through the count, not this module.
+ */
+
+let _inFlight = 0;
+let _peak = 0;
+
+/** Mark the start of a reactive turn. Returns the new in-flight count. */
+export function markReactiveStart() {
+  _inFlight += 1;
+  if (_inFlight > _peak) _peak = _inFlight;
+  return _inFlight;
+}
+
+/**
+ * Mark the end of a reactive turn. Clamped at zero so an unbalanced end (a
+ * double-finally, a test) can never drive the count negative and wedge backlog
+ * off permanently. Returns the new in-flight count.
+ */
+export function markReactiveEnd() {
+  if (_inFlight > 0) _inFlight -= 1;
+  return _inFlight;
+}
+
+/** How many reactive turns are consuming the subscription right now. */
+export function reactiveInFlight() {
+  return _inFlight;
+}
+
+/** Highest concurrent reactive count seen since the last reset (diagnostics). */
+export function reactivePeak() {
+  return _peak;
+}
+
+/** Test seam — reset the process-local counters between cases. */
+export function _resetReactiveGate() {
+  _inFlight = 0;
+  _peak = 0;
+}

package/lib/reactive-gate.test.mjs

@@ -0,0 +1,57 @@
+/**
+ * reactive-gate — the process-local counter that tells the governor + dispatcher
+ * a human/peer reply is actively consuming the subscription.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  markReactiveStart,
+  markReactiveEnd,
+  reactiveInFlight,
+  reactivePeak,
+  _resetReactiveGate,
+} from "./reactive-gate.mjs";
+
+test("starts at zero", () => {
+  _resetReactiveGate();
+  assert.equal(reactiveInFlight(), 0);
+});
+
+test("start/end move the count by exactly one and balance to zero", () => {
+  _resetReactiveGate();
+  assert.equal(markReactiveStart(), 1);
+  assert.equal(reactiveInFlight(), 1);
+  assert.equal(markReactiveEnd(), 0);
+  assert.equal(reactiveInFlight(), 0);
+});
+
+test("concurrent reactive turns NEST — backlog resumes only when the last ends", () => {
+  _resetReactiveGate();
+  markReactiveStart();
+  markReactiveStart();
+  assert.equal(reactiveInFlight(), 2, "two turns in flight");
+  markReactiveEnd();
+  assert.equal(reactiveInFlight(), 1, "still one waiting — do NOT resume backlog yet");
+  markReactiveEnd();
+  assert.equal(reactiveInFlight(), 0, "now backlog may resume");
+});
+
+test("end is clamped at zero — an unbalanced end can never wedge backlog off", () => {
+  _resetReactiveGate();
+  assert.equal(markReactiveEnd(), 0, "end with nothing in flight stays at 0");
+  assert.equal(markReactiveEnd(), 0, "and again");
+  // A subsequent real turn still registers correctly (not driven negative).
+  assert.equal(markReactiveStart(), 1);
+  assert.equal(reactiveInFlight(), 1);
+});
+
+test("peak records the high-water mark since reset", () => {
+  _resetReactiveGate();
+  markReactiveStart();
+  markReactiveStart();
+  markReactiveStart();
+  markReactiveEnd();
+  markReactiveEnd();
+  assert.equal(reactivePeak(), 3, "peak holds even after turns end");
+  assert.equal(reactiveInFlight(), 1);
+});

package/lib/resource-governor.mjs

@@ -63,6 +63,7 @@ import os from "node:os";
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { reactiveInFlight } from "./reactive-gate.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -103,6 +104,19 @@ export const REACTIVE_RESERVE = num(process.env.GOV_REACTIVE_RESERVE, 2);
  * gets near-all capacity.
  */
 export const DEGRADED_BACKLOG_MAX = num(process.env.GOV_DEGRADED_BACKLOG_MAX, 1);
+/**
+ * The most self-directed BACKLOG sessions allowed to run while a REACTIVE turn
+ * is in flight (a human/peer is waiting on a reply). REACTIVE_RESERVE keeps a
+ * dispatch slot free, but slots are not the scarce resource — the ONE Max
+ * subscription's throughput is, and several concurrent backlog opus sessions
+ * saturate it, starving the reply's own claude call (measured: a 19s quick reply
+ * and a 30s classify timeout under three concurrent backlog sessions). So while
+ * a reply generates, backlog admission is capped HARD to this (default 1): the
+ * subscription is left almost entirely to the human, and backlog resumes the
+ * instant the reply lands. The dispatcher evicts already-running backlog down to
+ * the same cap. 0 pauses backlog completely during a reactive turn.
+ */
+export const REACTIVE_INFLIGHT_BACKLOG_MAX = num(process.env.GOV_REACTIVE_INFLIGHT_BACKLOG_MAX, 1);
 /**
  * A `claude` session older than this is treated as STALE and does NOT count
  * toward the concurrency ceiling — an idle/wedged lane must not hold a slot
@@ -368,6 +382,10 @@ export function defaultDeps(extra = {}) {
     liveClaude: live,
     throttleCeiling: throttle.ceiling,
     throttleReason: throttle.reason,
+    // How many reactive turns are consuming the subscription right now. admit()
+    // caps backlog HARD while this is > 0 so a waiting human's reply is never
+    // starved. Injectable via `extra` for tests; live from the gate otherwise.
+    reactiveInFlight: reactiveInFlight(),
     ...extra,
   };
 }
@@ -500,22 +518,35 @@ export function admit(req = {}, deps) {
   //     can always be GENERATED (10 parallel sessions once starved the
   //     quick-reply's claude call into a 60s timeout). A DEGRADED/unfunded seat
   //     throttles backlog to DEGRADED_BACKLOG_MAX — a trickle in idle gaps.
+  // Is a reactive turn (a human/peer waiting on a reply) generating right now?
+  // While one is, self-directed backlog yields the SUBSCRIPTION — not merely a
+  // slot — so the reply's own claude call isn't starved. This is a hard cap
+  // ABOVE the REACTIVE_RESERVE math: reserve keeps steady-state headroom; this
+  // clamps to a trickle for the seconds a human is actually waiting.
+  const reactiveBusy = numField(d.reactiveInFlight, 0) > 0;
   let sourceCeiling;
   if (humanReply) {
     sourceCeiling = effectiveMax;
+  } else if (reactiveBusy) {
+    sourceCeiling = Math.min(effectiveMax, REACTIVE_INFLIGHT_BACKLOG_MAX);
+    if (mode === "degraded" && source === "backlog") {
+      sourceCeiling = Math.min(sourceCeiling, DEGRADED_BACKLOG_MAX);
+    }
   } else if (mode === "degraded" && source === "backlog") {
     sourceCeiling = Math.min(effectiveMax, DEGRADED_BACKLOG_MAX);
   } else {
     sourceCeiling = Math.max(1, effectiveMax - REACTIVE_RESERVE);
   }
   if (liveCount >= sourceCeiling) {
-    const why = mode === "degraded" && source === "backlog"
-      ? `budget degraded: self-directed backlog throttled to ${sourceCeiling} (${liveCount} live; inbox unaffected)`
-      : throttleCeiling < dMax
-        ? `at throttled ceiling (${liveCount}/${sourceCeiling}; soft-throttle active)`
-        : source === "inbox"
-          ? `at concurrency ceiling (${liveCount}/${sourceCeiling})`
-          : `self-directed work yields ${REACTIVE_RESERVE} slots to the inbox (${liveCount}/${sourceCeiling})`;
+    const why = reactiveBusy
+      ? `reactive turn in flight: self-directed ${source} yields the subscription, capped to ${sourceCeiling} (${liveCount} live)`
+      : mode === "degraded" && source === "backlog"
+        ? `budget degraded: self-directed backlog throttled to ${sourceCeiling} (${liveCount} live; inbox unaffected)`
+        : throttleCeiling < dMax
+          ? `at throttled ceiling (${liveCount}/${sourceCeiling}; soft-throttle active)`
+          : source === "inbox"
+            ? `at concurrency ceiling (${liveCount}/${sourceCeiling})`
+            : `self-directed work yields ${REACTIVE_RESERVE} slots to the inbox (${liveCount}/${sourceCeiling})`;
     return decide(QUEUE, why);
   }
 

package/lib/resource-governor.test.mjs

@@ -25,6 +25,7 @@ import {
   FREEMEM_FLOOR_FRACTION,
   etimeToMs,
   reapStaleClaude,
+  REACTIVE_INFLIGHT_BACKLOG_MAX,
 } from "./resource-governor.mjs";
 
 test("availableMemoryBytes counts reclaimable pages, not just free ones", () => {
@@ -128,6 +129,57 @@ test("admit: inbox may use the whole envelope; the reactive reserve is for it",
   assert.match(r.reason, /concurrency ceiling/);
 });
 
+// ---------------------------------------------------------------------------
+// Reactive-in-flight: backlog yields the SUBSCRIPTION (not just a slot) to a
+// human/peer reply that is actively generating.
+// ---------------------------------------------------------------------------
+
+test("admit: while a reactive turn is in flight, backlog is capped to REACTIVE_INFLIGHT_BACKLOG_MAX → QUEUE", () => {
+  // Default cap is 1. With reactiveInFlight and even a single backlog session
+  // live, a second backlog spawn QUEUEs — the subscription is left to the reply.
+  assert.equal(REACTIVE_INFLIGHT_BACKLOG_MAX, 1);
+  const r = admit(
+    { source: "backlog" },
+    deps({ reactiveInFlight: 1, liveClaude: { count: 1, rssMB: 300 } }),
+  );
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.match(r.reason, /reactive turn in flight/);
+});
+
+test("admit: reactive-in-flight cap is HARDER than the steady-state reserve", () => {
+  // With 3 live and NO reactive turn, backlog still ADMITs (reserve leaves 5).
+  assert.equal(
+    admit({ source: "backlog" }, deps({ liveClaude: { count: 3, rssMB: 900 } })).decision,
+    DECISIONS.ADMIT,
+  );
+  // The SAME 3 live but a reply generating → QUEUE (cap 1, already exceeded).
+  assert.equal(
+    admit({ source: "backlog" }, deps({ reactiveInFlight: 1, liveClaude: { count: 3, rssMB: 900 } })).decision,
+    DECISIONS.QUEUE,
+  );
+});
+
+test("admit: a human reply is NEVER gated by reactive-in-flight (it IS the reactive turn)", () => {
+  // inbox/humanReply keeps the whole envelope even while other reactive turns run.
+  assert.equal(
+    admit({ source: "inbox" }, deps({ reactiveInFlight: 2, liveClaude: { count: 4, rssMB: 1200 } })).decision,
+    DECISIONS.ADMIT,
+  );
+  assert.equal(
+    admit({ source: "backlog", humanReply: true }, deps({ reactiveInFlight: 2, liveClaude: { count: 4, rssMB: 1200 } })).decision,
+    DECISIONS.ADMIT,
+  );
+});
+
+test("admit: one backlog session is still allowed alongside a reply (cap 1, not 0)", () => {
+  // A single trickle of backlog is fine — the cap is 1, so with 0 live it ADMITs.
+  const r = admit(
+    { source: "backlog" },
+    deps({ reactiveInFlight: 1, liveClaude: { count: 0, rssMB: 0 } }),
+  );
+  assert.equal(r.decision, DECISIONS.ADMIT);
+});
+
 test("admit: throttle ceiling clamps effectiveMax below dynamicMax → QUEUE earlier", () => {
   // dynamicMax 8 but soft-throttle pinned the ceiling to 3; 3 live → QUEUE.
   const r = admit({ source: "backlog" }, deps({ throttleCeiling: 3, liveClaude: { count: 3, rssMB: 1000 } }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.11.11",
+  "version": "2.11.13",
   "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/scripts/daemon/agent-daemon.mjs

@@ -51,7 +51,8 @@ import { makeInboxScanPoller } from "../poller/inbox-scan-poller.mjs";
 import { existsSync as _existsSync } from "fs";
 import { isPriorityItem } from "../poller/utils.mjs";
 import { classifyItem, isDirectedAtAgent } from "./classifier.mjs";
-import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions } from "./dispatcher.mjs";
+import { dispatch, getStatus, availableSlots, canDispatchBacklog, resetActiveSessions, yieldBacklogForReactive } from "./dispatcher.mjs";
+import { markReactiveStart, markReactiveEnd } from "../../lib/reactive-gate.mjs";
 import { buildPrompt } from "./prompt-builder.mjs";
 import { sendQuickResponse, sendHoldingMessage, isQuickReply } from "./responder.mjs";
 // ANSWER ASSURANCE (scripts/daemon/assurance.mjs). The guarantee that an ask is
@@ -551,7 +552,17 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
   const _electResponderVerdict = deps.electResponderVerdict
     || ((item2) => electResponderVerdict(item2, { electResponder: deps.electResponder, orgCfg: deps.orgCfg }));
   const _claudeAvailable = deps.claudeAvailable || claudeAvailable;
-
+  // Evicts already-running backlog to hand the subscription to this reactive
+  // turn; injectable so a test can stub the dispatcher's eviction.
+  const _yieldBacklog = deps.yieldBacklogForReactive || yieldBacklogForReactive;
+
+  // A reactive turn begins HERE and is marked until the function returns. While
+  // it is marked the governor QUEUEs new self-directed backlog (it yields the
+  // subscription, not just a slot), so the classify + reply calls below are not
+  // starved. markReactiveEnd runs in the finally so a filtered/ignored/errored
+  // item releases the gate exactly once. The heavier lever — evicting backlog
+  // that is ALREADY running — fires only just before a real generate (below).
+  markReactiveStart();
   try {
     const isDm = item.is_dm === true;
     // Carry the routing decision on the item so everything downstream of here —
@@ -779,6 +790,12 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // is exactly today's behaviour.
     if (_isQuickReply(classResult, routed)) {
       console.log(`[daemon] Quick reply path for ${item.sender} (${classResult.model})`);
+      // Free the subscription NOW: evict any already-running backlog sessions
+      // down to REACTIVE_INFLIGHT_BACKLOG_MAX so this reply's own claude call
+      // runs on a nearly-idle subscription instead of queueing behind opus
+      // backlog (the measured cause of 19s quick replies / 30s classify
+      // timeouts). No-op when backlog is already at/under the cap.
+      try { _yieldBacklog(); } catch { /* fail-open: never block a reply on eviction */ }
       const result = await _sendQuickResponse(item, classResult, routed);
       if (result.sent) {
         markProcessed(item, service);
@@ -970,6 +987,9 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     // recoverInFlight() to re-deliver on restart.
     recordInFlight(item, service);
     if (obligationKeyForItem) noteSession(obligationKeyForItem, null);
+    // A reactive SESSION (complex reply) also competes for the subscription —
+    // yield already-running backlog to it, same as the quick-reply path.
+    try { _yieldBacklog(); } catch { /* fail-open */ }
     _dispatch(prompt, item, classResult, "inbox", {
       // Carried into the session child's env so its CLI send lanes stamp their
       // delivery receipts with the debt they discharge. This is what lets the
@@ -1108,6 +1128,12 @@ export async function answerItem(item, service, itemId, trace_id, deps = {}, rou
     recordClassification(false);
     emitEvent({ type: EVENT_TYPES.ERROR, trace_id, attrs: { item_id: itemId, service, stage: "process_item", error: err.message } });
     return { ok: false, path: "error", reason: err.message };
+  } finally {
+    // The reactive turn is over (a reply was sent, a session was spawned, or the
+    // item was filtered). Release the subscription back to backlog; the next
+    // sweep re-dispatches whatever was evicted or held. Balanced 1:1 with the
+    // markReactiveStart above, and clamped at zero inside the gate.
+    markReactiveEnd();
   }
 }
 

package/scripts/daemon/agent-daemon.test.mjs

@@ -831,6 +831,21 @@ test("NO FALLTHROUGH: a TRANSIENT quick-reply failure still falls through to a f
   assert.equal(res.path, "session");
 });
 
+test("REACTIVE PRIORITY: a quick reply yields the subscription (evicts backlog) BEFORE it generates", async () => {
+  resetState();
+  const item = { id: "MSG-YIELD", raw_ref: "slack:DYIELD:1", service: "slack", channel: "dm/ceo", channel_id: "DYIELD001", is_dm: true, sender: "ceo", subject: "quick q", content: "you around?" };
+  const order = [];
+  const res = await daemon.answerItem(item, "slack", "MSG-YIELD", "trace-yield", {
+    classify: async () => ({ priority: "high", action: "respond", model: "haiku", summary: "quick answer", category: "action_required", directed_at_agent: true }),
+    isQuickReply: () => true,
+    yieldBacklogForReactive: () => { order.push("yield"); return 2; },
+    sendQuickResponse: async () => { order.push("send"); return { sent: true }; },
+    claudeAvailable: () => true,
+  });
+  assert.equal(res.path, "quick_reply");
+  assert.deepEqual(order, ["yield", "send"], "backlog is yielded the subscription BEFORE the reply's claude call, not after");
+});
+
 test("resolveSelfMemberId reads the member cuid from the res frame's `result` (own-echo keystone)", async () => {
   daemon._resetSelfMemberId();
   const pk = process.env.COHORT_API_KEY, po = process.env.COHORT_ORG_ID, pa = process.env.COHORT_AGENT_ID;

package/scripts/daemon/cadence-consumer.mjs

@@ -901,7 +901,23 @@ export function startConsumer(opts = {}) {
     // the shared breaker and REQUEUE the tick unchanged (decision:"deferred")
     // instead of failTick — a 429 is an upstream gate, not a per-event failure,
     // so it must not burn this cadence's retry budget toward the DLQ.
-    if (rateGuard.classifyStderr(result.stderr_tail || result.error || "")) {
+    const cadenceOut = result.stderr_tail || result.error || result.stdout_tail || "";
+    const cadenceUl = rateGuard.classifyUsageLimit?.(cadenceOut, { agentRoot }) ?? { isLimit: false, resetAt: null };
+    if (cadenceUl.isLimit) {
+      try {
+        const rec = rateGuard.recordUsageLimit(RATE_PROVIDER, cadenceUl.resetAt, { agentRoot });
+        log({ level: "warn", stage: "subsession_usage_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil, reset_at: rec.resetAt });
+      } catch { /* */ }
+      // Same requeue-unchanged handling as a 429: a window-usage limit is a
+      // shared, provider-side gate — not evidence THIS cadence is broken — so
+      // requeue without failTick or a circuit trip; the shared breaker (held
+      // until reset) gates re-escalation.
+      requeueTick(agentRoot, event);
+      stats.retries += 1;
+      stats.last_decision = "deferred";
+      return { ok: false, decision: "deferred" };
+    }
+    if (rateGuard.classifyStderr(cadenceOut)) {
       try {
         const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot });
         log({ level: "warn", stage: "subsession_rate_limited", id: event.id, cadence: event.cadence, open_until: rec.openUntil });

package/scripts/daemon/classifier.mjs

@@ -455,7 +455,7 @@ async function runClaudeCLI(systemPrompt, userPrompt) {
     const args = [
       "--print",
       ...sessionPermissionArgs({ source: "classifier" }),
-      ...daemonClaudeArgs(),
+      ...daemonClaudeArgs(undefined, { source: "classifier" }),
       "--model", ANTHROPIC_MODEL,
       "--append-system-prompt", systemPrompt,
     ];

package/scripts/daemon/dispatcher-governance.test.mjs

@@ -352,6 +352,89 @@ test("M2: evicting a backlog session for a priority inbox item clears its resume
   }
 });
 
+// ---------------------------------------------------------------------------
+// yieldBacklogForReactive — a reply about to hit the subscription evicts
+// already-running BACKLOG down to REACTIVE_INFLIGHT_BACKLOG_MAX, and NEVER
+// touches an inbox/reactive session.
+// ---------------------------------------------------------------------------
+
+/** A child stub that records whether it was killed (never launches anything). */
+function killTrackingProc() {
+  const handlers = {};
+  const p = {
+    stdout: { on: () => {} },
+    stderr: { on: () => {} },
+    on: (ev, cb) => { handlers[ev] = cb; },
+    kill: () => { p.killed = true; },
+    killed: false,
+    _handlers: handlers,
+  };
+  return p;
+}
+
+test("yieldBacklogForReactive: evicts backlog down to the cap and spares every inbox session", async () => {
+  process.env.DAEMON_MAX_CONCURRENT = "8";
+  const { mod, dir } = await freshDispatcher();
+  try {
+    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
+    const procs = [];
+    const restore = mod.setSpawnForTests(() => { const p = killTrackingProc(); procs.push(p); return p; });
+    try {
+      // 3 backlog sessions (dispatch order = age order) …
+      for (let i = 0; i < 3; i++) {
+        mod.dispatch("backlog work", { id: `BL-${i}`, title: `bl ${i}`, source_file: "q.yaml" },
+          { summary: `bl ${i}`, priority: "low", model: "sonnet" }, "backlog");
+      }
+      // … and 2 inbox sessions, all running concurrently.
+      for (let i = 0; i < 2; i++) {
+        mod.dispatch("inbox work", { id: `IN-${i}`, channel: `D${i}` },
+          { summary: `in ${i}`, priority: "normal", model: "sonnet" }, "inbox");
+      }
+      assert.equal(mod.getStatus().active_sessions, 5, "3 backlog + 2 inbox live");
+
+      // A reply is about to generate → yield the subscription. Cap is 1, so 2 of
+      // the 3 backlog sessions are evicted; the inbox sessions are never touched.
+      const evicted = mod.yieldBacklogForReactive();
+      assert.equal(evicted, 2, "evicts backlog down to REACTIVE_INFLIGHT_BACKLOG_MAX (1)");
+
+      const backlogProcs = procs.slice(0, 3);
+      const inboxProcs = procs.slice(3, 5);
+      assert.equal(backlogProcs.filter((p) => p.killed).length, 2, "exactly two backlog procs killed");
+      assert.equal(inboxProcs.filter((p) => p.killed).length, 0, "no inbox/reactive proc is ever killed");
+
+      // Idempotent: already at the cap → a second call is a no-op.
+      assert.equal(mod.yieldBacklogForReactive(), 0, "no further eviction once at the cap");
+    } finally { restore(); }
+  } finally {
+    delete process.env.DAEMON_MAX_CONCURRENT;
+    await cleanup(dir);
+  }
+});
+
+test("yieldBacklogForReactive: no-op when backlog is already at/under the cap", async () => {
+  process.env.DAEMON_MAX_CONCURRENT = "8";
+  const { mod, dir } = await freshDispatcher();
+  try {
+    mod.setGovernanceForTests({ governor: fakeGovernor("ADMIT"), rateGuard: allowRate, budgetGuard: noBudget });
+    const restore = mod.setSpawnForTests(() => killTrackingProc());
+    try {
+      // Only inbox sessions running — nothing self-directed to yield.
+      for (let i = 0; i < 3; i++) {
+        mod.dispatch("inbox work", { id: `IN-${i}`, channel: `D${i}` },
+          { summary: `in ${i}`, priority: "normal", model: "sonnet" }, "inbox");
+      }
+      assert.equal(mod.yieldBacklogForReactive(), 0, "nothing to evict");
+      // One backlog session — at the cap of 1 → still a no-op.
+      mod.dispatch("bl", { id: "BL-ONE", title: "one", source_file: "q.yaml" },
+        { summary: "one", priority: "low", model: "sonnet" }, "backlog");
+      assert.equal(mod.yieldBacklogForReactive(), 0, "a single backlog session is within the cap");
+    } finally { restore(); }
+  } finally {
+    delete process.env.DAEMON_MAX_CONCURRENT;
+    await cleanup(dir);
+  }
+});
+
 // ---------------------------------------------------------------------------
 // M1 — a governor/budget/rate DEFER that force-queues an inbox item while NO
 // session is running must arm a single (debounced) re-drain timer, so the item

package/scripts/daemon/dispatcher.mjs

@@ -622,8 +622,12 @@ function defaultSpawnResume({ marker }) {
       clearResumePending(marker.sessionId);
       logSession({ event: "resume_completed", sessionId: marker.sessionId, item_id: marker.itemId });
     } else {
-      // A 429 during resume must open the breaker so subsequent spawns gate.
-      if (rateGuard.classifyStderr(stderr)) {
+      // A usage limit or 429 during resume must open the breaker so subsequent
+      // spawns gate. Usage-limit → hold until reset; 429 → transient backoff.
+      const ul = rateGuard.classifyUsageLimit?.(stderr, { agentRoot: AGENT_REPO_DIR }) ?? { isLimit: false, resetAt: null };
+      if (ul.isLimit) {
+        try { rateGuard.recordUsageLimit(RATE_PROVIDER, ul.resetAt, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+      } else if (rateGuard.classifyStderr(stderr)) {
         try { rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
       }
       logSession({ event: "resume_exit_nonzero", sessionId: marker.sessionId, item_id: marker.itemId, exit_code: code });
@@ -680,42 +684,97 @@ function countBySource(source) {
 
 /**
  * Evict the lowest-priority, longest-running backlog session to make room
- * for a high-priority inbox item. Returns true if a session was evicted.
+ * for a high-priority inbox item (or to yield the subscription to a reactive
+ * reply). Returns true if a session was evicted.
+ *
+ * @param {string} [why] human-readable eviction reason for the log/ledger.
+ */
+const EVICT_PRIORITY_RANK = { low: 0, normal: 1, high: 2, critical: 3 };
+
+/**
+ * SIGTERM one backlog session and retire its resume marker. Shared by the
+ * priority-preemption path and the reactive-yield path so both do the identical
+ * bookkeeping. Marks `s.evicting` so a SECOND selection in the same synchronous
+ * pass (before the async close handler deletes the session) cannot re-target the
+ * same not-yet-closed session — the bug that let one kill masquerade as many.
  */
-function evictForPriority() {
-  const priorityRank = { low: 0, normal: 1, high: 2, critical: 3 };
+function _evictSession(id, s, why) {
+  console.log(`[dispatcher] PREEMPT: Evicting backlog session ${id} (${s.classResult.summary}) for ${why}`);
+  logSession({ event: "evicted", sessionId: id, reason: "priority_preemption", summary: s.classResult.summary });
+  // M2: clear the resume-pending marker BEFORE the SIGTERM. Eviction is a
+  // deliberate preemption, not a crash — the item stays on disk and the
+  // backlog sweep re-dispatches it normally (acquiring the item-claim).
+  // If we left the marker, a reboot's reconcileResumePending would re-spawn
+  // it WITHOUT the claim while sweepBacklog independently claim+dispatched
+  // the same item → two concurrent runs. The non-zero SIGTERM close would
+  // otherwise keep the marker, so we must retire it here.
+  clearResumePending(id);
+  s.evicting = true;
+  s.process.kill("SIGTERM");
+}
+
+/** The single lowest-priority, oldest evictable backlog session, or null. */
+function _worstBacklogSession() {
   let worst = null;
   let worstId = null;
-
   for (const [id, s] of activeSessions) {
-    if (s.source !== "backlog") continue;
-    const rank = priorityRank[s.classResult.priority] || 1;
-    if (!worst) {
-      worst = s; worstId = id;
-      continue;
-    }
-    const worstRank = priorityRank[worst.classResult.priority] || 1;
-    // Prefer to evict lower priority; break ties by oldest session
+    if (s.source !== "backlog" || s.evicting) continue;
+    const rank = EVICT_PRIORITY_RANK[s.classResult.priority] ?? 1;
+    if (!worst) { worst = s; worstId = id; continue; }
+    const worstRank = EVICT_PRIORITY_RANK[worst.classResult.priority] ?? 1;
+    // Prefer to evict lower priority; break ties by oldest session.
     if (rank < worstRank || (rank === worstRank && s.startTime < worst.startTime)) {
       worst = s; worstId = id;
     }
   }
+  return worst ? { id: worstId, s: worst } : null;
+}
 
-  if (worst) {
-    console.log(`[dispatcher] PREEMPT: Evicting backlog session ${worstId} (${worst.classResult.summary}) for priority inbox item`);
-    logSession({ event: "evicted", sessionId: worstId, reason: "priority_preemption", summary: worst.classResult.summary });
-    // M2: clear the resume-pending marker BEFORE the SIGTERM. Eviction is a
-    // deliberate preemption, not a crash — the item stays on disk and the
-    // backlog sweep re-dispatches it normally (acquiring the item-claim).
-    // If we left the marker, a reboot's reconcileResumePending would re-spawn
-    // it WITHOUT the claim while sweepBacklog independently claim+dispatched
-    // the same item → two concurrent runs. The non-zero SIGTERM close would
-    // otherwise keep the marker, so we must retire it here.
-    clearResumePending(worstId);
-    worst.process.kill("SIGTERM");
-    return true;
+function evictForPriority(why = "priority inbox item") {
+  const target = _worstBacklogSession();
+  if (!target) return false;
+  _evictSession(target.id, target.s, why);
+  return true;
+}
+
+/**
+ * Yield the shared subscription to a reactive turn that is about to generate.
+ *
+ * REACTIVE_RESERVE keeps a slot free and the governor now QUEUEs NEW backlog
+ * while a reply is in flight — but neither of those stops backlog sessions that
+ * are ALREADY RUNNING from saturating the one Max subscription (the measured
+ * cause of 19s quick replies and 30s classify timeouts). This is the other half:
+ * called the instant a reactive reply is about to hit `claude`, it evicts
+ * already-running BACKLOG sessions down to REACTIVE_INFLIGHT_BACKLOG_MAX so the
+ * reply's own call runs on a nearly-idle subscription.
+ *
+ * Safe and conservative: it never touches another reactive/inbox session (only
+ * `source === "backlog"`); an evicted item stays on disk and the sweep re-claims
+ * it, so backlog loses concurrency for a few seconds, never work. No-op when
+ * backlog is already at/under the cap. Returns the number of sessions evicted.
+ */
+export function yieldBacklogForReactive() {
+  const cap = Math.max(0, Number(governor.REACTIVE_INFLIGHT_BACKLOG_MAX ?? 1));
+  // Live (not-already-evicting) backlog sessions, worst-first, so we shed the
+  // lowest-priority / oldest work and keep the freshest `cap` running.
+  const live = [];
+  for (const [id, s] of activeSessions) {
+    if (s.source === "backlog" && !s.evicting) live.push({ id, s });
   }
-  return false;
+  live.sort((a, b) => {
+    const ra = EVICT_PRIORITY_RANK[a.s.classResult.priority] ?? 1;
+    const rb = EVICT_PRIORITY_RANK[b.s.classResult.priority] ?? 1;
+    return ra - rb || a.s.startTime - b.s.startTime;
+  });
+  let evicted = 0;
+  for (let i = 0; i < live.length - cap; i++) {
+    _evictSession(live[i].id, live[i].s, "reactive reply waiting on the subscription");
+    evicted++;
+  }
+  if (evicted > 0) {
+    console.log(`[dispatcher] Yielded subscription to a reactive reply: evicted ${evicted} backlog session(s) (cap ${cap})`);
+  }
+  return evicted;
 }
 
 /**
@@ -1271,11 +1330,25 @@ function spawnSession(entry) {
     if (code === 0) {
       clearResumePending(sessionId);
       try { rateGuard.recordSuccess(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
-    } else if (rateGuard.classifyStderr(stderr)) {
-      try {
-        const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
-        logSession({ event: "rate_limit_recorded", sessionId, open_until: rec.openUntil, consecutive: rec.consecutive429 });
-      } catch { /* */ }
+    } else {
+      // A Max/subscription USAGE limit ("you've hit your session limit · resets
+      // 9:40pm") is checked FIRST and on BOTH streams — for `claude --print` it
+      // lands on stdout, not stderr. It holds the breaker until the window
+      // RESETS (not a decorrelated 429 backoff), so the seat stops storming a
+      // drained pool. A plain 429/overload falls through to the transient path.
+      const combined = `${stdout || ""}\n${stderr || ""}`;
+      const ul = rateGuard.classifyUsageLimit?.(combined, { agentRoot: AGENT_REPO_DIR }) ?? { isLimit: false, resetAt: null };
+      if (ul.isLimit) {
+        try {
+          const rec = rateGuard.recordUsageLimit(RATE_PROVIDER, ul.resetAt, { agentRoot: AGENT_REPO_DIR });
+          logSession({ event: "usage_limit_recorded", sessionId, open_until: rec.openUntil, reset_at: rec.resetAt });
+        } catch { /* */ }
+      } else if (rateGuard.classifyStderr(stderr)) {
+        try {
+          const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
+          logSession({ event: "rate_limit_recorded", sessionId, open_until: rec.openUntil, consecutive: rec.consecutive429 });
+        } catch { /* */ }
+      }
     }
 
     // Release item lock — MUST use same key order as acquireLock in daemon

package/scripts/daemon/responder.mjs

@@ -259,7 +259,7 @@ function runClaudeCLI(systemPrompt, userPrompt, model, opts = {}) {
     const args = [
       "--print",
       ...sessionPermissionArgs({ source: "responder" }),
-      ...daemonClaudeArgs(),
+      ...daemonClaudeArgs(undefined, { source: "responder" }),
       "--model", model,
       "--append-system-prompt", systemPrompt,
       // --output-format json is only valid in combination with --print (per b1