@cohortapp/agent-sdk 2.11.12 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.11.12",
+  "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/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.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 });
@@ -1326,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