@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/workflow/worktree.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/engine/workflow/worktree.mjs — a git worktree for one agent() call with
+ * `isolation: "worktree"`.
+ *
+ * The worktree is created on a new branch from the repository's HEAD, under the
+ * run's directory (outside the project, so it never shows up as untracked
+ * files in it). The child works there. When it ends, a worktree whose HEAD has
+ * not moved and whose status is clean is removed with its branch; anything
+ * else is kept, and the agent's result names its path and branch.
+ *
+ * Only for a working directory inside a git repository with at least one
+ * commit; otherwise the call gets an error (`usage: true`, which agent()
+ * rejects with) instead of running unisolated. A kept worktree is listed in the
+ * run's `end` record. Before creating one, `git worktree prune` forgets
+ * worktrees whose directories no longer exist.
+ *
+ * @module lib/engine/workflow/worktree
+ */
+
+import { execFile } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+
+const GIT_TIMEOUT_MS = 30_000;
+
+/**
+ * @param {string[]} args @param {string} cwd
+ * @returns {Promise<{ok:boolean, stdout:string, stderr:string}>}
+ */
+function git(args, cwd) {
+  // GIT_DIR and friends in the engine's environment (a hook's, say) would point git elsewhere.
+  const env = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "", LANG: "C", GIT_TERMINAL_PROMPT: "0" };
+  return new Promise((resolve) => {
+    execFile("git", args, { cwd, env, timeout: GIT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+      resolve({ ok: !err, stdout: String(stdout ?? "").trim(), stderr: String(stderr ?? "").trim() || (err ? err.message : "") });
+    });
+  });
+}
+
+/**
+ * @param {{cwd:string, dir:string, branch:string}} o
+ * @returns {Promise<{ok:true, path:string, branch:string, base:string, repo:string, root:string}|{ok:false, error:string, usage?:boolean}>}
+ */
+export async function createWorktree({ cwd, dir, branch }) {
+  const top = await git(["rev-parse", "--show-toplevel"], cwd);
+  if (!top.ok || top.stdout === "") return { ok: false, usage: true, error: `isolation "worktree" needs a git repository, and ${cwd} is not in one` };
+  const base = await git(["rev-parse", "HEAD"], top.stdout);
+  if (!base.ok) return { ok: false, usage: true, error: `isolation "worktree" needs a commit to start from; the repository at ${top.stdout} has none` };
+  // Forget worktrees whose directories are gone (a run directory deleted, a process
+  // that exited before removing one), so they do not stay registered in .git/worktrees.
+  await git(["worktree", "prune"], top.stdout);
+  mkdirSync(path.dirname(dir), { recursive: true });
+  const add = await git(["worktree", "add", "-b", branch, dir, base.stdout], top.stdout);
+  if (!add.ok) return { ok: false, error: `could not create a worktree: ${add.stderr}` };
+  // The child works in the same place inside the worktree as cwd is inside the repository.
+  const rel = path.relative(top.stdout, cwd);
+  return { ok: true, path: rel && !rel.startsWith("..") ? path.join(dir, rel) : dir, branch, base: base.stdout, repo: top.stdout, root: dir };
+}
+
+/**
+ * Remove the worktree when nothing changed; keep it otherwise.
+ * @param {{root:string, branch:string, base:string, repo:string}} w
+ * @returns {Promise<{removed:boolean, reason:string}>}
+ */
+export async function finishWorktree(w) {
+  const status = await git(["status", "--porcelain"], w.root);
+  const head = await git(["rev-parse", "HEAD"], w.root);
+  if (!status.ok || !head.ok) return { removed: false, reason: "its state could not be read" };
+  if (status.stdout !== "" || head.stdout !== w.base) return { removed: false, reason: status.stdout !== "" ? "it has uncommitted changes" : "it has new commits" };
+  const rm = await git(["worktree", "remove", "--force", w.root], w.repo);
+  if (!rm.ok) return { removed: false, reason: `removing it failed: ${rm.stderr}` };
+  await git(["branch", "-D", w.branch], w.repo);
+  return { removed: true, reason: "unchanged" };
+}

package/lib/execution/disposition.mjs

