@sema-agent/core 7.55.0 → 7.56.0

package/dist/core/mcp.js

@@ -2,7 +2,7 @@ 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";
@@ -22,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";
@@ -161,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
@@ -194,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);
@@ -225,7 +229,7 @@ function rethrowHonestMcpError(err, ctx) {
         case "connect_refused":
         case "connection_failed": {
             const httpFailure = describeHttpTransportFailure(err, ctx.site);
-            const detail = remoteErrorText(err);
+            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(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}`
@@ -240,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()));
         }
@@ -248,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()));
@@ -641,7 +645,7 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable, signal) {
+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) => {
@@ -767,18 +771,33 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     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), imageResizer, mcpDisclosure, isServerRevoked, h.transportKind).gates };
+            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);
+        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)
@@ -808,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);
@@ -859,20 +879,22 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             const err = dialed.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 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);
+            const raised = asServerWarning(spec, err, declared);
             warnings.push(raised);
             reconcileInstructions(server, undefined, false);
             return {
                 server,
                 prefix,
                 outcome: "refused",
-                reason: inlineUntrusted(namedMcpFailureText(err), 240),
+                reason: inlineUntrusted(failure, 240),
                 toolCount: 0,
                 added: [],
                 removed: priorNames,
@@ -930,14 +952,14 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 try {
                     const at = h.listing.open();
                     const cacheTools = h.openListing();
-                    const listed = await listToolsLenient(h.client);
+                    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), imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    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);
@@ -970,7 +992,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         toolCount: h.tools.length,
                         added: [],
                         removed: [],
-                        error: inlineUntrusted(namingLostSession(err, site, namedMcpFailureText(err)), 240),
+                        error: inlineUntrusted(namingLostSession(err, site, namedMcpFailureText(err, echoOf(h.spec))), 240),
                     });
                 }
             }
@@ -1085,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;
@@ -1168,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,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)";
@@ -1279,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)
-                            : namingLostSession(err, site, 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)}`);
                     }
@@ -1342,7 +1365,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 try {
                     res = await rs.client
                         .readResource({ uri }, { signal: watchdog.combinedSignal, timeout: timeoutMs })
-                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, site, 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 {
@@ -1403,7 +1426,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 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, site, 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 {
@@ -1431,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, site, 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);
@@ -1499,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) => {
@@ -1512,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 } : {}) };
@@ -1583,9 +1607,10 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         const listing = lease?.listing ?? new ConnectionListing();
         const at = listing.open();
         const cacheTools = openListing();
-        const listed = await underStartupBound(startupMs, dialOpts?.signal, (options) => listToolsLenient(client, options));
+        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, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        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
@@ -1623,7 +1648,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             ...(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) {
@@ -1631,7 +1656,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         throw err;
     }
 }
