@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/mcp.js

@@ -2,15 +2,18 @@ import { egressText } from "./untrusted-egress.js";
 import { __resetEnvKnobAnnouncements } from "./env-knob-announce.js";
 import { resolveEnvBudget } from "./env-budget.js";
 import { MCP_NAMESPACE } from "./protocol-table.js";
-import { resolveProtocolHttpHeaders } from "./protocol-http-auth.js";
+import { declaredHeaderValues, resolveProtocolHttpHeaders, scrubRequestEcho } from "./protocol-http-auth.js";
 import { disposeSectionEntry, sectionAnswerWarning } from "./prompt-section-seat.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { McpConnectionPool } from "./mcp-connection-pool.js";
+import { SessionEndingTransport, requestSite } from "./mcp-session-end.js";
+import { mcpToolGate, UNPROVEN_GATE } from "./mcp-listing-drift.js";
+import { ConnectionListing, Flights, IDLE_WATCHDOG_ABORT_REASON, Resendable, armMcpIdleWatchdog, callThroughLink, listingRefusal } from "./mcp-server-link.js";
+import { underStartupBound } from "./mcp-startup-request.js";
 import { LIST_MCP_RESOURCES, MCP_RESOURCE_LIST_ALLOW, MCP_RESOURCE_READ_ALLOW, READ_MCP_RESOURCE, READ_MCP_RESOURCE_DIR, retractInstructions, tellInstructions, toldOnDial, unretractInstructions, withdrawInstructionAdds } from "./mounted-mcp.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { classifyMcpFailure, describeHttpTransportFailure, livenessOf } from "./mcp-failure.js";
+import { classifyMcpFailure, describeHttpTransportFailure, livenessOf, namingLostSession, sessionGone } from "./mcp-failure.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -19,6 +22,7 @@ import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/p
 import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { sliceHeadSafe, sliceTailSafe } from "./surrogate-safe-slice.js";
 import { truncateError } from "./tool-errors.js";
+import { peerRequestRefusal } from "./host-floor.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { discloseReminderShaped, observeReminderMarkEcho } from "./reminder-disclosure.js";
 import { MARKED_BLOCK_AFTER_DATA } from "./reminder-mint.js";
