@sema-agent/core 5.56.0 → 5.57.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 5.57.0 — 2026-08-23
+
+### Added
+- **key×URL pairing adjudicator** (#309 cross-repo case, [5060]-[5063] consensus): `adjudicateModelRoute`
+  is the single source of the credential-pairing law. Per-model credential = paired by construction;
+  the deployment-config credential passes only on the deployment's own declared root; absent credential
+  is legal keyless except for an entry declaring its own off-root URL. Codes `route.credential_mismatch`
+  / `route.credential_missing` (refusal detail carries entry id + both URL halves + a one-line fixHint,
+  fail-closed by ruling). The three first-party brains gate inside buildRequest (refusal terminates
+  before any fetch) and expose `Brain.adjudicateRoute`; routing/failover/degrading/circuit-breaker
+  re-judge per leg (failover serves from the paired leg; a broken degrading hop is skipped). Two-leg
+  disposition: a NAMED model surfaces the refusal; a DERIVED model (compaction summarize, auto-mode
+  classifier, suggestions) pre-flights and falls back to the primary with a `route.fallback_to_primary`
+  notice; `route.base_url_changed_key_unchanged` mints at swapModels. `ROUTE_ADJUDICATION_CONFORMANCE_CORPUS`
+  (16 vectors) exported as the cross-codebase anchor. **Narrowings (each with a fixHint)**: declared-root
+  deployments' off-root entries now refuse instead of silently borrowing the gateway credential; an
+  entry-declared auth header now wins over the deployment key. Preserved byte-identical: unpinned
+  quick-start, keyless single-gateway, header-only boot token, gateway dual-auth.
+- **Per-model auth seats for WebFetch summarizer and team surfaces** (#417): `getApiKeyAndHeaders`
+  on `WebFetchSummarizerOptions` / `TeamDiscussionOptions` / `runScenario` (absent seat = byte-identical).
+- **Compound-prefix permission rules** (#364 case B, ruled; registered divergence): `Bash(cd /tmp && adb pull:*)`
+  — leading segments byte-exact, only the final segment takes arguments. The validator accepts the
+  chain form (a `*` in any other position still refuses); the matcher admits on segment-count equality
+  + byte-prefix at a word boundary (a single-command prefix still never admits a compound; the segment
+  deny/ask fence stays strictly ahead of the allow lane); the suggester mints the compound-prefix
+  sibling at index 1 when the final segment fits the same grammar as the simple seat; the card-edit
+  face accepts the respelling; org tighten gains the same grammar (a compound-prefix deny is enforceable
+  instead of bricking its snapshot). **Widenings**: validator accepts the new form; eligible compounds
+  offer 2 seats; card edit + import accept it; org snapshots carrying it are enforceable. **Mixed-fleet
+  note**: older engines quarantine compound-prefix rows (bytes preserved, disclosed) — do not publish
+  compound-prefix org rules before the fleet is level.
+- **Generic prefix grammar for rule suggestions** (#364 R1, CC 2.1.223 iNo corpus): the prefix arm
+  uses the corpus rule `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` with the interpreter/wrapper blacklist; the
+  125-line lexicon demotes to a bonus for multi-word deepening; ASCII-closed head-name screen.
+- **`precheckEditedRuleText(text, command)`** (#428, server pickup): the card-edit face's three text
+  gates (spelling normalization → grammar → coverage bound) extracted to one shared body and exported
+  (`EditedRuleTextPrecheck`). `ok` means SUBMITTABLE (record-level gates stay with `confirmRuleApproval`);
+  `canonicalRule` may differ from the submitted bytes; refusal words match `edit_rejected.detail`
+  verbatim (`code` rides validator refusals only). The entry screens unrenderable command bytes loudly
+  (`config.invalid_argument`).
+- **ScheduleWakeup honesty family** (#424 A-1/A-4): the wakeup intent carries `lifetime:"session"`
+  where the backend vouched for the reap contract; an undeclared backend keeps the historic durable
+  intent with receipt + description disclosure; `reason` rides `details.reason`. An incomplete
+  replace (stale wakeup possibly still armed) is disclosed on the receipt.
+- **SendMessage completion promises follow mount truth** (#424 A-6): `notificationWired?` / `oneShot?`
+  seats (defaults preserve wired behavior byte-identical); the unwired arm teaches retrieval, the
+  one-shot arm instructs blocking retrieval now; ten sites across two wordings guarded.
+
+### Fixed
+- **Derived-route pre-flight can never sink the main task** (pre-ship rescan P1): the judge call and
+  the whole seat (including URL normalization of garbage catalog values) now abstain on throw instead
+  of failing task preparation and leaking the acquired session view; both derived seats share the
+  guarded helper.
+- **Route URL comparison is wire-equivalent** (rescan): scheme/host case-fold + default-port elision
+  (path half stays byte-ordered; parse failure falls back to raw) — case-only respellings of the same
+  endpoint no longer refuse as `credential_mismatch`.
+- **MCP revocation copy tells the standing truth at all four outlets** (rescan; #424 A-5 completed):
+  the ListMcpResources arm joins the other three ("stays on this run's roster; every call refused
+  the same way"), with an extinction tripwire for the old sentence.
+- **AgentHarness auth carriers refuse loudly at the two host seats** (rescan hardening): a
+  deployment-wide auth header in `streamOptions.headers` is refused with a migration hint instead of
+  silently riding beside per-model credentials; `stripAuthHeaders` retired (zero callers).
+- **ExitWorktree parameter texts describe this tool** (#424 A-8): detached worktrees have no branch;
+  a changed tree is KEPT (not refused) — CC originals and reasoning recorded at the schema.
+- **Read-only memory notice restores CC's recall-framing paragraph** (#424 A-9, byte-compared).
+- **MCP/scheduler small truths** (rescan): the wakeup mount note is led by the `supportsSessionWakeup:false`
+  arm; an explicitly-declared `supportsSessionLifetime:false` backend behaves like an undeclared one
+  (seam defines the two spellings as one state — the refusal arm from an unshipped interim build rolled back).
+
+### Bench (not part of the package surface)
+- LLM distillation arm for the memory benchmark (three-clause instruction arc: retained 20.8%→100%,
+  convergence restored; distillation quality flat with the hand-authored ceiling on this corpus's
+  measurable axes); live provider key no longer travels to the loopback observation plane.
+
 ## 5.56.0 — 2026-08-23
 
 ### Fixed

package/dist/agents/send-message-tool.d.ts

@@ -33,6 +33,17 @@ export interface SendMessageToolOptions {
     notify?: (n: TaskNotificationPayload, opts?: {
         priority?: "now" | "next" | "later";
     }) => void;
+    /** Whether a completion notification really reaches the sender — drives every "you will be notified"
+     *  sentence on this face (description + four receipts), mirroring TaskOutput's `notificationWired`.
+     *  Default = `notify !== undefined`, which is the truth on both the first-party mount and a direct
+     *  mount that wires its own sink here. Pass `true` only when the deployment announces a finished
+     *  agent through a channel of its own (this tool then keeps the wired wording); `false` states the
+     *  degraded truth explicitly. */
+    notificationWired?: boolean;
+    /** RB-220 mirror of {@link import("../core/types.js").TaskSpec.oneShot} (the Runner mount fills it):
+     *  this run's process exits when the turn ends, so no completion notification can ever land — checked
+     *  AHEAD of {@link notificationWired}, since no amount of wiring makes a later turn exist. */
+    oneShot?: boolean;
     /** Steer-handle sink: the revived run re-emits a FRESH handle (design/122 risk-table contract). */
     sink?: (handle: SubagentSteerHandle) => void;
     /**

package/dist/agents/send-message-tool.js

@@ -46,6 +46,21 @@ function targetLaneKey(scope, targetId) {
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const completionMode = opts.oneShot === true ? "one_shot" : (opts.notificationWired ?? opts.notify !== undefined) ? "notified" : "silent";
+    const notifyWired = completionMode === "notified";
+    const NO_COMPLETION_NOTICE = completionMode === "one_shot"
+        ? "this is a ONE-SHOT submission — there is no later turn for a completion notification to land in, so retrieve its result NOW with TaskOutput(task_id, block: true) rather than ending your turn"
+        : "its completion is NOT announced on this mount — retrieve its status and result with TaskOutput(task_id) where mounted";
+    const AWAIT_COMPLETION = notifyWired
+        ? "Wait for its completion notification"
+        : completionMode === "one_shot"
+            ? "Wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
+            : "Check for its completion with TaskOutput(task_id) where mounted";
+    const awaitCompletion = notifyWired
+        ? "wait for its completion notification"
+        : completionMode === "one_shot"
+            ? "wait for it NOW with TaskOutput(task_id, block: true) — this one-shot submission ends with this turn"
+            : "check for its completion with TaskOutput(task_id) where mounted";
     const sendMessagePins = new Map();
     const pinGuard = (targetId, targetName, rung, to) => {
         if (rung === "other")
@@ -86,8 +101,11 @@ export function createSendMessageTool(opts) {
             `background run with its full prior conversation preserved, so don't re-explain what it already knows. Names ` +
             `keep working after an agent completes; but if a name you already messaged is later taken by a NEWER agent, the ` +
             `send is refused rather than silently redirected — re-send with the task_id of whichever agent you meant. ` +
-            `You will be notified automatically when it completes — prefer ending your turn; do not ` +
-            `poll. ` +
+            (notifyWired
+                ? `You will be notified automatically when it completes — prefer ending your turn; do not poll. `
+                : completionMode === "one_shot"
+                    ? `This is a ONE-SHOT submission: there is no later turn for a completion notification to land in, so do NOT end your turn expecting one — wait actively with TaskOutput(task_id, block: true) when you need a continued agent's result. `
+                    : `A finished agent is NOT announced on this mount — check on it with TaskOutput(task_id) where mounted rather than ending your turn to wait for a notification that never comes. `) +
             (tier3Capable
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
                 : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
@@ -255,7 +273,7 @@ export function createSendMessageTool(opts) {
                 if (row.status === "running") {
                     if (row.writerId === opts.registry.writerId) {
                         return {
-                            content: `Message not sent: ${whoT3} is currently running in this process but its mid-run delivery channel is not reachable from here. Wait for its completion notification, then send again to continue it.`,
+                            content: `Message not sent: ${whoT3} is currently running in this process but its mid-run delivery channel is not reachable from here. ${AWAIT_COMPLETION}, then send again to continue it.`,
                             details: { error: "still_running", to },
                             isError: true,
                         };
@@ -268,7 +286,7 @@ export function createSendMessageTool(opts) {
                         };
                     }
                     return {
-                        content: `Message not sent: ${whoT3} is running on another host — this process has no delivery channel to it. Wait for its completion notification, then send again to continue it.`,
+                        content: `Message not sent: ${whoT3} is running on another host — this process has no delivery channel to it. ${AWAIT_COMPLETION}, then send again to continue it.`,
                         details: { error: "running_elsewhere", to },
                         isError: true,
                     };
@@ -501,7 +519,9 @@ export function createSendMessageTool(opts) {
                     const priorCount = lease.messages.length - 1;
                     return {
                         content: `Message sent — ${whoT3} was revived in the background with its prior context intact${priorCount > 0 ? ` (${priorCount} earlier pending message(s) delivered with it)` : ""}. ` +
-                            `You will be notified automatically when it completes. Continue with other work — do not poll.`,
+                            (notifyWired
+                                ? `You will be notified automatically when it completes. Continue with other work — do not poll.`
+                                : `${NO_COMPLETION_NOTICE.charAt(0).toUpperCase()}${NO_COMPLETION_NOTICE.slice(1)}.`),
                         details: { type: "send-message", status: "revived", to, task_id: handle, seq: nextSeq, ...(priorCount > 0 ? { priorMessages: priorCount } : {}) },
                     };
                 }
@@ -628,10 +648,10 @@ export function createSendMessageTool(opts) {
                     }, { priority: "next" });
                     if (delivered.ok) {
                         const receiptText = delivered.disposition === "parked"
-                            ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. You will be notified of its completion; continue with other work.`
+                            ? `Message parked for ${who}: the agent finished before reading it — it will be delivered when the agent is next continued. ${notifyWired ? "You will be notified of its completion; continue with other work." : `Note: ${NO_COMPLETION_NOTICE}.`}`
                             : delivered.disposition === "pending"
-                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. You will be notified of the agent's completion either way; resend then if it went unanswered. ${DEDUP_RETRY_NOTE}`
-                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — you will be notified of its completion either way; resend then if it went unanswered. Continue with other work; do not poll. ${DEDUP_RETRY_NOTE}`;
+                                ? `Message accepted for ${who} but delivery is UNCONFIRMED (its channel did not confirm within the wait window) — it stays queued and will deliver if the channel binds. ${notifyWired ? "You will be notified of the agent's completion either way" : `Note: ${NO_COMPLETION_NOTICE}`}; resend then if it went unanswered. ${DEDUP_RETRY_NOTE}`
+                                : `Message queued for delivery to ${who} at its next turn. If it finishes before reading it, the message may not survive — ${notifyWired ? "you will be notified of its completion either way" : NO_COMPLETION_NOTICE}; resend then if it went unanswered. ${notifyWired ? "Continue with other work; do not poll. " : ""}${DEDUP_RETRY_NOTE}`;
                         return {
                             content: receiptText,
                             details: { type: "send-message", status: "delivered_running", disposition: delivered.disposition, to, task_id: targetId, summary },
@@ -639,7 +659,7 @@ export function createSendMessageTool(opts) {
                     }
                     if (delivered.reason === "no_channel") {
                         return {
-                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. Wait for its completion notification, then SendMessage to continue it. ${DEDUP_RETRY_NOTE}`,
+                            content: `Message not sent: ${who} is still running and this deployment has no mid-run delivery channel for it. ${AWAIT_COMPLETION}, then SendMessage to continue it. ${DEDUP_RETRY_NOTE}`,
                             details: { error: "still_running", to },
                             isError: true,
                         };
@@ -705,7 +725,7 @@ export function createSendMessageTool(opts) {
             }
             if (ledger.get(resumeToolUseId)?.running === true) {
                 return {
-                    content: `Message not sent: ${who} (or a prior follow-up to it) is still running — wait for its completion notification.`,
+                    content: `Message not sent: ${who} (or a prior follow-up to it) is still running — ${awaitCompletion}.`,
                     details: { error: "steering.still_running", to },
                     isError: true,
                 };
@@ -761,7 +781,9 @@ export function createSendMessageTool(opts) {
                     const marker = await resume(`${fromPrefix}[${safeSummary}] ${safeMessage}`);
                     return {
                         content: `Message sent — ${who} resumed in the background with its prior context intact (correlation marker [${marker}]).\n` +
-                            `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`,
+                            (notifyWired
+                                ? `You will be notified automatically when it completes; its reply will carry [${marker}]. Continue with other work — do not poll.`
+                                : `Its reply will carry [${marker}], but ${NO_COMPLETION_NOTICE}.`),
                         details: { type: "send-message", status: "resumed", to, task_id: targetId, marker, summary },
                     };
                 }
@@ -778,7 +800,7 @@ export function createSendMessageTool(opts) {
                                     ? `${who} reached its resume cap (${SUBAGENT_RESUME_CAP} follow-ups per agent) — relaunch a new agent instead.`
                                     : code === "steering.still_running"
                                         ?
-                                            `${who} (or a prior follow-up to it) is still running — wait for its completion notification. ${DEDUP_RETRY_NOTE}`
+                                            `${who} (or a prior follow-up to it) is still running — ${awaitCompletion}. ${DEDUP_RETRY_NOTE}`
                                         : code === "resume.row_recycling"
                                             ?
                                                 `${who}'s registry row is being adjudicated right now (a revival claim or a reap sweep holds it) — send again in a moment. ${DEDUP_RETRY_NOTE}`

package/dist/agents/team.d.ts

@@ -1,5 +1,5 @@
 import type { Runner } from "../core/runner/runtask.js";
-import type { McpServerSpec, ModelRef, ModelRole, TaskResult, ToolSpec } from "../core/types.js";
+import type { McpServerSpec, ModelRef, ModelRole, TaskResult, TaskSpec, ToolSpec } from "../core/types.js";
 export interface TeamMember {
     /** The member's role / specialty, e.g. "安全评审" or "performance". */
     role: string;
@@ -99,6 +99,15 @@ export interface TeamDiscussionOptions {
         denyTools?: string[];
         mcp?: McpServerSpec[];
     };
+    /**
+     * Per-model auth — MIRRORS {@link TaskSpec.getApiKeyAndHeaders} (forwarded into every member /
+     * summary / synthesizer run, which resolve it against their own resolved models). Without this
+     * seat a team whose member/synthesizer models live on per-model-credential routes had NO way to
+     * carry the resolver: every nested run fell to the brain's construction-time credential, which the
+     * key↔URL pairing gate refuses off the deployment root — the teacher/verify delegation family
+     * carries the same seat for the same reason.
+     */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
     /** Progress callback. */
     onEvent?: (e: TeamEvent) => void;
     /**

package/dist/agents/team.js

@@ -117,6 +117,7 @@ export async function runTeamDiscussion(opts) {
                 limits: memberLimits,
                 signal: opts.signal,
                 ...(opts.principal !== undefined ? { principal: opts.principal } : {}),
+                ...(opts.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: opts.getApiKeyAndHeaders } : {}),
             }, { isDelegatedChild: true });
             tokens += res.stats.tokens + (res.stats.nested?.tokens ?? 0);
             turns += res.stats.turns + (res.stats.nested?.turns ?? 0);

package/dist/brain/anthropic.js

@@ -5,7 +5,8 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders, takeHeaderCasefold } from "./request-params.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
@@ -234,7 +235,17 @@ export function createAnthropicBrain(config = {}) {
             httpLabel: "anthropic",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "https://api.anthropic.com").replace(/\/+$/, "");
                 const nonEmptyBlocks = context.systemBlocks?.filter((b) => b.text.length > 0);
                 const system = nonEmptyBlocks?.length
@@ -302,8 +313,7 @@ export function createAnthropicBrain(config = {}) {
                     betas.push("interleaved-thinking-2025-05-14");
                 }
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 if (betas.length > 0) {
                     const existing = (takeHeaderCasefold(headers, "anthropic-beta") ?? "").split(",").map((b) => b.trim()).filter(Boolean);
                     for (const beta of betas) {
@@ -680,5 +690,5 @@ export function createAnthropicBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }

package/dist/brain/circuit-breaker.js

@@ -153,5 +153,6 @@ export function createCircuitBreakerBrain(inner, opts = {}) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => inner.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/brain/degrading.js

@@ -144,6 +144,8 @@ export function createDegradingBrain(opts) {
                         break;
                     if (hop.model.id === failedModelId)
                         continue;
+                    if (hop.brain.adjudicateRoute?.(hop.model)?.ok === false)
+                        continue;
                     chainPath.push(hop.model.id);
                     degradeInfo = {
                         from: model.id,
@@ -182,5 +184,6 @@ export function createDegradingBrain(opts) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => opts.primary.adjudicateRoute?.(model, perModelAuth);
+    return { stream, adjudicateRoute };
 }

package/dist/brain/failover.js

@@ -82,5 +82,20 @@ export function createFailoverBrain(brains) {
         })();
         return out;
     };
-    return { stream };
+    const adjudicateRoute = (model, perModelAuth) => {
+        let firstRefusal;
+        let sawUnjudged = false;
+        for (const b of brains) {
+            const verdict = b.adjudicateRoute?.(model, perModelAuth);
+            if (verdict === undefined) {
+                sawUnjudged = true;
+                continue;
+            }
+            if (verdict.ok)
+                return verdict;
+            firstRefusal ??= verdict;
+        }
+        return sawUnjudged ? undefined : firstRefusal;
+    };
+    return { stream, adjudicateRoute };
 }

package/dist/brain/open-responses.js

@@ -5,7 +5,8 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
@@ -228,7 +229,17 @@ export function createOpenResponsesBrain(config = {}) {
             httpLabel: "responses",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
@@ -265,8 +276,7 @@ export function createOpenResponsesBrain(config = {}) {
                 if (effort !== undefined)
                     body.reasoning = { effort };
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
@@ -738,5 +748,5 @@ export function createOpenResponsesBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }

package/dist/brain/openai.js

@@ -5,7 +5,9 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
+import { BrainError } from "./errors.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, createBrainRouteJudge, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
 import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
@@ -270,7 +272,17 @@ export function createOpenAIBrain(config = {}) {
             httpLabel: "gateway",
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const apiKey = options?.apiKey ?? config.apiKey;
+                const routeCredential = resolveRouteCredential({
+                    optionsApiKey: options?.apiKey,
+                    optionsHeaders: options?.headers,
+                    modelHeaders: model.headers,
+                    configApiKey: config.apiKey,
+                    configHeaders: config.headers,
+                });
+                const routeVerdict = adjudicateModelRoute(model, routeCredential, { baseUrl: config.baseUrl });
+                if (!routeVerdict.ok)
+                    throw new BrainError("invalid_request", routeRefusalText(routeVerdict));
+                const apiKey = routeCredential.apiKey;
                 const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
@@ -304,8 +316,7 @@ export function createOpenAIBrain(config = {}) {
                     body.stop = options.stop;
                 applyThinking(body, model, options?.reasoning);
                 const headers = mergeHeaders(model.headers, config.headers, options?.headers);
-                if (options?.apiKey !== undefined)
-                    stripAuthHeaders(headers);
+                applyRouteCredentialHeaders(headers, routeCredential, { model: model.headers, options: options?.headers });
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
@@ -618,5 +629,5 @@ export function createOpenAIBrain(config = {}) {
             },
         });
     };
-    return { stream };
+    return { stream, adjudicateRoute: createBrainRouteJudge(config) };
 }

package/dist/brain/request-params.d.ts

@@ -22,17 +22,16 @@ export declare function reservedFor(api: string): ReadonlySet<string>;
  * deployment with no `extraBody` is unaffected.
  */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
-/**
- * Per-call auth REPLACES construction-time auth: drop every auth-bearing header
- * (case-insensitive `authorization` / `x-api-key`) from an already-merged header bag. Called by a
- * brain's buildRequest ONLY when a per-call `options.apiKey` is present — the brain then re-emits
- * the credential in its own wire posture (anthropic `x-api-key`, openai `Bearer`), making the
- * per-call key the request's single credential. Case-insensitivity matters twice: a
- * construction-time `Authorization` (capital A) is what boot env tokens ship, and a case-variant
- * duplicate would otherwise ride the wire alongside the hard-locked lowercase form (fetch Headers
- * folds duplicates into one comma-joined value — broken auth both ways).
- */
-export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/** The auth-bearing header names (case-fold), single-sourced for the credential enforcement
+ *  (`applyRouteCredentialHeaders`, route-adjudicator.ts — the ONE authority over auth spelling: a
+ *  per-model winner strips every carrier, any case, and re-asserts the winning bag's own),
+ *  {@link mergeHeaders} (which EXEMPTS them — see there), and the route credential resolver (which
+ *  reads carrier PRESENCE per bag to classify a headers-borne credential). The former per-call
+ *  strip helper that lived here (`stripAuthHeaders` — "per-call auth replaces construction-time
+ *  auth", triggered on `options.apiKey` presence) is retired: the three brains now run the
+ *  route-credential resolution instead, whose per-model arm strips a strict superset of what the
+ *  helper did. */
+export declare const AUTH_CARRIER_NAMES: ReadonlySet<string>;
 /**
  * #343 — the shared USER-HEADER merge layer (`model.headers` → construction `config.headers` →
  * per-call `options.headers`, later bag wins), CASE-FOLD deduplicated: HTTP header field names are
@@ -45,26 +44,29 @@ export declare function stripAuthHeaders(headers: Record<string, string>): void;
  * deployment — is byte-identical on the wire).
  *
  * EXEMPT: the auth carriers (`authorization` / `x-api-key`, any case) pass through with the exact
- * legacy spread semantics (same-spelling override only, no case-fold dedup), so that
- * {@link stripAuthHeaders} stays the ONE authority over auth spelling and this layer never becomes a
- * second, subtly different one.
+ * legacy spread semantics (same-spelling override only, no case-fold dedup), so that the credential
+ * enforcement (`applyRouteCredentialHeaders`, route-adjudicator.ts) stays the ONE authority over
+ * auth spelling and this layer never becomes a second, subtly different one.
  *
  * RE-RULED, because the exemption used to be justified by a reason that does not hold: the
  * note claimed it protected "the header-only ANTHROPIC_AUTH_TOKEN shape, which must survive under its
  * own capital-A spelling". Dedup would not endanger that shape — it keeps the WINNER'S spelling, and a
  * lone `Authorization` has nothing to be deduped against, so it survives either way; nor does the
- * per-call-replaces flow depend on the exemption, since {@link stripAuthHeaders} already deletes every
- * spelling present. Measured, not reasoned: `mergeHeaders({Authorization:A},{authorization:B})` keeps
- * BOTH, and the platform `Headers` fold sends `authorization: A, B`.
+ * credential-replaces flow depend on the exemption, since the enforcement already deletes every
+ * spelling present when a per-model credential wins. Measured, not reasoned:
+ * `mergeHeaders({Authorization:A},{authorization:B})` keeps BOTH, and the platform `Headers` fold
+ * sends `authorization: A, B`.
  *
- * STATED RESIDUAL (deliberately not fixed here): a deployment that spells the SAME auth carrier two
- * ways across two layers therefore ships both, comma-folded — the very disease this function fixed
- * for every other header. It is held, not denied, on severity: no server accepts a comma-joined
- * credential, so the failure is a LOUD 401 attributable to the misconfiguration, whereas the
- * non-auth case this function exists for produced a silently WRONG value (`X-Tenant: a, b` — neither
- * writer's, the later layer's documented override defeated). Tightening it changes which credential
- * reaches the wire, so it belongs in a window that discloses an auth-face behavior change, not in one
- * whose subject is the reasoning knob.
+ * STATED RESIDUAL (deliberately not fixed here), NARROWED by the credential enforcement: where a
+ * PER-MODEL credential wins (an options- or entry-bag carrier), every carrier is stripped and only
+ * the winning bag's re-asserted, so a cross-layer double spelling now folds to the winner. What
+ * remains is the DEPLOYMENT-CONFIG arm — its bytes ride untouched by design — so a config bag that
+ * itself spells the SAME auth carrier two ways still ships both, comma-folded. It is held, not
+ * denied, on severity: no server accepts a comma-joined credential, so the failure is a LOUD 401
+ * attributable to the misconfiguration, whereas the non-auth case this function exists for produced
+ * a silently WRONG value (`X-Tenant: a, b` — neither writer's, the later layer's documented
+ * override defeated). Tightening it changes which credential reaches the wire, so it belongs in a
+ * window that discloses an auth-face behavior change.
  */
 /**
  * #343 (review r4) — assign a STRUCTURAL locked header under its canonical lowercase name, deleting
@@ -72,8 +74,9 @@ export declare function stripAuthHeaders(headers: Record<string, string>): void;
  * the user-bag merge precisely so they "can NEVER be overridden" (council design/40) — but a valid
  * user bag carrying `Content-Type: text/plain` survived BESIDE the lowercase lock, and the platform
  * `Headers` fold turns the pair into `text/plain, application/json` on the wire: the lock decided
- * nothing. Auth carriers are deliberately NOT routed through here (per-call replacement + the
- * header-only boot flow are {@link stripAuthHeaders}' pinned jurisdiction).
+ * nothing. Auth carriers are deliberately NOT routed through here (credential replacement + the
+ * header-only boot flow are the pinned jurisdiction of `applyRouteCredentialHeaders`,
+ * route-adjudicator.ts).
  */
 export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
 /**

package/dist/brain/request-params.js

@@ -54,13 +54,7 @@ export function applyExtraBody(body, extraBody, reserved) {
     }
     return { ...passthrough, ...body };
 }
-const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
-export function stripAuthHeaders(headers) {
-    for (const k of Object.keys(headers)) {
-        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
-            delete headers[k];
-    }
-}
+export const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
 export function lockHeader(headers, lowerName, value) {
     for (const k of Object.keys(headers)) {
         if (k !== lowerName && k.toLowerCase() === lowerName)