@sema-agent/core 7.48.0 → 7.49.1

package/dist/core/mcp-connection-pool.js

@@ -0,0 +1,128 @@
+import { canonicalize } from "./canonical-json.js";
+export class McpConnectionPool {
+    entries = new Map();
+    dialing = new Map();
+    generation = new Map();
+    shut = false;
+    static keyOf(spec, principal, kind) {
+        const rest = Object.fromEntries(Object.keys(spec.transport).filter((k) => k !== "kind").map((k) => [k, Reflect.get(spec.transport, k)]));
+        return canonicalize([spec.name, kind ?? null, rest, principal ?? null]);
+    }
+    async acquire(key, dial, opts) {
+        if (this.shut)
+            return undefined;
+        if (opts?.fresh === true)
+            this.detach(key);
+        let entry = this.entries.get(key);
+        if (entry === undefined || entry.closed) {
+            let pending = this.dialing.get(key);
+            if (pending === undefined) {
+                const started = this.dialNew(key, this.generation.get(key) ?? 0, dial);
+                pending = started;
+                this.dialing.set(key, started);
+                const settled = () => {
+                    if (this.dialing.get(key) === started)
+                        this.dialing.delete(key);
+                };
+                void started.then(settled, settled);
+            }
+            entry = await pending;
+        }
+        return this.lease(entry);
+    }
+    detach(key) {
+        this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
+        const e = this.entries.get(key);
+        if (e !== undefined) {
+            e.current = false;
+            this.entries.delete(key);
+        }
+        this.dialing.delete(key);
+    }
+    close() {
+        this.shut = true;
+    }
+    get live() {
+        let n = 0;
+        for (const e of this.entries.values())
+            if (!e.closed)
+                n++;
+        return n;
+    }
+    async dialNew(key, generation, dial) {
+        const client = await dial();
+        const entry = { client, refs: 0, listeners: new Set(), holders: new Map(), meta: new Map(), nextVersion: 0, current: true, closed: false };
+        client.onclose = () => {
+            entry.closed = true;
+            if (this.entries.get(key) === entry)
+                this.entries.delete(key);
+            for (const fn of [...entry.listeners]) {
+                try {
+                    fn();
+                }
+                catch {
+                }
+            }
+        };
+        if ((this.generation.get(key) ?? 0) === generation)
+            this.entries.set(key, entry);
+        else
+            entry.current = false;
+        return entry;
+    }
+    lease(entry) {
+        entry.refs++;
+        const mine = new Set();
+        let released = false;
+        const cached = () => {
+            const held = new Set([...entry.holders.values()].flat());
+            return [...entry.meta].filter(([name]) => held.has(name)).map(([, r]) => r.tool);
+        };
+        const lease = {
+            client: entry.client,
+            onClose: (fn) => {
+                mine.add(fn);
+                entry.listeners.add(fn);
+            },
+            openListing: () => {
+                const version = entry.nextVersion++;
+                return (tools, apply, retained) => {
+                    for (const tool of tools) {
+                        const prior = entry.meta.get(tool.name);
+                        if (retained?.has(tool.name) === true) {
+                            if (prior === undefined)
+                                entry.meta.set(tool.name, { tool, version: -1 });
+                            continue;
+                        }
+                        if (prior !== undefined && prior.version > version)
+                            continue;
+                        entry.meta.delete(tool.name);
+                        entry.meta.set(tool.name, { tool, version });
+                    }
+                    if (!released)
+                        entry.holders.set(lease, tools.map((t) => t.name));
+                    entry.apply = apply;
+                    apply(cached());
+                };
+            },
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                for (const fn of mine)
+                    entry.listeners.delete(fn);
+                entry.refs--;
+                if (entry.holders.delete(lease) && entry.refs > 0)
+                    entry.apply?.(cached());
+                if (entry.refs > 0)
+                    return;
+                entry.current = false;
+                for (const [k, v] of this.entries)
+                    if (v === entry)
+                        this.entries.delete(k);
+                await entry.client.close().catch(() => undefined);
+            },
+        };
+        return lease;
+    }
+}

package/dist/core/mcp-failure.d.ts