@@ -128,33 +132,6 @@ export function mcpIdleTimeoutMs(kind) {
 function idleKindOf(kind) {
     return kind === "stdio" ? "stdio" : "http";
 }
-const IDLE_WATCHDOG_ABORT_REASON = Symbol("mcp-idle-watchdog-abort");
-function armMcpIdleWatchdog(health, idleMs, outerSignal) {
-    const idleController = new AbortController();
-    let timer;
-    const rearm = () => {
-        if (timer !== undefined)
-            clearTimeout(timer);
-        const armedAt = Date.now();
-        timer = setTimeout(() => {
-            if (health.pendingElicitations > 0 || health.lastElicitationClosedAt > armedAt) {
-                rearm();
-                return;
-            }
-            idleController.abort(IDLE_WATCHDOG_ABORT_REASON);
-        }, idleMs);
-    };
-    rearm();
-    return {
-        combinedSignal: outerSignal !== undefined ? AbortSignal.any([outerSignal, idleController.signal]) : idleController.signal,
-        idleSignal: idleController.signal,
-        rearm,
-        dispose: () => {
-            if (timer !== undefined)
-                clearTimeout(timer);
-        },
-    };
-}
 export function mcpStartupTimeoutMs(server) {
     const fromEnv = parseEnvMs("MCP_TIMEOUT");
     const own = server?.startupTimeoutMs;
@@ -185,21 +162,24 @@ export function collapseMcpErrorPrefix(message) {
         out = out.slice(m[0].length);
     }
 }
-function sanitizeMcpErrorTextInPlace(err) {
+function sanitizeMcpErrorTextInPlace(err, declared) {
     if (!(err instanceof Error))
         return;
-    const sanitized = egressText("same-principal", err instanceof McpError ? collapseMcpErrorPrefix(err.message) : err.message);
+    const sanitized = mcpRemoteText(err instanceof McpError ? collapseMcpErrorPrefix(err.message) : err.message, declared);
     if (sanitized !== err.message)
         err.message = sanitized;
 }
-function namedMcpFailureText(err) {
-    const detail = remoteErrorText(err, { collapse: true });
+function namedMcpFailureText(err, declared) {
+    const detail = remoteErrorText(err, declared, { collapse: true });
     const condition = thrownIs(err, McpError) ? describeMcpSpecErrorCode(readMember(err, "code")) : undefined;
     return condition !== undefined ? `${condition}: ${detail}` : detail;
 }
-function remoteErrorText(err, opts) {
+function remoteErrorText(err, declared, opts) {
     const raw = thrownText(err);
-    return egressText("same-principal", opts?.collapse === true ? collapseMcpErrorPrefix(raw) : raw);
+    return mcpRemoteText(opts?.collapse === true ? collapseMcpErrorPrefix(raw) : raw, declared);
+}
+function mcpRemoteText(text, declared) {
+    return egressText("same-principal", scrubRequestEcho(text, declared));
 }
 function writeEffectWarning(writeEffect) {
     return writeEffect
@@ -218,7 +198,7 @@ function rethrowHonestMcpError(err, ctx) {
         }
         throw e;
     };
-    sanitizeMcpErrorTextInPlace(err);
+    sanitizeMcpErrorTextInPlace(err, ctx.declared);
     if (ctx.idle?.signal.reason === IDLE_WATCHDOG_ABORT_REASON) {
         ctx.liveness?.observe?.("timeout");
         const serverLabel = inlineUntrusted(ctx.server);
@@ -231,7 +211,7 @@ function rethrowHonestMcpError(err, ctx) {
         finish(err);
     const serverLabel = inlineUntrusted(ctx.server);
     const fenceServerText = (label, raw) => delimitUntrusted(label, truncateMcpErrorText(raw));
-    const failure = classifyMcpFailure(err, { phase: "request" });
+    const failure = classifyMcpFailure(err, ctx.site);
     ctx.liveness?.observe?.(failure.kind);
     const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...extra });
     switch (failure.kind) {
@@ -248,12 +228,14 @@ function rethrowHonestMcpError(err, ctx) {
         case "not_mcp_response":
         case "connect_refused":
         case "connection_failed": {
-            const httpFailure = describeHttpTransportFailure(err);
-            const detail = remoteErrorText(err);
+            const httpFailure = describeHttpTransportFailure(err, ctx.site);
+            const detail = remoteErrorText(err, ctx.declared);
             const fenced = `\nThe transport error follows as external/untrusted data:\n${fenceServerText(`${ctx.server} transport error`, detail)}`;
-            finish(markMcpFailure(new Error(failure.delivered === "no"
-                ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
-                : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err }), details(failure.httpStatus !== undefined ? { httpStatus: failure.httpStatus } : undefined)));
+            finish(markMcpFailure(new Error(sessionGone(err, ctx.site)
+                ? `${ctx.what} met a lost session on MCP server "${serverLabel}": ${httpFailure.condition}; ${ctx.resent === true ? "the call was sent again once on a fresh session, and the server reported that one gone too — if the server executed it before answering, it ran twice" : "the call was not sent again — if the server executed it before answering, it ran"}. The outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`
+                : failure.delivered === "no"
+                    ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
+                    : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err }), details(failure.httpStatus !== undefined ? { httpStatus: failure.httpStatus } : undefined)));
         }
         case "protocol": {
             const code = err.code;
@@ -262,7 +244,7 @@ function rethrowHonestMcpError(err, ctx) {
                 finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${code} — ${condition}. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, err.message)}`, { cause: err }), details({ specErrorCode: code })));
             }
             if (ctx.attributeServer) {
-                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err, ctx.declared))}`, { cause: err }), details()));
             }
             finish(markMcpFailure(err, details()));
         }
