@cohortapp/agent-sdk 2.11.11 → 2.11.12

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.12",
   "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/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

@@ -680,42 +680,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 });
+  }
+  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 false;
+  return evicted;
 }
 
 /**