@cohortapp/agent-sdk 2.11.12 → 2.11.14

package/lib/budget-guard.mjs

@@ -1086,3 +1086,99 @@ function formatNotice(band, status) {
   }
   return `Seat spend at ${status.pct}% ($${usd} / $${cap} today) — heads-up only, nothing is degraded yet.${envelope}`;
 }
+
+// ---------------------------------------------------------------------------
+// Rolling usage window (subscription seats: TOKEN VOLUME, not dollars)
+// ---------------------------------------------------------------------------
+//
+// A Max seat has no dollar meter; what it can exhaust is a rolling token window
+// (≈5-hour session + weekly). The exact caps are UNPUBLISHED, so pacing is
+// DEFAULT-OFF: with GOV_WINDOW_5H_TOKENS / GOV_WEEK_TOKENS unset (0),
+// windowBand() is always "ok" and nothing paces — but the rolling volume is
+// still COMPUTED and surfaced so an operator can watch usage climb and calibrate
+// the caps. Reads the SAME cost-tracking ledger dailyStatus uses; "tokens" here
+// is input+output+cache summed over the window. The hard safety net remains
+// rate-guard's usage-limit recognition (recordUsageLimit holds the breaker until
+// reset); this is the proactive, opt-in layer above it.
+
+const WINDOW_5H_MS = 5 * 60 * 60 * 1000;
+const WINDOW_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+export const WINDOW_5H_TOKEN_CAP = Math.max(0, parseInt(process.env.GOV_WINDOW_5H_TOKENS || "0", 10) || 0);
+export const WINDOW_WEEK_TOKEN_CAP = Math.max(0, parseInt(process.env.GOV_WEEK_TOKENS || "0", 10) || 0);
+export const WINDOW_APPROACH_FRACTION = (() => {
+  const f = parseFloat(process.env.GOV_WINDOW_APPROACH || "0.8");
+  return f > 0 && f < 1 ? f : 0.8;
+})();
+
+function rowTokens(r) {
+  return (
+    (Number(r.input_tokens) || 0) +
+    (Number(r.output_tokens) || 0) +
+    (Number(r.cache_read_input_tokens) || 0) +
+    (Number(r.cache_creation_input_tokens) || 0)
+  );
+}
+
+/**
+ * Rolling token volume + session count over the last 5 hours and 7 days, from
+ * the cost-tracking ledger. Never throws (a missing/unreadable ledger → zeros).
+ */
+export function rollingWindowUsage(deps) {
+  const now = clock(deps)();
+  const dir = ledgerDir(deps);
+  let t5 = 0, s5 = 0, t7 = 0, s7 = 0;
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)).sort().slice(-8);
+  } catch {
+    return { window5hTokens: 0, window5hSessions: 0, week7dTokens: 0, week7dSessions: 0 };
+  }
+  for (const f of files) {
+    let body;
+    try { body = readFileSync(join(dir, f), "utf-8"); } catch { continue; }
+    for (const line of body.split("\n")) {
+      if (!line.trim()) continue;
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }
+      const at = r && r.ts ? Date.parse(r.ts) : NaN;
+      if (!Number.isFinite(at)) continue;
+      const dt = now - at;
+      if (dt < 0 || dt > WINDOW_WEEK_MS) continue;
+      const tok = rowTokens(r);
+      t7 += tok; s7 += 1;
+      if (dt <= WINDOW_5H_MS) { t5 += tok; s5 += 1; }
+    }
+  }
+  return { window5hTokens: t5, window5hSessions: s5, week7dTokens: t7, week7dSessions: s7 };
+}
+
+/**
+ * The usage-window band: "ok" | "approaching" | "at". DEFAULT-OFF — an unset
+ * (0) cap yields "ok" for that horizon, so the fleet paces on the window only
+ * once an operator has calibrated GOV_WINDOW_5H_TOKENS / GOV_WEEK_TOKENS. The
+ * band is the WORSE of the 5h and weekly horizons.
+ */
+export function windowBand(deps) {
+  const u = rollingWindowUsage(deps);
+  // Caps come from deps first (tests / a per-seat override), else the env consts.
+  const cap5 = deps && deps.cap5h != null ? deps.cap5h : WINDOW_5H_TOKEN_CAP;
+  const cap7 = deps && deps.capWeek != null ? deps.capWeek : WINDOW_WEEK_TOKEN_CAP;
+  const frac = deps && deps.approachFraction != null ? deps.approachFraction : WINDOW_APPROACH_FRACTION;
+  const bandFor = (used, cap) => {
+    if (!cap || cap <= 0) return "ok";
+    if (used >= cap) return "at";
+    if (used >= cap * frac) return "approaching";
+    return "ok";
+  };
+  const rank = { ok: 0, approaching: 1, at: 2 };
+  const b5 = bandFor(u.window5hTokens, cap5);
+  const b7 = bandFor(u.week7dTokens, cap7);
+  const band = rank[b5] >= rank[b7] ? b5 : b7;
+  return {
+    band,
+    ...u,
+    cap5h: cap5 || null,
+    capWeek: cap7 || null,
+    active: cap5 > 0 || cap7 > 0,
+  };
+}