@@ -2,7 +2,8 @@ import type { AssertAllKeysHandled } from "./ask-origin.js";
 /**
  * The closed set of failure classes ({@link McpFailure.kind}):
  *  · `connect_refused`   — a connect-phase errno (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / EHOSTUNREACH /
- *                          ENETUNREACH / UND_ERR_CONNECT_TIMEOUT): the request provably never left;
+ *                          ENETUNREACH / UND_ERR_CONNECT_TIMEOUT), or a proxy's refusal of the tunnel
+ *                          request: the request provably never left;
  *  · `connection_failed` — any other errno / undici code on the cause chain (a reset or a timeout
  *                          mid-exchange): the request may have run;
  *  · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in

package/dist/core/mcp-failure.js

@@ -1,5 +1,6 @@
 import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { proxyTunnelRefusedSentence, readConnectFailure } from "../brain/errors.js";
 export const MCP_FAILURE_KINDS = Object.freeze([
     "connect_refused",
     "connection_failed",
@@ -102,6 +103,11 @@ export const FAILURE_CLASSIFIER = [
         when: (err, at) => at.phase === "connect" && err instanceof Error && err.code === "ERR_INVALID_URL",
         reads: () => ({ kind: "invalid_config" }),
     },
+    {
+        name: "proxy refused the tunnel",
+        when: (err) => readConnectFailure(err).proxyRefusal !== undefined,
+        reads: () => ({ kind: "connect_refused" }),
+    },
     {
         name: "node error code, not a network errno",
         when: (err) => {
@@ -151,8 +157,13 @@ export function describeHttpTransportFailure(err) {
             return { condition: `its HTTP endpoint answered ${f.httpStatus} instead of an MCP response`, delivered: f.delivered, httpStatus: f.httpStatus };
         case "not_mcp_response":
             return { condition: "its HTTP endpoint answered something that is not an MCP response", delivered: f.delivered };
-        case "connect_refused":
-            return { condition: `its HTTP endpoint could not be reached (${networkErrorCode(err)})`, delivered: f.delivered };
+        case "connect_refused": {
+            const proxy = readConnectFailure(err).proxyRefusal;
+            return {
+                condition: `its HTTP endpoint could not be reached (${proxy !== undefined ? proxyTunnelRefusedSentence(proxy.status) : networkErrorCode(err)})`,
+                delivered: f.delivered,
+            };
+        }
         case "connection_failed":
             return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
         case "connection_closed":

package/dist/core/mcp.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolId } from "./protocol-table.js";
+import { McpConnectionPool } from "./mcp-connection-pool.js";
 import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
@@ -626,6 +627,9 @@ reminderDisclosure?: {
 }, mcpRevocations?: {
     isRevoked(serverName: string): boolean;
     onProbeFailure?: (error: unknown) => void;
+}, poolOpts?: {
+    pool: McpConnectionPool;
+    ownsPool?: boolean;
 }): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.

package/dist/core/mcp.js

@@ -4,6 +4,8 @@ import { resolveEnvBudget } from "./env-budget.js";
 import { MCP_NAMESPACE } from "./protocol-table.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 { MCP_RESOURCE_LIST_ALLOW, MCP_RESOURCE_READ_ALLOW } 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";
@@ -657,7 +659,7 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts) {
     const entries = snapshotMcpEntries(specs);
     {
         const collision = findNamespacePrefixCollision(MCP_NAMESPACE, entries.map((s) => s.name));
@@ -696,7 +698,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const mcpDisclosure = reminderDisclosure?.reminderMark !== undefined
         ? { mark: reminderDisclosure.reminderMark, windows: new Map(), ...(reminderDisclosure.counts !== undefined ? { counts: reminderDisclosure.counts } : {}) }
         : undefined;
-    const clients = [];
+    const connections = [];
     const tools = [];
     const toolAxes = [];
     const warnings = [];
@@ -710,8 +712,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const redialsInFlight = new Set();
     const commitConnectedServer = (spec, s, transportKind) => {
         const raised = [];
-        clients.push(s.client);
-        const handle = { name: spec.name, spec, client: s.client, health: s.health, tools: s.tools, listedRaw: s.listedTools, transportKind, announce: s.announce, instructions: s.instructions };
+        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 hIdx = serverHandles.findIndex((h) => h.name === spec.name);
         if (hIdx === -1)
             serverHandles.push(handle);
@@ -796,7 +798,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         if (before !== undefined || owedRemoval || hadPendingAdd)
             instructionsDelta.pendingRemovals.push(name);
     };
-    const settled = await Promise.allSettled(entries.map((spec, i) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKinds[i])));
+    const settled = await Promise.allSettled(entries.map((spec, i) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKinds[i], poolOpts?.pool)));
     try {
         for (let i = 0; i < entries.length; i++) {
             const r = settled[i];
@@ -822,7 +824,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         toolAxes.push(...resourceTools.axes);
     }
     catch (mergeErr) {
-        await Promise.allSettled(settled.map((r) => (r.status === "fulfilled" ? r.value.client.close() : Promise.resolve())));
+        await Promise.allSettled(settled.map((r) => (r.status === "fulfilled" ? r.value.close() : Promise.resolve())));
         throw mergeErr;
     }
     const redialOnce = async (server) => {
@@ -847,15 +849,14 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 prior.announce.fn = undefined;
                 prior.health.observe = undefined;
                 serverHandles.splice(hIdx, 1);
-                const cIdx = clients.indexOf(prior.client);
-                if (cIdx !== -1)
-                    clients.splice(cIdx, 1);
-                await prior.client.close().catch(() => undefined);
+                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 connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind);
+                connected = await connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, { fresh: true });
             }
             catch (err) {
                 const { kind, delivered, httpStatus } = classifyMcpFailure(err, { phase: "connect", transport: dialKind });
@@ -885,7 +886,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 };
             }
             if (disposing) {
-                await connected.client.close().catch(() => undefined);
+                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);
@@ -934,12 +935,13 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     continue;
                 }
                 try {
+                    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);
-                    cacheMcpToolMetadata(h.client, accepted);
+                    cacheTools(accepted, new Set(retainedRaw.map((t) => t.name)));
                     const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !priorNames.includes(n));
@@ -995,7 +997,9 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         reconnect: redialOnce,
         dispose: async () => {
             disposing = true;
-            await Promise.allSettled(clients.map((c) => c.close()));
+            await Promise.allSettled(connections.map((c) => c.close()));
+            if (poolOpts?.ownsPool === true)
+                poolOpts.pool.close();
         },
     };
 }
@@ -1517,48 +1521,69 @@ async function listToolsLenient(client, options) {
     });
     return { tools: walk.items, ...(walk.incomplete !== undefined ? { incomplete: walk.incomplete } : {}) };
 }
-async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure, isServerRevoked, transportKind) {
+async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure, isServerRevoked, transportKind, pool, dialOpts) {
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
     const health = { dead: false, pendingElicitations: 0, lastElicitationClosedAt: 0 };
-    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) => {
-            health.pendingElicitations++;
-            try {
-                const p = request.params;
-                const req = {
-                    server: spec.name,
-                    message: typeof p.message === "string" ? p.message : "",
-                    ...(p.requestedSchema !== undefined ? { requestedSchema: p.requestedSchema } : {}),
-                    ...(principal !== undefined ? { principal } : {}),
-                };
-                const answer = await onElicit(req, extra?.signal);
-                return answer.action === "accept" ? { action: "accept", content: answer.content ?? {} } : { action: answer.action };
-            }
-            finally {
-                health.pendingElicitations--;
-                health.lastElicitationClosedAt = Date.now();
-            }
-        });
-    }
-    const transport = buildTransport(spec, principal, transportKind);
     const announce = {};
     const startupMs = mcpStartupTimeoutMs();
     const startupOpts = startupMs !== undefined ? { timeout: startupMs } : undefined;
+    const dialClient = async () => {
+        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) => {
+                health.pendingElicitations++;
+                try {
+                    const p = request.params;
+                    const req = {
+                        server: spec.name,
+                        message: typeof p.message === "string" ? p.message : "",
+                        ...(p.requestedSchema !== undefined ? { requestedSchema: p.requestedSchema } : {}),
+                        ...(principal !== undefined ? { principal } : {}),
+                    };
+                    const answer = await onElicit(req, extra?.signal);
+                    return answer.action === "accept" ? { action: "accept", content: answer.content ?? {} } : { action: answer.action };
+                }
+                finally {
+                    health.pendingElicitations--;
+                    health.lastElicitationClosedAt = Date.now();
+                }
+            });
+        }
+        const transport = buildTransport(spec, principal, transportKind);
+        try {
+            await client.connect(transport, startupOpts);
+        }
+        catch (err) {
+            await client.close().catch(() => undefined);
+            throw err;
+        }
+        return client;
+    };
+    const lease = pool !== undefined && !elicitOn ? await pool.acquire(McpConnectionPool.keyOf(spec, principal, transportKind), dialClient, dialOpts) : undefined;
+    const client = lease !== undefined ? lease.client : await dialClient();
+    const close = () => (lease !== undefined ? lease.release() : client.close());
+    const openListing = () => {
+        const write = lease?.openListing();
+        return (tools, retained) => (write !== undefined ? write(tools, (all) => cacheMcpToolMetadata(client, all), retained) : cacheMcpToolMetadata(client, tools));
+    };
     try {
-        await client.connect(transport, startupOpts);
-        client.onclose = () => {
+        const onClosed = () => {
             health.dead = true;
             announce.fn?.();
         };
+        if (lease !== undefined)
+            lease.onClose(onClosed);
+        else
+            client.onclose = onClosed;
+        const cacheTools = openListing();
         const listed = await listToolsLenient(client, startupOpts);
         const { serverTools, serverAxes, dropped, advisories, accepted } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
-        cacheMcpToolMetadata(client, accepted);
+        cacheTools(accepted);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
-                listAllowed: !spec.allowTools || spec.allowTools.includes("list_resources"),
-                readAllowed: !spec.allowTools || spec.allowTools.includes("read_resource"),
+                listAllowed: !spec.allowTools || spec.allowTools.includes(MCP_RESOURCE_LIST_ALLOW),
+                readAllowed: !spec.allowTools || spec.allowTools.includes(MCP_RESOURCE_READ_ALLOW),
             }
             : undefined;
         const rawInstructions = client.getInstructions();
@@ -1574,6 +1599,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         return {
             status,
             client,
+            close,
+            openListing,
             health,
             announce,
             tools: serverTools,
@@ -1588,7 +1615,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         };
     }
     catch (err) {
-        await client.close().catch(() => undefined);
+        await close().catch(() => undefined);
         throw err;
     }
 }

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

@@ -1,4 +1,4 @@
-import { allowedToolNames, readDeniedEntry, readToolNameList } from "../../agents/tool-filter.js";
+import { resolveToolSubset } from "../../agents/tool-filter.js";
 const TOOL_CONTENT_ORIGIN_SET = { external: true, execution: true, local: true };
 export const TOOL_CONTENT_ORIGINS = Object.keys(TOOL_CONTENT_ORIGIN_SET);
 export function isToolContentOrigin(value) {
@@ -18,25 +18,13 @@ export function classifyToolContentOrigin(input) {
 export function withContentOrigin(tool, origin) {
     return Object.assign(tool, { contentOrigin: origin });
 }
-function selectedBy(entry, tool) {
-    return tool.name === entry || (tool.aliases?.includes(entry) ?? false);
-}
 export function delegationCallIsExternal(input) {
     if (input.faces === undefined || input.pool === undefined)
         return true;
     const face = input.requestedType === undefined ? undefined : input.faces.find((f) => f.name === input.requestedType);
     if (face === undefined)
         return true;
-    const selectedFor = (f) => {
-        const deniedList = readToolNameList(f.denyTools);
-        const d = deniedList.kind === "entries" ? deniedList.entries : [];
-        const a = allowedToolNames(f.allowTools);
-        const denies = (t) => d.some((x) => {
-            const read = readDeniedEntry(x);
-            return read.kind === "name" && selectedBy(read.name, t);
-        });
-        return input.pool.filter((t) => (a === undefined || [...a].some((x) => selectedBy(x, t))) && !denies(t));
-    };
+    const selectedFor = (f) => resolveToolSubset(input.pool, f.allowTools, f.denyTools);
     if (selectedFor(face).some((t) => input.isPolluting(t)))
         return true;
     if (face.canRedelegate === true && input.faces.some((f) => selectedFor(f).some((t) => input.isPolluting(t))))

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

@@ -5,6 +5,7 @@ import { type OriginClearanceRow } from "./origin-clearance.js";
 import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
 import { type MemoryExportBundle, type MemoryImportReport } from "./export-bundle.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionMarkOutcome, type SessionPollutionRecord, type SessionCaptureOptOutMarkOutcome, type SessionCaptureOptOutRecord, type SessionCaptureRecordStore } from "./layout.js";
+import { type SessionIncarnationResolver } from "./session-incarnation.js";
 import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryScopeEnumeration, MemorySessionHandle, ScanFinding, SessionCaptureResidueSweep } from "./types.js";
 /**
  * The RECALL-FRAMING sentence shared by every arm of the `# Memory` prompt section — the one
@@ -289,12 +290,13 @@ export interface MemoryEngineOptions {
      * for the fail-closed contract each leg must keep.
      */
     captureRecordStore?: SessionCaptureRecordStore;
