@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/lib/board/view.ts

@@ -0,0 +1,234 @@
+/**
+ * The snapshot: the one shape the page knows, built on the server.
+ *
+ * The browser is a dumb renderer over this record, so the lanes, the counts, the
+ * rollup, and the store's size are decided in one place and a client cannot invent
+ * a state the model surface would not report. `sig` is what makes a push cheap:
+ * the page is re-sent only when a card's revision moved.
+ *
+ * `where` is the store's own path, shortened, so a reader can tell which directory
+ * a shared board is filed under — and so nothing here needs a "remote" variant that
+ * no backend produces.
+ *
+ * Pure: the caller supplies the cards, the clock, and the sizes it read.
+ */
+
+import { type RosterSession, type RosterState, rosterStateOf } from "../session-roster.ts";
+import {
+	type Card,
+	CARD_STATUSES,
+	type CardStatus,
+	laneSince,
+	priorityOf,
+	type Priority,
+	signatureOf,
+} from "./card.ts";
+import { blockersOf, indexOf, lanesText, openDependentsOf } from "./links.ts";
+import type { Actor } from "./rules.ts";
+import { buildRound, type RoundSummary } from "./round.ts";
+
+/** One session on the repository's bus, as the Team tab lists it. */
+export interface ViewTeammate {
+	label: string;
+	/** `live` while its heartbeat holds, `quiet` once the record has aged out, `gone` once its process is not running. */
+	state: RosterState;
+	/** When it last proved it was there. */
+	seen: number;
+	/** Messages waiting in its inbox. */
+	mail: number;
+	/** Whether it is listening for mail; absent means its record does not say so. */
+	listening?: boolean;
+	/** Whether this is the session the page writes as. */
+	you: boolean;
+}
+
+/**
+ * One card as the page meets it: the stored card, plus the two answers it would
+ * otherwise compute for itself.
+ *
+ * Both are derived from the board, not stored on the card, so a client that did the
+ * same work would be a second copy of a rule — and the copies drift, which is how the
+ * page came to disagree with the tool about what a card waits for.
+ */
+export interface ViewCard extends Card {
+	/** The priority it acts on: a card that never set one is ordinary. */
+	priority: Priority;
+	/**
+	 * The unfinished cards it waits for, as `#2 (doing)`; absent when nothing blocks it.
+	 *
+	 * `undefined` is the whole fact — a waiting card is one with a `waits` — because a
+	 * boolean beside it would be one more thing that can disagree with the string.
+	 */
+	waits?: string;
+	/**
+	 * The unfinished cards waiting on it, as `#9 (todo)`; absent when none do.
+	 *
+	 * The other side of `waits`: what leaving this card undone holds up. Derived here
+	 * rather than in the page's script for the same reason, and filtered to the unfinished
+	 * for the same reason a finished blocker does not count.
+	 */
+	dependents?: string;
+	/**
+	 * When the card entered the lane it is in now, or absent when its history does not say.
+	 *
+	 * A timestamp rather than a phrase: the page already formats ages, and a wording
+	 * decided here would be a second copy of that rule. Absent is the honest answer for a
+	 * card written before the log existed, so the page draws no age rather than guessing
+	 * one from `updatedAt`, which moves on every write.
+	 */
+	since?: number;
+}
+
+/** One lane and the cards in it, in the order the page draws them. */
+export interface ViewLane {
+	status: CardStatus;
+	cards: ViewCard[];
+}
+
+/** The per-lane tallies the toolbar shows. */
+export interface ViewCounts {
+	total: number;
+	todo: number;
+	doing: number;
+	blocked: number;
+	done: number;
+}
+
+/** Everything the page is allowed to know. */
+export interface BoardView {
+	/** The session a page write is made as — the page's seat, never the browser. */
+	me: { id?: string; label: string };
+	/** The session the page is served from, when the page knows it: who is reading. */
+	session?: { id?: string; label: string };
+	lanes: ViewLane[];
+	counts: ViewCounts;
+	round: RoundSummary<ViewCard>;
+	/**
+	 * The sessions on this repository's bus, or absent when there is no bus here.
+	 *
+	 * Absent is not empty: a page with no roster cannot say who is around, while an
+	 * empty one can say nobody is — and the tab draws those two answers differently.
+	 */
+	teammates?: ViewTeammate[];
+	/** Bytes the store occupies, so a board that is never pruned says so. */
+	bytes: number;
+	/**
+	 * Card files the reader refused, so the footer can say the board is not empty.
+	 *
+	 * Zero is the ordinary answer and draws nothing; a count above it is the one fact
+	 * that separates "no work here" from "this build cannot read your work".
+	 */
+	skipped: number;
+	/** Changes when a card's revision, a teammate's state, or its mail does. */
+	sig: string;
+	/** The store's directory, shortened. */
+	where: string;
+}
+
+/** What the server read before building one snapshot. */
+export interface ViewInput {
+	me: Actor;
+	/**
+	 * The session the page is served from, when it has one.
+	 *
+	 * The page writes as its seat — a fixed name — so the reader's own row on the Team
+	 * tab is marked from the session, not from `me`: the seat is what a card records,
+	 * and the session is who is looking.
+	 */
+	session?: Actor;
+	cards: readonly Card[];
+	now: number;
+	bytes: number;
+	/** Card files the reader refused; absent reads as none, which is the ordinary board. */
+	skipped?: number;
+	where: string;
+	/** The bus's records, when the page could read them at all. */
+	roster?: readonly RosterSession[];
+}
+
+/** Build the page's snapshot. */
+export function buildView(input: ViewInput): BoardView {
+	// One index for the whole snapshot: a card's lane and its blockers are read from the
+	// same board, so a dependency and its dependent cannot be told two different stories.
+	const index = indexOf(input.cards);
+	// One mapped list feeds both halves of the snapshot: the rollup's groups carry the same
+	// card the lane does, so a client reading `round.unassigned` is not handed a card
+	// missing the facts every other card has.
+	const cards = input.cards.map((card) => viewCardOf(card, index));
+	const lanes = CARD_STATUSES.map((status) => ({
+		status,
+		cards: cards.filter((card) => card.status === status),
+	}));
+	const reader = input.session ?? input.me;
+	const teammates = input.roster === undefined ? undefined : teammatesOf(input.roster, reader.label, input.now);
+	return {
+		me: input.me.id === undefined ? { label: input.me.label } : { id: input.me.id, label: input.me.label },
+		...(input.session === undefined ? {} : { session: input.session }),
+		lanes,
+		counts: countOf(lanes),
+		round: buildRound(cards, input.now),
+		...(teammates === undefined ? {} : { teammates }),
+		bytes: input.bytes,
+		skipped: input.skipped ?? 0,
+		// The roster enters the signature at its coarse facts only: a heartbeat every ten
+		// seconds is not news, while a join, a quiet and a letter are. A file that became
+		// readable, or unreadable, is news too: the footer counts it, and a frame that is
+		// not pushed leaves the page saying the board holds less than it does.
+		sig: signatureOf(input.cards) + rosterSignature(teammates) + `|skipped:${input.skipped ?? 0}`,
+		where: input.where,
+	};
+}
+
+/**
+ * One card for the page: what it carries, plus what it acts on.
+ *
+ * The card is copied rather than annotated — the caller's cards are the store's, and a
+ * derived field written onto one would outlive the read that made it.
+ */
+function viewCardOf(card: Card, index: ReadonlyMap<string, Card>): ViewCard {
+	const waits = lanesText(blockersOf(card, index));
+	const dependents = lanesText(openDependentsOf(card.id, index));
+	const since = laneSince(card);
+	return {
+		...card,
+		priority: priorityOf(card),
+		...(waits === "" ? {} : { waits }),
+		...(dependents === "" ? {} : { dependents }),
+		...(since === undefined ? {} : { since }),
+	};
+}
+
+/** The roster as the page shows it, ordered so a repaint never reorders it. */
+function teammatesOf(roster: readonly RosterSession[], meLabel: string, now: number): ViewTeammate[] {
+	return roster
+		.map((session) => ({
+			label: session.label,
+			state: rosterStateOf(session, now),
+			seen: session.lastSeen,
+			mail: session.mail,
+			// A record that does not say is not a promise either way, so the fact is left out
+			// rather than drawn as "not listening".
+			...(session.watching === undefined ? {} : { listening: session.watching.armed }),
+			you: session.label.toLowerCase() === meLabel.toLowerCase(),
+		}))
+		.sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** What a frame must know about the roster; `seen` is left out on purpose. */
+function rosterSignature(teammates: readonly ViewTeammate[] | undefined): string {
+	if (teammates === undefined) return "";
+	return (
+		"|" +
+		teammates.map((teammate) => `${teammate.label}:${teammate.state}:${teammate.mail}:${teammate.listening}`).join(",")
+	);
+}
+
+/** The tallies, summed from the lanes so the two can never disagree. */
+function countOf(lanes: readonly ViewLane[]): ViewCounts {
+	const counts: ViewCounts = { total: 0, todo: 0, doing: 0, blocked: 0, done: 0 };
+	for (const lane of lanes) {
+		counts[lane.status] = lane.cards.length;
+		counts.total += lane.cards.length;
+	}
+	return counts;
+}

package/lib/errors.ts

@@ -1,12 +1,20 @@
 /**
- * One error-to-line helper for an unknown thrown value.
+ * Two helpers for an unknown thrown value: what to say about it, and whether it is the
+ * failure a caller was waiting for.
  *
- * Extensions report a rejected promise, a failed child process, and a parser
- * error the same way: an `Error` yields its message, and anything else is
- * stringified. Kept value-only so every extension has one definition.
+ * Extensions report a rejected promise, a failed child process, and a parser error the
+ * same way: an `Error` yields its message, and anything else is stringified. A `code` —
+ * `EEXIST`, `EPERM` — is what a filesystem write branches on, and reading it off an
+ * unknown value is the same boundary, so it lives here too. Kept value-only so every
+ * caller has one definition.
  */
 
 /** A user-facing message for an unknown thrown value. */
 export function messageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
+
+/** Whether an unknown thrown value carries one errno code, such as `EEXIST`. */
+export function hasErrorCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === code;
+}

