@gavin-hu/my-pi-agent 0.19.0 → 0.21.0

package/lib/bus-request.ts

@@ -0,0 +1,83 @@
+/**
+ * The request/response handshake each caller runs over `pi.events`.
+ *
+ * Pi loads every extension with its own module cache, so one extension cannot call
+ * another: `plan` is asked to enter plan mode, `session-bus` to join the team, and
+ * `serve` to hand a page a prefix — each on a channel, each with a payload of its own.
+ * What they share is not the question but the answer's two guarantees: it settles
+ * exactly once, and a caller with no listener is told so rather than left waiting.
+ *
+ * The refusal stays with the caller: this module never names an extension, a tool, or
+ * a sentence. Value-only, as `lib/` must be: the state is the caller's bus and one
+ * closure.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * What a listener answers with: the value, or the promise of one it has not got yet.
+ *
+ * An owner may have to bind a socket, start a bus, or read a repository before it
+ * knows the answer, and the *claim* is the answer, not the result — so it hands back
+ * the promise and stays claimed while it works, rather than leaving the caller to
+ * guess whether anyone is there.
+ */
+export type BusAnswer<T> = T | Promise<T>;
+
+/** One question for one channel. */
+export interface BusRequest<T, P> {
+	/** The `pi.events` channel the owner answers on. */
+	channel: string;
+	/**
+	 * The object it reads, with `respond` given beside it: the helper supplies the one
+	 * answer a request has, so no listener can answer twice and no caller can settle
+	 * its own request.
+	 */
+	payload(respond: (answer: BusAnswer<T>) => void): P;
+	/**
+	 * The answer when no listener claimed the request — the sentence that names the
+	 * extension which is not loaded. Settled on the microtask after the emit, because
+	 * a listener claims synchronously or not at all.
+	 */
+	unclaimed(): T;
+	/**
+	 * The answer when a listener claimed the request and then failed; defaults to
+	 * {@link unclaimed}, which reads the same to a caller that cannot tell why.
+	 */
+	failed?(error: unknown): T;
+}
+
+/**
+ * Ask `request`'s channel for its answer, and settle once.
+ *
+ * Resolves the claimant's answer — including one it is still producing — or
+ * {@link BusRequest.unclaimed} when nobody claimed the request, so a session running
+ * without that extension reports a sentence instead of hanging.
+ */
+export function requestOverBus<T, P>(pi: Pick<ExtensionAPI, "events">, request: BusRequest<T, P>): Promise<T> {
+	return new Promise<T>((resolve) => {
+		let claimed = false;
+		let settled = false;
+		const settle = (answer: T): void => {
+			if (settled) return;
+			settled = true;
+			resolve(answer);
+		};
+		const respond = (answer: BusAnswer<T>): void => {
+			if (claimed) return;
+			claimed = true;
+			// A claim that is still binding answers later, so its failure needs one place to
+			// become the sentence the caller reports rather than an unhandled rejection.
+			Promise.resolve(answer).then(settle, (error: unknown) => {
+				const failed = request.failed;
+				settle(failed === undefined ? request.unclaimed() : failed(error));
+			});
+		};
+		pi.events.emit(request.channel, request.payload(respond));
+		// A listener claims synchronously or not at all, so a request nothing claimed is one
+		// no extension is listening for.
+		queueMicrotask(() => {
+			if (!claimed) settle(request.unclaimed());
+		});
+	});
+}

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;

package/lib/http/index.ts

@@ -1,22 +1,26 @@
 /**
  * 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.
+ * guards built on them, the one server entry, the socket seam behind it, and the
+ * mount contract a page uses to claim a prefix on the session's one port.
  *
- * 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
+ * Import from here rather than a leaf module, so the layer reads as one kit. The
+ * `serve` extension imports {@link serveHttp} and never `./server.ts`; every other
+ * extension imports {@link requestMount} and never binds a socket at all — 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}.
  *
  * Value-only, like the rest of `lib/`: the only state is what a returned closure
- * carries (`createCloser`, `serveLoopback`).
+ * carries (`createCloser`, `serveHttp`).
  */
 
 export * from "./guard.ts";
 export * from "./headers.ts";
+export * from "./mount.ts";
+export * from "./port.ts";
 export * from "./response.ts";
 export * from "./router.ts";
 export * from "./serve.ts";

package/lib/http/mount.ts