-    /** the engine half of {@link import("../runner-deps.js").RunnerDeps.memorySessionIncarnation}
-     *  (that seat owns the meaning and the value's contract); resolved through
-     *  {@link createSessionIncarnationSeat}. Absent ⇒ nothing is stamped, nothing is asked for. */
-    sessionIncarnation?: (session: {
-        sessionId: string;
-    }) => string | undefined;
+    /** which occupant of a session id is running now — the session row's incarnation
+     *  ({@link import("../../engine/harness/types.js").SessionMetadata.incarnation} owns the meaning: stable
+     *  for one occupant's life, different for the next, only ever compared). The Runner fills it from the
+     *  session it acquired ({@link import("./session-incarnation.js").sessionIncarnationResolver}); a host
+     *  that builds an engine itself passes the same answer. Resolved through {@link createSessionIncarnationSeat}.
+     *  Absent ⇒ nothing is stamped, nothing is asked for, every record binds by id. */
+    sessionIncarnation?: SessionIncarnationResolver;
     /**
      * design/336 §4.2 — the delegation settlement window in ms (default
      * {@link DEFAULT_HOLD_SETTLE_TIMEOUT_MS} = 72h): a `pending` settlement row older than this is
@@ -838,8 +840,6 @@ export interface SessionMemoryStatus {
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
-    /** {@link memoryDir}'s physical form as this engine first mounted it; every later mount compares, never re-resolves. */
-    private mountedRoot;
     private readonly controlDir;
     private readonly now;
     private readonly perScopeBudgetBytes;