package/lib/format.ts

@@ -53,6 +53,28 @@ export function formatDuration(ms: number): string {
 	return `${hours}h${String(minutes % 60).padStart(2, "0")}m`;
 }
 
+/**
+ * A coarse age, the way a reader says it: `now`, `3m`, `2h`, `5d`.
+ *
+ * One rule for both surfaces that print an age — a card's offer in the transcript, and
+ * the same card on the page — so one fact cannot read `2h ago` in a tool result and `3h`
+ * on the page. Written as concatenation because the page's bundle carries this function's
+ * *source* (`FORMAT_AGE_JS`): a backtick or an interpolation in it would end the string it
+ * is spliced into.
+ */
+export function formatAge(now: number, at: number): string {
+	const seconds = Math.max(0, Math.round((now - at) / 1000));
+	if (seconds < 45) return "now";
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return minutes + "m";
+	const hours = Math.round(minutes / 60);
+	if (hours < 24) return hours + "h";
+	return Math.round(hours / 24) + "d";
+}
+
+/** {@link formatAge} as the page's bundle receives it. */
+export const FORMAT_AGE_JS = String(formatAge);
+
 /** `1 tool`, `3 tools`: a tool count with the right word. */
 export function formatToolCount(count: number): string {
 	const n = Number.isFinite(count) ? Math.max(0, Math.trunc(count)) : 0;
@@ -166,3 +188,16 @@ export function shortenPath(path: string, home: string = homedir()): string {
 	if (normalized === root) return "~";
 	return normalized.startsWith(`${root}/`) ? `~${normalized.slice(root.length)}` : normalized;
 }
+
+/** A compact byte size for a listing or a report: `68 B`, `12.4 kB`, `1.5 MB`. */
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["kB", "MB", "GB", "TB"];
+	let value = bytes;
+	let index = -1;
+	do {
+		value /= 1024;
+		index++;
+	} while (value >= 1024 && index < units.length - 1);
+	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[index]}`;
+}

package/lib/http/guard.ts

@@ -0,0 +1,112 @@
+/**
+ * The request guards both loopback servers apply before a route runs: the method
+ * allowlist, the `Host` allowlist, the cross-origin refusal, and — for a server
+ * that takes JSON — the content-type check.
+ *
+ * These were the `plan` review server's own three helpers until a second
+ * mutating page needed them. A guard is a policy, and two copies of a policy are
+ * how a `Host` rule or an origin rule drifts apart, so the sentences the client
+ * reads and the order they are checked in live here once.
+ *
+ * Each guard answers `undefined` when the request may proceed and the response to
+ * send instead when it may not, so a router reads as a chain of refusals.
+ */
+
+import { jsonHeaders } from "./headers.ts";
+import { hostHeaderName, isAllowedHostHeader } from "./router.ts";
+import { jsonError, type ServeResponse } from "./response.ts";
+
+/** The methods a loopback server answers unless it says otherwise. */
+export const PAGE_METHODS: readonly string[] = ["GET", "HEAD", "POST"];
+
+/** The 405 for a route that only accepts POST, or nothing when the method is right. */
+export function postOnly(method: string, what: string): ServeResponse | undefined {
+	if (method.toUpperCase() === "POST") return undefined;
+	return jsonError(405, `Use POST to ${what}.`);
+}
+
+/**
+ * The 403 for a state-changing request another site made, or nothing when the
+ * caller may proceed.
+ *
+ * A browser sends `Origin` on every state-changing request and `Sec-Fetch-Site`
+ * with its own classification; a request with neither is a script or a test,
+ * which has no ambient credential to abuse. A present `Origin` must name the host
+ * the request was addressed to, so a page served by another site cannot drive
+ * this one through a victim's browser.
+ */
+export function checkOrigin(headers: Record<string, string | string[] | undefined>): ServeResponse | undefined {
+	const site = headers["sec-fetch-site"];
+	if (typeof site === "string" && site !== "" && site !== "same-origin" && site !== "none") {
+		return jsonError(403, "Cross-origin request refused.");
+	}
+	const origin = headers.origin;
+	if (origin === undefined) return undefined;
+	if (typeof origin !== "string" || origin === "") return jsonError(403, "Unexpected Origin header.");
+	let parsed: URL;
+	try {
+		parsed = new URL(origin);
+	} catch {
+		return jsonError(403, "Unexpected Origin header.");
+	}
+	const host = headers.host;
+	if (typeof host !== "string" || hostHeaderName(parsed.host) !== hostHeaderName(host)) {
+		return jsonError(403, "Cross-origin request refused.");
+	}
+	return undefined;
+}
+
+/**
+ * The 415 for a state-changing body that is not JSON, or nothing when it is.
+ *
+ * A server that only reads JSON refuses anything else early: an HTML form post
+ * and a `text/plain` body cannot reach the parser, so the request cannot be
+ * mounted cross-origin by a form or a `<script>` tag.
+ */
+export function requireJsonBody(contentType: string | string[] | undefined): ServeResponse | undefined {
+	const value = Array.isArray(contentType) ? contentType[0] : contentType;
+	if (typeof value === "string" && /^application\/json\s*(;|$)/i.test(value.trim())) return undefined;
+	return jsonError(415, "The request body must be JSON.");
+}
+
+/** What a server answers, and to which host names. */
+export interface EnvelopeOptions {
+	/** The raw request method. */
+	method: string;
+	/** The raw request headers. */
+	headers: Record<string, string | string[] | undefined>;
+	/** The host names this server answers to now. */
+	hosts: readonly string[];
+	/** The methods it serves; `PAGE_METHODS` unless a route set needs more. */
+	allowed?: readonly string[];
+}
+
+/**
+ * The 405 or 403 a request deserves before any route runs, or nothing when the
+ * envelope is acceptable.
+ *
+ * `Host` fails closed: a missing or non-string header is refused too, not just a
+ * foreign one, so the DNS-rebinding guard cannot be skipped by omitting it. Every
+ * method that is not a read is also checked for a foreign origin.
+ */
+export function envelopeRefusal(options: EnvelopeOptions): ServeResponse | undefined {
+	const allowed = options.allowed ?? PAGE_METHODS;
+	const upper = options.method.toUpperCase();
+	if (!allowed.includes(upper)) {
+		return {
+			...jsonError(405, `Only ${joinMethods(allowed)} are served.`),
+			headers: { ...jsonHeaders(), Allow: allowed.join(", ") },
+		};
+	}
+	if (!isAllowedHostHeader(options.headers, { hosts: options.hosts, required: true })) {
+		return jsonError(403, "Unexpected Host header.");
+	}
+	const reads = upper === "GET" || upper === "HEAD";
+	return reads ? undefined : checkOrigin(options.headers);
+}
+
+/** `GET, HEAD, and POST` — the list as a sentence a person reads. */
+function joinMethods(methods: readonly string[]): string {
+	if (methods.length <= 1) return methods.join("");
+	return `${methods.slice(0, -1).join(", ")}, and ${methods.at(-1)}`;
+}

package/lib/http/index.ts

@@ -1,13 +1,24 @@
 /**
- * The loopback HTTP layer shared by `file-browse` and `plan`: the response
- * shape, the header policy, the request-envelope helpers, and the socket seam.
+ * The loopback HTTP layer shared by `file-browse`, `plan`, and `board`: the
+ * response shape, the header policy, the request-envelope helpers and the
+ * guards built on them, the one server entry, and the socket seam behind it.
+ *
+ * Import from here rather than a leaf module, so the layer reads as one kit. An
+ * extension imports {@link serveLoopback} and never `./server.ts`: a hand-built
+ * `node:http` server beside this one is how the close path and the idle grace
+ * start to differ again. The same rule covers the guards: `plan` and `board` both
+ * serve a page that can write, so the `Host`, origin, and JSON rules are
+ * {@link envelopeRefusal} and {@link requireJsonBody} rather than two copies, and
+ * the credential a page carries is {@link mintToken} / {@link tokenMatches}.
  *
- * Import from here rather than a leaf module, so the layer reads as one kit.
  * Value-only, like the rest of `lib/`: the only state is what a returned closure
- * carries (`createCloser`).
+ * carries (`createCloser`, `serveLoopback`).
  */
 
+export * from "./guard.ts";
 export * from "./headers.ts";
 export * from "./response.ts";
 export * from "./router.ts";
-export * from "./server.ts";
+export * from "./serve.ts";
+export * from "./sink.ts";
+export * from "./token.ts";

package/lib/http/serve.ts

@@ -0,0 +1,237 @@
+/**
+ * One loopback server per served surface: bind, accept, route, stream, idle,
+ * close.
+ *
+ * Both browser surfaces build the same socket around `lib/http`'s pieces, so the
+ * socket lives here: an extension supplies a handler that turns one request into
+ * one reply, and this module owns everything the request does not decide — the
+ * body cap, `HEAD` of a stream, the event-stream head, the port retry, the idle
+ * grace, and a close that is safe to call twice.
+ *
+ * The `Host` rule stays with each router: the allowlist is per extension, and for
+ * a shared review it grows while the server is up, so it cannot be passed in
+ * once.
+ *
+ * Value-only: the only state is what a returned closure carries.
+ */
+
+import {
+	createServer,
+	type IncomingHttpHeaders,
+	type IncomingMessage,
+	type Server,
+	type ServerResponse,
+} from "node:http";
+import type { ArmTimer } from "../timer.ts";
+import { jsonHeaders } from "./headers.ts";
+import { type ServeResponse, textResponse } from "./response.ts";
+import { bindHost, createCloser, openEventStream, respond } from "./server.ts";
+import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "./sink.ts";
+
+/** One request as a route sees it: the envelope, and a body already capped. */
+export interface LoopbackRequest {
+	/** Upper-cased method, e.g. `GET`. */
+	method: string;
+	/** The request target, path and query. */
+	url: string;
+	/** Headers exactly as the socket carried them; the router applies its `Host` rule. */
+	headers: IncomingHttpHeaders;
+	/** The body, read up to the cap; `""` for every method when no cap was set. */
+	body: string;
+}
+
+/** What a route answers with. */
+export interface LoopbackReply {
+	/** The response to write. A `stream` one needs `openSink` to go with it. */
+	result: ServeResponse;
+	/**
+	 * Runs once, on whichever comes first of the response reaching the wire and the
+	 * socket closing — the point a route may settle a session without a client
+	 * seeing a dropped connection.
+	 */
+	afterResponse?: () => void;
+	/** Open the reply as an event stream; the returned function detaches it. */
+	openSink?: (sink: EventSink) => () => void;
+}
+
+/** One request in, one reply out. A throw is answered as a plain 500. */
+export type LoopbackHandler = (request: LoopbackRequest) => Promise<LoopbackReply> | LoopbackReply;
+
+export interface LoopbackOptions {
+	/** The address to bind; defaults to `127.0.0.1`. */
+	host?: string;
+	/** Ports tried in order, so a remembered port can fall back to an OS-chosen one. */
+	ports: readonly number[];
+	handler: LoopbackHandler;
+	/** Largest body accepted; absent, no body is read and a route sees `""`. */
+	maxBodyBytes?: number;
+	/** Grace after the last event stream leaves; omitted, the server waits for `close()`. */
+	idle?: IdleGrace;
+	/** The timer the idle grace is armed on. */
+	timer?: ArmTimer;
+}
+
+/** A bound loopback server. */
+export interface LoopbackServer {
+	/** The port it actually bound. */
+	port: number;
+	/** `http://<host>:<port>`, the address the caller prints. */
+	origin: string;
+	/**
+	 * End every open stream, stop the idle grace, and close the socket. Idempotent.
+	 *
+	 * A last frame is the caller's to send before it calls this: closing is not a
+	 * conclusion, and only the route knows what its readers were waiting for.
+	 */
+	close(): Promise<void>;
+}
+
+/** The one refusal this layer answers itself: a body it will not read. */
+const BODY_TOO_LARGE: ServeResponse = {
+	status: 413,
+	headers: { ...jsonHeaders(), Connection: "close" },
+	body: JSON.stringify({ error: "The request body is too large." }),
+};
+
+/** A reply that asked to stream but offered no sink cannot be served as events. */
+const STREAM_WITHOUT_SINK: ServeResponse = textResponse(500, "Internal error");
+
+/** A handler that threw, or a socket that failed after its head was written. */
+const INTERNAL_ERROR: ServeResponse = textResponse(500, "Internal error");
+
+/**
+ * Bind the first port that answers, falling back in order. Rejects with the last
+ * bind error, so a caller can still name the reason (`EADDRINUSE` and friends).
+ */
+async function bindFirst(server: Server, host: string, ports: readonly number[]): Promise<number> {
+	let failure: unknown;
+	for (const port of ports.length === 0 ? [0] : ports) {
+		try {
+			return await bindHost(server, host, port);
+		} catch (error) {
+			failure = error;
+		}
+	}
+	throw failure instanceof Error ? failure : new Error(`could not bind ${host}`);
+}
+
+/**
+ * Read a request body, stopping at `limit`. An oversize body is reported rather
+ * than destroyed, so it can still be answered 413 over the open socket instead of
+ * the client seeing a dropped connection.
+ */
+function readBody(request: IncomingMessage, limit: number): Promise<string | undefined> {
+	return new Promise((resolve) => {
+		const chunks: Buffer[] = [];
+		let size = 0;
+		let done = false;
+		const settle = (body: string | undefined): void => {
+			if (done) return;
+			done = true;
+			resolve(body);
+		};
+		request.on("data", (chunk: Buffer) => {
+			if (done) return;
+			size += chunk.length;
+			if (size > limit) {
+				chunks.length = 0;
+				request.pause();
+				settle(undefined);
+				return;
+			}
+			chunks.push(chunk);
+		});
+		request.on("end", () => settle(Buffer.concat(chunks).toString("utf-8")));
+		request.on("error", () => settle(undefined));
+	});
+}
+
+/** A function that runs at most once; `undefined` stays `undefined`. */
+function once(fn: (() => void) | undefined): (() => void) | undefined {
+	if (fn === undefined) return undefined;
+	let done = false;
+	return () => {
+		if (done) return;
+		done = true;
+		fn();
+	};
+}
+
+/** Route one request: read, dispatch, then answer, stream, or refuse. */
+async function answer(
+	request: IncomingMessage,
+	response: ServerResponse,
+	options: LoopbackOptions,
+	sinks: SinkRegistry,
+): Promise<void> {
+	const method = request.method ?? "GET";
+	const body = options.maxBodyBytes === undefined ? "" : await readBody(request, options.maxBodyBytes);
+	if (body === undefined) {
+		respond(request, response, BODY_TOO_LARGE);
+		return;
+	}
+	let reply: LoopbackReply;
+	try {
+		reply = await options.handler({ method, url: request.url ?? "/", headers: request.headers, body });
+	} catch {
+		reply = { result: INTERNAL_ERROR };
+	}
+	const settle = once(reply.afterResponse);
+	if (reply.result.stream === true && reply.openSink === undefined) {
+		respond(request, response, STREAM_WITHOUT_SINK, settle);
+		response.on("close", () => settle?.());
+		return;
+	}
+	// A `HEAD` of a stream is a plain response: there is no body to hold open, and
+	// the client would otherwise wait on frames it asked not to get.
+	if (reply.openSink !== undefined && method.toUpperCase() !== "HEAD") {
+		openEventStream(response, reply.result);
+		const sink = sinks.open(response);
+		const detach = reply.openSink(sink);
+		let closed = false;
+		const finish = (): void => {
+			if (closed) return;
+			closed = true;
+			detach();
+			sink.end();
+			settle?.();
+		};
+		request.on("close", finish);
+		response.on("close", finish);
+		return;
+	}
+	respond(request, response, reply.result, settle);
+	response.on("close", () => settle?.());
+}
+
+/** Start a server on the first port that binds, and close it idempotently. */
+export async function serveLoopback(options: LoopbackOptions): Promise<LoopbackServer> {
+	const host = options.host ?? "127.0.0.1";
+	const sinks = createSinks({ idle: options.idle, timer: options.timer });
+	const server = createServer((request, response) => {
+		// A page that walks away mid-frame must not take the session down.
+		response.on("error", () => {});
+		void answer(request, response, options, sinks).catch(() => {
+			// A route that failed after its head was written can only be cut off; ending
+			// the socket beats a client waiting on a reply that will not come.
+			if (!response.writableEnded) response.end();
+		});
+	});
+	const port = await bindFirst(server, host, options.ports);
+	// The socket is bound but no page may ever read it: a server that asked for a first
+	// grace arms it here, so a browser that never came up cannot hold the port all session.
+	sinks.start();
+	const closeServer = createCloser(server);
+	let closed = false;
+	return {
+		port,
+		origin: `http://${host}:${port}`,
+		close: async () => {
+			if (closed) return;
+			closed = true;
+			// Streams end first: a connected page must not hold the close open.
+			sinks.endAll();
+			await closeServer();
+		},
+	};
+}