@sema-agent/core 5.48.0 → 5.50.0

package/dist/brain/open-responses.js

@@ -5,8 +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, stripAuthHeaders } from "./request-params.js";
-import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
@@ -151,16 +151,12 @@ function toResponsesTools(ctx) {
     }));
 }
 function resolveWireEffort(model, reasoning) {
-    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
+    if (!reasoningRequestCarried(model, reasoning))
         return undefined;
     const compat = responsesCompat(model);
     if (compat.supportsReasoningEffort === false)
         return undefined;
-    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
-    const mapped = model.thinkingLevelMap?.[effort];
-    if (mapped === null)
-        return undefined;
-    return mapped ?? effort;
+    return mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
 }
 function computeUsage(model, raw) {
     const input = raw?.input_tokens ?? 0;
@@ -268,14 +264,10 @@ export function createOpenResponsesBrain(config = {}) {
                 }
                 if (effort !== undefined)
                     body.reasoning = { effort };
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
-                headers["content-type"] = "application/json";
+                lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
                 const wire = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);

package/dist/brain/openai.js

@@ -5,8 +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 { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
-import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
     if (acc.closedTc)
@@ -86,19 +86,11 @@ function applyThinking(body, model, reasoning) {
         }
         return;
     }
-    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
+    if (!reasoningRequestCarried(model, reasoning))
         return;
     const compat = thinkingCompat(model);
     const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
-    let effortWire = effort;
-    if (model.thinkingLevelMap) {
-        const mapped = model.thinkingLevelMap[effort];
-        if (mapped === null)
-            effortWire = undefined;
-        else if (mapped !== undefined)
-            effortWire = mapped;
-    }
+    const effortWire = mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
     const format = compat.thinkingFormat ?? "openai";
     switch (format) {
         case "openai":
@@ -311,14 +303,10 @@ export function createOpenAIBrain(config = {}) {
                 if (options?.stop)
                     body.stop = options.stop;
                 applyThinking(body, model, options?.reasoning);
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
-                headers["content-type"] = "application/json";
+                lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
                 const wire = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);

package/dist/brain/reasoning.d.ts

@@ -16,6 +16,29 @@ import type { ThinkingLevel } from "../internal/harness-types.js";
 export type ReasoningIntensity = ThinkingLevel;
 /** Type guard: is `v` one of the 7 {@link ThinkingLevel} tiers? (A legacy/unknown reasoning string is not.) */
 export declare function isThinkingLevel(v: unknown): v is ThinkingLevel;
+/**
+ * THE thinking-request ENTRY predicate — does this request enter an applier's emission path at all?
+ * One conjunction, three arms: the model declares reasoning (TRUTHINESS — the adapters' own
+ * judgment, see the r5 note in {@link resolveReasoning}), the requested value is a real
+ * {@link ThinkingLevel} (an out-of-contract value — a typo'd tier, a caller's own enum — reads as
+ * ABSENCE, never as a declared tier), and it is not the explicit `"off"`.
+ *
+ * ENTRY gate, deliberately NOT an emitted-a-key guarantee: past this gate the per-FORMAT arms still
+ * decide what (if anything) lands on the wire — `supportsReasoningEffort:false` on a format whose
+ * only carrier is the effort key, a `null` levelmap entry, the binary enable keys. Those arms have
+ * their own reporting shape (the `graded:false` intent-echo family, each pinned with its rationale
+ * where it lives); this predicate only closes the gate the three appliers used to re-spell.
+ *
+ * Single-sourced here because every wire applier (openai.ts `applyThinking`, anthropic.ts's thinking
+ * + effort arms, open-responses.ts `resolveWireEffort`) used to re-spell the same three conjuncts —
+ * and the REPORTING resolver ({@link resolveReasoning}) mirrored only ONE of them (`!model.reasoning`),
+ * so a garbage tier put ZERO parameters on the wire while the resolution claimed a clamped-to-minimal
+ * gradient (or echoed the garbage string as `effective` on binary formats). A predicate the appliers
+ * and the reporter both call cannot drift.
+ */
+export declare function reasoningRequestCarried(model: {
+    reasoning?: boolean;
+}, reasoning: unknown): reasoning is ThinkingLevel;
 /** Ordinal rank of a level (`off`=0 … `max`=6). */
 export declare function rankOf(level: ThinkingLevel): number;
 /**
@@ -65,6 +88,66 @@ export interface ReasoningResolution {
     /** True when {@link effective} differs from {@link requested} (the request couldn't be honored exactly). */
     clamped: boolean;
 }
