@cohortapp/agent-sdk 2.16.0 → 2.17.0

package/scripts/daemon/prompt-builder.test.mjs

@@ -12,12 +12,38 @@ import yaml from "js-yaml";
 const ORG_AGENT_DIR = mkdtempSync(join(tmpdir(), "maestro-pb-org-"));
 mkdirSync(join(ORG_AGENT_DIR, "config"), { recursive: true });
 process.env.AGENT_DIR = ORG_AGENT_DIR;
-const { buildPrompt, buildInboxContext, _resetOrgConfigCache } = await import("./prompt-builder.mjs");
+const { buildPrompt, buildInboxContext, _resetOrgConfigCache, contextCompilerEnabled } = await import("./prompt-builder.mjs");
+const { _resetOrgCfgCache } = await import("./context-compiler.mjs");
+
+/**
+ * Run `fn` with the compiled-context path OFF.
+ *
+ * The three org-knowledge tests below assert the LEGACY `--- ORG SHARED
+ * KNOWLEDGE ---` block, which `buildPrompt` emits only on that path. The flag
+ * now defaults ON (design §3 R11), so the legacy assertions have to say which
+ * path they are about instead of relying on a default that has moved. The
+ * compiled path's own org injection is pinned separately, below.
+ */
+async function withLegacyContext(fn) {
+  const prior = process.env.DAEMON_CONTEXT_COMPILER;
+  process.env.DAEMON_CONTEXT_COMPILER = "0";
+  try {
+    return await fn();
+  } finally {
+    if (prior === undefined) delete process.env.DAEMON_CONTEXT_COMPILER;
+    else process.env.DAEMON_CONTEXT_COMPILER = prior;
+  }
+}
 
 /** Write config/org.yaml into the temp agent dir and drop the cached read. */
 function writeOrgConfig(doc) {
   writeFileSync(join(ORG_AGENT_DIR, "config/org.yaml"), doc == null ? "" : yaml.dump(doc));
   _resetOrgConfigCache();
+  // The compiled-context path caches its OWN read of config/org.yaml. Both
+  // caches have to drop, or a test that disables the integration is served the
+  // previous test's enabled config and "proves" a network call that the config
+  // on disk forbids.
+  _resetOrgCfgCache();
 }
 
 /** Stub global fetch to serve a knowledge.search frame, restore on cleanup. */
@@ -85,9 +111,9 @@ test("buildInboxContext fences thread context too", () => {
 const ITEM = { service: "slack", channel: "C123", channel_id: "C123", channel_type: "channel", sender: "Dana", content: "What is our refund policy?" };
 const CLASS = { priority: "normal", action: "respond", category: "ops", summary: "refund policy question" };
 
-test("buildPrompt injects ORG SHARED KNOWLEDGE when org.cohort is enabled", async () => {
+test("buildPrompt injects ORG SHARED KNOWLEDGE when org.cohort is enabled (legacy path)", async () => {
   writeOrgConfig({ org: { cohort: { enabled: true, base: "https://cohort.example", token: "tok" } } });
-  await withFetch(
+  await withLegacyContext(() => withFetch(
     fetchReturningFacts([
       { id: "k1", text: "Refunds are issued within 14 days of purchase." },
       { id: "k2", text: "Enterprise contracts are non-refundable after onboarding." },
@@ -103,7 +129,7 @@ test("buildPrompt injects ORG SHARED KNOWLEDGE when org.cohort is enabled", asyn
       assert.ok(prompt.includes("--- INCOMING MESSAGE ---"));
       assert.match(prompt, /Log all actions taken/);
     }
-  );
+  ));
 });
 
 test("buildPrompt does NOT inject org knowledge when the integration is disabled", async () => {
@@ -121,6 +147,50 @@ test("buildPrompt does NOT inject org knowledge when the integration is disabled
   );
 });
 
+// ---------------------------------------------------------------------------
+// DAEMON_CONTEXT_COMPILER — ONE path ships (design §3 R11)
+//
+// The code read `=== "1"` while .env.example shipped `=1`, so which of two
+// materially different context paths ran depended on whether the operator had
+// copied the example env. These pin the default and the escape hatch.
+// ---------------------------------------------------------------------------
+
+test("the compiled-context path is ON by default, matching .env.example", () => {
+  assert.equal(contextCompilerEnabled({}), true, "unset must mean on");
+  assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: "1" }), true);
+  assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: "" }), true);
+});
+
+test("the compiled-context path can still be turned off in a hurry", () => {
+  for (const v of ["0", "false", "off", "no", "OFF"]) {
+    assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: v }), false, v);
+  }
+});
+
+test("on the DEFAULT path the org's facts still reach the prompt", async () => {
+  writeOrgConfig({ org: { cohort: { enabled: true, base: "https://cohort.example", token: "tok" } } });
+  await withFetch(
+    fetchReturningFacts([{ id: "k1", text: "Refunds are issued within 14 days of purchase." }]),
+    async () => {
+      const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
+      assert.ok(prompt.includes("Refunds are issued within 14 days"), "org recall must survive the default path");
+      assert.ok(prompt.includes("--- INCOMING MESSAGE ---"));
+    }
+  );
+});
+
+test("on the DEFAULT path a disabled integration still makes no network call", async () => {
+  writeOrgConfig({ org: { cohort: { enabled: false } } });
+  let fetched = false;
+  await withFetch(
+    async () => { fetched = true; return { ok: true, status: 200, json: async () => ({ ok: true, result: { facts: [] } }), headers: { get: () => null } }; },
+    async () => {
+      await buildPrompt(ITEM, CLASS, { type: "inbox" });
+      assert.equal(fetched, false, "disabled integration must not hit the network on either path");
+    }
+  );
+});
+
 test("buildPrompt is unchanged with NO org config file at all", async () => {
   writeOrgConfig(null); // empty file → parses to {} → disabled
   const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
@@ -198,10 +268,10 @@ test("buildPrompt never asks a PRIVATE turn for the OUTCOMES block", async () =>
   }
 });
 
