@zackbart/connecta 0.34.0 → 0.35.0

package/dist/native-recovery.js

@@ -0,0 +1,52 @@
+/** Adapt only Connecta error envelopes; successful downstream payloads stay untouched. */
+export function nativeRecovery(result, executeCode, wireName) {
+    const response = result;
+    const body = response?.structuredContent;
+    if (!response?.isError || !body || typeof body.error !== "object" || !body.error)
+        return result;
+    const error = { ...body.error };
+    const action = error.nextAction;
+    if (action?.tool === "search_tools" || (!action && error.code === "unknown_tool")) {
+        error.nextAction = {
+            host: "search",
+            arguments: { query: action?.arguments?.query ?? wireName },
+            purpose: action?.purpose,
+        };
+    }
+    else if (action?.tool === "authorize_connector") {
+        const url = error.authorizationUrl ?? error.operatorUrl;
+        error.nextAction = url
+            ? { url, purpose: "Give this handoff to the user or operator." }
+            : { operator: "Check connector authentication in deployment configuration." };
+    }
+    else if (action?.tool === "call_tool" || action?.tool === "call_destructive_tool") {
+        error.nextAction = wireName
+            ? {
+                tool: wireName,
+                arguments: action.arguments?.args ?? {},
+                purpose: `${action.purpose ?? "Retry the original native call."}${action.arguments?.argsRedacted ? " Resend the original arguments; sensitive fields were omitted." : ""}`,
+            }
+            : { host: "search", purpose: action.purpose };
+    }
+    // These are Connecta-authored recovery fields, never arbitrary downstream data.
+    const rewrite = (text) => text.replace(/authorize_connector|search_tools|call_(?:destructive_)?tool|execute_code/g, (tool) => tool === "authorize_connector"
+        ? "the returned authorization handoff"
+        : tool.startsWith("call_")
+            ? "the original native tool"
+            : tool === "execute_code" && executeCode
+                ? tool
+                : "your host's tool search");
+    for (const key of ["message", "instructions", "retry"])
+        if (typeof error[key] === "string")
+            error[key] = rewrite(error[key]);
+    if (wireName && typeof error.operation === "string" && typeof error.retry === "string")
+        error.retry = error.retry.replaceAll(rewrite(error.operation), wireName);
+    if (!executeCode && typeof error.instructions === "string") {
+        error.instructions = error.instructions.replace(/; connecta\.search[\s\S]*$/, ". Retry the original native call after recovery.");
+    }
+    return {
+        ...response,
+        structuredContent: { ...body, error },
+        content: [{ type: "text", text: JSON.stringify({ ...body, error }) }],
+    };
+}

package/dist/native-tools.js