@@ -0,0 +1,142 @@
+/**
+ * The contract a page and the session's one server agree on.
+ *
+ * A session has one port and `serve` owns it, so a page cannot bind: it *mounts* a
+ * prefix and is handed back where it answers. Pi loads every extension with an
+ * isolated module cache and forbids one extension importing another, so the request
+ * travels on `pi.events` as an in-process request/response, on the handshake in
+ * `lib/bus-request.ts`.
+ *
+ * The handshake is claimed, not awaited: a mount binds, and `server.listen` cannot
+ * answer synchronously, so `respond` takes the *pending* outcome and only a request
+ * no listener claimed settles as "no server". That distinction is the difference
+ * between a page that starts and a page that is told the extension is missing.
+ *
+ * Value-only, as `lib/` must be: the state is the caller's bus and its closures.
+ */
+
+import type { NetworkInterfaceInfo } from "node:os";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type BusAnswer, requestOverBus } from "../bus-request.ts";
+import { messageOf } from "../errors.ts";
+import type { IdleGrace } from "./sink.ts";
+import type { LoopbackHandler } from "./serve.ts";
+
+/** EventBus channel on which a page asks the session's server for a prefix. */
+export const HTTP_MOUNT_CHANNEL = "my-pi-agent/http/mount";
+
+/** The refusal a page shows when nothing owns the session's socket. */
+export const NO_SERVER_REASON = "the serve extension is not loaded, so this session has no port";
+
+/** One page's request for a prefix on the session's server. */
+export interface MountSpec {
+	/**
+	 * The Pi session asking. The server is per session, so a mount from another one —
+	 * a WeChat peer, a second session in this process — never lands on this socket.
+	 */
+	session: string;
+	/** The prefix it answers under, e.g. `/board`; `""` claims the whole origin. */
+	prefix: string;
+	handler: LoopbackHandler;
+	/** Largest request body accepted here; absent, a route sees `""`. */
+	maxBodyBytes?: number;
+	/** Grace after this page's last reader leaves; omitted, it waits for `release()`. */
+	idle?: IdleGrace;
+}
+
+/** A prefix this page now serves. */
+export interface HttpMount {
+	/** The prefix, normalized: `/board`. */
+	base: string;
+	/** `http://127.0.0.1:<port>`, the session's one origin. */
+	origin: string;
+	/** The port the session's server bound. */
+	port: number;
+	/**
+	 * Free the prefix. Idempotent; the socket closes with its last mount, so a page
+	 * that is done does not hold the session's port.
+	 */
+	release(): Promise<void>;
+	/**
+	 * Serve this same page on one LAN address, for a review shared with a teammate.
+	 * `undefined` when the machine has no address to offer or the bind failed, so the
+	 * caller keeps the sentence that explains it.
+	 */
+	share(): Promise<SharedListener | undefined>;
+	/** Stop serving on the LAN address; the loopback mount keeps answering. */
+	unshare(): Promise<void>;
+}
+
+/** The LAN address a shared page answers on. */
+export interface SharedListener {
+	/** The address a link names, e.g. `192.168.1.24`. */
+	address: string;
+	/** `http://<address>:<port>`, which may differ from the loopback port. */
+	origin: string;
+}
+
+/** The machine's interfaces, as `os.networkInterfaces()` reports them. */
+export type NetworkInterfaces = Record<string, NetworkInterfaceInfo[] | undefined>;
+
+/**
+ * The addresses a teammate could reach this machine on: one per non-internal IPv4
+ * interface, ordered so a link is stable between calls.
+ *
+ * This is what a shared page is offered, never `0.0.0.0`: a review opens exactly
+ * one address, so the link the owner sends is the whole surface. Link-local
+ * (`169.254.*`) addresses are left out because they reach nothing.
+ */
+export function lanAddresses(interfaces: NetworkInterfaces): string[] {
+	const addresses = new Set<string>();
+	for (const entries of Object.values(interfaces)) {
+		for (const entry of entries ?? []) {
+			if (entry.family !== "IPv4" || entry.internal) continue;
+			if (entry.address === "0.0.0.0" || entry.address.startsWith("169.254.")) continue;
+			addresses.add(entry.address);
+		}
+	}
+	return [...addresses].sort(byAddress);
+}
+
+/** Numeric IPv4 comparison, so `…1.9` sorts before `…1.24`. */
+function byAddress(a: string, b: string): number {
+	const left = a.split(".").map(Number);
+	const right = b.split(".").map(Number);
+	for (let index = 0; index < 4; index++) {
+		const difference = (left[index] ?? 0) - (right[index] ?? 0);
+		if (difference !== 0) return difference;
+	}
+	return a.localeCompare(b);
+}
+
+/** What a mount request answers with: the page's place, or the reason it has none. */
+export type MountOutcome = { kind: "mounted"; mount: HttpMount } | { kind: "refused"; reason: string };
+
+/** The question, as it travels on the bus. */
+export interface MountRequest {
+	spec: MountSpec;
+	/**
+	 * Called once, by the owner, **synchronously** with the bind it just started. A
+	 * request nobody claims is a session without a server.
+	 */
+	respond(pending: BusAnswer<MountOutcome>): void;
+}
+
+/** How a page asks for its prefix; the seam a caller substitutes in a test. */
+export type MountSource = (spec: MountSpec) => Promise<MountOutcome>;
+
+/**
+ * Ask the session's server for `spec`'s prefix.
+ *
+ * Resolves `refused` with {@link NO_SERVER_REASON} when no listener claims the
+ * request, so a session running without `serve` fails with a sentence instead of
+ * hanging or binding a rival socket.
+ */
+export function requestMount(pi: Pick<ExtensionAPI, "events">, spec: MountSpec): Promise<MountOutcome> {
+	return requestOverBus<MountOutcome, MountRequest>(pi, {
+		channel: HTTP_MOUNT_CHANNEL,
+		payload: (respond) => ({ spec, respond }),
+		unclaimed: () => ({ kind: "refused", reason: NO_SERVER_REASON }),
+		failed: (error) => ({ kind: "refused", reason: messageOf(error) }),
+	});
+}