-test("buildPrompt caps the number of injected org facts (bounded)", async () => {
+test("buildPrompt caps the number of injected org facts (bounded, legacy path)", async () => {
   writeOrgConfig({ org: { cohort: { enabled: true, base: "https://cohort.example", token: "tok" } } });
   const many = Array.from({ length: 50 }, (_, i) => ({ id: `k${i}`, text: `fact number ${i}` }));
-  await withFetch(fetchReturningFacts(many), async () => {
+  await withLegacyContext(() => withFetch(fetchReturningFacts(many), async () => {
     const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
     const block = prompt.slice(
       prompt.indexOf("--- ORG SHARED KNOWLEDGE ---"),
@@ -209,7 +279,7 @@ test("buildPrompt caps the number of injected org facts (bounded)", async () =>
     );
     const bullets = (block.match(/^- fact number /gm) || []).length;
     assert.ok(bullets > 0 && bullets <= 6, `expected <=6 injected facts, got ${bullets}`);
-  });
+  }));
 });
 
 // ---------------------------------------------------------------------------
@@ -342,3 +412,145 @@ test("buildPrompt treats an unspecified holdingSent as delivered (back-compat)",
   });
   assert.match(prompt, /A HOLDING MESSAGE has ALREADY been sent/);
 });
+
+// ---------------------------------------------------------------------------
+// Interaction history is read per SERVICE (design §3 R12)
+//
+// `responder.mjs#logInteraction` files under `memory/interactions/<service>/…`;
+// this reader was pinned to `…/slack/…`, so a Cohort exchange was written down
+// and then never found.
+// ---------------------------------------------------------------------------
+
+test("the legacy history block finds a Cohort conversation, not just a Slack one", async () => {
+  writeOrgConfig(null);
+  const dir = join(ORG_AGENT_DIR, "memory", "interactions", "cohort", "chan-cohort-9");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "2026-04-06.jsonl"),
+    JSON.stringify({ ts: "1", from: "Dana", content: "the retainer number is wrong on page two", received_at: "2026-04-06T10:00:00Z" }) + "\n",
+  );
+
+  const item = { service: "cohort", channel: "engineering", channel_id: "chan-cohort-9", sender: "Dana", content: "and now?" };
+  const prompt = await withLegacyContext(() => buildPrompt(item, CLASS, { type: "inbox" }));
+  assert.ok(prompt.includes("the retainer number is wrong on page two"), "Cohort history must reach the prompt");
+});
+
+test("the legacy history block does not read another service's tree for the same channel id", async () => {
+  writeOrgConfig(null);
+  const dir = join(ORG_AGENT_DIR, "memory", "interactions", "whatsapp", "chan-crossed");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "2026-04-06.jsonl"),
+    JSON.stringify({ ts: "1", from: "Dana", content: "WHATSAPP ONLY SENTINEL", received_at: "2026-04-06T10:00:00Z" }) + "\n",
+  );
+
+  const item = { service: "cohort", channel: "engineering", channel_id: "chan-crossed", sender: "Dana", content: "?" };
+  const prompt = await withLegacyContext(() => buildPrompt(item, CLASS, { type: "inbox" }));
+  assert.ok(!prompt.includes("WHATSAPP ONLY SENTINEL"), "one service must not read another's history");
+});
+
+// ---------------------------------------------------------------------------
+// Resource scope: a per-person DM never reaches a shared room (design §5.5)
+//
+// `logInteraction` files each exchange under BOTH the room and
+// `dm-<sender-slug>`. Merging every candidate directory into one "history with
+// this sender" block meant that the moment this read stopped being Slack-only,
+// a sentence Dana said in a DM appeared in the prompt built for a PUBLIC
+// channel. Cohort is the service where that bites: one namespace for DMs and
+// rooms. Pinned on BOTH context paths, because both merged.
+// ---------------------------------------------------------------------------
+
+const DM_SECRET = "between us - we are letting Marco go on Friday, do not mention it yet";
+
+/** Seed a private DM log and a public-room log for the same person. */
+function seedDmAndRoom(service, channelId) {
+  const dmDir = join(ORG_AGENT_DIR, "memory", "interactions", service, "dm-dana");
+  mkdirSync(dmDir, { recursive: true });
+  writeFileSync(
+    join(dmDir, "2026-09-11.jsonl"),
+    JSON.stringify({ ts: "1", from: "Dana", content: DM_SECRET, received_at: "2026-09-11T10:00:00Z" }) + "\n",
+  );
+  const roomDir = join(ORG_AGENT_DIR, "memory", "interactions", service, channelId);
+  mkdirSync(roomDir, { recursive: true });
+  writeFileSync(
+    join(roomDir, "2026-09-11.jsonl"),
+    JSON.stringify({ ts: "2", from: "Dana", content: "PUBLIC ROOM SENTINEL", received_at: "2026-09-11T11:00:00Z" }) + "\n",
+  );
+}
+
+test("a public-channel prompt never carries the sender's DM history (legacy path)", async () => {
+  writeOrgConfig(null);
+  seedDmAndRoom("cohort", "c-capital-formation");
+  const item = {
+    service: "cohort", channel: "capital-formation", channel_id: "c-capital-formation",
+    is_dm: false, sender: "Dana", content: "what's the runway number?",
+  };
+  const prompt = await withLegacyContext(() => buildPrompt(item, CLASS, { type: "inbox" }));
+  assert.ok(!prompt.includes(DM_SECRET), "a per-person DM must never be quoted into a shared room");
+  assert.ok(prompt.includes("PUBLIC ROOM SENTINEL"), "the room's own history still reaches the prompt");
+});
+
+test("a public-channel prompt never carries the sender's DM history (compiled path)", async () => {
+  writeOrgConfig(null);
+  seedDmAndRoom("cohort", "c-capital-formation-2");
+  const item = {
+    service: "cohort", channel: "capital-formation", channel_id: "c-capital-formation-2",
+    is_dm: false, sender: "Dana", content: "what's the runway number?",
+  };
+  const prompt = await buildPrompt(item, CLASS, { type: "inbox" });
+  assert.ok(contextCompilerEnabled({}), "this test is about the compiled path, which is the default");
+  assert.ok(!prompt.includes(DM_SECRET), "a per-person DM must never be quoted into a shared room");
+  assert.ok(prompt.includes("PUBLIC ROOM SENTINEL"), "the room's own history still reaches the prompt");
+});
+
+test("the DM itself still reads its own per-person history (both paths)", async () => {
+  writeOrgConfig(null);
+  seedDmAndRoom("cohort", "c-dm-dana");
+  const item = {
+    service: "cohort", channel: "dm/dana", channel_id: "c-dm-dana",
+    is_dm: true, sender: "Dana", content: "still ok for Friday?",
+  };
+  const legacy = await withLegacyContext(() => buildPrompt(item, CLASS, { type: "inbox" }));
+  assert.ok(legacy.includes(DM_SECRET), "a private reply may see the private record");
+  const compiled = await buildPrompt(item, CLASS, { type: "inbox" });
+  assert.ok(compiled.includes(DM_SECRET), "…on the compiled path too");
+});
+
+test("an item with no privacy signal at all is treated as a ROOM", async () => {
+  writeOrgConfig(null);
+  seedDmAndRoom("cohort", "c-unknown-kind");
+  // No is_dm, no channel_type, a cuid channel id that says nothing either way.
+  const item = { service: "cohort", channel: "unknown", channel_id: "c-unknown-kind", sender: "Dana", content: "?" };
+  const legacy = await withLegacyContext(() => buildPrompt(item, CLASS, { type: "inbox" }));
+  assert.ok(!legacy.includes(DM_SECRET), "unknown is not permission");
+  const compiled = await buildPrompt(item, CLASS, { type: "inbox" });
+  assert.ok(!compiled.includes(DM_SECRET), "unknown is not permission (compiled path)");
+});
+
+// ---------------------------------------------------------------------------
+// DAEMON_CONTEXT_COMPILER — the flag that picks between two context paths
+// ---------------------------------------------------------------------------
+
+test("the context-compiler flag reads the words operators actually write", async () => {
+  const { contextCompilerSetting } = await import("./prompt-builder.mjs");
+
+  // Default ON (design §3 R11) — .env.example ships 1, the code used to ship 0.
+  assert.equal(contextCompilerEnabled({}), true);
+  assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: "" }), true);
+
+  for (const on of ["1", "true", "on", "yes", "Y", "ENABLED"]) {
+    assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: on }), true, `"${on}" means on`);
+  }
+  // The off words are wider than "0": an operator who writes `disabled` meant
+  // off, and the earlier list would have given them the opposite — on the one
+  // flag that selects between two materially different context paths.
+  for (const off of ["0", "false", "off", "no", "n", "disabled", "disable", "none", " OFF "]) {
+    assert.equal(contextCompilerEnabled({ DAEMON_CONTEXT_COMPILER: off }), false, `"${off}" means off`);
+  }
+
+  // A word we do not know still resolves ON — but it is reported as unknown, so
+  // the caller can say so rather than resolving a typo in silence.
+  const odd = contextCompilerSetting({ DAEMON_CONTEXT_COMPILER: "2" });
+  assert.deepEqual(odd, { enabled: true, recognised: false, raw: "2" });
+  assert.equal(contextCompilerSetting({ DAEMON_CONTEXT_COMPILER: "off" }).recognised, true);
+});

