ccqa 1.37.1 → 1.38.0

package/dist/bin/ccqa.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { HubApiError, createHubClient } from "../hub-client/index.mjs";
+import { HubApiError, createHubClient, hubRequest } from "../hub-client/index.mjs";
 import { t as EVIDENCE_DIR_ENV } from "../evidence-constants-C425F7ZG.mjs";
 import { a as formatAgentBrowserUnavailableMessage, i as assertAgentBrowserAvailable, n as spawnAB, o as pathWithAgentBrowserShim, r as AgentBrowserUnavailableError, s as resolveAgentBrowserBin$1, t as sleepSync } from "../spawn-ab-CRIVfWpw.mjs";
 import { createRequire } from "node:module";
@@ -7,7 +7,7 @@ import { Command } from "commander";
 import { accessSync, appendFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
-import { access, chmod, cp, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { access, appendFile, chmod, cp, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, normalize, posix, relative, resolve, sep } from "node:path";
 import { parse, stringify } from "yaml";
@@ -4648,22 +4648,27 @@ var HubConnectionError = class extends Error {
 		super(message);
 	}
 };
-/**
-* Resolve a hub client from flags / env. Returns `null` (never throws/exits)
-* when either the URL or the token is missing — callers that treat the hub
-* as optional can fall back; callers that require it should use
-* `requireHubClient` instead.
-*/
-function resolveHubClient(opts) {
+/** `resolveHubClient`'s resolution half: `null` when the URL or token is missing. */
+function resolveHubTransport(opts) {
 	const baseUrl = opts.hubUrl ?? process.env.CCQA_HUB_URL;
 	const token = opts.hubToken ?? process.env.CCQA_HUB_TOKEN;
 	if (!baseUrl || !token) return null;
 	const headers = resolveHubHeaders(opts.hubHeader);
-	return createHubClient({
+	return {
 		baseUrl: baseUrl.replace(/\/+$/, ""),
 		token,
 		...headers ? { headers } : {}
-	});
+	};
+}
+/**
+* Resolve a hub client from flags / env. Returns `null` (never throws/exits)
+* when either the URL or the token is missing — callers that treat the hub
+* as optional can fall back; callers that require it should use
+* `requireHubClient` instead.
+*/
+function resolveHubClient(opts) {
+	const transport = resolveHubTransport(opts);
+	return transport === null ? null : createHubClient(transport);
 }
 /** Same as `resolveHubClient`, but throws `HubConnectionError` instead of returning `null`. */
 function requireHubClient(opts) {
@@ -5655,14 +5660,16 @@ const FRONTEND_COVERAGE_FILE = "coverage-frontend.json";
 /** The only spec-id shape this run issues, and the only one the sink accepts. */
 const SPEC_ID_PATTERN = /^[A-Za-z0-9._\-/]{1,200}$/;
 //#endregion
-//#region src/coverage/sink.ts
+//#region src/coverage/resolver.ts
 /**
-* Where instrumented application processes push what they reached. Why they
-* push rather than being scraped is ADR-0021.
+* The interpretation half of coverage: what a run's raw events mean.
 *
-* It authenticates nothing. The gate is the set of spec ids this run issued —
-* a token would have to be configured on both sides to add anything, and the
-* sink binds to loopback by default.
+* Everything here is a deterministic fold over an ordered, stamped event
+* stream — pushes from instrumented processes, and the turns the run opened
+* and closed on identities. The resolver never reads a clock: every judgement
+* uses the `at` its event carries, so replaying the same stream on another
+* host reaches the same answer. Stamping is the transport's job — the one
+* place a single clock exists.
 */
 /** What an instrumented process pushes, once a second. */
 const PushSchema = z.object({
@@ -5681,17 +5688,13 @@ const PushSchema = z.object({
 		files: z.array(z.string())
 	})).default([])
 });
-const MAX_BODY_BYTES$6 = 8 * 1024 * 1024;
-var CoverageSink = class CoverageSink {
-	/** Where instrumented processes push to. Known once the socket is bound. */
-	url = "";
+var CoverageResolver = class {
 	specs = /* @__PURE__ */ new Map();
 	bootFiles = /* @__PURE__ */ new Set();
 	/** What each reporting process last said about itself, keyed so a restart is a new one. */
 	processes = /* @__PURE__ */ new Map();
 	pushesReceived = 0;
 	rejected = 0;
-	malformed = 0;
 	/** Every turn this run has handed out, oldest first. Kept for the whole run. */
 	windows = [];
 	/** Per spec, per window, the distinct events that landed in it. Drives the row's count. */
@@ -5704,60 +5707,40 @@ var CoverageSink = class CoverageSink {
 	* on arrival, so there is nothing else left to tell two of them apart.
 	*/
 	unmappedAt = /* @__PURE__ */ new Set();
-	server;
 	/** Spec ids this run issued. A push naming anything else is dropped. */
 	issued;
 	/** Declared identities to their display key. A tag absent here is somebody else's. */
 	tagToKey;
-	constructor(server, issued, tagToKey) {
-		this.server = server;
+	constructor(issued, tagToKey) {
 		this.issued = issued;
 		this.tagToKey = tagToKey;
 	}
-	/**
-	* Binds and starts accepting pushes. `issued` is fixed at start: the cookie
-	* is client-controlled, so an id this run never issued is refused here
-	* rather than trusted into a report.
-	*/
-	static async start(host, port, issued, tagToKey = /* @__PURE__ */ new Map()) {
-		const sink = new CoverageSink(createServer(), issued, tagToKey);
-		sink.server.on("request", (request, response) => {
-			sink.handle(request, response);
-		});
-		await new Promise((resolve, reject) => {
-			sink.server.once("error", reject);
-			sink.server.listen(port, host, () => {
-				sink.server.removeListener("error", reject);
-				resolve();
-			});
-		});
-		const address = sink.server.address();
-		sink.url = `http://${formatHost(host)}:${address.port}`;
-		return sink;
+	apply(event) {
+		switch (event.kind) {
+			case "push":
+				this.acceptPush(event.push);
+				return;
+			case "window-open":
+				this.windows.push({
+					tag: event.tag,
+					key: event.key,
+					specId: event.specId,
+					openedAt: event.at,
+					closedAt: void 0
+				});
+				return;
+			case "window-close": for (let i = this.windows.length - 1; i >= 0; i--) {
+				const window = this.windows[i];
+				if (window.tag !== event.tag || window.closedAt !== void 0) continue;
+				window.closedAt = event.at;
+				return;
+			}
+		}
 	}
 	/** What `specId` reached so far. Reads do not clear: late pushes still land. */
 	filesFor(specId) {
 		return this.specs.get(specId)?.files;
 	}
-	/** Gives `specId` sole claim to `window`'s identity from now until it is closed. */
-	openWindow(window, specId) {
-		this.windows.push({
-			tag: window.tag,
-			key: window.key,
-			specId,
-			openedAt: Date.now(),
-			closedAt: void 0
-		});
-	}
-	/** Ends the open turn on `tag`. Later events from it belong to nobody. */
-	closeWindow(tag) {
-		for (let i = this.windows.length - 1; i >= 0; i--) {
-			const window = this.windows[i];
-			if (window.tag !== tag || window.closedAt !== void 0) continue;
-			window.closedAt = Date.now();
-			return;
-		}
-	}
 	/** When the run may next open a turn on `tag`, given the drain it has to leave. */
 	lastClosedAt(tag) {
 		let latest;
@@ -5822,13 +5805,6 @@ var CoverageSink = class CoverageSink {
 		return this.rejected;
 	}
 	/**
-	* Pushes the sink could not read. Counted because the failure is otherwise
-	* invisible from this side and shows up as "the spec reached no server code".
-	*/
-	malformedPushes() {
-		return this.malformed;
-	}
-	/**
 	* Files the applications could not instrument — they can never report reach.
 	*
 	* Not baselined, unlike `unattributed` and `droppedPushes`: a file that
@@ -5856,38 +5832,7 @@ var CoverageSink = class CoverageSink {
 		for (const report of this.processes.values()) total += Math.max(0, report.droppedLatest - report.droppedBaseline);
 		return total;
 	}
-	async close() {
-		await new Promise((resolve) => {
-			this.server.close(() => {
-				resolve();
-			});
-		});
-	}
-	async handle(request, response) {
-		if (request.method !== "POST") {
-			response.writeHead(405).end();
-			return;
-		}
-		let body;
-		try {
-			body = await readBody$1(request);
-		} catch {
-			this.malformed++;
-			response.writeHead(413).end();
-			return;
-		}
-		let push;
-		try {
-			push = PushSchema.parse(JSON.parse(body));
-		} catch {
-			this.malformed++;
-			response.writeHead(400).end();
-			return;
-		}
-		this.accept(push);
-		response.writeHead(204).end();
-	}
-	accept(push) {
+	acceptPush(push) {
 		const process = `${push.pid}:${push.startedAt}`;
 		const known = this.processes.get(process);
 		const previous = known?.unattributed ?? push.unattributed;
@@ -5955,9 +5900,9 @@ var CoverageSink = class CoverageSink {
 	/**
 	* The turn on `tag` that `at` falls in, latest first.
 	*
-	* Both clocks are involved — the application stamped `at`, this process
-	* stamped the bounds — so each bound gives a little. It cannot reach the
-	* neighbouring turn: the run leaves a full drain between two turns on one
+	* Both clocks are involved — the application stamped `at`, the receiving
+	* process stamped the bounds — so each bound gives a little. It cannot reach
+	* the neighbouring turn: the run leaves a full drain between two turns on one
 	* identity and this reaches half of it.
 	*/
 	windowAt(tag, at) {
@@ -5971,6 +5916,170 @@ var CoverageSink = class CoverageSink {
 		return found;
 	}
 };
+//#endregion
+//#region src/coverage/sink.ts
+/**
+* Where instrumented application processes push what they reached. Why they
+* push rather than being scraped is ADR-0021.
+*
+* This is the transport half only: it reads bodies, stamps arrival with the
+* one clock this process has, and hands each event to the resolver — which
+* owns every judgement about what the events mean.
+*
+* It authenticates nothing. The gate is the set of spec ids this run issued —
+* a token would have to be configured on both sides to add anything, and the
+* sink binds to loopback by default.
+*/
+const MAX_BODY_BYTES$6 = 8 * 1024 * 1024;
+var CoverageSink = class CoverageSink {
+	/** Where instrumented processes push to. Known once the socket is bound. */
+	url = "";
+	server;
+	resolver;
+	/**
+	* Pushes this side could not read. Counted here, not in the resolver: an
+	* unreadable body never becomes an event, so only the transport that
+	* dropped it can count it — a host replaying the stream would see nothing.
+	*/
+	malformed = 0;
+	constructor(server, resolver) {
+		this.server = server;
+		this.resolver = resolver;
+	}
+	/**
+	* Binds and starts accepting pushes. `issued` is fixed at start: the cookie
+	* is client-controlled, so an id this run never issued is refused by the
+	* resolver rather than trusted into a report.
+	*/
+	static async start(host, port, issued, tagToKey = /* @__PURE__ */ new Map()) {
+		const sink = new CoverageSink(createServer(), new CoverageResolver(issued, tagToKey));
+		sink.server.on("request", (request, response) => {
+			sink.handle(request, response);
+		});
+		await new Promise((resolve, reject) => {
+			sink.server.once("error", reject);
+			sink.server.listen(port, host, () => {
+				sink.server.removeListener("error", reject);
+				resolve();
+			});
+		});
+		const address = sink.server.address();
+		sink.url = `http://${formatHost(host)}:${address.port}`;
+		return sink;
+	}
+	/** What `specId` reached so far. Reads do not clear: late pushes still land. */
+	filesFor(specId) {
+		return this.resolver.filesFor(specId);
+	}
+	/** Gives `specId` sole claim to `window`'s identity from now until it is closed. */
+	openWindow(window, specId) {
+		this.resolver.apply({
+			kind: "window-open",
+			at: Date.now(),
+			tag: window.tag,
+			key: window.key,
+			specId
+		});
+	}
+	/** Ends the open turn on `tag`. Later events from it belong to nobody. */
+	closeWindow(tag) {
+		this.resolver.apply({
+			kind: "window-close",
+			at: Date.now(),
+			tag
+		});
+	}
+	/** When the run may next open a turn on `tag`, given the drain it has to leave. */
+	lastClosedAt(tag) {
+		return this.resolver.lastClosedAt(tag);
+	}
+	/** Per window key, how many distinct events this spec was credited with. */
+	actorEventsFor(specId) {
+		return this.resolver.actorEventsFor(specId);
+	}
+	/** Events from a declared identity that arrived outside its turns. */
+	outsideWindowEvents() {
+		return this.resolver.outsideWindowEvents();
+	}
+	/** Events from identities this project never declared. Their reach belongs to nobody. */
+	unmappedActorEvents() {
+		return this.resolver.unmappedActorEvents();
+	}
+	/** Executions that ran while `specId` was open but outside its context. */
+	unattributedFor(specId) {
+		return this.resolver.unattributedFor(specId);
+	}
+	/** Files reached at module top level, never folded into any spec. */
+	boot() {
+		return this.resolver.boot();
+	}
+	/** True once any instrumented process has reported — i.e. the server half is wired up. */
+	heardFromApplication() {
+		return this.resolver.heardFromApplication();
+	}
+	/** Specs some process attributed a file to. */
+	attributedSpecs() {
+		return this.resolver.attributedSpecs();
+	}
+	/** Pushes refused because they named a spec id this run never issued. */
+	rejectedPushes() {
+		return this.resolver.rejectedPushes();
+	}
+	/**
+	* Pushes the sink could not read. Counted because the failure is otherwise
+	* invisible from this side and shows up as "the spec reached no server code".
+	*/
+	malformedPushes() {
+		return this.malformed;
+	}
+	/** Files the applications could not instrument — they can never report reach. */
+	uninstrumentedFiles() {
+		return this.resolver.uninstrumentedFiles();
+	}
+	/** Application processes that instrumented nothing at all. */
+	uninstrumentedProcesses() {
+		return this.resolver.uninstrumentedProcesses();
+	}
+	/** Pushes the applications could not deliver during this run. Never seen here. */
+	droppedPushes() {
+		return this.resolver.droppedPushes();
+	}
+	async close() {
+		await new Promise((resolve) => {
+			this.server.close(() => {
+				resolve();
+			});
+		});
+	}
+	async handle(request, response) {
+		if (request.method !== "POST") {
+			response.writeHead(405).end();
+			return;
+		}
+		let body;
+		try {
+			body = await readBody$1(request);
+		} catch {
+			this.malformed++;
+			response.writeHead(413).end();
+			return;
+		}
+		let push;
+		try {
+			push = PushSchema.parse(JSON.parse(body));
+		} catch {
+			this.malformed++;
+			response.writeHead(400).end();
+			return;
+		}
+		this.resolver.apply({
+			kind: "push",
+			at: Date.now(),
+			push
+		});
+		response.writeHead(204).end();
+	}
+};
 function formatHost(host) {
 	return host.includes(":") ? `[${host}]` : host;
 }
@@ -6936,7 +7045,19 @@ const SETTLE_QUIET_POLLS = 10;
 const SETTLE_CAP_MS = 1e4;
 var CoverageSession = class CoverageSession {
 	existing = /* @__PURE__ */ new Map();
+	/**
+	* Undefined in hub mode: nothing binds on the runner, and every read-side
+	* answer here stays empty — interpretation lives in the hub's resolve
+	* (ADR-0022).
+	*/
 	sink;
+	inbox;
+	/**
+	* Hub mode's stand-in for the sink's window log: when each identity's turn
+	* last closed, on this process's clock, which is all the drain scheduling
+	* ever compared against.
+	*/
+	windowClosedAt = /* @__PURE__ */ new Map();
 	runId;
 	/** What reported paths are relative to, and what they are checked against. */
 	root;
@@ -6944,10 +7065,15 @@ var CoverageSession = class CoverageSession {
 	cwd;
 	actors;
 	origins;
-	/** The denominator, enumerated once at start, or undefined when `coverage.include` is unset. */
+	/**
+	* The denominator, enumerated once at start, or undefined when
+	* `coverage.include` is unset — and always in hub mode, where it travels as
+	* a `universe` event instead of riding the report envelope.
+	*/
 	universe;
-	constructor(sink, runId, root, cwd, actors, origins, universe) {
+	constructor(sink, inbox, runId, root, cwd, actors, origins, universe) {
 		this.sink = sink;
+		this.inbox = inbox;
 		this.runId = runId;
 		this.root = root;
 		this.cwd = cwd;
@@ -6959,16 +7085,48 @@ var CoverageSession = class CoverageSession {
 		const origins = options.config.instrumentedOrigins.map((origin) => resolveEnvRefs(origin));
 		const unresolved = origins.filter((origin) => !/^https?:\/\//i.test(origin));
 		if (unresolved.length > 0) throw new Error(`coverage.instrumentedOrigins must be absolute http(s) URLs after variable substitution; got ${unresolved.join(", ")}`);
-		const bind = new URL(resolveEnvRefs(options.config.sink));
 		const actors = options.actors ?? NO_ACTORS;
-		const issued = new Set(options.specs.map((spec) => specIdFor(options.runId, spec)));
-		const sink = await CoverageSink.start(bind.hostname, bind.port === "" ? 80 : Number(bind.port), issued, actors.tagToKey);
+		let sink;
+		if (options.inbox === void 0) {
+			const bind = new URL(resolveEnvRefs(options.config.sink));
+			const issued = new Set(options.specs.map((spec) => specIdFor(options.runId, spec)));
+			sink = await CoverageSink.start(bind.hostname, bind.port === "" ? 80 : Number(bind.port), issued, actors.tagToKey);
+		}
 		const root = await resolveRoot(options.cwd, options.config.projectRoot) ?? options.cwd;
 		const universe = options.config.include === void 0 ? void 0 : await enumerateUniverse(root, options.config.include, (text) => warn(text));
-		return new CoverageSession(sink, options.runId, root, options.cwd, actors, origins, universe);
+		if (options.inbox !== void 0 && universe !== void 0) await options.inbox.append({
+			kind: "universe",
+			runId: options.runId,
+			include: [...universe.include],
+			files: [...universe.files]
+		});
+		return new CoverageSession(sink, options.inbox, options.runId, root, options.cwd, actors, origins, options.inbox === void 0 ? universe : void 0);
+	}
+	/**
+	* Ties the stream's run id to the hub's run record. The session starts
+	* before the hub assigns that id, so the link is appended once it exists;
+	* local mode has no stream to link.
+	*/
+	async linkHubRun(hubRunId) {
+		if (this.inbox === void 0) return;
+		await this.inbox.append({
+			kind: "run-link",
+			runId: this.runId,
+			hubRunId
+		});
 	}
+	/** Where the local sink listens. Hub mode binds nothing, so there is no URL. */
 	get sinkUrl() {
-		return this.sink.url;
+		return this.sink?.url ?? "";
+	}
+	/**
+	* True in hub mode: the facts leave as a stream, rows carry no coverage,
+	* and the run-side health read-outs below answer empty. The one mode flag
+	* callers should consult, so the answer cannot drift from what `start`
+	* actually wired.
+	*/
+	get streamsToHub() {
+		return this.inbox !== void 0;
 	}
 	/**
 	* Opens the spec's measurement.
@@ -6980,14 +7138,26 @@ var CoverageSession = class CoverageSession {
 	*/
 	async beginSpec(ref) {
 		const specId = specIdFor(this.runId, ref);
+		if (this.inbox !== void 0) await this.inbox.append({
+			kind: "spec-open",
+			runId: this.runId,
+			specId
+		});
 		for (const window of this.actors.windowsForSpec.get(specKey(ref)) ?? []) {
-			const closedAt = this.sink.lastClosedAt(window.tag);
+			const closedAt = this.inbox === void 0 ? this.sink.lastClosedAt(window.tag) : this.windowClosedAt.get(window.tag);
 			const wait = closedAt === void 0 ? 0 : closedAt + ACTOR_DRAIN_MS - Date.now();
 			if (wait > 0) {
 				meta("coverage", `waiting ${Math.ceil(wait / 1e3)}s for ${window.key} to go quiet`);
 				await new Promise((resolve) => setTimeout(resolve, wait));
 			}
-			this.sink.openWindow(window, specId);
+			if (this.inbox === void 0) this.sink.openWindow(window, specId);
+			else await this.inbox.append({
+				kind: "window-open",
+				runId: this.runId,
+				tag: window.tag,
+				key: window.key,
+				specId
+			});
 		}
 	}
 	/**
@@ -7009,21 +7179,34 @@ var CoverageSession = class CoverageSession {
 			warn: (text) => warn(`coverage: ${text}`)
 		});
 	}
-	/** Merges both sides once the spec's pushes have stopped arriving. */
+	/**
+	* Merges both sides once the spec's pushes have stopped arriving.
+	*
+	* In hub mode there is nothing to merge: the run appends what it alone can
+	* state — its markers and the browser half — and resolves nothing, so the
+	* row gets no coverage. There is no settle either: settling existed to read
+	* a complete file set before the row was written, and late pushes land on
+	* the hub whenever they arrive, attributed by the spec id they carry.
+	*/
 	async collect(ref, coverageDir) {
 		const specId = specIdFor(this.runId, ref);
+		if (this.inbox !== void 0) {
+			await this.streamSpecClose(this.inbox, ref, specId, coverageDir);
+			return;
+		}
+		const sink = this.sink;
 		await this.settle(specId);
 		const owned = this.actors.windowsForSpec.get(specKey(ref)) ?? [];
-		for (const window of owned) this.sink.closeWindow(window.tag);
-		const matched = this.sink.actorEventsFor(specId);
-		const backend = this.sink.filesFor(specId);
+		for (const window of owned) sink.closeWindow(window.tag);
+		const matched = sink.actorEventsFor(specId);
+		const backend = sink.filesFor(specId);
 		const frontend = await readFrontend(coverageDir, specId);
 		const inProject = await this.keepExisting(frontend?.files ?? []);
 		return {
 			files: [...new Set([...backend ?? [], ...inProject])].sort(),
 			frontendFiles: inProject.length,
 			backendFiles: backend?.size ?? 0,
-			backendReported: this.sink.heardFromApplication(),
+			backendReported: sink.heardFromApplication(),
 			frontendReported: frontend !== void 0,
 			frontendStopped: frontend?.stopped ?? false,
 			actorWindows: owned.map((window) => ({
@@ -7032,53 +7215,84 @@ var CoverageSession = class CoverageSession {
 			})),
 			excludedDependencies: frontend?.excludedDependencies ?? 0,
 			gaps: {
-				unattributed: this.sink.unattributedFor(specId),
+				unattributed: sink.unattributedFor(specId),
 				unmappedScripts: frontend?.unmappedScripts ?? 0,
 				unmappedRanges: frontend?.unmappedRanges ?? 0,
 				outsideProject: (frontend?.files.length ?? 0) - inProject.length,
 				unresolvedSources: frontend?.unresolvedSources ?? 0,
-				uninstrumentedFiles: this.sink.uninstrumentedFiles(),
-				uninstrumentedProcesses: this.sink.uninstrumentedProcesses(),
-				droppedPushes: this.sink.droppedPushes(),
-				unmappedActorEvents: this.sink.unmappedActorEvents(),
-				outsideWindowEvents: owned.reduce((sum, window) => sum + (this.sink.outsideWindowEvents().get(window.key) ?? 0), 0)
+				uninstrumentedFiles: sink.uninstrumentedFiles(),
+				uninstrumentedProcesses: sink.uninstrumentedProcesses(),
+				droppedPushes: sink.droppedPushes(),
+				unmappedActorEvents: sink.unmappedActorEvents(),
+				outsideWindowEvents: owned.reduce((sum, window) => sum + (sink.outsideWindowEvents().get(window.key) ?? 0), 0)
 			}
 		};
 	}
 	/** Files reached at module top level, across the whole run. */
 	boot() {
-		return [...this.sink.boot()].sort();
+		return this.sink === void 0 ? [] : [...this.sink.boot()].sort();
 	}
 	/** Whether any instrumented application process reported at all. */
 	heardFromApplication() {
-		return this.sink.heardFromApplication();
+		return this.sink?.heardFromApplication() ?? false;
 	}
 	/** Specs some application process attributed a file to. */
 	attributedSpecs() {
-		return this.sink.attributedSpecs();
+		return this.sink?.attributedSpecs() ?? 0;
 	}
 	/** Declared identities that acted outside the turns this run gave them. */
 	outsideWindowEvents() {
-		return this.sink.outsideWindowEvents();
+		return this.sink?.outsideWindowEvents() ?? /* @__PURE__ */ new Map();
 	}
 	/** Events from identities this project never declared. */
 	unmappedActorEvents() {
-		return this.sink.unmappedActorEvents();
+		return this.sink?.unmappedActorEvents() ?? 0;
 	}
 	/** Pushes naming a spec id this run never issued — a stale or forged cookie. */
 	rejectedPushes() {
-		return this.sink.rejectedPushes();
+		return this.sink?.rejectedPushes() ?? 0;
 	}
 	/** Pushes the sink could not read — the two halves' wire formats disagree. */
 	malformedPushes() {
-		return this.sink.malformedPushes();
+		return this.sink?.malformedPushes() ?? 0;
 	}
 	/** Application processes that instrumented nothing at all. */
 	uninstrumentedProcesses() {
-		return this.sink.uninstrumentedProcesses();
+		return this.sink?.uninstrumentedProcesses() ?? 0;
 	}
 	async close() {
-		await this.sink.close();
+		await this.sink?.close();
+	}
+	/**
+	* Hub-mode close: everything the run alone can state about this spec goes
+	* to the inbox. Windows close now, on this process's stamps — actor events
+	* match on the instant the work was asked for, so a spec's asynchronous
+	* tail still lands inside the turn that caused it.
+	*/
+	async streamSpecClose(inbox, ref, specId, coverageDir) {
+		for (const window of this.actors.windowsForSpec.get(specKey(ref)) ?? []) {
+			await inbox.append({
+				kind: "window-close",
+				runId: this.runId,
+				tag: window.tag
+			});
+			this.windowClosedAt.set(window.tag, Date.now());
+		}
+		const frontend = await readFrontend(coverageDir, specId);
+		if (frontend !== void 0) {
+			const files = [...new Set(await this.keepExisting(frontend.files))].sort();
+			await inbox.append({
+				kind: "browser",
+				runId: this.runId,
+				specId,
+				files
+			});
+		}
+		await inbox.append({
+			kind: "spec-close",
+			runId: this.runId,
+			specId
+		});
 	}
 	/** Keeps the paths that name a file in the working tree, cached per session. */
 	async keepExisting(paths) {
@@ -7088,14 +7302,16 @@ var CoverageSession = class CoverageSession {
 		}));
 		return paths.filter((path) => this.existing.get(path) === true);
 	}
+	/** Local mode only; hub mode never settles (see `collect`). */
 	async settle(specId) {
-		if (!this.sink.heardFromApplication()) return;
+		const sink = this.sink;
+		if (!sink.heardFromApplication()) return;
 		const deadline = Date.now() + SETTLE_CAP_MS;
-		let previous = this.sink.filesFor(specId)?.size ?? 0;
+		let previous = sink.filesFor(specId)?.size ?? 0;
 		let quiet = 0;
 		while (Date.now() < deadline && quiet < SETTLE_QUIET_POLLS) {
 			await new Promise((resolve) => setTimeout(resolve, SETTLE_POLL_MS));
-			const size = this.sink.filesFor(specId)?.size ?? 0;
+			const size = sink.filesFor(specId)?.size ?? 0;
 			quiet = size === previous ? quiet + 1 : 0;
 			previous = size;
 		}
@@ -12784,6 +13000,46 @@ function enrichZodError(error, source) {
 	return new Error(lines.join("\n"));
 }
 //#endregion
+//#region src/coverage/inbox.ts
+/**
+* The run's side of the hub coverage inbox (ADR-0022). Under
+* `--coverage-inbox hub` nothing binds on the runner: the run appends its own
+* facts — spec lifecycle markers, actor-window markers, the browser half, the
+* universe — to the hub's durable stream, next to the pushes the instrumented
+* application sends there itself. The hub stamps arrival order and stores;
+* interpretation happens at read time, in the shared resolver.
+*/
+/** `--coverage-inbox` values: where the measurement's two sides meet. */
+const COVERAGE_INBOX_MODES = ["local", "hub"];
+var CoverageInbox = class {
+	transport;
+	path;
+	constructor(options) {
+		const { project, ...transport } = options;
+		this.transport = transport;
+		this.path = `/api/v1/coverage/events?project=${encodeURIComponent(project)}`;
+	}
+	/**
+	* Appends one event to the project's stream. Never throws: a marker that
+	* could not be delivered degrades the resolved answer, and failing the run
+	* over it would cost the test results the run exists for. The transport is
+	* the hub client's, with its one opt-in: an append delivered twice resolves
+	* the same as once, so unlike the client's own POSTs it retries once.
+	*/
+	async append(event) {
+		try {
+			await hubRequest(this.transport, this.path, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(event)
+			}, "post-once");
+		} catch (err) {
+			const reason = err instanceof HubApiError ? `status ${err.status}` : errMessage(err);
+			warn(`coverage: could not append a ${event.kind} event to the hub inbox (${reason})`);
+		}
+	}
+};
+//#endregion
 //#region src/codegen/actions-to-script.ts
 function actionsToScript(input) {
 	const { actions, testName, stepMarkers = [], emptySteps = [] } = input;
@@ -15265,6 +15521,22 @@ async function executeRun(targets, opts) {
 	if (rerunProfile !== null && hubCtx == null) throw new RunUsageError(needsHubConnection("--only-hub-rerun-needed"));
 	if (opts.reportToHub && hubCtx == null) throw new RunUsageError(REPORT_TO_HUB_NEEDS_CONNECTION);
 	if (opts.learnHubLivePrompt && hubCtx == null) throw new RunUsageError(needsHubConnection("--learn-hub-live-prompt"));
+	let coverageInbox;
+	if (opts.coverageInbox === "hub") {
+		if (opts.coverage !== true) throw new RunUsageError("--coverage-inbox hub does nothing without --coverage — there is no measurement to stream");
+		const transport = resolveHubTransport(opts);
+		if (transport === null) throw new RunUsageError(needsHubConnection("--coverage-inbox hub"));
+		let project;
+		try {
+			project = resolveProjectOrThrow(opts.project, cwd);
+		} catch (err) {
+			throw new RunUsageError(errMessage(err));
+		}
+		coverageInbox = new CoverageInbox({
+			...transport,
+			project
+		});
+	}
 	const [customPrompt, triageUserPrompt, ledgerEntries, rerunReport, fetchedDeployHead] = await Promise.all([
 		forExecution ? fetchCustomPrompt(hubCtx) : null,
 		forExecution ? fetchTriageUserPrompt(hubCtx) : null,
@@ -15381,7 +15653,7 @@ async function executeRun(targets, opts) {
 	const liveSpecs = withMode.filter((s) => s.mode === "live");
 	meta("modes", `${detSpecs.length} deterministic / ${liveSpecs.length} live`);
 	if (dispatch.external.length > 0) meta("external", dispatch.external.map((g) => `${g.targetId} ${g.specs.length}`).join(" / "));
-	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown) : void 0;
+	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown, coverageInbox) : void 0;
 	if (liveSpecs.length === 0) {
 		const why = "it only applies to agent-browser 'mode: live' specs, and this run has none";
 		if (typeof opts.liveStepRetry === "number" && opts.liveStepRetry > 0) warn(`--live-step-retry is ignored: ${why}`);
@@ -15418,6 +15690,7 @@ async function executeRun(targets, opts) {
 		});
 		hubRunId = opened.id;
 		info(`hub: incremental run opened (${opened.id})`);
+		await coverage?.linkHubRun(opened.id);
 		const runId = opened.id;
 		let hubPatchEverSucceeded = false;
 		hubSink = { onUpsert: async (row) => {
@@ -15492,7 +15765,7 @@ async function executeRun(targets, opts) {
 		report: incrementalReport
 	};
 	const live = await runLiveSpecs(liveSpecs, liveOpts);
-	if (coverage) reportCoverageHealth(coverage, [...externalRows, ...live.reportResults]);
+	if (coverage && !coverage.streamsToHub) reportCoverageHealth(coverage, [...externalRows, ...live.reportResults]);
 	let overallExitCode = det.exitCode !== 0 ? 1 : 0;
 	if (live.failedCount > 0) overallExitCode = 1;
 	if (externalRows.some((r) => r.status === "failed")) overallExitCode = 1;
@@ -15527,7 +15800,7 @@ async function executeRun(targets, opts) {
 		});
 		report = await writeUnifiedReport({
 			reportDir,
-			results: coverage ? results.map(explainMissingCoverage) : results,
+			results: coverage && !coverage.streamsToHub ? results.map(explainMissingCoverage) : results,
 			git,
 			customPromptVersion,
 			triageUserPromptHash,
@@ -15585,9 +15858,10 @@ async function executeRun(targets, opts) {
 /**
 * Starts the run's coverage measurement before any spec runs: the sink has to
 * be listening before the first request reaches the application, and the set
-* of spec ids it will accept is only known once dispatch has resolved.
+* of spec ids it will accept is only known once dispatch has resolved. With
+* an `inbox`, nothing binds — the run streams its events to the hub instead.
 */
-async function startCoverage(cwd, config, actors, dispatch, teardown) {
+async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
 	if (config === void 0) throw new RunUsageError("--coverage needs a `coverage:` block in .ccqa/config.yaml whose `instrumentedOrigins` names the origins the spec cookie may be attached to");
 	let session;
 	try {
@@ -15596,12 +15870,14 @@ async function startCoverage(cwd, config, actors, dispatch, teardown) {
 			cwd,
 			config,
 			actors,
-			specs: dispatch.external.flatMap((g) => g.specs)
+			specs: dispatch.external.flatMap((g) => g.specs),
+			...inbox ? { inbox } : {}
 		});
 	} catch (err) {
 		throw new RunUsageError(`could not start coverage collection: ${errMessage(err)}`);
 	}
-	meta("coverage", `sink ${session.sinkUrl} → ${session.origins.join(", ")}`);
+	if (inbox !== void 0) meta("coverage", `streaming to hub inbox → ${session.origins.join(", ")}`);
+	else meta("coverage", `sink ${session.sinkUrl} → ${session.origins.join(", ")}`);
 	const unmeasured = dispatch.external.filter((g) => g.browserCoverage.browser === "none").length;
 	if (unmeasured > 0) warn(`${unmeasured} target(s) declare no browser to measure; their specs are reported as unmeasured rather than as reaching nothing`);
 	teardown?.onFinalize(() => session.close());
@@ -16235,7 +16511,10 @@ const runCommand = addHubOptions(addProfileOption(addLanguageOption(new Command(
 }, "never").option("--on-fail-explain-rerun-max-specs <n>", "Rerun at most N specs, in report order; the rest are named in the run summary and keep the label they were first given. Default: no cap. The knob for an environment having a bad day, where the alternative is turning the reruns off entirely.", parseRerunMaxSpecs).optionsGroup("What to do with the results:").option("--report-dir <dir>", `Directory for the structured run results (report.json + evidence PNGs), which are always written. Default: ${DEFAULT_REPORT_DIR}/.`).option("--report-format <fmt>", "Additional output format alongside HTML: 'text' (default), 'json' (writes report.json), 'github' (GitHub Actions annotations on stdout).", (raw) => {
 	if (REPORT_FORMATS.includes(raw)) return raw;
 	throw new Error(`--report-format must be one of ${REPORT_FORMATS.join(" | ")}`);
-}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").option("--coverage", "Measure what each spec actually reached in the application under test, and record it on the spec's report row. Needs a `coverage:` block in .ccqa/config.yaml naming the instrumented origins the spec cookie may go to. The browser half attaches to the target's browser from outside (nothing is emitted into generated tests; needs node 22+); the server half needs the application running with ccqa-tools.").optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
+}, "text").option("--report-to-hub", "Incrementally push the run report to the hub as the run progresses (open → patch per spec → finalize). Requires --hub-url/--hub-token (or CCQA_HUB_URL/CCQA_HUB_TOKEN). Without it, hub credentials are used only to fetch variables/sessions/prompts, not to push.").option("--coverage", "Measure what each spec actually reached in the application under test, and record it on the spec's report row. Needs a `coverage:` block in .ccqa/config.yaml naming the instrumented origins the spec cookie may go to. The browser half attaches to the target's browser from outside (nothing is emitted into generated tests; needs node 22+); the server half needs the application running with ccqa-tools.").option("--coverage-inbox <where>", "With --coverage: where the measurement's two sides meet. 'local' (default) binds a loopback inbox on this machine for the run's duration; 'hub' appends every event to the hub's durable coverage inbox instead — nothing listens on the runner, report.json carries no coverage, and the hub resolves per-spec results on read (requires a hub connection).", (raw) => {
+	if (COVERAGE_INBOX_MODES.includes(raw)) return raw;
+	throw new Error(`--coverage-inbox must be one of ${COVERAGE_INBOX_MODES.join(" | ")}`);
+}, "local").optionsGroup("Learning:").option("--learn-hub-live-prompt", "(live only) After the run finishes, ask Claude to refresh the \"live.agent\" prompt on the hub from a summary of the run. Requires a hub connection.").optionsGroup("Environment and connection:").option("--cwd <path>", "Working directory containing the .ccqa/ tree (monorepo support). Defaults to the current directory.").option("--project <name>", "Project name for the hub. Defaults to the current directory's name.")))).action(async (targets, opts) => {
 	await runCliAction(targets, opts);
 });
 /** Parse --concurrency: a positive integer. Rejects 0, negatives, non-integers. */
@@ -20755,7 +21034,7 @@ function decodeEncryptedBlob(bytes) {
 //#endregion
 //#region src/hub/api/handlers/secrets.ts
 const MAX_SECRET_BODY_BYTES = 4 * 1024 * 1024;
-function requireKey(config) {
+function requireKey$1(config) {
 	if (!config.encryptionKey) throw new HttpError(503, "encryption_not_configured", "CCQA_HUB_ENCRYPTION_KEY is not set on this hub");
 	return config.encryptionKey;
 }
@@ -20769,7 +21048,7 @@ function requireScope$1(ctx) {
 /** PUT /api/v1/projects/:project/sessions/:profile/:name — body is the raw agent-browser storage-state JSON. */
 function createPutSessionHandler(config) {
 	return async (ctx) => {
-		const key = requireKey(config);
+		const key = requireKey$1(config);
 		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const body = await readBody(ctx.req, MAX_SECRET_BODY_BYTES);
@@ -20798,7 +21077,7 @@ function createListSessionsHandler(config) {
 */
 function createGetSessionHandler(config) {
 	return async (ctx) => {
-		const key = requireKey(config);
+		const key = requireKey$1(config);
 		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const stored = await config.store.get(scope, name);
@@ -20820,7 +21099,7 @@ function createDeleteSessionHandler(config) {
 /** PUT /api/v1/projects/:project/variables/:profile/:name */
 function createPutVariableHandler(config) {
 	return async (ctx) => {
-		const key = requireKey(config);
+		const key = requireKey$1(config);
 		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const body = await readBody(ctx.req, MAX_SECRET_BODY_BYTES);
@@ -20843,7 +21122,7 @@ function createListVariablesHandler(config) {
 	return async (ctx) => {
 		const scope = requireScope$1(ctx);
 		const includeValues = ctx.url.searchParams.get("include") === "values";
-		const key = includeValues ? requireKey(config) : config.encryptionKey;
+		const key = includeValues ? requireKey$1(config) : config.encryptionKey;
 		const entries = await config.store.list(scope);
 		const variables = await Promise.all(entries.map(async (e) => {
 			const sensitive = e.meta.sensitive === true;
@@ -21498,6 +21777,428 @@ function createGetSpendHandler(storage) {
 	};
 }
 //#endregion
+//#region src/coverage/events.ts
+/**
+* The wire and storage shapes of the coverage event stream (ADR-0022).
+*
+* Two producers write it. The instrumented application posts the same push
+* body it has always posted — the inbox recognises it by its `protocol`
+* field, so a collector already deployed keeps working unchanged. The run
+* posts explicit run events: its markers, its browser half, its universe.
+* The hub stores either under a stamp `{seq, at}` and never looks inside;
+* interpretation happens at read time (resolver.ts).
+*
+* Every run event carries `runId` because one project's stream interleaves
+* many runs: the markers are what bound one run's view of the stream, so
+* they must say whose they are.
+*/
+const RunEventSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("run-link"),
+		runId: z.string(),
+		hubRunId: z.string()
+	}),
+	z.object({
+		kind: z.literal("spec-open"),
+		runId: z.string(),
+		specId: z.string()
+	}),
+	z.object({
+		kind: z.literal("spec-close"),
+		runId: z.string(),
+		specId: z.string()
+	}),
+	z.object({
+		kind: z.literal("window-open"),
+		runId: z.string(),
+		tag: z.string(),
+		key: z.string(),
+		specId: z.string()
+	}),
+	z.object({
+		kind: z.literal("window-close"),
+		runId: z.string(),
+		tag: z.string()
+	}),
+	z.object({
+		kind: z.literal("browser"),
+		runId: z.string(),
+		specId: z.string(),
+		files: z.array(z.string())
+	}),
+	z.object({
+		kind: z.literal("universe"),
+		runId: z.string(),
+		include: z.array(z.string()),
+		files: z.array(z.string())
+	})
+]);
+/**
+* What one POST to the inbox may carry: an application push (recognised by
+* `protocol`) or a run event (recognised by `kind`). Checked in this order —
+* the push shape has no `kind` and a run event has no `protocol`.
+*/
+const InboxBodySchema = z.union([PushSchema, RunEventSchema]);
+z.object({
+	seq: z.number(),
+	at: z.number(),
+	body: InboxBodySchema
+});
+z.object({
+	runId: z.string(),
+	hubRunId: z.string().optional(),
+	asOf: z.number(),
+	lastSeq: z.number(),
+	universe: z.object({
+		include: z.array(z.string()),
+		files: z.array(z.string())
+	}).optional(),
+	specs: z.array(z.object({
+		specId: z.string(),
+		files: z.array(z.string()),
+		actorEvents: z.record(z.string(), z.number())
+	})),
+	boot: z.array(z.string()),
+	health: z.object({
+		heardFromApplication: z.boolean(),
+		pushesDuringRun: z.number(),
+		attributedSpecs: z.number(),
+		rejectedPushes: z.number(),
+		uninstrumentedFiles: z.number(),
+		uninstrumentedProcesses: z.number(),
+		droppedPushes: z.number(),
+		unmappedActorEvents: z.number(),
+		outsideWindowEvents: z.record(z.string(), z.number()),
+		specsMeasured: z.number()
+	})
+});
+/**
+* Interprets `runId`'s view of the stream.
+*
+* Two passes, because the resolver needs its context up front: the first
+* collects what the run's own markers establish — which ids it issued, which
+* identity tags were its to hand out, its universe, and when its first and
+* last marker arrived. The second replays the stream through the shared
+* resolver: this run's window markers as they came, and every application
+* push — as-is when its stamp falls inside the span the run's sink would
+* have been listening (first marker to last marker plus `GRACE_MS`),
+* stripped of its spec and actor attribution when it does not. A push
+* outside the span was another run's audience, so its attribution is not
+* this run's to claim — but the collector never re-sends what an earlier
+* run acked, so on an always-on hub the boot set and each process's health
+* figures arrived long before this run began, and only survive here.
+*/
+function resolveStream(events, runId) {
+	const issued = /* @__PURE__ */ new Set();
+	const specOrder = [];
+	const tagToKey = /* @__PURE__ */ new Map();
+	const browserFiles = /* @__PURE__ */ new Map();
+	let universe;
+	let hubRunId;
+	let firstMarkerAt;
+	let lastMarkerAt = 0;
+	for (const event of events) {
+		const body = event.body;
+		if (!("kind" in body) || body.runId !== runId) continue;
+		if (firstMarkerAt === void 0) firstMarkerAt = event.at;
+		lastMarkerAt = event.at;
+		switch (body.kind) {
+			case "spec-open":
+				if (!issued.has(body.specId)) {
+					issued.add(body.specId);
+					specOrder.push(body.specId);
+				}
+				break;
+			case "window-open":
+				tagToKey.set(body.tag, body.key);
+				break;
+			case "universe":
+				universe = {
+					include: body.include,
+					files: body.files
+				};
+				break;
+			case "run-link":
+				hubRunId = body.hubRunId;
+				break;
+			case "browser": {
+				const files = browserFiles.get(body.specId) ?? /* @__PURE__ */ new Set();
+				for (const file of body.files) files.add(file);
+				browserFiles.set(body.specId, files);
+				break;
+			}
+		}
+	}
+	const resolver = new CoverageResolver(issued, tagToKey);
+	let asOf = 0;
+	let lastSeq = 0;
+	let pushesDuringRun = 0;
+	for (const event of events) {
+		if (event.seq > lastSeq) lastSeq = event.seq;
+		const body = event.body;
+		if ("kind" in body) {
+			if (body.runId !== runId) continue;
+			asOf = event.at;
+			if (body.kind === "window-open") resolver.apply({
+				kind: "window-open",
+				at: event.at,
+				tag: body.tag,
+				key: body.key,
+				specId: body.specId
+			});
+			else if (body.kind === "window-close") resolver.apply({
+				kind: "window-close",
+				at: event.at,
+				tag: body.tag
+			});
+			continue;
+		}
+		if (firstMarkerAt === void 0 || event.at < firstMarkerAt || event.at > lastMarkerAt + 3e4) {
+			resolver.apply({
+				kind: "push",
+				at: event.at,
+				push: {
+					...body,
+					specs: {},
+					actors: []
+				}
+			});
+			continue;
+		}
+		asOf = event.at;
+		pushesDuringRun++;
+		resolver.apply({
+			kind: "push",
+			at: event.at,
+			push: body
+		});
+	}
+	const specs = specOrder.map((specId) => {
+		const actorEvents = {};
+		for (const [key, count] of resolver.actorEventsFor(specId)) actorEvents[key] = count;
+		return {
+			specId,
+			files: [...new Set([...resolver.filesFor(specId) ?? [], ...browserFiles.get(specId) ?? []])].sort(),
+			actorEvents
+		};
+	});
+	const outsideWindowEvents = {};
+	for (const [key, count] of resolver.outsideWindowEvents()) outsideWindowEvents[key] = count;
+	return {
+		runId,
+		...hubRunId !== void 0 ? { hubRunId } : {},
+		asOf,
+		lastSeq,
+		...universe !== void 0 ? { universe } : {},
+		specs,
+		boot: [...resolver.boot()].sort(),
+		health: {
+			heardFromApplication: resolver.heardFromApplication(),
+			pushesDuringRun,
+			attributedSpecs: resolver.attributedSpecs(),
+			rejectedPushes: resolver.rejectedPushes(),
+			uninstrumentedFiles: resolver.uninstrumentedFiles(),
+			uninstrumentedProcesses: resolver.uninstrumentedProcesses(),
+			droppedPushes: resolver.droppedPushes(),
+			unmappedActorEvents: resolver.unmappedActorEvents(),
+			outsideWindowEvents,
+			specsMeasured: specs.length
+		}
+	};
+}
+/**
+* Every run that opened a spec in this stream, most recently heard-from
+* first — recency by the arrival position of each run's latest spec-open,
+* the one order the hub's stamps establish.
+*/
+function listRunIds(events) {
+	const lastOpenIndex = /* @__PURE__ */ new Map();
+	events.forEach((event, index) => {
+		const body = event.body;
+		if ("kind" in body && body.kind === "spec-open") lastOpenIndex.set(body.runId, index);
+	});
+	return [...lastOpenIndex.entries()].sort((a, b) => b[1] - a[1]).map(([id]) => id);
+}
+//#endregion
+//#region src/hub/api/auth.ts
+/**
+* Constant-time comparison against the hub's bearer token, so response
+* timing can't be used to guess the token character-by-character. Accepts
+* the token either as an `Authorization: Bearer <token>` header or, for
+* read-only GET endpoints only (the artifacts download is a browser `<a>` that can't
+* carry a header), a `?token=` query parameter — see docs/hub-api.md for
+* the security tradeoff that accepts.
+*/
+function extractToken(req, url) {
+	const header = req.headers.authorization;
+	if (header?.startsWith("Bearer ")) return header.slice(7);
+	return url.searchParams.get("token");
+}
+function isValidToken(provided, expected) {
+	if (provided === null) return false;
+	const a = Buffer.from(provided);
+	const b = Buffer.from(expected);
+	if (a.length !== b.length) return false;
+	return timingSafeEqual(a, b);
+}
+//#endregion
+//#region src/hub/api/handlers/coverage.ts
+/**
+* The coverage inbox (ADR-0022): the hub stamps, stores, serves and expires
+* coverage events — it never looks inside one, except the read-time resolve
+* below, the one bounded amendment ADR-0022 makes to the no-compute rule.
+* The append authenticates here rather than in the server's central token
+* check, because it accepts a second credential:
+* `CCQA_HUB_COVERAGE_TOKEN`, the append-only token the instrumented
+* application holds. That token may append pushes and nothing else — in
+* particular no run events, so a leaked application credential cannot forge
+* the markers that bound a run's view of the stream. The reads stay behind
+* the central check (see SELF_AUTHENTICATED_ROUTES in server.ts).
+*/
+const MAX_COVERAGE_BODY_BYTES = 8 * 1024 * 1024;
+function requireKey(config) {
+	if (!config.encryptionKey) throw new HttpError(503, "encryption_not_configured", "CCQA_HUB_ENCRYPTION_KEY is not set on this hub");
+	return config.encryptionKey;
+}
+function requireProjectParam(ctx) {
+	return requireSafeSegment(ctx.url.searchParams.get("project") ?? "", "project");
+}
+/** Which credential the request carries: the hub's own, or the application's append-only one. */
+function authenticate(ctx, config) {
+	const token = extractToken(ctx.req, ctx.url);
+	if (isValidToken(token, config.hubToken)) return "hub";
+	if (config.coverageToken === void 0) throw new HttpError(503, "coverage_inbox_not_configured", "CCQA_HUB_COVERAGE_TOKEN is not set on this hub");
+	if (isValidToken(token, config.coverageToken)) return "app";
+	throw new HttpError(401, "unauthorized", "missing or invalid bearer token");
+}
+/** POST /api/v1/coverage/events?project= — stamp and append one event; 204 on receipt. */
+function createAppendCoverageEventHandler(config) {
+	return async (ctx) => {
+		const caller = authenticate(ctx, config);
+		const key = requireKey(config);
+		const project = requireProjectParam(ctx);
+		const body = await readJsonBody(ctx.req, MAX_COVERAGE_BODY_BYTES, InboxBodySchema, "coverage event");
+		if (caller === "app" && !("protocol" in body)) throw new HttpError(403, "forbidden", "the coverage token appends application pushes only; run events require the hub bearer token");
+		const payload = encodeEncryptedBlob(encrypt(new TextEncoder().encode(JSON.stringify(body)), key));
+		await config.store.append(project, payload);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+/**
+* GET /api/v1/coverage/events?project=&sinceSeq= — the stream after `sinceSeq`
+* (exclusive, so a consumer passes back the `lastSeq` it saw), decrypted.
+* Hub bearer token only (the server's central check): what the append-only
+* credential wrote, it must not be able to read back.
+*/
+function createGetCoverageEventsHandler(config) {
+	return async (ctx) => {
+		const key = requireKey(config);
+		const project = requireProjectParam(ctx);
+		const sinceSeq = requireSinceSeqParam(ctx.url);
+		sendJson(ctx.res, 200, await readStream(config, key, project, sinceSeq));
+	};
+}
+/** The stored stream after `sinceSeq` (exclusive), decrypted and parsed. */
+async function readStream(config, key, project, sinceSeq) {
+	const { entries, lastSeq, skipped } = await config.store.read(project, sinceSeq);
+	const events = [];
+	let unreadable = 0;
+	for (const entry of entries) try {
+		const plain = decrypt(decodeEncryptedBlob(entry.payload), key);
+		const body = InboxBodySchema.parse(JSON.parse(new TextDecoder().decode(plain)));
+		events.push({
+			seq: entry.seq,
+			at: entry.at,
+			body
+		});
+	} catch {
+		unreadable += 1;
+	}
+	return {
+		events,
+		lastSeq,
+		skipped: skipped + unreadable
+	};
+}
+/** Newest runs the resolve read offers; past twenty the answer is history nobody pages through. */
+const RUN_IDS_LIMIT = 20;
+/** Resolved answers kept per handler; one page polls one key, so a handful covers the readers. */
+const RESOLVE_CACHE_LIMIT = 8;
+/**
+* Memo of served answers keyed by stream position (ADR-0022: a resolved
+* answer may be cached keyed by stream position, but the cache is never the
+* record). Any new event moves the stream's seq, so a stored answer can only
+* ever be served for exactly the stream it was computed from — which is what
+* lets the handler answer a hit without reading the stream at all.
+* Least-recently-used beyond `limit`. `runKey` is the requested runId, or ""
+* for "the latest run". Unambiguous join: `project` is a safe segment (no
+* newline) and the trailing element is a number, so `runKey` cannot forge
+* another key.
+*/
+function createResolveMemo(limit) {
+	const cache = /* @__PURE__ */ new Map();
+	const keyOf = (project, runKey, seq) => `${project}\n${runKey}\n${seq}`;
+	return {
+		get(project, runKey, seq) {
+			const cacheKey = keyOf(project, runKey, seq);
+			const hit = cache.get(cacheKey);
+			if (hit !== void 0) {
+				cache.delete(cacheKey);
+				cache.set(cacheKey, hit);
+			}
+			return hit;
+		},
+		put(project, runKey, seq, answer) {
+			cache.set(keyOf(project, runKey, seq), answer);
+			if (cache.size > limit) {
+				const oldest = cache.keys().next().value;
+				if (oldest !== void 0) cache.delete(oldest);
+			}
+		}
+	};
+}
+/**
+* GET /api/v1/coverage?project=[&runId=] — the stream, interpreted for one
+* run by the shared resolver (resolve-stream.ts); this handler only reads,
+* memoizes and serves. `runId` omitted means the run the stream most
+* recently heard a spec-open from — the page's default view; naming one
+* serves history. Hub bearer token only (the central check), like the raw
+* read.
+*/
+function createResolveCoverageHandler(config) {
+	const memo = createResolveMemo(RESOLVE_CACHE_LIMIT);
+	return async (ctx) => {
+		const key = requireKey(config);
+		const project = requireProjectParam(ctx);
+		const requested = ctx.url.searchParams.get("runId");
+		const runKey = requested !== null && requested !== "" ? requested : "";
+		const seq = await config.store.currentSeq(project);
+		const hit = memo.get(project, runKey, seq);
+		if (hit !== void 0) {
+			sendJson(ctx.res, 200, hit);
+			return;
+		}
+		const { events, lastSeq } = await readStream(config, key, project, 0);
+		const runIds = listRunIds(events).slice(0, RUN_IDS_LIMIT);
+		const runId = runKey !== "" ? runKey : runIds[0];
+		const answer = {
+			resolved: runId === void 0 || events.length === 0 ? null : resolveStream(events, runId),
+			runIds
+		};
+		memo.put(project, runKey, lastSeq, answer);
+		sendJson(ctx.res, 200, answer);
+	};
+}
+/** Rejected rather than defaulted on garbage: a typo would otherwise read as "the whole stream". */
+function requireSinceSeqParam(url) {
+	const raw = url.searchParams.get("sinceSeq");
+	if (raw === null || raw === "") return 0;
+	const value = Number(raw);
+	if (!Number.isInteger(value) || value < 0) throw new HttpError(400, "invalid_param", "invalid sinceSeq: must be a non-negative integer");
+	return value;
+}
+//#endregion
 //#region src/hub/core/rerun.ts
 /**
 * When each deployed commit reached the environment. A baseline read at that
@@ -22238,28 +22939,6 @@ var Router = class {
 	}
 };
 //#endregion
-//#region src/hub/api/auth.ts
-/**
-* Constant-time comparison against the hub's bearer token, so response
-* timing can't be used to guess the token character-by-character. Accepts
-* the token either as an `Authorization: Bearer <token>` header or, for
-* read-only GET endpoints only (the artifacts download is a browser `<a>` that can't
-* carry a header), a `?token=` query parameter — see docs/hub-api.md for
-* the security tradeoff that accepts.
-*/
-function extractToken(req, url) {
-	const header = req.headers.authorization;
-	if (header?.startsWith("Bearer ")) return header.slice(7);
-	return url.searchParams.get("token");
-}
-function isValidToken(provided, expected) {
-	if (provided === null) return false;
-	const a = Buffer.from(provided);
-	const b = Buffer.from(expected);
-	if (a.length !== b.length) return false;
-	return timingSafeEqual(a, b);
-}
-//#endregion
 //#region src/hub/api/cors.ts
 /**
 * Apply CORS headers when the request's Origin is in the configured
@@ -23448,6 +24127,7 @@ const CLIENT_JS = `
       "coverage.reached": "Reached", "coverage.uncovered": "Uncovered", "coverage.files": "files",
       "coverage.measured": "measured", "coverage.specsCombined": "specs combined",
       "coverage.noUniverse": "This measurement carried no file inventory, so only reached files are shown; nothing can be called uncovered.",
+      "coverage.noServerDuringRun": "No instrumented server process reported during this run — check CCQA_COVERAGE_ENDPOINT on the application.",
       "coverage.placeholder": "Select a file to see the cases that reach it.",
       "coverage.fileUncovered": "No case reached this file in this measurement.",
       "coverage.casesReach": "case(s) reach this file",
@@ -23671,6 +24351,7 @@ const CLIENT_JS = `
       "coverage.reached": "到達", "coverage.uncovered": "未到達", "coverage.files": "ファイル",
       "coverage.measured": "計測", "coverage.specsCombined": "spec 合算",
       "coverage.noUniverse": "この計測にはファイル台帳が付いていないため、到達したファイルのみ表示しています。未到達は判定できません。",
+      "coverage.noServerDuringRun": "この実行中、計装済みサーバプロセスからの報告がありませんでした。アプリケーション側の CCQA_COVERAGE_ENDPOINT を確認してください。",
       "coverage.placeholder": "ファイルを選択すると、到達しているケースが表示されます",
       "coverage.fileUncovered": "この計測では、どのケースもこのファイルに到達しませんでした。",
       "coverage.casesReach": "ケースが到達",
@@ -24599,8 +25280,8 @@ const CLIENT_JS = `
   }
 
   // == coverage: file tree =============================================
-  // One run's measurement drawn over the enumerated universe. Everything is
-  // display-side aggregation of report.json — the hub computes nothing new.
+  // One run's measurement drawn over the enumerated universe. The hub's
+  // resolve endpoint answers first (ADR-0022); the page only colours it.
   var covState = { q: "", unc: false, model: null, selected: null, openDirs: null, loadToken: 0 };
 
   function openCoverage() {
@@ -24616,17 +25297,14 @@ const CLIENT_JS = `
     document.getElementById("cov-body").hidden = true;
     status.hidden = false;
     status.textContent = t("coverage.loading");
-    apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&kind=run&limit=25")
-      .then(function (data) {
-        // A run still in flight has a report, but a partial one: rows trickle
-        // in per spec and the universe only arrives with the seal.
-        var runs = (data.runs || []).filter(function (r) { return r.status !== "running"; });
-        return covFindReport(runs, 0, token);
-      })
-      .then(function (found) {
+    covLoadResolved(token)
+      // Runs that measured locally streamed nothing; their answer still rides
+      // report.json, so the probe stays as the fallback for them.
+      .then(function (model) { return model || covLoadFromReports(token); })
+      .then(function (model) {
         if (token !== covState.loadToken) return;
-        if (!found) { status.textContent = t("coverage.none"); return; }
-        covState.model = covBuildModel(found.run, found.report);
+        if (!model) { status.textContent = t("coverage.none"); return; }
+        covState.model = model;
         covState.openDirs = null;
         covState.selected = null;
         status.hidden = true;
@@ -24639,6 +25317,89 @@ const CLIENT_JS = `
       });
   }
 
+  // The stream's resolved answer, or null when nothing streamed. Not always
+  // the freshest answer: a local run after a hub-mode one writes its coverage
+  // into report.json, not the stream, so a settled run newer than the
+  // stream's last word is probed first and wins when it measured.
+  function covLoadResolved(token) {
+    return apiFetch("/api/v1/coverage?project=" + encodeURIComponent(state.project))
+      .then(function (data) {
+        if (token !== covState.loadToken || !data || !data.resolved) return null;
+        var resolved = data.resolved;
+        return apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&kind=run&limit=25")
+          .catch(function () { return null; })
+          .then(function (list) {
+            // Newest first, settled only, and only runs created after the
+            // stream's "as of" — older ones the stream already answers for.
+            var newer = ((list && list.runs) || []).filter(function (r) {
+              return r.status !== "running" && Date.parse(r.createdAt) > resolved.asOf;
+            }).slice(0, 5);
+            return covFindReport(newer, 0, token).then(function (found) {
+              if (found) return covBuildModel(found.run, found.report);
+              return covResolvedGitHead(resolved).then(function (head) {
+                return covModelFromResolved(resolved, head);
+              });
+            });
+          });
+      })
+      .catch(function () { return null; });
+  }
+
+  // The stream carries no commit; only the linked run record does. One direct
+  // read — a stream run id with no run record simply shows no sha.
+  function covResolvedGitHead(resolved) {
+    if (!resolved.hubRunId) return Promise.resolve(null);
+    return apiFetch("/api/v1/runs/" + encodeURIComponent(resolved.hubRunId))
+      .then(function (run) { return (run && run.gitHead) || null; })
+      .catch(function () { return null; });
+  }
+
+  function covLoadFromReports(token) {
+    return apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&kind=run&limit=25")
+      .then(function (data) {
+        // A run still in flight has a report, but a partial one: rows trickle
+        // in per spec and the universe only arrives with the seal.
+        var runs = (data.runs || []).filter(function (r) { return r.status !== "running"; });
+        return covFindReport(runs, 0, token);
+      })
+      .then(function (found) {
+        if (!found) return null;
+        return covBuildModel(found.run, found.report);
+      });
+  }
+
+  // Reshapes the resolved answer into the {results, coverageUniverse} the
+  // report-based model builder already consumes, so one tree renderer serves
+  // both sources.
+  function covModelFromResolved(resolved, gitHead) {
+    var results = (resolved.specs || []).map(function (s) {
+      // Spec ids are "<runId>.<feature>/<spec>" (the run id keeps a stale
+      // cookie out); the page is already scoped to one run, so drop it.
+      var key = s.specId;
+      if (key.indexOf(resolved.runId + ".") === 0) key = key.slice(resolved.runId.length + 1);
+      var slash = key.indexOf("/");
+      return {
+        feature: slash === -1 ? key : key.slice(0, slash),
+        spec: slash === -1 ? "" : key.slice(slash + 1),
+        coverage: { files: s.files || [] },
+      };
+    });
+    var report = {
+      results: results,
+      createdAt: new Date(resolved.asOf).toISOString(),
+      git: { head: gitHead },
+    };
+    if (resolved.universe) report.coverageUniverse = { files: resolved.universe.files };
+    // The stream's own run id names no run page; only the linked record does.
+    var model = covBuildModel({ id: resolved.hubRunId || null }, report);
+    // The endpoint-mismatch detector (ADR-0022): specs measured, yet not one
+    // application push arrived while the run listened — the application is
+    // pushing somewhere else, or not at all.
+    model.noServerDuringRun =
+      !!(resolved.health && resolved.health.pushesDuringRun === 0 && results.length > 0);
+    return model;
+  }
+
   // Newest first, stop at the first run whose report actually measured.
   // Capped: each probe is a full report fetch, and past ten stale runs the
   // answer is "none recent enough to trust" anyway.
@@ -24730,7 +25491,14 @@ const CLIENT_JS = `
     var segments = [{ cls: "sg-verified", state: "reached", count: model.root.covered }];
     if (model.hasUniverse) segments.push({ cls: "sg-rerunneeded", state: "uncovered", count: uncovered });
     if (model.root.total > 0) axis.appendChild(ovAxisRow("", segments, "coverage.", model.root.total));
-    document.getElementById("cov-note").hidden = model.hasUniverse;
+    // One note slot, two conditions. The endpoint warning outranks the
+    // no-universe note: it says the numbers themselves are short, not just
+    // that nothing can be called uncovered.
+    var note = document.getElementById("cov-note");
+    var noteKey = model.noServerDuringRun ? "coverage.noServerDuringRun" : "coverage.noUniverse";
+    note.setAttribute("data-i18n", noteKey);
+    note.textContent = t(noteKey);
+    note.hidden = model.noServerDuringRun ? false : model.hasUniverse;
     // Without a denominator every shown file is reached — the filter could
     // only ever produce an empty tree, so it is withdrawn, not just zeroed.
     var uncChip = document.getElementById("cov-unc");
@@ -24869,12 +25637,18 @@ const CLIENT_JS = `
     var list = el("div", "cov-caselist");
     var runId = covState.model.run.id;
     // No pass/fail here on purpose: this pane answers "what reaches this
-    // file", not "did it pass" — the run page holds the verdicts.
+    // file", not "did it pass" — the run page holds the verdicts. A model
+    // with no linked run record gets plain rows: no link beats a dead one.
     f.cases.forEach(function (key) {
-      var a = document.createElement("a");
-      a.href = "#/runs/" + encodeURIComponent(runId);
-      a.appendChild(el("span", "cs", key));
-      list.appendChild(a);
+      var row;
+      if (runId) {
+        row = document.createElement("a");
+        row.href = "#/runs/" + encodeURIComponent(runId);
+      } else {
+        row = el("div");
+      }
+      row.appendChild(el("span", "cs", key));
+      list.appendChild(row);
     });
     host.appendChild(list);
   }
@@ -28599,6 +29373,15 @@ async function loadStoredCustomPrompt(storage, project) {
 //#region src/hub/api/server.ts
 /** Endpoints reachable without a token: the liveness probe and the bundled UI shell. */
 const PUBLIC_PATHS = new Set(["/api/v1/health", "/"]);
+/**
+* Requests ("METHOD pathname") that authenticate inside their handlers
+* instead of the central bearer check below: the coverage append accepts a
+* second, append-only credential (ADR-0022) that a single-token check cannot
+* express. Keyed by method so the sibling reads under the same path stay
+* behind the central check. Every handler registered here must enforce auth
+* itself.
+*/
+const SELF_AUTHENTICATED_ROUTES = new Set(["POST /api/v1/coverage/events"]);
 function createHubServer(config) {
 	const queue = new LearningQueue(config.storage.jobs, createLearningWorker({ storage: config.storage }));
 	queue.recoverFromRestart().catch((err) => {
@@ -28622,12 +29405,13 @@ async function handleRequest(req, res, router, config) {
 	try {
 		if (applyCors(req, res, config.allowedOrigins)) return;
 		const url = new URL(req.url ?? "/", "http://localhost");
-		const matched = router.match(req.method ?? "GET", url.pathname);
+		const method = req.method ?? "GET";
+		const matched = router.match(method, url.pathname);
 		if (!matched) {
 			sendError(res, new HttpError(404, "not_found", `no route for ${req.method} ${url.pathname}`));
 			return;
 		}
-		if (!PUBLIC_PATHS.has(url.pathname)) {
+		if (!PUBLIC_PATHS.has(url.pathname) && !SELF_AUTHENTICATED_ROUTES.has(`${method} ${url.pathname}`)) {
 			if (!isValidToken(extractToken(req, url), config.token)) {
 				sendError(res, new HttpError(401, "unauthorized", "missing or invalid bearer token"));
 				return;
@@ -28720,6 +29504,15 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/perspectives", createGetPerspectivesHandler(perspectivesConfig));
 	router.patch("/api/v1/projects/:project/perspectives", createPatchPerspectivesNoteHandler(perspectivesConfig));
 	router.delete("/api/v1/projects/:project/perspectives", createDeletePerspectivesHandler(perspectivesConfig));
+	const coverageConfig = {
+		store: storage.coverageEvents,
+		encryptionKey: config.encryptionKey,
+		hubToken: config.token,
+		coverageToken: config.coverageToken
+	};
+	router.post("/api/v1/coverage/events", createAppendCoverageEventHandler(coverageConfig));
+	router.get("/api/v1/coverage/events", createGetCoverageEventsHandler(coverageConfig));
+	router.get("/api/v1/coverage", createResolveCoverageHandler(coverageConfig));
 	router.post("/api/v1/projects/:project/learning-jobs", createCreateLearningJobHandler({
 		storage,
 		queue
@@ -28889,6 +29682,7 @@ function isNotFound(err) {
 *   deploys/<project>/<profile>/touch.json       (SpecTouchIndex derived from the log)
 *   acks/<project>/<profile>/<name>.json         (Ack: a consumer's acted-on keys)
 *   spend/<project>.json                         (SpendLog, pruned to its retention window)
+*   coverage/<project>/events.jsonl              (coverage inbox: stamped encrypted events)
 *
 * IDs and names are validated by their callers (run ids are server-minted
 * UUIDs; project/profile/name come from validated request params) before
@@ -28992,6 +29786,9 @@ function ackPath(root, project, profile, name) {
 function spendPath(root, project) {
 	return join(root, "spend", `${project}.json`);
 }
+function coverageEventsPath(root, project) {
+	return join(root, "coverage", project, "events.jsonl");
+}
 //#endregion
 //#region src/hub/core/storage/file/ack-store.ts
 function assertSafeKey(project, profile, name) {
@@ -29101,6 +29898,176 @@ function createFileArtifactStore(root) {
 		}
 	};
 }
+const PRUNE_COUNT_BATCH = 1e3;
+const PRUNE_AGE_SLACK_MS = 3600 * 1e3;
+/**
+* Coverage-inbox storage: `coverage/<project>/events.jsonl`, one stamped
+* event per line, appended in place (not atomic-rewritten — an append must
+* not cost the whole stream). A reader can therefore observe a partial final
+* line mid-append; the read side counts such lines as skipped rather than
+* failing, and the prune's full rewrite goes through the atomic path.
+*/
+function createFileCoverageEventStore(root, caps) {
+	const maxEvents = caps?.maxEvents ?? 2e5;
+	const maxBytes = caps?.maxBytes ?? 268435456;
+	const retentionMs = caps?.retentionMs ?? 336 * 60 * 60 * 1e3;
+	const pruneBatch = Math.min(PRUNE_COUNT_BATCH, Math.max(1, Math.floor(maxEvents / 10)));
+	const pruneBytesTarget = maxBytes - Math.max(1, Math.floor(maxBytes / 10));
+	const states = /* @__PURE__ */ new Map();
+	async function loadState(project, path) {
+		const cached = states.get(project);
+		if (cached) return cached;
+		const raw = await readRaw(path);
+		const state = {
+			nextSeq: 1,
+			count: 0,
+			bytes: Buffer.byteLength(raw),
+			oldestAt: null,
+			endsWithNewline: raw === "" || raw.endsWith("\n")
+		};
+		for (const rawLine of nonEmptyLines(raw)) {
+			const line = parseLine(rawLine);
+			if (line === null) continue;
+			if (line.seq >= state.nextSeq) state.nextSeq = line.seq + 1;
+			state.count += 1;
+			if (state.oldestAt === null || line.at < state.oldestAt) state.oldestAt = line.at;
+		}
+		states.set(project, state);
+		return state;
+	}
+	async function pruneIfDue(project, path, state, now) {
+		const overCount = state.count > maxEvents;
+		const overBytes = state.bytes > maxBytes;
+		const overAge = state.oldestAt !== null && state.oldestAt < now - retentionMs - PRUNE_AGE_SLACK_MS;
+		if (!overCount && !overBytes && !overAge) return;
+		const lines = await readLines(path);
+		const cutoff = now - retentionMs;
+		const fresh = lines.filter((l) => l.at >= cutoff);
+		const keep = overCount ? Math.max(0, maxEvents - pruneBatch) : maxEvents;
+		let kept = fresh.length > keep ? fresh.slice(fresh.length - keep) : fresh;
+		if (overBytes) kept = newestWithinBytes(kept, pruneBytesTarget);
+		const encoded = new TextEncoder().encode(kept.map((l) => JSON.stringify(l)).join("\n") + (kept.length > 0 ? "\n" : ""));
+		await writeBytes(path, encoded);
+		const dropped = state.count - kept.length;
+		state.count = kept.length;
+		state.bytes = encoded.byteLength;
+		state.oldestAt = kept[0]?.at ?? null;
+		state.endsWithNewline = true;
+		if (dropped > 0) console.warn(`hub: coverage inbox for "${project}": dropped ${dropped} events past retention (${maxEvents} events / ${Math.round(maxBytes / 1048576)} MiB / ${Math.round(retentionMs / 864e5)} days)`);
+	}
+	return {
+		async append(project, payload) {
+			assertSafeName(project, "project");
+			const path = coverageEventsPath(root, project);
+			return await serialize(path, async () => {
+				const state = await loadState(project, path);
+				const stamp = {
+					seq: state.nextSeq,
+					at: Date.now()
+				};
+				const line = {
+					...stamp,
+					payload: Buffer.from(payload).toString("base64")
+				};
+				await mkdir(dirname(path), { recursive: true });
+				const text = (state.endsWithNewline ? "" : "\n") + JSON.stringify(line) + "\n";
+				await appendFile(path, text);
+				state.nextSeq += 1;
+				state.count += 1;
+				state.bytes += Buffer.byteLength(text);
+				state.endsWithNewline = true;
+				if (state.oldestAt === null) state.oldestAt = stamp.at;
+				await pruneIfDue(project, path, state, stamp.at);
+				return stamp;
+			});
+		},
+		async read(project, sinceSeq) {
+			assertSafeName(project, "project");
+			const path = coverageEventsPath(root, project);
+			const now = Date.now();
+			await serialize(path, async () => {
+				await pruneIfDue(project, path, await loadState(project, path), now);
+			});
+			const raw = await readRaw(path);
+			const cutoff = now - retentionMs;
+			const entries = [];
+			let lastSeq = 0;
+			let skipped = 0;
+			for (const rawLine of nonEmptyLines(raw)) {
+				const line = parseLine(rawLine);
+				if (line === null) {
+					skipped += 1;
+					continue;
+				}
+				if (line.seq > lastSeq) lastSeq = line.seq;
+				if (line.seq <= sinceSeq) continue;
+				if (line.at < cutoff) continue;
+				entries.push({
+					seq: line.seq,
+					at: line.at,
+					payload: new Uint8Array(Buffer.from(line.payload, "base64"))
+				});
+			}
+			entries.sort((a, b) => a.seq - b.seq);
+			return {
+				entries,
+				lastSeq,
+				skipped
+			};
+		},
+		async currentSeq(project) {
+			assertSafeName(project, "project");
+			const cached = states.get(project);
+			if (cached) return cached.nextSeq - 1;
+			const path = coverageEventsPath(root, project);
+			return (await serialize(path, () => loadState(project, path))).nextSeq - 1;
+		}
+	};
+}
+/** The longest tail of `lines` whose serialized size (newlines included) fits in `budget`. */
+function newestWithinBytes(lines, budget) {
+	let total = 0;
+	for (let i = lines.length - 1; i >= 0; i -= 1) {
+		total += Buffer.byteLength(JSON.stringify(lines[i])) + 1;
+		if (total > budget) return lines.slice(i + 1);
+	}
+	return lines;
+}
+async function readRaw(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (err) {
+		if (err instanceof Error && "code" in err && err.code === "ENOENT") return "";
+		throw err;
+	}
+}
+function nonEmptyLines(raw) {
+	return raw.split("\n").filter((l) => l !== "");
+}
+/** Every parseable line of the log; partial or corrupt lines are silently omitted (the read side counts them). */
+async function readLines(path) {
+	const lines = [];
+	for (const rawLine of nonEmptyLines(await readRaw(path))) {
+		const line = parseLine(rawLine);
+		if (line !== null) lines.push(line);
+	}
+	return lines;
+}
+function parseLine(rawLine) {
+	let value;
+	try {
+		value = JSON.parse(rawLine);
+	} catch {
+		return null;
+	}
+	const line = value;
+	if (typeof line.seq !== "number" || typeof line.at !== "number" || typeof line.payload !== "string") return null;
+	return {
+		seq: line.seq,
+		at: line.at,
+		payload: line.payload
+	};
+}
 //#endregion
 //#region src/hub/core/storage/file/deploy-store.ts
 function createFileDeployStore(root) {
@@ -29544,7 +30511,8 @@ function createFileHubStorage(dataDir) {
 		acks: createFileAckStore(dataDir),
 		spend: createFileSpendStore(dataDir),
 		attestations: createFileAttestationStore(dataDir),
-		auditDismissals: createFileAuditDismissalStore(dataDir)
+		auditDismissals: createFileAuditDismissalStore(dataDir),
+		coverageEvents: createFileCoverageEventStore(dataDir)
 	};
 }
 //#endregion
@@ -29588,6 +30556,11 @@ async function runServe(opts) {
 		process.exit(2);
 	}
 	else warn("CCQA_HUB_ENCRYPTION_KEY is not set — sessions and variables cannot be stored (PUT returns 503)");
+	const coverageToken = process.env.CCQA_HUB_COVERAGE_TOKEN;
+	if (coverageToken !== void 0 && coverageToken === token) {
+		error("CCQA_HUB_COVERAGE_TOKEN must differ from CCQA_HUB_TOKEN — the same value would make the append-only credential a full hub token");
+		process.exit(2);
+	}
 	const dataDir = resolveCwd(opts.dataDir);
 	const server = createHubServer({
 		storage: createHubStorage({
@@ -29598,7 +30571,8 @@ async function runServe(opts) {
 		encryptionKey,
 		allowedOrigins: opts.allowOrigin ?? [],
 		...opts.maxPushMb ? { maxPushBytes: opts.maxPushMb * 1024 * 1024 } : {},
-		...opts.maxRunsPerBranch ? { maxRunsPerBranch: opts.maxRunsPerBranch } : {}
+		...opts.maxRunsPerBranch ? { maxRunsPerBranch: opts.maxRunsPerBranch } : {},
+		...coverageToken ? { coverageToken } : {}
 	});
 	const requestedPort = Number(opts.port);
 	if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
@@ -29615,6 +30589,7 @@ async function runServe(opts) {
 		header("serve", `port ${boundPort}`);
 		meta("data-dir", dataDir);
 		meta("encryption", encryptionKey ? "enabled" : "disabled (no CCQA_HUB_ENCRYPTION_KEY)");
+		meta("coverage inbox", coverageToken && encryptionKey ? "enabled" : coverageToken ? "disabled (no CCQA_HUB_ENCRYPTION_KEY)" : "disabled (no CCQA_HUB_COVERAGE_TOKEN)");
 		meta("run retention", `${opts.maxRunsPerBranch ?? 200} per project/branch`);
 		const auth = driftAuthAvailable();
 		meta("triage learning", auth.ok ? "available" : `unavailable (${auth.reason} — learning jobs will fail)`);