@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/policy/search-globs.ts

@@ -0,0 +1,60 @@
+// What the search box's second field means: VSCode's "files to include" grammar, read the same way everywhere it runs
+// (the daemon, the recorded demo):
+// - a bare name matches both the file and the folder (`p` and `p/**`)
+// - a path matches at any depth unless it starts with `./` or `/` (anchored to the root)
+// - a leading dot is an extension shorthand (`.ts` becomes `*.ts`); a trailing slash is dropped
+// - commas split patterns, except inside `{...}` or `[...]`
+// - a leading `!` excludes; this app's own addition, not VSCode's
+
+// VSCode's splitGlobAware: the split character is inert inside a brace group or character class.
+const splitPatterns = (include: string, splitChar: string): string[] => {
+    const segments: string[] = [];
+    let current = ``;
+    let inBraces = false;
+    let inBrackets = false;
+    for (const char of include) {
+        if (char === splitChar && !inBraces && !inBrackets) {
+            segments.push(current);
+            current = ``;
+            continue;
+        }
+        inBraces = char === `{` ? true : char === `}` ? false : inBraces;
+        inBrackets = char === `[` ? true : char === `]` ? false : inBrackets;
+        current += char;
+    }
+    segments.push(current);
+    return segments.map((segment) => segment.trim()).filter((segment) => segment !== ``);
+};
+
+// One typed segment maps to two globs: the file itself, and everything under a folder of that name. An anchored form
+// (`./p`, `/p`) keeps its `./` prefix, since that's how the engine tells "anchored" from "any depth".
+const expand = (segment: string): string[] => {
+    const trimmed = segment.replace(/\/+$/, ``);
+    if (trimmed === ``) {
+        return [];
+    }
+    const anchored = /^\.?\//.test(trimmed);
+    if (anchored) {
+        const path = trimmed.replace(/^\.?\//, ``).replace(/^\/+/, ``);
+        return path === `` ? [] : [`./${path}`, `./${path}/**`];
+    }
+    // ".ts" is how people write an extension filter; VSCode reads it as "*.ts" rather than a hidden file.
+    const pattern = trimmed.startsWith(`.`) ? `*${trimmed}` : trimmed;
+    return [`**/${pattern}`, `**/${pattern}/**`];
+};
+
+export interface IncludeGlobs {
+    // Files the search is limited to, empty means the whole workspace. OR'ed: any pattern matching admits.
+    readonly globs: readonly string[];
+    // Files kept out of it, whatever the includes said.
+    readonly notGlobs: readonly string[];
+}
+
+export const includeGlobs = (include: string | undefined): IncludeGlobs => {
+    const segments = splitPatterns(include ?? ``, `,`);
+    return {
+        globs: segments.filter((segment) => !segment.startsWith(`!`)).flatMap(expand),
+        // A bare "!" excludes nothing; without this it would expand into a glob that matches everything.
+        notGlobs: segments.filter((segment) => segment.startsWith(`!`)).flatMap((segment) => expand(segment.slice(1))),
+    };
+};

package/src/protocol/container-requirements.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { CONTAINER_REQUIREMENTS, containerDrift } from "./container-requirements.js";
+
+// Healthy baseline: every case below removes one piece of it to produce a gap.
+const CURRENT = {
+    SANDBOX_PUBLIC_URL: "https://sandbox-0738cd6b5027.sbx.intentic.dev",
+    SANDBOX_GRANT: "ig1.eyJzdWIiOiIwNzM4Y2Q2YjUwMjcifQ.sig",
+    INGRESS_URL: "https://ingress.intentic.dev",
+};
+
+describe(`containerDrift`, () => {
+    it(`says nothing about a container set up by a current release`, () => {
+        expect(containerDrift(CURRENT)).toEqual([]);
+    });
+
+    it(`names both keys a pre-migration container is missing, and what that costs`, () => {
+        const gaps = containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL });
+        expect(gaps).toHaveLength(1);
+        expect(gaps[0]?.key).toBe(`reachability`);
+        expect(gaps[0]?.missing).toEqual([`SANDBOX_GRANT`, `INGRESS_URL`]);
+        expect(gaps[0]?.repair).toContain(`setup command`);
+    });
+
+    it(`reports only the half that is actually gone`, () => {
+        expect(containerDrift({ ...CURRENT, INGRESS_URL: undefined })[0]?.missing).toEqual([`INGRESS_URL`]);
+        expect(containerDrift({ ...CURRENT, SANDBOX_GRANT: undefined })[0]?.missing).toEqual([`SANDBOX_GRANT`]);
+    });
+
+    // Blank must count as missing: it is indistinguishable from a dropped value replayed through `-e NAME=`.
+    it(`counts blank and whitespace-only values as missing, not as set`, () => {
+        expect(containerDrift({ ...CURRENT, SANDBOX_GRANT: `` })[0]?.missing).toEqual([`SANDBOX_GRANT`]);
+        expect(containerDrift({ ...CURRENT, SANDBOX_GRANT: `   ` })[0]?.missing).toEqual([`SANDBOX_GRANT`]);
+    });
+
+    // No public address means no evidence of intent, so nothing is reported as missing.
+    it(`asks nothing of a sandbox that offers no evidence it was meant to be reachable`, () => {
+        expect(containerDrift({})).toEqual([]);
+        expect(containerDrift({ CONNECT_TOKEN: `tok`, WORKSPACE_ROOT: `/work` })).toEqual([]);
+        expect(containerDrift({ SANDBOX_PUBLIC_URL: `` })).toEqual([]);
+    });
+
+    // A hosted Fly microVM has no grant by design, so this reports nothing on it.
+    it(`stays quiet on a hosted machine, which serves its address without dialling out`, () => {
+        expect(containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL, SANDBOX_VM: `1` })).toEqual([]);
+    });
+});
+
+describe(`CONTAINER_REQUIREMENTS`, () => {
+    it(`keys every row uniquely, so a UI can key and dedupe on it`, () => {
+        const keys = CONTAINER_REQUIREMENTS.map((requirement) => requirement.key);
+        expect(new Set(keys).size).toBe(keys.length);
+    });
+
+    // Overlapping `given`/`requires` would make the row impossible to fire.
+    // Empty `given` would make the row fire on every sandbox in the fleet.
+    it(`states evidence that is separate from what it demands`, () => {
+        for (const requirement of CONTAINER_REQUIREMENTS) {
+            expect(requirement.given.length).toBeGreaterThan(0);
+            expect(requirement.requires.length).toBeGreaterThan(0);
+            expect(requirement.given.filter((name) => requirement.requires.includes(name))).toEqual([]);
+        }
+    });
+
+    // Rendered verbatim in the product, so an empty string is a blank card, not just a missing test value.
+    it(`words every row for the person who has to fix it`, () => {
+        for (const requirement of CONTAINER_REQUIREMENTS) {
+            expect(requirement.enables.length).toBeGreaterThan(0);
+            expect(requirement.lost.length).toBeGreaterThan(0);
+            expect(requirement.repair.length).toBeGreaterThan(0);
+        }
+    });
+});