@@ -270,7 +252,7 @@ function rethrowHonestMcpError(err, ctx) {
         case "invalid_config":
         case "unknown": {
             if (ctx.attributeServer) {
-                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err, ctx.declared))}`, { cause: err }), details()));
             }
             if (err instanceof Error)
                 finish(markMcpFailure(err, details()));
@@ -396,7 +378,7 @@ function buildTransport(spec, principal, kind) {
     if (!("url" in t))
         throw new Error(`MCP server "${spec.name}": transport kind "${String(kind)}" carries no url`);
     const headers = resolveProtocolHttpHeaders(MCP_NAMESPACE.id, t, principal);
-    return new StreamableHTTPClientTransport(new URL(t.url), {
+    return new SessionEndingTransport(new URL(t.url), {
         requestInit: headers ? { headers } : undefined,
         fetch: declaredEndpointFetch,
     });
@@ -663,7 +645,7 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable) {
+export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal, hostFloor) {
     const snapshot = snapshotMcpEntries(specs);
     const axesRefused = new WeakMap();
     const entries = snapshot.map((spec) => {
@@ -722,11 +704,10 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const droppedTools = [];
     let disposing = false;
     const serverHandles = [];
-    const redialsInFlight = new Set();
     const commitConnectedServer = (spec, s, transportKind) => {
         const raised = [];
         connections.push({ client: s.client, close: s.close });
-        const handle = { name: spec.name, spec, client: s.client, openListing: s.openListing, health: s.health, tools: s.tools, listedRaw: s.listedTools, transportKind, announce: s.announce, instructions: s.instructions };
+        const handle = { name: spec.name, spec, client: s.client, openListing: s.openListing, health: s.health, tools: s.tools, listing: s.listing, gatesAt: s.gatesAt, gates: () => gatesNow(handle), transportKind, announce: s.announce, instructions: s.instructions };
         const hIdx = serverHandles.findIndex((h) => h.name === spec.name);
         if (hIdx === -1)
             serverHandles.push(handle);
@@ -786,11 +767,37 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         }
     };
     const dialKinds = entries.map(readDialKind);
+    const liveOf = (server) => serverHandles.find((h) => h.name === server);
+    const gatesNow = (h) => {
+        const latest = h.listing.latest();
+        if (latest.at !== h.gatesAt.at)
+            h.gatesAt = { at: latest.at, gates: intakeListedTools({ tools: [...latest.entries], unproven: latest.unproven }, h.spec, linkOf(h.name), echoOf(h.spec), imageResizer, mcpDisclosure, isServerRevoked, h.transportKind).gates };
+        return h.gatesAt.gates;
+    };
+    const linkOf = (server) => ({
+        live: () => liveOf(server),
+        recover: (lost) => redialFlights.running(server) ?? (liveOf(server) === lost ? redialFlights.start(server, () => redialDial(server)) : Promise.resolve()),
+    });
+    const endpointRefusal = (spec, dialKind) => {
+        const transport = spec.transport;
+        const raw = dialKind !== "stdio" && typeof transport === "object" && transport !== null && "url" in transport ? transport.url : undefined;
+        let url;
+        try {
+            if (typeof raw !== "string")
+                return undefined;
+            url = new URL(raw);
+        }
+        catch {
+            return undefined;
+        }
+        return peerRequestRefusal(`mcp: server "${inlineUntrusted(spec.name, 120)}"`, url, hostFloor);
+    };
     const dialServer = (spec, dialKind, dialOpts) => {
-        const refusal = axesRefused.get(spec);
-        return refusal !== undefined ? Promise.reject(refusal) : connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, dialOpts);
+        const refusal = axesRefused.get(spec) ?? endpointRefusal(spec, dialKind);
+        return refusal !== undefined ? Promise.reject(refusal) : connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, { ...dialOpts, link: linkOf(spec.name), ...(signal !== undefined ? { signal } : {}) });
     };
     const prefixOf = (name) => mintNamespacePrefix(MCP_NAMESPACE, name);
+    const echoOf = (spec) => declaredHeaderValues(spec.transport, principal);
     const heldCount = (name) => serverHandles.find((h) => h.name === name)?.tools.length ?? 0;
     const reconcileInstructions = (name, after, connected) => {
         if (!connected)
@@ -820,10 +827,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 commitConnectedServer(spec, s, dialKinds[i]);
             }
             else {
-                warnings.push(asServerWarning(spec, r.reason));
+                const declared = echoOf(spec);
+                warnings.push(asServerWarning(spec, r.reason, declared));
                 const { kind, delivered, httpStatus } = classifyMcpFailure(r.reason, { phase: "connect", transport: dialKinds[i] });
                 const liveness = livenessOf(kind, Date.now());
-                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason), ...(liveness !== undefined ? { liveness } : {}) });
+                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason, declared), ...(liveness !== undefined ? { liveness } : {}) });
             }
         }
         const resourceTools = buildResourceTools(resourceServers, isServerRevoked);
@@ -834,89 +842,89 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         await Promise.allSettled(settled.map((r) => (r.status === "fulfilled" && r.value !== null ? r.value.close() : Promise.resolve())));
         throw mergeErr;
     }
-    const redialOnce = async (server) => {
+    const declineRedial = (server, outcome, reason) => ({ server, prefix: prefixOf(server), outcome, reason, toolCount: heldCount(server), added: [], removed: [] });
+    const redialFlights = new Flights();
+    const ownerStopped = () => (disposing ? "this materialization is being disposed — the task is tearing down" : signal?.aborted === true ? "the run was aborted" : undefined);
+    const redialDial = async (server) => {
         const prefix = prefixOf(server);
-        const declined = (outcome, reason) => ({ server, prefix, outcome, reason, toolCount: heldCount(server), added: [], removed: [] });
-        if (disposing)
-            return declined("refused", "this materialization is being disposed — the task is tearing down");
+        const declined = (outcome, reason) => declineRedial(server, outcome, reason);
+        const stopped = ownerStopped();
+        if (stopped !== undefined)
+            return declined("refused", stopped);
         const spec = entries.find((e) => e.name === server);
         if (spec === undefined)
             return declined("not_declared", `no MCP server named ${inlineUntrusted(server, 120)} is declared for this task`);
         if (isServerRevoked(server))
             return declined("refused", "server revoked by the operator — the re-dial did not contact it");
-        if (redialsInFlight.has(server))
-            return declined("refused", "a re-dial of this server is already in flight — wait for it to settle");
-        redialsInFlight.add(server);
-        try {
-            const hIdx = serverHandles.findIndex((h) => h.name === server);
-            const prior = hIdx === -1 ? undefined : serverHandles[hIdx];
-            const priorNames = prior ? prior.tools.map((t) => t.name) : [];
-            if (prior) {
-                prior.announce.fn = undefined;
-                prior.health.observe = undefined;
-                serverHandles.splice(hIdx, 1);
-                const cIdx = connections.findIndex((c) => c.client === prior.client);
-                const priorConnection = cIdx === -1 ? undefined : connections.splice(cIdx, 1)[0];
-                await (priorConnection?.close() ?? prior.client.close()).catch(() => undefined);
-            }
-            const dialKind = readDialKind(spec);
-            let connected;
-            try {
-                connected = await dialServer(spec, dialKind, { fresh: true, sections: promptSections });
-            }
-            catch (err) {
-                const { kind, delivered, httpStatus } = classifyMcpFailure(err, { phase: "connect", transport: dialKind });
-                const redialLiveness = livenessOf(kind, Date.now());
-                const status = { name: server, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(err), ...(redialLiveness !== undefined ? { liveness: redialLiveness } : {}) };
-                const sIdx = statuses.findIndex((st) => st.name === server);
-                if (sIdx === -1)
-                    statuses.push(status);
-                else
-                    statuses[sIdx] = status;
-                const raised = asServerWarning(spec, err);
-                warnings.push(raised);
-                reconcileInstructions(server, undefined, false);
-                return {
-                    server,
-                    prefix,
-                    outcome: "refused",
-                    reason: inlineUntrusted(namedMcpFailureText(err), 240),
-                    toolCount: 0,
-                    added: [],
-                    removed: priorNames,
-                    tools: [],
-                    axes: [],
-                    dropped: [],
-                    warnings: [raised.message],
-                    status,
-                };
-            }
-            if (disposing) {
-                await connected.close().catch(() => undefined);
-                return declined("refused", "this materialization was disposed while the re-dial was in flight — the new connection was closed");
-            }
-            const raised = commitConnectedServer(spec, connected, dialKind);
-            reconcileInstructions(server, connected.instructions, true);
-            const newNames = connected.tools.map((t) => t.name);
+        const hIdx = serverHandles.findIndex((h) => h.name === server);
+        const prior = hIdx === -1 ? undefined : serverHandles[hIdx];
+        const priorNames = prior ? prior.tools.map((t) => t.name) : [];
+        if (prior) {
+            prior.announce.fn = undefined;
+            prior.health.observe = undefined;
+            serverHandles.splice(hIdx, 1);
+            const cIdx = connections.findIndex((c) => c.client === prior.client);
+            const priorConnection = cIdx === -1 ? undefined : connections.splice(cIdx, 1)[0];
+            await (priorConnection?.close() ?? prior.client.close()).catch(() => undefined);
+        }
+        const dialKind = readDialKind(spec);
+        const dialed = await dialServer(spec, dialKind, { fresh: true, sections: promptSections, ...(prior !== undefined ? { carried: prior.listing.latest().entries } : {}) }).then((connected) => ({ connected }), (err) => ({ err }));
+        const stoppedLate = ownerStopped();
+        if (stoppedLate !== undefined) {
+            if ("connected" in dialed)
+                await dialed.connected.close().catch(() => undefined);
+            return declined("refused", `${stoppedLate} while the re-dial was in flight — nothing new was kept or recorded`);
+        }
+        if ("err" in dialed) {
+            const err = dialed.err;
+            const { kind, delivered, httpStatus } = classifyMcpFailure(err, { phase: "connect", transport: dialKind });
+            const redialLiveness = livenessOf(kind, Date.now());
+            const declared = echoOf(spec);
+            const failure = namedMcpFailureText(err, declared);
+            const status = { name: server, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: failure, ...(redialLiveness !== undefined ? { liveness: redialLiveness } : {}) };
+            const sIdx = statuses.findIndex((st) => st.name === server);
+            if (sIdx === -1)
+                statuses.push(status);
+            else
+                statuses[sIdx] = status;
+            const raised = asServerWarning(spec, err, declared);
+            warnings.push(raised);
+            reconcileInstructions(server, undefined, false);
             return {
                 server,
                 prefix,
-                outcome: "reconnected",
-                toolCount: newNames.length,
-                added: newNames.filter((n) => !priorNames.includes(n)),
-                removed: priorNames.filter((n) => !newNames.includes(n)),
-                tools: connected.tools,
-                axes: connected.axes,
-                dropped: connected.dropped.map((d) => ({ server: inlineUntrusted(server, 160), ...d })),
-                ...(raised.length > 0 ? { warnings: raised.map((w) => w.message) } : {}),
-                status: connected.status,
-                ...(connected.listingIncomplete !== undefined ? { listingIncomplete: connected.listingIncomplete } : {}),
+                outcome: "refused",
+                reason: inlineUntrusted(failure, 240),
+                toolCount: 0,
+                added: [],
+                removed: priorNames,
+                tools: [],
+                axes: [],
+                dropped: [],
+                warnings: [raised.message],
+                status,
             };
         }
-        finally {
-            redialsInFlight.delete(server);
-        }
+        const { connected } = dialed;
+        const raised = commitConnectedServer(spec, connected, dialKind);
+        reconcileInstructions(server, connected.instructions, true);
+        const newNames = connected.tools.map((t) => t.name);
+        return {
+            server,
+            prefix,
+            outcome: "reconnected",
+            toolCount: newNames.length,
+            added: newNames.filter((n) => !priorNames.includes(n)),
+            removed: priorNames.filter((n) => !newNames.includes(n)),
+            tools: connected.tools,
+            axes: connected.axes,
+            dropped: connected.dropped.map((d) => ({ server: inlineUntrusted(server, 160), ...d })),
+            ...(raised.length > 0 ? { warnings: raised.map((w) => w.message) } : {}),
+            status: connected.status,
+            ...(connected.listingIncomplete !== undefined ? { listingIncomplete: connected.listingIncomplete } : {}),
+        };
     };
+    const redialOnce = (server) => (redialFlights.running(server) === undefined ? redialFlights.start(server, () => redialDial(server)) : Promise.resolve(declineRedial(server, "refused", "a re-dial of this server is already in flight — wait for it to settle")));
     return {
         tools,
         toolAxes,
@@ -940,20 +948,25 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     results.push({ server: h.name, prefix: prefixOf(h.name), status: "revoked", toolCount: h.tools.length, added: [], removed: [], error: "server revoked by the operator — the refresh did not contact it" });
                     continue;
                 }
+                const site = requestSite(h.client);
                 try {
+                    const at = h.listing.open();
                     const cacheTools = h.openListing();
-                    const listed = await listToolsLenient(h.client);
-                    const advertised = new Set(listed.tools.map((t) => t.name));
-                    const retainedRaw = listed.incomplete !== undefined ? h.listedRaw.filter((t) => !advertised.has(t.name)) : [];
-                    const mergedRaw = retainedRaw.length > 0 ? [...listed.tools, ...retainedRaw] : listed.tools;
-                    const { serverTools, serverAxes, dropped, accepted } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
-                    cacheTools(accepted, new Set(retainedRaw.map((t) => t.name)));
+                    const listed = await listToolsLenient(h.client, undefined, echoOf(h.spec));
+                    const answered = h.listing.answer(at, listed.tools, listed.incomplete !== undefined);
+                    const mergedRaw = answered.view;
+                    if (!answered.recorded) {
+                        results.push({ server: h.name, prefix: prefixOf(h.name), status: "failed", toolCount: h.tools.length, added: [], removed: [], error: "a later listing of this server was opened and applied while this one was in the air — this one was discarded" });
+                        continue;
+                    }
+                    const { serverTools, serverAxes, gates, dropped, accepted } = intakeListedTools({ tools: [...mergedRaw], unproven: answered.unproven }, h.spec, linkOf(h.name), echoOf(h.spec), imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    cacheTools(accepted, answered.kept);
                     const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !priorNames.includes(n));
                     const removed = priorNames.filter((n) => !newNames.includes(n));
                     h.tools = serverTools;
-                    h.listedRaw = mergedRaw;
+                    h.gatesAt = { at, gates };
                     results.push({
                         server: h.name,
                         prefix: prefixOf(h.name),
@@ -971,7 +984,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     });
                 }
                 catch (err) {
-                    h.health.observe?.(classifyMcpFailure(err, { phase: "request" }).kind);
+                    h.health.observe?.(classifyMcpFailure(err, site).kind);
                     results.push({
                         server: h.name,
                         prefix: prefixOf(h.name),
@@ -979,7 +992,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         toolCount: h.tools.length,
                         added: [],
                         removed: [],
-                        error: inlineUntrusted(namedMcpFailureText(err), 240),
+                        error: inlineUntrusted(namingLostSession(err, site, namedMcpFailureText(err, echoOf(h.spec))), 240),
                     });
                 }
             }
@@ -1094,7 +1107,7 @@ export async function walkMcpListPages(fetchPage, opts) {
         catch (err) {
             if (pages === 0 || opts.signal?.aborted)
                 throw err;
-            return { items, incomplete: { reason: "page_error", pages, error: remoteErrorText(err) } };
+            return { items, incomplete: { reason: "page_error", pages, error: remoteErrorText(err, opts.declared ?? []) } };
         }
         opts.onPage?.();
         const pageStart = items.length;
@@ -1177,13 +1190,13 @@ async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
             if (err instanceof McpError && err.code === ErrorCode.InvalidParams) {
                 if (pages > 0)
                     return { kind: "ok", resources, cursorInvalid: true };
-                const detail = remoteErrorText(err, { collapse: true });
+                const detail = remoteErrorText(err, rs.declared, { collapse: true });
                 return { kind: classifyDirReadInvalidParams(detail), detail };
             }
             if (err instanceof McpError && err.code === ErrorCode.MethodNotFound)
                 return { kind: "unsupported" };
             if (pages > 0 && !signal?.aborted) {
-                return { kind: "ok", resources, incomplete: remoteErrorText(err) };
+                return { kind: "ok", resources, incomplete: remoteErrorText(err, rs.declared) };
             }
             throw err;
         }
@@ -1266,6 +1279,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                     }
                     const idleMs = mcpIdleTimeoutMs(rs.transportKind);
                     const watchdog = armMcpIdleWatchdog(rs.health, idleMs, signal);
+                    const site = requestSite(rs.client);
                     try {
                         const walk = await walkMcpListPages(async (cursor, remainingMs) => {
                             const page = await rs.client
@@ -1274,7 +1288,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                                 throw watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON ? new Error(idleWatchdogTripText(idleMs)) : err;
                             });
                             return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
-                        }, { budgetMs: mcpToolTimeoutMs(), onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
+                        }, { budgetMs: mcpToolTimeoutMs(), onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, declared: rs.declared, ...(signal !== undefined ? { signal } : {}) });
                         all.push(...walk.items.map((r) => ({ server: rs.server, ...r })));
                         const lines = walk.items.map((r) => resourceLine(r));
                         const body = lines.length ? lines.join("\n") : "(no resources)";
@@ -1287,11 +1301,12 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                         }
                     }
                     catch (err) {
+                        sanitizeMcpErrorTextInPlace(err, rs.declared);
                         if (signal?.aborted)
                             throw err;
                         const msg = watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON
                             ? idleWatchdogTripText(idleMs)
-                            : remoteErrorText(err);
+                            : namingLostSession(err, site, remoteErrorText(err, rs.declared));
                         errors.push({ server: rs.server, error: msg });
                         sections.push(`[${rs.server}] Error: could not list resources: ${inlineUntrusted(msg)}`);
                     }
@@ -1345,11 +1360,12 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const timeoutMs = mcpToolTimeoutMs();
                 const idleMs = mcpIdleTimeoutMs(rs.transportKind);
                 const watchdog = armMcpIdleWatchdog(rs.health, idleMs, signal);
+                const site = requestSite(rs.client);
                 let res;
                 try {
                     res = await rs.client
                         .readResource({ uri }, { signal: watchdog.combinedSignal, timeout: timeoutMs })
-                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
+                        .catch((err) => rethrowHonestMcpError(err, { server, declared: rs.declared, what, timeoutMs, writeEffect: false, signal, attributeServer: true, site, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
                     rs.health.observe?.("completed");
                 }
                 finally {
@@ -1406,10 +1422,11 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const timeoutMs = mcpToolTimeoutMs();
                 const idleMs = mcpIdleTimeoutMs(rs.transportKind);
                 const watchdog = armMcpIdleWatchdog(rs.health, idleMs, signal);
+                const site = requestSite(rs.client);
                 try {
                     const ext = rs.client.getServerCapabilities()?.extensions?.[MCP_SKILLS_EXTENSION];
                     if (ext?.directoryRead === true) {
-                        const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
+                        const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, declared: rs.declared, what, timeoutMs, writeEffect: false, signal, attributeServer: true, site, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
                         const serverSaid = (detail) => `\nThe server's error text follows as external/untrusted data:\n${delimitUntrusted(`${server} error`, truncateMcpErrorText(detail))}`;
                         if (r.kind === "not_found") {
                             return {
@@ -1437,10 +1454,10 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                     const walk = await walkMcpListPages(async (cursor, remainingMs) => {
                         const page = await rs.client
                             .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
-                            .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
+                            .catch((err) => rethrowHonestMcpError(err, { server, declared: rs.declared, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, site, idle: { signal: watchdog.idleSignal, idleMs }, liveness: rs.health }));
                         rs.health.observe?.("completed");
                         return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
-                    }, { budgetMs: timeoutMs, onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
+                    }, { budgetMs: timeoutMs, onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, declared: rs.declared, ...(signal !== undefined ? { signal } : {}) });
                     const dirPrefix = uri.endsWith("/") ? uri : `${uri}/`;
                     const children = walk.items.filter((r) => typeof r.uri === "string" && r.uri !== uri && r.uri.startsWith(dirPrefix));
                     return renderDirChildren(server, uri, children, walk.incomplete ? { listing: walk.incomplete } : undefined);
@@ -1505,7 +1522,7 @@ export function parseCallToolResultLenient(data) {
     return { success: true, data: { ...parsed.data, structuredContent } };
 }
 const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
-async function listToolsLenient(client, options) {
+async function listToolsLenient(client, options, declared) {
     if (!client.getServerCapabilities()?.tools)
         return { tools: [], toolsCapabilityAbsent: true };
     const walk = await walkMcpListPages(async (cursor, remainingMs) => {
@@ -1518,6 +1535,7 @@ async function listToolsLenient(client, options) {
     }, {
         budgetMs: options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC,
         fingerprintOf: listEntryFingerprint,
+        declared,
         ...(options?.signal !== undefined ? { signal: options.signal } : {}),
     });
     return { tools: walk.items, ...(walk.incomplete !== undefined ? { incomplete: walk.incomplete } : {}) };
@@ -1532,7 +1550,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
     const announce = {};
     const startupMs = mcpStartupTimeoutMs(spec);
     const startupOpts = startupMs !== undefined ? { timeout: startupMs } : undefined;
-    const dialClient = async () => {
+    const dialClient = async (stop = dialOpts?.signal) => {
+        stop?.throwIfAborted();
         const client = new Client({ name: `sema-core/${spec.name}`, version: "0.1.0" }, { capabilities: elicitOn ? { elicitation: { form: {} } } : {} });
         if (elicitOn) {
             client.setRequestHandler(ElicitRequestSchema, async (request, extra) => {
@@ -1555,12 +1574,17 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             });
         }
         const transport = buildTransport(spec, principal, transportKind);
+        const hangUp = () => void client.close().catch(() => undefined);
+        stop?.addEventListener("abort", hangUp, { once: true });
         try {
             await client.connect(transport, startupOpts);
         }
         catch (err) {
             await client.close().catch(() => undefined);
-            throw err;
+            throw stop?.aborted === true ? stop.reason : err;
+        }
+        finally {
+            stop?.removeEventListener("abort", hangUp);
         }
         return client;
     };
@@ -1580,10 +1604,14 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             lease.onClose(onClosed);
         else
             client.onclose = onClosed;
+        const listing = lease?.listing ?? new ConnectionListing();
+        const at = listing.open();
         const cacheTools = openListing();
-        const listed = await listToolsLenient(client, startupOpts);
-        const { serverTools, serverAxes, dropped, advisories, accepted } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
-        cacheTools(accepted);
+        const declared = declaredHeaderValues(spec.transport, principal);
+        const listed = await underStartupBound(startupMs, dialOpts?.signal, (options) => listToolsLenient(client, options, declared));
+        const answered = listing.answer(at, listed.tools, listed.incomplete !== undefined, dialOpts.carried);
+        const { serverTools, serverAxes, gates, dropped, advisories, accepted } = intakeListedTools({ tools: [...answered.view], unproven: answered.unproven }, spec, dialOpts.link, declared, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        cacheTools(accepted, answered.kept);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1612,14 +1640,15 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             announce,
             tools: serverTools,
             axes: serverAxes,
+            listing,
+            gatesAt: { at, gates },
             dropped,
             schemaAdvisories: advisories,
             ...(listed.toolsCapabilityAbsent === true ? { toolsCapabilityAbsent: true } : {}),
-            listedTools: listed.tools,
             ...(instructions ? { instructions } : {}),
             ...(disposed?.defect !== undefined ? { instructionsDefect: disposed.defect } : {}),
             ...(listed.incomplete !== undefined ? { listingIncomplete: listed.incomplete } : {}),
-            ...(resourceInfo && (resourceInfo.listAllowed || resourceInfo.readAllowed) ? { resourceServer: { server: spec.name, client, health, transportKind: idleKindOf(transportKind), ...resourceInfo } } : {}),
+            ...(resourceInfo && (resourceInfo.listAllowed || resourceInfo.readAllowed) ? { resourceServer: { server: spec.name, client, health, transportKind: idleKindOf(transportKind), declared, ...resourceInfo } } : {}),
         };
     }
     catch (err) {
@@ -1627,10 +1656,11 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         throw err;
     }
 }
-function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind) {
+function intakeListedTools(listed, spec, link, declared, imageResizer, reminderDisclosure, isServerRevoked, transportKind) {
     const declaredContentOrigin = spec.contentOrigin;
     const serverTools = [];
     const serverAxes = [];
+    const gates = new Map();
     const dropped = [];
     const accepted = [];
     const advisories = [];
@@ -1697,6 +1727,9 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         if (interaction.advisory !== undefined)
             advisories.push({ tool: inlineUntrusted(t.name), reason: interaction.advisory });
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
+        const gateFace = { ...(interaction.declared ? { mcpRequiresUserInteraction: true } : {}), ...(t.annotations?.readOnlyHint === true ? { mcpReadOnlyHint: true } : {}) };
+        const gate = mcpToolGate(remoteName, axis, gateFace, taskRequired);
+        gates.set(namespacedName, listed.unproven?.has(remoteName) === true ? UNPROVEN_GATE : gate);
         const mounted = {
             name: namespacedName,
             description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
@@ -1704,8 +1737,8 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
             ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
-            ...(interaction.declared ? { mcpRequiresUserInteraction: true } : {}),
-            mcpRemoteName: remoteName, ...boundaryFlowFace(spec.toolAxes?.[remoteName]), ...(t.annotations?.readOnlyHint === true ? { mcpReadOnlyHint: true } : {}), permissionSeat: "passthrough",
+            ...gateFace,
+            mcpRemoteName: remoteName, ...boundaryFlowFace(spec.toolAxes?.[remoteName]), permissionSeat: "passthrough",
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
                 if (isServerRevoked?.(spec.name) === true) {
@@ -1724,38 +1757,56 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                         isError: true,
                     };
                 }
-                if (health.dead)
-                    throwDeadServer(spec.name, what);
                 const timeoutMs = mcpToolTimeoutMs();
                 const idleMs = mcpIdleTimeoutMs(idleKindOf(transportKind));
-                const watchdog = armMcpIdleWatchdog(health, idleMs, signal);
-                let res;
-                try {
-                    res = await client
-                        .callTool({ name: remoteName, arguments: (params ?? {}) }, LENIENT_CALL_TOOL_RESULT_SCHEMA, {
-                        signal: watchdog.combinedSignal,
-                        timeout: timeoutMs,
-                        resetTimeoutOnProgress: true,
-                        onprogress: () => watchdog.rearm(),
-                        maxTotalTimeout: mcpToolTotalTimeoutMs(timeoutMs),
-                    })
-                        .catch((err) => rethrowHonestMcpError(err, {
-                        server: spec.name,
-                        what,
-                        timeoutMs,
-                        writeEffect,
-                        signal,
-                        idle: { signal: watchdog.idleSignal, idleMs },
-                        liveness: health,
-                        ...(reminderDisclosure !== undefined
-                            ? { reminder: { mark: reminderDisclosure.mark, outlet: "mcp", ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) } }
-                            : {}),
-                    }));
-                    health.observe?.("completed");
-                }
-                finally {
-                    watchdog.dispose();
-                }
+                const send = async (conn, resent) => {
+                    const site = requestSite(conn.client);
+                    const watchdog = armMcpIdleWatchdog(conn.health, idleMs, signal);
+                    try {
+                        const res = await conn.client
+                            .callTool({ name: remoteName, arguments: (params ?? {}) }, LENIENT_CALL_TOOL_RESULT_SCHEMA, {
+                            signal: watchdog.combinedSignal,
+                            timeout: timeoutMs,
+                            resetTimeoutOnProgress: true,
+                            onprogress: () => watchdog.rearm(),
+                            maxTotalTimeout: mcpToolTotalTimeoutMs(timeoutMs),
+                        })
+                            .catch((err) => {
+                            try {
+                                return rethrowHonestMcpError(err, {
+                                    server: spec.name,
+                                    declared,
+                                    what,
+                                    timeoutMs,
+                                    writeEffect,
+                                    signal,
+                                    site,
+                                    ...(resent ? { resent: true } : {}),
+                                    idle: { signal: watchdog.idleSignal, idleMs },
+                                    liveness: conn.health,
+                                    ...(reminderDisclosure !== undefined
+                                        ? { reminder: { mark: reminderDisclosure.mark, outlet: "mcp", ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) } }
+                                        : {}),
+                                });
+                            }
+                            catch (failure) {
+                                if (sessionGone(err, site) && signal?.aborted !== true)
+                                    return new Resendable(conn, failure);
+                                throw failure;
+                            }
+                        });
+                        if (res instanceof Resendable)
+                            return res;
+                        conn.health.observe?.("completed");
+                        return res;
+                    }
+                    finally {
+                        watchdog.dispose();
+                    }
+                };
+                const res = await callThroughLink(link, namespacedName, gate, signal, send, () => throwDeadServer(spec.name, what));
+                if (typeof res === "string")
+                    return listingRefusal(res, remoteName, spec.name);
                 const mapped = await mapContent(res.content, spec.name, imageResizer);
                 if (res.isError === true) {
                     const parts = [];
@@ -1768,7 +1819,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                     const errScLine = structuredContentErrorLine(res.structuredContent, parts.join("\n"));
                     if (errScLine !== undefined)
                         parts.push(errScLine);
-                    const body = truncateMcpErrorText(egressText("same-principal", parts.join("\n").trim()));
+                    const body = truncateMcpErrorText(mcpRemoteText(parts.join("\n").trim(), declared));
                     const msg = body
                         ? `MCP tool ${inlineUntrusted(remoteName)} reported an error. The server's error content follows as external/untrusted data:\n${delimitUntrusted(`${spec.name} tool error`, body)}`
                         : `MCP tool ${inlineUntrusted(remoteName)} reported an error`;
@@ -1815,10 +1866,10 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         serverTools.push(declaredContentOrigin !== undefined ? withContentOrigin(mounted, declaredContentOrigin) : mounted);
         accepted.push(t);
     }
-    return { serverTools, serverAxes, dropped, advisories, accepted };
+    return { serverTools, serverAxes, gates, dropped, advisories, accepted };
 }
-function asServerWarning(spec, err) {
-    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: sanitizedCause(err) });
+function asServerWarning(spec, err, declared) {
+    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err, declared)})`, { cause: sanitizedCause(err, declared) });
     warning.code = "mcp.server_unavailable";
     return warning;
 }
@@ -1843,8 +1894,8 @@ function dialDecision(dialable, spec) {
     }
     throw Object.assign(new Error(`MCP materialization refused: the dialable seat could not decide whether to dial server "${inlineUntrusted(spec.name, 120)}" — ${inlineUntrusted(why, 240)}. No server was dialed.`, cause), { code: "config.mcp_dialable_failed" });
 }
-function sanitizedCause(err) {
-    const copy = new Error(namedMcpFailureText(err));
+function sanitizedCause(err, declared) {
+    const copy = new Error(namedMcpFailureText(err, declared));
     const name = thrownName(err);
     if (name !== undefined) {
         if (name !== "")