@@ -47,7 +47,7 @@ import { dedupeKey, threadKey } from "./journal.mjs";
  * directedness ladder. A human pointed at this agent; the agent owes an answer.
  */
 export const T0_REASONS = Object.freeze([
-  "direct", "dm", "mention", "named", "assignee", "reviewer", "owner",
+  "direct", "dm", "mention", "collective", "named", "assignee", "reviewer", "owner",
   "approver", "requester", "proposer", "participant", "invited", "attendee",
   "waiting_on",
 ]);

package/lib/execution/intake.mjs

@@ -64,6 +64,7 @@ export const INTAKE_ORIGINS = Object.freeze([
 export const SURFACE_FAMILY = Object.freeze({
   dm: "messaging",
   mention: "messaging",
+  broadcast: "messaging",
   thread_reply: "messaging",
   call: "calling",
   task_assigned: "board",
@@ -99,6 +100,7 @@ export const SURFACE_TOPIC = Object.freeze({
 export const KIND_SURFACE = Object.freeze({
   message: "dm",
   mention: "mention",
+  broadcast: "broadcast",
   thread_reply: "thread_reply",
   call: "call",
   voice_note: "dm",
@@ -129,6 +131,7 @@ export const KIND_SURFACE = Object.freeze({
 export const RECONSTRUCTED_REASON = Object.freeze({
   dm: "dm",
   mention: "mention",
+  broadcast: "collective",
   thread_reply: "thread",
   call: "invited",
   task_assigned: "assignee",
@@ -424,6 +427,13 @@ export function fromChannelEvent(item, o = {}) {
     surface = "mention";
     reason = "mention";
     why.push(`${service} channel item names me`);
+  } else if (kind === "broadcast") {
+    // The org projection already proved the four broadcast conditions (human
+    // author, my room, not threaded, collective address) before stamping the
+    // kind; a channel adapter that stamps it is making the same claim.
+    surface = "broadcast";
+    reason = "collective";
+    why.push(`${service} channel item is a human's roll-call to the whole room`);
   } else if (kind === "thread_reply" || (item.is_reply === true && s(item.thread_id))) {
     // A reply in a thread. Whether the agent is IN that thread is a fact only
     // the adapter has; without it this is a lane-tier claim at best.

package/lib/execution/surface-policy.mjs

@@ -140,6 +140,21 @@ export const ORG_SURFACE_POLICY = Object.freeze({
     maxChainDepth: 2,
     ambientDrop: false,
   }),
+  /**
+   * A human's roll-call to the whole room. Respondable, now, in public — and
+   * the chain depth is ONE: the answer is a single post about myself, and a
+   * roll-call must never become a conversation between thirteen agents.
+   */
+  broadcast: Object.freeze({
+    respondable: true,
+    replyMethod: "messaging.send",
+    latency: "now",
+    actionClasses: Object.freeze([]),
+    offlineSafe: true,
+    selfApprove: true,
+    maxChainDepth: 1,
+    ambientDrop: true,
+  }),
   /** A reply in a thread I am part of. Same room, same tightness as a mention. */
   thread_reply: Object.freeze({
     respondable: true,

package/lib/learning/curator.mjs

@@ -339,14 +339,16 @@ export function parseConsolidationEnvelope(text, validIds) {
 export async function defaultConsolidateSpawn(prompt, opts = {}) {
   try {
     const { spawnSync } = await import("node:child_process");
-    const { resolveClaudeBin, daemonClaudeArgs, augmentedPath } = await import("../claude-bin.mjs");
-    const model = opts.model || "sonnet";
-    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
-    const res = spawnSync(resolveClaudeBin(), args, {
-      input: prompt,
+    const { buildSpawn } = await import("../runtime/adapter.mjs");
+    // argv + env from the runtime adapter (lane "curator"): --print --model <m>
+    // <daemon MCP args>, prompt on stdin, PATH augmented.
+    const spec = buildSpawn({ lane: "curator", model: opts.model || "sonnet", prompt, mcp: {}, env: process.env });
+    if (!spec.ok) return "";
+    const res = spawnSync(spec.bin, spec.argv, {
+      input: spec.stdin,
       encoding: "utf8",
       timeout: opts.timeoutMs || CONSOLIDATE_TIMEOUT_MS,
-      env: { ...process.env, PATH: augmentedPath() },
+      env: spec.env,
       maxBuffer: 8 * 1024 * 1024,
     });
     if (res.status === 0 && res.stdout) return res.stdout;

package/lib/learning/reflect.mjs

@@ -28,7 +28,7 @@
 "use strict";
 
 import { spawnSync } from "node:child_process";
-import { resolveClaudeBin, daemonClaudeArgs, augmentedPath } from "../claude-bin.mjs";
+import { buildSpawn } from "../runtime/adapter.mjs";
 import { captureSession, countUserTurns } from "../collective/capture.mjs";
 import { readRecentCards } from "../collective/cards.mjs";
 import { jaccard, tokenSet } from "../collective/recall.mjs";
@@ -146,13 +146,15 @@ export function buildReviewPrompt(transcriptText, extras = {}) {
 /** Default reviewer spawn: one `claude --print --model <sonnet>`. Fail-open → "". */
 export function defaultReviewSpawn(prompt, opts = {}) {
   try {
-    const model = opts.model || "sonnet";
-    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
-    const res = spawnSync(resolveClaudeBin(), args, {
-      input: prompt,
+    // argv + env from the runtime adapter (lane "reflect"): --print --model <m>
+    // <daemon MCP args>, prompt on stdin, PATH augmented.
+    const spec = buildSpawn({ lane: "reflect", model: opts.model || "sonnet", prompt, mcp: {}, env: process.env });
+    if (!spec.ok) return "";
+    const res = spawnSync(spec.bin, spec.argv, {
+      input: spec.stdin,
       encoding: "utf8",
       timeout: opts.timeoutMs || REFLECT_TIMEOUT_MS,
-      env: { ...process.env, PATH: augmentedPath() },
+      env: spec.env,
       maxBuffer: 8 * 1024 * 1024,
     });
     if (res.status === 0 && res.stdout) return res.stdout;

package/lib/model-router/catalog/cohort.yaml

@@ -0,0 +1,137 @@
+# lib/model-router/catalog/cohort.yaml
+# Bundled cohort-llm catalog rows (ships with @cohortapp/agent-sdk).
+#
+# cohort-llm is Cohort's OWN model gateway (hq docs/cohort-llm/design.md §4).
+# The rows are Cohort model TIERS, never upstream model ids: the gateway routes
+# each tier to its legs (design §4.7) and failover never changes the tier a seat
+# is billed for (§5.1 TierRate).
+#
+# first_party: true — this provider is Cohort's own infrastructure, so:
+#   - tool_reliability A is an explicit first-party declaration (the gateway owns
+#     tier→leg selection and the parity eval, design §8.4), not a probe grade;
+#   - data_classes allows public/internal/sensitive without a config backends
+#     entry (it is not a third-party supplier; the gateway's own data-class
+#     supplier gates, design §4.7, sit behind it).
+#
+# auth: seat_token — there is no static env key. The seat exchanges its
+#   OrgApiKey for a short-lived cst_… token at POST /cohort/v1/tokens
+#   (lib/org/llm-token.mjs). There is deliberately no auth_env key.
+#
+# endpoints are the DEFAULT gateway; the loader rewrites both to
+#   org.cohort.llmBaseUrl or COHORT_LLM_BASE_URL when either is set.
+#
+# cost: null on every row. cohort-llm prices usage from its versioned price book
+#   and returns the cost (x-cohort-cost-micros / the cohort SSE frame); a local
+#   $/MTok here would be the kind of guess design C7 removes. Budget-guard reads
+#   /cohort/v1/quota for cohort-metered seats instead of pricing tokens.
+#
+# context_window follows the tier's smallest leg in the design §4.7 starting slot
+# map (R3 research, fetched 2026-09-14):
+#   cohort-agentic  GLM-5.3 (1M) → DeepSeek-V4-Pro-0813 (1M)        → 1M
+#   cohort-reason   Kimi-K3 (1M) → GLM-5.3 (1M)                      → 1M
+#   cohort-fast     gpt-oss-120b (131K) → GLM-5.3-Flash (1M)         → 131K
+#   cohort-extract  DeepSeek-V4-Flash-0731 (1M) → GLM-5.3-Flash (1M) → 1M
+# max_tokens is the gateway's default per-request ceiling (32K, design §4.1).
+# The slot map is PROVISIONAL until the parity eval (design §8.4, W4-C).
+#
+# tier_map: the Anthropic-slot aliases a claude-shaped caller passes
+#   (`--model opus`, ANTHROPIC_DEFAULT_*_MODEL) → Cohort tiers, used when a seat's
+#   routing selects this provider. fable is the premium slot (Kimi-K3 class, R3).
+
+provider: cohort
+first_party: true
+auth: seat_token
+endpoints:
+  anthropic: https://llm.cohortapp.com
+  openai: https://llm.cohortapp.com/v1
+data_residency: us
+data_classes: [public, internal, sensitive]
+tier_map:
+  fable: cohort-reason
+  opus: cohort-agentic
+  sonnet: cohort-agentic
+  haiku: cohort-fast
+models:
+  - id: cohort-agentic
+    status: available
+    replaced_by: null
+    context_window: 1000000
+    context_tokens: 950000
+    max_tokens: 32000
+    cost: { input: null, output: null, cache_read: null, cache_write: null, tiered: [] }
+    cost_provenance: { source: gateway, fetched: "2026-09-14", volatile: true }
+    compat:
+      cache_control: anthropic
+      max_tokens_field: max_tokens
+      thinking_format: anthropic
+      requires_reasoning_echo: false
+      rejects_duplicate_tool_names: false
+      omit_temperature: false
+      supports_prompt_cache_key: true
+    tool_reliability: A
+    harness: { session: true, direct: true, batch: false }
+    quality: {}
+    notes: "2026-09-14: first-party tier; main agent loop. Legs GLM-5.3 → DeepSeek-V4-Pro-0813 (design §4.7, provisional)."
+
+  - id: cohort-reason
+    status: available
+    replaced_by: null
+    context_window: 1000000
+    context_tokens: 950000
+    max_tokens: 32000
+    cost: { input: null, output: null, cache_read: null, cache_write: null, tiered: [] }
+    cost_provenance: { source: gateway, fetched: "2026-09-14", volatile: true }
+    compat:
+      cache_control: anthropic
+      max_tokens_field: max_tokens
+      thinking_format: anthropic
+      requires_reasoning_echo: false
+      rejects_duplicate_tool_names: false
+      omit_temperature: false
+      supports_prompt_cache_key: true
+    tool_reliability: A
+    harness: { session: true, direct: true, batch: false }
+    quality: {}
+    notes: "2026-09-14: first-party tier; hardest background work (TTFT). Legs Kimi-K3 → GLM-5.3 (design §4.7, provisional)."
+
+  - id: cohort-fast
+    status: available
+    replaced_by: null
+    context_window: 131072
+    context_tokens: 124000
+    max_tokens: 32000
+    cost: { input: null, output: null, cache_read: null, cache_write: null, tiered: [] }
+    cost_provenance: { source: gateway, fetched: "2026-09-14", volatile: true }
+    compat:
+      cache_control: anthropic
+      max_tokens_field: max_tokens
+      thinking_format: anthropic
+      requires_reasoning_echo: false
+      rejects_duplicate_tool_names: false
+      omit_temperature: false
+      supports_prompt_cache_key: true
+    tool_reliability: A
+    harness: { session: true, direct: true, batch: false }
+    quality: {}
+    notes: "2026-09-14: first-party tier; classifier/haiku lanes. Legs gpt-oss-120b (131K) → GLM-5.3-Flash (design §4.7, provisional)."
+
+  - id: cohort-extract
+    status: available
+    replaced_by: null
+    context_window: 1000000
+    context_tokens: 950000
+    max_tokens: 32000
+    cost: { input: null, output: null, cache_read: null, cache_write: null, tiered: [] }
+    cost_provenance: { source: gateway, fetched: "2026-09-14", volatile: true }
+    compat:
+      cache_control: anthropic
+      max_tokens_field: max_tokens
+      thinking_format: anthropic
+      requires_reasoning_echo: false
+      rejects_duplicate_tool_names: false
+      omit_temperature: false
+      supports_prompt_cache_key: true
+    tool_reliability: A
+    harness: { session: true, direct: true, batch: false }
+    quality: {}
+    notes: "2026-09-14: first-party tier; structured extraction. Legs DeepSeek-V4-Flash-0731 → GLM-5.3-Flash (design §4.7, provisional)."

package/lib/model-router/catalog.mjs

@@ -43,6 +43,9 @@ import {
 import { join, resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { resolveLlmBaseUrl, cohortEndpoints } from "../org/llm-token.mjs";
+import { loadOrgConfig } from "../org/client.mjs";
+
 // js-yaml is a hard dependency of @cohortapp/agent-sdk (package.json), but we still
 // import it defensively so the read path can degrade rather than crash if the
 // dep tree is ever broken on a machine.
@@ -87,12 +90,17 @@ const VALID_COST_KEYS = new Set([
 
 const COST_FIELDS = ["input", "output", "cache_read", "cache_write"];
 
+/** How a provider authenticates: a static env key, or a Cohort seat token. */
+const VALID_AUTH = new Set(["env", "seat_token"]);
+const DATA_CLASS_NAMES = new Set(["public", "internal", "sensitive"]);
+
 // Bundled providers we recognise. The authority-merge rule "never add providers"
 // is enforced for the overlay (tighten-only); agent config MAY introduce a new
 // provider via catalog_overrides (it is the highest authority and the agent owns
 // its own machine), but we surface a warning so a typo'd provider name is loud.
 const BUNDLED_PROVIDERS = new Set([
   "anthropic",
+  "cohort",
   "deepseek",
   "moonshot",
   "qwen",
@@ -294,6 +302,7 @@ function normaliseRow(provider, rawRow, errors) {
     tool_reliability: VALID_GRADES.has(tool_reliability) ? tool_reliability : null,
     harness: normaliseHarness(rawRow.harness, errors, label),
     quality: rawRow.quality && typeof rawRow.quality === "object" ? { ...rawRow.quality } : {},
+    notes: typeof rawRow.notes === "string" ? rawRow.notes : null,
   };
   return { ok: true, row };
 }
@@ -323,6 +332,7 @@ function parseProviderDoc(doc, label, errors) {
     errors.push({ source: label, error: "catalog document missing string `provider`" });
     return null;
   }
+  const meta = providerMeta(doc, label, errors);
   const rows = new Map();
   const models = Array.isArray(doc.models) ? doc.models : [];
   if (!Array.isArray(doc.models)) {
@@ -337,6 +347,7 @@ function parseProviderDoc(doc, label, errors) {
     row.endpoints = doc.endpoints && typeof doc.endpoints === "object" ? { ...doc.endpoints } : {};
     row.data_residency =
       typeof doc.data_residency === "string" ? doc.data_residency : null;
+    Object.assign(row, cloneMeta(meta));
     rows.set(row.id, row);
   }
   return {
@@ -344,10 +355,59 @@ function parseProviderDoc(doc, label, errors) {
     auth_env: typeof doc.auth_env === "string" ? doc.auth_env : null,
     endpoints: doc.endpoints && typeof doc.endpoints === "object" ? { ...doc.endpoints } : {},
     data_residency: typeof doc.data_residency === "string" ? doc.data_residency : null,
+    ...cloneMeta(meta),
     rows,
   };
 }
 
+/**
+ * Provider-level identity the router gates on (hoisted onto every row):
+ *   first_party   Cohort's own infrastructure (the cohort-llm gateway). A
+ *                 first-party provider declares its own grade and data-class
+ *                 allowance instead of earning them from a probe/config entry.
+ *   auth          "env" (auth_env names a static key, the default) or
+ *                 "seat_token" (a short-lived Cohort seat token, lib/org/llm-token.mjs).
+ *   data_classes  classes a FIRST-PARTY provider allows without a config entry.
+ *   tier_map      Anthropic-slot alias (fable/opus/sonnet/haiku) → this provider's row id.
+ */
+function providerMeta(doc, label, errors) {
+  const auth = doc.auth == null ? "env" : doc.auth;
+  if (!VALID_AUTH.has(auth)) errors.push({ source: label, error: `auth "${auth}" not in {env,seat_token}` });
+  const firstParty = doc.first_party === true;
+  let dataClasses = null;
+  if (doc.data_classes != null) {
+    if (!Array.isArray(doc.data_classes)) {
+      errors.push({ source: label, error: "data_classes must be an array" });
+    } else {
+      const bad = doc.data_classes.filter((c) => !DATA_CLASS_NAMES.has(c));
+      if (bad.length) errors.push({ source: label, error: `unknown data_classes ${JSON.stringify(bad)}` });
+      dataClasses = doc.data_classes.filter((c) => DATA_CLASS_NAMES.has(c));
+      if (!firstParty) errors.push({ source: label, error: "data_classes is only honoured on a first_party provider (third parties are allowed per config backends)" });
+    }
+  }
+  const tierMap = {};
+  if (doc.tier_map != null) {
+    if (typeof doc.tier_map !== "object" || Array.isArray(doc.tier_map)) {
+      errors.push({ source: label, error: "tier_map must be an object" });
+    } else {
+      for (const [k, v] of Object.entries(doc.tier_map)) {
+        if (typeof v === "string" && v) tierMap[String(k).toLowerCase()] = v;
+        else errors.push({ source: label, error: `tier_map.${k} must be a row id string` });
+      }
+    }
+  }
+  return { first_party: firstParty, auth: VALID_AUTH.has(auth) ? auth : "env", data_classes: dataClasses, tier_map: tierMap };
+}
+
+function cloneMeta(meta) {
+  return {
+    first_party: meta.first_party,
+    auth: meta.auth,
+    data_classes: meta.data_classes ? [...meta.data_classes] : null,
+    tier_map: { ...meta.tier_map },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Source gathering (each returns provider docs + records its file mtime)
 // ---------------------------------------------------------------------------
@@ -596,6 +656,8 @@ function mergePartialRow(byRef, ref, entry, layer, errors, warnings) {
       row.auth_env = entry.auth_env ?? null;
       row.endpoints = entry.endpoints ?? {};
       row.data_residency = entry.data_residency ?? null;
+      // A config-created row is never first-party: that is a bundled declaration.
+      Object.assign(row, { first_party: false, auth: "env", data_classes: null, tier_map: {} });
       byRef.set(ref, row);
     }
     return;
@@ -689,6 +751,11 @@ export function loadCatalog(agentRoot, opts = {}) {
     for (const row of parsed.rows.values()) byRef.set(row.ref, row);
   }
 
+  // The cohort gateway's base URL is seat configuration, not catalog data:
+  // org.cohort.llmBaseUrl, then COHORT_LLM_BASE_URL, then the default. Applied
+  // on the bundled floor so an explicit agent catalog_override still wins.
+  applyCohortBaseUrl(byRef, providersByName, cohortBaseUrlFor(root, opts));
+
   // Layer 3: pricing cache (COST ONLY).
   const pricing = gatherPricingCache(root, opts, errors, mtimes);
   if (pricing) {
@@ -745,6 +812,10 @@ export function loadCatalog(agentRoot, opts = {}) {
       auth_env: doc.auth_env,
       endpoints: doc.endpoints,
       data_residency: doc.data_residency,
+      first_party: doc.first_party === true,
+      auth: doc.auth || "env",
+      data_classes: doc.data_classes || null,
+      tier_map: doc.tier_map || {},
     });
   }
 
@@ -761,6 +832,49 @@ export function loadCatalog(agentRoot, opts = {}) {
   };
 }
 
+/** The cohort gateway base URL for this load (injectable, else config/env). */
+function cohortBaseUrlFor(root, opts) {
+  if (opts && typeof opts.cohortLlmBaseUrl === "string" && opts.cohortLlmBaseUrl) {
+    return opts.cohortLlmBaseUrl.replace(/\/+$/, "");
+  }
+  let cfg = opts && opts.orgConfig !== undefined ? opts.orgConfig : null;
+  if (cfg === null) {
+    try { cfg = existsSync(join(root, "config", "org.yaml")) ? loadOrgConfig(root) : {}; } catch { cfg = {}; }
+  }
+  return resolveLlmBaseUrl({ cfg, env: (opts && opts.env) || process.env });
+}
+
+/** Point the cohort provider (and its rows) at a gateway base URL. */
+function applyCohortBaseUrl(byRef, providersByName, baseUrl) {
+  const doc = providersByName.get("cohort");
+  if (!doc) return;
+  const endpoints = cohortEndpoints(baseUrl);
+  doc.endpoints = { ...doc.endpoints, ...endpoints };
+  for (const row of byRef.values()) {
+    if (row.provider === "cohort") row.endpoints = { ...row.endpoints, ...endpoints };
+  }
+}
+
+/**
+ * The Cohort tier for a claude-shaped model flag. A `cohort-*` id passes
+ * through; an Anthropic-slot alias or id (fable/opus/sonnet/haiku, e.g.
+ * "claude-sonnet-4-6") maps through the provider's tier_map; anything else is
+ * null (the caller decides — never a silent guess).
+ * @param {string} modelFlag
+ * @param {Record<string,string>} tierMap
+ * @returns {string|null}
+ */
+export function cohortTierFor(modelFlag, tierMap) {
+  const m = typeof modelFlag === "string" ? modelFlag.trim().toLowerCase() : "";
+  if (!m) return null;
+  if (m.startsWith("cohort-")) return m;
+  const map = tierMap && typeof tierMap === "object" ? tierMap : {};
+  for (const slot of ["fable", "opus", "sonnet", "haiku"]) {
+    if ((m === slot || m.includes(slot)) && map[slot]) return map[slot];
+  }
+  return null;
+}
+
 function maxMtime(mtimes) {
   let m = 0;
   for (const t of mtimes) if (t > m) m = t;
@@ -863,6 +977,7 @@ function mtimeSignature(root, opts) {
     }
   }
   for (const [tag, fn, injected] of [
+    ["org", (r) => join(r, "config", "org.yaml"), opts.orgConfig !== undefined || typeof opts.cohortLlmBaseUrl === "string"],
     ["price", pricingCachePath, opts.pricingCache !== undefined],
     ["local", localConfigPath, opts.localConfig !== undefined],
     ["agent", agentConfigPath, opts.agentConfig !== undefined],
@@ -870,6 +985,8 @@ function mtimeSignature(root, opts) {
     if (injected) parts.push(`${tag}:injected`);
     else parts.push(`${tag}:${mtimeSafe(fn(root))}`);
   }
+  // The gateway URL may come from the environment.
+  parts.push(`llm:${typeof opts.cohortLlmBaseUrl === "string" ? opts.cohortLlmBaseUrl : ((opts.env || process.env).COHORT_LLM_BASE_URL || "")}`);
   // Overlay is passed by value (already verified); fold its version in.
   if (opts.overlay) parts.push(`ovl:${opts.overlay.version || "?"}`);
   return parts.join("|");
@@ -922,4 +1039,4 @@ export const _internals = {
   mtimeSignature,
 };
 
-export default { loadCatalog, loadCatalogCached, invalidateCatalogCache, lookupModel, listModels };
+export default { loadCatalog, loadCatalogCached, invalidateCatalogCache, lookupModel, listModels, cohortTierFor };

package/lib/model-router/economics.mjs

@@ -310,6 +310,8 @@ const DEFERRABLE_PREFIXES = Object.freeze([
 // the live conversational / inbox path.
 const REALTIME_TASK_CLASSES = Object.freeze(new Set([
   "session.responder",
+  "session.answer",
+  "session.plan",
   "classify.inbox",
   "huddle",
   "voice.brief",
@@ -556,6 +558,13 @@ const HAIKU_EXPLORE = Object.freeze({
 // cheap classes where a subagent would only add overhead.
 const SPAWN_KNOBS = Object.freeze({
   "session.responder": { maxTurns: 40, effort: null, agentsJson: HAIKU_EXPLORE },
+  // The reply tiers (design §5.6 / §5.1). Until now `dispatcher.mjs` hardcoded
+  // `session.responder` for every spawn, so `effort` was ALWAYS null and
+  // `maxTurns` always 40 — complexity moved the model and the timeout and
+  // nothing else. An answer gets low effort and a short leash; a plan gets high
+  // effort, a longer one, and the cheap-subagent map it will actually use.
+  "session.answer":    { maxTurns: 6,  effort: "low",  agentsJson: null },
+  "session.plan":      { maxTurns: 60, effort: "high", agentsJson: HAIKU_EXPLORE },
   "classify.inbox":    { maxTurns: 1,  effort: null, agentsJson: null },
   lookup:              { maxTurns: 2,  effort: null, agentsJson: null },
   enrich:              { maxTurns: 3,  effort: null, agentsJson: null },