@sema-agent/core 5.49.0 → 5.50.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 5.50.0 — 2026-08-21
+
+### Added
+- **`RunnerDeps.mcpRevocations`** (design/338, the #322 batch-3 hook — mid-turn MCP revocation):
+  the host's revocation ledger, probed synchronously at every MCP dispatch (tool call + the three
+  resource tools) BEFORE the transport. A revoked server's call settles as the coded refusal
+  `mcp.server_revoked` with known-not-executed wording; the ledger is live (revoke/un-revoke take
+  effect on the very next call, no engine-side caching); a throwing probe fails OPEN with a
+  once-per-run `mcp.revocation_probe_failed` notice. Absent seat = pre-338 semantics.
+- **Machine-readable refusal codes on the wire**: `delegation.concurrency_cap`,
+  `delegation.session_cap` and `mcp.server_revoked` now carry a `details.code` twin beside
+  `details.error` (same value; the wire errorCode lift reads `code`) — tool_end frames for these
+  refusals become classifiable. `HarvestRejectionCode` gains `"deferred"` (additive).
+- Conformance clauses **31 → 34**: the hold×applyPatches protocol (hold-unaware plain write /
+  release-replay CAS conflict carrying currentRev / snapshot faces tracking the post-UPDATE tuple)
+  and the whitewash-precedence UPDATE spelling. `MemorySessionHandle` gains a keyset gate
+  (machine face for consumer obligations).
+
+### Fixed
+- **Workflow mount batch** (merged-scan FAM-3): a generic own-nullish merger
+  (`overlayWorktreeBaseline`) replaces the per-key drop list — an overlay's own-undefined keys no
+  longer erase base governance (excludeTools/deferTools/toolPolicy/shellGate/…); new keys are safe
+  by construction (`checkpointStore: null` is the one registered exception). Host tighten-only
+  clamps (`handsReadOnly:true` / `interactiveTools:false`) now ride into workflow children at the
+  same injection point as the read-face clamp — a clamped host's workflow child can no longer
+  unclamp itself.
+- **Brain effort batch** (FAM-4): the effective-reasoning verdict is minted at the single point
+  that writes the wire and echoed back (three single-sources: the carried predicate, the wire
+  value mint, the declared-levels shape gate) — a garbled tier (`thinking:"hgih"`) now reports the
+  same fact the wire shows instead of a clamped-to-minimal or echo-garbage lie; the anthropic
+  budget arm reports its cap-wins drop; truthy non-array effortLevels no longer throw at request
+  construction. Per-call headers are case-fold deduplicated (`X-Tenant` + `x-tenant` no longer
+  ride the wire as two entries; auth carriers exempt as pinned).
+- **Memory projection write-back debt** (#366 root fix): a committed entry whose id write-back to
+  the projection file failed is now a durable DEBT row (`projection-debts.json`, write-ahead
+  staged across all four mint lanes) — the next harvest validates and re-binds the id-less file to
+  its committed identity instead of re-adopting it as a duplicate; stale rows drop, unvalidatable
+  rows defer fail-closed. The old silent swallow is loud in both directions.
+- The durable reap drops the stale terminal in-process handle after a winning row delete (#361) —
+  inside the reap-to-restart window a same-process SendMessage answered the pre-deletion "not
+  retained" text while a fresh process answered the honest no-transcript form.
+- Delegation entry ledgers get a lifecycle (reap anchor + amortized sweep) — one Map entry per
+  (scope, rootSessionId) no longer accumulates for the life of the process.
+
+### Notes
+- Conformance 31→34 is a tightening for backend implementers (a hold-unaware backend fails the
+  new cases; upgrade-order duty as before). Everything else is additive or a narrowing inside
+  existing coded families; no BREAKING changes.
+
 ## 5.49.0 — 2026-08-20
 
 ### Added

package/dist/agents/roster-store.js

@@ -110,7 +110,10 @@ export class FileRosterStore {
         if (text.trim() === "")
             return [];
         try {
-            const raw = JSON.parse(text);
+            const rawU = JSON.parse(text);
+            if (typeof rawU !== "object" || rawU === null)
+                throw new Error("roster file: not a JSON object");
+            const raw = rawU;
             if (!Array.isArray(raw.entries))
                 throw new Error("roster file: entries is not an array");
             const kept = raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");

package/dist/agents/subagent.d.ts

@@ -484,6 +484,12 @@ export declare function resolveDelegationEntryCaps(caps: {
     maxConcurrent?: number;
     maxCumulativePerSession?: number;
 } | undefined): ResolvedDelegationEntryCaps;
+/** @internal — observability seam for the lifecycle pins (tests only; never a public surface):
+ *  the ledger footprint of one registry. */
+export declare function delegationEntryLedgerFootprint(registry: object): {
+    keys: number;
+    handles: number;
+};
 /**
  * Options for {@link createSubagentTool}.
  *

package/dist/agents/subagent.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
+import { errorResult } from "../core/tools.js";
 import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
 import { registerDelegationLaunch, replayExternalSettlementEffects, settleDelegation } from "../core/memory-engine/delegation-settlement.js";
@@ -912,6 +913,125 @@ function delegationEntryLedger(registry, key) {
     }
     return set;
 }
+const delegationLedgerLifecycles = new WeakMap();
+const delegationLedgerKeyStores = new WeakMap();
+function bindDelegationLedgerKeyStore(registry, key, store) {
+    let byKey = delegationLedgerKeyStores.get(registry);
+    if (byKey === undefined) {
+        byKey = new Map();
+        delegationLedgerKeyStores.set(registry, byKey);
+    }
+    if (byKey.get(key) === null)
+        return;
+    byKey.set(key, store ?? null);
+}
+async function sweepDelegationEntryLedgerKeys(registry, keys) {
+    const byKey = delegationEntryLedgers.get(registry);
+    if (byKey === undefined)
+        return;
+    const keyStores = delegationLedgerKeyStores.get(registry);
+    const activeFace = registry.activeDelegationHandles;
+    if (typeof activeFace !== "function")
+        return;
+    for (const key of keys) {
+        const set = byKey.get(key);
+        if (set === undefined)
+            continue;
+        const store = keyStores?.get(key);
+        if (store === undefined || store === null)
+            continue;
+        let scopeK;
+        let rootK;
+        try {
+            const parsed = JSON.parse(key);
+            if (!Array.isArray(parsed) || typeof parsed[0] !== "string" || typeof parsed[1] !== "string")
+                continue;
+            scopeK = parsed[0];
+            rootK = parsed[1];
+        }
+        catch {
+            continue;
+        }
+        if (activeFace.call(registry, scopeK, rootK).length > 0)
+            continue;
+        const sizeBefore = set.size;
+        let stored;
+        try {
+            stored = (await store.listBySession(scopeK, rootK)).map((r) => r.handle);
+        }
+        catch {
+            continue;
+        }
+        if (byKey.get(key) !== set || set.size !== sizeBefore || activeFace.call(registry, scopeK, rootK).length > 0)
+            continue;
+        if (stored.length === 0) {
+            byKey.delete(key);
+            keyStores?.delete(key);
+            continue;
+        }
+        const keep = new Set(stored);
+        for (const h of [...set])
+            if (!keep.has(h))
+                set.delete(h);
+        if (set.size === 0) {
+            byKey.delete(key);
+            keyStores?.delete(key);
+        }
+    }
+}
+function armDelegationLedgerLifecycle(registry) {
+    let life = delegationLedgerLifecycles.get(registry);
+    if (life === undefined) {
+        life = { cursor: 0, subscribed: false };
+        delegationLedgerLifecycles.set(registry, life);
+    }
+    if (life.subscribed)
+        return;
+    const reapFace = registry.onSessionReap;
+    if (typeof reapFace !== "function")
+        return;
+    life.subscribed = true;
+    reapFace.call(registry, (sessionId, scope) => {
+        const byKey = delegationEntryLedgers.get(registry);
+        if (byKey === undefined)
+            return;
+        const keys = [...byKey.keys()].filter((k) => {
+            try {
+                const parsed = JSON.parse(k);
+                if (!Array.isArray(parsed) || typeof parsed[0] !== "string" || typeof parsed[1] !== "string")
+                    return false;
+                return parsed[1] === sessionId && (scope === undefined || parsed[0] === scope);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (keys.length > 0)
+            void sweepDelegationEntryLedgerKeys(registry, keys).catch(() => undefined);
+    });
+}
+function sweepDelegationLedgerRound(registry, n) {
+    const life = delegationLedgerLifecycles.get(registry);
+    const byKey = delegationEntryLedgers.get(registry);
+    if (life === undefined || byKey === undefined || byKey.size === 0)
+        return;
+    const keys = [...byKey.keys()];
+    const start = life.cursor % keys.length;
+    const slice = [];
+    for (let i = 0; i < Math.min(n, keys.length); i++)
+        slice.push(keys[(start + i) % keys.length]);
+    life.cursor = (start + slice.length) % keys.length;
+    void sweepDelegationEntryLedgerKeys(registry, slice).catch(() => undefined);
+}
+export function delegationEntryLedgerFootprint(registry) {
+    const byKey = delegationEntryLedgers.get(registry);
+    if (byKey === undefined)
+        return { keys: 0, handles: 0 };
+    let handles = 0;
+    for (const s of byKey.values())
+        handles += s.size;
+    return { keys: byKey.size, handles };
+}
 export function normalizeSubagentType(value) {
     return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
 }
@@ -2491,7 +2611,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         await cancelObserver();
                         const wt = await finishWorktree();
-                        return { isError: true, content: `Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, details: { error: code } };
+                        return errorResult(`Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, { error: code, code });
                     };
                     const activeFace = bg.registry.activeDelegationHandles;
                     const active = typeof activeFace === "function" ? activeFace.call(bg.registry, capScope, capRoot) : [];
@@ -2640,6 +2760,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 if (capLedgerKey !== undefined && reviveRow === undefined)
                     delegationEntryLedger(bg.registry, capLedgerKey).add(taskId);
+                if (capLedgerKey !== undefined) {
+                    bindDelegationLedgerKeyStore(bg.registry, capLedgerKey, bg.agentStore);
+                    armDelegationLedgerLifecycle(bg.registry);
+                    sweepDelegationLedgerRound(bg.registry, 3);
+                }
                 childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
                     recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));

package/dist/agents/teacher.js

@@ -31,7 +31,10 @@ export function parseTeacherAdvice(text) {
     const end = text.lastIndexOf("}");
     if (start !== -1 && end > start) {
         try {
-            const o = JSON.parse(text.slice(start, end + 1));
+            const oU = JSON.parse(text.slice(start, end + 1));
+            if (typeof oU !== "object" || oU === null)
+                throw new Error("not an object");
+            const o = oU;
             return {
                 strategy: typeof o.strategy === "string" ? o.strategy : undefined,
                 correction: typeof o.correction === "string" ? o.correction : undefined,

package/dist/brain/anthropic.js

@@ -5,10 +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, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
-import { isThinkingLevel, reasoningBudgetShare, resolveEffort } from "./reasoning.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders, takeHeaderCasefold } from "./request-params.js";
+import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
-const MIN_THINKING_TOKENS = 1024;
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
     const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
     const want = fixed ?? Math.floor(max * share);
@@ -261,13 +260,13 @@ export function createAnthropicBrain(config = {}) {
                 if (options?.temperature !== undefined && anthCompat.supportsTemperature !== false) {
                     body.temperature = options.temperature;
                 }
-                if (model.reasoning && isThinkingLevel(options?.reasoning) && options.reasoning !== "off") {
+                if (reasoningRequestCarried(model, options?.reasoning)) {
                     if (anthCompat.thinkingMode === "adaptive") {
                         body.thinking = { type: "adaptive" };
                     }
                     else {
                         const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
-                        if (hardCap && body.max_tokens < MIN_THINKING_TOKENS * 2) {
+                        if (budgetCapSkipsThinking(body.max_tokens, hardCap)) {
                             body.thinking = undefined;
                             delete body.thinking;
                         }
@@ -283,13 +282,9 @@ export function createAnthropicBrain(config = {}) {
                 }
                 const betas = [];
                 let sendEffortBeta = false;
-                if (anthCompat.effortLevels &&
-                    anthCompat.effortLevels.length > 0 &&
-                    model.reasoning &&
-                    options?.reasoning &&
-                    options.reasoning !== "off" &&
-                    isThinkingLevel(options.reasoning)) {
-                    const { effective } = resolveEffort(options.reasoning, anthCompat.effortLevels.filter(isThinkingLevel));
+                const declaredEffort = declaredEffortLevels(anthCompat.effortLevels);
+                if (declaredEffort !== undefined && reasoningRequestCarried(model, options?.reasoning)) {
+                    const { effective } = resolveEffort(options.reasoning, declaredEffort);
                     const wireEffort = effective === "minimal" ? "low" : effective;
                     body.output_config = { effort: wireEffort };
                     sendEffortBeta = true;
@@ -303,23 +298,19 @@ export function createAnthropicBrain(config = {}) {
                 if (anthCompat.interleavedThinking) {
                     betas.push("interleaved-thinking-2025-05-14");
                 }
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
                 if (betas.length > 0) {
-                    const existing = (headers["anthropic-beta"] ?? "").split(",").map((b) => b.trim()).filter(Boolean);
+                    const existing = (takeHeaderCasefold(headers, "anthropic-beta") ?? "").split(",").map((b) => b.trim()).filter(Boolean);
                     for (const beta of betas) {
                         if (!existing.includes(beta))
                             existing.push(beta);
                     }
                     headers["anthropic-beta"] = existing.join(",");
                 }
-                headers["content-type"] = "application/json";
-                headers["anthropic-version"] = config.version ?? "2023-06-01";
+                lockHeader(headers, "content-type", "application/json");
+                lockHeader(headers, "anthropic-version", config.version ?? "2023-06-01");
                 if (apiKey)
                     headers["x-api-key"] = apiKey;
                 const builtThinkingRequested = body.thinking !== undefined;

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