-function intakeListedTools(listed, spec, link, imageResizer, reminderDisclosure, isServerRevoked, transportKind) {
+function intakeListedTools(listed, spec, link, declared, imageResizer, reminderDisclosure, isServerRevoked, transportKind) {
     const declaredContentOrigin = spec.contentOrigin;
     const serverTools = [];
     const serverAxes = [];
@@ -1750,6 +1775,7 @@ function intakeListedTools(listed, spec, link, imageResizer, reminderDisclosure,
                             try {
                                 return rethrowHonestMcpError(err, {
                                     server: spec.name,
+                                    declared,
                                     what,
                                     timeoutMs,
                                     writeEffect,
@@ -1793,7 +1819,7 @@ function intakeListedTools(listed, spec, link, imageResizer, reminderDisclosure,
                     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`;
@@ -1842,8 +1868,8 @@ function intakeListedTools(listed, spec, link, imageResizer, reminderDisclosure,
     }
     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;
 }
@@ -1868,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 !== "")

package/dist/core/memory-engine/delegation-settlement.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { QUARANTINE_DIR, appendChallengeEvents, enqueueMemoryAnnouncement, ensureDirExists, v1MemoryPathKeyResolver, lineageContributionsOfSession, lockedStrictUpdate, markSessionPolluted, readProjectionDebts, readSessionPollution, readStrictSidecar, ControlPlaneCorruptError } from "./layout.js";
+import { QUARANTINE_DIR, appendChallengeEvents, claimStaging, enqueueMemoryAnnouncement, ensureDirExists, isSameFile, mintStagingName, stagingNamePattern, v1MemoryPathKeyResolver, lineageContributionsOfSession, lockedStrictUpdate, markSessionPolluted, readProjectionDebts, readSessionPollution, readStrictSidecar, ControlPlaneCorruptError } from "./layout.js";
 import { thrownText } from "../thrown-value.js";
 export const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
 function reqStr(v) {
@@ -495,25 +495,6 @@ export function readHolds(controlDir) {
 function sha256(buf) {
     return createHash("sha256").update(buf).digest("hex");
 }
-let stagingSeq = 0;
-function uniqueStagingName(holdId, now) {
-    stagingSeq += 1;
-    return `${holdId}.staging-${now()}-${process.pid}-${stagingSeq}`;
-}
-function stagingGenerationPattern(holdId) {
-    return new RegExp(`^${holdId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\.staging-\\d+-\\d+-\\d+(?:\\.claim-\\d+-\\d+)*$`);
-}
-function claimStaging(stagingPath) {
-    stagingSeq += 1;
-    const claimed = `${stagingPath}.claim-${process.pid}-${stagingSeq}`;
-    try {
-        renameSync(stagingPath, claimed);
-        return claimed;
-    }
-    catch {
-        return stagingPath;
-    }
-}
 function dropStaging(claimedPath) {
     try {
         unlinkSync(claimedPath);
@@ -638,7 +619,7 @@ export function openInstructionHold(controlDir, input) {
     if (!writeCustodyVerified(join(holdDir, captureName), buf)) {
         return refuse("hold capture verification failed (the custody copy could not be written, made durable, or hashed back to the captured digest)", "capture_lost");
     }
-    const stagingName = uniqueStagingName(holdId, input.now);
+    const stagingName = mintStagingName(holdId, input.now);
     const stagingPath = stagingPathBeside(input.absPath, stagingName);
     try {
         renameSync(input.absPath, stagingPath);
@@ -695,7 +676,7 @@ export function reconcileHolds(controlDir, input) {
         }
     };
     const finishRemoval = (row, plane) => {
-        const stagingName = uniqueStagingName(row.holdId, input.now);
+        const stagingName = mintStagingName(row.holdId, input.now);
         renameSync(plane, stagingPathBeside(plane, stagingName));
         const staging = claimStaging(stagingPathBeside(plane, stagingName));
         if (sha256(readFileSync(staging)) === row.contentDigest) {
@@ -726,7 +707,14 @@ export function reconcileHolds(controlDir, input) {
     };
     const sweepStagingGenerations = (row, plane, custody) => {
         const seatDir = dirname(plane);
-        const pattern = stagingGenerationPattern(row.holdId);
+        const pattern = stagingNamePattern(row.holdId);
+        let seat;
+        try {
+            seat = lstatSync(plane);
+        }
+        catch {
+            seat = undefined;
+        }
         for (const name of listSeat(seatDir)) {
             if (!pattern.test(name))
                 continue;
@@ -746,7 +734,10 @@ export function reconcileHolds(controlDir, input) {
                     continue;
                 }
             }
-            discloseStranded(row.holdId, row.rel, retireStagingToCustody(staged, holdDir, name).at);
+            const onSeat = seat !== undefined && isSameFile(staged, seat);
+            const retired = retireStagingToCustody(staged, holdDir, name);
+            if (!(onSeat && retired.settled && isSameFile(plane, seat)))
+                discloseStranded(row.holdId, row.rel, retired.at);
         }
     };
     const rows = readHolds(controlDir).filter((r) => r.status === "capturing");

package/dist/core/memory-engine/engine.js

@@ -19,7 +19,7 @@ import { landedUndecided, layerDigest, layerObservationLookup, readOnlyLayerCand
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
 import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, anchorStoreRoot, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, effectiveControlRootOf, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, mintStagingName, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, anchorStoreRoot, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, effectiveControlRootOf, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, writeFileNoReplace, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
 import { createSessionIncarnationSeat, recalledForAnyIdentity, recalledForIdentity, rememberForIdentity } from "./session-incarnation.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 import { writableRootOf } from "./types.js";
@@ -1516,7 +1516,7 @@ export class MemoryEngine {
                                     }
                                     let restoredCommitted = false;
                                     if (captured) {
-                                        const stagingName = `${captureName}.staging`;
+                                        const stagingName = mintStagingName(captureName, this.now);
                                         const stagingPath = stagingPathBeside(canonical, stagingName);
                                         try {
                                             this.refuseOutsideStore(canonical, "containing session residue");
@@ -2475,8 +2475,8 @@ export class MemoryEngine {
                         if (committed !== undefined) {
                             try {
                                 this.refuseOutsideStore(f.canonical, "restoring a held entry's committed content", handle);
-                                writeFileNoFollow(f.canonical, committed);
-                                report.restored.push(rel);
+                                if (writeFileNoReplace(f.canonical, committed) === "written")
+                                    report.restored.push(rel);
                             }
                             catch (err) {
                                 report.warnings.push(`${rel}: the committed content could not be restored after the hold captured this session's edit — the entry is unavailable on the plane until release or the next restore: ${this.writeFailureText(err)}`);

package/dist/core/memory-engine/layout.d.ts

@@ -513,13 +513,21 @@ export interface QuarantineOutcome {
  * without native bindings. What this buys is the leaf variant, which is the cheap one; the ancestor
  * variant stays open and is recorded with the rest of the family rather than papered over.
  *
- * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. A HARD link is the
- * same tamper by other means — the file's bytes live under a second name, possibly outside the store, and
- * an in-place write would change them there too — so an opened file with more than one name is refused
- * the same way, before anything is truncated (the check reads the opened descriptor: no window). The
- * write itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
- * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after the
- * truncation already destroyed the destination) is the failure this guard exists to prevent.
+ * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink, and EACCES for a
+ * file whose own bits refuse the write. A write changes only the NAME it writes. A file with one name is
+ * rewritten in place (its inode and mode stay). A HARD link is the same tamper as a symlink by other
+ * means — the file's bytes live under a second name, possibly outside the store, and an in-place write
+ * would change them there too — so a file the open finds with more names is never written in place.
+ * One such name is the engine's own: a staging name a no-replace restore stopped between its `link` and
+ * its `unlink` left beside the file; it is removed first ({@link dropStagingSecondNames}), the interrupted
+ * restore's last step. A file that still has another name gets a new file under THIS name, written the
+ * way the store commits a file ({@link atomicWriteFileSync}: an exclusive no-follow sibling, 0o600,
+ * renamed over this name); the other names keep their file, its bytes and its mode. Residual: a path
+ * replaced by another file between the open and that rename is replaced again (the window every
+ * rename-based store write has). The in-place write goes through `writeFileSync` on the open descriptor,
+ * which writes every byte or throws — a bare `writeSync` may short-write, and reporting a truncated
+ * restore as contained (after the truncation already destroyed the destination) is the failure this
+ * guard exists to prevent.
  */
 export declare function writeFileNoFollow(path: string, content: string): void;
 /** {@link writeFileNoFollow}'s NO-REPLACE twin: write `content` only if nothing is at `path`. `"written"`
@@ -529,6 +537,48 @@ export declare function writeFileNoFollow(path: string, content: string): void;
  *  it refuses a symlink at the final component on its own (POSIX `EEXIST` on a link, dangling or not),
  *  so the twin's no-follow property is kept without a second check. */
 export declare function writeFileNoReplace(path: string, content: string): "written" | "kept";
+/** THE minter of every staging name the engine puts beside a plane file while it is displaced:
+ *  `<owner>.staging-<ms>-<pid>-<seq>`. One grammar for every site, so one recognizer
+ *  ({@link stagingNamePattern}) knows the names the engine can have left beside a seat. */
+export declare function mintStagingName(owner: string, now: () => number): string;
+/** The grammar {@link mintStagingName} and {@link claimStaging} write, as a recognizer — of ONE owner's
+ *  generations when `owner` is given; otherwise of every staging name an engine has minted beside a seat,
+ *  for the two owners it mints them for: an instruction hold (`hold-<ms>-<12 hex>`) and a crash-residue
+ *  capture (`<ms>-residue-<entry id>.md`), whose `<ms>-residue-<id>.md.staging` of 7.55.0 and earlier is
+ *  included (a name already on disk does not lose its owner with an upgrade). A prefix or a bare
+ *  `.staging-` suffix would adopt any name a writer chose on the strength of its spelling. Minted and
+ *  recognised side by side so the two cannot drift. */
+export declare function stagingNamePattern(owner?: string): RegExp;
+/** Take exclusive hold of a staged name by an atomic same-directory rename to a name minted HERE: the
+ *  staged name lives in a WRITABLE directory, so a plain read-then-unlink could delete a replacement that
+ *  landed between the two while reporting success over the earlier bytes. After the claim, what the rename
+ *  moved is what every later read and unlink addresses. Returns the claim when it took, the original when
+ *  the directory refused it (a hardening, not a precondition — a caller that removes on the strength of
+ *  the claim checks which one it got). Residual: a writer enumerating the directory can still replace the
+ *  CLAIM name before it is read — nothing Node's `fs` closes that, and the window is narrower than the one
+ *  it replaces. */
+export declare function claimStaging(stagingPath: string): string;
+/** Whether `path` names the file `ref` describes: a regular file on the same device with the same inode,
+ *  read without following a link at `path`. */
+export declare function isSameFile(path: string, ref: {
+    readonly dev: number;
+    readonly ino: number;
+}): boolean;
+/**
+ * Remove every staging name an engine minted ({@link stagingNamePattern}) beside `seat` that is another
+ * name of the file `opened` describes — the un-dropped half of a no-replace restore stopped between its
+ * `link` and its `unlink`. Called by a write about to replace that file's bytes: removing the name loses
+ * nothing the write itself does not overwrite, and touches only names in the engine's staging grammar (a name
+ * is read as the engine's own by its spelling and by being the same file, so a hard link someone made and
+ * spelled that way goes too; every other hard-link copy, snapshot name and planted link stays, with its file).
+ * Not claimed first: a claim is a `rename`, which replaces whatever already stands at the claim name.
+ * Residual: a file put at that minted name between the check and the removal is removed — only a writer of
+ * this directory can put it there, and it can remove the name itself. Answers how many names went.
+ */
+export declare function dropStagingSecondNames(seat: string, opened: {
+    readonly dev: number;
+    readonly ino: number;
+}): number;
 /**
  * The ONE way a committed baseline goes back after {@link quarantineAndTombstone} emptied its seat —
  * the inverse half of that function, beside it so the removal word and its readers stay in one module.
@@ -1272,7 +1322,9 @@ export declare function writeAllSync(fd: number, data: string): void;
  *  is not fsync'd (stores/file/fs-atomic.ts has the dir-fsync variant for stores that need it), so
  *  a crash in that window can resurface the old content. Sidecars tolerate that (they are rebuilt
  *  or re-derived); do not route data that can't through here. Throws on failure (fail-closed: a
- *  sidecar that cannot be written must not be silently skipped). */
+ *  sidecar that cannot be written must not be silently skipped). The tmp file is created EXCLUSIVELY and
+ *  no-follow: a name already standing there (a link or a file somebody placed) is an `EEXIST` refusal,
+ *  never a file this write truncates or writes through. */
 export declare function atomicWriteFileSync(path: string, data: string): void;
 /** Content-gated {@link atomicWriteFileSync} for a DERIVED/control-plane file: a byte-identical
  *  rewrite (the common case on a repeat mount over an unchanged store) is skipped entirely, so the