@intentic/sandbox-contract 1.247.0 → 1.249.0

package/src/protocol/ingress-protocol.ts

@@ -0,0 +1,441 @@
+import { Agent, request as h1Request, type IncomingMessage, type OutgoingHttpHeaders, type ServerResponse } from "node:http";
+import {
+    type ClientHttp2Session,
+    connect as h2Connect,
+    constants,
+    createServer as createH2Server,
+    type IncomingHttpHeaders,
+    type ServerHttp2Stream,
+} from "node:http2";
+import { type AddressInfo, createServer as createNetServer, connect as netConnect, type Socket } from "node:net";
+import { Duplex } from "node:stream";
+
+// Both ends of the ingress tunnel's h2 session, over any node Duplex, in one file: a wire format with two owners
+// drifts. h2 gives multiplexing and backpressure for free; routing is per h2 stream, since one edge connection can
+// interleave several sandboxes' hosts.
+
+// Header hygiene
+
+// Headers that must not cross a hop: h2 throws on these, and `host` is replaced by :authority.
+const HOP_BY_HOP = new Set([
+    "connection",
+    "host",
+    "http2-settings",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+
+// Headers that survive a hop: pseudo-headers and HOP_BY_HOP removed, values unchanged, including array values for a
+// repeated field like `set-cookie`.
+const endToEnd = (headers: IncomingHttpHeaders): OutgoingHttpHeaders => {
+    const kept: OutgoingHttpHeaders = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value !== undefined && !name.startsWith(":") && !HOP_BY_HOP.has(name)) {
+            kept[name] = value;
+        }
+    }
+    return kept;
+};
+
+// The upgrade envelope
+
+// A websocket upgrade rides a CONNECT stream, where the headers an upgrade needs (Connection, Upgrade,
+// Sec-WebSocket-Key) are exactly the ones h2 forbids. The whole h1 request head travels prefixed under `x-ingress-*`
+// and is rebuilt verbatim on the far side, so no header is individually allowlisted.
+const UPGRADE_METHOD_HEADER = "x-ingress-method";
+const UPGRADE_PATH_HEADER = "x-ingress-path";
+const UPGRADE_HEADER_PREFIX = "x-ingress-h-";
+
+const upgradeEnvelope = (request: IncomingMessage, authority: string): OutgoingHttpHeaders => {
+    const envelope: OutgoingHttpHeaders = {
+        [constants.HTTP2_HEADER_METHOD]: constants.HTTP2_METHOD_CONNECT,
+        [constants.HTTP2_HEADER_AUTHORITY]: authority,
+        [UPGRADE_METHOD_HEADER]: request.method ?? "GET",
+        [UPGRADE_PATH_HEADER]: request.url ?? "/",
+    };
+    for (const [name, value] of Object.entries(request.headers)) {
+        if (value !== undefined) {
+            envelope[`${UPGRADE_HEADER_PREFIX}${name}`] = value;
+        }
+    }
+    return envelope;
+};
+
+// Rebuilds the h1 head an envelope carried; anything without the `x-ingress-h-` prefix is dropped as not part of the
+// original request.
+const upgradeHead = (headers: IncomingHttpHeaders): { method: string; path: string; headers: OutgoingHttpHeaders } => {
+    const rebuilt: OutgoingHttpHeaders = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value !== undefined && name.startsWith(UPGRADE_HEADER_PREFIX)) {
+            rebuilt[name.slice(UPGRADE_HEADER_PREFIX.length)] = value;
+        }
+    }
+    return {
+        method: single(headers[UPGRADE_METHOD_HEADER]) ?? "GET",
+        path: single(headers[UPGRADE_PATH_HEADER]) ?? "/",
+        headers: rebuilt,
+    };
+};
+
+// First value of a header that should never repeat; a repeated one is taken as its first value.
+const single = (value: string | string[] | undefined): string | undefined => (Array.isArray(value) ? value[0] : value);
+
+// Serializes a response head verbatim from `rawHeaders` (order and spelling preserved) since it is written raw onto the
+// browser's socket; latin1, since header values are opaque octets, not utf-8 text.
+const serializeHead = (response: IncomingMessage, drop: ReadonlySet<string>, add: readonly string[]): Buffer => {
+    const lines = [`HTTP/${response.httpVersion} ${String(response.statusCode)} ${response.statusMessage ?? ""}`];
+    for (let index = 0; index + 1 < response.rawHeaders.length; index += 2) {
+        const name = response.rawHeaders[index] as string;
+        if (!drop.has(name.toLowerCase())) {
+            lines.push(`${name}: ${response.rawHeaders[index + 1] as string}`);
+        }
+    }
+    return Buffer.from(`${[...lines, ...add].join("\r\n")}\r\n\r\n`, "latin1");
+};
+
+// A non-101 answer on a CONNECT stream needs re-framing: `transfer-encoding` is dropped since the body is already
+// de-chunked, and `connection: close` delimits it instead.
+const DECLINED_UPGRADE_DROP = new Set(["connection", "keep-alive", "transfer-encoding"]);
+const DECLINED_UPGRADE_ADD = ["connection: close"];
+const NOTHING_DROPPED: ReadonlySet<string> = new Set();
+
+// Session tuning
+
+// Session memory budget shared by every stream on the tunnel; exhausting it kills the whole session, not one request.
+const MAX_SESSION_MEMORY_MB = 128;
+
+// Per-stream receive window, larger than h2's 64KB default since this session crosses the internet.
+const INITIAL_WINDOW_SIZE = 1024 * 1024;
+
+// Concurrent stream ceiling per sandbox, raised since streams here can stay open for a session's whole life.
+const PEER_MAX_CONCURRENT_STREAMS = 256;
+
+// Fixed loopback address; no stream over this tunnel can be pointed anywhere but this container's own listener.
+const LOOPBACK = "127.0.0.1";
+
+// The splice
+
+// Pipes both directions; `pipe` carries end-of-stream each way on its own. A failure on either side destroys both,
+// since `destroy` is idempotent and the two handlers won't loop.
+const splice = (left: Duplex, right: Duplex): void => {
+    left.pipe(right);
+    right.pipe(left);
+    const fail = (): void => {
+        left.destroy();
+        right.destroy();
+    };
+    left.on("error", fail);
+    right.on("error", fail);
+    // A side that closes without finishing its writes (a reset, a dropped socket) takes the other side down too;
+    // `writableFinished` distinguishes that from a graceful FIN already forwarded by the pipe.
+    left.on("close", () => {
+        if (!right.writableFinished) {
+            right.destroy();
+        }
+    });
+    right.on("close", () => {
+        if (!left.writableFinished) {
+            left.destroy();
+        }
+    });
+};
+
+// The loopback bridge
+
+// Bridges the caller's Duplex onto a real net.Socket: node's Duplex-over-h2 wrapper allows one write in flight, so a
+// same-turn second write throws ERR_INTERNAL_ASSERTION and kills the process. The accepted socket is checked against
+// the one just dialed.
+const loopbackBridge = async (): Promise<{ session: Socket; tunnel: Socket }> => {
+    const listener = createNetServer();
+    try {
+        await new Promise<void>((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(0, LOOPBACK, resolve);
+        });
+        const accepted = new Promise<Socket>((resolve, reject) => {
+            listener.once("connection", resolve);
+            listener.once("error", reject);
+        });
+        const tunnel = netConnect((listener.address() as AddressInfo).port, LOOPBACK);
+        await new Promise<void>((resolve, reject) => {
+            tunnel.once("connect", resolve);
+            tunnel.once("error", reject);
+        });
+        const session = await accepted;
+        if (session.remotePort !== tunnel.localPort) {
+            session.destroy();
+            tunnel.destroy();
+            throw new Error("the loopback bridge accepted a connection that was not its own");
+        }
+        // Disables Nagle: both ends are local, and frames here are already sized by h2.
+        session.setNoDelay(true);
+        tunnel.setNoDelay(true);
+        return { session, tunnel };
+    } finally {
+        listener.close();
+    }
+};
+
+// The ingress half: an h2 client over the tunnel
+
+export interface IngressSession {
+    // Forwards one edge request down the tunnel. Resolves once the response is fully written; rejects on failure, and
+    // the caller reads `response.headersSent` to tell an untouched response (write your own 502) from one truncated
+    // mid-body.
+    readonly forwardRequest: (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    // Same for an upgrade, given the hijacked socket and any bytes already read past the request head. Nothing is
+    // written to `socket` until the far end accepts, so a rejection leaves it untouched for the caller to answer.
+    readonly forwardUpgrade: (request: IncomingMessage, socket: Duplex, head: Buffer) => Promise<void>;
+    // Ends the session and its bridge, which ends the caller's duplex and closes the WebSocket.
+    readonly close: () => void;
+}
+
+// Opens the ingress side of a tunnel; async since the bridge itself is. The connect URL is a placeholder — this session
+// has no host of its own, every request supplies the authority it's routed by.
+export const openIngressSession = async (duplex: Duplex): Promise<IngressSession> => {
+    const bridge = await loopbackBridge();
+    splice(bridge.tunnel, duplex);
+    const session: ClientHttp2Session = h2Connect("http://tunnel.invalid", {
+        createConnection: () => bridge.session,
+        maxSessionMemory: MAX_SESSION_MEMORY_MB,
+        peerMaxConcurrentStreams: PEER_MAX_CONCURRENT_STREAMS,
+        settings: { initialWindowSize: INITIAL_WINDOW_SIZE },
+    });
+    // Without a handler here, a dead or hostile peer raises an uncaught exception and takes every other sandbox's
+    // tunnel down with it. Destroying the duplex closes the WebSocket, which the reconnect loop waits on.
+    session.on("error", () => duplex.destroy());
+    session.on("close", () => duplex.destroy());
+
+    // Authority to route the stream by. The ingress already refuses any Host that doesn't own a sandbox, so a request
+    // with no Host here is a caller bug, not a routing decision.
+    const authorityOf = (request: IncomingMessage): string => {
+        const host = request.headers.host;
+        if (host === undefined || host === "") {
+            throw new Error("an ingress request is routed by its Host header, and this one has none");
+        }
+        return host;
+    };
+
+    const forwardRequest = (request: IncomingMessage, response: ServerResponse): Promise<void> =>
+        new Promise<void>((resolve, reject) => {
+            const authority = authorityOf(request);
+            // `endStream: false` for every method, not only ones that may carry a body: the request is piped
+            // regardless, and an already-ended GET closes the stream with an empty frame.
+            const stream = session.request(
+                {
+                    [constants.HTTP2_HEADER_METHOD]: request.method ?? "GET",
+                    [constants.HTTP2_HEADER_PATH]: request.url ?? "/",
+                    [constants.HTTP2_HEADER_AUTHORITY]: authority,
+                    // The edge is HTTPS-only, so this is what the browser used; nothing here routes on it.
+                    [constants.HTTP2_HEADER_SCHEME]: "https",
+                    ...endToEnd(request.headers),
+                },
+                { endStream: false },
+            );
+            request.pipe(stream);
+
+            // The browser giving up must reach the daemon: without this, a closed tab leaves the h2 stream, the
+            // daemon's own request, and any long-lived generator (SSE) running for nobody. RST_STREAM(CANCEL) unwinds
+            // all three.
+            response.on("close", () => {
+                if (!response.writableFinished) {
+                    stream.close(constants.NGHTTP2_CANCEL);
+                }
+            });
+
+            stream.on("response", (headers) => {
+                if (response.destroyed) {
+                    stream.close(constants.NGHTTP2_CANCEL);
+                    return;
+                }
+                response.writeHead(Number(headers[constants.HTTP2_HEADER_STATUS] ?? 502), endToEnd(headers));
+                stream.pipe(response);
+            });
+            stream.on("error", reject);
+            // The response resolves on `finish`, once node has flushed it to the browser, not merely when the h2 stream
+            // closes.
+            response.on("finish", resolve);
+            stream.on("close", () => {
+                if (!response.writableEnded) {
+                    reject(new Error("the tunnel closed the stream before the response was complete"));
+                }
+            });
+        });
+
+    const forwardUpgrade = (request: IncomingMessage, socket: Duplex, head: Buffer): Promise<void> =>
+        new Promise<void>((resolve, reject) => {
+            const stream = session.request(upgradeEnvelope(request, authorityOf(request)), { endStream: false });
+            stream.on("error", reject);
+            stream.once("response", (headers) => {
+                const status = Number(headers[constants.HTTP2_HEADER_STATUS]);
+                if (status !== constants.HTTP_STATUS_OK) {
+                    // The far end refused the upgrade; nothing has reached the browser yet, so the caller still owns
+                    // the socket.
+                    stream.close(constants.NGHTTP2_CANCEL);
+                    reject(new Error(`the tunnel refused an upgrade with :status ${String(status)}`));
+                    return;
+                }
+                // Bytes the client already sent past its request head; dropped, the handshake completes and then hangs
+                // on a frame nobody has.
+                if (head.length > 0) {
+                    stream.write(head);
+                }
+                splice(stream, socket);
+                resolve();
+            });
+        });
+
+    return {
+        forwardRequest,
+        forwardUpgrade,
+        // Graceful GOAWAY first, then the bridge's far half, which the session itself knows nothing about.
+        close: () => {
+            session.close(() => bridge.tunnel.destroy());
+            bridge.tunnel.end();
+        },
+    };
+};
+
+// The daemon half: an h2 server over the tunnel, onto the loopback listener
+
+export interface ServeIngressSessionOptions {
+    // The daemon's own listener; every stream lands there as a plain HTTP/1.1 request or upgrade.
+    readonly targetPort: number;
+}
+
+export interface IngressSessionServer {
+    // Sends GOAWAY over the bridge, which ends the caller's duplex once it's done writing the shutdown frame. The
+    // WebSocket itself belongs to whoever dialed it.
+    readonly close: () => void;
+}
+
+// One h2 server per session, bound to nothing; it exists only to be handed a connection. The h1 hop to the loopback
+// listener runs over a keep-alive agent, so steady traffic reuses sockets; the upgrade path does not.
+export const serveIngressSession = async (duplex: Duplex, options: ServeIngressSessionOptions): Promise<IngressSessionServer> => {
+    const bridge = await loopbackBridge();
+    splice(bridge.tunnel, duplex);
+    const agent = new Agent({ keepAlive: true, maxSockets: PEER_MAX_CONCURRENT_STREAMS });
+    const server = createH2Server({
+        maxSessionMemory: MAX_SESSION_MEMORY_MB,
+        settings: { initialWindowSize: INITIAL_WINDOW_SIZE },
+    });
+
+    // A failed session is news for the reconnect loop, not an uncaught exception that takes the whole daemon down.
+    // Destroying the duplex closes the WebSocket the loop waits on; `clientError` should never fire but isn't worth
+    // crashing over either.
+    server.on("sessionError", () => duplex.destroy());
+    server.on("clientError", () => duplex.destroy());
+    server.on("error", () => duplex.destroy());
+
+    const forwardToLoopback = (stream: ServerHttp2Stream, headers: IncomingHttpHeaders): void => {
+        const local = h1Request({
+            host: LOOPBACK,
+            port: options.targetPort,
+            method: single(headers[constants.HTTP2_HEADER_METHOD]) ?? "GET",
+            path: single(headers[constants.HTTP2_HEADER_PATH]) ?? "/",
+            // The Host the request was made to, restored where an h1 server reads it; this alone tells a preview, a
+            // port and the daemon apart.
+            headers: { host: single(headers[constants.HTTP2_HEADER_AUTHORITY]) ?? "", ...endToEnd(headers) },
+            agent,
+        });
+        stream.pipe(local);
+        local.on("response", (response) => {
+            stream.respond({ [constants.HTTP2_HEADER_STATUS]: response.statusCode ?? 502, ...endToEnd(response.headers) });
+            response.pipe(stream);
+        });
+        // The listener isn't answering; closed with an error code rather than a 502 of our own, since the ingress owns
+        // what an unreachable sandbox looks like.
+        local.on("error", () => stream.close(constants.NGHTTP2_INTERNAL_ERROR));
+        stream.on("error", () => local.destroy());
+        // The edge cancelled (RST_STREAM); stop generating a response nobody reads. `aborted` is the only event that
+        // means this — on a reset, node fires `aborted` before `finish` and `close`, so a
+        // `writableEnded`/`writableFinished` guard there would miss it.
+        stream.on("aborted", () => local.destroy());
+    };
+
+    const spliceUpgrade = (stream: ServerHttp2Stream, headers: IncomingHttpHeaders): void => {
+        const head = upgradeHead(headers);
+        // `agent: false`: an upgraded connection stops being HTTP once accepted and can never return to the keep-alive
+        // pool the request path above uses.
+        const local = h1Request({ host: LOOPBACK, port: options.targetPort, method: head.method, path: head.path, headers: head.headers, agent: false });
+        local.on("upgrade", (response, socket, first) => {
+            stream.respond({ [constants.HTTP2_HEADER_STATUS]: constants.HTTP_STATUS_OK });
+            // Response head written verbatim (see serializeHead), then any bytes already sent past it, then the pipe.
+            stream.write(serializeHead(response, NOTHING_DROPPED, []));
+            if (first.length > 0) {
+                stream.write(first);
+            }
+            splice(stream, socket);
+        });
+        // The local server declined to upgrade; its answer goes to the browser with framing that matches the already
+        // de-chunked body.
+        local.on("response", (response) => {
+            stream.respond({ [constants.HTTP2_HEADER_STATUS]: constants.HTTP_STATUS_OK });
+            stream.write(serializeHead(response, DECLINED_UPGRADE_DROP, DECLINED_UPGRADE_ADD));
+            response.pipe(stream);
+        });
+        local.on("error", () => stream.close(constants.NGHTTP2_CONNECT_ERROR));
+        // An upgrade request carries no body; the client is waiting on the handshake before it says anything else.
+        local.end();
+    };
+
+    server.on("stream", (stream, headers) => {
+        if (headers[constants.HTTP2_HEADER_METHOD] === constants.HTTP2_METHOD_CONNECT) {
+            spliceUpgrade(stream, headers);
+            return;
+        }
+        forwardToLoopback(stream, headers);
+    });
+
+    // Creates a server-side session without a listener: the server never binds, it is simply handed a connection.
+    server.emit("connection", bridge.session);
+
+    return {
+        close: () => {
+            agent.destroy();
+            server.close();
+            bridge.tunnel.end();
+        },
+    };
+};
+
+// Reimplements `ws`'s createWebSocketStream, which Bun does not support, so both runtimes get the same Duplex.
+// Preserves byte safety: the write callback fires only once the socket has taken the frame, and a closed socket ends
+// the readable side with `push(null)`.
+export interface TunnelWebSocket {
+    readonly send: (data: Buffer, options: { binary: boolean }, callback: (error?: Error) => void) => void;
+    readonly close: () => void;
+    readonly on: {
+        (event: `message`, listener: (data: unknown) => void): unknown;
+        (event: `close`, listener: () => void): unknown;
+        (event: `error`, listener: (error: Error) => void): unknown;
+    };
+}
+
+export const webSocketDuplex = (socket: TunnelWebSocket): Duplex => {
+    const duplex = new Duplex({
+        read: () => {},
+        write: (chunk: Buffer, _encoding, callback) => {
+            socket.send(chunk, { binary: true }, (error) => callback(error ?? null));
+        },
+        // Half-closing a WebSocket isn't possible; ending the writable side closes the socket outright.
+        final: (callback) => {
+            socket.close();
+            callback();
+        },
+    });
+    // `message` carries a Buffer for binary frames; a stray text frame arrives as a string and is coerced rather than
+    // dropped.
+    socket.on(`message`, (data: unknown) => {
+        duplex.push(Buffer.isBuffer(data) ? data : Buffer.from(data as string));
+    });
+    socket.on(`close`, () => duplex.push(null));
+    socket.on(`error`, (error: Error) => duplex.destroy(error));
+    return duplex;
+};

package/src/protocol/listener-protocol.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { ActivityStatusSchema } from "../schemas/activity.js";
+
+// Wire between the daemon and an extension's realtime-listener gateway (ext-discord, ext-slack, ext-telegram,
+// ext-whatsapp, ext-imap): the four /listeners/:provider routes (state, dispatch, failure, status). Shared here so both
+// ends compile against one declaration.
+
+// One normalized inbound event: the JSON body a realtime source POSTs to /listeners/<provider>/dispatch. A zod schema
+// since it's parsed from untrusted gateway input; `provider` and `type` are open strings, not a core enum.
+export const ListenerMessageSchema = z.object({
+    provider: z.string().min(1),
+    type: z.string().min(1),
+    id: z.string(),
+    channelId: z.string(),
+    author: z.object({ id: z.string(), name: z.string() }),
+    content: z.string(),
+    // Discord only: the message @mentions or replies to one of our bots; voice events never set it.
+    mentioned: z.boolean().optional(),
+    // CI pipeline event: the ref it ran on. Top-level, not in `extra`, since the dispatcher matches triggers on it.
+    branch: z.string().optional(),
+    // Prior channel messages fetched when tagged; top-level so it reaches the model but skips the activity feed.
+    history: z
+        .array(
+            z.object({
+                author: z.object({ id: z.string(), name: z.string() }),
+                content: z.string(),
+                timestamp: z.string(),
+                self: z.boolean().optional(),
+            }),
+        )
+        .optional(),
+    timestamp: z.string(),
+    // Provider-specific fields:
+    // - discord message: guildId, attachments
+    // - voice_utterance: path
+    // - voice_transcript: path, participants, durationSeconds
+    extra: z.record(z.string(), z.unknown()).optional(),
+});
+export type ListenerMessage = z.infer<typeof ListenerMessageSchema>;
+
+// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response: a text delta, a failure sentence, or a
+// terminal marker. A type, not a schema, since only the daemon produces these.
+export interface ListenerDispatchFrame {
+    readonly automationId: string;
+    readonly delta?: string;
+    // The turn's failure, forwarded verbatim since a gateway delivers it into the owner's own channel.
+    readonly failed?: string;
+    readonly end?: boolean;
+}
+
+// Where a device-linking ceremony stands (whatsapp), reported per status tick; every state here means not yet paired.
+// `since` stamps the current code's age, since WhatsApp reissues a fresh one on each reopen.
+export const ListenerPairingSchema = z.object({
+    // waiting: socket up, no code yet (or the last one died with its socket)
+    // code: `code` is live, type it on the phone
+    // failed: `detail` says what WhatsApp refused
+    state: z.enum(["waiting", "code", "failed"]),
+    code: z.string().optional(),
+    detail: z.string().optional(),
+    since: z.number().optional(),
+});
+export type ListenerPairing = z.infer<typeof ListenerPairingSchema>;
+
+// Push-based status: a gateway POSTs its connection/voice snapshot to /listeners/<provider>/status, since the daemon
+// holds no provider connection to probe itself. Extends ActivityStatus with whisper's voice-pending flag and each
+// unpaired capability's pairing ceremony by id.
+export const ListenerStatusSchema = ActivityStatusSchema.extend({
+    whisperReady: z.boolean().optional(),
+    pairing: z.record(z.string(), ListenerPairingSchema).optional(),
+});
+export type ListenerStatus = z.infer<typeof ListenerStatusSchema>;
+
+// A connection's place in the reconcile lifecycle: `idle` is up but intentionally holding nothing (no enabled
+// automation), `pairing` is up but waiting on an uncompleted credential ceremony; the rest are the connect loop.
+export type ListenerGatewayPhase = "idle" | "ready" | "pairing" | "connecting" | "disconnected";

package/src/{peer-dial.test.ts → protocol/peer-dial.test.ts}

@@ -11,7 +11,7 @@ class FakeSocket implements SocketLike {
     closed: { readonly code: number | undefined; readonly reason: string | undefined } | undefined;
     private readonly listeners = new Map<string, Set<(event: { readonly code?: number }) => void>>();
 
-    addEventListener(type: "open" | "close" | "error", listener: (event: { readonly code?: number }) => void): void {
+    addEventListener(type: "open" | "close" | "error" | "message", listener: (event: { readonly code?: number }) => void): void {
         const set = this.listeners.get(type) ?? new Set();
         set.add(listener);
         this.listeners.set(type, set);
@@ -31,6 +31,10 @@ class FakeSocket implements SocketLike {
         this.readyState = 3;
         this.emit("close", code);
     }
+    // A frame from the sandbox: the heartbeat, or any call. Only that one arrived matters to the loop.
+    says(): void {
+        this.emit("message");
+    }
     private emit(type: string, code?: number): void {
         for (const listener of this.listeners.get(type) ?? []) {
             listener(code === undefined ? {} : { code });
@@ -38,6 +42,9 @@ class FakeSocket implements SocketLike {
     }
 }
 
+// This door's silence deadline, named so the assertions can read it off the same number the loop is given.
+const SILENCE_MS = 30_000;
+
 // A ladder that answers with a fixed delay and records what it was told, so the test can read the held time.
 const ladder = (delay = 1_000) => {
     const held: number[] = [];
@@ -64,6 +71,7 @@ const dialling = () => {
         hello: () => ({ type: "hello", token: "iht_test", version: "1.0.0" }),
         attach: (socket) => void attached.push(socket),
         backoff: ladder(),
+        silenceMs: SILENCE_MS,
         log: (message) => void said.push(message),
         revoked,
     });
@@ -105,6 +113,46 @@ test("a drop redials on the ladder, telling it how long the socket held", async
     }
 });
 
+/* THE DROP NOBODY REPORTS, which is the one that used to last for days: a far end that is gone while the socket
+ * stays open — a sandbox container recreated behind a port relay that outlived it, a NAT that forgot the flow, a
+ * laptop's wifi suspended mid-session. Note what this test never calls: `drops`. Nothing closes, nothing errors,
+ * and the loop has to reach the conclusion on its own or hold a dead link forever. */
+test("a socket that goes silent is abandoned and redialled, though no close ever arrives", async () => {
+    vi.useFakeTimers();
+    try {
+        const { link, sockets, said } = dialling();
+        await vi.waitFor(() => expect(sockets).toHaveLength(1));
+        sockets[0]?.opens();
+
+        // A frame inside every window holds the link: this is the sandbox's heartbeat, three beats of it.
+        for (let beat = 0; beat < 3; beat += 1) {
+            await vi.advanceTimersByTimeAsync(SILENCE_MS - 1_000);
+            sockets[0]?.says();
+        }
+        expect(link.state()).toBe("open");
+        expect(sockets).toHaveLength(1);
+
+        // Then the beats stop, and nothing else happens: no close, no error.
+        await vi.advanceTimersByTimeAsync(SILENCE_MS);
+        expect(said.at(-1)).toBe(`nothing heard for ${SILENCE_MS / 1_000}s; reconnecting in 1s`);
+        expect(sockets[0]?.closed).toEqual({ code: 1000, reason: "no heartbeat" });
+        expect(link.state()).toBe("connecting");
+
+        await vi.advanceTimersByTimeAsync(1_000);
+        await vi.waitFor(() => expect(sockets).toHaveLength(2));
+
+        // The close an abandoned socket may still emit minutes later must not put a second loop on the link.
+        sockets[0]?.drops(1006);
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(sockets).toHaveLength(2);
+
+        link.stop();
+        await link.done;
+    } finally {
+        vi.useRealTimers();
+    }
+});
+
 test("a refused enrollment (1008) is never retried and is reported once", async () => {
     vi.useFakeTimers();
     try {
@@ -142,6 +190,7 @@ test("a stop during resolution opens nothing, and a socket a slow resolver still
         hello: () => ({}),
         attach: () => undefined,
         backoff: ladder(),
+        silenceMs: SILENCE_MS,
         log: () => undefined,
         revoked: () => undefined,
     });
@@ -166,6 +215,7 @@ test("a stop during resolution opens nothing, and a socket a slow resolver still
         hello: () => ({}),
         attach: () => undefined,
         backoff: ladder(),
+        silenceMs: SILENCE_MS,
         log: () => undefined,
         revoked: () => undefined,
     });
@@ -191,6 +241,7 @@ test("a pairing that is gone by the next attempt ends the loop rather than diall
         hello: () => ({}),
         attach: () => undefined,
         backoff: ladder(0),
+        silenceMs: SILENCE_MS,
         log: () => undefined,
         revoked: () => undefined,
     });