package/src/protocol/container-requirements.ts

@@ -0,0 +1,58 @@
+// A row belongs only if its keys come from setup, their absence is settled, and other env proves intent.
+// Add a row here, add it to `ic sandbox doctor`'s `classify_public` too: the two tables are not kept in sync.
+
+/** `enables` and `lost` render verbatim to the user: word them for the product, not the env. */
+export interface ContainerRequirement {
+    readonly key: string;
+    readonly requires: readonly string[];
+    // Absent `given` evidence means this sandbox never had the capability: not a fault, just unconfigured.
+    readonly given: readonly string[];
+    // Row stays silent if any `unless` key is present: an alternate mechanism already satisfies the evidence.
+    readonly unless?: readonly string[];
+    readonly enables: string;
+    readonly lost: string;
+    readonly repair: string;
+}
+
+/** Undefined and empty env values are equivalent: both count as missing. */
+export type ContainerEnv = Readonly<Record<string, string | undefined>>;
+
+const present = (env: ContainerEnv, name: string): boolean => (env[name] ?? "").trim() !== "";
+
+export const CONTAINER_REQUIREMENTS: readonly ContainerRequirement[] = [
+    // A pre-migration container has the public name but nothing to serve it with: 502 at the edge, forever.
+    {
+        key: "reachability",
+        requires: ["SANDBOX_GRANT", "INGRESS_URL"],
+        given: ["SANDBOX_PUBLIC_URL"],
+        // A Fly microVM's edge replays directly to it, so it holds no grant by design.
+        unless: ["SANDBOX_VM"],
+        enables: "reaching this sandbox at its public address, from anywhere",
+        lost:
+            "Its public address answers 502 to everyone, including this browser when it is not on the same machine as the sandbox. " +
+            "On that machine the workspace still works, over a direct connection that never leaves it — which is why this can go unnoticed for a long time.",
+        repair: "Re-run this sandbox's setup command. It carries a freshly signed grant, and it keeps the workspace, its history and its Docker engine.",
+    },
+];
+
+export interface ContainerGap {
+    readonly key: string;
+    readonly missing: readonly string[];
+    readonly enables: string;
+    readonly lost: string;
+    readonly repair: string;
+}
+
+/** Empty means every requirement is met or not applicable; non-empty always means a setup rerun is needed. */
+export const containerDrift = (env: ContainerEnv): readonly ContainerGap[] =>
+    CONTAINER_REQUIREMENTS.filter(
+        (requirement) => requirement.given.every((name) => present(env, name)) && !(requirement.unless ?? []).some((name) => present(env, name)),
+    )
+        .map((requirement) => ({
+            key: requirement.key,
+            missing: requirement.requires.filter((name) => !present(env, name)),
+            enables: requirement.enables,
+            lost: requirement.lost,
+            repair: requirement.repair,
+        }))
+        .filter((gap) => gap.missing.length > 0);