package/lib/http/port.ts

@@ -0,0 +1,25 @@
+/**
+ * The per-session port band the loopback pages share.
+ *
+ * `serve` draws the session's one port from it, so every page that session serves
+ * clusters where a person's bookmarks already point. The band is one product decision,
+ * stated here once: a number repeated in each extension's config is several chances to
+ * move one of them, and nothing would notice until a bookmark landed outside the range.
+ *
+ * A pick is a guess, not a reservation. `serveHttp` binds it and falls back to whatever
+ * free port the OS gives, so a port another process holds costs a retry rather than a
+ * start.
+ */
+
+import { randomInt } from "node:crypto";
+
+/** Base of the per-session port range. */
+export const PORT_BASE = 4780;
+
+/** Number of ports in the per-session range. */
+export const PORT_RANGE = 1000;
+
+/** A random port in the per-session range `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
+export function randomPort(): number {
+	return PORT_BASE + randomInt(PORT_RANGE);
+}

package/lib/http/serve.ts

@@ -1,16 +1,21 @@
 /**
- * One loopback server per served surface: bind, accept, route, stream, idle,
- * close.
+ * The one loopback server a session serves its pages on: bind once, dispatch by
+ * mount, 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.
+ * A session has one port, so the socket cannot belong to a page. A page *mounts* a
+ * path prefix on it — `/board`, `/files`, `/plan/<id>` — and the server owns
+ * everything a request does not decide: the longest-prefix dispatch, the body cap
+ * of whichever mount was reached, `HEAD` of a stream, the event-stream head, the
+ * port retry, and a close that is safe to call twice. A mount's handler is handed
+ * the request target *relative to its own prefix*, so a router keeps matching the
+ * paths it always matched.
  *
- * 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.
+ * The idle grace is per mount, not per socket: one page going quiet must not close
+ * another's, so a mount carries its own open-stream registry and release, and the
+ * socket closes when its last mount leaves.
+ *
+ * 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.
  */