package/scripts/daemon/responder-history.test.mjs

@@ -22,7 +22,8 @@ import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { loadConversationHistory } from "./responder.mjs";
+import { loadConversationHistory, deriveRouterItem } from "./responder.mjs";
+import { routingKey } from "./lib/session-router.mjs";
 
 const cohortItem = {
   sender: "Dana Okafor",
@@ -183,3 +184,38 @@ test("cohort: server history wins over the local mirror", async () => {
   assert.match(text, /authoritative line/, "the server is the source of truth");
   assert.doesNotMatch(text, /outdated mirror line/, "the stale mirror must not be mixed in");
 });
+
+// ---------------------------------------------------------------------------
+// Session continuity: the responder's router adapter (design §3 R10)
+//
+// `deriveRouterItem` returned null for `cohort`, so every Cohort turn fell back
+// to a fresh pre-minted UUID and the session router — which exists, and which
+// Slack and Gmail have used all along — never saw the one surface the owner
+// actually uses.
+// ---------------------------------------------------------------------------
+
+test("deriveRouterItem keys a Cohort item on its room, so a follow-up can resume", () => {
+  const out = deriveRouterItem(cohortItem);
+  assert.deepEqual(out, {
+    source: "cohort",
+    channel: "cmql1802601iihhzpf774vwbk",
+    thread_root_id: null,
+  });
+  assert.equal(routingKey(out), "cohort:cmql1802601iihhzpf774vwbk");
+});
+
+test("deriveRouterItem narrows to the thread when there is one", () => {
+  const out = deriveRouterItem({ ...cohortItem, thread_id: "root-42" });
+  assert.equal(routingKey(out), "cohort:cmql1802601iihhzpf774vwbk:root-42");
+});
+
+test("deriveRouterItem refuses the display label as a key", () => {
+  // `task/<title>` and `doc/<name>` are labels; two rooms can share one.
+  assert.equal(deriveRouterItem({ sender: "Dana", service: "cohort", channel: "task/Ship the thing" }), null);
+});
+
+test("deriveRouterItem still keys slack, gmail and calendar exactly as before", () => {
+  assert.equal(routingKey(deriveRouterItem({ service: "slack", channel: "D099", thread_id: null })), "slack:D099");
+  assert.equal(routingKey(deriveRouterItem({ service: "gmail", thread_id: "t-1" })), "gmail:t-1");
+  assert.equal(routingKey(deriveRouterItem({ service: "calendar", event_id: "e-1" })), "calendar:e-1");
+});

package/scripts/daemon/responder.mjs

@@ -28,7 +28,13 @@ import { spawn } from "child_process";
 import { join } from "path";
 import { randomUUID } from "crypto";
 import { checkRecentlySent, registerSent } from "./session-lock.mjs";
-import { routingKey as deriveRoutingKey, createRouter } from "./lib/session-router.mjs";
+import {
+  routingKey as deriveRoutingKey,
+  createRouter,
+  routerItemFromDaemonItem,
+  claimSession,
+  releaseSession,
+} from "./lib/session-router.mjs";
 // Permission scoping (security CRITICAL / audit H1). sessionPermissionArgs()
 // preserves the historical "--dangerously-skip-permissions" by default and only
 // scopes tools when the operator opts in (MAESTRO_SCOPED_PERMISSIONS=1), so the
@@ -71,6 +77,7 @@ const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.ur
 const SONNET_MODEL = "claude-sonnet-4-6";
 // Resolve claude against the agent's PATH (not launchd's bare env).
 import { resolveClaudeBin, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+import { isPrivateConversation, interactionWriteDirNames } from "../../lib/context/history-scope.mjs";
 const CLAUDE_BIN = resolveClaudeBin();
 const CLAUDE_CLI_TIMEOUT_MS = 60_000;
 const SESSION_REGISTRY_PATH = join(AGENT_REPO_DIR, "state", "daemon", "session-router-registry.json");
@@ -101,45 +108,15 @@ function getRouter() {
 }
 
 /**
- * Translate a daemon-shaped item into the source/channel/thread_ts shape
- * that session-router's routingKey() expects.
+ * Translate a daemon-shaped item into the `{source, channel, …}` shape
+ * `session-router`'s `routingKey()` expects.
  *
- * Daemon items use {service, channel, thread_id, sender_email, ...}; the
- * router's pure key fn was specced against {source, channel, thread_ts,
- * thread_id, ...} per memo §4.2. This adapter is the seam between them.
- *
- * Returns null for items the router can't key (e.g. service we don't yet
- * support, or missing required fields). Caller falls back to a fresh
- * pre-minted UUID + EPHEMERAL semantics.
+ * The adapter itself now lives in `lib/session-router.mjs` beside the key
+ * function, because `dispatcher.mjs` needs the SAME translation: two copies
+ * would let one room be keyed two ways, which is the same thing as having no
+ * router. Exported here for the responder's own tests.
  */
-function deriveRouterItem(item) {
-  if (!item || typeof item !== "object") return null;
-
-  if (item.service === "slack") {
-    const channel = item.channel || item.channel_id;
-    if (!channel) return null;
-    return {
-      source: "slack",
-      channel,
-      thread_ts: item.thread_id || item.thread_ts || null,
-      ts: item.ts || item.timestamp || null,
-    };
-  }
-
-  if (item.service === "gmail") {
-    const tid = item.thread_id || item.threadId;
-    if (!tid) return null;
-    return { source: "gmail", thread_id: tid };
-  }
-
-  if (item.service === "calendar") {
-    const eid = item.event_id || item.eventId;
-    if (!eid) return null;
-    return { source: "calendar", event_id: eid };
-  }
-
-  return null;
-}
+export const deriveRouterItem = routerItemFromDaemonItem;
 
 // Lazy token access — dotenv loads in daemon main before these are called
 function getSlackToken() {
@@ -438,10 +415,17 @@ function logInteraction(item, responseText, o = {}) {
     ? resolveSlackChannel(item)
     : (item.channel_id || item.channel || null);
 
-  // Write to both channel-ID and sender-slug directories
-  const dirs = [];
-  if (channelId) dirs.push(join(AGENT_REPO_DIR, "memory", "interactions", service, String(channelId)));
-  dirs.push(join(AGENT_REPO_DIR, "memory", "interactions", service, `dm-${senderSlug}`));
+  // The room always; the PERSON only when the exchange was actually private.
+  // This used to write both unconditionally, which made `dm-<slug>` a mixed
+  // store of private and public-room content — inert only for as long as
+  // nothing read it per-service. It is read now, so the gate belongs at both
+  // ends (`lib/context/history-scope.mjs`, design §5.5).
+  const dirs = interactionWriteDirNames({
+    channelId,
+    senderSlug,
+    isPrivate: isPrivateConversation(item),
+  }).map((name) => join(AGENT_REPO_DIR, "memory", "interactions", service, String(name)));
+  if (dirs.length === 0) return;
 
   const incomingEntry = {
     ts: item.ts || item.timestamp || new Date().toISOString(),
@@ -738,14 +722,25 @@ ${MESSAGE_CRAFT}`;
   let sessionId = null;
   if (routerItem) {
     try {
-      key = deriveRoutingKey(routerItem);
-      const decision = router.route(key);
-      if (decision.decision === "RESUME" && decision.resumeId) {
-        sessionId = decision.resumeId;
+      const candidateKey = deriveRoutingKey(routerItem);
+      const decision = router.route(candidateKey);
+      // One CLI process per key. `claimSession` is the same lease the dispatcher
+      // takes, in the same process, so a 60-second quick reply can never be
+      // handed the session id of a long agentic run that is still going — and
+      // two quick replies from one burst cannot share a transcript either.
+      if (claimSession(candidateKey)) {
+        key = candidateKey;
+        if (decision.decision === "RESUME" && decision.resumeId) {
+          sessionId = decision.resumeId;
+        } else {
+          // EPHEMERAL or EPHEMERAL_REPLACE — pre-mint a fresh UUID. Reusing
+          // the same key on next call (with a different sessionId) is fine;
+          // touch() will overwrite the registry entry.
+          sessionId = randomUUID();
+        }
       } else {
-        // EPHEMERAL or EPHEMERAL_REPLACE — pre-mint a fresh UUID. Reusing
-        // the same key on next call (with a different sessionId) is fine;
-        // touch() will overwrite the registry entry.
+        // Already in flight: spawn cold, and stay out of the registry so the
+        // running session keeps ownership of the row.
         sessionId = randomUUID();
       }
     } catch (err) {
@@ -757,30 +752,37 @@ ${MESSAGE_CRAFT}`;
     }
   }
 
-  const cliResult = await runClaudeCLI(systemPrompt, userContent, model, {
-    sessionId,
-    router: key ? router : null,
-    routingKey: key,
-  });
+  // The claim is held across the spawn AND the registry write that follows it,
+  // and released in a `finally`: a throw anywhere in between must not leave the
+  // room's key claimed forever, which would silently disable continuity for it.
+  try {
+    const cliResult = await runClaudeCLI(systemPrompt, userContent, model, {
+      sessionId,
+      router: key ? router : null,
+      routingKey: key,
+    });
 
-  const text = (cliResult.text || "").trim();
-  if (!text) {
-    throw new Error("claude CLI returned empty result text in generateResponse");
-  }
+    const text = (cliResult.text || "").trim();
+    if (!text) {
+      throw new Error("claude CLI returned empty result text in generateResponse");
+    }
 
-  // (b3) On success, touch the registry with the CLI-resolved session_id so
-  // the next call routed to this key gets a RESUME decision. Skip touch on
-  // is_error responses or when JSON parsing failed (legacy fallback path).
-  if (key && cliResult.jsonResult && cliResult.jsonResult.is_error !== true) {
-    const claudeSessionId = cliResult.jsonResult.session_id || sessionId;
-    try {
-      await router.touch(key, { claudeSessionId, model });
-    } catch (err) {
-      console.warn(`[responder] router.touch failed for ${key}: ${err.message}`);
+    // (b3) On success, touch the registry with the CLI-resolved session_id so
+    // the next call routed to this key gets a RESUME decision. Skip touch on
+    // is_error responses or when JSON parsing failed (legacy fallback path).
+    if (key && cliResult.jsonResult && cliResult.jsonResult.is_error !== true) {
+      const claudeSessionId = cliResult.jsonResult.session_id || sessionId;
+      try {
+        await router.touch(key, { claudeSessionId, model });
+      } catch (err) {
+        console.warn(`[responder] router.touch failed for ${key}: ${err.message}`);
+      }
     }
-  }
 
-  return text;
+    return text;
+  } finally {
+    if (key) releaseSession(key);
+  }
 }
 
 // Default the generator slot to the real CLI-backed implementation. (Declared