package/lib/budget-guard.test.mjs

@@ -18,6 +18,8 @@ import {
   readNotified,
   BANDS,
   DEFAULT_DAILY_SPEND_CAP_USD,
+  rollingWindowUsage,
+  windowBand,
 } from "./budget-guard.mjs";
 
 const FIXED = Date.UTC(2026, 5, 9, 12, 0, 0); // 2026-06-09T12:00:00Z
@@ -363,3 +365,63 @@ test("dailyStatus: a subscription-auth seat STILL bands on session volume (a rea
     assert.equal(sub.mode, "degraded");
   } finally { await rm(dir); }
 });
+
+// ---------------------------------------------------------------------------
+// rolling usage window (token volume) + windowBand (default-off pacing)
+// ---------------------------------------------------------------------------
+
+function seedWindowLedger(dir, rows) {
+  // rows: [{ minsAgo, tokens }] written to today's + yesterday's files by ts.
+  const now = FIXED;
+  const byFile = {};
+  for (const r of rows) {
+    const at = new Date(now - r.minsAgo * 60_000);
+    const day = at.toISOString().slice(0, 10);
+    (byFile[day] ||= []).push(JSON.stringify({
+      ts: at.toISOString(),
+      total_cost_usd: 0.1, model: "sonnet", cadence: "x",
+      input_tokens: r.tokens, output_tokens: 0,
+    }));
+  }
+  for (const [day, lines] of Object.entries(byFile)) {
+    writeFileSync(join(dir, `${day}.jsonl`), lines.join("\n") + "\n");
+  }
+}
+
+test("rollingWindowUsage sums tokens/sessions in the 5h and 7d windows", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [
+      { minsAgo: 10, tokens: 1000 },   // in 5h + 7d
+      { minsAgo: 60, tokens: 2000 },   // in 5h + 7d
+      { minsAgo: 400, tokens: 500 },   // >5h (400m), in 7d
+      { minsAgo: 60 * 24 * 8, tokens: 9999 }, // >7d — excluded
+    ]);
+    const u = rollingWindowUsage({ ledgerDir: dir, now: clk });
+    assert.equal(u.window5hTokens, 3000);
+    assert.equal(u.window5hSessions, 2);
+    assert.equal(u.week7dTokens, 3500);
+    assert.equal(u.week7dSessions, 3);
+  } finally { await rm(dir); }
+});
+
+test("windowBand is DEFAULT-OFF: no caps → always 'ok' however high usage climbs", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [{ minsAgo: 5, tokens: 10_000_000 }]);
+    const b = windowBand({ ledgerDir: dir, now: clk }); // no caps
+    assert.equal(b.band, "ok");
+    assert.equal(b.active, false);
+    assert.equal(b.window5hTokens, 10_000_000);
+  } finally { await rm(dir); }
+});
+
+test("windowBand bands 'approaching' then 'at' once a 5h cap is calibrated", async () => {
+  const dir = await makeLedgerDir();
+  try {
+    seedWindowLedger(dir, [{ minsAgo: 5, tokens: 8500 }]);
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 10_000 }).band, "approaching"); // 85% of 10k
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 8000 }).band, "at");             // over 8k
+    assert.equal(windowBand({ ledgerDir: dir, now: clk, cap5h: 100_000 }).band, "ok");          // well under
+  } finally { await rm(dir); }
+});

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/resource-governor.mjs

