@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/model-router/failover.mjs

@@ -18,7 +18,26 @@
  * House style: ESM, Node built-ins only, mirrors rate-guard's deps-injection.
  */
 
-import { DISPOSITION, asFailoverReason, cooldownMsFor } from "./taxonomy.mjs";
+import { DISPOSITION, asFailoverReason, cooldownMsFor, MAX_SAME_RETRY_AFTER_MS } from "./taxonomy.mjs";
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * The cohort refusal an attempt reported (a normalised §4.8 object, as
+ * lib/org/quota.mjs `parseRefusalBody` returns), or null.
+ * @param {object|undefined} meta
+ */
+function refusalOf(meta) {
+  const r = meta && meta.refusal;
+  return r && typeof r === "object" && typeof r.code === "string" && r.code.startsWith("cohort_") ? r : null;
+}
+
+/** A finite, non-negative retry-after (ms) an attempt reported, or null. */
+function retryAfterOf(meta) {
+  return meta && Number.isFinite(meta.retryAfterMs) && meta.retryAfterMs >= 0 ? meta.retryAfterMs : null;
+}
 
 /**
  * @typedef {object} Candidate
@@ -74,6 +93,15 @@ function cooldownKey(candidate, scope) {
  *                             may advance ONCE (the "one Anthropic-only re-route
  *                             permitted" rule). Default false (sticky refusal).
  *   maxAttempts             → hard cap on total attempts (safety net; default 32)
+ *   sleep(ms)               → injected sleep for a disposition's retryBackoffMs
+ *                             ladder (request_timeout). Default: a real timer.
+ *
+ * A cohort refusal is handed back, never scheduled here. When the final attempt
+ * reported `meta.refusal` (budget_refusal, gateway_retry) the result carries it
+ * as `refusal`, with `retryAfterMs` when the response named one. The daemon's
+ * one scheduler for cohort holds is `rateGuard.recordCohortRefusal(refusal)`;
+ * stepChain computes no wake time for these reasons (CF-143: the earlier
+ * gateway_retry wake had no production caller — see docs/engine/README.md).
  *
  * @param {Candidate[]} chain
  * @param {object} opts
@@ -83,7 +111,9 @@ function cooldownKey(candidate, scope) {
  *   chosen?: Candidate,
  *   reason: string|null,           // final reason (null on success)
  *   tried: Array<{ref, reason, retry?:boolean, meta?:object}>,
- *   soonestCooldownExpiry: number|null,  // epoch ms to re-queue at, or null
+ *   soonestCooldownExpiry: number|null,  // epoch ms a BREAKER cooldown ends, or null
+ *   refusal?: object|null,         // the final attempt's cohort refusal (resetsAt, window, scope)
+ *   retryAfterMs?: number|null,    // the final attempt's retry-after
  *   attempts: number
  * }>}
  */
