@sema-agent/core 7.54.1 → 7.56.0

package/dist/core/host-floor.js

@@ -0,0 +1,206 @@
+import { isIP } from "node:net";
+import { HOST_UNREADABLE_SENTENCE, callHostTargetOf, hostOfUrl, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+import { describeFault, isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { DECLARATION_RECEIPT_MODE } from "./own-property-receipt.js";
+function isPrivateV4(ip) {
+    const o = ip.split(".").map(Number);
+    if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+        return true;
+    const [a = -1, b = -1] = o;
+    return (a === 127 ||
+        a === 10 ||
+        a === 0 ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        (a === 100 && b >= 64 && b <= 127));
+}
+function embeddedV4(h) {
+    const fromHex = (hi, lo) => {
+        const a = parseInt(hi, 16), c = parseInt(lo, 16);
+        return `${(a >> 8) & 255}.${a & 255}.${(c >> 8) & 255}.${c & 255}`;
+    };
+    let m = /^(?:::ffff:|64:ff9b::)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(h);
+    if (m)
+        return m[1];
+    m = /^(?:::ffff:|64:ff9b::)([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
+    const [, hi, lo] = m ?? [];
+    return hi !== undefined && lo !== undefined ? fromHex(hi, lo) : undefined;
+}
+export function isPrivateHost(host) {
+    const h = host
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.+$/, "")
+        .toLowerCase();
+    if (h === "localhost")
+        return true;
+    const fam = isIP(h);
+    if (fam === 0)
+        return false;
+    if (fam === 4)
+        return isPrivateV4(h);
+    const v4 = embeddedV4(h);
+    if (v4)
+        return isPrivateV4(v4);
+    if (h === "::1" || h === "::")
+        return true;
+    return /^fe[89ab]/.test(h) || /^f[cd]/.test(h) || /^fe[c-f]/.test(h);
+}
+export const HOST_FLOOR_INVALID_CODE = "config.host_floor_invalid";
+const FLOOR_MEMBERS = ["deny", "only"];
+function floorInvalid(what) {
+    return Object.assign(new Error(`RunnerDeps.hostFloor ${what} — a host floor that does not read is refused whole, never half-armed (an entry is a host pattern: \`example.com\` or \`*.example.com\`).`), { code: HOST_FLOOR_INVALID_CODE });
+}
+function readEntries(value, member) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw floorInvalid(`.${member} must be a list of host patterns (got ${value === null ? "null" : typeof value})`);
+    const list = value;
+    const patterns = [];
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        if (typeof entry !== "string")
+            throw floorInvalid(`.${member}[${i}] must be a string (got ${entry === null ? "null" : typeof entry})`);
+        const read = readHostPattern(entry);
+        if ("problem" in read) {
+            const why = read.problem === "every_host" ? "names every host"
+                : read.problem === "inner_wildcard" ? "carries a `*` other than a leading `*.`"
+                    : read.problem === "below_address" ? "names hosts below an address, which has none"
+                        : read.problem === "empty_label" ? "names a host with an empty label (a leading or doubled dot) — write the host itself, and every host below a domain as `*.<domain>`"
+                            : "is more or less than a host (a scheme, a port, a path, credentials or whitespace)";
+            throw floorInvalid(`.${member}[${i}] "${inlineUntrusted(entry, 120)}" ${why}`);
+        }
+        patterns.push(read.pattern);
+    }
+    return patterns;
+}
+function covers(d, o) {
+    if (d.match === "host")
+        return o.match === "host" && o.host === d.host;
+    return o.host === d.host ? o.match === "subdomain" : hostPatternAdmits(d, o.host);
+}
+export function receiveHostFloor(declared) {
+    if (declared === undefined)
+        return undefined;
+    const received = receive(declared, DECLARATION_RECEIPT_MODE);
+    if (!received.ok)
+        throw floorInvalid(`could not be read as plain data — ${describeFault(received.fault)}`);
+    return received.value;
+}
+export function compileHostFloor(declared) {
+    const value = receiveHostFloor(declared);
+    if (value === undefined)
+        return undefined;
+    if (!isPlainRecord(value))
+        throw floorInvalid(`must be a record { deny?, only? } (got ${value === null ? "null" : Array.isArray(value) ? "a list" : typeof value})`);
+    const unknownMember = Object.keys(value).find((k) => !FLOOR_MEMBERS.includes(k));
+    if (unknownMember !== undefined)
+        throw floorInvalid(`has a member "${inlineUntrusted(unknownMember, 60)}" — its members are \`deny\` and \`only\``);
+    const deny = readEntries(value.deny, "deny") ?? [];
+    const only = readEntries(value.only, "only");
+    for (const o of only ?? []) {
+        const d = deny.find((candidate) => covers(candidate, o));
+        if (d !== undefined)
+            throw floorInvalid(`.only entry "${spelledHostPattern(o)}" is wholly denied by the .deny entry "${spelledHostPattern(d)}" — it could never admit a host`);
+    }
+    const reach = (host) => deny.some((d) => hostPatternAdmits(d, host)) ? "denied" : only !== undefined && !only.some((o) => hostPatternAdmits(o, host)) ? "outside_only" : "admitted";
+    return Object.freeze({
+        entries: Object.freeze({ deny: Object.freeze(deny.map(spelledHostPattern)), ...(only !== undefined ? { only: Object.freeze(only.map(spelledHostPattern)) } : {}) }),
+        posture: Object.freeze({ onlyMode: only !== undefined, denyCount: deny.length, onlyCount: only?.length ?? 0 }),
+        reach,
+        lifts: (host) => only !== undefined && reach(host) === "admitted",
+    });
+}
+export function floorRefusal(reading, floor) {
+    if ("unreadable" in reading)
+        return `${HOST_UNREADABLE_SENTENCE[reading.unreadable]}, and this deployment's host floor admits only a host it can read`;
+    const reach = floor.reach(reading.host);
+    if (reach === "admitted")
+        return undefined;
+    const host = inlineUntrusted(reading.host, 253);
+    return reach === "denied" ? `host "${host}" is denied by this deployment's host floor (hostFloor.deny)` : `host "${host}" is outside the hosts this deployment reaches (hostFloor.only)`;
+}
+export function hostFloorPolicy(floor) {
+    return {
+        check: (req) => {
+            const reading = callHostTargetOf(req, "tighten");
+            const refused = reading === undefined ? undefined : floorRefusal(reading, floor);
+            return refused === undefined ? { action: "allow" } : { action: "deny", message: `${refused} — no rule, mode or approval clears the deployment's host floor`, decisionReason: "rule" };
+        },
+    };
+}
+export function hopRefusal(url, floor, privateFloor) {
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return `a non-http(s) URL (${inlineUntrusted(url.protocol, 40)}) was refused`;
+    const reading = hostOfUrl(url.toString());
+    if ("unreadable" in reading)
+        return `${HOST_UNREADABLE_SENTENCE[reading.unreadable]}; refused`;
+    const floored = floor !== undefined ? floorRefusal(reading, floor) : undefined;
+    if (floored !== undefined)
+        return `${floored}; refused`;
+    if (privateFloor && isPrivateHost(reading.host) && floor?.lifts(reading.host) !== true) {
+        return `host "${inlineUntrusted(reading.host, 253)}" is private/internal; refused (SSRF guard — reachable only when this deployment's hostFloor.only names it)`;
+    }
+    return undefined;
+}
+export const HOST_FLOOR_REFUSED_CODE = "config.host_floor_refused";
+export function peerRequestRefusal(what, url, floor) {
+    const reason = hopRefusal(url, floor, false);
+    return reason === undefined ? undefined : Object.assign(new Error(`${what} is not contacted — ${reason}`), { code: HOST_FLOOR_REFUSED_CODE });
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function release(res) {
+    const body = res.body;
+    if (typeof body?.cancel === "function")
+        void body.cancel().catch(() => undefined);
+}
+function followedInit(status, init) {
+    if (!(status === 303 || ((status === 301 || status === 302) && init.method === "POST")) || init.method === "GET" || init.method === "HEAD")
+        return init;
+    const BODY_HEADERS = ["content-type", "content-encoding", "content-language", "content-location", "content-length"];
+    const headers = Object.fromEntries(Object.entries(init.headers).filter(([k]) => !BODY_HEADERS.includes(k.toLowerCase())));
+    return { method: "GET", headers, ...(init.signal !== undefined ? { signal: init.signal } : {}) };
+}
+export async function fetchFollowing(doFetch, start, init, law) {
+    let current = start;
+    let hopInit = init;
+    for (let hop = 0; hop <= law.maxRedirects; hop++) {
+        const refused = law.refusal(current);
+        if (refused !== undefined)
+            return { kind: "refused", reason: refused };
+        const res = await doFetch(current.toString(), {
+            method: hopInit.method,
+            headers: hopInit.headers,
+            redirect: "manual",
+            ...(hopInit.body !== undefined ? { body: hopInit.body } : {}),
+            ...(hopInit.signal !== undefined ? { signal: hopInit.signal } : {}),
+        });
+        law.onResponse?.(res);
+        if (!REDIRECT_STATUSES.has(res.status))
+            return { kind: "answered", res };
+        const location = res.headers.get("location");
+        if (!location)
+            return { kind: "answered", res };
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            release(res);
+            return { kind: "refused", reason: `invalid redirect Location: ${inlineUntrusted(location, 200)}` };
+        }
+        const nextRefused = law.refusal(next);
+        if (nextRefused !== undefined) {
+            release(res);
+            return { kind: "refused", reason: nextRefused };
+        }
+        if (!law.follows(current, next))
+            return { kind: "unfollowed", res, from: current, to: next };
+        release(res);
+        hopInit = followedInit(res.status, hopInit);
+        current = next;
+    }
+    return { kind: "too_many" };
+}

package/dist/core/host-target.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The HOST vocabulary, one home for how a host is spelled and read:
+ *  · {@link hostOfSpelling} — the RULE side: the host a `<Tool>(domain:<host>)` rule names;
+ *  · {@link hostOfUrl} — the CALL side: the host a URL names, which every host-rule judge reads as the call's subject and the
+ *    engine's fetch tool reads as the host it connects to (one reading, two readers);
+ *  · {@link callHostTargetOf} — which argument of a call carries that URL: the host face's protective and declared readings.
+ * Both sides go through the URL parser (lower case, IDN in its ASCII form, a full-width dot folded, an IPv4 shorthand expanded)
+ * and read trailing dots off; a call's host that does not read back as itself through the rule side's reader names no host a rule
+ * can be judged on, so a rule and a call that name one host always name it in one spelling.
+ *
+ * Leaf module: it reads the catalog's host slots (the protective floor) and the name-reading seat, nothing else.
+ */
+import { type ToolCallLike } from "./tool-registry.js";
+/**
+ * THE reading of a host's spelling: the host as the URL parser reads it (lower case, IDN in its ASCII form, a full-width dot
+ * folded, an IPv4 shorthand expanded, trailing dots read off), or why it names none — `empty_label` for a name with an empty
+ * label once its trailing dots are read off (`.evil.test`, `a..test`: no host has one, and nothing a rule or a floor entry is
+ * matched against ever does), `not_a_host` for a spelling that is more or less than a host (empty, carrying whitespace or a
+ * separator a URL reads as something else, a port — a `:` outside an address's brackets —, credentials, a path).
+ */
+export declare function readSpelledHost(spelled: string): {
+    readonly host: string;
+} | {
+    readonly problem: "empty_label" | "not_a_host";
+};
+/** The host a spelling names ({@link readSpelledHost}), or undefined when it names none. */
+export declare function hostOfSpelling(spelled: string): string | undefined;
+/** Is this host (as {@link hostOfUrl} reads it) an address — the URL parser's IPv4 form or a bracketed IPv6? */
+export declare function isAddressHost(host: string): boolean;
+/** A host pattern: one exact host (`host`), or every host BELOW a domain at any depth, never the domain itself (`subdomain`). */
+export interface HostPattern {
+    readonly match: "host" | "subdomain";
+    readonly host: string;
+}
+/** Why a spelling is no host pattern: `*` alone (every host), a `*` other than a leading `*.`, a host with an empty label (a
+ *  leading or doubled dot — "this domain and every host below" is two patterns, `example.com` and `*.example.com`), more or less
+ *  than a host, a `*.` over an address (an address has no subdomains). */
+export type HostPatternProblem = "every_host" | "inner_wildcard" | "empty_label" | "not_a_host" | "below_address";
+/**
+ * THE reader of a host pattern's spelling — `example.com` or `*.example.com` — for every place one is written: the content of a
+ * `<Tool>(domain:<pattern>)` rule and an entry of the deployment's host floor. The `*.` operator is the spelling's leading two
+ * characters; the host after it is read by {@link readSpelledHost}, must hold no `*` as read (a full-width or small asterisk the
+ * parser folds included) and must read back as itself; each caller words its own refusal from the problem.
+ */
+export declare function readHostPattern(spelled: string): {
+    readonly pattern: HostPattern;
+} | {
+    readonly problem: HostPatternProblem;
+};
+/** A pattern as it is written back: the host, or `*.` and the domain. */
+export declare function spelledHostPattern(pattern: HostPattern): string;
+/** Does the pattern reach this host (as {@link hostOfUrl} reads it)? `host`: equal; `subdomain`: a name ending in `.<domain>` with
+ *  at least one label before it and no empty label. */
+export declare function hostPatternAdmits(pattern: HostPattern, host: string): boolean;
+/** Why a URL names no host a rule can be judged on — the closed set the fetch tool maps to its own refusal sentences:
+ *  not a string; not a URL; not http(s); credentials in it; a host that does not read back as itself once its trailing dots
+ *  are read off (`https://2130706433../` — the parser keeps the name, the rule side reads `127.0.0.1`). */
+export declare const HOST_UNREADABLE_REASONS: readonly ["not_text", "not_url", "not_http", "credentials", "unstable"];
+export type HostUnreadableReason = (typeof HOST_UNREADABLE_REASONS)[number];
+/** The host a URL names, or why it names none. */
+export type HostReading = {
+    readonly host: string;
+} | {
+    readonly unreadable: HostUnreadableReason;
+};
+/** The words a refusal states for each unreadable reason. */
+export declare const HOST_UNREADABLE_SENTENCE: Readonly<Record<HostUnreadableReason, string>>;
+/** THE call-side reading of a URL: the host it names (lower case, IDN in its ASCII form, trailing dots read off), or why it
+ *  names none ({@link HostUnreadableReason}). */
+export declare function hostOfUrl(value: unknown): HostReading;
+/** Which reading a judge takes: `tighten` for a deny, an ask and the unreadable law; `grant` for an allow. */
+export type HostReadingDirection = "tighten" | "grant";
+/**
+ * The host a call reaches as every host-rule judge reads it — the rule policy's host lane, a person's stored rows, the entry
+ * lists, the approval card's offer — or undefined when the call has no URL slot in that direction:
+ *  · `tighten` — the PROTECTIVE reading: the call face's own slot, else the catalog's slot under the first name the call
+ *    answers to that declares one (a bare request, or a face that declares none). Borrowing a slot can only add a host to
+ *    judge, so a deny or an ask keeps reaching a same-name tool;
+ *  · `grant` — the DECLARED reading: the call face's own slot only. A tool that declares none (a caller's tool that merely took
+ *    the fetch tool's name, a bare request) is not the tool the catalog describes, and no allow by host reaches it.
+ * The slot's value is read by {@link hostOfUrl}; a value that names no host answers `{ unreadable }`, and each judge's law
+ * says what that means for its direction.
+ */
+export declare function callHostTargetOf(call: ToolCallLike, direction: HostReadingDirection): HostReading | undefined;

package/dist/core/host-target.js

@@ -0,0 +1,92 @@
+import { hostTargetOf } from "./tool-registry.js";
+import { seatOf } from "./tool-name-readings.js";
+export function readSpelledHost(spelled) {
+    if (spelled === "" || /[\s/\\@?#%]/.test(spelled) || (spelled.includes(":") && !/^\[[^\]]+\]$/.test(spelled)))
+        return { problem: "not_a_host" };
+    let url;
+    try {
+        url = new URL(`https://${spelled}/`);
+    }
+    catch {
+        return { problem: "not_a_host" };
+    }
+    if (url.port !== "" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "")
+        return { problem: "not_a_host" };
+    const host = url.hostname.replace(/\.+$/, "");
+    if (host === "")
+        return { problem: "not_a_host" };
+    return !host.startsWith("[") && host.split(".").includes("") ? { problem: "empty_label" } : { host };
+}
+export function hostOfSpelling(spelled) {
+    const read = readSpelledHost(spelled);
+    return "host" in read ? read.host : undefined;
+}
+export function isAddressHost(host) {
+    return host.startsWith("[") || /^\d+\.\d+\.\d+\.\d+$/.test(host);
+}
+export function readHostPattern(spelled) {
+    if (spelled === "*")
+        return { problem: "every_host" };
+    const below = spelled.startsWith("*.");
+    const read = readSpelledHost(below ? spelled.slice(2) : spelled);
+    if ("problem" in read)
+        return read;
+    const host = read.host;
+    if (host.includes("*"))
+        return { problem: "inner_wildcard" };
+    if (hostOfSpelling(host) !== host)
+        return { problem: "not_a_host" };
+    if (below && isAddressHost(host))
+        return { problem: "below_address" };
+    return { pattern: { match: below ? "subdomain" : "host", host } };
+}
+export function spelledHostPattern(pattern) {
+    return pattern.match === "subdomain" ? `*.${pattern.host}` : pattern.host;
+}
+export function hostPatternAdmits(pattern, host) {
+    if (pattern.match === "host")
+        return host === pattern.host;
+    if (isAddressHost(host) || !host.endsWith(`.${pattern.host}`))
+        return false;
+    const labels = host.slice(0, -(pattern.host.length + 1));
+    return labels !== "" && !labels.split(".").includes("");
+}
+export const HOST_UNREADABLE_REASONS = Object.freeze(["not_text", "not_url", "not_http", "credentials", "unstable"]);
+export const HOST_UNREADABLE_SENTENCE = Object.freeze({
+    not_text: "the URL argument is not a string",
+    not_url: "the URL does not parse",
+    not_http: "the URL is not http(s)",
+    credentials: "the URL carries credentials",
+    unstable: "the URL's host does not read back as one host",
+});
+export function hostOfUrl(value) {
+    if (typeof value !== "string")
+        return { unreadable: "not_text" };
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { unreadable: "not_url" };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return { unreadable: "not_http" };
+    if (url.username !== "" || url.password !== "")
+        return { unreadable: "credentials" };
+    const host = url.hostname.replace(/\.+$/, "");
+    return host !== "" && hostOfSpelling(host) === host ? { host } : { unreadable: "unstable" };
+}
+export function callHostTargetOf(call, direction) {
+    const slot = hostSlotOf(call, direction);
+    if (slot === undefined)
+        return undefined;
+    const args = call.args;
+    const own = typeof args === "object" && args !== null && !Array.isArray(args) && Object.hasOwn(args, slot.param);
+    return hostOfUrl(own ? args[slot.param] : undefined);
+}
+function hostSlotOf(call, direction) {
+    const declared = call.face?.hostTarget;
+    if (declared !== undefined || direction === "grant")
+        return declared;
+    return seatOf("floor.protectiveHostTarget", { get: hostTargetOf }, call)?.value;
+}

package/dist/core/image-downsample.d.ts

@@ -7,7 +7,7 @@
  * `core/types.ts`) needed no changes on this car.
  */
 /**
- * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value = CC 2.1.187
+ * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value =
  * `API_IMAGE_MAX_BASE64_SIZE` (constants/apiLimits.ts:22, "5 * 1024 * 1024 // 5 MB" — the hard Anthropic API
  * limit on a base64 image block; CC resizes/compresses down to fit UNDER it, imageResizer.ts). An MCP server
  * returning a bigger image previously passed straight through = a context/API bomb.

package/dist/core/lsp-diagnostics.d.ts

@@ -83,7 +83,7 @@ export declare class LspDiagnosticsRegistry {
  *  the map; a judgment that fails withholds them all). The run's drain already marked them delivered, so they do not come back. */
 export declare function withholdListedDiagnostics(files: LspFileDiagnostics[], withheldOf: (uris: readonly string[]) => Promise<ReadonlyMap<string, unknown>>): Promise<LspFileDiagnostics[]>;
 /**
- * CC 198 `formatDiagnosticsSummary` (198:320480-320499), verbatim shape:
+ * `formatDiagnosticsSummary` shape:
  * ```
  * {basename}:
  *   {symbol} [Line {line+1}:{col+1}] {message}[ [{code}]][ ({source})]
@@ -96,16 +96,16 @@ export declare function withholdListedDiagnostics(files: LspFileDiagnostics[], w
  * repository. They land inside the `<new-diagnostics>` envelope, and (since this block is now
  * delivered inside a marked reminder shell) inside an authority-marked reminder too, so a diagnostic
  * message carrying `</new-diagnostics>` closed the envelope and placed server text at the top level
- * of engine-authored authority. CC 223 does not neutralize here either — a deliberate, disclosed
+ * of engine-authored authority. The reference does not neutralize here either — a deliberate, disclosed
  * hardening divergence: CC ships the same block inside the same reminder shell, so the hole exists on
  * both sides and only the fix is ours. Neutralization runs BEFORE the join, so the 4000-char cap
  * still bounds the FINAL text and can never cut inside a neutralized marker's own bytes.
  */
 export declare function formatDiagnosticsSummary(files: LspFileDiagnostics[]): string;
-/** CC 198 model-facing injection block (198:320500-320503), verbatim framing.
+/** Model-facing injection block.
  *
  *  DELIVERY (design/319 sibling work): the runner shells this block in a MARKED `<system-reminder>`
- *  before steering it — CC 223 `case "diagnostics"` does the same (`ih([Vr({content: …})])` → the
+ *  before steering it — the reference's `case "diagnostics"` does the same (`ih([Vr({content: …})])` → the
  *  reminder wrap), and until that was matched this was the engine's only authority text reaching the
  *  model as a bare block with no provenance mark at all. The block's own bytes are unchanged; the
  *  shell is applied at the delivery site (runtask), not baked in here, so this exported renderer keeps

package/dist/core/lsp.d.ts

@@ -58,8 +58,8 @@ export interface LspSymbolInfo {
  * answered null/[] — today's behavior byte-for-byte, and what an external manager returning bare
  * `{kind:"none"}` keeps getting). The failure reasons exist because one literal "No results." used to cover
  * both real emptiness and every transport-level fault — a findReferences that TIMED OUT read as "no
- * references, safe to delete" (CC 2.1.220 keeps these apart: `Error performing ${operation}: ...` vs the
- * plain empty-result strings, (pretty220.js:474840, historical; not relocated in 250 — see cc-250 anchors)).
+ * references, safe to delete" (the reference keeps these apart: `Error performing ${operation}: ...` vs the
+ * plain empty-result strings).
  */
 export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item"
 /** HRD-LSP-7: the QUERIED file could not be read for the didOpen/didChange re-sync (deleted between the
@@ -246,7 +246,7 @@ export interface LspTransport {
  *  gate (no read face) only; a gated read is the admitted held object's ({@link LspReadAdmission}). TOC = local fs; TOB =
  *  the sandbox ExecutionEnv. */
 export type LspReadText = (filePath: string, signal?: AbortSignal) => Promise<string>;
-/** CC 2.1.220's LSP file cap (10MB — `File too large for LSP analysis`, (pretty220.js:474745, historical; not relocated in 250 — see cc-250 anchors)). Single-sourced
+/** The LSP file cap (10MB — `File too large for LSP analysis`). Single-sourced
  *  in core: the TOOL-layer check in {@link createLspTool} (the model-visible enforcement, CC-parity) and the
  *  defense-in-depth throw in the engine's `defaultLspReadText` must agree on one number. */
 export declare const MAX_LSP_FILE_BYTES: number;

package/dist/core/mailbox-store.d.ts

@@ -221,6 +221,10 @@ export interface MailboxStore {
      *  (the in-memory reference); absent = undeclared (the CC inbox adapter). Read by
      *  {@link mailboxCrossProcessMountVerdict}; any other value is a malformed declaration and refuses. */
     readonly crossProcessSafe?: boolean;
+    /** WHICH boxes this store serves, as an opaque word: two store objects with the same identity read and write
+     *  the same boxes (one backing directory, one database), in whichever process they live. Absent = the store
+     *  cannot say — and then no peer may assume that a box it appends to here is one another session drains. */
+    readonly identity?: string;
     /** Durably park one message. Refuses `"mailbox.recipient_tombstoned"` when the backend can see
      *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;

package/dist/core/mcp-connection-pool.d.ts

@@ -18,6 +18,7 @@
  * answer to its questions belongs to the leg that is waiting on it.
  */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ConnectionListing, type LenientListedTool } from "./mcp-server-link.js";
 import type { McpServerSpec } from "./mcp-server-spec.js";
 /** The slice of a listed tool the SDK client caches per connection (its output validator, its task-support flags). */
 export interface McpToolMeta {
@@ -31,6 +32,8 @@ export type McpListingWriter = (tools: ReadonlyArray<McpToolMeta>, apply: (all:
 /** One leg's hold on a pooled connection. */
 export interface McpLease {
     readonly client: Client;
+    /** The connection's listing, one record shared by every holder (mcp-server-link.ts `ConnectionListing`). */
+    readonly listing: ConnectionListing<LenientListedTool>;
     /**
      * Open a `tools/list` round trip on the connection — call it BEFORE the request. The returned writer records the result twice over:
      * as the connection's metadata for each listed tool, at this listing's version (its place in the order listings were opened on the
@@ -65,13 +68,26 @@ export declare class McpConnectionPool {
      * Lease the connection for `key`, dialling it with `dial` when none is live. `fresh` replaces the pool's current connection with a new
      * dial (a re-dial): the connection it replaces lives on until its other holders release it. Resolves `undefined` once the pool is
      * closed — the caller dials for itself. A dial that rejects rejects every waiter of that dial, and the pool keeps nothing of it.
+     *
+     * `signal` is the CALLER's abort, and it is that caller's alone: it ends this caller's wait (rejecting with its reason) and leaves the dial
+     * to the legs still waiting on it. The dial belongs to the pool: it is given a stop of its own, fired when the last leg waiting on it has
+     * walked away, so a leg's abort neither holds nor cancels a dial another leg still needs.
      */
-    acquire(key: string, dial: () => Promise<Client>, opts?: {
+    acquire(key: string, dial: (stop: AbortSignal) => Promise<Client>, opts?: {
         fresh?: boolean;
+        signal?: AbortSignal;
     }): Promise<McpLease | undefined>;
+    /**
+     * Wait for a dial as one of its legs; this leg's abort ends only this leg's wait. The last leg to walk away abandons the dial in the
+     * same step as its abort (see {@link abandon}) — the table holds only dials some leg still waits on, so a leg that asks next dials afresh
+     * instead of joining a stopped dial and failing with another leg's abort.
+     */
+    private waitOn;
+    /** A dial nobody waits on any more: out of the table and stopped, and — had it landed already — the connection nobody leased is let go, so such a dial leaves no connection behind. */
+    private abandon;
     /** Make the next lease of `key` dial a new connection. */
     detach(key: string): void;
-    /** No lease is granted after this; the connections still held stay open until their holders release them. */
+    /** No lease is granted after this; the connections still held stay open until their holders release them — one nobody holds is closed now. */
     close(): void;
     /** How many connections the pool holds open right now (for the lifecycle pins). */
     get live(): number;

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

@@ -1,4 +1,5 @@
 import { canonicalize } from "./canonical-json.js";
+import { ConnectionListing } from "./mcp-server-link.js";
 export class McpConnectionPool {
     entries = new Map();
     dialing = new Map();
@@ -17,25 +18,67 @@ export class McpConnectionPool {
     async acquire(key, dial, opts) {
         if (this.shut)
             return undefined;
+        opts?.signal?.throwIfAborted();
         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 stop = new AbortController();
+                const started = this.dialNew(key, this.generation.get(key) ?? 0, () => dial(stop.signal));
+                const own = { promise: started, waiters: 0, stop };
+                pending = own;
+                this.dialing.set(key, own);
                 const settled = () => {
-                    if (this.dialing.get(key) === started)
+                    if (this.dialing.get(key) === own)
                         this.dialing.delete(key);
                 };
                 void started.then(settled, settled);
             }
-            entry = await pending;
+            entry = await this.waitOn(key, pending, opts?.signal);
         }
         return this.lease(entry);
     }
+    async waitOn(key, dial, signal) {
+        dial.waiters++;
+        let waiting = true;
+        const stopWaiting = () => {
+            if (waiting)
+                dial.waiters--;
+            waiting = false;
+        };
+        try {
+            if (signal === undefined)
+                return await dial.promise;
+            return await new Promise((resolve, reject) => {
+                const walkAway = () => {
+                    stopWaiting();
+                    if (dial.waiters === 0)
+                        this.abandon(key, dial, signal.reason);
+                    reject(signal.reason);
+                };
+                signal.addEventListener("abort", walkAway, { once: true });
+                dial.promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", walkAway));
+            });
+        }
+        finally {
+            stopWaiting();
+        }
+    }
+    abandon(key, dial, reason) {
+        if (this.dialing.get(key) === dial)
+            this.dialing.delete(key);
+        dial.stop.abort(reason);
+        dial.promise.then((entry) => {
+            if (entry.refs > 0 || entry.closed)
+                return;
+            entry.current = false;
+            if (this.entries.get(key) === entry)
+                this.entries.delete(key);
+            void entry.client.close().catch(() => undefined);
+        }, () => undefined);
+    }
     detach(key) {
         this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
         const e = this.entries.get(key);
@@ -47,6 +90,9 @@ export class McpConnectionPool {
     }
     close() {
         this.shut = true;
+        for (const e of [...this.entries.values()])
+            if (e.refs === 0 && !e.closed)
+                void e.client.close().catch(() => undefined);
     }
     get live() {
         let n = 0;
@@ -57,7 +103,7 @@ export class McpConnectionPool {
     }
     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 };
+        const entry = { client, listing: new ConnectionListing(), 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)
@@ -86,6 +132,7 @@ export class McpConnectionPool {
         };
         const lease = {
             client: entry.client,
+            listing: entry.listing,
             onClose: (fn) => {
                 mine.add(fn);
                 entry.listeners.add(fn);

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

@@ -120,14 +120,17 @@ export type McpExchangeOutcome = McpFailureKind | "completed";
  *  mint of the record — no two sites can disagree about the word, about which words may carry
  *  `errorCode`, or about what a completed exchange proves. */
 export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
+/** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
+export type McpRequestSite = {
+    phase: "request";
+    session?: true;
+};
 /** Where the failure was judged: at the dial (connect + initial listing), where an errno on a stdio
  *  transport is the child process failing to spawn, or on a request over an established connection. */
 export type McpFailureSite = {
     phase: "connect";
     transport: "stdio" | "http" | undefined;
-} | {
-    phase: "request";
-};
+} | McpRequestSite;
 /**
  * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
  * `kind === "http_status"`.
@@ -213,4 +216,20 @@ export interface HttpTransportFailure {
     delivered: McpDelivered;
     httpStatus?: number;
 }
-export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;
+export declare function describeHttpTransportFailure(err: unknown, at?: McpRequestSite): HttpTransportFailure | undefined;
+/**
+ * The one reading of a lost session: a request that carried the session id the server issued at the handshake (`at.session`) was
+ * answered 404 by the HTTP endpoint — the protocol's word for a session it no longer knows (a restart, a reaped session). It is the
+ * server's REPORT, not a proof that nothing ran: the call lane sends the request again once on a fresh session, and every face that
+ * renders the failure names it ({@link LOST_SESSION}), while its record stays the table's (`http_status`, `delivered: "unknown"`) — a
+ * server that executed the request and then answered 404 ran it. Read from the thrown value's structure and the site, never from the
+ * body's text. Nothing else qualifies: a 5xx, a timeout or a lost pipe leave the outcome unknown, a protocol error or a tool's own error
+ * means the server processed the call, a 400 is the protocol's word for a request that lacked its session header (a server that answers
+ * an unknown session 400 with words saying so is not read by its words), and a 404 on a connection that holds no session id is an
+ * endpoint answering, not a session ending.
+ */
+export declare function sessionGone(err: unknown, at: McpFailureSite): boolean;
+/** What every face says of a lost session ({@link sessionGone}). */
+export declare const LOST_SESSION = "the server reported the session the request was sent on gone (its HTTP endpoint answered 404 to the session id it issued)";
+/** A failure's text, with a lost session ({@link sessionGone}) named ahead of it — for a face that renders the failure as one line. */
+export declare function namingLostSession(err: unknown, at: McpRequestSite, text: string): string;