@@ -855,8 +855,10 @@ export declare class MemoryEngine {
     /** {@link MemoryEngineOptions.onIncident} — the advisory disclosure seat (partition + announce codes). */
     private readonly onIncident;
     private unsettleableDisclosed;
-    /** A backend-pinned directory (FileBackend zero-copy detection). */
-    private readonly backendPinnedRoot?;
+    /** The backend pins its own directory (the File backend), which the constructor proved is the memory dir:
+     *  the entry files ARE the backend's storage (zero-copy). False = a copy-out projection of a backend
+     *  without a directory. */
+    private readonly zeroCopy;
     constructor(opts: MemoryEngineOptions);
     /** the session identity axis (resolution + disclosures: `session-incarnation.ts`). */
     private readonly incarnation;
@@ -1624,8 +1626,8 @@ export declare class MemoryEngine {
      */
     sessionMemoryStatus(sessionId: string): Promise<SessionMemoryStatus>;
     /** The committed, side-effect-free audit read: the adoption-restricted committed view when the
-     *  backend offers one (zero-copy File — ledger+shadow, no disk adoption), else the non-adopting
-     *  retrieval view (copy-out File), else the backend itself (Pg/TiDB shapes — naturally committed
+     *  backend offers one (the File backend — ledger+shadow, no disk adoption), else a non-adopting
+     *  retrieval view where one is offered, else the backend itself (Pg/TiDB shapes — naturally committed
      *  and side-effect-free per the getByIds contract clause). */
     private committedAuditFace;
     /** The COMMITTED header listing of `scopes` through the face above: the name source of the
@@ -1745,9 +1747,9 @@ export declare class MemoryEngine {
      * side-effect-free, or assembling one harvest mutates the store it is reading. Reading order:
      *  - zero-copy File: the control-plane shadow IS the committed state (the disk file is the
      *    session's own working copy — exactly what must NOT serve as the committed baseline);
-     *  - copy-out with a `retrievalView` face (File): the lock-free non-adopting view;
-     *  - twins (Pg/TiDB shapes): plain `getByIds` — naturally committed-state and side-effect-free
-     *    (the contract clause on {@link MemoryBackend.getByIds}).
+     *  - copy-out (a backend without a directory): its `retrievalView` face when it has one, else plain
+     *    `getByIds` — twins (Pg/TiDB shapes) are naturally committed-state and side-effect-free (the
+     *    contract clause on {@link MemoryBackend.getByIds}).
      */
     private committedFrontmatterFor;
     /** L4/C-F9 (S2-0) — capture a gate-rejected file into control-plane quarantine FROM THE SCANNED
@@ -1788,17 +1790,25 @@ export declare class MemoryEngine {
      * @returns the rejection to report, or `undefined` when the index is clean/absent.
      */
     private gateDerivedIndex;
-    /** The file backend's verdict at an act the engine itself performs on a store path ({@link
-     *  landsOutsideStore}): throws `memory.target_outside_store` when `path` would land outside `root`;
-     *  each caller's existing failure lane reports it. `root` is the mount's canonical root where a
-     *  handle exists, so a root re-pointed after the mount is judged against the one it mounted. */
+    /** The act gate at every write, rename or removal the engine itself performs under the memory dir: the
+     *  anchor is read at the act ({@link assertRootAnchored}, with the session's `handle` where one exists),
+     *  and `path` must land inside the anchored root ({@link landsOutsideStore}) — else `memory.target_outside_store`;
+     *  each caller's existing failure lane reports it. Read at the act, not at the face's head: a face awaits
+     *  between its first read and its writes, and a root re-pointed (or re-anchored) in that window is judged here. */
     private refuseOutsideStore;
+    /** {@link refuseOutsideStore} as a value, for a site whose failure lane is a report row rather than a
+     *  throw: the refusal's text, or `undefined` when the act may proceed. */
+    private storeActRefusedText;
+    /** The memory dir against its anchor ({@link anchorStoreRoot}), read every time: at every mount and at the head
+     *  of every face acting on the memory dir itself; answers the anchored root. With a `handle`, its mount root
+     *  must be the anchored one too (a handle mounted before a re-anchor names a tree the store no longer has). */
+    private assertRootAnchored;
     /** Projection write: reads the target to skip a no-op, then writes — the same check-then-use shape
      *  as the containment restores, so it takes the same no-follow write. A link at a projection path
      *  is never a supported layout (the harvest scan refuses symlinked entry files outright), and this
      *  site already reports write failures by throwing, so ELOOP joins the failures it already had. A
-     *  target whose directory resolves outside `root` (a directory on the path is a link) is refused
-     *  the same way, before anything is read or written ({@link landsOutsideStore}). */
+     *  target whose directory resolves outside the anchored root (a directory on the path is a link) is
+     *  refused the same way, before anything is read or written ({@link refuseOutsideStore}). */
     private writeIfChanged;
     /** Persist the canonical projection back to the session file (id minting / frontmatter completion).
      *  C-F6 (S2-0): called ONLY after the backend transaction committed — never ahead of the journal
@@ -1822,7 +1832,7 @@ export declare class MemoryEngine {
     private repairProjectionSeat;
     /**
      * #366 — validate a projection-debt row against the COMMITTED state (side-effect-free read: the
-     * retrievalView face in copy-out, never the File backend's adopting `getByIds`). Three-valued on
+     * backend's retrievalView face in copy-out when it offers one). Three-valued on
      * purpose: `valid` binds, `stale` clears the row (the seat claim dissolved — entry gone, moved or
      * renamed), and `unknown` (committed state unreadable) makes the caller DEFER the file fail-closed
      * — treating a transient read fault as "stale" would clear the row and mint the very duplicate