@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/scripts/daemon/dispatcher.mjs

@@ -30,17 +30,37 @@ let governor = resourceGovernor;
 let rateGuard = rateGuardModule;
 let budgetGuard = budgetGuardModule;
 const RATE_PROVIDER = process.env.MAESTRO_RATE_PROVIDER || "anthropic";
+// cohort-llm clients (seat token + quota). `undefined` = resolve lazily from the
+// seat's config; `null` = none. Injectable for tests.
+let cohortClients = undefined;
 
 /**
  * Test seam: swap the governance modules for fakes. Each arg is optional;
  * omitted modules keep the real implementation. Returns a restore fn.
+ * `cohort` is `{quota, token}` (lib/org/llm-token.mjs seatCohortClients shape).
  */
-export function setGovernanceForTests({ governor: g, rateGuard: r, budgetGuard: b } = {}) {
-  const prev = { governor, rateGuard, budgetGuard };
+export function setGovernanceForTests({ governor: g, rateGuard: r, budgetGuard: b, cohort: c } = {}) {
+  const prev = { governor, rateGuard, budgetGuard, cohortClients };
   if (g) governor = g;
   if (r) rateGuard = r;
   if (b) budgetGuard = b;
-  return () => { governor = prev.governor; rateGuard = prev.rateGuard; budgetGuard = prev.budgetGuard; };
+  if (c !== undefined) cohortClients = c;
+  return () => { governor = prev.governor; rateGuard = prev.rateGuard; budgetGuard = prev.budgetGuard; cohortClients = prev.cohortClients; };
+}
+
+/** The seat's cohort-llm clients, or null when it has none. Never throws. */
+function getCohortClients() {
+  if (cohortClients === undefined) {
+    try {
+      cohortClients = seatCohortClients({
+        agentRoot: AGENT_REPO_DIR,
+        log: (level, msg) => { try { console[level === "error" ? "error" : "warn"](`[dispatcher] cohort-llm: ${msg}`); } catch { /* */ } },
+      });
+    } catch {
+      cohortClients = null;
+    }
+  }
+  return cohortClients;
 }
 
 // Indirection so a test can capture the EXACT argv handed to `claude` by the
@@ -99,6 +119,10 @@ const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.ur
 // Resolve the claude binary against the agent's PATH (not launchd's bare
 // env). Without this, every daemon-spawned `claude --print` exits ENOENT.
 import { resolveClaudeBin, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+import { buildSpawn, admitSpawnCached, isCohortRouted, readSeatEngine } from "../../lib/runtime/adapter.mjs";
+import { seatEngineFields, engineRunShape, sessionBudgetUsd, seatTokenSync } from "../../lib/runtime/seat-engine.mjs";
+import { seatCohortClients } from "../../lib/org/llm-token.mjs";
+import { COHORT_LLM_BILLED_BY } from "../../lib/org/cost-sync.mjs";
 const CLAUDE_BIN = resolveClaudeBin();
 
 // Model router — opt-in. When config/model-routing.yaml is present in the
@@ -112,10 +136,11 @@ const CLAUDE_BIN = resolveClaudeBin();
 //   - v2 (schema_version: 2): resolveChain → RouteDecision. The decision carries
 //     the chosen backend, the session-retarget env, the spawn knobs, the
 //     ordered failover chain, an estimated cost, and a decision_id that joins
-//     the ledger row ↔ resume marker ↔ routing audit. We build the argv + child
-//     env from the decision via the execution layer's pure builders
-//     (buildSpawnArgs / buildChildEnv from lib/model-router/spawn.mjs) so the
-//     §7.3 child-env scrubbing + argv contract match spawnRouted exactly.
+//     the ledger row ↔ resume marker ↔ routing audit. The argv + child env are
+//     built from the decision by the runtime adapter (lib/runtime/adapter.mjs),
+//     whose retarget env goes through the same runtime env builder
+//     (lib/runtime/child-env.mjs) that spawnRouted uses, so the credential scrub
+//     matches spawnRouted exactly.
 //
 // NOTE on spawnRouted: the daemon's spawnSession() must register the child
 // process SYNCHRONOUSLY (tests + getStatus() observe active_sessions right after
@@ -135,7 +160,6 @@ import {
   modelFlagFor,
   resolveChain,
 } from "../../lib/model-router.mjs";
-import { buildSpawnArgs, buildChildEnv } from "../../lib/model-router/spawn.mjs";
 import { budgetLadder, spawnKnobsFor } from "../../lib/model-router/economics.mjs";
 // Observability spine (WS — diagnostics). The dispatcher emits `dispatched` at
 // spawn and `session_opened`/`session_closed` from the existing close hook,
@@ -151,6 +175,7 @@ import {
   releaseSession,
 } from "./lib/session-router.mjs";
 import { replyTier } from "../../lib/assurance/tier.mjs";
+import { activeEntryFor, linkBoardTask } from "../../lib/session/current-work.mjs";
 
 /**
  * The reply tier comes from `lib/assurance/tier.mjs` (design §5.1) — the ONE
@@ -364,14 +389,15 @@ export function parseUsageFromText(text) {
     }
   }
   if (!obj || typeof obj !== "object") return { ok: false, reason: "no-json-object" };
+  const cohortMeta = cohortResultMeta(obj);
   const usage = obj.usage && typeof obj.usage === "object" ? obj.usage : null;
-  if (!usage) return { ok: false, reason: "no-usage-field" };
+  if (!usage) return { ok: false, reason: "no-usage-field", ...cohortMeta };
   const inputTokens = Number(usage.input_tokens);
   const outputTokens = Number(usage.output_tokens);
   if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens)) {
-    return { ok: false, reason: "non-numeric-tokens" };
+    return { ok: false, reason: "non-numeric-tokens", ...cohortMeta };
   }
-  const out = { ok: true, inputTokens, outputTokens };
+  const out = { ok: true, inputTokens, outputTokens, ...cohortMeta };
   const cacheRead = Number(usage.cache_read_input_tokens);
   if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
   // Cache CREATION tokens bill at 1.25x input and were previously dropped on
@@ -380,14 +406,35 @@ export function parseUsageFromText(text) {
   // the CLI's total_cost_usd.
   const cacheWrite = Number(usage.cache_creation_input_tokens);
   if (Number.isFinite(cacheWrite)) out.cacheWriteTokens = cacheWrite;
-  const totalCost = Number(obj.total_cost_usd);
-  if (Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
+  // A NUMBER, not anything Number() will coerce. The Cohort Engine writes
+  // `total_cost_usd: null` when not every request reported gateway cost
+  // (lib/engine/output/json.mjs), and `Number(null)` is 0 — finite, >= 0 —
+  // which recorded such a session as $0.00 authoritative: the free-looking
+  // row this whole parser exists to never write. The stock CLI always sends a
+  // number, so the coercion was harmless until the engine port made null a
+  // value this field can carry. (engine-envelope-parity.test.mjs)
+  const totalCost = obj.total_cost_usd;
+  if (typeof totalCost === "number" && Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
   if (typeof obj.model === "string" && obj.model) {
     out.model = /opus/i.test(obj.model) ? "opus" : /haiku/i.test(obj.model) ? "haiku" : "sonnet";
   }
   return out;
 }
 
+/**
+ * What a Cohort Engine result says about the gateway that served it: the
+ * `cohort` block (lib/engine/output/json.mjs) carries the gateway request ids.
+ * PURE. Empty for a claude result.
+ * @param {object} obj the parsed run result
+ * @returns {{servedByCohort?:true, requestIds?:string[]}}
+ */
+export function cohortResultMeta(obj) {
+  const c = obj && typeof obj === "object" && obj.cohort && typeof obj.cohort === "object" ? obj.cohort : null;
+  if (!c) return {};
+  const ids = Array.isArray(c.requestIds) ? c.requestIds.filter((x) => typeof x === "string" && x) : [];
+  return { servedByCohort: true, requestIds: ids };
+}
+
 /**
  * Append a TRUTHFUL cost-ledger row for a finished dispatcher session via
  * scripts/cost/track-claude-usage.mjs (source "dispatcher"). Real token counts
@@ -403,7 +450,7 @@ export function parseUsageFromText(text) {
  *
  * Best-effort + detached; never blocks the close path.
  */
-function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId }) {
+function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId, billedBy = null }) {
   const usage = parseUsageFromText(stdout);
   try {
     const trackerPath = join(AGENT_REPO_DIR, "scripts/cost/track-claude-usage.mjs");
@@ -420,6 +467,10 @@ function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId
     // routing decision + resume marker (SPEC §4.7). The tracker captures it as a
     // generic flag; absent on the v1 / no-config paths.
     if (decisionId) trackerArgs.push("--decision-id", String(decisionId));
+    // A session cohort-llm served was metered by the gateway: mark the row so
+    // org cost-sync never reports it twice, and keep the gateway request ids.
+    if (billedBy || usage.servedByCohort) trackerArgs.push("--billed-by", String(billedBy || COHORT_LLM_BILLED_BY));
+    if (Array.isArray(usage.requestIds) && usage.requestIds.length) trackerArgs.push("--request-ids", usage.requestIds.join(","));
     if (usage.ok) {
       trackerArgs.push("--input-tokens", String(usage.inputTokens));
       trackerArgs.push("--output-tokens", String(usage.outputTokens));
@@ -705,6 +756,21 @@ export function reconcileResumePending(opts = {}) {
       continue;
     }
 
+    // cohort-llm admission: a marker whose work now routes to cohort-llm is not
+    // resumed into a refused quota. A deferral is not a try (no strike).
+    // W4-E1: the admission (with the engine it resolved and its token) rides to the spawn.
+    let admission = { ok: true };
+    {
+      const admitResume = typeof opts.admitResume === "function" ? opts.admitResume : defaultAdmitResume;
+      try { admission = admitResume({ marker }) || { ok: true }; } catch { admission = { ok: true }; }
+      if (!admission.ok) {
+        const d = admission.deferral || {};
+        logSession({ event: "resume_cohort_deferred", sessionId: marker.sessionId, item_id: marker.itemId, code: d.code || null, kind: d.kind || null, until: Number.isFinite(d.until) ? new Date(d.until).toISOString() : null, cold: admission.cold === true });
+        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;
@@ -716,7 +782,7 @@ export function reconcileResumePending(opts = {}) {
 
     const spawnResume = typeof opts.spawnResume === "function" ? opts.spawnResume : defaultSpawnResume;
     try {
-      spawnResume({ marker });
+      spawnResume({ marker, admission });
       logSession({ event: "resume_dispatched", sessionId: marker.sessionId, claudeSessionId: marker.claudeSessionId, item_id: marker.itemId, attempt: marker.recoveryAttempts });
       stats.resumed++;
     } catch (err) {
@@ -771,9 +837,12 @@ export function resumeModelFlag(marker, target) {
  *   [--print, --output-format json, <permission args>, <daemon args>,
  *    <router knobs>, --session-id <id>, --model <flag>, <prompt>]
  *
- * and the same env rule: a retarget (envForSpawn carries ANTHROPIC_BASE_URL)
- * goes through buildChildEnv's §7.3 credential scrub; the Anthropic path keeps
- * the explicit empty-key posture (keychain / OAuth-token fallthrough).
+ * and the same env rule (both built by the runtime adapter): a retarget
+ * (envForSpawn carries ANTHROPIC_BASE_URL) goes through the runtime env
+ * builder's credential scrub — foreign keys AND the seat's OAuth token — and a
+ * retarget without a third-party token is refused and resumed on the stock
+ * path instead (`refusedRetarget`); the Anthropic path keeps the explicit
+ * empty-key posture (keychain / OAuth-token fallthrough).
  * MAESTRO_SESSION_ID rides the env so delivery receipts attribute correctly.
  *
  * @param {object} o
@@ -789,31 +858,67 @@ export function buildResumeSpawn(o = {}) {
   const marker = o.marker || {};
   const target = o.target && typeof o.target === "object" ? o.target : null;
   const pathFn = typeof o.augmentedPath === "function" ? o.augmentedPath : augmentedPath;
-  const modelFlag = resumeModelFlag(marker, target);
-  const knobArgs = [];
-  if (target) {
-    if (target.maxTurns != null && Number.isFinite(Number(target.maxTurns))) knobArgs.push("--max-turns", String(target.maxTurns));
-    if (target.effort) knobArgs.push("--effort", String(target.effort));
-    if (target.agentsJson) knobArgs.push("--agents", typeof target.agentsJson === "string" ? target.agentsJson : JSON.stringify(target.agentsJson));
-  }
-  const args = [
-    "--print",
-    "--output-format", "json",
-    ...(Array.isArray(o.permissionArgs) ? o.permissionArgs : []),
-    ...(Array.isArray(o.daemonArgs) ? o.daemonArgs : []),
-    ...knobArgs,
-    "--session-id", marker.claudeSessionId,
-    "--model", modelFlag,
-    marker.prompt,
-  ];
+  // argv + env come from the runtime adapter (lib/runtime/adapter.mjs, lane
+  // "resume"): the same contract as a fresh dispatcher spawn, built in one place.
   const base = o.baseEnv && typeof o.baseEnv === "object" ? o.baseEnv : {};
-  const envForSpawn = (target && target.envForSpawn) || {};
-  const retargeting = !!envForSpawn.ANTHROPIC_BASE_URL;
-  const env = retargeting
-    ? { ...buildChildEnv({ ...base, PATH: pathFn() }, envForSpawn), PATH: pathFn() }
-    : { ...base, PATH: pathFn(), ANTHROPIC_API_KEY: "", ANTHROPIC_AUTH_TOKEN: "", ...envForSpawn };
-  if (marker.sessionId) env.MAESTRO_SESSION_ID = String(marker.sessionId);
-  return { args, env, modelFlag, retargeting };
+  const daemonArgs = Array.isArray(o.daemonArgs) ? o.daemonArgs : [];
+  const deps = {
+    augmentedPath: pathFn,
+    daemonArgs: () => daemonArgs,
+    resolveBin: typeof o.resolveBin === "function" ? o.resolveBin : () => CLAUDE_BIN,
+  };
+  // W4-E1: engine cohort continues the same --session-id through `cli.mjs run`
+  // (never --resume), on the marker's Anthropic slot mapped to a tier, with no retarget.
+  const engine = o.engine === "cohort" ? "cohort" : "claude";
+  if (engine === "cohort") {
+    const shape = engineRunShape({ target, laneModel: marker.model || "sonnet" });
+    const spec = buildSpawn({
+      lane: "resume",
+      model: shape.model,
+      prompt: marker.prompt,
+      sessionId: marker.claudeSessionId,
+      permissions: Array.isArray(o.permissionArgs) ? o.permissionArgs : [],
+      mcp: {},
+      knobs: shape.knobs,
+      env: base,
+      retarget: shape.retarget,
+      extraEnv: { MAESTRO_SESSION_ID: marker.sessionId || undefined },
+      ...seatEngineFields({ engine, agentRoot: o.agentRoot || null, token: o.cohortToken || null, baseUrl: o.cohortBaseUrl || null }),
+      ...(o.maxBudgetUsd != null ? { maxBudgetUsd: o.maxBudgetUsd } : {}),
+    }, deps);
+    if (!spec.ok) throw new Error(`buildResumeSpawn: ${spec.error.message}`);
+    return { args: spec.argv, env: spec.env, bin: spec.bin, modelFlag: shape.model, retargeting: false, refusedRetarget: null, engine };
+  }
+  const spawnInput = (t, flag) => ({
+    lane: "resume",
+    model: flag,
+    prompt: marker.prompt,
+    sessionId: marker.claudeSessionId,
+    permissions: Array.isArray(o.permissionArgs) ? o.permissionArgs : [],
+    mcp: {},
+    knobs: t,
+    env: base,
+    retarget: (t && t.envForSpawn) || {},
+    extraEnv: { MAESTRO_SESSION_ID: marker.sessionId || undefined },
+  });
+  let modelFlag = resumeModelFlag(marker, target);
+  let spec = buildSpawn(spawnInput(target, modelFlag), deps);
+  let refusedRetarget = null;
+  if (!spec.ok && /^retarget_/.test(spec.error.code)) {
+    // The retarget was refused (no third-party token): resume on the stock
+    // Anthropic path instead of handing that backend the seat's own
+    // credential. resumeModelFlag with a non-retarget target keeps F11 — a
+    // foreign pinned id is never passed to Anthropic.
+    refusedRetarget = spec.error;
+    // CF-11: the Anthropic rerun must not inherit the third-party decision's
+    // knobs (--max-turns/--effort/--agents were sized for that backend).
+    const stock = { ...target, envForSpawn: {}, modelFlag: null, maxTurns: null, effort: null, agentsJson: null };
+    modelFlag = resumeModelFlag(marker, stock);
+    spec = buildSpawn(spawnInput(stock, modelFlag), deps);
+  }
+  // A claude resume past the retarget fallback cannot fail: a failure is a defect.
+  if (!spec.ok) throw new Error(`buildResumeSpawn: ${spec.error.message}`);
+  return { args: spec.argv, env: spec.env, bin: spec.bin, modelFlag, retargeting: spec.retargeting, refusedRetarget, engine };
 }
 
 /**
@@ -832,7 +937,7 @@ export function buildResumeSpawn(o = {}) {
  * and the fresh prompt continues the work.
  *
  * Audit F11: the argv and env are built through the SAME resolveSpawnTarget /
- * buildChildEnv path as spawnSession (buildResumeSpawn), so a retargeted
+ * runtime-adapter path as spawnSession (buildResumeSpawn), so a retargeted
  * session resumes on its backend, the router's knobs ride along, and
  * `--output-format json` makes the run's usage measurable for the ledger.
  *
@@ -840,41 +945,85 @@ export function buildResumeSpawn(o = {}) {
  * Best-effort; failures are logged, the marker stays (next reconcile retries
  * up to the strike cap). On a clean close the marker is cleared here.
  */
-function defaultSpawnResume({ marker }) {
+/**
+ * The router's CURRENT decision for a resume marker. resolveSpawnTarget never
+ * throws (it degrades to the v1 path / stock CLI internally); the request is
+ * rebuilt from what the marker kept of the original classification. null when
+ * there is no router or it faulted.
+ */
+function resumeTargetFor(marker) {
   const source = marker.source || "backlog";
-  // The router's CURRENT decision for this work. resolveSpawnTarget never
-  // throws (it degrades to the v1 path / stock CLI internally); the request is
-  // rebuilt from what the marker kept of the original classification.
-  let target = null;
   try {
     const routingConfig = getRoutingConfig();
-    if (routingConfig) {
-      const classResult = { model: marker.model || "sonnet", priority: marker.priority || "normal", summary: marker.summary || null };
-      const routingRequest = requestFromClassifierResult(classResult, { source, role: "responder" });
-      target = resolveSpawnTarget(routingConfig, routingRequest, classResult, source, marker.modelFlag || marker.model || "sonnet");
-    }
+    if (!routingConfig) return null;
+    const classResult = { model: marker.model || "sonnet", priority: marker.priority || "normal", summary: marker.summary || null };
+    const routingRequest = requestFromClassifierResult(classResult, { source, role: "responder" });
+    return resolveSpawnTarget(routingConfig, routingRequest, classResult, source, marker.modelFlag || marker.model || "sonnet");
   } catch (err) {
     // A router fault must not block a resume: fall back to the marker's flag.
     console.warn(`[dispatcher] resume routing failed for ${marker.sessionId}, using marker flag: ${err.message}`);
-    target = null;
+    return null;
   }
-  const { args, env: spawnEnv, modelFlag } = buildResumeSpawn({
+}
+
+/** The cohort-llm gate for a resume; a cold cache primes itself for the next reconcile. */
+function defaultAdmitResume({ marker }) {
+  const target = resumeTargetFor(marker);
+  // W4-E1: the engine is resolved once here and rides the admission to the spawn.
+  const engine = readSeatEngine(AGENT_REPO_DIR);
+  const gate = cohortGateFor(target, engine);
+  if (!gate.ok && gate.cold) {
+    const c = getCohortClients();
+    if (c && c.quota) Promise.resolve().then(() => c.quota.canAdmit()).catch(() => null);
+  }
+  if (gate.ok && engine === "cohort") {
+    // An engine-cohort resume starts with a seat token. None cached (a cleared
+    // cache) is a short retry, exactly as a fresh dispatch parks it: a deferral,
+    // not a try, so the marker takes no strike. Mint one for the next reconcile.
+    const token = gate.token || seatTokenSync(getCohortClients()?.token);
+    if (!token) {
+      const tm = getCohortClients()?.token;
+      if (tm && typeof tm.getToken === "function") Promise.resolve().then(() => tm.getToken()).catch(() => null);
+      return { ok: false, cohort: true, engine, deferral: { kind: "retry", until: Date.now() + 30_000, code: "cohort_token_unavailable", message: "no cohort-llm seat token for the engine", refusal: null } };
+    }
+    return { ...gate, engine, token };
+  }
+  return { ...gate, engine };
+}
+
+function defaultSpawnResume({ marker, admission = null }) {
+  const target = resumeTargetFor(marker);
+  // W4-E1: the engine the admission resolved (else read now), its token, and the envelope's cap.
+  const engine = admission && (admission.engine === "cohort" || admission.engine === "claude") ? admission.engine : readSeatEngine(AGENT_REPO_DIR);
+  const engineFields = engine === "cohort"
+    ? { engine, agentRoot: AGENT_REPO_DIR, cohortToken: (admission && admission.token) || seatTokenSync(getCohortClients()?.token), cohortBaseUrl: getCohortClients()?.token?.baseUrl || null, ...(() => { const b = engineSessionBudget(); return b.maxBudgetUsd != null ? { maxBudgetUsd: b.maxBudgetUsd } : {}; })() }
+    : {};
+  const { args, env: spawnEnv, bin, modelFlag, refusedRetarget } = buildResumeSpawn({
     marker,
     target,
     baseEnv: process.env,
     permissionArgs: sessionPermissionArgs({ source: "dispatcher-resume", priority: marker.priority }),
     daemonArgs: daemonClaudeArgs(),
+    ...engineFields,
   });
+  if (refusedRetarget) {
+    logSession({ event: "resume_retarget_refused", sessionId: marker.sessionId, code: refusedRetarget.code, error: refusedRetarget.message });
+  }
+  // An engine-cohort seat is cohort-served whatever routing picked (the same test
+  // cohortGateFor applies), so its refusals key the "cohort" backend.
+  const resumeEngineCohort = engine === "cohort";
+  const resumeServedByCohort = resumeEngineCohort || (!refusedRetarget && isCohortRouted({ target }));
+  const resumeBreaker = resumeServedByCohort ? rateGuardModule.COHORT_BACKEND : RATE_PROVIDER;
   const decisionId = (target && target.decisionId) || marker.decision_id || null;
   const startedAt = Date.now();
-  const proc = _spawn(CLAUDE_BIN, args, { cwd: AGENT_REPO_DIR, env: spawnEnv, stdio: ["ignore", "pipe", "pipe"] });
+  const proc = _spawn(bin, args, { cwd: AGENT_REPO_DIR, env: spawnEnv, stdio: ["ignore", "pipe", "pipe"] });
   let stdout = "";
   let stderr = "";
   proc.stdout.on("data", (c) => { stdout += c.toString(); });
   proc.stderr.on("data", (c) => { stderr += c.toString(); });
   proc.on("close", (code) => {
     // A resumed run costs money too: parse its --output-format json usage.
-    try { recordDispatcherCost({ stdout, model: marker.model, durationMs: Date.now() - startedAt, exitCode: code, decisionId }); }
+    try { recordDispatcherCost({ stdout, model: marker.model, durationMs: Date.now() - startedAt, exitCode: code, decisionId, billedBy: resumeServedByCohort ? COHORT_LLM_BILLED_BY : null }); }
     catch { /* cost tracking is best-effort */ }
     if (code === 0) {
       // Resume succeeded — the underlying work is done; clear the marker.
@@ -883,11 +1032,18 @@ function defaultSpawnResume({ marker }) {
     } else {
       // 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 { /* */ }
+      // Structured cohort refusal FIRST; an engine-cohort lane never reads the
+      // English subscription-limit text (see the spawn path below).
+      const resumeRefusal = resumeServedByCohort ? (rateGuard.classifyCohortRefusal?.(`${stdout}\n${stderr}`) ?? null) : null;
+      const resumeUlText = resumeRefusal ? { isLimit: false, resetAt: null } : (rateGuard.classifyUsageLimit?.(stderr, { agentRoot: AGENT_REPO_DIR }) ?? { isLimit: false, resetAt: null });
+      const ul = resumeEngineCohort ? { isLimit: false, resetAt: null } : resumeUlText;
+      if (resumeEngineCohort && resumeUlText.isLimit) logSession({ event: "usage_limit_text_ignored", sessionId: marker.sessionId, engine: "cohort" });
+      if (resumeRefusal) {
+        try { rateGuard.recordCohortRefusal?.(resumeRefusal, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+      } else if (ul.isLimit) {
+        try { rateGuard.recordUsageLimit(resumeBreaker, ul.resetAt, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
       } else if (rateGuard.classifyStderr(stderr)) {
-        try { rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+        try { rateGuard.recordRateLimit(resumeBreaker, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
       }
       logSession({ event: "resume_exit_nonzero", sessionId: marker.sessionId, item_id: marker.itemId, exit_code: code });
     }
@@ -897,18 +1053,29 @@ function defaultSpawnResume({ marker }) {
   });
 }
 
+/**
+ * The entry shape is `lib/session/current-work.activeEntryFor` — the SAME
+ * module that reads active.json back into the "what am I doing right now"
+ * block, so the writer and the reader cannot drift. It carries the Cohort ask
+ * identity (channelId + messageId) so the board row hq opens for an inbox ask
+ * can be linked to this session ({@link linkActiveSessionBoard}), and the
+ * board item id when a backlog row is for one.
+ */
 function writeActiveSession(sessionId, entry) {
   try {
     let active = {};
     try { active = JSON.parse(readFileSync(ACTIVE_PATH, "utf-8")); } catch {}
-    active[sessionId] = {
-      sender: entry.item?.sender || null,
-      channel: entry.item?.channel || entry.item?.channel_id || null,
-      summary: entry.classResult?.summary || "unknown",
-      model: entry.classResult?.model || "sonnet",
-      startTime: Date.now(),
-      source: entry.source,
-    };
+    active[sessionId] = activeEntryFor({ item: entry.item, classResult: entry.classResult, source: entry.source, now: Date.now() });
+    // A board row that resolved BEFORE the spawn (the daemon's `working` track
+    // is fire-and-forget and can win the race) is applied now, not lost.
+    const ask = active[sessionId].ask;
+    if (ask) {
+      const pending = pendingBoardLinks.get(`${ask.channelId}:${ask.messageId}`);
+      if (pending) {
+        active[sessionId] = { ...active[sessionId], boardTaskId: pending.taskId, boardCol: pending.col || null };
+        pendingBoardLinks.delete(`${ask.channelId}:${ask.messageId}`);
+      }
+    }
     const tmpPath = ACTIVE_PATH + ".tmp";
     writeFileSync(tmpPath, JSON.stringify(active, null, 2));
     renameSync(tmpPath, ACTIVE_PATH);
@@ -917,6 +1084,45 @@ function writeActiveSession(sessionId, entry) {
   }
 }
 
+/** Board rows that resolved for an ask whose session is not in active.json yet. Bounded. */
+const pendingBoardLinks = new Map();
+const PENDING_BOARD_LINKS_MAX = 64;
+
+/**
+ * Attach the board row hq opened for an ask to the live session working it,
+ * so the current-work block can cite the item id. Called by the daemon when
+ * its `working` board.track resolves with a taskId (agent-daemon.mjs).
+ *
+ * PURE core (`linkBoardTask`) + one atomic rewrite of active.json. Fail-open:
+ * a board link must never break a dispatch. When no live session carries the
+ * ask yet (the track won the race against the spawn), the link is parked and
+ * applied by the next writeActiveSession for that ask.
+ *
+ * @param {{channelId:string, messageId:string}} ask
+ * @param {{taskId:string, col?:string|null}} row
+ * @returns {{linked:boolean, sessionId:string|null, parked:boolean}}
+ */
+export function linkActiveSessionBoard(ask, row) {
+  try {
+    if (!ask || !ask.channelId || !ask.messageId || !row || !row.taskId) return { linked: false, sessionId: null, parked: false };
+    let active = {};
+    try { active = JSON.parse(readFileSync(ACTIVE_PATH, "utf-8")); } catch {}
+    const r = linkBoardTask(active, ask, row);
+    if (!r.sessionId) {
+      if (pendingBoardLinks.size >= PENDING_BOARD_LINKS_MAX) pendingBoardLinks.delete(pendingBoardLinks.keys().next().value);
+      pendingBoardLinks.set(`${ask.channelId}:${ask.messageId}`, { taskId: String(row.taskId), col: row.col || null });
+      return { linked: false, sessionId: null, parked: true };
+    }
+    const tmpPath = ACTIVE_PATH + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(r.active, null, 2));
+    renameSync(tmpPath, ACTIVE_PATH);
+    return { linked: true, sessionId: r.sessionId, parked: false };
+  } catch (err) {
+    console.warn(`[dispatcher] Failed to link board row to session: ${err.message}`);
+    return { linked: false, sessionId: null, parked: false };
+  }
+}
+
 function removeActiveSession(sessionId) {
   try {
     let active = {};
@@ -1084,6 +1290,13 @@ export function canDispatchBacklog(item) {
  *   fires onClose once it is later drained and spawned). It does NOT fire on the
  *   pre-spawn drop paths (backlog dedup / claim-denied / governor-DEFER backlog),
  *   which leave the durable on-disk item untouched for the next sweep anyway.
+ * @param {(o:{sessionId:string, item:object})=>void} [opts.onSpawn]
+ *   Invoked EXACTLY ONCE, when a child process has actually been started for
+ *   this entry, with the session id the dispatcher minted. This is the ONLY
+ *   truthful "started" signal: `dispatch()` returns silently on every not-now
+ *   path (rate-limited, governor QUEUE/DEFER, backlog cap, claim denied, the
+ *   cohort pre-spawn gate), and a caller that announced "started" at the call
+ *   site announced it for those too. Survives queueing like onClose.
  */
 export function dispatch(prompt, item, classResult, source = "inbox", opts = {}) {
   // `obligationKey` names the debt this session was spawned to discharge. It is
@@ -1096,6 +1309,8 @@ export function dispatch(prompt, item, classResult, source = "inbox", opts = {})
     prompt, item, classResult, source,
     obligationKey: opts.obligationKey || null,
     onClose: typeof opts.onClose === "function" ? opts.onClose : null,
+    onSpawn: typeof opts.onSpawn === "function" ? opts.onSpawn : null,
+    cohortPrimed: opts.cohortPrimed === true,
   };
   const priority = classResult.priority;
   const isPriorityInbox = source === "inbox" && (priority === "critical" || priority === "high");
@@ -1386,13 +1601,6 @@ function spawnSession(entry) {
     ? (source === "backlog" ? OPUS_BACKLOG_TIMEOUT : OPUS_INBOX_TIMEOUT)
     : (source === "backlog" ? SONNET_BACKLOG_TIMEOUT : SONNET_INBOX_TIMEOUT);
 
-  // Track backlog items to prevent retry storms
-  if (source === "backlog") {
-    const key = backlogKey(item);
-    activeBacklogKeys.add(key);
-    backlogRetryCount.set(key, (backlogRetryCount.get(key) || 0) + 1);
-  }
-
   // Resolve the spawn target via the model router. v2 configs go through
   // resolveChain (full RouteDecision: model + retarget env + spawn knobs +
   // decision_id + estimated cost + failover chain); v1 configs keep the legacy
@@ -1401,7 +1609,44 @@ function spawnSession(entry) {
   const routingConfig = getRoutingConfig();
   const routingRequest = requestFromClassifierResult(classResult, { source, role: "responder" });
   const target = resolveSpawnTarget(routingConfig, routingRequest, classResult, source, model, item);
-  const effectiveModelFlag = target.modelFlag || model;
+  let effectiveModelFlag = target.modelFlag || model;
+
+  // cohort-llm pre-spawn gate (design C6 / §8.3). Stock Claude Code retries a
+  // 429 ten times and ignores the gateway's quota headers, so a session that
+  // cohort-llm would refuse must not start. Decided BEFORE any counter, claim
+  // or lock below moves, so a deferral leaves no trace but the requeue. Human
+  // replies are not exempt: a refused seat would 429 them just the same.
+  //
+  // W4-E1 (CF-44): the seat's engine is resolved ONCE for this spawn and used by
+  // the gate, the spawn and the breaker alike. Read per spawn, so flipping
+  // runtime.engine back to "claude" restores claude on the next spawn.
+  const seatEngine = readSeatEngine(AGENT_REPO_DIR);
+  const engineCohortSpawn = seatEngine === "cohort";
+  let engineToken = null;
+  {
+    const gate = cohortGateFor(target, seatEngine);
+    if (!gate.ok) {
+      deferSpawnForCohort(entry, gate, target);
+      return false;
+    }
+    if (engineCohortSpawn) {
+      // The engine starts with the seat token the admission read. None (a
+      // cleared cache) is a short retry, parked like any cohort deferral —
+      // never a claude spawn on the seat's Anthropic credential.
+      engineToken = gate.token || seatTokenSync(getCohortClients()?.token);
+      if (!engineToken) {
+        deferSpawnForCohort(entry, { ok: false, cohort: true, deferral: { kind: "retry", until: Date.now() + 30_000, code: "cohort_token_unavailable", message: "no cohort-llm seat token for the engine", refusal: null } }, target);
+        return false;
+      }
+    }
+  }
+
+  // Track backlog items to prevent retry storms
+  if (source === "backlog") {
+    const key = backlogKey(item);
+    activeBacklogKeys.add(key);
+    backlogRetryCount.set(key, (backlogRetryCount.get(key) || 0) + 1);
+  }
 
   // Session continuity. A fresh `randomUUID()` per dispatch meant every full
   // session in a live thread started COLD — the agent re-read the room, re-did
@@ -1452,72 +1697,71 @@ function spawnSession(entry) {
   }
   const claudeSessionId = resumedSessionId || randomUUID();
 
-  // The v2 router supplies spawn knobs (SPEC §4.4 / §6.5): --max-turns bounds
-  // the session, --effort tunes reasoning where supported, --agents attaches the
-  // cheap-subagent (Haiku-Explore) fan-out map — the sanctioned intra-session
-  // cost lever that keeps the main loop's cache intact. v1 / no-config spawns
-  // carry none of these (knobs are null), so this is purely additive.
-  const knobArgs = [];
-  if (target.maxTurns != null && Number.isFinite(Number(target.maxTurns))) {
-    knobArgs.push("--max-turns", String(target.maxTurns));
-  }
-  if (target.effort) knobArgs.push("--effort", String(target.effort));
-  if (target.agentsJson) {
-    knobArgs.push("--agents", typeof target.agentsJson === "string" ? target.agentsJson : JSON.stringify(target.agentsJson));
-  }
-
-  const args = [
-    "--print",
-    // --output-format json so this run's stdout carries the REAL token usage we
-    // record to the cost ledger (recovery C1). The dispatcher's stdout is only
-    // tee'd to a per-session log file — it's never streamed to the user (the
-    // session sends its own user-facing messages via the Slack/Gmail APIs), so
-    // switching the format does not affect any reply.
-    "--output-format", "json",
-    ...sessionPermissionArgs({ source: "dispatcher", priority: classResult?.priority }),
-    ...daemonClaudeArgs(),
-    ...knobArgs,
-    "--session-id", claudeSessionId,
-    "--model", effectiveModelFlag,
+  // argv + env come from the runtime adapter (lib/runtime/adapter.mjs, lane
+  // "dispatcher"). What it builds, unchanged from the inline version:
+  //   argv  --print --output-format json <permissions> <daemon MCP args>
+  //         <router knobs> --session-id <id> --model <flag> <prompt>
+  //         --output-format json so stdout carries the REAL token usage for the
+  //         cost ledger (recovery C1); the dispatcher's stdout only goes to a
+  //         per-session log, never to a user. The v2 knobs (--max-turns,
+  //         --effort, --agents Haiku-Explore) are null on v1 / no-config spawns.
+  //   env   no router / an Anthropic decision: stock posture — strip
+  //         ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN so `claude` rides the seat's
+  //         subscription credential (CEO directive 2026-04-27).
+  //         A v2 retarget (envForSpawn carries ANTHROPIC_BASE_URL): the one
+  //         runtime env builder scrubs every foreign credential AND the seat's
+  //         OAuth token, and forces ANTHROPIC_API_KEY="" and
+  //         CLAUDE_CODE_ATTRIBUTION_HEADER=0.
+  // MAESTRO_SESSION_ID / MAESTRO_OBLIGATION_KEY are set after every merge so a
+  // router target can never drop the delivery-receipt attribution; they are
+  // plain identifiers, never credentials.
+  // W4-E1: an engine-cohort seat runs `cli.mjs run` — its tier from the router
+  // only when the router chose cohort, no retarget, and a per-session spend cap
+  // from the seat's funded envelope. A claude seat's input is exactly as before.
+  const engineShape = engineCohortSpawn ? engineRunShape({ target, laneModel: model }) : null;
+  const spawnInput = {
+    lane: "dispatcher",
+    bin: CLAUDE_BIN,
+    model: engineShape ? engineShape.model : effectiveModelFlag,
     prompt,
-  ];
-
-  // Build the spawn env.
-  //   Default (no router): strip ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN so
-  //   `claude` falls through to the keychain OAuth (Max subscription) per
-  //   CEO directive 2026-04-27.
-  //   Router active: merge the resolved target's envForSpawn — this points the
-  //   CLI at the chosen backend (Moonshot, OpenRouter, NIM, etc.) and sets
-  //   ANTHROPIC_API_KEY="" explicitly so Claude Code doesn't fall back to
-  //   OAuth against api.anthropic.com.
-  //
-  // For a v2 retarget (envForSpawn carries ANTHROPIC_BASE_URL), we build the
-  // child env through the execution layer's buildChildEnv so the §7.3 allowlist
-  // scrub applies (no foreign *_API_KEY / *_AUTH_TOKEN leaks into a third-party
-  // session). buildChildEnv already injects ANTHROPIC_API_KEY="" for a retarget.
-  // For the common Anthropic-session case (envForSpawn === {}) and the v1 path
-  // we keep the prior explicit empty-key env verbatim (byte-compatible).
-  const retargeting = !!(target.envForSpawn && target.envForSpawn.ANTHROPIC_BASE_URL);
-  const spawnEnv = retargeting
-    ? { ...buildChildEnv({ ...process.env, PATH: augmentedPath() }, target.envForSpawn), PATH: augmentedPath() }
-    : {
-        ...process.env,
-        PATH: augmentedPath(),
-        ANTHROPIC_API_KEY: "",
-        ANTHROPIC_AUTH_TOKEN: "",
-        ...(target.envForSpawn || {}),
-      };
-  // ATTRIBUTION for delivery receipts. Set after the merges above so a router
-  // target's envForSpawn can never drop it — a retargeted session replies
-  // through exactly the same CLI lanes and owes exactly the same receipt.
-  // These are plain identifiers, never credentials, so the §7.3 allowlist scrub
-  // in buildChildEnv has nothing to object to.
-  spawnEnv.MAESTRO_SESSION_ID = sessionId;
-  if (entry.obligationKey) spawnEnv.MAESTRO_OBLIGATION_KEY = String(entry.obligationKey);
-
-  const proc = _spawn(CLAUDE_BIN, args, {
+    sessionId: claudeSessionId,
+    permissions: sessionPermissionArgs({ source: "dispatcher", priority: classResult?.priority }),
+    mcp: {},
+    knobs: engineShape ? engineShape.knobs : target,
+    env: process.env,
+    retarget: engineShape ? engineShape.retarget : (target.envForSpawn || {}),
+    extraEnv: { MAESTRO_SESSION_ID: sessionId, MAESTRO_OBLIGATION_KEY: entry.obligationKey || undefined },
+    ...seatEngineFields({ engine: seatEngine, agentRoot: AGENT_REPO_DIR, token: engineToken, baseUrl: engineCohortSpawn ? getCohortClients()?.token?.baseUrl : null }),
+    ...(engineCohortSpawn ? engineSessionBudget() : {}),
+  };
+  let spawnSpec = buildSpawn(spawnInput);
+  let refusedRetarget = null;
+  if (!spawnSpec.ok && /^retarget_/.test(spawnSpec.error.code)) {
+    // Refused retarget (no third-party token). Answer on the stock Anthropic
+    // path with the classifier's Anthropic model rather than send that backend
+    // the seat's own credential — or drop the item.
+    console.warn(`[dispatcher] ${spawnSpec.error.message} — spawning ${sessionId} on the stock path`);
+    logSession({ event: "retarget_refused", sessionId, code: spawnSpec.error.code, decision_id: target.decisionId || null });
+    refusedRetarget = spawnSpec.error;
+    effectiveModelFlag = model;
+    // CF-11: the rerun is an ANTHROPIC session. The third-party decision's
+    // --max-turns/--effort/--agents were sized for that backend and must not
+    // ride along.
+    spawnSpec = buildSpawn({ ...spawnInput, model, knobs: null, retarget: {} });
+  }
+  // A seat on engine cohort is cohort-served whatever routing picked — the same
+  // test cohortGateFor admits it by — so its breaker is the "cohort" backend.
+  const engineCohort = engineCohortSpawn;
+  const servedByCohort = engineCohort || (!refusedRetarget && isCohortRouted({ target }));
+  const breakerProvider = servedByCohort ? rateGuardModule.COHORT_BACKEND : RATE_PROVIDER;
+  // Both engines are wired and the engine's token was checked before any claim,
+  // so a failure past the retarget fallback is a defect.
+  if (!spawnSpec.ok) throw new Error(`[dispatcher] runtime adapter: ${spawnSpec.error.message}`);
+  const args = spawnSpec.argv;
+
+  const proc = _spawn(spawnSpec.bin, args, {
     cwd: AGENT_REPO_DIR,
-    env: spawnEnv,
+    env: spawnSpec.env,
     stdio: ["ignore", "pipe", "pipe"],
   });
 
@@ -1525,14 +1769,20 @@ function spawnSession(entry) {
   // and it isn't the stock Anthropic CLI no-op. The v2 path also carries the
   // decision_id + the one-line explain so `maestro router why` can join this
   // session to its routing-audit + ledger rows.
+  //
+  // CF-11: the event describes the run that ACTUALLY happened. After a refused
+  // retarget that is the stock Anthropic session with the classifier's model
+  // and no router knobs; the intended backend rides along as `refused`.
   if (target.backend && target.transport !== "anthropic-cli") {
     logSession({
       event: "routed",
       sessionId,
       decision_id: target.decisionId,
-      backend: target.backend,
-      transport: target.transport,
-      model: target.model,
+      backend: refusedRetarget ? "anthropic" : target.backend,
+      transport: refusedRetarget ? "anthropic-cli" : target.transport,
+      model: refusedRetarget ? model : target.model,
+      knobs: refusedRetarget ? null : { maxTurns: target.maxTurns ?? null, effort: target.effort ?? null, agents: target.agentsJson ? true : false },
+      ...(refusedRetarget ? { refused: { backend: target.backend, model: target.model, code: refusedRetarget.code } } : {}),
       tried: target.decision ? target.decision.tried : target._v1Resolved?.tried,
       fallback_reason: target.decision ? target.decision.audit?.fallback_reason : target._v1Resolved?.fallback_reason,
       explain: target.explain,
@@ -1562,6 +1812,11 @@ function spawnSession(entry) {
   const startTime = Date.now();
   activeSessions.set(sessionId, { process: proc, item, classResult, startTime, model, source, claudeSessionId });
   writeActiveSession(sessionId, entry);
+  // A child exists from this line on — the one moment "started" is true.
+  if (entry.onSpawn) {
+    try { entry.onSpawn({ sessionId, item }); }
+    catch (err) { console.warn(`[dispatcher] onSpawn callback threw for ${sessionId}: ${err.message}`); }
+  }
 
   // WS4: drop the in-flight resume marker. Present-after-crash = mid-flight, so
   // a startup reconcile can re-dispatch `claude --print --resume`. Cleared on a
@@ -1667,7 +1922,7 @@ function spawnSession(entry) {
     // bound re-dispatch.
     if (code === 0) {
       clearResumePending(sessionId);
-      try { rateGuard.recordSuccess(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+      try { rateGuard.recordSuccess(breakerProvider, { agentRoot: AGENT_REPO_DIR }); } 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
@@ -1675,15 +1930,32 @@ function spawnSession(entry) {
       // 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) {
+      // A cohort-llm refusal is checked FIRST on a cohort-served run: its body
+      // says "rate_limit_error", and the English path would otherwise read a
+      // spent seat window as an Anthropic incident. It holds the "cohort"
+      // backend until the refusal's resetsAt and never opens a provider breaker.
+      const cohortRefusal = servedByCohort ? (rateGuard.classifyCohortRefusal?.(combined) ?? null) : null;
+      // An engine-cohort lane has no Claude subscription: its limits arrive as the
+      // structured refusal above. Its English text ("Session limit reached") is
+      // never read as a subscription usage limit — without a structured refusal
+      // it is logged and left to the transient-429 check (cohort backend).
+      const ulText = cohortRefusal ? { isLimit: false, resetAt: null } : (rateGuard.classifyUsageLimit?.(combined, { agentRoot: AGENT_REPO_DIR }) ?? { isLimit: false, resetAt: null });
+      const ul = engineCohort ? { isLimit: false, resetAt: null } : ulText;
+      if (engineCohort && ulText.isLimit) logSession({ event: "usage_limit_text_ignored", sessionId, engine: "cohort" });
+      if (cohortRefusal) {
         try {
-          const rec = rateGuard.recordUsageLimit(RATE_PROVIDER, ul.resetAt, { agentRoot: AGENT_REPO_DIR });
+          const rec = rateGuard.recordCohortRefusal(cohortRefusal, { agentRoot: AGENT_REPO_DIR });
+          logSession({ event: "cohort_refusal_recorded", sessionId, code: cohortRefusal.code, disposition: rec.disposition && rec.disposition.kind, open_until: rec.openUntil });
+        } catch { /* */ }
+        try { const c = getCohortClients(); if (c && c.quota && typeof c.quota.invalidate === "function") c.quota.invalidate(); } catch { /* */ }
+      } else if (ul.isLimit) {
+        try {
+          const rec = rateGuard.recordUsageLimit(breakerProvider, 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 });
+          const rec = rateGuard.recordRateLimit(breakerProvider, { agentRoot: AGENT_REPO_DIR });
           logSession({ event: "rate_limit_recorded", sessionId, open_until: rec.openUntil, consecutive: rec.consecutive429 });
         } catch { /* */ }
       }
@@ -1777,6 +2049,7 @@ function spawnSession(entry) {
       durationMs: Date.now() - startTime,
       exitCode: code,
       decisionId: target.decisionId,
+      billedBy: servedByCohort ? COHORT_LLM_BILLED_BY : null,
     });
     if (!costUsage.ok) {
       logSession({ event: "cost_usage_parse_failed", sessionId, reason: costUsage.reason });
@@ -1961,10 +2234,181 @@ function drainQueue() {
     // Commit: remove from whichever queue it sat at the head of, then spawn.
     if (priorityQueue[0] === next) priorityQueue.shift();
     else normalQueue.shift();
+    // A cohort-llm deferral parks the entry OFF the queue (cohortParked) and
+    // returns false; keep draining — the entries behind it may route elsewhere.
     spawnSession(next);
   }
 }
 
+// ── cohort-llm pre-spawn gate ────────────────────────────────────────────────
+
+/**
+ * The gate for one spawn target. Synchronous (spawnSession must register its
+ * child synchronously), so it reads the quota CACHE; a cold cache answers
+ * `{cold:true}` and the caller primes it.
+ */
+function cohortGateFor(target, engine = readSeatEngine(AGENT_REPO_DIR)) {
+  // A seat on engine cohort is cohort-metered whatever the router picked: the
+  // engine talks to cohort-llm directly, so its spawns are gated even when no
+  // model routing targets the cohort provider. The caller passes the engine it
+  // resolved for this spawn (W4-E1), so the gate and the spawn cannot disagree.
+  if (!isCohortRouted({ engine, target })) return { ok: true, cohort: false };
+  const clients = getCohortClients();
+  if (!clients || !clients.quota) {
+    return {
+      ok: false,
+      cohort: true,
+      deferral: { kind: "retry", until: Date.now() + 30_000, code: "cohort_quota_unconfigured", message: "this seat has no cohort-llm client (no OrgApiKey?)", refusal: null },
+    };
+  }
+  return admitSpawnCached({ engine, target }, { quota: clients.quota, token: clients.token, rateGuard, rateGuardDeps: { agentRoot: AGENT_REPO_DIR } });
+}
+
+/**
+ * W4-E1 (design §8.3, A2 "no per-session dollar cap"): an engine-cohort
+ * session's `--max-budget-usd`, from the seat's funded envelope — one day's
+ * binding allowance (lib/runtime/seat-engine.mjs sessionBudgetUsd). No funded
+ * envelope, or a budget guard that cannot say: no cap is invented.
+ * @returns {{maxBudgetUsd:number}|{}}
+ */
+function engineSessionBudget() {
+  try {
+    const allowance = typeof budgetGuard.dailyAllowance === "function" ? budgetGuard.dailyAllowance({ agentRoot: AGENT_REPO_DIR }) : null;
+    const usd = sessionBudgetUsd(allowance);
+    return usd == null ? {} : { maxBudgetUsd: usd };
+  } catch {
+    return {}; // the guard's own bands still govern the seat
+  }
+}
+
+/**
+ * Hand a deferred spawn back without losing it:
+ *   inbox    PARKED off the queue (cohortParked — never dropped) until the
+ *            deferral lifts or the cold cache is primed, then put back at the
+ *            head of its queue. Parking, not requeueing at the head: a seat
+ *            that routes only SOME work to cohort must keep draining the
+ *            entries behind a refused one (they may route to Anthropic), and a
+ *            7d/30d window or a credits hold must not stall the whole inbox.
+ *   backlog  the item claim is released and the item cools until the deferral
+ *            lifts (the on-disk item is retried by the sweep).
+ * A cold cache is primed and the work retried once the reading lands. The
+ * deferral is logged once per hold, not on every re-gate.
+ */
+function deferSpawnForCohort(entry, gate, target) {
+  const { item, classResult, source } = entry;
+  const d = gate.deferral || {};
+  const until = Number.isFinite(d.until) ? d.until : Date.now() + 30_000;
+  const holdKey = `${gate.cold === true ? "cold" : `${d.code || ""}|${d.kind || ""}|${until}`}`;
+  if (entry.cohortHoldKey !== holdKey) {
+    entry.cohortHoldKey = holdKey;
+    logSession({
+      event: "cohort_deferred",
+      source,
+      code: d.code || null,
+      kind: d.kind || null,
+      until: new Date(until).toISOString(),
+      cold: gate.cold === true,
+      decision_id: (target && target.decisionId) || null,
+      summary: classResult && classResult.summary,
+    });
+  }
+  if (source === "backlog") {
+    if (item && item.id) { try { releaseItemClaim(item.id); } catch { /* */ } }
+    if (!gate.cold) {
+      backlogCooldownUntil.set(backlogKey(item), until);
+      try { saveCooldowns(); } catch { /* */ }
+    }
+  } else {
+    parkForCohort(entry, gate.cold ? null : until);
+  }
+  if (gate.cold) primeCohortQuota(entry);
+}
+
+// ── cohort-parked inbox entries ──────────────────────────────────────────────
+// {entry, until} — `until` null means "waiting on a cold-cache prime".
+const cohortParked = [];
+let cohortParkTimer = null;
+/** Parked entries re-check at least this often (and setTimeout cannot hold a 30d delay). */
+const COHORT_PARK_RECHECK_MAX_MS = 10 * 60_000;
+const COHORT_PARK_RECHECK_MIN_MS = 1_000;
+let cohortInboxPrimeInFlight = false;
+
+function parkForCohort(entry, until) {
+  cohortParked.push({ entry, until });
+  armCohortRelease();
+}
+
+function armCohortRelease() {
+  if (cohortParkTimer) { clearTimeout(cohortParkTimer); cohortParkTimer = null; }
+  const timed = cohortParked.filter((p) => p.until !== null);
+  if (timed.length === 0) return;
+  const earliest = Math.min(...timed.map((p) => p.until));
+  const delay = Math.max(COHORT_PARK_RECHECK_MIN_MS, Math.min(COHORT_PARK_RECHECK_MAX_MS, earliest - Date.now()));
+  cohortParkTimer = setTimeout(() => {
+    cohortParkTimer = null;
+    try { releaseCohortParked(); } catch (err) { console.warn(`[dispatcher] cohort-llm release failed: ${err.message}`); }
+  }, delay);
+  if (cohortParkTimer && typeof cohortParkTimer.unref === "function") cohortParkTimer.unref();
+}
+
+/**
+ * Put parked entries back at the head of their queues (original order) and
+ * drain: `cold:true` releases the entries waiting on a prime; otherwise the
+ * ones whose deferral has lifted. They are gated again on the way out.
+ */
+function releaseCohortParked({ cold = false } = {}) {
+  const now = Date.now();
+  const back = [];
+  const keep = [];
+  for (const p of cohortParked) {
+    const due = cold ? p.until === null : p.until !== null && p.until <= now;
+    (due ? back : keep).push(p);
+  }
+  cohortParked.length = 0;
+  cohortParked.push(...keep);
+  for (let i = back.length - 1; i >= 0; i--) {
+    const e = back[i].entry;
+    const high = e.classResult && (e.classResult.priority === "critical" || e.classResult.priority === "high");
+    (high ? priorityQueue : normalQueue).unshift(e);
+  }
+  armCohortRelease();
+  if (back.length > 0) drainQueue();
+}
+
+/** Fetch a quota reading, then retry the deferred work once. */
+function primeCohortQuota(entry) {
+  const clients = getCohortClients();
+  if (!clients || !clients.quota) return;
+  if (entry.source !== "backlog") {
+    if (cohortInboxPrimeInFlight) return; // one read releases every cold-parked entry
+    cohortInboxPrimeInFlight = true;
+  }
+  Promise.resolve()
+    .then(() => clients.quota.canAdmit())
+    .catch(() => null)
+    .then(() => {
+      try {
+        if (entry.source === "backlog") {
+          // One re-dispatch per prime. A failed read is cached too, so the
+          // second gate answers with a real deferral instead of cold again.
+          if (entry.cohortPrimed) return;
+          dispatch(entry.prompt, entry.item, entry.classResult, "backlog", { obligationKey: entry.obligationKey, onClose: entry.onClose, onSpawn: entry.onSpawn, cohortPrimed: true });
+        } else {
+          cohortInboxPrimeInFlight = false;
+          releaseCohortParked({ cold: true });
+        }
+      } catch (err) {
+        cohortInboxPrimeInFlight = false;
+        console.warn(`[dispatcher] cohort-llm retry after quota prime failed: ${err.message}`);
+      }
+    });
+}
+
+/** Test seam: run one drain pass now (the queue is otherwise drained by closes and timers). */
+export function _drainQueueForTests() {
+  drainQueue();
+}
+
 /** Get current status for health checks */
 export function getStatus() {
   return {
@@ -1972,6 +2416,8 @@ export function getStatus() {
     max_concurrent: MAX_CONCURRENT,
     priority_queue_length: priorityQueue.length,
     normal_queue_length: normalQueue.length,
+    // Inbox entries held off the queues by a cohort-llm deferral (never dropped).
+    cohort_parked_length: cohortParked.length,
     sessions: Array.from(activeSessions.entries()).map(([id, s]) => ({
       id,
       model: s.model,