@@ -504,6 +504,16 @@ export function admit(req = {}, deps) {
   if (mode === "suspended" && (source === "backlog" || source === "cadence")) {
     return decide(DEFER, "budget suspended (>=125% of the seat envelope): deferring non-inbox work");
   }
+  // USAGE-WINDOW PACING (default-off; only active once GOV_WINDOW_* caps are
+  // calibrated — see budget-guard.windowBand). At the rolling window's limit,
+  // pause self-directed work so a burst spreads across windows instead of
+  // exhausting one; a direct human reply is never paced. "approaching" is folded
+  // into the concurrency ceiling below (throttle, don't stop). `windowBand`
+  // defaults to "ok" so an uncalibrated seat behaves exactly as before.
+  const windowBand = req.windowBand || "ok";
+  if (windowBand === "at" && !humanReply) {
+    return decide(DEFER, `usage window at limit: deferring ${source} work so it spreads across windows; direct human replies continue`);
+  }
   // NOTE: `degraded` (>=100% / unfunded) no longer hard-stops backlog. Owner
   // instruction (2026-08-25): THROTTLE, don't stop — the seat keeps a thin
   // trickle of self-directed work so autonomous progress never fully halts,
@@ -524,10 +534,14 @@ export function admit(req = {}, deps) {
   // 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;
+  // "approaching" the usage window → throttle self-directed work toward a trickle
+  // (like a reactive turn) so the seat glides into the window rather than slamming
+  // it. Default-off: windowBand is "ok" unless GOV_WINDOW_* caps are set.
+  const windowApproaching = windowBand === "approaching";
   let sourceCeiling;
   if (humanReply) {
     sourceCeiling = effectiveMax;
-  } else if (reactiveBusy) {
+  } else if (reactiveBusy || windowApproaching) {
     sourceCeiling = Math.min(effectiveMax, REACTIVE_INFLIGHT_BACKLOG_MAX);
     if (mode === "degraded" && source === "backlog") {
       sourceCeiling = Math.min(sourceCeiling, DEGRADED_BACKLOG_MAX);
@@ -540,6 +554,8 @@ export function admit(req = {}, deps) {
   if (liveCount >= sourceCeiling) {
     const why = reactiveBusy
       ? `reactive turn in flight: self-directed ${source} yields the subscription, capped to ${sourceCeiling} (${liveCount} live)`
+      : windowApproaching
+      ? `usage window approaching: self-directed ${source} throttled to ${sourceCeiling} to spread across windows (${liveCount} live)`
       : mode === "degraded" && source === "backlog"
         ? `budget degraded: self-directed backlog throttled to ${sourceCeiling} (${liveCount} live; inbox unaffected)`
         : throttleCeiling < dMax

package/lib/resource-governor.test.mjs

@@ -180,6 +180,33 @@ test("admit: one backlog session is still allowed alongside a reply (cap 1, not
   assert.equal(r.decision, DECISIONS.ADMIT);
 });
 
+// ---------------------------------------------------------------------------
+// Usage-window pacing (default-off; driven by req.windowBand from budget-guard)
+// ---------------------------------------------------------------------------
+
+test("admit: windowBand 'at' DEFERS self-directed work; a human reply is never paced", () => {
+  assert.equal(admit({ source: "backlog", windowBand: "at" }, deps()).decision, DECISIONS.DEFER);
+  assert.equal(admit({ source: "cadence", windowBand: "at" }, deps()).decision, DECISIONS.DEFER);
+  // inbox / humanReply continue at the window limit
+  assert.equal(admit({ source: "inbox", windowBand: "at" }, deps()).decision, DECISIONS.ADMIT);
+  assert.equal(admit({ source: "backlog", humanReply: true, windowBand: "at" }, deps()).decision, DECISIONS.ADMIT);
+});
+
+test("admit: windowBand 'approaching' throttles backlog to a trickle (QUEUE), inbox unaffected", () => {
+  // 1 already live → backlog capped to REACTIVE_INFLIGHT_BACKLOG_MAX(1) → QUEUE
+  const r = admit({ source: "backlog", windowBand: "approaching" }, deps({ liveClaude: { count: 1, rssMB: 300 } }));
+  assert.equal(r.decision, DECISIONS.QUEUE);
+  assert.match(r.reason, /usage window approaching/);
+  // inbox still admits at the same live count
+  assert.equal(admit({ source: "inbox", windowBand: "approaching" }, deps({ liveClaude: { count: 1, rssMB: 300 } })).decision, DECISIONS.ADMIT);
+});
+
+test("admit: windowBand default (undefined/'ok') changes nothing — pacing is off by default", () => {
+  // 3 live, no window signal → backlog still ADMITs (reserve leaves 5)
+  assert.equal(admit({ source: "backlog" }, deps({ liveClaude: { count: 3, rssMB: 900 } })).decision, DECISIONS.ADMIT);
+  assert.equal(admit({ source: "backlog", windowBand: "ok" }, deps({ liveClaude: { count: 3, rssMB: 900 } })).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.12",
+  "version": "2.11.14",
   "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

@@ -601,8 +601,10 @@ export function startConsumer(opts = {}) {
       // as a human reply, and every cadence tick arrives as `source:"cadence"`.
       // Two gates, one predicate, or the rung silences the inbox on the second
       // hop instead of the first.
+      let windowBand;
+      try { windowBand = budgetGuardModule.windowBand?.({ agentRoot })?.band; } catch { /* default-off */ }
       const adm = governor.admit(
-        { source: "cadence", mode, humanReply: cadence ? isHumanLaneCadence(cadence) : false },
+        { source: "cadence", mode, humanReply: cadence ? isHumanLaneCadence(cadence) : false, windowBand },
         governor.defaultDeps({ agentRoot })
       );
       if (adm.decision !== "ADMIT") return { admit: false, reason: adm.reason || adm.decision };
@@ -901,7 +903,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

@@ -191,11 +191,45 @@ test("reconcile blocks a marker that is older than the freshness window", async
   } finally { await cleanup(dir); }
 });
 
+test("resume reconcile DEFERS (never re-storms) when the backlog budget is 0 (reactive-only seat)", async () => {
+  // DAEMON_MAX_CONCURRENT=3 → backlogCap = 3 - RESERVED_INBOX_SLOTS(3) = 0, so a
+  // reactive-only seat must resume NOTHING on boot — the fresh-seat storm root.
+  process.env.DAEMON_MAX_CONCURRENT = "3";
+  const { mod, dir } = await freshDispatcher();
+  try {
+    plantMarker(dir, "s-a", { itemId: "BL-A", sourceFile: "q.yaml", startedAt: Date.now() });
+    plantMarker(dir, "s-b", { itemId: "BL-B", sourceFile: "q.yaml", startedAt: Date.now() });
+    let spawned = 0;
+    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
+    assert.equal(spawned, 0, "no resume spawns on a budget-0 seat");
+    assert.equal(stats.resumed, 0);
+    assert.equal(stats.deferred, 2, "both live markers deferred, not blocked/expired");
+    // markers are LEFT on disk (deferred, not retired) for a later reconcile
+    const left = readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json"));
+    assert.equal(left.length, 2, "deferred markers persist");
+  } finally { delete process.env.DAEMON_MAX_CONCURRENT; await cleanup(dir); }
+});
+
+test("resume reconcile is GATED (resumes nothing) while the shared breaker is open", async () => {
+  const { mod, dir } = await freshDispatcher();
+  try {
+    mod.setGovernanceForTests({ rateGuard: { checkRateLimit: () => ({ allowed: false, retryAt: Date.now() + 60_000 }) } });
+    plantMarker(dir, "s-x", { itemId: "BL-X", sourceFile: "q.yaml", startedAt: Date.now() });
+    let spawned = 0;
+    const stats = mod.reconcileResumePending({ spawnResume: () => { spawned++; } });
+    assert.equal(spawned, 0, "an open breaker (e.g. a usage-limit hold) blocks all resume");
+    assert.equal(stats.resumed, 0);
+    assert.equal(stats.scanned, 0, "returns before scanning when the breaker is open");
+    // the marker is untouched, ready for the next reconcile after the breaker clears
+    assert.equal(readdirSync(join(dir, "state/sessions/resume-pending")).filter((f) => f.endsWith(".json")).length, 1);
+  } finally { await cleanup(dir); }
+});
+
 test("reconcile on an empty resume-pending dir is a no-op", async () => {
   const { mod, dir } = await freshDispatcher();
   try {
     const stats = mod.reconcileResumePending({ spawnResume: () => { throw new Error("should not spawn"); } });
-    assert.deepEqual(stats, { scanned: 0, resumed: 0, blocked: 0, expired: 0 });
+    assert.deepEqual(stats, { scanned: 0, resumed: 0, blocked: 0, expired: 0, deferred: 0 });
   } finally { await cleanup(dir); }
 });
 

package/scripts/daemon/dispatcher.mjs

@@ -75,7 +75,11 @@ function admitFor(source, priority) {
         console.warn(`[dispatcher] budget ${st.mode}: ${st.pct}% of $${st.capUSD}/day (${st.capSource}) — gating ${source} work`);
       }
     } catch { /* budget read best-effort */ }
-    return governor.admit({ source, priority, mode }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
+    // Usage-window band (default-off unless GOV_WINDOW_* caps set) → the governor
+    // paces self-directed work as the rolling window fills. Best-effort.
+    let windowBand;
+    try { windowBand = budgetGuard.windowBand?.({ agentRoot: AGENT_REPO_DIR })?.band; } catch { /* */ }
+    return governor.admit({ source, priority, mode, windowBand }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
   } catch {
     return { decision: "ADMIT", reason: "governor-error-fail-open", snapshot: {} };
   }
@@ -499,13 +503,32 @@ export function resetActiveSessions(opts = {}) {
  */
 export function reconcileResumePending(opts = {}) {
   const now = (typeof opts.now === "function" ? opts.now : Date.now)();
-  const stats = { scanned: 0, resumed: 0, blocked: 0, expired: 0 };
+  const stats = { scanned: 0, resumed: 0, blocked: 0, expired: 0, deferred: 0 };
   let files = [];
   try {
     if (!existsSync(RESUME_PENDING_DIR)) return stats;
     files = readdirSync(RESUME_PENDING_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp"));
   } catch { return stats; }
 
+  // ADMISSION GATE — resume must honour the same throttle as any backlog spawn,
+  // or a stormed seat's leftover markers bypass it and re-storm on every boot
+  // (the fresh-seat backlog-storm root). Two guards:
+  //  (1) if the shared breaker is open (a usage/rate limit is holding spawns),
+  //      resume NOTHING — resuming would hammer a drained pool the moment it
+  //      re-opens. Markers stay for the next reconcile after the breaker clears.
+  //  (2) cap resumes this pass to the BACKLOG concurrency (in-memory, race-free
+  //      — unlike the governor's ps count). DAEMON_MAX_CONCURRENT=3 →
+  //      RESERVED_INBOX_SLOTS(3) → budget 0 → a reactive-only seat resumes
+  //      nothing on boot (the item stays re-deliverable / the marker persists).
+  try {
+    const rb = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
+    if (rb && rb.allowed === false) {
+      logSession({ event: "resume_reconcile_gated", reason: "breaker_open", retry_at: rb.retryAt || null, markers: files.length });
+      return stats;
+    }
+  } catch { /* fail-open — a breaker read error must not strand recovery */ }
+  const resumeBudget = Math.max(0, MAX_CONCURRENT - RESERVED_INBOX_SLOTS - activeSessions.size);
+
   for (const file of files) {
     const path = join(RESUME_PENDING_DIR, file);
     stats.scanned++;
@@ -554,6 +577,15 @@ export function reconcileResumePending(opts = {}) {
       continue;
     }
 
+    // Over the backlog budget for this pass → DEFER (leave the marker, do NOT
+    // bump attempts — a deferral is not a try). The next reconcile picks it up
+    // once slots free / the throttle lifts. This is what stops the re-storm.
+    if (stats.resumed >= resumeBudget) {
+      logSession({ event: "resume_deferred_throttle", sessionId: marker.sessionId, item_id: marker.itemId, budget: resumeBudget });
+      stats.deferred++;
+      continue;
+    }
+
     // Bump the attempt count on the marker BEFORE re-dispatch so a crash mid-
     // resume still advances toward the 3-strike cap (no infinite loop).
     marker.recoveryAttempts = attempts + 1;
@@ -573,7 +605,7 @@ export function reconcileResumePending(opts = {}) {
     }
   }
   if (stats.scanned > 0) {
-    console.log(`[dispatcher] resume reconcile: ${stats.resumed} resumed, ${stats.blocked} blocked, ${stats.expired} expired (of ${stats.scanned})`);
+    console.log(`[dispatcher] resume reconcile: ${stats.resumed} resumed, ${stats.deferred} deferred, ${stats.blocked} blocked, ${stats.expired} expired (of ${stats.scanned})`);
   }
   return stats;
 }
@@ -622,8 +654,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 +1362,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