@@ -94,6 +124,7 @@ export async function stepChain(chain, opts = {}) {
   const onAttempt = typeof opts.onAttempt === "function" ? opts.onAttempt : null;
   const allowContentReroute = opts.allowContentReroute === true;
   const maxAttempts = Number.isFinite(opts.maxAttempts) ? opts.maxAttempts : 32;
+  const sleep = typeof opts.sleep === "function" ? opts.sleep : defaultSleep;
 
   const tried = [];
   const candidates = Array.isArray(chain) ? chain.filter(Boolean) : [];
@@ -142,14 +173,14 @@ export async function stepChain(chain, opts = {}) {
 
     // ── Attempt this candidate, with same-candidate retry where allowed ──
     let advanced = false;
-    let retriedThisCandidate = false;
+    let sameRetries = 0;
     while (attempts < maxAttempts) {
       attempts++;
       let res;
       try {
         res = await attempt(candidate, {
           attemptIndex: attempts - 1,
-          retryOfRef: retriedThisCandidate ? candidate.ref : null,
+          retryOfRef: sameRetries > 0 ? candidate.ref : null,
           now: now(),
         });
       } catch (err) {
@@ -182,7 +213,7 @@ export async function stepChain(chain, opts = {}) {
       const record = {
         ref: candidate.ref,
         reason,
-        retry: retriedThisCandidate || undefined,
+        retry: sameRetries > 0 || undefined,
         meta: res.meta,
       };
       tried.push(record);
@@ -212,13 +243,25 @@ export async function stepChain(chain, opts = {}) {
       }
 
       // ── retry-same? ──────────────────────────────────────────────────
-      const canRetrySame =
-        !retriedThisCandidate &&
-        d.retrySame &&
-        d.retrySame !== "cli"; // "cli" means the CLI already retried internally
-      if (canRetrySame) {
-        retriedThisCandidate = true;
-        continue; // retry the SAME candidate once
+      // A row with a retryBackoffMs ladder retries once per entry, sleeping
+      // first (request_timeout, CF-143); any other retrying row retries once,
+      // immediately. "cli" means the CLI already retried internally.
+      const ladder = Array.isArray(d.retryBackoffMs) ? d.retryBackoffMs : null;
+      const sameBudget = ladder ? ladder.length : d.retrySame && d.retrySame !== "cli" ? 1 : 0;
+      if (sameRetries < sameBudget) {
+        if (ladder) {
+          const ra = retryAfterOf(res.meta);
+          // A retry-after longer than the ceiling is not slept through: fail over.
+          if (ra != null && ra > MAX_SAME_RETRY_AFTER_MS) {
+            sameRetries = sameBudget;
+          } else {
+            await sleep(ra != null ? ra : ladder[sameRetries]);
+          }
+        }
+        if (sameRetries < sameBudget) {
+          sameRetries++;
+          continue; // retry the SAME candidate
+        }
       }
 
       // ── failover-next? ───────────────────────────────────────────────
@@ -232,12 +275,15 @@ export async function stepChain(chain, opts = {}) {
           break; // advance to next candidate
         }
         // No failover for this reason (context_overflow / payload_too_large /
-        // network / sticky content_policy). Terminate the whole walk.
+        // network / sticky content_policy / budget_refusal / gateway_retry).
+        // Terminate the whole walk; a cohort refusal rides back to the caller.
         return {
           ok: false,
           reason,
           tried,
           soonestCooldownExpiry, // null for network/overflow (no cooldown)
+          refusal: refusalOf(res.meta),
+          retryAfterMs: retryAfterOf(res.meta),
           attempts,
           chosen: undefined,
         };
@@ -251,11 +297,14 @@ export async function stepChain(chain, opts = {}) {
   }
 
   // ── Chain exhausted ──────────────────────────────────────────────────
+  const lastMeta = tried.length ? tried[tried.length - 1].meta : undefined;
   return {
     ok: false,
     reason: lastReason || "unknown",
     tried,
     soonestCooldownExpiry,
+    refusal: refusalOf(lastMeta),
+    retryAfterMs: retryAfterOf(lastMeta),
     attempts,
     chosen: undefined,
   };
@@ -288,11 +337,13 @@ export function summarizeExhaustion(summary) {
   const trail = (summary.tried || [])
     .map((t) => `${t.ref ?? "?"}=${t.reason}`)
     .join(" → ");
-  const wake =
-    summary.soonestCooldownExpiry == null
+  const r = summary.refusal;
+  const wake = r
+    ? `cohort refusal ${r.code}${r.resetsAt ? ` (resets ${r.resetsAt})` : ""}; hold the seat via rate-guard, do not re-queue on this summary`
+    : summary.soonestCooldownExpiry == null
       ? "no cooldown (re-queue immediately / DEFER)"
       : `wake at ${new Date(summary.soonestCooldownExpiry).toISOString()}`;
   return `chain exhausted (final=${summary.reason}): ${trail}; ${wake}`;
 }
 
-export const _internals = { cooldownKey, tableCooldownUntil, noopBreaker };
+export const _internals = { cooldownKey, tableCooldownUntil, noopBreaker, refusalOf, retryAfterOf };

package/lib/model-router/llm-task.mjs

@@ -36,8 +36,9 @@
 import { loadCatalogCached, listModels, lookupModel } from "./catalog.mjs";
 import { estimateCost, writeLedgerRow } from "./ledger.mjs";
 import { keyFor, isOpen as healthIsOpen } from "./health.mjs";
-import { classifyHttp, classifyTransportError } from "./taxonomy.mjs";
+import { classifyHttp, classifyTransportError, DISPOSITION } from "./taxonomy.mjs";
 import { repairToolCalls } from "./repair.mjs";
+import { parseRefusalBody } from "../org/quota.mjs";
 
 const GRADE_RANK = { A: 3, B: 2, C: 1 };
 const DATA_CLASSES = new Set(["public", "internal", "sensitive"]);
@@ -389,7 +390,21 @@ export async function llmTask(prompt, opts = {}) {
   if (!ok) {
     const reason = classifyHttp(status, parsedBody ?? rawText ?? null);
     writeRow(catalog, row, wire, {}, opts, request, reason);
-    return fail(reason, { model: row.id, provider: row.provider, ref: row.ref, wire, status });
+    // retry-after (seconds) rides along so a caller can honour it.
+    let retryAfterMs = null;
+    try {
+      const ra = res && res.headers && typeof res.headers.get === "function" ? res.headers.get("retry-after") : null;
+      const secs = ra == null || ra === "" ? NaN : Number(ra);
+      if (Number.isFinite(secs) && secs >= 0) retryAfterMs = Math.round(secs * 1000);
+    } catch { /* advisory */ }
+    // A cohort refusal object (§4.8: code, window, scope, resetsAt, requestId)
+    // is preserved verbatim, so a scheduler can hold until resetsAt
+    // (rateGuard.recordCohortRefusal takes exactly this shape).
+    const refusal = safe(() => parseRefusalBody(parsedBody ?? rawText ?? null), null);
+    const extra = { model: row.id, provider: row.provider, ref: row.ref, wire, status, retryAfterMs, refusal };
+    // A budget refusal is typed non-retryable (x-should-retry: false, CF-143).
+    if (reason === "budget_refusal") extra.retryable = false;
+    return fail(reason, extra);
   }
 
   const { text, usage } = parseResponse(parsedBody, wire);
@@ -453,6 +468,27 @@ export async function llmTask(prompt, opts = {}) {
   return out;
 }
 
+/**
+ * An llmTask result as a stepChain AttemptResult: the reason drives the
+ * disposition table, and `meta` carries what the table and the caller need —
+ * the status, retry-after (a request_timeout ladder honours it) and the cohort
+ * refusal (stepChain hands it back as `outcome.refusal`). PURE.
+ *
+ * @param {object} res  an llmTask result
+ * @returns {{ok:boolean, reason?:string, value?:object, meta:{status:number|null, retryAfterMs:number|null, refusal:object|null, retryable?:boolean}}}
+ */
+export function attemptResultOf(res) {
+  if (!res || typeof res !== "object") return { ok: false, reason: "unknown", meta: { status: null, retryAfterMs: null, refusal: null } };
+  const meta = {
+    status: Number.isFinite(res.status) ? res.status : null,
+    retryAfterMs: Number.isFinite(res.retryAfterMs) ? res.retryAfterMs : null,
+    refusal: res.refusal || null,
+  };
+  if (typeof res.retryable === "boolean") meta.retryable = res.retryable;
+  if (res.ok === true) return { ok: true, value: res, meta };
+  return { ok: false, reason: DISPOSITION[res.reason] ? res.reason : "unknown", meta };
+}
+
 /** Pick the cheapest anthropic direct row (kill-switch path). */
 function pickAnthropicDirect(catalog, request, opts) {
   const minRank = GRADE_RANK[opts.minGrade || request.minGrade || "C"] || GRADE_RANK.C;
@@ -512,4 +548,4 @@ export const _internals = {
   credentialEnvFor,
 };
 
-export default { llmTask, pickDirectModel };
+export default { llmTask, pickDirectModel, attemptResultOf };

package/lib/model-router/resolve.mjs

@@ -34,6 +34,7 @@
  */
 
 import { loadCatalogCached, lookupModel } from "./catalog.mjs";
+import { hasSeatCredential, apiKeyHelperCommand } from "../org/llm-token.mjs";
 import { estimateCost } from "./ledger.mjs";
 import { keyFor, isOpen as breakerIsOpen } from "./health.mjs";
 import { nextCredential as authNextCredential, available as authAvailable } from "./auth-profiles.mjs";
@@ -364,7 +365,10 @@ function gateCandidate(row, req, ctx) {
 
   // 5. data_class — deny-by-default. The provider's allowed_data_classes
   //    (config backends ∩ overlay max) must include the request's data_class.
-  const allowed = ctx.allowedDataClasses[row.provider];
+  //    A FIRST-PARTY provider (Cohort's own gateway) declares its allowance in
+  //    the catalog; a config backends entry or overlay cap still narrows it.
+  const allowed = ctx.allowedDataClasses[row.provider] ||
+    (row.first_party === true && Array.isArray(row.data_classes) ? new Set(row.data_classes) : null);
   if (allowed && !allowed.has(req.data_class)) {
     return { ok: false, reason: "data_class_denied" };
   }
@@ -381,12 +385,26 @@ function gateCandidate(row, req, ctx) {
   //    anthropic-cli the same way. Direct-api Anthropic and ALL third-party rows
   //    require their credential or they are structurally unreachable.
   const sessionAnthropic = row.provider === "anthropic" && harness === "session";
-  if (row.auth_env && !sessionAnthropic) {
+  // A seat-token row (cohort-llm) has no static key: it is reachable when the
+  // seat can mint a token — it holds an OrgApiKey or a live cached token.
+  if (row.auth === "seat_token") {
+    if (!(typeof ctx.seatCredential === "function" && ctx.seatCredential())) {
+      return { ok: false, reason: "missing_credential" };
+    }
+  } else if (row.auth_env && !sessionAnthropic) {
     const cred = resolveRowCredential(row, ctx);
     if (!cred.token) {
       return { ok: false, reason: "missing_credential" };
     }
   }
+  // A third-party SESSION row with no auth_env at all used to pass this gate
+  // (the check above only runs when auth_env is set) and was then retargeted
+  // with a base URL and no token — leaving the seat's Claude subscription token
+  // as the child's only credential, sent to that backend (F1 §5.3). Such a row
+  // is unreachable: it cannot authenticate as itself.
+  if (row.auth !== "seat_token" && !row.auth_env && harness === "session" && row.provider !== "anthropic") {
+    return { ok: false, reason: "missing_credential" };
+  }
 
   // 7. breaker — the per-backend AND per-backend:model breaker must be closed.
   const backendKey = keyFor(row.provider);
@@ -421,6 +439,9 @@ function modelClassOf(row) {
 function buildEnvForSpawn(row, harness, env, config, credCtx) {
   if (harness !== "session") return {};
   if (row.provider === "anthropic") return {};
+  if (row.auth === "seat_token") {
+    return cohortRetargetEnv(row, { agentRoot: (credCtx && credCtx.agentRoot) || env.AGENT_ROOT || env.AGENT_DIR });
+  }
 
   const baseUrl = row.endpoints && row.endpoints.anthropic;
   if (!baseUrl) return {}; // not session-capable on the anthropic wire; caller falls back
@@ -434,14 +455,23 @@ function buildEnvForSpawn(row, harness, env, config, credCtx) {
   // Auth token: a pooled auth-profile set picks the next non-cooled credential
   // (additive — a single-key setup falls through to env[auth_env] exactly as
   // before). credCtx carries { authProfiles, authProfileDeps, now, env }.
+  // Only a NON-EMPTY token is set. An absent one leaves ANTHROPIC_AUTH_TOKEN
+  // out of the retarget set, and the runtime env builder
+  // (lib/runtime/child-env.mjs) refuses to spawn a retarget without it — so the
+  // seat's own Claude credential can never be the token that reaches this
+  // backend.
   if (row.auth_env) {
     const cred = credCtx ? resolveRowCredential(row, credCtx) : null;
     if (cred && cred.pooled && cred.token) {
       out.ANTHROPIC_AUTH_TOKEN = cred.token;
-    } else if (typeof env[row.auth_env] === "string") {
+    } else if (typeof env[row.auth_env] === "string" && env[row.auth_env].trim() !== "") {
       out.ANTHROPIC_AUTH_TOKEN = env[row.auth_env];
     }
   }
+  // `strip_attribution_header: false` still shapes the DECISION record, but the
+  // runtime env builder forces CLAUDE_CODE_ATTRIBUTION_HEADER=0 on every
+  // retarget: a per-request attribution header poisons a third-party prompt
+  // cache, and nothing on this path wants that.
   if (!config || config.strip_attribution_header !== false) {
     out.CLAUDE_CODE_ATTRIBUTION_HEADER = "0";
   }
@@ -451,6 +481,47 @@ function buildEnvForSpawn(row, harness, env, config, credCtx) {
   return out;
 }
 
+/** How often Claude Code re-runs the cohort key helper (well inside a 60-min token). */
+export const COHORT_HELPER_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * The retarget env for a seat-token (cohort-llm) session row — the internal
+ * Path B testbed, where the `claude` binary is pointed at Cohort's gateway
+ * (design C1 / §4.7):
+ *   - ANTHROPIC_BASE_URL = the gateway; NO ANTHROPIC_AUTH_TOKEN. The credential
+ *     is the apiKeyHelper (COHORT_LLM_API_KEY_HELPER, which the runtime adapter
+ *     passes as `--settings`), because a static token outranks the helper and
+ *     would expire mid-session (lib/runtime/child-env.mjs COHORT_HELPER_KEY);
+ *   - every Anthropic slot alias maps to a Cohort tier through the provider's
+ *     tier_map (ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU,FABLE}_MODEL), so a
+ *     `--model sonnet` or a subagent's `haiku` never names an Anthropic model at
+ *     the gateway.
+ * Exported for spawnRouted's per-candidate failover env. PURE.
+ * @param {object} row  a catalog row with auth: "seat_token"
+ * @param {{agentRoot?:string, nodeBin?:string}} [o]
+ */
+export function cohortRetargetEnv(row, o = {}) {
+  const baseUrl = row && row.endpoints && row.endpoints.anthropic;
+  if (!baseUrl) return {};
+  const tm = (row.tier_map && typeof row.tier_map === "object") ? row.tier_map : {};
+  return {
+    ANTHROPIC_BASE_URL: baseUrl,
+    ANTHROPIC_API_KEY: "",
+    ANTHROPIC_MODEL: row.id,
+    ANTHROPIC_SMALL_FAST_MODEL: tm.haiku || row.id,
+    ANTHROPIC_DEFAULT_FABLE_MODEL: tm.fable || row.id,
+    ANTHROPIC_DEFAULT_OPUS_MODEL: tm.opus || row.id,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: tm.sonnet || row.id,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: tm.haiku || row.id,
+    CLAUDE_CODE_SUBAGENT_MODEL: row.id,
+    COHORT_LLM_BASE_URL: baseUrl,
+    COHORT_LLM_API_KEY_HELPER: apiKeyHelperCommand({ agentRoot: o.agentRoot, nodeBin: o.nodeBin }),
+    CLAUDE_CODE_API_KEY_HELPER_TTL_MS: String(COHORT_HELPER_TTL_MS),
+    CLAUDE_CODE_ATTRIBUTION_HEADER: "0",
+    CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: "1",
+  };
+}
+
 function transportFor(row, harness) {
   if (harness === "session") {
     if (row.provider === "anthropic") return TRANSPORT.anthropicApi;
@@ -630,6 +701,21 @@ export function resolveChain(request = {}, opts = {}) {
     authProfiles: opts.authProfiles || null,
     authProfileDeps: opts.authProfileDeps || (agentRoot ? { agentRoot } : undefined),
     now,
+    agentRoot: agentRoot || env.AGENT_ROOT || env.AGENT_DIR || null,
+    // Seat-token (cohort-llm) reachability, asked at most once per resolve.
+    seatCredential: (() => {
+      let memo;
+      return () => {
+        if (memo === undefined) {
+          memo = typeof opts.seatCredential === "function"
+            ? !!opts.seatCredential()
+            // helperReadable: a Path B child authenticates through the
+            // apiKeyHelper, which cannot see an env-only key (it is scrubbed).
+            : hasSeatCredential({ agentRoot: agentRoot || env.AGENT_ROOT || env.AGENT_DIR, env, now, helperReadable: true });
+        }
+        return memo;
+      };
+    })(),
   };
 
   let chosenRow = null;

package/lib/model-router/spawn.mjs

@@ -39,7 +39,7 @@
  * @module lib/model-router/spawn
  */
 
-import { resolveChain } from "./resolve.mjs";
+import { resolveChain, cohortRetargetEnv } from "./resolve.mjs";
 import { stepChain } from "./failover.mjs";
 import { keyFor, isOpen as healthIsOpen, open as healthOpen, close as healthClose } from "./health.mjs";
 import { lookupModel } from "./catalog.mjs";
@@ -47,43 +47,38 @@ import {
   nextCredential as authNextCredential,
   markCredentialCoolingDown as authMarkCooling,
 } from "./auth-profiles.mjs";
+import { buildRuntimeEnv, isCredentialKey, RETARGET_KEYS } from "../runtime/child-env.mjs";
 
 // Failover reasons that indicate the CREDENTIAL itself is the problem (a 429 /
 // auth failure on this key) — these cool THAT credential in the pool so the next
 // attempt rotates to a sibling. A backend/model-class reason (overloaded,
-// server_error, …) cools the breaker, not the key.
+// server_error, …) cools the breaker, not the key. A cohort budget refusal
+// (`budget_refusal`, CF-143) and a gateway transient (`gateway_retry`) are never
+// here: the credential is healthy, and a sibling key of the same tenant would be
+// refused again or would slip past an operator limit.
 const CRED_COOL_REASONS = new Set(["rate_limit", "auth", "auth_permanent", "billing"]);
 
-// Env keys that the session-retarget set is allowed to introduce. Everything
-// else credential-shaped is scrubbed (§7.3) before injection.
-const RETARGET_KEYS = new Set([
-  "ANTHROPIC_BASE_URL",
-  "ANTHROPIC_AUTH_TOKEN",
-  "ANTHROPIC_API_KEY",
-  "ANTHROPIC_MODEL",
-  "ANTHROPIC_SMALL_FAST_MODEL",
-  "CLAUDE_CODE_ATTRIBUTION_HEADER",
-  "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS",
-]);
-
 // ---------------------------------------------------------------------------
 // Child-env scrubbing (graft #3 / §7.3)
 // ---------------------------------------------------------------------------
 
 /**
- * Build the child env by allowlist: start from a scrubbed copy of `baseEnv`
- * with every credential-shaped var (`*_API_KEY` / `*_AUTH_TOKEN`, including the
- * break-glass key) removed, then inject ONLY the resolved candidate's
- * session-retarget pair (decision.envForSpawn). A session routed to a third
- * party never sees Anthropic credentials, and vice versa.
+ * Build the child env by allowlist. A thin compatibility wrapper over the one
+ * runtime env builder, `lib/runtime/child-env.mjs#buildRuntimeEnv`, which owns
+ * the rules:
+ *
+ *   - stock (envForSpawn has no ANTHROPIC_BASE_URL): every foreign
+ *     credential-shaped var is scrubbed; the seat's CLAUDE_CODE_OAUTH_TOKEN is
+ *     kept; ANTHROPIC_API_KEY is kept only with opts.keepAnthropicApiKey.
+ *   - retarget: CLAUDE_CODE_OAUTH_TOKEN and every inherited ANTHROPIC_* var are
+ *     scrubbed too, ANTHROPIC_API_KEY="" and CLAUDE_CODE_ATTRIBUTION_HEADER=0
+ *     are forced, and a retarget without a third-party token is REFUSED.
  *
- * The Anthropic SESSION path (envForSpawn === {}) rides the stock CLI / keychain
- * OAuth or a Console key the spawner owns; we keep an explicitly-injected
- * ANTHROPIC_API_KEY from the caller's base env in that case ONLY if the caller
- * opted in via opts.keepAnthropicApiKey (default: scrub for hygiene). When we do
- * retarget (envForSpawn has ANTHROPIC_BASE_URL), ANTHROPIC_API_KEY="" is part of
- * the retarget set and is injected verbatim (empty-string discipline, W:
- * keychain fallthrough).
+ * A refusal is an expected failure, so callers that can meet one (every spawn
+ * site) call buildRuntimeEnv and branch on `ok`. This wrapper exists for the
+ * callers that hand it a decision the resolver already credential-gated; for
+ * them a refusal means the decision was built wrong, which is a defect — so it
+ * throws rather than return an env that could be spawned.
  *
  * @param {object} baseEnv      usually process.env
  * @param {object} envForSpawn  decision.envForSpawn (the retarget pair) or {}
@@ -92,27 +87,13 @@ const RETARGET_KEYS = new Set([
  * @returns {object} the child env
  */
 export function buildChildEnv(baseEnv, envForSpawn = {}, opts = {}) {
-  const out = {};
-  const src = baseEnv && typeof baseEnv === "object" ? baseEnv : {};
-  for (const [k, v] of Object.entries(src)) {
-    if (isCredentialKey(k)) continue; // scrub all credential-shaped vars
-    out[k] = v;
-  }
-  // For a retarget (third-party session), force the empty-string ANTHROPIC_API_KEY
-  // so Claude Code does NOT fall back to keychain OAuth.
-  const retargeting = !!(envForSpawn && envForSpawn.ANTHROPIC_BASE_URL);
-  if (!retargeting && opts.keepAnthropicApiKey && typeof src.ANTHROPIC_API_KEY === "string") {
-    out.ANTHROPIC_API_KEY = src.ANTHROPIC_API_KEY;
-  }
-  // Inject only the retarget set (whitelisted keys).
-  for (const [k, v] of Object.entries(envForSpawn || {})) {
-    if (RETARGET_KEYS.has(k)) out[k] = v;
+  const r = buildRuntimeEnv({ baseEnv, retarget: envForSpawn, keepAnthropicApiKey: !!opts.keepAnthropicApiKey });
+  if (!r.ok) {
+    const err = new Error(r.error.message);
+    err.code = r.error.code;
+    throw err;
   }
-  return out;
-}
-
-function isCredentialKey(k) {
-  return /(_API_KEY|_AUTH_TOKEN|_SECRET|_ACCESS_KEY|_PRIVATE_KEY)$/i.test(k) || k === "ANTHROPIC_API_KEY";
+  return r.env;
 }
 
 // ---------------------------------------------------------------------------
@@ -193,6 +174,9 @@ function envForCandidate(catalog, ref, harness, baseEnv, decision, authCtx) {
   }
   if (!row || harness !== "session") return isChosen ? decision.envForSpawn || {} : {};
   if (row.provider === "anthropic") return isChosen ? decision.envForSpawn || {} : {};
+  // A seat-token (cohort-llm) candidate authenticates through the key helper,
+  // never a pooled/static token.
+  if (row.auth === "seat_token") return cohortRetargetEnv(row, { agentRoot: baseEnv && (baseEnv.AGENT_ROOT || baseEnv.AGENT_DIR) });
   const baseUrl = row.endpoints && row.endpoints.anthropic;
   if (!baseUrl) return isChosen ? decision.envForSpawn || {} : {};
   const out = {
@@ -393,8 +377,20 @@ export async function spawnRouted(request = {}, opts = {}) {
       // strip it from the retarget set so it can never leak into the child env.
       const credFingerprint = retarget.__credFingerprint || null;
       if (retarget.__credFingerprint !== undefined) delete retarget.__credFingerprint;
-      const childEnv = buildChildEnv(env, retarget, { keepAnthropicApiKey: opts.keepAnthropicApiKey });
+      const built = buildRuntimeEnv({ baseEnv: env, retarget, keepAnthropicApiKey: !!opts.keepAnthropicApiKey });
       lastArgs = args;
+      if (!built.ok) {
+        // Refused retarget (no third-party token, a subscription token as the
+        // token, a helper aimed at another gateway): this candidate cannot be
+        // spawned without handing it the seat's own credential. Nothing left the
+        // machine, so nothing is known about the backend: fail over as a
+        // LOCAL refusal, which opens no breaker (CF-11 — reporting it as `auth`
+        // cooled a real provider for 5 minutes on a local config gap) and cools
+        // no credential.
+        lastEnv = null;
+        return { ok: false, reason: "local_refusal", meta: { refused: built.error.code } };
+      }
+      const childEnv = built.env;
       lastEnv = childEnv;
 
       let res;
@@ -442,6 +438,9 @@ export async function spawnRouted(request = {}, opts = {}) {
     env: lastEnv,
     outcome,
     tried: outcome.tried || [],
+    // A cohort refusal the walk stopped on (budget_refusal / gateway_retry),
+    // with resetsAt: hand it to rateGuard.recordCohortRefusal to hold the seat.
+    refusal: outcome.refusal || null,
     ok: outcome.ok === true,
   };
 }