package/src/protocol/host-protocol.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+// The handshake on /system/hosts/connect, the one message on this socket that isn't oRPC. Proving whose socket it is
+// can't itself be an oRPC call, so the machine's first frame is plain JSON; the daemon verifies it and only then
+// attaches the typed link. Anything before that link exists is this frame or a closed socket.
+
+// Shared with the daemon's peer bridge, which answers the handshake itself when the machine is asleep.
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+
+/* HOW OFTEN THIS DOOR PINGS A CONNECTED MACHINE, read by both sides of the socket: the daemon's hub pings on
+ * it (hosts/host-peer.ts) and the agent presumes a link dead after a few of them pass in silence
+ * (peer-dial.ts's peerLinkSilenceMs). Frequent enough to stay inside the idle timeout of every tunnel and proxy
+ * in the path, and it is the failure of a ping that tells the daemon a lid closed without a close frame ever
+ * arriving. One number, because the two sides disagreeing about it is a device that is either dropped while
+ * healthy or believed alive for as long as its socket stays open. */
+export const HOST_HEARTBEAT_MS = 30_000;
+
+export const HostHelloSchema = z.object({
+    type: z.literal("hello"),
+    // Sent in the first frame, never the URL (a WebSocket has no headers, and a URL gets logged everywhere).
+    token: z.string(),
+    // The build the machine runs, surfaced so an old binary is visible rather than mysteriously missing a tool.
+    version: z.string(),
+});
+export type HostHello = z.infer<typeof HostHelloSchema>;
+
+// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential (the token rides the hello
+// frame); one place builds it, so the agent and the daemon route can't disagree.
+export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;

package/src/protocol/ingress-contract.ts