@@ -25,6 +30,7 @@ import {
 import type { ArmTimer } from "../timer.ts";
 import { jsonHeaders } from "./headers.ts";
 import { type ServeResponse, textResponse } from "./response.ts";
+import { parseRequestUrl } from "./router.ts";
 import { bindHost, createCloser, openEventStream, respond } from "./server.ts";
 import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "./sink.ts";
 
@@ -32,7 +38,7 @@ import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "
 export interface LoopbackRequest {
 	/** Upper-cased method, e.g. `GET`. */
 	method: string;
-	/** The request target, path and query. */
+	/** The request target, path and query, relative to the mount's prefix. */
 	url: string;
 	/** Headers exactly as the socket carried them; the router applies its `Host` rule. */
 	headers: IncomingHttpHeaders;
@@ -57,35 +63,67 @@ export interface LoopbackReply {
 /** 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[];
+/** One page's claim on a path prefix. */
+export interface ServedMount {
+	/** The prefix it answers under: `/board`, or `""` for the whole origin. */
+	prefix: string;
 	handler: LoopbackHandler;
-	/** Largest body accepted; absent, no body is read and a route sees `""`. */
+	/** Largest body accepted here; absent, no body is read and a route sees `""`. */
 	maxBodyBytes?: number;
-	/** Grace after the last event stream leaves; omitted, the server waits for `close()`. */
+	/** Grace after this mount's last stream leaves; omitted, it waits for `release()`. */
 	idle?: IdleGrace;
-	/** The timer the idle grace is armed on. */
+	/** The timer this mount's idle grace is armed on. */
 	timer?: ArmTimer;
 }
 
-/** A bound loopback server. */
-export interface LoopbackServer {
+/** A prefix served on a running server. */
+export interface Mount {
+	/** The normalized prefix, e.g. `/board`. */
+	base: string;
+	/** The port the server bound. */
+	port: number;
+	/** `http://<host>:<port>`, the address this mount is reached on. */
+	origin: string;
+	/**
+	 * End this mount's streams and free its prefix. Idempotent, and the server closes
+	 * with its last mount.
+	 */
+	release(): Promise<void>;
+}
+
+export interface ServeOptions {
+	/** 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[];
+}
+
+/** A bound server, before any page has mounted on it. */
+export interface ServedServer {
 	/** 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.
+	 * Add one prefix. `undefined` means the prefix is already taken, which a caller
+	 * reports rather than lets two pages answer as one.
+	 */
+	mount(spec: ServedMount): Mount | undefined;
+	/**
+	 * End every mount's streams and close the socket. Idempotent, and what the last
+	 * mount's release does on its own.
 	 */
 	close(): Promise<void>;
 }
 
+/** One prefix as the server holds it: its spec, its streams, and its mount handle. */
+interface Route {
+	spec: ServedMount;
+	base: string;
+	sinks: SinkRegistry;
+	mount: Mount;
+}
+
 /** The one refusal this layer answers itself: a body it will not read. */
 const BODY_TOO_LARGE: ServeResponse = {
 	status: 413,
@@ -99,6 +137,10 @@ 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");
 
+/** A prefix no mount claims, and a target no URL parser accepts. */
+const NOT_FOUND: ServeResponse = textResponse(404, "Nothing is served at this path.");
+const MALFORMED: ServeResponse = textResponse(400, "Malformed request URL.");
+
 /**
  * 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).
@@ -115,6 +157,31 @@ async function bindFirst(server: Server, host: string, ports: readonly number[])
 	throw failure instanceof Error ? failure : new Error(`could not bind ${host}`);
 }
 
+/** One prefix, spelled the way dispatch compares it: no trailing slash, a leading one. */
+function normalizeBase(prefix: string): string {
+	const trimmed = prefix.replace(/\/+$/, "");
+	if (trimmed === "" || trimmed === "/") return "";
+	return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/** Whether `base` is a prefix of `pathname` at a segment boundary; `""` covers everything. */
+function prefixCovers(base: string, pathname: string): boolean {
+	return base === "" || pathname === base || pathname.startsWith(`${base}/`);
+}
+
+/**
+ * The mount a path belongs to: the longest prefix that covers it, so `/plan/a` wins
+ * over a bare `/plan` and a root mount is the fallback rather than the rival.
+ */
+function routeFor(routes: Map<string, Route>, pathname: string): Route | undefined {
+	let best: Route | undefined;
+	for (const route of routes.values()) {
+		if (!prefixCovers(route.base, pathname)) continue;
+		if (best === undefined || route.base.length > best.base.length) best = route;
+	}
+	return best;
+}
+
 /**
  * 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
@@ -157,22 +224,45 @@ function once(fn: (() => void) | undefined): (() => void) | undefined {
 	};
 }
 
-/** Route one request: read, dispatch, then answer, stream, or refuse. */
+/**
+ * Route one request: pick the mount, read, dispatch, then answer, stream, or refuse.
+ *
+ * A request that names a prefix without its slash is redirected to the slashed form,
+ * because a page's own links are relative to its directory and `/board` is not one.
+ */
 async function answer(
 	request: IncomingMessage,
 	response: ServerResponse,
-	options: LoopbackOptions,
-	sinks: SinkRegistry,
+	routes: Map<string, Route>,
+	redirect: (to: string) => ServeResponse,
 ): Promise<void> {
 	const method = request.method ?? "GET";
-	const body = options.maxBodyBytes === undefined ? "" : await readBody(request, options.maxBodyBytes);
+	const target = request.url ?? "/";
+	const parsed = parseRequestUrl(target);
+	if (!parsed) {
+		respond(request, response, MALFORMED);
+		return;
+	}
+	const route = routeFor(routes, parsed.pathname);
+	if (route === undefined) {
+		respond(request, response, NOT_FOUND);
+		return;
+	}
+	if (route.base !== "" && parsed.pathname === route.base) {
+		respond(request, response, redirect(`${route.base}/${parsed.search.toString() === "" ? "" : `?${parsed.search}`}`));
+		return;
+	}
+	const rest = target.slice(route.base.length);
+	const url = rest === "" ? "/" : rest.startsWith("?") ? `/${rest}` : rest;
+	const limit = route.spec.maxBodyBytes;
+	const body = limit === undefined ? "" : await readBody(request, limit);
 	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 });
+		reply = await route.spec.handler({ method, url, headers: request.headers, body });
 	} catch {
 		reply = { result: INTERNAL_ERROR };
 	}
@@ -186,7 +276,7 @@ async function answer(
 	// 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 sink = route.sinks.open(response);
 		const detach = reply.openSink(sink);
 		let closed = false;
 		const finish = (): void => {
@@ -205,30 +295,67 @@ async function answer(
 }
 
 /** Start a server on the first port that binds, and close it idempotently. */
-export async function serveLoopback(options: LoopbackOptions): Promise<LoopbackServer> {
+export async function serveHttp(options: ServeOptions): Promise<ServedServer> {
 	const host = options.host ?? "127.0.0.1";
-	const sinks = createSinks({ idle: options.idle, timer: options.timer });
+	const routes = new Map<string, Route>();
+	let closed = false;
+	let closeServer: (() => Promise<void>) | undefined;
+
+	const close = async (): Promise<void> => {
+		if (closed) return;
+		closed = true;
+		// Streams end first: a connected page must not hold the close open.
+		const open = [...routes.values()];
+		routes.clear();
+		for (const route of open) route.sinks.endAll();
+		await closeServer?.();
+	};
+
 	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(() => {
+		void answer(request, response, routes, (to) => ({
+			status: 301,
+			headers: { ...jsonHeaders(), Location: to },
+			body: "",
+		})).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);
-	const closeServer = createCloser(server);
-	let closed = false;
+	closeServer = createCloser(server);
+	const origin = `http://${host}:${port}`;
+
 	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();
+		origin,
+		mount(spec) {
+			const base = normalizeBase(spec.prefix);
+			if (routes.has(base)) return undefined;
+			const sinks = createSinks({ idle: spec.idle, timer: spec.timer });
+			const route: Route = {
+				spec: { ...spec, prefix: base },
+				base,
+				sinks,
+				mount: {
+					base,
+					port,
+					origin,
+					release: async () => {
+						if (!routes.delete(base)) return;
+						sinks.endAll();
+						if (routes.size === 0) await close();
+					},
+				},
+			};
+			routes.set(base, route);
+			// A mount that asked for a first grace arms it here, so a browser that never
+			// came up cannot hold the prefix for the rest of the session.
+			sinks.start();
+			return route.mount;
 		},
+		close,
 	};
 }

package/lib/http/server.ts

@@ -1,9 +1,9 @@
 /**
- * The socket primitives `serveLoopback` is built from: bind, write a response
- * out, and close.
+ * The socket primitives `serveHttp` is built from: bind, write a response out, and
+ * close.
  *
  * Internal to the layer: an extension starts a server through
- * `serveLoopback`, which composes these, so this module is reached from `lib/http`
+ * `serveHttp`, which composes these, so this module is reached from `lib/http`
  * and its own suite — not from the barrel. Everything here is behavior a caller
  * cannot get right by accident: a bind on an address the caller names (loopback
  * unless it asked for more), an accept-level `error` listener so a transient