@@ -0,0 +1,382 @@
+import { duringViewEffect } from "./runtime/call.js";
+import { RequestScope, requestOwner } from "./runtime/request-scope.js";
+import { Effect } from "effect";
+import { upwardStep } from "./upward.js";
+import { authCall, authInvoke, authFlow, authMethod, registerAuth, registerAuthMethod, authOwnMethod, } from "./auth/native.js";
+import { runEdge } from "./runtime/run.js";
+import { ProtocolError, } from "@modelcontextprotocol/server";
+import { withAuthorizationHandoff } from "./authorization-handoff.js";
+import { classifyCallError } from "./errors.js";
+import { nativeRecovery } from "./native-recovery.js";
+import { CatalogService } from "./catalog-service.js";
+import { jsonResult } from "./meta-tools.js";
+import { failureRecord, logFailure } from "./operator-record.js";
+/**
+ * Longest native name. A client prefixes its own connection name, and common
+ * tool-name limits are 64 characters: Eve's `connecta__` and Claude Code's
+ * `mcp__connecta__` both fit beside 48.
+ */
+export const NATIVE_NAME_MAX = 48;
+/** One page, no cursor: Eve 0.83 reads only the first `tools/list` page. */
+const MAX_NATIVE_TOOLS = 1_000;
+/** Native `tools/list` cache hint. Shorter than the meta surface's hour: the list follows downstream catalogs. */
+export const NATIVE_TOOLS_LIST_TTL_MS = 300_000;
+const HASH_CHARS = 6;
+const SEPARATOR = "__";
+/** No `__`, no leading `_`: the last `__` of a plain name is then always its separator. */
+const PLAIN_TOOL = /^[A-Za-z0-9-](?:[A-Za-z0-9-]|_(?!_))*$/;
+const NATIVE_NAME = new RegExp(`^[A-Za-z][A-Za-z0-9_-]{0,${NATIVE_NAME_MAX - 1}}$`);
+/** Connecta's own tools on a native endpoint. Their names never contain `__`. */
+const NATIVE_OWN_TOOLS = ["execute_code", "skills", "read_result"];
+const enc = new TextEncoder();
+function shortHash(text) {
+    return runEdge(shortHashNative(text));
+}
+const shortHashNative = /* @__PURE__ */ registerAuth(shortHash, function (text) {
+    return authFlow(function* () {
+        const digest = new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", enc.encode(text)])));
+        return [...digest.subarray(0, HASH_CHARS / 2)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+    });
+});
+/**
+ * The connector half of a native name. Connector ids are `[a-z0-9_-]+`; one
+ * that does not start with a letter gets an uppercase `C`, which no connector
+ * id can contain, so the prefix never collides with another id.
+ */
+function connectorPart(connectorId) {
+    return /^[a-z]/.test(connectorId) ? connectorId : `C${connectorId}`;
+}
+/**
+ * A pure function of the connector id and downstream tool name, so it is
+ * stable across catalog refreshes: `<connector>__<tool>` when that is exact,
+ * legal and short, otherwise its head plus a six-hex SHA-256 suffix of the
+ * original pair.
+ */
+export function nativeToolName(connectorId, toolName) {
+    return runEdge(nativeToolNameNative(connectorId, toolName));
+}
+const nativeToolNameNative = /* @__PURE__ */ registerAuth(nativeToolName, function (connectorId, toolName) {
+    return authFlow(function* () {
+        const tool = toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+        const plain = `${connectorPart(connectorId)}${SEPARATOR}${tool}`;
+        if (tool === toolName && PLAIN_TOOL.test(tool) && plain.length <= NATIVE_NAME_MAX)
+            return plain;
+        const head = plain.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "");
+        return `${head}_${yield* upwardStep(authCall(shortHash, [`${connectorId}.${toolName}`]))}`;
+    });
+});
+/** Read or write, from the served classification only. */
+function annotationsFor(tool) {
+    return tool.classification === "read"
+        ? { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+        : { readOnlyHint: false, destructiveHint: true, openWorldHint: true };
+}
+/** Object arguments retain every applicable constraint, including local refs. */
+function nativeInputSchema(schema) {
+    function supportsObject(value, seen = new Set()) {
+        if (value === true)
+            return true;
+        if (!value || typeof value !== "object" || Array.isArray(value) || seen.has(value))
+            return false;
+        const node = value;
+        const next = new Set(seen).add(value);
+        if (node.type !== undefined &&
+            node.type !== "object" &&
+            !(Array.isArray(node.type) && node.type.includes("object")))
+            return false;
+        if (node.$ref !== undefined) {
+            if (typeof node.$ref !== "string" || !node.$ref.startsWith("#/"))
+                return false;
+            let target = schema;
+            for (const part of node.$ref.slice(2).split("/")) {
+                if (!target || typeof target !== "object")
+                    return false;
+                target = target[part.replace(/~1/g, "/").replace(/~0/g, "~")];
+            }
+            if (!supportsObject(target, next))
+                return false;
+        }
+        for (const key of ["anyOf", "oneOf", "allOf"]) {
+            const branches = node[key];
+            if (Array.isArray(branches) &&
+                !(key === "allOf"
+                    ? branches.every((branch) => supportsObject(branch, next))
+                    : branches.some((branch) => supportsObject(branch, next))))
+                return false;
+        }
+        return true;
+    }
+    if (!supportsObject(schema))
+        return undefined;
+    return schema.type === "object" ? schema : { ...schema, type: "object" };
+}
+/**
+ * The downstream input schema, advertised verbatim. Validation accepts
+ * anything: invocation validates against the same catalog definition and
+ * returns its structured `invalid_args` with repair, as call_tool does.
+ */
+function passThroughSchema(schema) {
+    // Listing has already excluded connectors with unrepresentable schemas.
+    const json = schema === undefined ? { type: "object" } : nativeInputSchema(schema);
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "connecta",
+            validate: (value) => ({ value }),
+            jsonSchema: { input: () => json, output: () => json },
+        },
+    };
+}
+function describe(entry, executeCode) {
+    const lines = [entry.tool.description?.trim() || entry.tool.title || entry.tool.name];
+    if (executeCode)
+        lines.push(`Program address: ${entry.connector.id}.${entry.tool.name}`);
+    return lines.join("\n\n");
+}
+export class NativeSurface {
+    registry;
+    options;
+    catalog;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = options;
+        this.catalog = new CatalogService(registry, options.baseUrl, {
+            requestScope: options.requestScope,
+            requestSignal: options.requestSignal,
+            probeTimeoutMs: options.probeTimeoutMs,
+            concurrency: options.discoveryConcurrency,
+            // Listing omits a read-only endpoint's writes, as search does.
+            readOnly: options.readOnly,
+            defer: options.defer,
+        });
+    }
+    /**
+     * Every listable native tool. A connector whose catalog fails is omitted
+     * whole, never partially, with an operator warning; two tools claiming one
+     * name are both omitted and stay reachable by address in execute_code.
+     */
+    claims(connectors = this.registry.listConnectors()) {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "claims", [connectors]));
+    }
+    list() {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "list", []));
+    }
+    /**
+     * The downstream tool behind a native name, from the catalogs whose
+     * connector prefix the name could carry, including truncated prefixes. Resolution sees
+     * writes on a read-only endpoint, so invocation refuses them by code.
+     */
+    resolve(name) {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "resolve", [name]));
+    }
+    /** A native call: the existing route its current verdict selects. */
+    call(name, args, request) {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "call", [name, args, request]));
+    }
+    registerTool(server, name, entry) {
+        server.registerTool(name, {
+            ...(entry?.tool.title ? { title: entry.tool.title } : {}),
+            ...(entry ? { description: describe(entry, this.options.executeCode) } : {}),
+            inputSchema: passThroughSchema(entry?.tool.inputSchema),
+            ...(entry ? { annotations: annotationsFor(entry.tool) } : {}),
+            ...(entry ? { _meta: { "dev.connecta/address": `${entry.connector.id}.${entry.tool.name}` } } : {}),
+        }, authMethod((args, request) => Effect.gen({ self: this }, function* () {
+            const result = yield* authInvoke(this, "call", [name, args ?? {}, request]);
+            return nativeRecovery(result, this.options.executeCode, name);
+        })));
+    }
+    /**
+     * Register what this request needs before the SDK dispatches it: the whole
+     * listing for `tools/list`, the one called name for `tools/call` (resolved
+     * when it runs, so a catalog failure comes back as Connecta's structured
+     * error rather than "tool not found"), nothing otherwise.
+     */
+    register(server, hint) {
+        return runEdge(authOwnMethod(NativeSurface.prototype, this, "register", [server, hint]));
+    }
+    static {
+        registerAuthMethod(NativeSurface.prototype, "register", function (server, hint) {
+            const self = this;
+            return duringViewEffect({
+                requestScope: this.options.requestScope,
+                signal: this.options.requestSignal,
+            }, () => authFlow(function* () {
+                if (hint.method === "tools/call") {
+                    if (NATIVE_NAME.test(hint.name) && !NATIVE_OWN_TOOLS.includes(hint.name))
+                        self.registerTool(server, hint.name);
+                    return;
+                }
+                if (hint.method !== "tools/list")
+                    return;
+                const tools = yield* upwardStep(authInvoke(self, "list", []));
+                if (tools.length > MAX_NATIVE_TOOLS) {
+                    logFailure(self.options.logger, "native tools/list refused a pool over the 1,000-tool native cap", failureRecord({}));
+                    server.server.setRequestHandler("tools/list", () => {
+                        throw new ProtocolError(-32603, `This endpoint has ${tools.length} tools, over the ${MAX_NATIVE_TOOLS}-tool native listing cap. Ask the operator to narrow the pool or use the meta surface.`);
+                    });
+                    return;
+                }
+                for (const entry of tools)
+                    self.registerTool(server, entry.name, entry);
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, NativeSurface.prototype.register);
+        registerAuthMethod(NativeSurface.prototype, "call", function (name, args, request) {
+            const self = this;
+            return duringViewEffect({
+                requestScope: this.options.requestScope,
+                signal: this.options.requestSignal,
+            }, () => authFlow(function* () {
+                self.options.bind(request);
+                const target = yield* upwardStep(authInvoke(self, "resolve", [name]));
+                if (target.kind !== "found") {
+                    const failure = target.kind === "missing" ? target.failure : undefined;
+                    const error = failure
+                        ? {
+                            ...classifyCallError(failure.cause, "catalog_lookup_failed"),
+                            connector: failure.connector.id,
+                            message: `Connector "${failure.connector.id}" catalog lookup failed.`,
+                        }
+                        : {
+                            code: "unknown_tool",
+                            message: target.kind === "ambiguous"
+                                ? `Ambiguous native name "${name}". Ask the operator to rename a claimant.`
+                                : `Unknown native tool "${name}".`,
+                            retryable: false,
+                        };
+                    if (failure && (error.code === "auth_required" || error.code === "downstream_oauth_required")) {
+                        error.nextAction = {
+                            tool: "authorize_connector",
+                            arguments: { connector: failure.connector.id },
+                            operatorHandoff: "Give the returned handoff to the operator.",
+                        };
+                    }
+                    const result = jsonResult({
+                        ok: false,
+                        error: yield* upwardStep(authCall(withAuthorizationHandoff, [self.options.requestScope, error])),
+                    });
+                    result.isError = true;
+                    return result;
+                }
+                const address = `${target.entry.connector.id}.${target.entry.tool.name}`;
+                return yield* upwardStep(authInvoke(self.options, "route", [
+                    target.entry.tool.classification === "read" ? "call_tool" : "call_destructive_tool",
+                    { address, args },
+                    request,
+                ]));
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, NativeSurface.prototype.call);
+        registerAuthMethod(NativeSurface.prototype, "resolve", function (name) {
+            const self = this;
+            return duringViewEffect({
+                requestScope: this.options.requestScope,
+                signal: this.options.requestSignal,
+            }, () => authFlow(function* () {
+                const prefixed = self.registry.listConnectors().filter((connector) => {
+                    const prefix = `${connectorPart(connector.id)}${SEPARATOR}`;
+                    // A hashed name can truncate even the connector prefix, and strips
+                    // trailing underscores from its head. Include every possible claimant.
+                    const head = prefix.slice(0, NATIVE_NAME_MAX - HASH_CHARS - 1).replace(/_+$/, "");
+                    // A hashed name carries a stripped head only as exactly `${head}_` + six hex digits.
+                    return (name.startsWith(prefix) ||
+                        (name.length === head.length + 1 + HASH_CHARS &&
+                            name.startsWith(`${head}_`) &&
+                            /^[0-9a-f]+$/.test(name.slice(-HASH_CHARS))));
+                });
+                const { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", [prefixed]));
+                const found = byName.get(name);
+                if (found === null)
+                    return { kind: "ambiguous" };
+                // An unavailable possible claimant cannot prove uniqueness.
+                for (const entry of loaded)
+                    if ("error" in entry)
+                        return { kind: "missing", failure: { connector: entry.connector, cause: entry.error } };
+                return found ? { kind: "found", entry: found } : { kind: "missing" };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, NativeSurface.prototype.resolve);
+        registerAuthMethod(NativeSurface.prototype, "list", function () {
+            const self = this;
+            return duringViewEffect({
+                requestScope: this.options.requestScope,
+                signal: this.options.requestSignal,
+            }, () => authFlow(function* () {
+                const { loaded, byName } = yield* upwardStep(authInvoke(self, "claims", []));
+                for (const entry of loaded) {
+                    // Validate the whole connector before registering any of its tools.
+                    const tool = "tools" in entry
+                        ? entry.tools.find((tool) => tool.inputSchema !== undefined && !nativeInputSchema(tool.inputSchema))
+                        : undefined;
+                    if (!("error" in entry) && !tool)
+                        continue;
+                    self.options.catalogErrors.push(entry.connector.id);
+                    logFailure(self.options.logger, "native catalog unavailable", failureRecord({ connector: entry.connector.id, ...(tool ? { tool } : {}) }, "error" in entry ? entry.error : undefined));
+                }
+                return [...byName.values()].filter((entry) => entry !== null &&
+                    !self.options.catalogErrors.includes(entry.connector.id) &&
+                    (!(self.options.readOnly || entry.connector.readOnly) || entry.tool.classification === "read"));
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, NativeSurface.prototype.list);
+        registerAuthMethod(NativeSurface.prototype, "claims", function (connectors) {
+            const self = this;
+            return duringViewEffect({
+                requestScope: this.options.requestScope,
+                signal: this.options.requestSignal,
+            }, () => authFlow(function* () {
+                const loaded = yield* upwardStep(authInvoke(self.catalog, "listCatalogs", [true, connectors ?? self.registry.listConnectors()]));
+                const byName = new Map();
+                for (const entry of loaded) {
+                    if (!("tools" in entry))
+                        continue;
+                    for (const tool of entry.tools) {
+                        const name = yield* upwardStep(authCall(nativeToolName, [entry.connector.id, tool.name]));
+                        if (byName.has(name)) {
+                            byName.set(name, null);
+                            logFailure(self.options.logger, "native name collision", failureRecord({ connector: entry.connector.id, tool }));
+                        }
+                        else
+                            byName.set(name, { name, connector: entry.connector, tool });
+                    }
+                }
+                return { loaded, byName };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, NativeSurface.prototype.claims);
+    }
+}
+/** Read the method and tool name a request carries, for {@link NativeSurface.register}. */
+export function nativeRequestHint(request, modern) {
+    return runEdge(nativeRequestHintNative(request, modern));
+}
+const nativeRequestHintNative = /* @__PURE__ */ registerAuth(nativeRequestHint, function (request, modern) {
+    return authFlow(function* () {
+        let method;
+        let name;
+        if (modern) {
+            // The SDK checked both headers against the body before calling the factory.
+            method = request.headers.get("Mcp-Method")?.trim();
+            const header = request.headers.get("Mcp-Name")?.trim();
+            const encoded = header && /^=\?base64\?(.*)\?=$/.exec(header);
+            try {
+                name = encoded
+                    ? new TextDecoder().decode(Uint8Array.from(atob(encoded[1]), (c) => c.charCodeAt(0)))
+                    : header;
+            }
+            catch {
+                name = undefined;
+            }
+        }
+        else {
+            try {
+                const body = (yield* upwardStep(authInvoke(request.clone(), "json", [])));
+                method = body?.method;
+                name = body?.params?.name;
+            }
+            catch {
+                return { method: "other" };
+            }
+        }
+        if (method === "tools/list")
+            return { method };
+        if (method === "tools/call" && typeof name === "string")
+            return { method, name };
+        return { method: "other" };
+    });
+});

package/dist/node.d.ts

@@ -2,9 +2,11 @@ import type { Server } from "node:http";
 import type { Connecta } from "./index.js";
 export interface ListenOptions {
     port: number;
+    /** Explicit HTTP(S) CONNECT proxy for owned outbound sends. Never read from the environment. */
+    proxy?: string;
     /** Interface to bind. Defaults to Node's own (all interfaces). */
     host?: string;
-    /** Reject request bodies larger than this with 413. Default 10 MiB. */
+    /** Pre-auth buffer cap, independent of the authenticated MCP cap. Default 4 MiB. */
     maxBodyBytes?: number;
     /**
      * Stop accepting connections on SIGTERM/SIGINT, let in-flight requests
@@ -19,7 +21,6 @@ export interface ListenOptions {
 /**
  * Serve a Connecta over node:http. Thin adapter: IncomingMessage → Request,
  * Response → ServerResponse, plus the process-level concerns a long-running
- * container needs (body cap, response streaming, graceful shutdown). No
- * dependencies beyond node core.
+ * container needs (body cap, response streaming, graceful shutdown). Outbound HTTP uses an owned undici dispatcher configured here.
  */
 export declare function listen(connecta: Connecta, portOrOptions: number | ListenOptions): Server;

package/dist/node.js

@@ -2,8 +2,11 @@ import { createServer } from "node:http";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { failureRecord, logFailure } from "./operator-record.js";
-/** 10 MiB. Tool arguments are JSON; nothing legitimate approaches this. */
-const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
+import { configureGuardedTransport } from "./guarded-transport.js";
+import { createNodeGuardedTransport } from "./http/node-transport.js";
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
+/** The adapter buffers before auth, bounded by the same default as the core. */
+const DEFAULT_MAX_BODY_BYTES = CONFIG_DEFAULTS.admission.requests.maxBodyBytes;
 const BODY_TOO_LARGE = Symbol("body-too-large");
 async function toRequest(req, maxBodyBytes, signal) {
     const host = req.headers.host ?? "localhost";
@@ -55,11 +58,11 @@ async function writeResponse(res, response) {
 /**
  * Serve a Connecta over node:http. Thin adapter: IncomingMessage → Request,
  * Response → ServerResponse, plus the process-level concerns a long-running
- * container needs (body cap, response streaming, graceful shutdown). No
- * dependencies beyond node core.
+ * container needs (body cap, response streaming, graceful shutdown). Outbound HTTP uses an owned undici dispatcher configured here.
  */
 export function listen(connecta, portOrOptions) {
     const opts = typeof portOrOptions === "number" ? { port: portOrOptions } : portOrOptions;
+    configureGuardedTransport(createNodeGuardedTransport(opts.proxy));
     const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
     // Node has no ExecutionContext, so deferred work (activity sinks) would
     // otherwise be an untracked floating promise. Track it here and drain it on
@@ -71,7 +74,31 @@ export function listen(connecta, portOrOptions) {
             void promise.finally(() => pending.delete(promise));
         },
     };
+    const awaitingRequest = new Set();
+    const activeResponses = new Map();
+    let shuttingDown = false;
     const server = createServer((req, res) => {
+        awaitingRequest.delete(req.socket);
+        const socket = req.socket;
+        activeResponses.set(socket, (activeResponses.get(socket) ?? 0) + 1);
+        const finished = () => {
+            res.removeListener("finish", finished);
+            res.removeListener("close", finished);
+            const remaining = (activeResponses.get(socket) ?? 1) - 1;
+            if (remaining > 0)
+                activeResponses.set(socket, remaining);
+            else {
+                activeResponses.delete(socket);
+                // finish means the response was handed to the socket; destroySoon
+                // flushes its queued bytes before closing, including an SSE trailer.
+                // Count pipelined responses so an earlier finish cannot cut a later
+                // admitted response off. Before shutdown Node's keepalive is unchanged.
+                if (shuttingDown)
+                    socket.destroySoon();
+            }
+        };
+        res.once("finish", finished);
+        res.once("close", finished);
         void (async () => {
             const controller = new AbortController();
             const abortRequest = () => {
@@ -133,7 +160,17 @@ export function listen(connecta, portOrOptions) {
     });
     if (opts.gracefulShutdown !== false) {
         const timeoutMs = opts.shutdownTimeoutMs ?? 10_000;
-        let shuttingDown = false;
+        // closeIdleConnections() only knows sockets that have served a request.
+        // A client's spare connection (or incomplete first headers) must not hold
+        // shutdown open without ever having been admitted to the application.
+        server.on("connection", (socket) => {
+            if (shuttingDown) {
+                socket.destroy();
+                return;
+            }
+            awaitingRequest.add(socket);
+            socket.once("close", () => awaitingRequest.delete(socket));
+        });
         const shutdown = (signal) => {
             if (shuttingDown)
                 return;
@@ -147,15 +184,15 @@ export function listen(connecta, portOrOptions) {
             // Stop queued/running sandbox work now, not after server.close has
             // waited for the very requests those children are holding open.
             const executorClose = connecta.close();
-            // close() alone waits on idle keep-alive sockets, so a single browser
-            // tab would stall every shutdown until the force-exit deadline.
-            server.closeIdleConnections();
             server.close(() => {
                 void Promise.allSettled([...pending, executorClose]).then(() => {
                     clearTimeout(forced);
                     process.exit(0);
                 });
             });
+            server.closeIdleConnections();
+            for (const socket of awaitingRequest)
+                socket.destroy();
         };
         process.on("SIGTERM", () => shutdown("SIGTERM"));
         process.on("SIGINT", () => shutdown("SIGINT"));