@@ -0,0 +1,103 @@
+import { createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
+import { SANDBOX_ID } from "../ids/tunnel-ids.js";
+
+// A sandbox proves identity with a signed grant; a hostname's embedded id resolves ownership by parsing, not a registry
+// lookup. Platform, ingress and daemon must agree on every string here. Routing is per h2 stream, since one TLS
+// connection can carry multiple sandboxes' hosts.
+
+// The reachability grant
+
+// Version prefix: an ingress that doesn't recognize it refuses the tunnel rather than negotiating a shape.
+const GRANT_PREFIX = "ig1";
+
+const base64url = (bytes: Buffer): string => bytes.toString("base64url");
+
+// Signed claim; wire fields are `sub` (12-hex sandbox id) and `iat` (seconds). No expiry: the grant lives for a
+// container's whole life, and revocation is deleting the sandbox row.
+export interface ReachabilityGrant {
+    readonly sandboxId: string;
+    readonly issuedAt: number;
+}
+
+// Mints a grant: an Ed25519 signature over the JSON `{sub, iat}` payload, with a PEM/PKCS8 private key.
+export const mintReachabilityGrant = (privateKeyPem: string, sandboxId: string, issuedAtMs: number): string => {
+    if (!SANDBOX_ID.test(sandboxId)) {
+        throw new Error(`a reachability grant names a 12-hex sandbox id, got "${sandboxId}"`);
+    }
+    const payload = Buffer.from(JSON.stringify({ sub: sandboxId, iat: Math.floor(issuedAtMs / 1000) }), "utf8");
+    const signature = edSign(null, payload, createPrivateKey(privateKeyPem));
+    return `${GRANT_PREFIX}.${base64url(payload)}.${base64url(signature)}`;
+};
+
+// Verifies a grant against the platform's public key; any malformed shape returns undefined instead of throwing.
+export const verifyReachabilityGrant = (publicKeyPem: string, token: string): ReachabilityGrant | undefined => {
+    const parts = token.split(".");
+    if (parts.length !== 3 || parts[0] !== GRANT_PREFIX) {
+        return undefined;
+    }
+    try {
+        const payload = Buffer.from(parts[1] as string, "base64url");
+        const signature = Buffer.from(parts[2] as string, "base64url");
+        if (!edVerify(null, payload, createPublicKey(publicKeyPem), signature)) {
+            return undefined;
+        }
+        const parsed = JSON.parse(payload.toString("utf8")) as { sub?: unknown; iat?: unknown };
+        if (typeof parsed.sub !== "string" || !SANDBOX_ID.test(parsed.sub) || typeof parsed.iat !== "number") {
+            return undefined;
+        }
+        return { sandboxId: parsed.sub, issuedAt: parsed.iat };
+    } catch {
+        return undefined;
+    }
+};
+
+// Host to owner routing
+
+// Resolves which sandbox owns a Host: the leftmost DNS label is `sandbox-<id>` or ends in `-<id>` (12-hex); anything
+// else, including the loopback `<id>.local.<zone>` label, returns undefined.
+export const hostOwnerId = (host: string): string | undefined => {
+    const label = host.split(":")[0]?.split(".")[0] ?? "";
+    const match = /-([0-9a-f]{12})$/.exec(label);
+    return match === null ? undefined : match[1];
+};
+
+// Wire constants
+
+// Tunnel door on the ingress; versioned so a v2 session shape adds a new path instead of replacing this one.
+export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
+
+// Grant travels as a header on the tunnel upgrade; this connection is never a browser's.
+export const INGRESS_GRANT_HEADER = "x-intentic-grant";
+
+// Env vars every lane hands the daemon; the daemon reads them directly, not the entrypoint.
+export const ENV_INGRESS_URL = "INGRESS_URL";
+export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
+
+// The daemon-side surface
+
+// Daemon-side tunnel behavior this contract requires: dial, register, forward to the loopback listener, and reconnect
+// forever with backoff, never giving up. `close()` is for shutdown and tests.
+export interface IngressTunnelOptions {
+    // e.g. https://ingress.<zone>; the daemon derives the wss:// door itself via INGRESS_TUNNEL_PATH.
+    readonly url: string;
+    readonly grant: string;
+    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
+    readonly targetPort: number;
+    readonly log: (message: string, error?: unknown) => void;
+}
+
+export interface IngressTunnelHandle {
+    readonly close: () => Promise<void>;
+    // For /health and the boot log: whether the tunnel currently holds a registered session.
+    readonly connected: () => boolean;
+}
+
+export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
+
+// What the ingress side must also honor, enforced by ingress-protocol tests:
+// - Register: verify the grant offline; if PLATFORM_URL is set, check the sandbox exists (GET /api/reachability/<id>)
+//   and cache the answer, failing open if the platform doesn't respond. A 404 refuses the tunnel.
+// - Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
+// - Liveness: WebSocket ping every 15s; a peer silent for 45s is unregistered.
+// - Routing: host maps via hostOwnerId to a registered tunnel; no tunnel answers 502 naming the sandbox label.
+// - The tunnel door and any host without a sandbox id are served directly by the ingress, never routed.

package/src/{ingress-protocol.test.ts → protocol/ingress-protocol.test.ts}

@@ -5,29 +5,16 @@ import { type Duplex, duplexPair } from "node:stream";
 import { afterAll, beforeAll, expect, test } from "vitest";
 import { openIngressSession, serveIngressSession } from "./ingress-protocol.js";
 
-/* THE WHOLE CHAIN, IN PROCESS, exactly as the two consumers wire it:
- *
- *   node http client ─h1→ FRONT server (the ingress) ─h2 stream→ duplex pair ─h2 session→ DAEMON half ─h1→ TARGET
- *
- * Driven by node's own http client rather than by calling the exported functions with hand-built objects,
- * because every property worth pinning here is a property of the BYTES: that a 4MB body survives, that a
- * response arrives in pieces instead of being buffered whole, that a WebSocket's `Sec-WebSocket-Accept` is the
- * daemon's own and not a recomputation, that a half-close reaches the far end. A fake IncomingMessage proves
- * none of those, and each of them is a way this file can be wrong while type-checking perfectly.
- *
- * The front server IS the shape the ingress uses (request → forwardRequest, upgrade → forwardUpgrade, a 502
- * when either rejects with nothing yet said to the browser), so a regression in the promise contract fails
- * here rather than in the ingress package alone. */
+// Drives the full ingress-to-daemon chain (front server, duplex pair, target) through node's real http client, in
+// process, so streaming, half-close and header identity are pinned as bytes, not shapes.
 
 const listen = async (server: Server): Promise<number> => {
     await new Promise<void>((resolve) => void server.listen(0, "127.0.0.1", resolve));
     return (server.address() as AddressInfo).port;
 };
 
-/* Two halves of a test that have to happen in a fixed ORDER without either measuring time: the gate is opened
- * by the far end observing something, and the near end waits for that rather than for a duration. A gate that
- * is never opened fails as the suite's own hang bound, which is the correct report — "the bytes never arrived"
- * is the failure, and no duration in this file would be measuring anything else. */
+// Coordinates a fixed order between two halves without measuring time: the near end waits on the far end's signal; an
+// unopened gate fails as the suite's own hang timeout.
 const gate = <T = void>(): { readonly open: (value: T) => void; readonly opened: Promise<T> } => {
     let open = (_value: T): void => {};
     const opened = new Promise<T>((resolve) => {
@@ -38,8 +25,8 @@ const gate = <T = void>(): { readonly open: (value: T) => void; readonly opened:
 
 const HOST = "sandbox-0123456789ab.sbx.test";
 
-// What the target saw, as the target's own answer, so the assertions are about a real server's view of the
-// forwarded request rather than about the proxy's bookkeeping.
+// What the target saw, mirrored back as its own response, so assertions read a real server's view rather than the
+// proxy's bookkeeping.
 interface Seen {
     readonly method: string;
     readonly url: string;
@@ -62,14 +49,12 @@ const firstChunk = gate();
 const secondSent = gate();
 const uploadStarted = gate();
 
-// 64KB a write, so a `/flood` response keeps node's write queue non-empty and a reset lands on top of a write
-// that has not completed.
+// 64KB per write, keeping node's write queue non-empty so a reset lands on an unfinished write.
 const FLOOD_CHUNK = Buffer.alloc(64 * 1024, 7);
 
 type Route = (request: IncomingMessage, response: ServerResponse) => void | Promise<void>;
 
-// One entry per property under test, rather than a chain of ifs: the routes are independent, and a reader
-// looking for "what does a cancelled request do" should find one function, not the fifth branch of one.
+// One route per property under test, not a branch of one handler, so each behavior has its own function.
 const routes: Record<string, Route> = {
     "/seen": (request, response) => {
         const seen: Seen = {
@@ -87,8 +72,7 @@ const routes: Record<string, Route> = {
         response.writeHead(200, { "content-type": "application/octet-stream", "x-sha256": digest(bytes) });
         response.end(bytes);
     },
-    // Two writes with the SECOND one held until the client has read the first: a proxy that buffers the whole
-    // response before forwarding it deadlocks here instead of passing.
+    // Second write waits for the client to read the first; a proxy that buffers the whole response deadlocks here.
     "/drip": async (_request, response) => {
         response.writeHead(200, { "content-type": "text/event-stream" });
         response.write("one");
@@ -97,22 +81,20 @@ const routes: Record<string, Route> = {
         response.end();
         secondSent.open();
     },
-    // The mirror image: the request body's first chunk must reach here before the client sends the rest.
+    // Mirror of /drip: the first body chunk must arrive here before the client sends the rest.
     "/slurp": async (request, response) => {
         request.once("data", () => uploadStarted.open());
         const bytes = await bodyOf(request);
         response.writeHead(200, { "content-type": "text/plain" });
         response.end(bytes.toString("utf8"));
     },
-    // Never answered: the test asserts that the BROWSER giving up reaches this far, as a close on a response
-    // this server is still holding — "aborted", never the "ended" of an exchange that completed.
+    // Never answered; asserts a client abort surfaces as "aborted", not the "ended" of a completed exchange.
     "/hangup": (_request, response) => {
         response.writeHead(200, { "content-type": "text/event-stream" });
         response.write("open");
         response.on("close", () => cancelled.open(response.writableEnded ? "ended" : "aborted"));
     },
-    // A response big enough that writes are still pending when the client resets the stream: the interleaving
-    // that the loopback bridge exists to survive.
+    // Large enough that writes are still pending when the client resets mid-stream.
     "/flood": (_request, response) => {
         response.writeHead(200, { "content-type": "application/octet-stream" });
         const pump = (): void => {
@@ -139,9 +121,8 @@ const target = createServer((request: IncomingMessage, response: ServerResponse)
 
 const cancelled = gate<string>();
 
-/* A real HTTP/1.1 upgrade, hand-written because this package depends on no WebSocket library and does not need
- * one: what the protocol has to carry is the 101 head and the bytes after it. `/refuse` answers instead of
- * upgrading, which is the other branch of the daemon's CONNECT handling. */
+// Hand-written HTTP/1.1 upgrade carrying the 101 head plus the raw bytes after it. `/refuse` answers instead of
+// upgrading.
 target.on("upgrade", (request: IncomingMessage, socket: Duplex, head: Buffer) => {
     if ((request.url ?? "") === "/refuse") {
         socket.end("HTTP/1.1 404 Not Found\r\nContent-Type: text/plain\r\nContent-Length: 7\r\n\r\nno dice");
@@ -152,8 +133,7 @@ target.on("upgrade", (request: IncomingMessage, socket: Duplex, head: Buffer) =>
             "HTTP/1.1 101 Switching Protocols",
             "Upgrade: websocket",
             "Connection: Upgrade",
-            // Stands in for Sec-WebSocket-Accept: a value only this server can produce, so reading it back
-            // proves the head travelled rather than being reconstructed by the proxy.
+            // A value only this server can produce; proves the head travelled rather than being reconstructed.
             `Sec-WebSocket-Accept: ${digest(Buffer.from(String(request.headers["sec-websocket-key"])))}`,
             `X-Seen-Host: ${String(request.headers.host)}`,
             `X-Seen-Path: ${String(request.url)}`,
@@ -165,12 +145,11 @@ target.on("upgrade", (request: IncomingMessage, socket: Duplex, head: Buffer) =>
         socket.write(head);
     }
     socket.on("data", (chunk: Buffer) => void socket.write(Buffer.concat([Buffer.from("echo:"), chunk])));
-    // A FIN from the far end of the whole chain must arrive as a FIN here, or a WebSocket close handshake never
-    // completes.
+    // A far-end FIN must arrive here or the close handshake never completes.
     socket.on("end", () => void socket.end("bye"));
 });
 
-// The ingress's shape: one session, every request routed through it per request.
+// One session; every request is routed through it.
 const front = async (
     targetPort: number,
 ): Promise<{ readonly server: Server; readonly poison: (bytes: Buffer) => void; readonly close: () => void }> => {
@@ -194,8 +173,7 @@ const front = async (
     });
     return {
         server,
-        // Garbage straight onto the wire the edge reads, interleaved with whatever the daemon half is sending:
-        // what a wedged peer or a half-open socket that came back wrong looks like from the ingress's side.
+        // Writes garbage onto the wire the edge reads, simulating a wedged or corrupted peer.
         poison: (bytes: Buffer) => void daemonSide.write(bytes),
         close: () => {
             session.close();
@@ -208,9 +186,8 @@ const front = async (
 let edge: Awaited<ReturnType<typeof front>>;
 let edgePort = 0;
 
-/* Every ERR_INTERNAL_ASSERTION this module can produce arrives as an uncaught exception from inside node, with
- * none of our frames on the stack — so it is caught HERE or not at all, and a test that merely "passed" while
- * the process was dying is exactly the report that hid this the first time. */
+// Node-internal assertion failures surface only as an uncaughtException with none of our frames on the stack; caught
+// here or not at all.
 const uncaught: string[] = [];
 
 beforeAll(async () => {
@@ -245,7 +222,7 @@ const call = (
 test("a request round-trips with its authority, path and method, and no hop-by-hop header crosses", async () => {
     const answer = await call("/seen?q=1", {
         method: "PUT",
-        // The three the browser must not be able to push through a hop, alongside two that must survive it.
+        // Three headers that must not cross a hop, plus two that must survive it.
         headers: { "x-custom": "kept", "x-forwarded-proto": "https", connection: "close", upgrade: "h2c", "keep-alive": "timeout=99" },
         body: Buffer.from("hi"),
     });
@@ -253,16 +230,9 @@ test("a request round-trips with its authority, path and method, and no hop-by-h
     expect(answer.status).toBe(201);
     expect(answer.headers["x-target"]).toBe("yes");
     const seen = JSON.parse(answer.body.toString("utf8")) as Seen;
-    // The Host the browser used is what the daemon's own listener sees — how a preview, a forwarded port and
-    // the daemon itself are told apart inside the container.
     expect(seen).toMatchObject({ method: "PUT", url: "/seen?q=1", host: HOST });
     expect(seen.headerNames).toContain("x-custom");
     expect(seen.headerNames).toContain("x-forwarded-proto");
-    /* Hop-by-hop headers describe ONE hop and are re-derived on each, never forwarded. `connection` is the
-     * assertion that says so by value: the browser sent `close`, and what reaches the target is the `keep-alive`
-     * of the daemon's own loopback hop. Asserting merely that the target sees no `connection` would be asserting
-     * something false — node writes one for its own hop — and would pass just as well if the browser's value had
-     * been forwarded and then overwritten. */
     expect(seen.connection).toBe("keep-alive");
     expect(seen.headerNames).not.toContain("upgrade");
     expect(seen.headerNames).not.toContain("keep-alive");
@@ -274,8 +244,6 @@ test("a multi-megabyte body survives in both directions, byte for byte", async (
     const answer = await call("/echo", { method: "POST", body: payload });
 
     expect(answer.status).toBe(200);
-    // The target's own digest of what it received, and ours of what came back: one assertion per direction,
-    // and neither can pass on a truncated or re-ordered stream.
     expect(answer.headers["x-sha256"]).toBe(digest(payload));
     expect(digest(answer.body)).toBe(digest(payload));
 });
@@ -298,8 +266,6 @@ test("a response is streamed, not buffered: the client reads chunk one before th
     await secondSent.opened;
 
     expect(chunks.join("")).toBe("onetwo");
-    // Two writes, two reads: coalesced into one would mean the proxy held the first until the body was
-    // complete, which is the failure this asserts against.
     expect(chunks.length).toBeGreaterThan(1);
 });
 
@@ -336,8 +302,6 @@ test("an upgrade splices raw bytes, carries the far end's own handshake head, an
     });
 
     expect(upgraded.status).toBe(101);
-    // Computed by the target from the key the browser sent, and therefore proof that the original request
-    // headers reached it through the CONNECT envelope AND that its answer came back verbatim.
     expect(upgraded.headers["sec-websocket-accept"]).toBe(digest(Buffer.from(key)));
     expect(upgraded.headers["x-seen-host"]).toBe(HOST);
     expect(upgraded.headers["x-seen-path"]).toBe("/socket");
@@ -350,7 +314,6 @@ test("an upgrade splices raw bytes, carries the far end's own handshake head, an
         upgraded.socket.on("end", () => resolve(read));
     });
     upgraded.socket.write("abc");
-    // Half-close: the far end must see the FIN, answer on the still-open direction, and then end.
     upgraded.socket.end();
 
     expect(await spliced).toBe("echo:abcbye");
@@ -386,15 +349,10 @@ test("a browser that gives up cancels the stream all the way to the target", asy
     });
     request.destroy();
 
-    // Without the RST_STREAM this asserts, the target keeps generating a response for a browser that is gone,
-    // for as long as the container lives.
     await expect(cancelled.opened).resolves.toBe("aborted");
 });
 
 test("a tunnel whose target is not listening fails the exchange rather than answering for it", async () => {
-    // A port nothing serves: the daemon half cannot reach a listener, so the exchange must fail in a way the
-    // ingress can turn into its own 502 — the body naming the host label is the ingress's to write, not this
-    // module's.
     const dead = createServer();
     const deadPort = await listen(dead);
     await new Promise<void>((resolve) => void dead.close(() => resolve()));
@@ -402,8 +360,7 @@ test("a tunnel whose target is not listening fails the exchange rather than answ
     const [edgeSide, daemonSide] = duplexPair();
     const daemon = await serveIngressSession(daemonSide, { targetPort: deadPort });
     const session = await openIngressSession(edgeSide);
-    // What the ingress needs to be true of the rejection, reported through the answer rather than asserted
-    // inside a catch nothing awaits: it is free to write a status, so nothing was said to the browser first.
+    // True if a status was already written before the rejection handler runs.
     const said = gate<boolean>();
     const server = createServer((request, response) => {
         void session.forwardRequest(request, response).catch(() => {
@@ -429,23 +386,11 @@ test("a tunnel whose target is not listening fails the exchange rather than answ
     server.close();
 });
 
-/* THE REGRESSION THIS MODULE'S TRANSPORT EXISTS FOR. Reset a batch of streams that are mid-write and the h2
- * session emits control frames on top of writes that have not completed — which, run directly over a Duplex,
- * is node's one-write-per-turn JSStreamSocket invariant and an ERR_INTERNAL_ASSERTION out of an internal
- * callback. Measured twice over: the process died, AND the RST_STREAM never went out, so the cancellation
- * never reached the container.
- *
- * Driven entirely through the public API, so it keeps pinning the behaviour however the transport is built. If
- * someone removes the loopback bridge because "http2 takes a Duplex", this is the test that goes red. */
 test("a shutdown landing on top of pending writes neither crashes nor wedges the session", async () => {
     const own = await front((target.address() as AddressInfo).port);
     const ownPort = await listen(own.server);
 
-    /* Eight responses actively writing, each confirmed to be delivering bytes before the shutdown, so node's
-     * write queue is genuinely non-empty when the GOAWAY is produced. All eight stay live on purpose: an
-     * earlier version of this test reset half of them first and passed against the broken transport, because
-     * the resets drained the very pressure the shutdown has to land on top of. (The reset path has its own
-     * test above; what is being pinned here is a control frame written over pending data.) */
+    // All eight stay live: resetting some first would drain the pending-write pressure the shutdown needs to land on.
     const flooding = Array.from({ length: 8 }, () =>
         new Promise<void>((resolve) => {
             const request = h1Request({ host: "127.0.0.1", port: ownPort, path: "/flood", headers: { host: HOST } }, (response) => {
@@ -461,19 +406,12 @@ test("a shutdown landing on top of pending writes neither crashes nor wedges the
     await new Promise((resolve) => setTimeout(resolve, 400));
     own.server.close();
 
-    /* Two ways to fail, and the suite's own budget is the second one. Run straight over a Duplex this hangs:
-     * the shutdown frame cannot be written, so `close()` never completes and the tunnel wedges holding every
-     * stream on it — which is why a hang bound, rather than a duration, is the right report here. */
+    // If the shutdown frame can't be written, this hangs; the suite's timeout is the failure signal, not an assertion.
     expect(uncaught).toStrictEqual([]);
-    // And the neighbours are untouched: the shared fixture's session still serves.
     const after = await call("/seen");
     expect(after.status).toBe(201);
 });
 
-/* CONTAINMENT: one tunnel's session dying must be one tunnel's problem. The ingress holds every sandbox's
- * session in a single process, so a peer that speaks nonsense — a wedged container, a half-open socket that
- * came back as garbage, anything that makes nghttp2 give up — is the failure most likely to be shared, and it
- * must not be. */
 test("a poisoned session dies alone and leaves another tunnel serving", async () => {
     const targetPort = (target.address() as AddressInfo).port;
     const poisoned = await front(targetPort);
@@ -493,15 +431,12 @@ test("a poisoned session dies alone and leaves another tunnel serving", async ()
     expect(await through(poisonedPort)).toBe(201);
     expect(await through(healthyPort)).toBe(201);
 
-    // Not an h2 frame by any reading: the session must fail rather than try to interpret it.
+    // Not a valid h2 preface; the session must fail rather than parse it.
     poisoned.poison(Buffer.from("this is not a PRI * HTTP/2.0 preface, nor anything else nghttp2 accepts"));
     await new Promise((resolve) => setTimeout(resolve, 250));
 
-    // The dead session refuses new streams, which the front turns into its 502 — the tunnel is gone, and that
-    // is a routing fact rather than a crash.
     expect(await through(poisonedPort)).toBe(502);
     expect(uncaught).toStrictEqual([]);
-    // The whole point: the other tunnel never noticed.
     expect(await through(healthyPort)).toBe(201);
 
     poisoned.close();