+/** Anthropic's hard floor for an extended-thinking budget. Lives HERE (not the anthropic brain) so
+ *  the cap-wins predicate below and the brain's budget-window math read ONE constant. */
+export declare const MIN_THINKING_TOKENS = 1024;
+/**
+ * The anthropic BUDGET path's cap-wins arm (#346, single-sourced; design/119 #2 review codex H4):
+ * a HARD per-request output cap (an engine-imposed override or the caller's explicit
+ * `options.maxTokens` — the two lanes the brain refuses to raise) too small to host a legal thinking
+ * budget (≥ {@link MIN_THINKING_TOKENS}) plus answer room means the CAP WINS and thinking is skipped
+ * for the request. Shared by the wire arm (anthropic.ts, which acts on it) and
+ * {@link resolveReasoning}'s budget arm (which mirrors it when the caller supplies the request
+ * facts), so the skip decision and its report are one predicate — the reporter's budget arm used to
+ * claim an unconditional `graded:true` gradient while this arm deleted the thinking block from the
+ * very request it described. A soft (model/config-sourced) cap never skips: the brain raises it to
+ * host the budget instead (`hardCap === false`).
+ */
+export declare function budgetCapSkipsThinking(outputCapTokens: number, hardCap: boolean): boolean;
+/**
+ * OPTIONAL per-request facts for {@link resolveReasoning} — what the wire's budget arm knows at
+ * request build that a per-leg eager resolution cannot: the resolved output cap and whether it is a
+ * HARD bound. Supplied ⇒ the anthropic budget arm mirrors the wire's cap-wins skip
+ * ({@link budgetCapSkipsThinking}); absent ⇒ the budget arm reports the cap-blind gradient it always
+ * did (the eager per-leg trace/result mint has no request facts — a capped request's per-attempt skip
+ * is visible only to a caller that passes them).
+ */
+export interface ReasoningWireFacts {
+    /** The request's resolved output cap (the wire `max_tokens` at the moment the thinking arm judges). */
+    outputCapTokens: number;
+    /** True when the cap is HARD (engine override / caller `options.maxTokens`) — the lanes the brain
+     *  refuses to raise; a soft model/config cap is raised to host the budget instead. */
+    hardOutputCap: boolean;
+}
+/**
+ * The anthropic-`effortLevels` PRESENCE/SHAPE gate, shared by the wire arm (anthropic.ts) and the
+ * reporting dispatch below so the two cannot disagree about which family a request rides (#335): the
+ * old twin predicates were `x && x.length > 0` on both sides, so a truthy NON-ARRAY (a string —
+ * `.length > 0` holds) entered the wire arm and threw a bare TypeError from its `.filter` pre-clean
+ * BEFORE {@link resolveEffort}'s centralized non-array fallback could read it as undeclared — while
+ * the reporter happily described an effort resolution for the same config. Only the container shape
+ * is judged here; MEMBER validity stays {@link resolveEffort}'s job (its element-level sanitization
+ * is the single bad-value seat, which is also why the returned array is not member-checked — the cast
+ * is checked at runtime by every consumer's `resolveEffort` call).
+ */
+export declare function declaredEffortLevels(v: unknown): readonly ThinkingLevel[] | undefined;
+/**
+ * The effort-lane WIRE-VALUE mint — clamp ({@link resolveEffort}) + the `Model.thinkingLevelMap`
+ * translation in ONE place, consumed by both completions-family appliers (openai.ts `applyThinking`,
+ * open-responses.ts `resolveWireEffort`) AND the reporting dispatch ({@link resolveReasoning}'s
+ * arms), so the value that reaches the wire and the resolution a trace/result face claims are two
+ * reads of one computation, never parallel re-derivations. Map semantics (the field's contract): a
+ * MISSING key ⇒ provider default (the clamped tier name as-is); a STRING ⇒ that provider-specific
+ * spelling (same tier, still honored); `null` ⇒ the tier is UNSUPPORTED on this model —
+ * `wireValue: undefined`, no effort value on the wire (thinking still enables via a format's own
+ * enable key where one exists), which is exactly the tier-not-honored shape the reporter must echo.
+ */
+export declare function mintEffortWireValue(requested: ThinkingLevel, model: {
+    thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
+}, allowed: readonly ThinkingLevel[] | undefined): {
+    resolution: ReasoningResolution;
+    wireValue: string | undefined;
+};
 /**
  * A {@link ReasoningResolution} enriched with the endpoint discriminant, for observability (design/96 S6).
  * The brain consumes only the {@link ReasoningResolution} fields to shape the request; `format`/`endpoint`
@@ -77,9 +160,12 @@ export interface ResolvedReasoning extends ReasoningResolution {
     /** A coarse endpoint label for the trace (`model.api` — e.g. `openai-completions`, `anthropic-messages`). */
     endpoint: string;
     /**
-     * Present (true) only when the model declares NO reasoning capability (`Model.reasoning` falsy): every
-     * brain early-returns on that flag (openai.ts applyThinking / anthropic.ts / open-responses.ts
-     * resolveWireEffort), so NO thinking
+     * Present (true) only when the request never CARRIES at all: {@link reasoningRequestCarried} false
+     * on a non-"off" request — the model declares NO reasoning capability (`Model.reasoning` falsy),
+     * OR the requested value is not a valid {@link ThinkingLevel} (an out-of-contract tier every wire
+     * applier reads as ABSENCE — the same three-conjunct gate all of them share) — or, with
+     * {@link ReasoningWireFacts} supplied, the anthropic budget path's cap-wins skip
+     * ({@link budgetCapSkipsThinking}), so NO thinking
      * parameter reaches the wire at all — the requested tier is DROPPED entirely, not clamped or
      * downgraded-to-binary. `effective:"off"` here states the ENGINE side of that fact (nothing was
      * requested), NOT a measured gateway state: on the binary enable-only formats (qwen / zai /
@@ -101,7 +187,10 @@ export interface ResolvedReasoning extends ReasoningResolution {
  * brains keep calling {@link resolveEffort}/{@link resolveBinary}/{@link reasoningBudgetShare} on the hot path.
  *
  * - Anthropic (`api === "anthropic-messages"`) → budget-based: the tier sets a budget share, so it's a real
- *   gradient (`graded:true`) and never tier-clamped (`clamped:false`); reported as `format:"budget"`.
+ *   gradient (`graded:true`) and never tier-clamped (`clamped:false`); reported as `format:"budget"`. With
+ *   the optional {@link ReasoningWireFacts} the arm additionally mirrors the wire's cap-wins skip
+ *   ({@link budgetCapSkipsThinking}: a hard per-request output cap < 2·{@link MIN_THINKING_TOKENS} deletes
+ *   the thinking block) as the drop shape — facts absent keeps the historic cap-blind gradient.
  * - Binary enable-only formats (qwen / zai / qwen-chat-template) → `graded:false` (tier not honored).
  * - An effort endpoint with `supportsReasoningEffort:false` → `graded:false` (enable key only, no effort tier).
  * - Otherwise effort-based → clamp DOWN to the endpoint's `reasoningEffortLevels` (default minimal|low|medium|high).
@@ -111,11 +200,14 @@ export interface ResolvedReasoning extends ReasoningResolution {
  *   honored. Previously this resolver never read the map and reported such a request as exactly honored
  *   (`graded:true`, `clamped:false`) while the wire dropped the value — trace/result-face drift.
  *
- * - A model whose `reasoning` capability flag is FALSY drops the request ENTIRELY (neither brain emits any
- *   thinking parameter, whatever the format) → `effective:"off"`, `graded:false`, `clamped:true`,
+ * - A request that never CARRIES ({@link reasoningRequestCarried} false on a non-"off" value: the model's
+ *   `reasoning` capability flag is FALSY, or the requested value is not a valid tier — no brain emits any
+ *   thinking parameter for either, whatever the format) → `effective:"off"`, `graded:false`, `clamped:true`,
  *   `dropped:true` — the loud-drop arm. Previously this resolver described the capability dispatch for such
  *   a model (a resolution the request never carried), and the runner's trace guard skipped the frame — the
- *   one arm where the request evaporates was the one arm with no disclosure.
+ *   one arm where the request evaporates was the one arm with no disclosure; and an out-of-contract tier
+ *   was worse still — reported as a clamped-to-minimal gradient (or echoed verbatim as `effective` on the
+ *   binary formats) while the wire carried nothing.
  *
  * `off`/falsy never enables thinking, so it resolves trivially (no clamp, graded:true) — the caller decides
  * whether to emit at all.
@@ -125,7 +217,7 @@ export declare function resolveReasoning(requested: ThinkingLevel, model: {
     reasoning?: boolean;
     compat?: unknown;
     thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
-}): ResolvedReasoning;
+}, facts?: ReasoningWireFacts): ResolvedReasoning;
 /**
  * Resolve a requested intensity for an effort-based endpoint (`reasoning_effort` / `reasoning.effort`). Picks
  * the requested tier when supported; otherwise the highest supported tier ≤ requested (clamp DOWN, never

package/dist/brain/reasoning.js

@@ -10,28 +10,52 @@ const RANK = {
 export function isThinkingLevel(v) {
     return typeof v === "string" && Object.prototype.hasOwnProperty.call(RANK, v);
 }
+export function reasoningRequestCarried(model, reasoning) {
+    return !!model.reasoning && isThinkingLevel(reasoning) && reasoning !== "off";
+}
 export function rankOf(level) {
     return RANK[level];
 }
 export const DEFAULT_EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
 const BINARY_FORMATS = new Set(["qwen", "zai", "qwen-chat-template"]);
 export const RESPONSES_APIS = new Set(["openai-responses", "azure-openai-responses", "openai-chatgpt-responses"]);
-export function resolveReasoning(requested, model) {
-    const resolved = dispatchReasoning(requested, model);
-    if (requested !== "off" && !model.reasoning) {
+export const MIN_THINKING_TOKENS = 1024;
+export function budgetCapSkipsThinking(outputCapTokens, hardCap) {
+    return hardCap && outputCapTokens < MIN_THINKING_TOKENS * 2;
+}
+export function declaredEffortLevels(v) {
+    return Array.isArray(v) && v.length > 0 ? v : undefined;
+}
+export function mintEffortWireValue(requested, model, allowed) {
+    const resolution = resolveEffort(requested, allowed ?? DEFAULT_EFFORT_LEVELS);
+    let wireValue = resolution.effective;
+    const mapped = model.thinkingLevelMap?.[resolution.effective];
+    if (mapped === null)
+        wireValue = undefined;
+    else if (mapped !== undefined)
+        wireValue = mapped;
+    return { resolution, wireValue };
+}
+export function resolveReasoning(requested, model, facts) {
+    const resolved = dispatchReasoning(requested, model, facts);
+    if (requested !== "off" && !reasoningRequestCarried(model, requested)) {
         return { requested, effective: "off", graded: false, clamped: true, format: resolved.format, endpoint: resolved.endpoint, dropped: true };
     }
     return resolved;
 }
-function effortTierUnmapped(requested, effective, model) {
-    return requested !== "off" && model.thinkingLevelMap?.[effective] === null;
-}
-function dispatchReasoning(requested, model) {
+function dispatchReasoning(requested, model, facts) {
     const endpoint = model.api ?? "unknown";
     const compat = (model.compat ?? {});
     if (model.api === "anthropic-messages") {
-        if (compat.effortLevels && compat.effortLevels.length > 0) {
-            return { ...resolveEffort(requested, compat.effortLevels), format: "effort", endpoint };
+        const declaredAnthropic = declaredEffortLevels(compat.effortLevels);
+        if (declaredAnthropic !== undefined) {
+            return { ...resolveEffort(requested, declaredAnthropic), format: "effort", endpoint };
+        }
+        if (requested !== "off" &&
+            compat.thinkingMode !== "adaptive" &&
+            facts !== undefined &&
+            budgetCapSkipsThinking(facts.outputCapTokens, facts.hardOutputCap)) {
+            return { requested, effective: "off", graded: false, clamped: true, format: "budget", endpoint, dropped: true };
         }
         return { requested, effective: requested, graded: true, clamped: false, format: "budget", endpoint };
     }
@@ -39,11 +63,11 @@ function dispatchReasoning(requested, model) {
         if (compat.supportsReasoningEffort === false) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        const responsesResolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-        if (effortTierUnmapped(requested, responsesResolved.effective, model)) {
+        const responsesMint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+        if (requested !== "off" && responsesMint.wireValue === undefined) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        return { ...responsesResolved, format: "responses", endpoint };
+        return { ...responsesMint.resolution, format: "responses", endpoint };
     }
     const format = compat.thinkingFormat ?? "openai";
     if (BINARY_FORMATS.has(format)) {
@@ -53,11 +77,11 @@ function dispatchReasoning(requested, model) {
     if (!supportsEffort && format !== "openrouter") {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    const resolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-    if (effortTierUnmapped(requested, resolved.effective, model)) {
+    const mint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+    if (requested !== "off" && mint.wireValue === undefined) {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    return { ...resolved, format, endpoint };
+    return { ...mint.resolution, format, endpoint };
 }
 export function resolveEffort(requested, allowed = DEFAULT_EFFORT_LEVELS) {
     const declared = Array.isArray(allowed) ? allowed.filter((lvl) => isThinkingLevel(lvl) && lvl !== "off") : [];

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

@@ -23,7 +23,7 @@ export declare function reservedFor(api: string): ReadonlySet<string>;
  */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
 /**
- * [1282] per-call auth REPLACES construction-time auth: drop every auth-bearing header
+ * 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
@@ -33,6 +33,42 @@ export declare function applyExtraBody(body: Record<string, unknown>, extraBody:
  * folds duplicates into one comma-joined value — broken auth both ways).
  */
 export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/**
+ * #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
+ * case-insensitive (RFC 9110), but the plain-object spread the three brains used
+ * (`{...model.headers, ...config.headers, ...options.headers}`) keyed by exact spelling — a
+ * `X-Tenant` in one bag and `x-tenant` in another BOTH survived and both went on the wire, where
+ * fetch's Headers folds them into one comma-joined value ("a, b"): neither writer's value, and the
+ * later layer's documented override silently defeated. Now a later bag's entry replaces an earlier
+ * case-variant; the WINNER'S spelling and value survive (a single-spelling config — every existing
+ * 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) — their case handling is
+ * {@link stripAuthHeaders}' pinned jurisdiction (the per-call-replaces flow and the
+ * header-only ANTHROPIC_AUTH_TOKEN shape, which must survive under its own capital-A spelling), and
+ * this layer must not become a second, subtly different auth authority.
+ */
+/**
+ * #343 (review r4) — assign a STRUCTURAL locked header under its canonical lowercase name, deleting
+ * every case-variant spelling first. The brains hard-lock `content-type` / `anthropic-version` AFTER
+ * 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).
+ */
+export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
+/**
+ * #343 (review r4) — case-fold READ-AND-CLAIM for an AUGMENTABLE structural header (`anthropic-beta`):
+ * returns the current value under whatever spelling the user bag carried and deletes that spelling,
+ * so the caller's canonical lowercase write REPLACES it instead of duplicating beside it (the
+ * read-modify-write used to key the read by the exact lowercase name and miss `Anthropic-Beta`,
+ * losing the user's betas from the merge AND double-sending the header).
+ */
+export declare function takeHeaderCasefold(headers: Record<string, string>, lowerName: string): string | undefined;
+export declare function mergeHeaders(...bags: Array<Record<string, string> | undefined>): Record<string, string>;
 /**
  * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's
  * endpoint reads — a stray cap key belonging to another wire form is inert there and must not be

package/dist/brain/request-params.js

@@ -54,13 +54,51 @@ 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)) {
-        const lower = k.toLowerCase();
-        if (lower === "authorization" || lower === "x-api-key")
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
             delete headers[k];
     }
 }
+export function lockHeader(headers, lowerName, value) {
+    for (const k of Object.keys(headers)) {
+        if (k !== lowerName && k.toLowerCase() === lowerName)
+            delete headers[k];
+    }
+    headers[lowerName] = value;
+}
+export function takeHeaderCasefold(headers, lowerName) {
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === lowerName) {
+            const v = headers[k];
+            delete headers[k];
+            return v;
+        }
+    }
+    return undefined;
+}
+export function mergeHeaders(...bags) {
+    const out = {};
+    const spellingByFold = new Map();
+    for (const bag of bags) {
+        if (!bag)
+            continue;
+        for (const [name, value] of Object.entries(bag)) {
+            const fold = name.toLowerCase();
+            if (AUTH_CARRIER_NAMES.has(fold)) {
+                out[name] = value;
+                continue;
+            }
+            const prior = spellingByFold.get(fold);
+            if (prior !== undefined && prior !== name)
+                delete out[prior];
+            spellingByFold.set(fold, name);
+            out[name] = value;
+        }
+    }
+    return out;
+}
 export const OUTPUT_CAP_KEYS = {
     openai: ["max_tokens", "max_completion_tokens"],
     anthropic: ["max_tokens"],

package/dist/core/background-agent-store.d.ts

@@ -170,7 +170,7 @@ export interface BackgroundAgentRecord {
 export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
 /** Erase {@link REVIVED_ROW_CLEARED_FIELDS} from a record a revival is about to write back. */
 export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRecord): void;
