@qilin-agent/cli 0.0.0-stage → 3.1.4

package/lib/web-entry-C--0C6wG.js

@@ -0,0 +1,1500 @@
+import { a as isTenantIdentity, i as TenantRuntime, n as LOOPBACK_HOSTS, r as TENANT_VARIABLE, t as BOOTSTRAP_DIRECTORY } from "./tenant-runtime-ChD53FKq.js";
+import { resolveQilinHome } from "@qilin-agent/home-paths";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import { AccountStore, DEPLOYMENT_AUTHORITY_HEADER, accountsFilePath } from "@qilin-agent/accounts-local";
+import { createServer, request } from "node:http";
+import { createServer as createServer$1 } from "node:https";
+import { connect } from "node:net";
+//#region lib/types/tenant-proxy.js
+/**
+* The hub's transport hop into one tenant runtime: an HTTP request forwarded
+* with that runtime's own authority, and an upgraded socket piped the same way.
+*
+* The hop changes transport facts only. It rewrites `Host` to the tenant's
+* authority — the tenant's session cookie is named after the authority it was
+* issued for, so one browser can hold one cookie per tenant on one origin —
+* and rewrites `Origin` to that same authority after checking the browser's
+* own Origin names the hub, which keeps the tenant's same-origin fence as
+* strong as it is without a proxy. Everything else, including `Range`,
+* `Set-Cookie`, `Location`, and partial-content answers, crosses unchanged.
+*
+* The hop decides no access: the tenant runtime's own account gate answers
+* every request, so a forged routing cookie reaches a runtime that does not
+* recognize the caller.
+* @module @qilin-agent/cli/tenant-proxy
+*/
+/**
+* Headers that name one connection rather than one message: forwarded, they
+* would promise the browser a connection the hub does not have.
+*/
+const HOP_BY_HOP = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
+/**
+* Whether a browser-labeled request may be forwarded at all.
+*
+* Over plain HTTP a read carries neither Origin nor Fetch-Metadata, so an
+* absent Origin is accepted and the tenant's own Host fence still binds the
+* request. A present Origin must name the hub exactly, and an explicit
+* cross-site marker is refused: the hub is the outermost hop, so this is the
+* only place those markers can be read before the tenant's authority replaces
+* them.
+* @param headers - browser headers, verbatim.
+* @param hubAuthority - authority the browser used to reach the hub.
+* @returns true when the request may be forwarded.
+*/
+function hubAcceptsOrigin(headers, hubAuthority) {
+	if (headers["sec-fetch-site"] === "cross-site") return false;
+	const origin = headers.origin;
+	if (origin === void 0) return true;
+	try {
+		return new URL(origin).host === hubAuthority;
+	} catch {
+		return false;
+	}
+}
+/**
+* Headers to forward upstream: the browser's own, minus connection-scoped
+* entries, with the authority-bearing ones rewritten to the tenant.
+* @param headers - browser headers, verbatim.
+* @param tenantAuthority - the runtime's own `host:port`.
+* @param deploymentAuthority - authority the browser used to reach the hub, and
+* therefore the one the runtime names its sessions for; empty when the request
+* reached a runtime directly, which then keeps its own authority as the name.
+* Required rather than optional because every hop of this deployment knows it,
+* and an upgrade that forgot it authenticates against a cookie no browser holds.
+* @returns the forwarded header set.
+*/
+function forwardedHeaders(headers, tenantAuthority, deploymentAuthority) {
+	const forwarded = {};
+	for (const [name, value] of Object.entries(headers)) {
+		const lower = name.toLowerCase();
+		if (HOP_BY_HOP.has(lower) || lower === "host" || lower === "origin" || lower === DEPLOYMENT_AUTHORITY_HEADER) continue;
+		forwarded[name] = value;
+	}
+	forwarded.host = tenantAuthority;
+	if (headers.origin !== void 0) forwarded.origin = `http://${tenantAuthority}`;
+	if (deploymentAuthority !== "") forwarded[DEPLOYMENT_AUTHORITY_HEADER] = deploymentAuthority;
+	return forwarded;
+}
+/**
+* Send one request to a tenant runtime and hand back its streaming answer.
+*
+* The hub's own origin fence runs here, in the operation that would forward the
+* request, so no caller can forward a browser request whose Origin names
+* another site.
+* @param options - the runtime, the path, headers, and body to forward.
+* @returns the runtime's status, headers, and body, or the refusal.
+* @throws Error when the runtime is unreachable or refuses the connection.
+*/
+async function proxyRequest(options) {
+	const origin = new URL(options.origin);
+	if (!hubAcceptsOrigin(options.headers, options.hubAuthority)) return {
+		status: 403,
+		headers: { "content-type": "text/plain; charset=utf-8" },
+		stream: Readable.from("qilin tenants: that origin is not this hub\n")
+	};
+	const answered = Promise.withResolvers();
+	const upstream = request({
+		protocol: origin.protocol,
+		hostname: origin.hostname,
+		port: origin.port,
+		method: options.method,
+		path: options.path,
+		headers: forwardedHeaders(options.headers, origin.host, options.hubAuthority)
+	});
+	upstream.on("response", (response) => {
+		answered.resolve({
+			status: response.statusCode ?? 502,
+			headers: response.headers,
+			stream: response
+		});
+	});
+	upstream.on("error", (error) => {
+		answered.reject(error);
+	});
+	options.body?.pipe(upstream);
+	if (options.body === void 0) upstream.end();
+	return await answered.promise;
+}
+/**
+* Write one upstream answer to the browser, streaming the body.
+* @param answer - the runtime's status, headers, and body.
+* @param response - the browser's response.
+*/
+function relayAnswer(answer, response) {
+	const headers = {};
+	for (const [name, value] of Object.entries(answer.headers)) {
+		if (HOP_BY_HOP.has(name.toLowerCase())) continue;
+		headers[name] = value;
+	}
+	response.writeHead(answer.status, headers);
+	answer.stream.pipe(response);
+}
+/**
+* Pipe one upgraded browser socket to the same path on a tenant runtime, with
+* the tenant's authority in place of the hub's.
+*
+* The upgrade is piped, never terminated: the hub holds no copy of the frames,
+* so the tenant's own mux and its trust fence stay in charge of the stream.
+* @param request - the browser's upgrade request.
+* @param socket - the browser's socket.
+* @param head - bytes already read from the browser.
+* @param target - origin of the runtime the socket belongs to.
+* @param headers - already-forwarded headers, with the tenant's authority set.
+*/
+function relayUpgrade(request, socket, head, target, headers) {
+	const origin = new URL(target);
+	const upstream = connect({
+		host: origin.hostname,
+		port: Number(origin.port)
+	});
+	const lines = [`${request.method ?? "GET"} ${request.url ?? "/"} HTTP/1.1`];
+	lines.push("connection: Upgrade");
+	const upgrade = request.headers.upgrade;
+	lines.push(`upgrade: ${typeof upgrade === "string" && upgrade !== "" ? upgrade : "websocket"}`);
+	for (const [name, value] of Object.entries(headers)) {
+		if (value === void 0) continue;
+		for (const entry of Array.isArray(value) ? value : [value]) lines.push(`${name}: ${entry}`);
+	}
+	upstream.on("connect", () => {
+		upstream.write(`${lines.join("\r\n")}\r\n\r\n`);
+		if (head.length > 0) upstream.write(head);
+		upstream.pipe(socket);
+		socket.pipe(upstream);
+	});
+	const closeBoth = () => {
+		upstream.destroy();
+		socket.destroy();
+	};
+	upstream.on("error", closeBoth);
+	socket.on("error", closeBoth);
+	socket.on("close", () => {
+		upstream.destroy();
+	});
+}
+function usageDirectory(home) {
+	return join(home, "tenants", ".usage");
+}
+/** Absolute path of one account's ledger file. */
+function usageFilePath(home, accountId) {
+	return join(usageDirectory(home), `${accountId}.jsonl`);
+}
+/**
+* Append one report to an account's ledger, creating the directory on first use.
+* @param home - deployment home.
+* @param accountId - the account the reporting runtime serves.
+* @param report - the values it reported.
+*/
+async function appendUsage(home, accountId, report) {
+	await mkdir(usageDirectory(home), {
+		recursive: true,
+		mode: 448
+	});
+	await appendFile(usageFilePath(home, accountId), `${JSON.stringify(report)}\n`, {
+		encoding: "utf8",
+		mode: 384
+	});
+}
+/** Whether one report's time falls inside a window. */
+function insideWindow(report, window) {
+	if (window?.from !== void 0 && report.at < window.from) return false;
+	if (window?.to !== void 0 && report.at > window.to) return false;
+	return true;
+}
+/**
+* Read one account's records, latest line per Turn, oldest first.
+*
+* A Turn reported twice keeps the later line and an out-of-order earlier line
+* never replaces it; a line that is not a report is skipped rather than failing
+* the read, because runtimes append to this file while the hub reads it.
+* @param home - deployment home.
+* @param accountId - the account whose ledger to read.
+* @param window - report times to include.
+* @returns the records inside the window, sorted by report time.
+*/
+async function readUsageRecords(home, accountId, window) {
+	let source;
+	try {
+		source = await readFile(usageFilePath(home, accountId), "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+	const perTurn = /* @__PURE__ */ new Map();
+	for (const line of source.split("\n")) {
+		const report = parseUsageReport(line);
+		if (report === void 0 || !insideWindow(report, window)) continue;
+		const key = `${report.sessionId}\n${String(report.turn)}`;
+		const previous = perTurn.get(key);
+		if (previous === void 0 || previous.at <= report.at) perTurn.set(key, report);
+	}
+	return [...perTurn.values()].sort((left, right) => left.at - right.at);
+}
+/**
+* Total the records of one account's ledger inside a window.
+* @param home - deployment home.
+* @param accountId - the account whose ledger to total.
+* @param window - report times to include.
+* @returns the total, zeroes when nothing was reported in the window.
+*/
+async function readUsageTotal(home, accountId, window) {
+	return totalUsage(await readUsageRecords(home, accountId, window));
+}
+/**
+* The report-time window one read asks for.
+* @param params - query parameters of the read.
+* @returns the window, or undefined when a bound is not a whole non-negative
+* number of epoch milliseconds or the bounds are inverted.
+*/
+function readUsageWindow(params) {
+	const bound = (name) => {
+		const raw = params.get(name);
+		if (raw === null || raw === "") return void 0;
+		const value = Number(raw);
+		return Number.isSafeInteger(value) && value >= 0 ? value : "invalid";
+	};
+	const from = bound("from");
+	const to = bound("to");
+	if (from === "invalid" || to === "invalid") return void 0;
+	if (from !== void 0 && to !== void 0 && to < from) return void 0;
+	return {
+		...from === void 0 ? {} : { from },
+		...to === void 0 ? {} : { to }
+	};
+}
+/**
+* The newest records one answer carries, and whether older ones were left out.
+*
+* Records are sorted by report time, so a chart drawn from the newest slice is
+* missing its oldest days rather than scattered holes; the flag says so.
+* @param records - records in report-time order.
+* @param cap - most records one answer may carry.
+* @returns the records to send and whether the cap dropped any.
+*/
+function capUsageRecords(records, cap) {
+	if (cap <= 0) return {
+		records: [],
+		truncated: records.length > 0
+	};
+	return records.length <= cap ? {
+		records: [...records],
+		truncated: false
+	} : {
+		records: records.slice(records.length - cap),
+		truncated: true
+	};
+}
+/**
+* Sum one account's records into a total.
+* @param records - records already deduplicated per Turn.
+* @returns the total they add up to.
+*/
+function totalUsage(records) {
+	const sessions = /* @__PURE__ */ new Set();
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
+	let at = 0;
+	for (const record of records) {
+		sessions.add(record.sessionId);
+		inputTokens += record.inputTokens;
+		outputTokens += record.outputTokens;
+		cacheReadTokens += record.cacheReadTokens ?? 0;
+		cacheWriteTokens += record.cacheWriteTokens ?? 0;
+		at = Math.max(at, record.at);
+	}
+	const prompt = inputTokens + cacheReadTokens;
+	return {
+		sessions: sessions.size,
+		turns: records.length,
+		inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		cacheHitRate: prompt === 0 ? 0 : cacheReadTokens / prompt,
+		at
+	};
+}
+/**
+* Total every account's ledger inside a window.
+* @param home - deployment home.
+* @param window - report times to include.
+* @returns one total per account that reported in the window.
+*/
+async function readUsageTotals(home, window) {
+	const directory = usageDirectory(home);
+	let entries;
+	try {
+		entries = await readdir(directory);
+	} catch (error) {
+		if (error.code === "ENOENT") return {};
+		throw error;
+	}
+	const totals = {};
+	for (const entry of entries) {
+		if (!entry.endsWith(".jsonl")) continue;
+		totals[entry.slice(0, -6)] = await readUsageTotal(home, entry.slice(0, -6), window);
+	}
+	return totals;
+}
+/**
+* Sum every account's total into the deployment's own.
+*
+* The session and turn counts add up rather than deduplicating, because one
+* session belongs to one account: two accounts reporting a session each
+* reported two.
+* @param totals - totals keyed by account identity.
+* @returns the summed total, zeroes when no account has reported.
+*/
+function sumUsageTotals(totals) {
+	let sessions = 0;
+	let turns = 0;
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
+	let at = 0;
+	for (const total of Object.values(totals)) {
+		sessions += total.sessions;
+		turns += total.turns;
+		inputTokens += total.inputTokens;
+		outputTokens += total.outputTokens;
+		cacheReadTokens += total.cacheReadTokens;
+		cacheWriteTokens += total.cacheWriteTokens;
+		at = Math.max(at, total.at);
+	}
+	const prompt = inputTokens + cacheReadTokens;
+	return {
+		sessions,
+		turns,
+		inputTokens,
+		outputTokens,
+		cacheReadTokens,
+		cacheWriteTokens,
+		cacheHitRate: prompt === 0 ? 0 : cacheReadTokens / prompt,
+		at
+	};
+}
+/**
+* Read one ledger line as a report.
+* @param line - one line of an account's ledger.
+* @returns the report, or undefined when the line is empty, torn, or not a report.
+*/
+function parseUsageReport(line) {
+	if (line === "") return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(line);
+	} catch (error) {
+		if (error instanceof SyntaxError) return void 0;
+		throw error;
+	}
+	return isUsageReport(parsed) ? parsed : void 0;
+}
+/**
+* Whether a parsed value carries the report fields with usable values.
+* @param value - the parsed line.
+* @returns true when it is one report.
+*/
+function isUsageReport(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const report = value;
+	if (typeof report["sessionId"] !== "string" || report["sessionId"] === "") return false;
+	if (!isCount(report["inputTokens"]) || !isCount(report["outputTokens"])) return false;
+	if (!isCount(report["turn"])) return false;
+	if (report["cacheReadTokens"] !== void 0 && !isCount(report["cacheReadTokens"])) return false;
+	if (report["cacheWriteTokens"] !== void 0 && !isCount(report["cacheWriteTokens"])) return false;
+	return typeof report["at"] === "number" && Number.isSafeInteger(report["at"]) && report["at"] >= 0;
+}
+/** Whether a value is a whole, non-negative count. */
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+//#endregion
+//#region lib/types/tenants.js
+/**
+* `qilin tenants serve`: one hub over a shared Harness home, one isolated Web
+* runtime per account. Sessions, tasks, and workspaces stay with the account
+* that owns them; plugins, model settings, credentials, and the account file
+* stay shared, so every tenant runtime is that one deployment.
+*
+* The hub authenticates nobody: a handoff is a redirect, not a credential.
+* Each tenant runtime keeps the shared home's account gate and admits only its
+* own account, so the sign-in happens at the runtime and the runtime is the
+* boundary. The hub must be reachable where its account list is not a secret —
+* it binds loopback by default and lists usernames.
+*
+* Idle reclamation counts from the last handoff. A browser that reached a tenant
+* origin keeps talking to that origin directly, which the hub cannot observe, so
+* a deployment that leaves long-lived tabs open raises `--idle-ms` or disables
+* reclamation with 0; `--single-origin` moves that same traffic through the hub
+* instead, and reclamation then counts proxied requests.
+*
+* With `--single-origin` the hub serves one origin and routes by a routing
+* cookie it sets at the handoff: `/api`, the mux upgrade, and media requests are
+* absolute paths on the page origin, so only cookie routing can attribute them
+* to a tenant. The cookie selects a runtime, it does not authorize: the runtime
+* still answers with its own account gate, so a forged cookie reaches a
+* runtime that does not recognize the caller.
+*
+* `--max-tenants` bounds how many runtimes live at once: a handoff that would
+* exceed the bound reclaims the least recently used one, and every tenant's
+* Sessions stay on disk. A runtime that fails to start is not retried on every
+* visit: the hub doubles a wait per consecutive failure, and `/status` reports
+* the count and the earliest retry.
+* @module @qilin-agent/cli/tenants
+*/
+/** Routing cookie the hub sets so later requests, whatever their path, name their tenant. */
+const TENANT_COOKIE = "qilin_tenant";
+/** Largest usage report the ledger accepts; one report is a few dozen bytes. */
+const MAX_USAGE_BODY_BYTES = 4 * 1024;
+/**
+* Most ledger records one read answers with. A bound on the response rather than
+* a deployment choice: a long-lived account reports one record per Turn, so the
+* newest slice is what a chart shows and `truncated` says the rest was left out.
+*/
+const USAGE_RECORDS_CAP = 5e3;
+/**
+* Whether every runtime of this deployment must mark its session cookies
+* `Secure`.
+*
+* The browser reaches the deployment through the hub, so a deployment that
+* terminates TLS itself is the one case where the client's own connection is
+* encrypted; a runtime behind a plain-HTTP hub cannot know otherwise, and it
+* never guesses.
+* @param options - the deployment's own TLS material, when it terminates TLS.
+* @returns true only when this deployment terminates TLS.
+*/
+function secureSessionCookies(options) {
+	return options.tls !== void 0;
+}
+/** The text one proxied answer carries. */
+async function answerText(stream) {
+	const chunks = [];
+	for await (const chunk of stream) chunks.push(chunk);
+	return Buffer.concat(chunks).toString("utf8");
+}
+/** Store key of the runtime a deployment with no accounts uses. */
+const BOOTSTRAP_ACCOUNT = "first-run";
+/**
+* The routing cookie one handoff sets.
+*
+* It selects a runtime; it authorizes nothing. The runtime still answers with
+* its own account gate, so the value is an account identity and not a secret,
+* and `HttpOnly` keeps it out of page scripts that have no use for it.
+* @param accountId - account identity the browser should reach from now on.
+* @returns one `Set-Cookie` value.
+*/
+function routingCookie(accountId) {
+	return `${TENANT_COOKIE}=${accountId}; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000`;
+}
+/** The routing cookie's removal, for a browser whose tenant no longer exists. */
+function clearedRoutingCookie() {
+	return `${TENANT_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`;
+}
+/** Documents the deployment itself answers, whatever account a browser chose. */
+const DEPLOYMENT_DOORS = new Set(["/login", "/setup"]);
+/**
+* Whether a path belongs to the deployment's own doors: the sign-in and setup
+* documents, and the account surface they call.
+*
+* These are where a browser picks, or creates, the account it works as, so they
+* are answered by the runtime that carries the deployment's registration policy
+* rather than by whichever account's runtime this browser happens to hold.
+* @param pathname - the request path.
+* @returns true for the sign-in surface.
+*/
+function deploymentDoor(pathname) {
+	return DEPLOYMENT_DOORS.has(pathname) || pathname.startsWith("/api/auth/");
+}
+/**
+* One cookie value from a request, decoded no further than substitution.
+* @param header - the browser's `Cookie` header.
+* @param name - cookie name to read.
+* @returns the value, or undefined when the browser did not send it.
+*/
+function cookieValue(header, name) {
+	if (header === void 0) return void 0;
+	for (const part of header.split(";")) {
+		const separator = part.indexOf("=");
+		if (separator === -1) continue;
+		if (part.slice(0, separator).trim() === name) return part.slice(separator + 1).trim();
+	}
+}
+/**
+* One path segment read as an account name.
+* @param segment - the raw path segment.
+* @returns the decoded segment, or undefined when it is not valid percent-encoding.
+*/
+function decodeIdentifier(segment) {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return;
+	}
+}
+/**
+* One PEM file the deployment address serves with.
+* @param path - the file the invocation named.
+* @param flag - the flag that named it, for the refusal.
+* @returns the file's bytes.
+* @throws Error when the file cannot be read.
+*/
+function readPem(path, flag) {
+	try {
+		return readFileSync(path);
+	} catch (error) {
+		throw new Error(`qilin tenants: ${flag} ${path} is not readable: ${String(error)}`);
+	}
+}
+/** One answered request. */
+function respond(response, status, contentType, body) {
+	response.writeHead(status, {
+		"cache-control": "no-store",
+		"content-type": contentType,
+		"content-length": Buffer.byteLength(body)
+	});
+	response.end(body);
+}
+/** One JSON answer. */
+function json(response, status, body) {
+	respond(response, status, "application/json; charset=utf-8", `${JSON.stringify(body)}\n`);
+}
+/**
+* Serve the hub until it is asked to stop.
+* @param options - the interface, port, tenant profile, and idle window.
+* @returns the process exit code, 0 after a clean shutdown.
+*/
+/**
+* What the deployment's own address and its tenant interface mean for reaching
+* them, as the lines a start prints.
+*
+* A hub on loopback is reachable from this machine only, and account runtimes
+* bind loopback unless `--tenant-host` names another interface. Naming a
+* reachable one exposes every runtime there directly — plain HTTP, no entry in
+* between — which an operator has to know before treating the hub address as the
+* only door.
+* @param host - interface the entry bound.
+* @param tenantHost - interface each account runtime binds, when the invocation named one.
+* @param port - port the entry bound.
+* @returns one line per fact the operator needs, in print order.
+*/
+function addressNotices(host, tenantHost, port) {
+	const runtimes = tenantHost === void 0 || LOOPBACK_HOSTS.includes(tenantHost) ? "every account runtime stays on loopback" : `each account runtime is reachable at ${tenantHost} over plain HTTP, with no entry in between`;
+	if (!LOOPBACK_HOSTS.includes(host)) return [`qilin tenants: this address is reachable at ${host}:${String(port)}; ${runtimes}`];
+	return tenantHost === void 0 || LOOPBACK_HOSTS.includes(tenantHost) ? [] : [`qilin tenants: ${runtimes}`];
+}
+/**
+* The runtime a handoff stops to make room, or undefined when there is room or
+* nothing may be reclaimed yet.
+*
+* Only a running runtime is a candidate: one that is still starting has no last
+* use to compare, so the next handoff reclaims it once it is serving. The
+* runtime about to start is never its own candidate.
+* @param live - every runtime holding a child, in any state.
+* @param target - the runtime about to start.
+* @param maxTenants - cap on live runtimes; zero or less means no cap.
+* @returns the runtime to stop, if any.
+*/
+function reclaimFor(live, target, maxTenants) {
+	if (maxTenants <= 0) return void 0;
+	const others = live.filter((runtime) => runtime !== target);
+	if (others.length < maxTenants) return void 0;
+	let oldest;
+	for (const runtime of others) {
+		if (runtime.status().state !== "running") continue;
+		if (oldest === void 0 || runtime.lastUsedAt <= oldest.lastUsedAt) oldest = runtime;
+	}
+	return oldest;
+}
+/**
+* One queue that runs handoffs one at a time.
+*
+* Two handoffs that passed the cap together would both start a runtime, so each
+* handoff's make-room-and-start runs behind the previous one. A handoff that
+* fails settles its own promise and leaves the queue ready for the next.
+* @returns a function that queues one handoff.
+*/
+function createHandoffQueue() {
+	let tail = Promise.resolve();
+	return (work) => {
+		const next = tail.then(work, work);
+		tail = next.then(() => void 0, () => void 0);
+		return next;
+	};
+}
+async function runTenantsServe(options) {
+	const home = options.home ?? resolveQilinHome();
+	const binPath = process.argv[1];
+	if (binPath === void 0) throw new Error("qilin tenants: the CLI entry path is unknown, so no tenant runtime can be started");
+	const startRuntime = options.createRuntime ?? ((runtimeOptions) => new TenantRuntime(runtimeOptions));
+	const runtimes = /* @__PURE__ */ new Map();
+	const usageTokens = /* @__PURE__ */ new Map();
+	let usageUrl = "";
+	/** Runtimes holding a child, whether or not it has printed its URL yet. */
+	const active = () => [...runtimes.values()].filter((runtime) => runtime.status().state === "running" || runtime.status().state === "starting");
+	const runtimeFor = (accountId) => {
+		const existing = runtimes.get(accountId);
+		if (existing !== void 0) return existing;
+		const usageToken = randomBytes(32).toString("hex");
+		usageTokens.set(usageToken, accountId);
+		const created = startRuntime({
+			usage: {
+				url: usageUrl,
+				token: usageToken
+			},
+			home,
+			accountId,
+			profile: options.profile,
+			binPath,
+			execArgv: process.execArgv,
+			host: options.tenantHost ?? void 0,
+			restartBackoffMilliseconds: options.restartBackoffMilliseconds,
+			patches: options.patches,
+			appArguments: options.appArguments,
+			sessionCookieSecure: secureSessionCookies(options),
+			log: (line) => {
+				process.stderr.write(`qilin tenants: [${accountId}] ${line}\n`);
+			}
+		});
+		runtimes.set(accountId, created);
+		return created;
+	};
+	/**
+	* The runtime a deployment serves the product's own surface from: the landing
+	* page, the sign-in form, registration, and first-run initialization.
+	*
+	* The registration mode is the deployment's own policy, not a consequence of
+	* holding an account: a deployment that accepts new accounts keeps accepting
+	* them once the first one exists, and only an operator asking for `closed`
+	* turns that off.
+	* @returns the first-run runtime.
+	*/
+	const bootstrapRuntime = () => {
+		const existing = runtimes.get(BOOTSTRAP_ACCOUNT);
+		if (existing !== void 0) return existing;
+		const created = startRuntime({
+			home,
+			accountId: BOOTSTRAP_ACCOUNT,
+			directoryName: BOOTSTRAP_DIRECTORY,
+			bootstrap: true,
+			registration: options.registration,
+			profile: options.profile,
+			binPath,
+			execArgv: process.execArgv,
+			host: options.tenantHost ?? void 0,
+			restartBackoffMilliseconds: options.restartBackoffMilliseconds,
+			patches: options.patches,
+			appArguments: options.appArguments,
+			sessionCookieSecure: secureSessionCookies(options),
+			log: (line) => {
+				process.stderr.write(`qilin tenants: [first-run] ${line}\n`);
+			}
+		});
+		runtimes.set(BOOTSTRAP_ACCOUNT, created);
+		return created;
+	};
+	/**
+	* Bring the live runtimes under the cap by reclaiming the least recently used
+	* ones. Every tenant's Sessions stay on disk, so reclaiming costs one boot.
+	* @param target - the runtime about to start, which is never reclaimed.
+	*/
+	const makeRoom = async (target) => {
+		for (;;) {
+			const oldest = reclaimFor(active(), target, options.maxTenants);
+			if (oldest === void 0) return;
+			process.stderr.write(`qilin tenants: ${String(options.maxTenants)} runtime(s) are already alive; reclaiming ${oldest.status().accountId} to start ${target.status().accountId}\n`);
+			await oldest.stop();
+		}
+	};
+	/** Handoffs run one at a time, so two of them cannot both pass the cap and start. */
+	const serialize = createHandoffQueue();
+	const roster = async () => await AccountStore.open(accountsFilePath(home));
+	const status = async () => {
+		const store = await roster();
+		return {
+			mode: options.singleOrigin ? "single-origin" : "handoff",
+			maxTenants: options.maxTenants,
+			alive: active().length,
+			tenants: [...runtimes.values()].map((runtime) => {
+				const reported = runtime.status();
+				return {
+					...reported,
+					username: store.byId(reported.accountId)?.username ?? null
+				};
+			})
+		};
+	};
+	/**
+	* Resolve the runtime one browser is driving, starting it when it is not serving.
+	* @param store - the roster this request read.
+	* @param accountId - the account the browser's routing cookie names.
+	* @returns the runtime, or undefined when the roster no longer holds that account.
+	*/
+	const routedRuntime = async (store, accountId) => {
+		if (store.byId(accountId) === void 0) return void 0;
+		const runtime = runtimeFor(accountId);
+		await serialize(async () => {
+			await makeRoom(runtime);
+			await runtime.ensure();
+		});
+		return runtime;
+	};
+	/**
+	* Forward one browser request to a runtime and relay its answer.
+	* @param request - the browser's request.
+	* @param response - the browser's response.
+	* @param runtime - the runtime the request belongs to.
+	* @param path - path and query to request upstream.
+	* @param extraCookies - cookies to add to the answer.
+	*/
+	const forward = async (request, response, runtime, path, extraCookies) => {
+		const origin = runtime.proxyTarget();
+		if (origin === void 0) throw new Error("the runtime is not serving");
+		runtime.lastUsedAt = Date.now();
+		const answered = await proxyRequest({
+			origin,
+			method: request.method ?? "GET",
+			path,
+			headers: request.headers,
+			hubAuthority: request.headers.host ?? "",
+			body: request
+		});
+		const upstreamCookies = answered.headers["set-cookie"] === void 0 ? [] : Array.isArray(answered.headers["set-cookie"]) ? answered.headers["set-cookie"] : [answered.headers["set-cookie"]];
+		relayAnswer({
+			...answered,
+			headers: {
+				...answered.headers,
+				"set-cookie": [...upstreamCookies, ...extraCookies]
+			}
+		}, response);
+	};
+	/**
+	* The runtime the product's own surface is served from, running.
+	*
+	* The product hides or shows its register entry from the answer this runtime
+	* reports, and the runtime refuses the call it would hide: both follow the
+	* deployment's registration policy, so an operator who accepts new accounts
+	* sees the entry for every account the roster already holds.
+	* @returns the first-run runtime, running.
+	*/
+	const runningFirstRun = async () => {
+		const runtime = bootstrapRuntime();
+		await serialize(async () => {
+			await makeRoom(runtime);
+			await runtime.ensure();
+		});
+		return runtime;
+	};
+	/**
+	* Hand a request to the runtime a deployment without accounts uses, so the
+	* product's own first-run form creates the first account instead of the
+	* deployment describing what an operator should type.
+	* @param request - the browser's request.
+	* @param response - the browser's answer.
+	* @param path - request path, preserved so the application sees its own route.
+	* @param extraCookies - cookies this deployment appends to the answer.
+	*/
+	const serveFirstRun = async (request, response, path, extraCookies = []) => {
+		try {
+			await forward(request, response, await runningFirstRun(), path, extraCookies);
+		} catch (error) {
+			process.stderr.write(`qilin tenants: the first-run runtime did not start: ${String(error)}\n`);
+			respond(response, 503, "text/plain; charset=utf-8", "qilin tenants: this deployment could not start its first-run runtime\n");
+		}
+	};
+	/**
+	* Which account the browser's session names, as the runtime that issued it
+	* reports it.
+	*
+	* The deployment never reads a session itself: the runtime owns that answer,
+	* and this asks it the same question the product's landing page asks.
+	* @param request - the browser's request, for the cookie that carries the session.
+	* @returns the account id, or undefined when no session names one.
+	*/
+	const signedInAccountId = async (request) => {
+		const origin = (await runningFirstRun()).proxyTarget();
+		if (origin === void 0) return void 0;
+		const answered = await proxyRequest({
+			origin,
+			method: "GET",
+			path: "/api/auth/status",
+			headers: {
+				cookie: request.headers.cookie ?? "",
+				host: request.headers.host ?? ""
+			},
+			hubAuthority: request.headers.host ?? ""
+		});
+		if (answered.status !== 200) {
+			answered.stream.resume();
+			return;
+		}
+		const body = JSON.parse(await answerText(answered.stream));
+		if (typeof body !== "object" || body === null) return void 0;
+		const user = body.user;
+		if (typeof user !== "object" || user === null) return void 0;
+		const id = user.id;
+		return typeof id === "string" ? id : void 0;
+	};
+	const bearerToken = (header) => {
+		if (header === void 0) return void 0;
+		const separator = header.indexOf(" ");
+		if (separator === -1) return void 0;
+		if (header.slice(0, separator).toLowerCase() !== "bearer") return void 0;
+		const value = header.slice(separator + 1).trim();
+		return value === "" ? void 0 : value;
+	};
+	/** The account one presented token was minted for, compared without leaking its prefix. */
+	const accountForToken = (presented) => {
+		const candidate = Buffer.from(presented, "utf8");
+		for (const [token, accountId] of usageTokens) {
+			const known = Buffer.from(token, "utf8");
+			if (known.length === candidate.length && timingSafeEqual(known, candidate)) return accountId;
+		}
+	};
+	/** Read one report body, bounded, or undefined when it is oversized or not JSON. */
+	const readReportBody = async (request) => {
+		const chunks = [];
+		let size = 0;
+		for await (const chunk of request) {
+			const buffer = chunk;
+			size += buffer.length;
+			if (size > MAX_USAGE_BODY_BYTES) return void 0;
+			chunks.push(buffer);
+		}
+		try {
+			return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+		} catch (error) {
+			if (error instanceof SyntaxError) return void 0;
+			throw error;
+		}
+	};
+	/**
+	* Answer a usage read for one account: the administrator's seat widens the
+	* answer to every account's records, tagged; everyone else reads their own.
+	* Shared by the ledger channel (a runtime reporting under its token) and the
+	* browser's own read, which the hub answers directly from its ledger.
+	* @param response - the answer to write.
+	* @param accountId - the account the read belongs to.
+	* @param search - the read's query, carrying the window.
+	*/
+	const answerUsageRead = async (response, accountId, search) => {
+		const window = readUsageWindow(search);
+		if (window === void 0) {
+			json(response, 400, { error: "invalid-window" });
+			return;
+		}
+		const store = await roster();
+		if (store.byId(accountId)?.admin === true) {
+			const tagged = [];
+			for (const account of store.all()) for (const record of await readUsageRecords(home, account.id, window)) tagged.push({
+				accountId: account.id,
+				record
+			});
+			tagged.sort((left, right) => left.record.at - right.record.at);
+			const capped = capUsageRecords(tagged, USAGE_RECORDS_CAP);
+			const totals = await readUsageTotals(home);
+			json(response, 200, {
+				scope: "deployment",
+				totals,
+				total: sumUsageTotals(totals),
+				records: capped.records.map((entry) => ({
+					...entry.record,
+					accountId: entry.accountId
+				})),
+				truncated: capped.truncated
+			});
+			return;
+		}
+		const capped = capUsageRecords(await readUsageRecords(home, accountId, window), USAGE_RECORDS_CAP);
+		json(response, 200, {
+			accountId,
+			total: await readUsageTotal(home, accountId),
+			records: capped.records,
+			truncated: capped.truncated
+		});
+	};
+	/**
+	* Answer one runtime over the ledger channel: a report books spend, and a read
+	* answers what that same token's account spent. Only a token this hub minted
+	* is accepted, so neither verb can name another account.
+	*
+	* The account's own seat widens the read: the deployment's administrator reads
+	* every account's ledger, and the seat is read from the roster on each request
+	* so it follows the account it belongs to rather than the token's age.
+	*/
+	const handleUsage = async (request, response) => {
+		if (request.method !== "POST" && request.method !== "GET") {
+			respond(response, 405, "text/plain; charset=utf-8", "qilin tenants: the ledger reports and reads\n");
+			return;
+		}
+		const presented = bearerToken(request.headers.authorization);
+		const accountId = presented === void 0 ? void 0 : accountForToken(presented);
+		if (accountId === void 0 || !isTenantIdentity(accountId)) {
+			json(response, 401, { error: "unauthorized" });
+			return;
+		}
+		if (request.method === "GET") {
+			await answerUsageRead(response, accountId, new URL(request.url ?? "/", "http://qilin.invalid").searchParams);
+			return;
+		}
+		const body = await readReportBody(request);
+		if (!isUsageReport(body)) {
+			json(response, 400, { error: "invalid-body" });
+			return;
+		}
+		await appendUsage(home, accountId, body);
+		response.writeHead(204);
+		response.end();
+	};
+	const handle = async (request, response) => {
+		const url = new URL(request.url ?? "/", "http://qilin.invalid");
+		if (url.pathname === "/healthz") {
+			json(response, 200, { ok: true });
+			return;
+		}
+		if (url.pathname === "/status") {
+			json(response, 200, await status());
+			return;
+		}
+		const productPath = () => {
+			if (!url.pathname.startsWith("/t/")) return `${url.pathname}${url.search}`;
+			const rest = url.pathname.slice(3);
+			const separator = rest.indexOf("/");
+			return separator === -1 ? `/${url.search}` : `${rest.slice(separator)}${url.search}`;
+		};
+		const store = await roster();
+		if (store.all().length === 0) {
+			await serveFirstRun(request, response, productPath());
+			return;
+		}
+		const hubOwnRoute = url.pathname === "/";
+		if (request.method !== "GET" && !(options.singleOrigin && !hubOwnRoute)) {
+			respond(response, 405, "text/plain; charset=utf-8", "qilin tenants: the hub answers reads only\n");
+			return;
+		}
+		if (url.pathname.startsWith("/t/")) {
+			const rest = url.pathname.slice(3);
+			const separator = rest.indexOf("/");
+			const username = decodeIdentifier(separator === -1 ? rest : rest.slice(0, separator));
+			if (username === void 0) {
+				respond(response, 400, "text/plain; charset=utf-8", "qilin tenants: that account path is not valid UTF-8\n");
+				return;
+			}
+			const account = store.byIdentifier(username);
+			if (account === void 0) {
+				await serveFirstRun(request, response, productPath());
+				return;
+			}
+			try {
+				const runtime = runtimeFor(account.id);
+				const launchUrl = await serialize(async () => {
+					await makeRoom(runtime);
+					return await runtime.ensure();
+				});
+				const deeper = separator === -1 ? "/" : url.pathname.slice(3 + username.length);
+				if (!options.singleOrigin) {
+					response.writeHead(303, {
+						"cache-control": "no-store",
+						"location": `${new URL(launchUrl).origin}${deeper}${url.search}`,
+						"referrer-policy": "no-referrer"
+					});
+					response.end();
+					return;
+				}
+				await forward(request, response, runtime, `${deeper}${url.search}`, [routingCookie(account.id)]);
+			} catch (error) {
+				process.stderr.write(`qilin tenants: the runtime for ${account.username} did not start: ${String(error)}\n`);
+				respond(response, 503, "text/plain; charset=utf-8", `qilin tenants: the runtime for ${account.username} did not start\n`);
+			}
+			return;
+		}
+		if (options.singleOrigin) {
+			const accountId = cookieValue(request.headers.cookie, TENANT_COOKIE);
+			if (deploymentDoor(url.pathname)) {
+				await serveFirstRun(request, response, productPath(), [clearedRoutingCookie()]);
+				return;
+			}
+			if (url.pathname === "/api/usage/me" && request.method === "GET") {
+				const accountId = cookieValue(request.headers.cookie, TENANT_COOKIE) ?? await signedInAccountId(request);
+				if (accountId === void 0 || store.byId(accountId) === void 0) {
+					json(response, 401, { error: "unauthorized" });
+					return;
+				}
+				await answerUsageRead(response, accountId, new URL(request.url ?? "/", "http://qilin.invalid").searchParams);
+				return;
+			}
+			if (accountId !== void 0) {
+				const runtime = await routedRuntime(store, accountId);
+				if (runtime !== void 0) {
+					try {
+						await forward(request, response, runtime, `${url.pathname}${url.search}`, []);
+					} catch (error) {
+						process.stderr.write(`qilin tenants: no runtime served ${url.pathname}: ${String(error)}\n`);
+						respond(response, 503, "text/plain; charset=utf-8", "qilin tenants: that tenant is not serving\n");
+					}
+					return;
+				}
+				response.setHeader("set-cookie", clearedRoutingCookie());
+			}
+		}
+		if (options.singleOrigin && request.method === "GET" && request.headers.cookie !== void 0 && (request.headers.accept ?? "").includes("text/html")) {
+			const accountId = await signedInAccountId(request);
+			if (accountId !== void 0 && store.byId(accountId) !== void 0) {
+				if ((await routedRuntime(store, accountId))?.proxyTarget() !== void 0) {
+					response.writeHead(303, {
+						"cache-control": "no-store",
+						"location": `${url.pathname}${url.search}`,
+						"referrer-policy": "no-referrer",
+						"set-cookie": routingCookie(accountId)
+					});
+					response.end();
+					return;
+				}
+			}
+		}
+		if (options.singleOrigin && request.headers.cookie !== void 0) {
+			const signedIn = await signedInAccountId(request);
+			if (signedIn !== void 0 && store.byId(signedIn) !== void 0) {
+				const runtime = await routedRuntime(store, signedIn);
+				if (runtime?.proxyTarget() !== void 0) {
+					await forward(request, response, runtime, `${url.pathname}${url.search}`, [routingCookie(signedIn)]);
+					return;
+				}
+			}
+		}
+		await serveFirstRun(request, response, productPath());
+	};
+	const onRequest = (request, response) => {
+		handle(request, response).catch((error) => {
+			process.stderr.write(`qilin tenants: request failed: ${String(error)}\n`);
+			if (!response.headersSent) respond(response, 500, "text/plain; charset=utf-8", "qilin tenants: request failed\n");
+			else response.end();
+		});
+	};
+	const server = options.tls === void 0 ? createServer(onRequest) : createServer$1({
+		cert: readPem(options.tls.certFile, "--tls-cert"),
+		key: readPem(options.tls.keyFile, "--tls-key")
+	}, onRequest);
+	if (options.singleOrigin) server.on("upgrade", (request, socket, head) => {
+		(async () => {
+			if (!hubAcceptsOrigin(request.headers, request.headers.host ?? "")) {
+				socket.destroy();
+				return;
+			}
+			let accountId = cookieValue(request.headers.cookie, TENANT_COOKIE);
+			if (accountId === void 0 && request.headers.cookie !== void 0) accountId = await signedInAccountId(request);
+			const runtime = accountId === void 0 ? void 0 : await routedRuntime(await roster(), accountId);
+			const target = runtime?.proxyTarget();
+			if (runtime === void 0 || target === void 0) {
+				socket.destroy();
+				return;
+			}
+			runtime.lastUsedAt = Date.now();
+			relayUpgrade(request, socket, head, target, forwardedHeaders(request.headers, new URL(target).host, request.headers.host ?? ""));
+		})().catch((error) => {
+			process.stderr.write(`qilin tenants: the upgrade to ${request.url ?? ""} failed: ${String(error)}\n`);
+			socket.destroy();
+		});
+	});
+	const listening = Promise.withResolvers();
+	server.on("error", (error) => {
+		listening.reject(error);
+	});
+	server.listen(options.port, options.host, () => {
+		const address = server.address();
+		listening.resolve(typeof address === "object" && address !== null ? address.port : options.port);
+	});
+	const port = await listening.promise;
+	const usageServer = createServer((request, response) => {
+		handleUsage(request, response).catch((error) => {
+			process.stderr.write(`qilin tenants: the usage report failed: ${String(error)}\n`);
+			if (response.headersSent) response.end();
+			else json(response, 500, { error: "ledger-failed" });
+		});
+	});
+	const usagePort = await new Promise((resolve, reject) => {
+		usageServer.once("error", reject);
+		usageServer.listen(0, "127.0.0.1", () => {
+			const bound = usageServer.address();
+			resolve(typeof bound === "object" && bound !== null ? bound.port : 0);
+		});
+	});
+	usageUrl = `http://127.0.0.1:${String(usagePort)}/usage`;
+	const printableHost = options.host === "0.0.0.0" || options.host === "::" ? "127.0.0.1" : options.host;
+	const address = `${options.tls === void 0 ? "http" : "https"}://${printableHost}:${String(port)}/`;
+	process.stdout.write(`qilin tenants: ${address}\n`);
+	for (const notice of addressNotices(options.host, options.tenantHost, port)) process.stderr.write(`${notice}\n`);
+	if ((await roster()).isEmpty && options.registration !== "open") process.stderr.write("qilin tenants: no account exists yet and this deployment does not accept new ones; create the first with `qilin tenants add <name>`\n");
+	options.onListening?.(address);
+	const sweep = Math.max(250, Math.min(Math.floor(options.idleMilliseconds / 4), 3e4));
+	const idle = options.idleMilliseconds <= 0 ? void 0 : setInterval(() => {
+		const now = Date.now();
+		for (const runtime of runtimes.values()) {
+			if (runtime.status().state !== "running") continue;
+			if (now - runtime.lastUsedAt < options.idleMilliseconds) continue;
+			process.stderr.write(`qilin tenants: reclaiming the idle runtime for ${runtime.status().accountId}\n`);
+			runtime.stop();
+		}
+	}, sweep);
+	const stopping = Promise.withResolvers();
+	const shutdown = () => {
+		(async () => {
+			if (idle !== void 0) clearInterval(idle);
+			server.closeAllConnections();
+			usageServer.closeAllConnections();
+			await new Promise((resolve) => {
+				server.close(() => {
+					resolve();
+				});
+			});
+			await new Promise((resolve) => {
+				usageServer.close(() => {
+					resolve();
+				});
+			});
+			usageTokens.clear();
+			await Promise.all([...runtimes.values()].map(async (runtime) => {
+				await runtime.stop();
+			}));
+			stopping.resolve(0);
+		})();
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	if (options.signal !== void 0) if (options.signal.aborted) shutdown();
+	else options.signal.addEventListener("abort", shutdown, { once: true });
+	return await stopping.promise;
+}
+//#endregion
+//#region lib/types/web-entry.js
+/**
+* The deployment entry: one public address, one supervisor, and one runtime per
+* account.
+*
+* Every profile that serves a browser address is a deployment: `qilin web` and
+* the product surface `qilin` both come here. This process binds the address a
+* browser reaches, terminates TLS when the invocation carries a certificate and
+* key, and starts one child runtime per account on demand. A child boots the same
+* profile with {@link TENANT_VARIABLE} set, so the application is what a runtime
+* process runs and the supervisor is what the deployment runs.
+*
+* Runtimes stay on loopback: the public address is the supervisor's. That is
+* why this entry serves every account through its own origin rather than
+* redirecting a browser to a runtime port — a redirect target a client cannot
+* reach is not a deployment.
+*
+* The entry reads the deployment's own flags and hands every other argument to
+* each runtime's command line, so an application flag reaches the process that
+* implements it instead of being dropped here. `--patch` is the exception it
+* forwards as a launcher flag, because an overlay applies to the composition
+* each runtime boots.
+*
+* The desktop shell boots the product profile in-process through
+* `profile-boot`, so it never reaches this module and keeps serving one
+* account directly.
+* @module @qilin-agent/cli/web-entry
+*/
+/** The profiles whose boot is a deployment of the product surface. */
+const ENTRY_PROFILES = ["qilin", "web"];
+/** Idle window a deployment gets before it sets one. */
+const DEFAULT_IDLE_MILLISECONDS = 18e5;
+/** Where the public address binds when the invocation names none. */
+const DEFAULT_HOST = "127.0.0.1";
+/** Which port the public address binds when the invocation names none. */
+const DEFAULT_PORT = 8790;
+/** First wait before retrying a runtime that failed to start. */
+const DEFAULT_RESTART_BACKOFF_MILLISECONDS = 1e3;
+/**
+* Addresses that mean "every interface". The served application refuses them
+* because binding every interface exposes remote execution to the network, and
+* the deployment address is the only address a browser reaches.
+*/
+const WILDCARD_HOSTS = [
+	"0.0.0.0",
+	"::",
+	"[::]",
+	"*"
+];
+/** Deployment flags that accumulate every occurrence instead of keeping the first. */
+const REPEATABLE_VALUE_FLAGS = ["--patch"];
+/** Deployment flags that carry a value. */
+const VALUE_FLAGS = [
+	"--host",
+	"--port",
+	"--patch",
+	"--tls-cert",
+	"--tls-key",
+	"--tenant-profile",
+	"--idle-ms",
+	"--max-tenants",
+	"--restart-backoff-ms",
+	"--tenant-host",
+	"--registration"
+];
+/** Deployment flags that stand alone. */
+const SWITCH_FLAGS = [
+	"--no-open",
+	"--per-account-ports",
+	"-h",
+	"--help"
+];
+/**
+* Split one invocation's arguments into the deployment's own flags and the
+* application's.
+* @param args - the arguments after the launcher's own flags.
+* @returns the deployment values, its repeatable lists, its switches, and the application's arguments.
+* @throws Error when a deployment flag that carries a value names none.
+*/
+function splitArguments(args) {
+	const values = /* @__PURE__ */ new Map();
+	const lists = /* @__PURE__ */ new Map();
+	const switches = /* @__PURE__ */ new Set();
+	const appArguments = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const token = args[index] ?? "";
+		const separator = token.indexOf("=");
+		const name = separator === -1 ? token : token.slice(0, separator);
+		const inline = separator === -1 ? void 0 : token.slice(separator + 1);
+		if (SWITCH_FLAGS.includes(name)) {
+			if (inline !== void 0) throw new Error(`qilin web: ${name} takes no value, received ${JSON.stringify(token)}`);
+			switches.add(name);
+			continue;
+		}
+		if (VALUE_FLAGS.includes(name)) {
+			const value = inline ?? args[index + 1];
+			if (inline === void 0) index += 1;
+			if (value === void 0 || inline === void 0 && value.startsWith("--")) throw new Error(`qilin web: ${name} needs a value`);
+			if (REPEATABLE_VALUE_FLAGS.includes(name)) {
+				lists.set(name, [...lists.get(name) ?? [], value]);
+				continue;
+			}
+			if (!values.has(name)) values.set(name, value);
+			continue;
+		}
+		appArguments.push(token);
+	}
+	return {
+		values,
+		lists,
+		switches,
+		appArguments
+	};
+}
+/**
+* One whole-number deployment flag.
+* @param values - the deployment values the invocation named.
+* @param name - the flag to read.
+* @param fallback - the value to use when the flag is absent.
+* @param minimum - the smallest accepted value.
+* @returns the parsed value.
+* @throws Error when the flag is present but not a whole number at or above the floor.
+*/
+function wholeNumber(values, name, fallback, minimum) {
+	const raw = values.get(name);
+	if (raw === void 0) return fallback;
+	if (!/^[0-9]+$/u.test(raw) || Number(raw) < minimum) throw new Error(`qilin web: ${name} needs a whole number of at least ${String(minimum)}, received ${JSON.stringify(raw)}`);
+	return Number(raw);
+}
+/**
+* The certificate and key the public address serves with.
+* @param values - the deployment values the invocation named.
+* @returns the resolved pair, or undefined when the invocation named none.
+* @throws Error when only one of the two flags is present.
+*/
+function tlsOptions(values) {
+	const certFile = values.get("--tls-cert");
+	const keyFile = values.get("--tls-key");
+	if (certFile === void 0 && keyFile === void 0) return void 0;
+	if (certFile === void 0 || keyFile === void 0) throw new Error("qilin web: --tls-cert and --tls-key must be supplied together");
+	return {
+		certFile: resolve(certFile),
+		keyFile: resolve(keyFile)
+	};
+}
+/**
+* Read who may create accounts on this deployment.
+*
+* A loopback address is this machine's own, so the product's form may create the
+* accounts it is asked to; an address other machines reach answers the same
+* question with the operator, who runs `qilin tenants add` where the decision is
+* deliberate.
+* @param values - the deployment values the invocation named.
+* @param host - interface the public address binds.
+* @returns the effective policy.
+* @throws Error when the flag names a policy this deployment does not have.
+*/
+function registrationPolicy(values, host) {
+	const named = values.get("--registration");
+	if (named === void 0) return LOOPBACK_HOSTS.includes(host) ? "open" : "closed";
+	if (named !== "open" && named !== "closed") throw new Error(`qilin web: --registration is open or closed, received ${JSON.stringify(named)}`);
+	return named;
+}
+/**
+* Read one deployment invocation.
+* @param args - the arguments after the launcher's own flags.
+* @param servedProfile - profile this deployment serves when the invocation names none.
+* @returns what the entry should serve.
+* @throws Error when a named flag cannot be honoured.
+*/
+function deploymentOptions(args, servedProfile) {
+	const { values, lists, switches, appArguments } = splitArguments(args);
+	const host = values.get("--host") ?? DEFAULT_HOST;
+	if (switches.has("-h") || switches.has("--help")) return {
+		host,
+		port: DEFAULT_PORT,
+		tenantProfile: values.get("--tenant-profile") ?? servedProfile,
+		idleMilliseconds: DEFAULT_IDLE_MILLISECONDS,
+		maxTenants: 0,
+		restartBackoffMilliseconds: DEFAULT_RESTART_BACKOFF_MILLISECONDS,
+		singleOrigin: !switches.has("--per-account-ports"),
+		tenantHost: values.get("--tenant-host"),
+		registration: LOOPBACK_HOSTS.includes(host) ? "open" : "closed",
+		tls: void 0,
+		help: true,
+		patches: (lists.get("--patch") ?? []).map((path) => resolve(path)),
+		appArguments
+	};
+	if (WILDCARD_HOSTS.includes(host)) throw new Error(`qilin web: --host ${host} is an unspecified (wildcard) address, which is not supported: bind one concrete address instead`);
+	const singleOrigin = !switches.has("--per-account-ports");
+	const tls = tlsOptions(values);
+	if (tls !== void 0 && !singleOrigin) throw new Error("qilin web: --tls-cert terminates TLS at this address, so it cannot be combined with --per-account-ports");
+	return {
+		host,
+		port: wholeNumber(values, "--port", DEFAULT_PORT, 0),
+		tenantProfile: values.get("--tenant-profile") ?? servedProfile,
+		idleMilliseconds: wholeNumber(values, "--idle-ms", DEFAULT_IDLE_MILLISECONDS, 0),
+		maxTenants: wholeNumber(values, "--max-tenants", 0, 0),
+		restartBackoffMilliseconds: wholeNumber(values, "--restart-backoff-ms", DEFAULT_RESTART_BACKOFF_MILLISECONDS, 0),
+		singleOrigin,
+		tenantHost: values.get("--tenant-host"),
+		registration: registrationPolicy(values, host),
+		tls,
+		help: false,
+		patches: (lists.get("--patch") ?? []).map((path) => resolve(path)),
+		appArguments
+	};
+}
+/**
+* Whether this process is the deployment entry rather than one account's runtime.
+* @returns true when no tenant marker is present.
+*/
+function isWebEntry() {
+	return process.env[TENANT_VARIABLE] === void 0;
+}
+/**
+* The deployment's own help, which the served application's help cannot answer
+* for: this process owns the address every account is reached through.
+* @returns the help text.
+*/
+function helpText() {
+	return [
+		"Usage: qilin --profile web [deployment options] [app options...]",
+		"       qilin [deployment options] [app options...]",
+		"",
+		"Serve one public address, with one isolated runtime per account.",
+		"",
+		"Deployment options:",
+		`  --host <host>              address to bind (default ${DEFAULT_HOST}); wildcard addresses are refused`,
+		`  --port <port>              listen port; 0 lets the OS pick one (default ${String(DEFAULT_PORT)})`,
+		"  --patch <path>             extra patch-list overlay every runtime boots with (repeatable)",
+		"  --tls-cert <file>          PEM server certificate chain; requires --tls-key",
+		"  --tls-key <file>           unencrypted PEM private key; requires --tls-cert",
+		"  --tenant-profile <name>    profile each account runtime boots (default: the served profile)",
+		"  --tenant-host <host>       interface each account runtime binds (default loopback)",
+		"  --per-account-ports        give every account an origin of its own",
+		`  --idle-ms <ms>             reclaim an idle runtime after this long; 0 keeps every one (default ${String(DEFAULT_IDLE_MILLISECONDS)})`,
+		"  --max-tenants <count>      most runtimes alive at once; 0 keeps every one",
+		"  --restart-backoff-ms <ms>  first wait before retrying a runtime that failed to start",
+		"  --registration open|closed who may create accounts (default open on a loopback address, closed otherwise)",
+		"  --no-open                  do not open the address in the default browser",
+		"  -h, --help                 print this help",
+		"",
+		"Every other argument passes to the command line of each account runtime.",
+		"",
+		"Examples:",
+		"  qilin web                                   serve the deployment on 127.0.0.1:8790",
+		"  qilin web --port 8080 --no-open             serve another port without opening a browser",
+		"  qilin web --tls-cert ./chain.pem --tls-key ./key.pem",
+		"                                             serve HTTPS, terminating TLS here",
+		"  qilin web --patch ./overlay.yml             compose every runtime with one overlay",
+		""
+	].join("\n");
+}
+/**
+* Hand the deployment's address to the operating system's default browser.
+*
+* The launcher is the platform's own, the same call the Web application makes
+* for its runtime; it is repeated here because this process is the deployment
+* rather than a runtime, and the CLI does not depend on that bundle.
+* @param url - the address to open.
+* @returns nothing once the launcher is started.
+*/
+function openAddress(url) {
+	const [command, ...args] = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? [
+		"cmd",
+		"/c",
+		"start",
+		"",
+		url
+	] : ["xdg-open", url];
+	const child = spawn(command, args, {
+		stdio: "ignore",
+		detached: true
+	});
+	child.once("error", (error) => {
+		process.stderr.write(`qilin web: could not open ${url}: ${String(error)}\n`);
+	});
+	child.unref();
+}
+/**
+* Serve the deployment: the public address, and one runtime per account.
+* @param invocation - the served profile, its overlays, and the app's arguments.
+* @returns the process exit code.
+* @throws Error when the invocation names a flag the deployment cannot honour.
+*/
+async function runWebEntry(invocation) {
+	if (invocation.fromDefaultProfile !== void 0) throw new Error("qilin web: --from-default-profile initializes a custom profile, and a deployment serves a shipped profile; omit it");
+	const options = deploymentOptions(invocation.args, invocation.profile);
+	if (options.help) {
+		process.stdout.write(helpText());
+		return 0;
+	}
+	return await runTenantsServe({
+		host: options.host,
+		port: options.port,
+		profile: options.tenantProfile,
+		idleMilliseconds: options.idleMilliseconds,
+		maxTenants: options.maxTenants,
+		restartBackoffMilliseconds: options.restartBackoffMilliseconds,
+		singleOrigin: options.singleOrigin,
+		tenantHost: options.tenantHost,
+		registration: options.registration,
+		patches: [...invocation.patches, ...options.patches].map((path) => resolve(path)),
+		appArguments: options.appArguments,
+		...options.tls === void 0 ? {} : { tls: options.tls },
+		...invocation.args.includes("--no-open") ? {} : { onListening: (url) => {
+			try {
+				openAddress(url);
+			} catch (error) {
+				process.stderr.write(`qilin web: could not open ${url}: ${String(error)}\n`);
+			}
+		} }
+	});
+}
+//#endregion
+export { ENTRY_PROFILES, isWebEntry, runWebEntry };