-export declare function announceTranscriptIntegrityGapOnce(handle: string, sink: ((handle: string) => void) | undefined): void;
+export declare function announceTranscriptIntegrityGapOnce(handle: string, scope: string | undefined, sink: ((handle: string, scope: string | undefined) => void) | undefined): void;
 /** Content-free projection for list reads (design/151 HIGH-1: `summary`/`finalOutput`/`recentSteps`
  *  and friends NEVER ride a list — content is get-by-handle only, behind the full predicate). */
 export interface BackgroundAgentRowSummary {

package/dist/core/background-agent-store.js

@@ -22,14 +22,15 @@ export function clearRevivedRowTerminalPayload(record) {
         delete record[field];
 }
 const transcriptIntegrityAnnounced = new Set();
-export function announceTranscriptIntegrityGapOnce(handle, sink) {
+export function announceTranscriptIntegrityGapOnce(handle, scope, sink) {
     if (sink === undefined)
         return;
-    if (transcriptIntegrityAnnounced.has(handle))
+    const key = `${scope ?? ""}\u0000${handle}`;
+    if (transcriptIntegrityAnnounced.has(key))
         return;
-    transcriptIntegrityAnnounced.add(handle);
+    transcriptIntegrityAnnounced.add(key);
     try {
-        sink(handle);
+        sink(handle, scope);
     }
     catch {
     }

package/dist/core/mcp.d.ts

@@ -193,7 +193,10 @@ export interface McpRefreshResult {
      *  DOMAIN for the swap (review F4: a prefix domain is self-healing and decoupled from the diff
      *  baseline, which advances even when a consumer skips a swap). Present on every entry. */
     prefix: string;
-    status: "refreshed" | "not_connected" | "failed";
+    /** `"revoked"` (design/338): the host ledger marks this server revoked — the refresh did NOT
+     *  contact it (no tools/list round trip; the engine must not hand a severed server a request
+     *  channel or splice its post-revocation text into the model catalog). */
+    status: "refreshed" | "not_connected" | "failed" | "revoked";
     toolCount: number;
     added: string[];
     removed: string[];
@@ -467,6 +470,9 @@ export declare function materializeMcpTools(specs: McpServerSpec[], principal?:
 reminderDisclosure?: {
     reminderMark?: string;
     counts?: ReminderDisclosureCounts;
+}, mcpRevocations?: {
+    isRevoked(serverName: string): boolean;
+    onProbeFailure?: (error: unknown) => void;
 }): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.