ccqa 1.36.0 → 1.37.1

package/dist/bin/ccqa.mjs

@@ -4,8 +4,8 @@ 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";
 import { Command } from "commander";
-import { accessSync, appendFileSync, createWriteStream, existsSync, readFileSync, rmSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+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 { homedir, tmpdir } from "node:os";
@@ -17,9 +17,10 @@ import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk"
 import { AsyncLocalStorage } from "node:async_hooks";
 import { promisify } from "node:util";
 import { createInterface } from "node:readline/promises";
+import { createServer } from "node:http";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { createInterface as createInterface$1 } from "node:readline";
-import { createServer } from "node:http";
+import { createServer as createServer$1 } from "node:net";
 //#region src/run/report-constants.ts
 /**
 * Pure report/run constants with no runtime dependencies. Kept separate from
@@ -185,14 +186,14 @@ const SpecModeSchema = z.enum(["deterministic", "live"]);
 * A name a spec chooses that ccqa resolves to a path or looks up in a
 * registry. Restricted to a slug so it cannot escape a directory.
 */
-function slug(what) {
+function slug$1(what) {
 	return z.string().min(1).regex(/^[a-z0-9][a-z0-9._-]*$/i, `${what} must be a slug (letters, digits, '.', '_', '-'; no path separators)`);
 }
 /**
 * A saved browser session (cookies + localStorage) to restore before the spec
 * runs, resolved to `.ccqa/sessions/<profile>/<name>.json` at run time.
 */
-const SessionNameSchema = slug("session name");
+const SessionNameSchema = slug$1("session name");
 /**
 * Sessions to restore before a `mode: live` spec runs: one name or a list,
 * always read back as a list. Multiple names are merged (their cookies +
@@ -206,7 +207,7 @@ const SessionFieldSchema = z.union([SessionNameSchema, z.array(SessionNameSchema
 * registered target is the registry's responsibility, so new targets don't
 * require a schema change.
 */
-const TargetIdSchema = slug("target");
+const TargetIdSchema = slug$1("target");
 /** The built-in recorder-backed target. `mode:` / `session:` only apply to it. */
 const AGENT_BROWSER_TARGET = "agent-browser";
 /**
@@ -3454,6 +3455,48 @@ const ReportArtifactSchema = z.object({
 	sizeBytes: z.number()
 });
 /**
+* Everything one spec's measurement could not place.
+*
+* These are load-bearing, not diagnostics. An execution nobody could attribute
+* is indistinguishable from one that never happened, and "never happened" is
+* the answer this measurement exists to produce — so each way of losing one is
+* counted separately and shown next to the result (ADR-0021).
+*/
+const CoverageGapsSchema = z.object({
+	unattributed: z.number(),
+	unmappedScripts: z.number(),
+	unmappedRanges: z.number(),
+	outsideProject: z.number(),
+	unresolvedSources: z.number(),
+	uninstrumentedFiles: z.number(),
+	uninstrumentedProcesses: z.number(),
+	droppedPushes: z.number(),
+	unmappedActorEvents: z.number().default(0),
+	outsideWindowEvents: z.number().default(0)
+});
+/**
+* What one spec's execution actually reached: V8's own counters for the
+* browser and per-request instrumentation for the server, unioned on the spec
+* id both sides carry (ADR-0021).
+*
+* `backendReported` / `frontendReported` separate "reached nothing" from "that
+* half never answered", which otherwise render identically as zero.
+*/
+const ReportCoverageSchema = z.object({
+	files: z.array(z.string()),
+	frontendFiles: z.number(),
+	backendFiles: z.number(),
+	backendReported: z.boolean(),
+	frontendReported: z.boolean(),
+	frontendStopped: z.boolean(),
+	actorWindows: z.array(z.object({
+		key: z.string(),
+		events: z.number()
+	})).default([]),
+	excludedDependencies: z.number(),
+	gaps: CoverageGapsSchema
+});
+/**
 * Per-step / per-run cost+usage record, pulled from the SDK's `result` message.
 * Every numeric field is nullable so the report can carry partial telemetry
 * (e.g. when the SDK omits a field, or when a step was skipped).
@@ -3552,6 +3595,8 @@ const ReportSpecResultSchema = z.object({
 	evidence: z.array(ReportEvidenceSchema).nullable(),
 	evidenceUnavailable: z.string().optional(),
 	artifacts: z.array(ReportArtifactSchema).optional(),
+	coverage: ReportCoverageSchema.optional(),
+	coverageUnavailable: z.string().optional(),
 	liveRun: LiveReportRunSchema.nullable()
 });
 /**
@@ -3575,6 +3620,17 @@ const GitEnvelopeSchema = z.object({
 	baseSha: z.string().nullable().optional(),
 	baseSource: BaseSourceSchema.nullable().optional()
 });
+/**
+* The denominator for the run's coverage measurement: every source file under
+* `coverage.include`, enumerated by the run from the same checkout the specs
+* ran against — which is what entitles a viewer to read "absent from every
+* row's file set" as "uncovered" rather than "unknown". Run-level because it
+* is a property of the checkout, not of any one spec.
+*/
+const CoverageUniverseSchema = z.object({
+	include: z.array(z.string()),
+	files: z.array(z.string())
+});
 const RunReportDataSchema = z.object({
 	schemaVersion: z.literal(1),
 	kind: ReportKindSchema.default("run"),
@@ -3589,6 +3645,7 @@ const RunReportDataSchema = z.object({
 	triageUserPromptHash: z.string().optional(),
 	deployedSha: z.string().optional(),
 	cost: ReportCostSchema.nullable().default(null),
+	coverageUniverse: CoverageUniverseSchema.optional(),
 	results: z.array(ReportSpecResultSchema)
 });
 /** Shape of the "export labels" download produced by the report's client-side JS. */
@@ -3669,9 +3726,19 @@ function scrubOutcome(outcome, scrubMap) {
 		}
 	};
 }
+/**
+* Pause before the single retry of an errored classification call. Long enough
+* to ride out a transient network/model hiccup, short enough not to stall the
+* report when the error is persistent.
+*/
+const RETRY_DELAY_MS = 2e3;
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function classifyFailure(input, options) {
-	const { result: raw, isError } = await invokeClaudeStreaming({
-		prompt: buildFailureAnalysisPrompt(input),
+	const prompt = buildFailureAnalysisPrompt(input);
+	const invoke = () => invokeClaudeStreaming({
+		prompt,
 		allowedTools: [
 			"Read",
 			"Grep",
@@ -3684,11 +3751,22 @@ async function classifyFailure(input, options) {
 		...options.model ? { model: options.model } : {},
 		...options.cwd ? { cwd: options.cwd } : {}
 	}, () => {});
-	if (isError || !raw) return {
-		analysis: unknownAnalysis(isError ? "Claude returned an error result" : "Claude returned no output"),
-		raw: raw ?? "",
-		sdkError: isError
-	};
+	let { result: raw, isError } = await invoke();
+	let retried = false;
+	if (isError) {
+		warn("failure analysis: Claude invocation errored — retrying once");
+		await sleep(RETRY_DELAY_MS);
+		({result: raw, isError} = await invoke());
+		retried = true;
+	}
+	if (isError || !raw) {
+		const cause = isError ? "Claude returned an error result" : "Claude returned no output";
+		return {
+			analysis: unknownAnalysis(retried ? `${cause} (after 1 retry)` : cause),
+			raw: raw ?? "",
+			sdkError: isError
+		};
+	}
 	let sawParseableJson = false;
 	for (const candidate of extractJsonCandidates(raw)) {
 		let parsed;
@@ -5438,36 +5516,1660 @@ function computeLineDiff(a, b) {
 	});
 	return out.map((l) => l.kind === "add" ? `+ ${l.text}` : l.kind === "del" ? `- ${l.text}` : `  ${l.text}`);
 }
-function truncate$1(s, n) {
-	if (s.length <= n) return s;
-	return s.slice(s.length - n);
+function truncate$1(s, n) {
+	if (s.length <= n) return s;
+	return s.slice(s.length - n);
+}
+//#endregion
+//#region src/run/output-tail.ts
+/** Cap on the per-spec output tail kept for the report / analysis prompt. */
+const OUTPUT_TAIL_CAP = 64 * 1024;
+/**
+* Keeps the LAST `cap` characters appended — test runners put the failure
+* summary at the end of their output, so the tail is what's worth keeping on
+* overflow. Dependency-free so both the vitest pipeline and the runCommand
+* runner (src/targets/run-command-runner.ts) can use it without importing the
+* whole pipeline.
+*/
+var TailBuffer = class {
+	buf = "";
+	cap;
+	constructor(cap) {
+		this.cap = cap;
+	}
+	append(s) {
+		this.buf += s;
+		if (this.buf.length > this.cap * 2) this.buf = this.buf.slice(-this.cap);
+	}
+	toString() {
+		if (this.buf.length <= this.cap) return this.buf;
+		return `[...output truncated...]\n${this.buf.slice(-this.cap)}`;
+	}
+};
+//#endregion
+//#region src/coverage/actors.ts
+/**
+* Attribution by who acted, for the requests that cannot carry a spec id.
+*
+* The measurement's normal carrier is the request itself — a cookie the browser
+* holds, a baggage header, a Temporal header. A webhook from a chat platform
+* has none of them: the browser only ever talked to the platform, and what
+* reaches the application was sent by the platform's servers. Everything such a
+* flow runs would be unattributed, which for a suite whose majority is chat
+* flows means the measurement misses its main subject.
+*
+* What the webhook does carry is who caused it. If exactly one spec may act as
+* that identity at a time, "who" plus "when" identifies the spec — so the
+* application records only the fact (`this identity acted, at this instant`)
+* and every judgement about which spec that belongs to is made here and in the
+* sink. Nothing flows the other way: the application is never told which
+* identities matter or which windows are open, so there is no table to
+* distribute, go stale, or leak one project's identities into another's logs.
+*/
+/**
+* Quiet gap enforced between two specs that act as the same identity.
+*
+* The application stamps events with its own clock and the sink judges them
+* against its own, so an event near a boundary could fall on either side. Three
+* seconds is over two push intervals, which also means the window being closed
+* has had time to receive everything still in flight for it.
+*/
+const ACTOR_DRAIN_MS = 3e3;
+ACTOR_DRAIN_MS / 2;
+const NO_ACTORS = {
+	windows: [],
+	tagToKey: /* @__PURE__ */ new Map(),
+	windowsForSpec: /* @__PURE__ */ new Map()
+};
+/**
+* Reads the config's actors into the plan the run plays out, refusing anything
+* ambiguous rather than measuring under a guess.
+*
+* Every rejection here is one that would otherwise surface as "this spec
+* reached nothing": an identity that resolved to nothing matches no event, and
+* two entries resolving alike make each other's events unattributable.
+*/
+async function resolveActors(actors, cwd) {
+	const providers = Object.keys(actors);
+	if (providers.length === 0) return NO_ACTORS;
+	const known = new Set((await listAllSpecsWithSpecFile(cwd)).map(specKey));
+	const windows = [];
+	const tagToKey = /* @__PURE__ */ new Map();
+	const windowsForSpec = /* @__PURE__ */ new Map();
+	for (const provider of providers) for (const [identity, specs] of Object.entries(actors[provider] ?? {})) {
+		const key = `${provider}:${identity}`;
+		const refs = [...iterEnvRefNames(identity)];
+		if (refs.length === 0) throw new RunUsageError(`coverage.actors.${key} names an identity directly — write it as a variable (e.g. \${TEST_USER_ID}) so the value stays out of reports and the hub`);
+		const missing = refs.filter((name) => process.env[name] === void 0 || process.env[name] === "");
+		if (missing.length > 0) throw new RunUsageError(`coverage.actors.${key} needs ${missing.join(", ")}, which ${missing.length === 1 ? "is" : "are"} not set — an identity that resolves to nothing matches no event, and the specs under it would report reaching nothing`);
+		const tag = `${provider}:${resolveEnvRefs(identity)}`;
+		const clash = tagToKey.get(tag);
+		if (clash !== void 0) throw new RunUsageError(`coverage.actors.${key} and coverage.actors.${clash} name the same identity — their windows would overlap and neither one's events could be told apart`);
+		for (const member of specs) if (!known.has(member)) throw new RunUsageError(`coverage.actors.${key} lists "${member}", which is not a spec in this project`);
+		const window = {
+			key,
+			tag,
+			specs
+		};
+		windows.push(window);
+		tagToKey.set(tag, key);
+		for (const member of specs) {
+			const owned = windowsForSpec.get(member);
+			if (owned) owned.push(window);
+			else windowsForSpec.set(member, [window]);
+		}
+	}
+	return {
+		windows,
+		tagToKey,
+		windowsForSpec
+	};
+}
+/**
+* The serial groups the plan implies: two specs acting as one identity cannot
+* overlap, or neither could claim what happened while both were running.
+*/
+function actorGroups(plan) {
+	if (plan.windowsForSpec.size === 0) return () => [];
+	return (ref) => (plan.windowsForSpec.get(specKey(ref)) ?? []).map((window) => window.key);
+}
+//#endregion
+//#region src/coverage/contract.ts
+/**
+* The names and shapes ccqa agrees on with the instrumented application.
+*
+* Restated from `ccqa-tools`'s `wire.ts` rather than imported: the CLI must
+* not depend on the instrumentation SDK, which is installed in the application
+* under test and versioned separately. `contract.test.ts` asserts the two still
+* agree — a drift here reports "the spec reached no server code", which is
+* indistinguishable from the truth it is supposed to measure.
+*
+* Not named `wire.ts` like its counterpart, deliberately. The one moment anyone
+* opens both is while working out why the sink saw nothing, and two tabs with
+* one name is the wrong thing to hand them.
+*/
+/** Set on the browser by the acquisition engine, scoped to the instrumented origins. */
+const COVERAGE_COOKIE = "__ccqa_coverage";
+/** What the browser engine leaves for the run to read back at collect time. */
+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
+/**
+* Where instrumented application processes push what they reached. Why they
+* push rather than being scraped is ADR-0021.
+*
+* 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.
+*/
+/** What an instrumented process pushes, once a second. */
+const PushSchema = z.object({
+	protocol: z.literal(1),
+	pid: z.number(),
+	startedAt: z.number(),
+	unattributed: z.number(),
+	specs: z.record(z.string(), z.array(z.string())),
+	boot: z.array(z.string()),
+	uninstrumentedFiles: z.number().default(0),
+	uninstrumentedProcess: z.boolean().default(false),
+	droppedPushes: z.number().default(0),
+	actors: z.array(z.object({
+		tag: z.string(),
+		at: z.number(),
+		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 = "";
+	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. */
+	matched = /* @__PURE__ */ new Map();
+	/** Events from a declared identity that fell outside every turn it was given. */
+	outsideWindow = /* @__PURE__ */ new Map();
+	/**
+	* Events from identities this project never declared — other people using the
+	* same environment. Deduplicated by timestamp alone: the identity is dropped
+	* 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;
+		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;
+	}
+	/** 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;
+		for (const window of this.windows) {
+			if (window.tag !== tag || window.closedAt === void 0) continue;
+			latest = window.closedAt;
+		}
+		return latest;
+	}
+	/** Per window key, how many distinct events this spec was credited with. */
+	actorEventsFor(specId) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const [key, events] of this.matched.get(specId) ?? []) counts.set(key, events.size);
+		return counts;
+	}
+	/**
+	* Events from a declared identity that arrived outside its turns.
+	*
+	* Loud rather than silent: it means something other than this run drove that
+	* identity, and whatever it reached is missing from a spec that looks whole.
+	*/
+	outsideWindowEvents() {
+		return this.outsideWindow;
+	}
+	/** Events from identities this project never declared. Their reach belongs to nobody. */
+	unmappedActorEvents() {
+		return this.unmappedAt.size;
+	}
+	/** Executions that ran while `specId` was open but outside its context. */
+	unattributedFor(specId) {
+		const spec = this.specs.get(specId);
+		if (spec === void 0) return 0;
+		let total = 0;
+		for (const [process, baseline] of spec.baseline) total += Math.max(0, (this.processes.get(process)?.unattributed ?? 0) - baseline);
+		return total;
+	}
+	/**
+	* Files reached at module top level. Deliberately not folded into any spec:
+	* the first spec to import a module would otherwise own it, which makes a
+	* spec's result depend on the order the run happened to execute.
+	*/
+	boot() {
+		return this.bootFiles;
+	}
+	/** True once any instrumented process has reported — i.e. the server half is wired up. */
+	heardFromApplication() {
+		return this.pushesReceived > 0;
+	}
+	/**
+	* Specs some process attributed a file to.
+	*
+	* Distinct from `heardFromApplication`, which a process satisfies with its
+	* boot set alone. An application that reports but attributes nothing has the
+	* instrumentation working and the spec cookie not arriving — and that reads
+	* identically to a server that genuinely ran no code.
+	*/
+	attributedSpecs() {
+		return this.specs.size;
+	}
+	/** Pushes refused because they named a spec id this run never issued. */
+	rejectedPushes() {
+		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
+	* failed to rewrite when the process booted is still unrewritten now, so it
+	* is a standing condition of this run and not a past event.
+	*/
+	uninstrumentedFiles() {
+		let total = 0;
+		for (const report of this.processes.values()) total += report.uninstrumentedFiles;
+		return total;
+	}
+	/**
+	* Application processes that instrumented nothing at all. Kept apart from
+	* the file count because one of these hides every file the process ran, and
+	* folded together it would read as a single missing file.
+	*/
+	uninstrumentedProcesses() {
+		let total = 0;
+		for (const report of this.processes.values()) if (report.blind) total++;
+		return total;
+	}
+	/** Pushes the applications could not deliver during this run. Never seen here. */
+	droppedPushes() {
+		let total = 0;
+		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) {
+		const process = `${push.pid}:${push.startedAt}`;
+		const known = this.processes.get(process);
+		const previous = known?.unattributed ?? push.unattributed;
+		for (const file of push.boot) this.bootFiles.add(file);
+		for (const [specId, files] of Object.entries(push.specs)) {
+			if (!SPEC_ID_PATTERN.test(specId) || !this.issued.has(specId)) {
+				this.rejected++;
+				continue;
+			}
+			let spec = this.specs.get(specId);
+			if (spec === void 0) {
+				spec = {
+					files: /* @__PURE__ */ new Set(),
+					baseline: /* @__PURE__ */ new Map()
+				};
+				this.specs.set(specId, spec);
+			}
+			if (!spec.baseline.has(process)) spec.baseline.set(process, previous);
+			for (const file of files) spec.files.add(file);
+		}
+		for (const event of push.actors) this.attributeActorEvent(event, process, previous);
+		this.processes.set(process, {
+			unattributed: push.unattributed,
+			uninstrumentedFiles: push.uninstrumentedFiles,
+			blind: known?.blind === true || push.uninstrumentedProcess,
+			droppedBaseline: known?.droppedBaseline ?? push.droppedPushes,
+			droppedLatest: push.droppedPushes
+		});
+		this.pushesReceived++;
+	}
+	/**
+	* Decides which spec, if any, an identity's work belongs to.
+	*
+	* `at` is when the work was first asked for, not when it ran — an activity a
+	* queue picks up minutes later still carries the instant that caused it, so a
+	* slow tail lands in the turn that started it rather than the one running now.
+	*/
+	attributeActorEvent(event, process, previous) {
+		const key = this.tagToKey.get(event.tag);
+		if (key === void 0) {
+			this.unmappedAt.add(event.at);
+			return;
+		}
+		const window = this.windowAt(event.tag, event.at);
+		if (window === void 0) {
+			this.outsideWindow.set(key, (this.outsideWindow.get(key) ?? 0) + 1);
+			return;
+		}
+		const spec = this.specs.get(window.specId) ?? {
+			files: /* @__PURE__ */ new Set(),
+			baseline: /* @__PURE__ */ new Map()
+		};
+		this.specs.set(window.specId, spec);
+		if (!spec.baseline.has(process)) spec.baseline.set(process, previous);
+		for (const file of event.files) spec.files.add(file);
+		let byKey = this.matched.get(window.specId);
+		if (byKey === void 0) {
+			byKey = /* @__PURE__ */ new Map();
+			this.matched.set(window.specId, byKey);
+		}
+		const events = byKey.get(key) ?? /* @__PURE__ */ new Set();
+		events.add(`${event.tag} ${event.at}`);
+		byKey.set(key, events);
+	}
+	/**
+	* 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
+	* identity and this reaches half of it.
+	*/
+	windowAt(tag, at) {
+		let found;
+		for (const window of this.windows) {
+			if (window.tag !== tag) continue;
+			if (at < window.openedAt - 1500) continue;
+			if (window.closedAt !== void 0 && at > window.closedAt + 1500) continue;
+			found = window;
+		}
+		return found;
+	}
+};
+function formatHost(host) {
+	return host.includes(":") ? `[${host}]` : host;
+}
+async function readBody$1(request) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of request) {
+		const buffer = chunk;
+		size += buffer.length;
+		if (size > MAX_BODY_BYTES$6) throw new Error("coverage push too large");
+		chunks.push(buffer);
+	}
+	return (chunks.length === 1 ? chunks[0] : Buffer.concat(chunks)).toString("utf8");
+}
+//#endregion
+//#region src/coverage/frontend/source-map.ts
+/** Parses a source map JSON string. Returns undefined for anything unusable. */
+function parseSourceMap(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const candidate = parsed;
+	if (candidate.sections !== void 0) return void 0;
+	if (candidate.version !== 3) return void 0;
+	if (typeof candidate.mappings !== "string") return void 0;
+	if (!Array.isArray(candidate.sources)) return void 0;
+	return candidate;
+}
+const SOURCE_MAPPING_URL_RE = /\/\/[#@][ \t]*sourceMappingURL=([^\s]+)/g;
+/** Extracts the `//# sourceMappingURL=` value from generated code, if present. */
+function readSourceMappingUrl(code) {
+	let last;
+	for (const match of code.matchAll(SOURCE_MAPPING_URL_RE)) last = match[1];
+	return last;
+}
+const DATA_URL_RE = /^data:([^,]*),(.*)$/s;
+/** Decodes a `data:` source map URL into its JSON text. Returns undefined otherwise. */
+function decodeInlineSourceMap(url) {
+	const match = DATA_URL_RE.exec(url);
+	if (!match) return void 0;
+	const [, meta, payload] = match;
+	if (meta === void 0 || payload === void 0 || !/^application\/json/.test(meta)) return void 0;
+	try {
+		return /;base64$/.test(meta) ? Buffer.from(payload, "base64").toString("utf-8") : decodeURIComponent(payload);
+	} catch {
+		return;
+	}
+}
+function joinSourceRoot(root, source) {
+	if (typeof root !== "string" || root === "") return source;
+	return root.endsWith("/") ? `${root}${source}` : `${root}/${source}`;
+}
+const VLQ_CONTINUATION_BIT = 32;
+const VLQ_VALUE_MASK = 31;
+const VLQ_SHIFT = 5;
+const BASE64_INDEX = new Map(Array.from("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/").map((ch, i) => [ch, i]));
+/**
+* Decodes one VLQ value starting at `pos`. Uses multiplication rather than
+* bit shifts so values beyond 32 bits (large generated files) decode
+* correctly — `<<` in JS truncates to a signed 32-bit int.
+*/
+function decodeVlq(mappings, pos) {
+	let result = 0;
+	let shift = 0;
+	let i = pos;
+	for (;;) {
+		const char = mappings[i];
+		if (char === void 0) throw new Error("truncated VLQ in mappings");
+		const digit = BASE64_INDEX.get(char);
+		if (digit === void 0) throw new Error(`invalid base64 digit in mappings: ${char}`);
+		i += 1;
+		result += (digit & VLQ_VALUE_MASK) * 2 ** shift;
+		if ((digit & VLQ_CONTINUATION_BIT) === 0) break;
+		shift += VLQ_SHIFT;
+	}
+	const negative = result % 2 === 1;
+	const magnitude = Math.floor(result / 2);
+	return {
+		value: negative ? -magnitude : magnitude,
+		next: i
+	};
+}
+function isSegmentBoundary(mappings, pos) {
+	return pos >= mappings.length || mappings[pos] === "," || mappings[pos] === ";";
+}
+/**
+* Decodes `mappings` into segments that carry source info (the 4- and
+* 5-field kind). 1-field segments (generated code with no original source)
+* are skipped: they can never contribute a source, so keeping them around
+* would only cost time later.
+*/
+function decodeMappings(mappings) {
+	const segments = [];
+	const len = mappings.length;
+	let pos = 0;
+	let generatedLine = 0;
+	let generatedColumn = 0;
+	let sourceIndex = 0;
+	let sourceLine = 0;
+	let sourceColumn = 0;
+	while (pos < len) {
+		const char = mappings[pos];
+		if (char === ";") {
+			generatedLine += 1;
+			generatedColumn = 0;
+			pos += 1;
+			continue;
+		}
+		if (char === ",") {
+			pos += 1;
+			continue;
+		}
+		const col = decodeVlq(mappings, pos);
+		generatedColumn += col.value;
+		pos = col.next;
+		if (isSegmentBoundary(mappings, pos)) continue;
+		const srcIndex = decodeVlq(mappings, pos);
+		sourceIndex += srcIndex.value;
+		pos = srcIndex.next;
+		const srcLine = decodeVlq(mappings, pos);
+		sourceLine += srcLine.value;
+		pos = srcLine.next;
+		const srcColumn = decodeVlq(mappings, pos);
+		sourceColumn += srcColumn.value;
+		pos = srcColumn.next;
+		segments.push({
+			generatedLine,
+			generatedColumn,
+			sourceIndex
+		});
+		if (!isSegmentBoundary(mappings, pos)) pos = decodeVlq(mappings, pos).next;
+	}
+	return segments;
+}
+function prepareSourceMap(map, generatedCode) {
+	const lineStarts = computeLineStarts(generatedCode);
+	const positions = [];
+	let segments;
+	try {
+		segments = decodeMappings(map.mappings);
+	} catch {
+		return;
+	}
+	for (const segment of segments) {
+		const lineStart = lineStarts[segment.generatedLine];
+		if (lineStart === void 0) continue;
+		positions.push({
+			offset: lineStart + segment.generatedColumn,
+			sourceIndex: segment.sourceIndex
+		});
+	}
+	positions.sort((a, b) => a.offset - b.offset);
+	return {
+		positions,
+		paths: map.sources.map((source) => source === null ? void 0 : joinSourceRoot(map.sourceRoot, source))
+	};
+}
+/** Start offset (UTF-16 code units) of each line in `code`, index 0 for line 0. */
+function computeLineStarts(code) {
+	const starts = [0];
+	for (let i = 0; i < code.length; i++) if (code.charCodeAt(i) === 10) starts.push(i + 1);
+	return starts;
+}
+/** Index of the first mapped position at or after `offset`. */
+function lowerBound(positions, offset) {
+	let lo = 0;
+	let hi = positions.length;
+	while (lo < hi) {
+		const mid = lo + hi >>> 1;
+		if ((positions[mid]?.offset ?? 0) < offset) lo = mid + 1;
+		else hi = mid;
+	}
+	return lo;
+}
+/**
+* Which of `prepared`'s sources the covered ranges touch.
+*
+* Every range is walked even once all sources are known, because a range that
+* maps nowhere has to be counted — dropping it would turn an unknown into a
+* silent "never reached".
+*/
+function resolveCovered(prepared, ranges) {
+	const seen = new Uint8Array(prepared.paths.length);
+	const sources = [];
+	let unmappedRanges = 0;
+	for (const range of ranges) {
+		let matched = false;
+		for (let i = lowerBound(prepared.positions, range.startOffset); i < prepared.positions.length; i++) {
+			const position = prepared.positions[i];
+			if (position === void 0 || position.offset >= range.endOffset) break;
+			matched = true;
+			if (seen[position.sourceIndex] === 1) continue;
+			seen[position.sourceIndex] = 1;
+			const path = prepared.paths[position.sourceIndex];
+			if (path !== void 0) sources.push(path);
+		}
+		if (!matched) unmappedRanges += 1;
+	}
+	return {
+		sources,
+		unmappedRanges
+	};
+}
+//#endregion
+//#region src/coverage/frontend/source-path.ts
+/**
+* Turns the source names a bundler writes into `sources` back into paths a
+* reader can find in the project.
+*
+* Bundlers namespace those entries — `webpack://_N_E/./src/a.ts`,
+* `webpack-internal:///(pages-dir-browser)/./src/a.ts` — and some write the
+* absolute path the build machine used. None of the forms is a project path on
+* its own.
+*
+* Anything that still resolves outside the root is dropped rather than
+* coerced. A framework's own runtime arrives as `../../../node_modules/...`,
+* and flattening those leading segments would invent a path that exists
+* nowhere and report the framework as project code nobody has a test for.
+*
+* Why a reason and not just `undefined`: dependency code is dropped on purpose
+* and a name nobody could resolve is a hole in the measurement. Reported as one
+* number the two are indistinguishable, and since dependencies dominate it by
+* orders of magnitude, the number reads as noise — which is how a real hole
+* goes unnoticed inside it.
+*/
+/** Dependency code is dropped: an unreached library file is not a missing test. */
+const VENDOR = /(^|\/)node_modules\//;
+/** `(rsc)`, `(pages-dir-browser)`, ... — which build layer, not part of the path. */
+const LAYER = /^\([^)]*\)\//;
+const DEPENDENCY = { kind: "dependency" };
+const UNRESOLVED = { kind: "unresolved" };
+/** `absolute` as a posix path under `root`, or undefined when it is not under it. */
+function toProjectRelative(root, absolute) {
+	const rel = relative(root, absolute).split(sep).join("/");
+	return rel === "" || rel.startsWith("..") ? void 0 : rel;
+}
+function normalizeSourcePath(raw, roots) {
+	if (VENDOR.test(raw)) return DEPENDENCY;
+	let path = raw;
+	const scheme = path.indexOf("://");
+	if (scheme >= 0) {
+		const afterScheme = path.slice(scheme + 3);
+		const slash = afterScheme.indexOf("/");
+		const from = path.startsWith("file:") ? slash : slash + 1;
+		path = slash < 0 ? afterScheme : afterScheme.slice(from);
+	}
+	path = posix.normalize(path.replace(LAYER, ""));
+	if (path === "" || path === ".") return UNRESOLVED;
+	if (path.startsWith("<") || path.startsWith("[")) return UNRESOLVED;
+	const absolute = path.startsWith("/") ? path : resolve(roots.base, path);
+	const rel = toProjectRelative(roots.root, absolute);
+	if (rel === void 0) return UNRESOLVED;
+	return VENDOR.test(rel) ? DEPENDENCY : {
+		kind: "project",
+		path: rel
+	};
+}
+//#endregion
+//#region src/coverage/frontend/build-output.ts
+/**
+* Follows a build output back to the source it was compiled from.
+*
+* A workspace package is consumed through its published entry, so a bundler
+* names it `packages/x/dist/index.mjs`. That file exists and is genuinely what
+* ran, but nobody edits it — reported as-is it becomes an entry in the
+* untested-file list that no test could ever cover.
+*
+* Only a 1:1 build is followed: one output per input, which is what an
+* unbundled compile produces and what its map states in a single `sources`
+* entry. A bundle's map lists everything that went into it and cannot say
+* which of them the file "is", so those are left pointing at the output.
+*
+* The server half follows the same 1:1 rule at load time, in `ccqa-tools`'s
+* `instrument/origin.ts`. It reaches further: it already holds the code, so it
+* can read an inline map, where this side only reads a sibling `.map`. A
+* package built with an inline map is therefore reported under its source by
+* the server and under its build output by the browser.
+*/
+/**
+* The project-relative source `path` was built from, or undefined to keep
+* `path` as it is.
+*
+* Only the sibling `<file>.map` convention is read. Finding an inline map means
+* reading the whole build output on the chance it carries one, which is a lot
+* of I/O for a case library builds rarely emit.
+*/
+function sourceBehindBuildOutput(path, root) {
+	const output = join(root, path);
+	let json;
+	try {
+		json = readFileSync(`${output}.map`, "utf8");
+	} catch {
+		return;
+	}
+	const map = parseSourceMap(json);
+	if (map === void 0 || map.sources.length !== 1) return void 0;
+	const source = map.sources[0];
+	if (typeof source !== "string" || source === "") return void 0;
+	const absolute = resolve(dirname(output), map.sourceRoot ?? "", source);
+	const rel = toProjectRelative(root, absolute);
+	if (rel === void 0) return void 0;
+	return existsSync(absolute) ? rel : void 0;
+}
+//#endregion
+//#region src/coverage/frontend/resolve.ts
+/**
+* What counts as a source file. Shared with the universe enumeration
+* (universe.ts): the denominator must use the same notion of "source file"
+* as the reached side, or "uncovered" drifts as one definition evolves.
+*/
+const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
+var FrontendResolution = class {
+	specId;
+	coverageDir;
+	roots;
+	fetchText;
+	warn;
+	files = /* @__PURE__ */ new Set();
+	/**
+	* Resolution, memoised. `roots` is fixed for the session and V8 re-reports
+	* every script it has seen on each take, so both answers below are otherwise
+	* recomputed for the whole page at every navigation.
+	*/
+	classified = /* @__PURE__ */ new Map();
+	/** Project path -> the source it was built from, or itself. */
+	sources = /* @__PURE__ */ new Map();
+	/** Decoded once per script and kept; the raw map is dropped with it. */
+	maps = /* @__PURE__ */ new Map();
+	unmappedScripts = 0;
+	unmappedRanges = 0;
+	unresolvedSources = 0;
+	excludedDependencies = 0;
+	/** Set once collection dies: everything after this point was never seen. */
+	stopped = false;
+	/** What the last write held, so an unchanged flush does not rewrite the file. */
+	written = "";
+	dirReady = false;
+	constructor(opts) {
+		this.specId = opts.specId;
+		this.coverageDir = opts.coverageDir;
+		this.roots = opts.roots;
+		this.fetchText = opts.fetchText;
+		this.warn = opts.warn;
+	}
+	async absorb(script) {
+		if (script.ranges.length === 0) return;
+		const direct = this.bundlerModulePath(script.url);
+		if (direct !== void 0) {
+			this.files.add(this.sourceOf(direct));
+			return;
+		}
+		const prepared = await this.loadSourceMap(script);
+		if (prepared === void 0) {
+			this.unmappedScripts++;
+			return;
+		}
+		const resolved = resolveCovered(prepared, [...script.ranges]);
+		this.unmappedRanges += resolved.unmappedRanges;
+		for (const raw of resolved.sources) {
+			const source = this.classify(raw);
+			if (source.kind === "unresolved") this.unresolvedSources++;
+			else if (source.kind === "dependency") this.excludedDependencies++;
+			else this.files.add(this.sourceOf(source.path));
+		}
+	}
+	/** Collection died mid-spec; the shorter file set must say so. */
+	markStopped() {
+		this.stopped = true;
+		this.flush();
+	}
+	/**
+	* Written after every batch that changed something, not only at the end: a
+	* spec that fails mid-way still leaves everything it reached, and a failing
+	* spec is exactly when the reader wants to know what ran.
+	*/
+	flush() {
+		const payload = {
+			specId: this.specId,
+			files: [...this.files].sort(),
+			unmappedScripts: this.unmappedScripts,
+			unmappedRanges: this.unmappedRanges,
+			unresolvedSources: this.unresolvedSources,
+			excludedDependencies: this.excludedDependencies,
+			stopped: this.stopped
+		};
+		const text = `${JSON.stringify(payload, null, 2)}\n`;
+		if (text === this.written) return;
+		try {
+			if (!this.dirReady) {
+				mkdirSync(this.coverageDir, { recursive: true });
+				this.dirReady = true;
+			}
+			writeFileSync(join(this.coverageDir, FRONTEND_COVERAGE_FILE), text, "utf8");
+			this.written = text;
+		} catch (error) {
+			this.warn(`could not write ${FRONTEND_COVERAGE_FILE} (${message$2(error)})`);
+		}
+	}
+	classify(raw) {
+		const known = this.classified.get(raw);
+		if (known !== void 0) return known;
+		const source = normalizeSourcePath(raw, this.roots);
+		this.classified.set(raw, source);
+		return source;
+	}
+	sourceOf(path) {
+		const known = this.sources.get(path);
+		if (known !== void 0) return known;
+		const source = sourceBehindBuildOutput(path, this.roots.root) ?? path;
+		this.sources.set(path, source);
+		return source;
+	}
+	/**
+	* Restricted to bundler schemes: a real `http(s)` URL is a built asset, and
+	* its path says nothing about the sources inside it.
+	*/
+	bundlerModulePath(url) {
+		if (url === "" || /^https?:/i.test(url) || !url.includes("://")) return void 0;
+		const source = this.classify(url);
+		if (source.kind !== "project" || !SOURCE_FILE.test(source.path)) return void 0;
+		return source.path;
+	}
+	async loadSourceMap(script) {
+		const cached = this.maps.get(script.url);
+		if (cached !== void 0) return cached ?? void 0;
+		const prepared = await this.fetchSourceMap(script);
+		this.maps.set(script.url, prepared ?? null);
+		return prepared;
+	}
+	async fetchSourceMap(script) {
+		const source = await script.source();
+		if (source === void 0) return void 0;
+		const reference = readSourceMappingUrl(source);
+		if (reference === void 0) return void 0;
+		let json = decodeInlineSourceMap(reference);
+		if (json === void 0) {
+			let target;
+			try {
+				target = new URL(reference, script.url).toString();
+			} catch {
+				return;
+			}
+			json = await this.fetchText(target);
+			if (json === void 0) return void 0;
+		}
+		const map = parseSourceMap(json);
+		if (map === void 0) return void 0;
+		return prepareSourceMap(map, source);
+	}
+};
+function message$2(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/coverage/browser/cdp.ts
+/**
+* Minimal Chrome DevTools Protocol client, dependency-free on purpose.
+*
+* Coverage acquisition speaks a handful of domains over one transport, which
+* is not enough to justify a protocol library in a published CLI. The
+* transport is the `WebSocket` global — stable since Node 22 — so availability
+* is gated with an explicit error instead of a package.json engines bump:
+* everything else in ccqa still runs on 20, and only `--coverage`'s browser
+* half needs more.
+*/
+var CdpError = class extends Error {};
+/**
+* Wire-level trace, for diagnosing the engine against a live browser:
+* `CCQA_CDP_TRACE=1` writes to stderr, `CCQA_CDP_TRACE_FILE=<path>` to a file.
+* The file is the usable one during a live run, whose stderr already carries
+* the agent's narration.
+*/
+const TRACE_FILE = process.env.CCQA_CDP_TRACE_FILE;
+const TRACE = process.env.CCQA_CDP_TRACE === "1" || TRACE_FILE !== void 0;
+function trace(direction, text) {
+	if (!TRACE) return;
+	const line = `[cdp ${direction}] ${Date.now() % 1e5} ${text}\n`;
+	if (TRACE_FILE === void 0) {
+		process.stderr.write(line);
+		return;
+	}
+	try {
+		appendFileSync(TRACE_FILE, line);
+	} catch {}
+}
+/** Throws with the actual requirement when the runtime cannot open the socket. */
+function requireWebSocket() {
+	if (typeof WebSocket === "undefined") throw new CdpError(`browser coverage needs the WebSocket global (node 22+); this is node ${process.version}`);
+}
+/**
+* Resolves whatever a target hands us — `host:port`, an `http://` endpoint, or
+* a ws URL — to the **browser-level** ws endpoint. A page-level ws URL is not
+* enough: auto-attach has to be armed at the browser to see every page and
+* every popup, so a page URL is reduced to its host and re-resolved through
+* `/json/version` like the rest.
+*/
+async function browserWebSocketUrl(endpoint) {
+	const trimmed = endpoint.trim();
+	if (/^wss?:\/\//i.test(trimmed) && trimmed.includes("/devtools/browser/")) return trimmed;
+	let host;
+	try {
+		host = new URL(/^[a-z+]+:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`).host;
+	} catch {
+		throw new CdpError(`not a CDP endpoint: "${endpoint}"`);
+	}
+	const version = await fetch(`http://${host}/json/version`).catch((error) => {
+		throw new CdpError(`CDP endpoint ${host} did not answer /json/version (${message$1(error)})`);
+	});
+	if (!version.ok) throw new CdpError(`CDP endpoint ${host} answered ${version.status}`);
+	const body = await version.json();
+	if (typeof body.webSocketDebuggerUrl !== "string") throw new CdpError(`CDP endpoint ${host} reported no webSocketDebuggerUrl`);
+	return body.webSocketDebuggerUrl;
+}
+var CdpClient = class CdpClient {
+	ws;
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Map();
+	closeHandlers = /* @__PURE__ */ new Set();
+	constructor(ws) {
+		this.ws = ws;
+		ws.addEventListener("message", (event) => this.receive(String(event.data)));
+		ws.addEventListener("close", () => this.drop("connection closed"));
+		ws.addEventListener("error", () => this.drop("connection error"));
+	}
+	static async connect(wsUrl) {
+		requireWebSocket();
+		const ws = new WebSocket(wsUrl);
+		await new Promise((resolve, reject) => {
+			ws.addEventListener("open", () => resolve(), { once: true });
+			ws.addEventListener("error", () => reject(new CdpError(`could not connect to ${wsUrl}`)), { once: true });
+		});
+		return new CdpClient(ws);
+	}
+	send(method, params, sessionId) {
+		if (this.ws.readyState !== WebSocket.OPEN) return Promise.reject(new CdpError(`${method}: connection closed`));
+		const id = this.nextId++;
+		const promise = new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject,
+				method
+			});
+		});
+		trace("->", `#${id} ${method} sid:${shortId(sessionId)}`);
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params: params ?? {},
+			sessionId
+		}));
+		return promise;
+	}
+	on(method, handler) {
+		let set = this.listeners.get(method);
+		if (set === void 0) {
+			set = /* @__PURE__ */ new Set();
+			this.listeners.set(method, set);
+		}
+		set.add(handler);
+	}
+	onClose(handler) {
+		this.closeHandlers.add(handler);
+	}
+	close() {
+		try {
+			this.ws.close();
+		} catch {}
+	}
+	receive(data) {
+		let parsed;
+		try {
+			parsed = JSON.parse(data);
+		} catch {
+			trace("rx", `unparseable frame: ${data.slice(0, 60)}`);
+			return;
+		}
+		if (parsed.id !== void 0) {
+			const waiting = this.pending.get(parsed.id);
+			if (waiting === void 0) return;
+			this.pending.delete(parsed.id);
+			if (parsed.error !== void 0) {
+				trace("<-", `#${parsed.id} ${waiting.method} ERROR ${parsed.error.message ?? "?"}`);
+				waiting.reject(new CdpError(`${waiting.method}: ${parsed.error.message ?? "CDP error"}`));
+			} else {
+				trace("<-", `#${parsed.id} ${waiting.method} ok`);
+				waiting.resolve(parsed.result ?? {});
+			}
+			return;
+		}
+		if (parsed.method !== void 0) {
+			trace("ev", describeEvent(parsed.method, parsed.params ?? {}, parsed.sessionId));
+			const set = this.listeners.get(parsed.method);
+			if (set === void 0) return;
+			for (const handler of set) try {
+				handler(parsed.params ?? {}, parsed.sessionId);
+			} catch {}
+		}
+	}
+	drop(reason) {
+		for (const waiting of this.pending.values()) waiting.reject(new CdpError(`${waiting.method}: ${reason}`));
+		this.pending.clear();
+		for (const handler of this.closeHandlers) try {
+			handler();
+		} catch {}
+		this.closeHandlers.clear();
+	}
+};
+/** Attach events carry the one thing a method name cannot: what was handed over. */
+function describeEvent(method, params, sessionId) {
+	const base = `${method} sid:${shortId(sessionId)}`;
+	if (method !== "Target.attachedToTarget") return base;
+	const info = params;
+	return `${base} child:${shortId(info.sessionId)} ${info.targetInfo?.type ?? "?"} ${info.targetInfo?.url?.slice(0, 40) ?? "?"} wait:${String(info.waitingForDebugger)}`;
+}
+function shortId(sessionId) {
+	return sessionId?.slice(0, 6) ?? "-";
+}
+function message$1(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/coverage/browser/engine.ts
+const TAKE_INTERVAL_MS = 400;
+/** How long a navigation may hold takes before the guard assumes a lost event. */
+const NAVIGATION_GUARD_MS = 5e3;
+/** How long `stop()` waits for the final take before declaring the tail lost. */
+const STOP_TAKE_TIMEOUT_MS = 2e3;
+/** The browser's own chrome. Nothing there is the application under test. */
+const INTERNAL_URL = /^(chrome|chrome-untrusted|chrome-extension|devtools):/;
+async function startBrowserCoverage(opts) {
+	const client = await (opts.connect ?? ((wsUrl) => CdpClient.connect(wsUrl)))(await browserWebSocketUrl(opts.cdpUrl));
+	const engine = new Engine(client, opts);
+	try {
+		await engine.arm();
+	} catch (error) {
+		client.close();
+		throw error;
+	}
+	return engine;
+}
+var Engine = class {
+	client;
+	opts;
+	resolution;
+	pages = /* @__PURE__ */ new Map();
+	/**
+	* Targets already armed, by target id. Browser-level auto-attach reports
+	* existing targets too, so the explicit sweep for them can hand over the
+	* same target a second time, and a page armed through two sessions is taken
+	* twice for one set of counters.
+	*/
+	armedTargets = /* @__PURE__ */ new Set();
+	/** Sessions whose take failure was already said; see enqueueTake. */
+	warnedTakeSessions = /* @__PURE__ */ new Set();
+	cookies;
+	timer;
+	stopped = false;
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
+		this.cookies = opts.origins.map((url) => ({
+			name: COVERAGE_COOKIE,
+			value: opts.specId,
+			url
+		}));
+		this.resolution = new FrontendResolution({
+			specId: opts.specId,
+			coverageDir: opts.coverageDir,
+			roots: opts.roots,
+			fetchText: (url) => this.fetchThroughBrowser(url),
+			warn: opts.warn
+		});
+	}
+	async arm() {
+		this.client.on("Target.attachedToTarget", (params) => {
+			this.onAttached(params);
+		});
+		this.client.on("Target.detachedFromTarget", (params) => {
+			const sessionId = params.sessionId;
+			if (sessionId === void 0) return;
+			const page = this.pages.get(sessionId);
+			this.pages.delete(sessionId);
+			if (page !== void 0) this.armedTargets.delete(page.targetId);
+		});
+		this.client.on("Page.frameStartedNavigating", (params, sessionId) => {
+			if (sessionId === void 0) return;
+			const page = this.pages.get(sessionId);
+			if (page === void 0 || !this.isMainFrame(page, params.frameId)) return;
+			page.navigatingSince = Date.now();
+		});
+		this.client.on("Page.frameNavigated", (params, sessionId) => {
+			if (sessionId === void 0) return;
+			const page = this.pages.get(sessionId);
+			if (page === void 0) return;
+			const frame = params.frame;
+			if (frame?.parentId !== void 0) return;
+			if (frame?.id !== void 0) page.mainFrameId = frame.id;
+			page.navigatingSince = void 0;
+			this.setCookies(page);
+		});
+		this.client.on("Page.frameStoppedLoading", (params, sessionId) => {
+			if (sessionId === void 0) return;
+			const page = this.pages.get(sessionId);
+			if (page === void 0 || !this.isMainFrame(page, params.frameId)) return;
+			page.navigatingSince = void 0;
+		});
+		this.client.onClose(() => {
+			if (!this.stopped && this.pages.size > 0) this.resolution.markStopped();
+			this.pages.clear();
+			if (this.timer !== void 0) clearInterval(this.timer);
+		});
+		await this.client.send("Target.setAutoAttach", {
+			autoAttach: true,
+			waitForDebuggerOnStart: false,
+			flatten: true,
+			filter: [{ type: "tab" }, { exclude: true }]
+		});
+		const existing = await this.client.send("Target.getTargets", { filter: [{ type: "tab" }] });
+		for (const info of existing.targetInfos) {
+			if (this.armedTargets.has(info.targetId)) continue;
+			await this.client.send("Target.attachToTarget", {
+				targetId: info.targetId,
+				flatten: true
+			}).catch(() => void 0);
+		}
+		this.timer = setInterval(() => {
+			for (const page of this.pages.values()) {
+				this.enqueueTake(page.sessionId);
+				if (page.armed) this.setCookies(page);
+			}
+		}, TAKE_INTERVAL_MS);
+		this.timer.unref?.();
+	}
+	async stop() {
+		this.stopped = true;
+		if (this.timer !== void 0) clearInterval(this.timer);
+		let sawEverything = ![...this.pages.values()].some((page) => !page.armed);
+		for (const page of this.pages.values()) page.navigatingSince = void 0;
+		const takes = Promise.all([...this.pages.keys()].map((sessionId) => this.enqueueTake(sessionId)));
+		if (await Promise.race([takes.then(() => false), new Promise((resolve) => setTimeout(resolve, STOP_TAKE_TIMEOUT_MS, true))])) {
+			this.opts.warn("the final coverage take did not answer; the spec's tail went unseen");
+			sawEverything = false;
+		}
+		if (!sawEverything) this.resolution.markStopped();
+		this.resolution.flush();
+		this.client.close();
+	}
+	async onAttached(params) {
+		const { sessionId, targetInfo } = params;
+		const release = () => params.waitingForDebugger ? this.client.send("Runtime.runIfWaitingForDebugger", {}, sessionId).catch(() => void 0) : Promise.resolve();
+		if (this.stopped) {
+			await release();
+			return;
+		}
+		if (targetInfo.type === "tab") {
+			if (!this.armedTargets.has(targetInfo.targetId)) {
+				this.armedTargets.add(targetInfo.targetId);
+				await this.client.send("Target.setAutoAttach", {
+					autoAttach: true,
+					waitForDebuggerOnStart: true,
+					flatten: true
+				}, sessionId).catch(() => void 0);
+			}
+			await release();
+			return;
+		}
+		const measurable = (targetInfo.type === "page" || targetInfo.type === "iframe") && !INTERNAL_URL.test(targetInfo.url);
+		if (!measurable || this.armedTargets.has(targetInfo.targetId)) {
+			await release();
+			if (measurable) await this.client.send("Target.detachFromTarget", { sessionId }).catch(() => void 0);
+			return;
+		}
+		this.armedTargets.add(targetInfo.targetId);
+		const page = {
+			sessionId,
+			targetId: targetInfo.targetId,
+			armed: false,
+			navigatingSince: void 0,
+			mainFrameId: void 0,
+			pending: Promise.resolve()
+		};
+		this.pages.set(sessionId, page);
+		const sent = [
+			this.client.send("Profiler.enable", {}, sessionId),
+			this.client.send("Profiler.startPreciseCoverage", {
+				callCount: true,
+				detailed: true
+			}, sessionId).then(() => {
+				page.armed = true;
+			}),
+			this.client.send("Page.enable", {}, sessionId),
+			this.setCookies(page)
+		];
+		await release();
+		const failed = (await Promise.allSettled(sent)).find((r) => r.status === "rejected");
+		if (failed !== void 0) this.opts.warn(`could not arm a browser target (${message(failed.reason)})`);
+	}
+	setCookies(page) {
+		if (this.cookies.length === 0) return Promise.resolve();
+		return this.client.send("Network.setCookies", { cookies: this.cookies }, page.sessionId).catch((error) => {
+			this.opts.warn(`could not attach the spec cookie (${message(error)})`);
+		});
+	}
+	enqueueTake(sessionId) {
+		const page = this.pages.get(sessionId);
+		if (page === void 0 || !page.armed) return Promise.resolve();
+		if (page.navigatingSince !== void 0) {
+			if (Date.now() - page.navigatingSince < NAVIGATION_GUARD_MS) return Promise.resolve();
+			page.navigatingSince = void 0;
+		}
+		page.pending = page.pending.then(async () => {
+			const taken = await this.client.send("Profiler.takePreciseCoverage", {}, sessionId);
+			await this.absorbEntries(taken.result);
+		}).catch((error) => {
+			if (this.stopped || this.warnedTakeSessions.has(sessionId)) return;
+			this.warnedTakeSessions.add(sessionId);
+			if (this.pages.has(sessionId)) this.opts.warn(`a coverage take failed and later ones may too (${message(error)})`);
+		});
+		return page.pending;
+	}
+	/** Face value until the main frame's id is known; see the arm() comment. */
+	isMainFrame(page, frameId) {
+		return page.mainFrameId === void 0 || frameId === void 0 || frameId === page.mainFrameId;
+	}
+	async absorbEntries(entries) {
+		let changed = false;
+		for (const entry of entries) {
+			const ranges = [];
+			for (const fn of entry.functions) for (const range of fn.ranges) if (range.count > 0) ranges.push({
+				startOffset: range.startOffset,
+				endOffset: range.endOffset
+			});
+			if (ranges.length === 0) continue;
+			const script = {
+				url: entry.url,
+				ranges,
+				source: async () => /^https?:/i.test(entry.url) ? this.fetchThroughBrowser(entry.url) : void 0
+			};
+			await this.resolution.absorb(script);
+			changed = true;
+		}
+		if (changed) this.resolution.flush();
+	}
+	/**
+	* Fetches through a page where there is one, so the request carries the
+	* session's cookies (see `FrontendResolutionOptions.fetchText`).
+	*/
+	async fetchThroughBrowser(url) {
+		const [page] = this.pages.values();
+		if (page !== void 0) try {
+			const tree = await this.client.send("Page.getFrameTree", {}, page.sessionId);
+			const loaded = await this.client.send("Network.loadNetworkResource", {
+				frameId: tree.frameTree.frame.id,
+				url,
+				options: {
+					disableCache: false,
+					includeCredentials: true
+				}
+			}, page.sessionId);
+			if (loaded.resource.success && loaded.resource.stream !== void 0) return await this.readStream(loaded.resource.stream, page.sessionId);
+		} catch {}
+		try {
+			const response = await fetch(url);
+			if (!response.ok) return void 0;
+			return await response.text();
+		} catch {
+			return;
+		}
+	}
+	async readStream(handle, sessionId) {
+		const parts = [];
+		for (;;) {
+			const chunk = await this.client.send("IO.read", { handle }, sessionId);
+			parts.push(chunk.base64Encoded === true ? Buffer.from(chunk.data, "base64").toString("utf8") : chunk.data);
+			if (chunk.eof) break;
+		}
+		await this.client.send("IO.close", { handle }, sessionId).catch(() => void 0);
+		return parts.join("");
+	}
+};
+function message(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/coverage/universe.ts
+/**
+* Directories that hold generated or vendored code, not sources anyone writes
+* tests against. Dot-directories (.git, .next, .turbo…) are skipped wholesale.
+*/
+const SKIP_DIRS = new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"coverage"
+]);
+/**
+* More files than any human will triage as a gap list — a ceiling this high is
+* only reached when `coverage.include` points at something like a whole
+* monorepo, and a truncated universe would silently misreport "uncovered".
+*/
+const MAX_FILES = 2e4;
+async function enumerateUniverse(root, include, warn) {
+	const files = [];
+	const dirs = [...new Set(include.map(normalizeDir))];
+	for (const dir of dirs) {
+		await walk(dir === "" ? root : join(root, dir), dir, files, warn);
+		if (files.length > MAX_FILES) {
+			warn(`coverage.include matched more than ${MAX_FILES} files — the universe was omitted rather than truncated. Narrow coverage.include to the directories the measurement covers.`);
+			return;
+		}
+	}
+	if (files.length === 0) {
+		warn("coverage.include matched no files — the universe was omitted. Check that the directories exist relative to coverage.projectRoot.");
+		return;
+	}
+	files.sort();
+	return {
+		include: [...include],
+		files
+	};
+}
+function normalizeDir(dir) {
+	const posix = dir.replaceAll("\\", "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+	return posix === "." ? "" : posix;
+}
+async function walk(abs, rel, out, warn) {
+	let entries;
+	try {
+		entries = await readdir(abs, { withFileTypes: true });
+	} catch (err) {
+		warn(`coverage universe: cannot read ${abs} (${err.code ?? String(err)}) — its files are not counted.`);
+		return;
+	}
+	for (const entry of entries) if (entry.isDirectory()) {
+		if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+		await walk(join(abs, entry.name), rel === "" ? entry.name : `${rel}/${entry.name}`, out, warn);
+	} else if (entry.isFile() && SOURCE_FILE.test(entry.name)) out.push(rel === "" ? entry.name : `${rel}/${entry.name}`);
+}
+//#endregion
+//#region src/coverage/session.ts
+/**
+* One run's coverage measurement: the sink the application pushes to, the
+* acquisition engine each spec's browser is armed with, and the merge of what
+* both sides reported into a report row.
+*
+* The two sides never talk to each other. The browser writes what it reached
+* into the spec's coverage directory; instrumented server processes push what
+* they reached here. They meet on the spec id the cookie carried between them.
+*/
+/**
+* The application pushes on a timer, so the last second of a spec is still in
+* flight when its test returns — and the tail of a spec is where the work it
+* triggered asynchronously lands.
+*/
+const SETTLE_POLL_MS = 250;
+const SETTLE_QUIET_POLLS = 10;
+const SETTLE_CAP_MS = 1e4;
+var CoverageSession = class CoverageSession {
+	existing = /* @__PURE__ */ new Map();
+	sink;
+	runId;
+	/** What reported paths are relative to, and what they are checked against. */
+	root;
+	/** Where ccqa runs — the engine's base for resolving bundler-relative paths. */
+	cwd;
+	actors;
+	origins;
+	/** The denominator, enumerated once at start, or undefined when `coverage.include` is unset. */
+	universe;
+	constructor(sink, runId, root, cwd, actors, origins, universe) {
+		this.sink = sink;
+		this.runId = runId;
+		this.root = root;
+		this.cwd = cwd;
+		this.actors = actors;
+		this.origins = origins;
+		this.universe = universe;
+	}
+	static async start(options) {
+		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);
+		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);
+	}
+	get sinkUrl() {
+		return this.sink.url;
+	}
+	/**
+	* Opens the spec's measurement.
+	*
+	* Waits out the drain first, when the spec acts as an identity another spec
+	* just finished acting as: the two clocks involved make an event near the
+	* boundary ambiguous, and a quiet gap is the only thing that resolves it
+	* without either side having to trust the other's time.
+	*/
+	async beginSpec(ref) {
+		const specId = specIdFor(this.runId, ref);
+		for (const window of this.actors.windowsForSpec.get(specKey(ref)) ?? []) {
+			const closedAt = this.sink.lastClosedAt(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);
+		}
+	}
+	/**
+	* Attaches the acquisition engine to the browser the spec's target drives.
+	* Everything spec-specific the engine needs — the id, the cookie's
+	* destinations, the roots — lives here, so the caller only supplies where
+	* the browser is.
+	*/
+	armBrowser(ref, cdpUrl, coverageDir) {
+		return startBrowserCoverage({
+			cdpUrl,
+			specId: specIdFor(this.runId, ref),
+			origins: this.origins,
+			coverageDir,
+			roots: {
+				base: this.cwd,
+				root: this.root
+			},
+			warn: (text) => warn(`coverage: ${text}`)
+		});
+	}
+	/** Merges both sides once the spec's pushes have stopped arriving. */
+	async collect(ref, coverageDir) {
+		const specId = specIdFor(this.runId, ref);
+		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);
+		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(),
+			frontendReported: frontend !== void 0,
+			frontendStopped: frontend?.stopped ?? false,
+			actorWindows: owned.map((window) => ({
+				key: window.key,
+				events: matched.get(window.key) ?? 0
+			})),
+			excludedDependencies: frontend?.excludedDependencies ?? 0,
+			gaps: {
+				unattributed: this.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)
+			}
+		};
+	}
+	/** Files reached at module top level, across the whole run. */
+	boot() {
+		return [...this.sink.boot()].sort();
+	}
+	/** Whether any instrumented application process reported at all. */
+	heardFromApplication() {
+		return this.sink.heardFromApplication();
+	}
+	/** Specs some application process attributed a file to. */
+	attributedSpecs() {
+		return this.sink.attributedSpecs();
+	}
+	/** Declared identities that acted outside the turns this run gave them. */
+	outsideWindowEvents() {
+		return this.sink.outsideWindowEvents();
+	}
+	/** Events from identities this project never declared. */
+	unmappedActorEvents() {
+		return this.sink.unmappedActorEvents();
+	}
+	/** Pushes naming a spec id this run never issued — a stale or forged cookie. */
+	rejectedPushes() {
+		return this.sink.rejectedPushes();
+	}
+	/** Pushes the sink could not read — the two halves' wire formats disagree. */
+	malformedPushes() {
+		return this.sink.malformedPushes();
+	}
+	/** Application processes that instrumented nothing at all. */
+	uninstrumentedProcesses() {
+		return this.sink.uninstrumentedProcesses();
+	}
+	async close() {
+		await this.sink.close();
+	}
+	/** Keeps the paths that name a file in the working tree, cached per session. */
+	async keepExisting(paths) {
+		const unknown = paths.filter((path) => !this.existing.has(path));
+		await Promise.all(unknown.map(async (path) => {
+			this.existing.set(path, await access(join(this.root, path)).then(() => true, () => false));
+		}));
+		return paths.filter((path) => this.existing.get(path) === true);
+	}
+	async settle(specId) {
+		if (!this.sink.heardFromApplication()) return;
+		const deadline = Date.now() + SETTLE_CAP_MS;
+		let previous = this.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;
+			quiet = size === previous ? quiet + 1 : 0;
+			previous = size;
+		}
+	}
+};
+/**
+* Ends a spec's measurement, whatever happened to the spec.
+*
+* Every caller has to reach this, including the paths that give up before the
+* spec runs: a turn opened on an identity and never closed swallows every later
+* event for it, and the next spec on that identity skips the drain it needs.
+*
+* Never throws. A measurement that could not be read is not a test result.
+*/
+async function closeMeasurement(collector, ref, coverageDir) {
+	try {
+		return await collector.collect(ref, coverageDir);
+	} catch (error) {
+		warn(`coverage: could not collect for ${specKey(ref)} (${errMessage(error)})`);
+		return;
+	}
+}
+/**
+* The configured root, checked before a run leans on it.
+*
+* Every failure here is otherwise silent and identical to success: a root that
+* does not exist, or does not contain the project, sends every relative source
+* outside it, and the run reports a smaller file set with no error at all —
+* the answer this measurement exists to prevent.
+*/
+async function resolveRoot(cwd, declared) {
+	if (declared === void 0) return void 0;
+	const substituted = resolveEnvRefs(declared).trim();
+	if (substituted === "") throw new Error(`coverage.projectRoot "${declared}" resolved to nothing — is the variable set?`);
+	const root = resolve(cwd, substituted);
+	if ((await stat(root).catch(() => void 0))?.isDirectory() !== true) throw new Error(`coverage.projectRoot must name an existing directory; "${declared}" resolved to ${root}`);
+	if (relative(root, cwd).startsWith("..")) throw new Error(`coverage.projectRoot must contain the directory ccqa runs in; ${root} does not contain ${cwd}`);
+	return root;
+}
+/**
+* Where a spec's browser-side result lands.
+*
+* Not the artifacts directory: the tool a target runs owns that one and may
+* recreate it on startup, and everything left there is also reported as an
+* artifact — the same measurement would then ship twice, once structured and
+* once as a raw blob.
+*/
+function specCoverageDir(reportDir, feature, spec) {
+	return join(reportDir, "coverage", feature, spec);
 }
-//#endregion
-//#region src/run/output-tail.ts
-/** Cap on the per-spec output tail kept for the report / analysis prompt. */
-const OUTPUT_TAIL_CAP = 64 * 1024;
 /**
-* Keeps the LAST `cap` characters appended — test runners put the failure
-* summary at the end of their output, so the tail is what's worth keeping on
-* overflow. Dependency-free so both the vitest pipeline and the runCommand
-* runner (src/targets/run-command-runner.ts) can use it without importing the
-* whole pipeline.
+* `<runId>.<feature>/<spec>`. The run id keeps a stale cookie from an earlier
+* run out; the spec half is `specKey`, so an id here and a report row name the
+* same spec the same way.
 */
-var TailBuffer = class {
-	buf = "";
-	cap;
-	constructor(cap) {
-		this.cap = cap;
-	}
-	append(s) {
-		this.buf += s;
-		if (this.buf.length > this.cap * 2) this.buf = this.buf.slice(-this.cap);
+function specIdFor(runId, ref) {
+	return `${runId}.${specKey(ref)}`;
+}
+async function readFrontend(coverageDir, specId) {
+	let raw;
+	try {
+		raw = await readFile(join(coverageDir, FRONTEND_COVERAGE_FILE), "utf8");
+	} catch {
+		return;
 	}
-	toString() {
-		if (this.buf.length <= this.cap) return this.buf;
-		return `[...output truncated...]\n${this.buf.slice(-this.cap)}`;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed.files) || parsed.specId !== specId) throw new Error("not this spec");
+		return parsed;
+	} catch (error) {
+		warn(`coverage: ${FRONTEND_COVERAGE_FILE} for ${specId} could not be read (${errMessage(error)})`);
+		return;
 	}
-};
+}
 //#endregion
 //#region src/report/spec-row.ts
 /**
@@ -5600,10 +7302,10 @@ function toPosix(p) {
 */
 function substituteRunCommandFiles(runCommand, testFiles) {
 	if (!runCommand.includes("{files}")) return runCommand;
-	const joined = testFiles.map(shellQuote).join(" ");
+	const joined = testFiles.map(shellQuote$1).join(" ");
 	return runCommand.replaceAll("{files}", joined);
 }
-function shellQuote(s) {
+function shellQuote$1(s) {
 	return /^[A-Za-z0-9_./-]+$/.test(s) ? s : `'${s.replaceAll("'", `'\\''`)}'`;
 }
 /**
@@ -5729,21 +7431,70 @@ async function runOneSpec$1(ref, opts, blocks) {
 		});
 		await mkdir(evidenceDir, { recursive: true });
 	}
-	const command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
+	const measurement = opts.coverage !== void 0 && opts.browserCoverage.browser === "cdp" ? {
+		collector: opts.coverage,
+		cdpEndpoint: opts.browserCoverage.cdpEndpoint
+	} : null;
+	const coverageDir = specCoverageDir(opts.reportDir, featureName, specName);
+	if (measurement) {
+		await rm(coverageDir, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(coverageDir, { recursive: true });
+	}
+	const childEnv = {
+		[ARTIFACTS_DIR_ENV]: artifactsDir,
+		CCQA_RUN_ID: buildRunId(),
+		...evidenceDir ? { [EVIDENCE_DIR_ENV]: evidenceDir } : {}
+	};
+	let command = substituteArtifactsDir(substituteRunCommandFiles(runCommand, testFiles), artifactsDir);
+	let browserHandle;
+	let browserEngine;
+	let attachError;
+	if (measurement) {
+		await measurement.collector.beginSpec(ref);
+		try {
+			browserHandle = await measurement.cdpEndpoint({
+				cwd: opts.cwd,
+				featureName,
+				specName
+			});
+			const acquired = browserHandle;
+			opts.teardown?.onFinalize(() => acquired.dispose());
+			browserEngine = await measurement.collector.armBrowser(ref, browserHandle.cdpUrl, coverageDir);
+			if (browserHandle.amendCommand) command = browserHandle.amendCommand(command);
+			Object.assign(childEnv, browserHandle.env);
+		} catch (err) {
+			attachError = errMessage(err);
+			warn(`coverage: could not attach to the target's browser (${attachError})`);
+		}
+	}
 	meta("command", command);
 	blank();
 	const started = Date.now();
 	let outcome;
+	let spawnFailure;
+	let measured;
 	try {
 		outcome = await runShellCommand$1(command, {
 			cwd: opts.cwd,
 			artifactsDir,
-			evidenceDir,
-			logPath: join(artifactsDir, OUTPUT_LOG_FILE)
+			logPath: join(artifactsDir, OUTPUT_LOG_FILE),
+			env: childEnv
 		});
 	} catch (err) {
-		return didNotExecute(`could not spawn runCommand: ${err instanceof Error ? err.message : String(err)}`, "the runCommand could not be spawned");
+		spawnFailure = err instanceof Error ? err.message : String(err);
+	} finally {
+		if (browserEngine) await browserEngine.stop().catch(() => void 0);
+		if (measurement) measured = await closeMeasurement(measurement.collector, ref, coverageDir);
+		if (browserHandle) await browserHandle.dispose().catch(() => void 0);
 	}
+	const coverageFields = coverageRowFields(opts, measured, attachError);
+	if (spawnFailure !== void 0 || outcome === void 0) return {
+		...didNotExecute(`could not spawn runCommand: ${spawnFailure ?? "unknown error"}`, "the runCommand could not be spawned"),
+		...coverageFields
+	};
 	const durationMs = Date.now() - started;
 	blank();
 	let artifacts;
@@ -5770,16 +7521,29 @@ async function runOneSpec$1(ref, opts, blocks) {
 		target: opts.targetId,
 		durationMs,
 		...artifactFields,
-		...evidenceFields
+		...evidenceFields,
+		...coverageFields
 	};
 	return {
 		...failedRow([`command failed (exit ${outcome.exitCode}): ${command}`, outcome.tail.length > 0 ? `--- output (tail) ---\n${outcome.tail}` : null].filter((p) => p !== null).join("\n")),
 		durationMs,
 		...artifactFields,
-		...evidenceFields
+		...evidenceFields,
+		...coverageFields
 	};
 }
 /**
+* What the row says about measurement. A half-measured row (the server side
+* only, because the browser never attached) would read as "this spec reached
+* almost nothing", so a failed attach reports its reason instead of numbers.
+*/
+function coverageRowFields(opts, measured, attachError) {
+	if (attachError !== void 0) return { coverageUnavailable: `could not attach to the target's browser: ${attachError}` };
+	if (measured !== void 0) return { coverage: measured };
+	if (opts.coverage !== void 0 && opts.browserCoverage.browser === "none") return { coverageUnavailable: opts.browserCoverage.reason };
+	return {};
+}
+/**
 * The row's step screenshots, or — when there are none — the reason, so the
 * report never shows an empty evidence section without explanation. A
 * supported target that produced nothing almost always means the generated
@@ -5863,9 +7627,7 @@ async function runShellCommand$1(command, opts) {
 		shell: true,
 		env: {
 			...process.env,
-			[ARTIFACTS_DIR_ENV]: opts.artifactsDir,
-			CCQA_RUN_ID: buildRunId(),
-			...opts.evidenceDir ? { [EVIDENCE_DIR_ENV]: opts.evidenceDir } : {}
+			...opts.env
 		},
 		stdio: [
 			"ignore",
@@ -6406,8 +8168,9 @@ const C$1 = {
 * diff — so report rows and CI logs look the same whichever target a
 * project's specs use.
 *
-* One Claude call per failing spec, which reads the source itself rather than
-* deferring to a drift audit run beforehand. It is still one *phase*:
+* One Claude call per failing spec (two when the first errors and is retried
+* once), which reads the source itself rather than deferring to a drift audit
+* run beforehand. It is still one *phase*:
 * `beginFailureAnalysis` hands back the state every path shares, so a mixed
 * run prints one `failure analysis` banner in one place rather than one per
 * execution path. It runs after every spec has executed, so no Claude turn is
@@ -7198,6 +8961,12 @@ async function resolveSerialGroups(groups, cwd) {
 	}
 	return (ref) => bySpec.get(specKey(ref)) ?? [];
 }
+/** Every group either lookup gives a spec. Names from different sources never collide. */
+function mergeGroups(...lookups) {
+	const present = lookups.filter((lookup) => lookup !== NO_GROUPS);
+	if (present.length <= 1) return present[0] ?? NO_GROUPS;
+	return (ref) => present.flatMap((lookup) => lookup(ref));
+}
 //#endregion
 //#region src/hub/contract/schema.ts
 /**
@@ -7318,8 +9087,10 @@ z.object({ error: z.object({
 * One spec's record of a single run, as stored in a ledger bucket. Identical
 * to `LastGreenEntry` plus the commit the environment was running at the time
 * — without it a bucket entry can be ordered in wall-clock time but not
-* *positioned* against the deploy log, which is the only ordering re-run
-* selection may use (ADR-0010).
+* *positioned* against the deploy log, which is the only ordering the
+* staleness verdict may use (ADR-0010). Wall-clock order is fit only for
+* scheduling within an already-decided set, where a mis-ranking delays a
+* spec rather than excusing it.
 */
 const SpecLedgerEntrySchema = z.object({
 	gitHead: z.string(),
@@ -7904,7 +9675,10 @@ function selectSpecsNeedingRerun(specs, report) {
 		const entry = report.specs[specKey(spec)];
 		const verdict = entry?.verdict ?? "inProgress";
 		counts.set(verdict, (counts.get(verdict) ?? 0) + 1);
-		if (verdict === "rerunNeeded") selected.push(spec);
+		if (verdict === "rerunNeeded") selected.push({
+			spec,
+			lastRunAt: entry?.lastRun?.at ?? ""
+		});
 		else if (verdict === "inProgress") {
 			excludedInProgress++;
 			if (!entry) excludedUnknownToHub++;
@@ -7914,8 +9688,9 @@ function selectSpecsNeedingRerun(specs, report) {
 			}
 		}
 	}
+	selected.sort((a, b) => a.lastRunAt.localeCompare(b.lastRunAt));
 	return {
-		selected,
+		selected: selected.map((s) => s.spec),
 		summary: formatCounts(SUMMARY_ORDER$1, counts),
 		excludedInProgress,
 		excludedUnknownToHub,
@@ -9836,6 +11611,15 @@ ${stepsText}
 - Do not invent success when blocked: fail honestly with a short reason.
 - **Evidence discipline**: when the assertion target is a specific row / message / banner / URL, scroll it into view (or focus the relevant pane) before letting the step end. The "after" screenshot is captured for you automatically — your job is to make sure that screenshot shows the thing your STEP_RESULT line is talking about.
 
+### Waiting for asynchronous responses
+
+Some expected outcomes arrive asynchronously — an automated reply, a background job finishing, a list refreshing. Waiting for them is fine, but the wait has a budget:
+
+- Prefer bounded probes (\`agent-browser wait --text "..."\`, or a short pause followed by a fresh \`snapshot\`) over long blind sleeps, and keep a rough running total of how long you have waited within this step.
+- **The total wait within one step must not exceed 3 minutes**, unless the step's own instruction explicitly names a longer wait. Do not keep adding "one more" sleep past the budget.
+- When the budget is spent and the expected outcome has still not appeared, STOP waiting and emit \`STEP_RESULT|<stepId>|fail|...\`. **Never end your turn without a STEP_RESULT because you were still waiting** — a silent timeout is recorded as a protocol failure and hides the real cause from failure analysis.
+- The fail reason must state what you waited for, roughly how long in total, and what you observed instead (e.g. "waited ~3 min for a reply to appear after submitting; none appeared, the view still shows only the submitted item").
+
 ### Output contract (STRICT)
 
 Your final assistant message MUST contain exactly one line of the form:
@@ -10286,6 +12070,46 @@ async function copyEvidenceIntoReport(absPath, evidenceDir, reportDir) {
 	}
 }
 //#endregion
+//#region src/targets/agent-browser/browser-endpoint.ts
+/**
+* Where the agent-browser target's browser comes from under `--coverage`.
+*
+* agent-browser owns its browser but hands out the keys on request:
+* `get cdp-url` answers with the browser-level DevTools socket. The daemon
+* launches a session's browser lazily, so an `open about:blank` forces it up
+* first — into a session the caller already owns, before the agent starts
+* driving it. Auth-state restored into the session afterwards lands in a warm
+* browser, which is the same shape as the executor's mid-run recovery path.
+*
+* `dispose` does nothing on purpose: the session's lifecycle belongs to the
+* caller (the live runner closes it after the engine has stopped), and
+* closing somebody else's session from here would tear the browser down
+* while its owner still thinks it is driving it.
+*/
+async function acquireAgentBrowserEndpoint(ctx) {
+	const session = ctx.driverSession;
+	if (session === void 0) throw new Error("the agent-browser target's browser lives in a driver session, and none was supplied");
+	const warm = spawnAB([
+		"--session",
+		session,
+		"open",
+		"about:blank"
+	]);
+	if (warm.status !== 0) throw new Error(`could not start the session's browser: ${warm.stderr || warm.stdout}`);
+	const answer = spawnAB([
+		"--session",
+		session,
+		"get",
+		"cdp-url"
+	]);
+	const cdpUrl = answer.stdout.trim().split("\n").pop()?.trim() ?? "";
+	if (answer.status !== 0 || !/^wss?:\/\//.test(cdpUrl)) throw new Error(`agent-browser did not answer \`get cdp-url\` for session ${session}: ${answer.stderr || answer.stdout}`);
+	return {
+		cdpUrl,
+		dispose: async () => {}
+	};
+}
+//#endregion
 //#region src/diagnose/snapshot.ts
 const require = createRequire(import.meta.url);
 const SNAPSHOT_TIMEOUT_MS = 1e4;
@@ -10399,6 +12223,37 @@ async function closeSession(sessionName) {
 * agent-browser) and, when `reportDir` is set, run drift audit + failure
 * analysis to produce report rows. Sibling of `runDeterministicSpecs`.
 */
+/**
+* Brackets one live spec's execution with the measurement.
+*
+* The bracket has to hold even when the spec does not run: opening a turn on an
+* identity and never closing it would leave the next spec waiting on a window
+* that outlived its owner.
+*/
+async function measureLive(spec, opts, coverageDir, execute) {
+	const collector = opts.coverage;
+	if (collector === void 0) return {
+		outcome: await execute(),
+		coverage: void 0
+	};
+	await rm(coverageDir, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(coverageDir, { recursive: true });
+	await collector.beginSpec(spec);
+	let outcome;
+	try {
+		outcome = await execute();
+	} catch (err) {
+		await closeMeasurement(collector, spec, coverageDir);
+		throw err;
+	}
+	return {
+		outcome,
+		coverage: await closeMeasurement(collector, spec, coverageDir)
+	};
+}
 async function runLiveSpecs(specs, opts) {
 	if (specs.length === 0) return {
 		reportResults: [],
@@ -10427,22 +12282,28 @@ async function runLiveSpecs(specs, opts) {
 				blank();
 				info(`[${i + 1}/${specs.length}] ${label}`);
 			}
-			const outcome = await runOneSpec({
+			const coverageDir = specCoverageDir(reportDir, spec.featureName, spec.specName);
+			const measured = await measureLive(spec, opts, coverageDir, () => runOneSpec({
 				...spec,
 				opts,
 				userPromptSuffix,
-				cwd
-			});
+				cwd,
+				coverageDir
+			}));
+			const { outcome } = measured;
 			if (outcome.kind !== "run") return {
 				outcome,
 				row: null
 			};
-			const row = await buildLiveReportRow(outcome, {
-				auth,
-				diffProvider,
-				reportDir,
-				blocks
-			}, opts, cwd);
+			const row = {
+				...await buildLiveReportRow(outcome, {
+					auth,
+					diffProvider,
+					reportDir,
+					blocks
+				}, opts, cwd),
+				...outcome.coverageBroken !== void 0 ? { coverageUnavailable: `could not attach to the live browser: ${outcome.coverageBroken}` } : measured.coverage ? { coverage: measured.coverage } : {}
+			};
 			await opts.report?.upsert(row);
 			return {
 				outcome,
@@ -10572,7 +12433,7 @@ async function resolveSessionState(names, hubCtx, profile, verify = verifySessio
 	};
 }
 async function runOneSpec(args) {
-	const { featureName, specName, opts, userPromptSuffix, cwd } = args;
+	const { featureName, specName, opts, userPromptSuffix, cwd, coverageDir } = args;
 	const specDir = getSpecDir(featureName, specName, cwd);
 	let specContent;
 	try {
@@ -10615,6 +12476,23 @@ async function runOneSpec(args) {
 		cleanupSession = resolution.cleanup;
 		meta("state", spec.session.join(", "));
 	}
+	let browserEngine;
+	let coverageBroken;
+	if (opts.coverage) try {
+		const handle = await acquireAgentBrowserEndpoint({
+			cwd,
+			featureName,
+			specName,
+			driverSession: sessionName
+		});
+		browserEngine = await opts.coverage.armBrowser({
+			featureName,
+			specName
+		}, handle.cdpUrl, coverageDir);
+	} catch (err) {
+		coverageBroken = errMessage(err);
+		warn(`coverage: could not attach to the live browser (${coverageBroken})`);
+	}
 	try {
 		const runId = buildRunId();
 		const envScrubMap = buildProseEnvScrubMap(spec, expanded, { CCQA_RUN_ID: runId });
@@ -10651,9 +12529,11 @@ async function runOneSpec(args) {
 			runDir,
 			specYaml: specContent,
 			envScrubMap,
-			result
+			result,
+			...coverageBroken === void 0 ? {} : { coverageBroken }
 		};
 	} finally {
+		if (browserEngine) await browserEngine.stop().catch(() => void 0);
 		if (cleanupSession) await cleanupSession();
 		opts.teardown?.untrackSession(sessionName);
 		await closeSession(sessionName);
@@ -10818,6 +12698,39 @@ const TargetConfigSchema = z.object({
 */
 const SerialGroupsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "serial group name must be a slug (letters, digits, '.', '_', '-')"), z.array(z.string().min(1)).min(1));
 /**
+* Which specs act as which external identity, for the flows whose requests
+* cannot carry a spec id at all.
+*
+* A chat platform's webhook is sent by the platform, not the browser, so no
+* cookie rides along and everything the flow reaches would be unattributed.
+* What the request does carry is who caused it, and if only one spec is allowed
+* to act as that identity at a time, "who" plus "when" is enough.
+*
+* ```yaml
+* coverage:
+*   actors:
+*     slack:                      # the preset's tag prefix
+*       ${TEST_USER_ID}: [chat/create-item, chat/resolve-item]
+* ```
+*
+* The provider name is the prefix the matching preset stamps, and the key is an
+* identity expression the run's variables resolve. Only the unexpanded text is
+* ever displayed or used as a lock key, so the identity itself stays out of
+* reports and the hub.
+*/
+const CoverageActorsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i, "actor provider must be a slug (letters, digits, '.', '_', '-')"), z.record(z.string().min(1), z.array(z.string().min(1)).min(1)));
+/**
+* Settings for `ccqa run --coverage`, which measures what each spec actually
+* reached in the application under test.
+*/
+const CoverageConfigSchema = z.object({
+	instrumentedOrigins: z.array(z.string().min(1)).min(1),
+	sink: z.string().min(1).default("http://127.0.0.1:4757"),
+	projectRoot: z.string().min(1).optional(),
+	include: z.array(z.string().min(1)).optional(),
+	actors: CoverageActorsSchema.default({})
+}).strict();
+/**
 * Top-level `.ccqa/config.yaml` schema. `defaultTarget` is used by specs
 * with no `target:` of their own. Both defaults make a missing config file
 * equivalent to "agent-browser only, no extra settings".
@@ -10825,7 +12738,8 @@ const SerialGroupsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i,
 const ProjectConfigSchema = z.object({
 	defaultTarget: TargetIdSchema.default(AGENT_BROWSER_TARGET),
 	targets: z.record(TargetIdSchema, TargetConfigSchema).default({}),
-	serialGroups: SerialGroupsSchema.default({})
+	serialGroups: SerialGroupsSchema.default({}),
+	coverage: CoverageConfigSchema.optional()
 }).strict();
 /** Config file location, relative to the project root (`--cwd`). */
 const PROJECT_CONFIG_PATH = ".ccqa/config.yaml";
@@ -11938,13 +13852,17 @@ const agentBrowserTarget = {
 	id: AGENT_BROWSER_TARGET,
 	input: "recording",
 	generate: generateAgentBrowserTest,
-	existingOutput: (ref, cwd) => getTestScript(ref.featureName, ref.specName, cwd)
+	existingOutput: (ref, cwd) => getTestScript(ref.featureName, ref.specName, cwd),
+	browserCoverage: {
+		browser: "cdp",
+		cdpEndpoint: acquireAgentBrowserEndpoint
+	}
 };
 //#endregion
 //#region src/targets/playwright/emit-mechanical.ts
 /** Module the emitted step-boundary capture calls import from. */
 const STEP_EVIDENCE_MODULE = "ccqa/step-evidence";
-/** Capture call emitted when a step is entered / closed. Exported for the coverage gate. */
+/** Capture call emitted when a step is entered / closed. Exported for the generation gate. */
 const STEP_EVIDENCE_BEFORE = "ccqaStepBefore";
 const STEP_EVIDENCE_AFTER = "ccqaStepAfter";
 /** The exact boundary call for one step, as emitted and as the gate greps for it. */
@@ -12162,6 +14080,145 @@ const j = (s) => JSON.stringify(s);
 */
 const jExpr = (s) => envRefsToJsExpression(s);
 //#endregion
+//#region src/targets/playwright/browser-server.ts
+/**
+* Where the playwright target's browser comes from under `--coverage`.
+*
+* `playwright test` launches its own browser inside a process ccqa does not
+* own, and Playwright has no environment knob that would open a debugging
+* port on it. So the ownership is inverted: ccqa launches a browser server —
+* with the *consumer's own* Playwright, so the wire protocol matches by
+* construction — and a generated config makes the tests connect to it via
+* `use.connectOptions`. The config wrapper imports the project's real config,
+* so everything else about the run is the project's own; it is written next
+* to that config because Playwright resolves relative paths against the
+* config's directory, and a wrapper anywhere else would silently re-root
+* them.
+*
+* The ordering this buys is the point: the browser exists and the engine is
+* attached before the test process is even spawned, so there is no window in
+* which a script can run unprofiled or a request can leave uncookied.
+*/
+const CONNECT_ENV = "CCQA_PW_CONNECT";
+const CONFIG_NAMES = [
+	"playwright.config.ts",
+	"playwright.config.mts",
+	"playwright.config.cts",
+	"playwright.config.js",
+	"playwright.config.mjs",
+	"playwright.config.cjs"
+];
+async function acquirePlaywrightBrowser(ctx) {
+	await sweepStaleWrappers(ctx.cwd);
+	const chromium = await resolveChromium(ctx.cwd);
+	const port = await freePort();
+	const server = await chromium.launchServer({ args: [`--remote-debugging-port=${port}`] });
+	let wrapperPath;
+	try {
+		await waitForCdp(port);
+		wrapperPath = await writeWrapperConfig(ctx);
+	} catch (error) {
+		await server.close().catch(() => void 0);
+		throw error;
+	}
+	const wrapper = wrapperPath;
+	let disposed = false;
+	return {
+		cdpUrl: `http://127.0.0.1:${port}`,
+		env: { [CONNECT_ENV]: server.wsEndpoint() },
+		amendCommand: (command) => {
+			if (/(^|\s)(--config|-c)[=\s]/.test(command)) throw new Error("the runCommand already passes --config; --coverage needs to supply its own. Drop the flag from targets.playwright.runCommand (the default config resolution still applies) or run without --coverage.");
+			if (/[|;&<>`$]/.test(command)) throw new Error("the runCommand uses shell operators, so --coverage cannot safely append its --config to it. Reduce targets.playwright.runCommand to a plain `playwright test` invocation or run without --coverage.");
+			return `${command} --config=${shellQuote(wrapper)}`;
+		},
+		dispose: async () => {
+			if (disposed) return;
+			disposed = true;
+			await server.close().catch(() => void 0);
+			await unlink(wrapper).catch(() => void 0);
+		}
+	};
+}
+/**
+* Wrappers a killed earlier run left behind. Deleted on the next acquire, not
+* only guarded against: a stray one is git-status dirt in somebody's repo.
+*/
+async function sweepStaleWrappers(cwd) {
+	const entries = await readdir(cwd).catch(() => []);
+	for (const name of entries) if (name.startsWith("ccqa-coverage.") && name.endsWith(".playwright.config.ts")) await unlink(join(cwd, name)).catch(() => void 0);
+}
+/** Single quotes survive every shell metacharacter except themselves. */
+function shellQuote(s) {
+	return `'${s.replaceAll("'", `'\\''`)}'`;
+}
+/**
+* The consumer's Playwright, not a dependency of ccqa's: their tests speak
+* their version's protocol, and the server has to be the same animal. Their
+* `runCommand` runs `playwright test`, so the package is present — but under
+* pnpm's isolation it may only be resolvable through `@playwright/test`.
+*/
+async function resolveChromium(cwd) {
+	const fromProject = createRequire(join(cwd, "package.json"));
+	const origins = [];
+	try {
+		origins.push(fromProject.resolve("@playwright/test/package.json"));
+	} catch {}
+	for (const name of ["playwright", "playwright-core"]) for (const origin of [null, ...origins]) try {
+		const mod = await import(pathToFileURL((origin === null ? fromProject : createRequire(origin)).resolve(name)).href);
+		const chromium = mod.chromium ?? mod.default?.chromium;
+		if (chromium !== void 0) return chromium;
+	} catch {}
+	throw new Error(`could not resolve Playwright from ${cwd} — the playwright target's --coverage launches the browser with the project's own Playwright, which must be installed`);
+}
+async function writeWrapperConfig(ctx) {
+	const existing = CONFIG_NAMES.find((name) => existsSync(join(ctx.cwd, name)));
+	const wrapperName = `ccqa-coverage.${slug(ctx.featureName)}--${slug(ctx.specName)}.playwright.config.ts`;
+	const wrapperPath = join(ctx.cwd, wrapperName);
+	const header = "// Written by `ccqa run --coverage` for one spec's run and removed after it.";
+	const connect = `use: { ...(base as { use?: object }).use, connectOptions: { wsEndpoint: process.env.${CONNECT_ENV} ?? "" } }`;
+	await writeFile(wrapperPath, (existing === void 0 ? [
+		header,
+		`export default { use: { connectOptions: { wsEndpoint: process.env.${CONNECT_ENV} ?? "" } } };`,
+		""
+	] : [
+		header,
+		"// It only points the browser at the server ccqa launched; everything else",
+		"// is the project's own config, imported unchanged.",
+		`import base from "./${existing}";`,
+		`export default { ...(base as object), ${connect} };`,
+		""
+	]).join("\n"), "utf8");
+	return wrapperPath;
+}
+function slug(name) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "-");
+}
+function freePort() {
+	return new Promise((resolve, reject) => {
+		const probe = createServer$1();
+		probe.once("error", reject);
+		probe.listen(0, "127.0.0.1", () => {
+			const address = probe.address();
+			const port = typeof address === "object" && address !== null ? address.port : void 0;
+			probe.close(() => {
+				if (port === void 0) reject(/* @__PURE__ */ new Error("could not pick a port"));
+				else resolve(port);
+			});
+		});
+	});
+}
+/** The debugging socket opens with the browser; a short poll absorbs the gap. */
+async function waitForCdp(port) {
+	const deadline = Date.now() + 5e3;
+	for (;;) {
+		try {
+			if ((await fetch(`http://127.0.0.1:${port}/json/version`)).ok) return;
+		} catch {}
+		if (Date.now() > deadline) throw new Error(`the launched browser never opened its debugging port (${port})`);
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+}
+//#endregion
 //#region src/targets/playwright/index.ts
 const PLAYWRIGHT_TARGET = "playwright";
 /**
@@ -12183,6 +14240,10 @@ const playwrightTarget = {
 	existingOutput: existingPlaywrightOutput,
 	runner: runCommandRunner,
 	stepEvidence: { supported: true },
+	browserCoverage: {
+		browser: "cdp",
+		cdpEndpoint: acquirePlaywrightBrowser
+	},
 	guidanceKind: PLAYWRIGHT_TARGET
 };
 async function generatePlaywrightTest(ctx) {
@@ -12209,7 +14270,7 @@ async function generatePlaywrightTest(ctx) {
 			path: draftPath,
 			contents: draft
 		},
-		...stepMarkers.length > 0 ? { draftInvariant: stepEvidencePreserveRule() } : {}
+		draftInvariant: stepMarkers.length > 0 ? stepEvidencePreserveRule() : ""
 	}) : await finalizePreparedFiles({
 		ctx,
 		target: PLAYWRIGHT_TARGET,
@@ -12221,7 +14282,7 @@ async function generatePlaywrightTest(ctx) {
 		summary: `Playwright spec compiled from ${actions.length} recorded action(s)`,
 		warnings: []
 	});
-	const missing = await missingStepEvidence(result, stepMarkers);
+	const missing = await missingInjectedCalls(result, stepMarkers);
 	for (const w of missing) warn(w);
 	return {
 		...result,
@@ -12229,14 +14290,14 @@ async function generatePlaywrightTest(ctx) {
 	};
 }
 /**
-* Per-step warning for any `ccqa/step-evidence` boundary call absent from the
-* generated test files — the report would then miss that step's screenshots.
-* Reads the written test files (the LLM pass may have relocated them); a file
-* that can't be read is reported as missing all its steps rather than passing
-* silently.
+* Warnings for calls the emitter injected that the written test no longer has.
+* The deterministic emit always has them; the library-rewrite pass can drop
+* them when it restructures into page objects, which silently costs the spec
+* its screenshots. Reads the files from disk (the LLM pass may have relocated
+* them); a file that can't be read is reported as missing everything rather
+* than passing silently.
 */
-async function missingStepEvidence(result, markers) {
-	if (markers.length === 0) return [];
+async function missingInjectedCalls(result, markers) {
 	const corpus = (await Promise.all(result.files.filter((f) => f.kind === "test").map((f) => readFile(f.path, "utf8").catch(() => "")))).join("\n");
 	const warnings = [];
 	for (const m of markers) {
@@ -12280,6 +14341,10 @@ const runnTarget = {
 		supported: false,
 		reason: "runn runs API scenarios, which have no screen to capture"
 	},
+	browserCoverage: {
+		browser: "none",
+		reason: "runn runs API scenarios; there is no browser to measure"
+	},
 	guidanceKind: RUNN_TARGET
 };
 /** Exported with the engine's invoke seam so unit tests can stub Claude. */
@@ -12434,6 +14499,7 @@ function groupSpecsByTarget(specs, catalog, config, resolve = resolveTarget) {
 					supported: false,
 					reason: `the "${plugin.id}" target does not capture step screenshots`
 				},
+				browserCoverage: plugin.browserCoverage,
 				specs: []
 			};
 			group.specs.push(entry);
@@ -12503,6 +14569,9 @@ async function runExternalSpecs(dispatch, ctx) {
 				targetId: group.targetId,
 				targetConfig: group.targetConfig,
 				stepEvidence: group.stepEvidence,
+				browserCoverage: group.browserCoverage,
+				...ctx.coverage ? { coverage: ctx.coverage } : {},
+				...ctx.teardown ? { teardown: ctx.teardown } : {},
 				onSpecComplete: async (row) => {
 					streamed.push(row);
 					await ctx.report.upsert(row);
@@ -13268,7 +15337,8 @@ async function executeRun(targets, opts) {
 	}
 	const catalog = await readSpecs(specs, cwd);
 	const projectConfig = await loadProjectConfig(cwd);
-	const resources = await resolveSerialGroups(projectConfig.serialGroups, cwd);
+	const actors = opts.coverage === true && forExecution ? await resolveActors(projectConfig.coverage?.actors ?? {}, cwd) : NO_ACTORS;
+	const resources = mergeGroups(await resolveSerialGroups(projectConfig.serialGroups, cwd), actorGroups(actors));
 	const declared = [...new Set(specs.flatMap(resources))];
 	if (declared.length > 0) meta("serial groups", declared.join(", "));
 	let waitingOnGroup = [];
@@ -13311,6 +15381,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;
 	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}`);
@@ -13373,7 +15444,8 @@ async function executeRun(targets, opts) {
 		customPromptVersion: customPrompt?.customPromptVersion ?? null,
 		triageUserPromptHash,
 		deployedSha,
-		opts
+		opts,
+		coverage
 	}), hubSink, currentReportCost);
 	let completedNormally = false;
 	opts.teardown?.onFinalize(async () => {
@@ -13397,7 +15469,9 @@ async function executeRun(targets, opts) {
 		resources,
 		...opts.model ? { model: opts.model } : {},
 		...opts.language ? { language: opts.language } : {},
-		report: incrementalReport
+		report: incrementalReport,
+		...coverage ? { coverage } : {},
+		...opts.teardown ? { teardown: opts.teardown } : {}
 	});
 	const liveOpts = {
 		...opts.model ? { model: opts.model } : {},
@@ -13409,6 +15483,7 @@ async function executeRun(targets, opts) {
 		concurrency: opts.concurrency ?? 1,
 		resources,
 		...opts.hubProfile ? { profile: opts.hubProfile } : {},
+		...coverage ? { coverage } : {},
 		diffProvider,
 		hubContext: hubCtx,
 		customPrompt,
@@ -13417,6 +15492,7 @@ async function executeRun(targets, opts) {
 		report: incrementalReport
 	};
 	const live = await runLiveSpecs(liveSpecs, liveOpts);
+	if (coverage) 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;
@@ -13432,30 +15508,32 @@ async function executeRun(targets, opts) {
 		}))], analysisDeps);
 		const detResults = await analyzeDeterministicSummaries(det.summaries, cwd, reportDir, analysisRun);
 		const analyzedExternalRows = await analyzeExternalRows(externalRows, analysisRun);
+		const results = await rerunExplainedFailures([
+			...detResults,
+			...analyzedExternalRows,
+			...live.reportResults
+		], {
+			mode: rerunMode,
+			maxSpecs: opts.onFailExplainRerunMaxSpecs ?? null,
+			execute: createRerunExecutor({
+				detSpecs,
+				liveSpecs,
+				dispatch,
+				liveOpts,
+				opts,
+				cwd,
+				resources
+			})
+		});
 		report = await writeUnifiedReport({
 			reportDir,
-			results: await rerunExplainedFailures([
-				...detResults,
-				...analyzedExternalRows,
-				...live.reportResults
-			], {
-				mode: rerunMode,
-				maxSpecs: opts.onFailExplainRerunMaxSpecs ?? null,
-				execute: createRerunExecutor({
-					detSpecs,
-					liveSpecs,
-					dispatch,
-					liveOpts,
-					opts,
-					cwd,
-					resources
-				})
-			}),
+			results: coverage ? results.map(explainMissingCoverage) : results,
 			git,
 			customPromptVersion,
 			triageUserPromptHash,
 			deployedSha,
-			opts
+			opts,
+			coverage
 		});
 		completedNormally = true;
 		if (hubRunId) {
@@ -13465,7 +15543,8 @@ async function executeRun(targets, opts) {
 				customPromptVersion,
 				triageUserPromptHash,
 				deployedSha,
-				opts
+				opts,
+				coverage
 			});
 			const streamedKeys = new Set(incrementalReport.rows().map((r) => `${r.feature}/${r.spec}`));
 			const evidence = await readRowsFilesBase64(report.results.filter((r) => !streamedKeys.has(`${r.feature}/${r.spec}`)), reportDir);
@@ -13504,11 +15583,58 @@ async function executeRun(targets, opts) {
 	};
 }
 /**
-* Compact, prompt-friendly summary of one ccqa run for the live agent-prompt
-* update step. One section per spec: header line + per-step verdicts (see
-* `liveStepSummaryLine`). Kept to a few KB even with many specs/steps so the
-* prompt cache can absorb the bulk.
+* 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.
+*/
+async function startCoverage(cwd, config, actors, dispatch, teardown) {
+	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 {
+		session = await CoverageSession.start({
+			runId: buildRunId(),
+			cwd,
+			config,
+			actors,
+			specs: dispatch.external.flatMap((g) => g.specs)
+		});
+	} catch (err) {
+		throw new RunUsageError(`could not start coverage collection: ${errMessage(err)}`);
+	}
+	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());
+	return session;
+}
+/**
+* A run that measured coverage still leaves rows without any — a spec on a
+* target that declares no browser, or one that never executed. Saying why keeps
+* the reader from reading a blank as "this spec reached nothing".
 */
+function explainMissingCoverage(row) {
+	if (row.coverage !== void 0 || row.coverageUnavailable !== void 0) return row;
+	return {
+		...row,
+		coverageUnavailable: row.status === "skipped" ? "the spec did not execute" : "this target is not measured by --coverage yet"
+	};
+}
+/** Everything the measurement could not place; silence here reads as "never reached". */
+function reportCoverageHealth(coverage, rows) {
+	if (!coverage.heardFromApplication()) warn("no instrumented application process reported — only the browser half was measured. The server needs ccqa-tools and CCQA_COVERAGE_ENDPOINT pointed at this run's sink");
+	if (rows.filter((row) => row.coverage !== void 0).length > 0 && coverage.heardFromApplication() && coverage.attributedSpecs() === 0) warn("instrumented application processes reported, but no spec was attributed to them — the spec cookie is not reaching the application, so every spec's server-side reach is zero for that reason rather than because the server ran nothing. Check coverage.instrumentedOrigins covers every origin the spec's requests go to, and that a server which is not node:http-based installs the middleware itself");
+	const boot = coverage.boot();
+	if (boot.length > 0) meta("coverage", `${boot.length} file(s) reached only at module load, attributed to no spec`);
+	const blind = coverage.uninstrumentedProcesses();
+	if (blind > 0) warn(`${blind} application process(es) instrumented nothing at all — every file they ran is missing from this run, not just some. Load hooks need node 22.15+ (23.5+ on 23.x); bundled code needs the build plugin instead`);
+	for (const [key, count] of coverage.outsideWindowEvents()) warn(`${count} event(s) from ${key} arrived outside this run's turns — another job or a person used that identity while it was being measured, and what they triggered is attributed to nobody`);
+	const unmapped = coverage.unmappedActorEvents();
+	if (unmapped > 0) meta("coverage", `${unmapped} event(s) from identities this project does not declare, attributed to no spec`);
+	const rejected = coverage.rejectedPushes();
+	if (rejected > 0) warn(`${rejected} coverage push(es) named a spec id this run never issued — dropped`);
+	const malformed = coverage.malformedPushes();
+	if (malformed > 0) warn(`${malformed} coverage push(es) could not be read — the application's ccqa-tools and this CLI disagree on the wire format`);
+}
 function buildLiveRunSummary(results) {
 	const sections = [];
 	for (const r of results) {
@@ -13780,6 +15906,7 @@ function createRerunExecutor(ctx) {
 				targetId: group.targetId,
 				targetConfig: group.targetConfig,
 				stepEvidence: group.stepEvidence,
+				browserCoverage: group.browserCoverage,
 				onSpecComplete: async () => {}
 			});
 			return row?.status === "passed" ? "passed" : "failed";
@@ -13799,7 +15926,7 @@ function createRerunExecutor(ctx) {
 * final report.json stays byte-identical (existing e2e goldens compare it).
 */
 function buildReportEnvelope(args) {
-	const { git, customPromptVersion, triageUserPromptHash, deployedSha, opts } = args;
+	const { git, customPromptVersion, triageUserPromptHash, deployedSha, opts, coverage } = args;
 	const runUrl = githubRunUrl();
 	return {
 		schemaVersion: 1,
@@ -13821,19 +15948,21 @@ function buildReportEnvelope(args) {
 		customPromptVersion,
 		...triageUserPromptHash !== null ? { triageUserPromptHash } : {},
 		...deployedSha !== null ? { deployedSha } : {},
-		cost: currentReportCost()
+		cost: currentReportCost(),
+		...coverage?.universe ? { coverageUniverse: coverage.universe } : {}
 	};
 }
 /** Write the unified JSON (+ optional GitHub-annotation) report for one run. Returns the report data. */
 async function writeUnifiedReport(args) {
-	const { reportDir, results, git, customPromptVersion, triageUserPromptHash, deployedSha, opts } = args;
+	const { reportDir, results, git, customPromptVersion, triageUserPromptHash, deployedSha, opts, coverage } = args;
 	const data = {
 		...buildReportEnvelope({
 			git,
 			customPromptVersion,
 			triageUserPromptHash,
 			deployedSha,
-			opts
+			opts,
+			coverage
 		}),
 		results
 	};
@@ -14106,7 +16235,7 @@ 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.").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.").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. */
@@ -18129,7 +20258,8 @@ const PatchRunRequestSchema = z.object({
 		customPromptVersion: z.string().nullable().optional(),
 		runUrl: z.string().nullable().optional(),
 		triageUserPromptHash: z.string().optional(),
-		cost: ReportCostSchema.nullable().optional()
+		cost: ReportCostSchema.nullable().optional(),
+		coverageUniverse: CoverageUniverseSchema.optional()
 	}).partial().optional()
 });
 /** Insert or replace `rows` into `results`, upserting by feature/spec identity. */
@@ -18345,7 +20475,8 @@ function createPatchRunHandler(config) {
 				...reportMeta?.customPromptVersion !== void 0 ? { customPromptVersion: reportMeta.customPromptVersion } : {},
 				...reportMeta?.runUrl !== void 0 ? { runUrl: reportMeta.runUrl } : {},
 				...reportMeta?.triageUserPromptHash !== void 0 ? { triageUserPromptHash: reportMeta.triageUserPromptHash } : {},
-				...reportMeta?.cost !== void 0 ? { cost: reportMeta.cost } : {}
+				...reportMeta?.cost !== void 0 ? { cost: reportMeta.cost } : {},
+				...reportMeta?.coverageUniverse !== void 0 ? { coverageUniverse: reportMeta.coverageUniverse } : {}
 			};
 			const merged = mergeResults(current?.results ?? [], rows);
 			specs = countSpecs(merged);
@@ -20245,6 +22376,7 @@ const HTML_BODY = `
     <nav class="nav">
       <a href="#/runs" class="nav-runs"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M3 12h4l3 8 4-16 3 8h4"/></svg> <span data-i18n="nav.runs">Runs</span></a>
       <a href="#/perspectives" class="nav-perspectives"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M8 6h13M8 12h13M8 18h13"/><path d="M3 6h.01M3 12h.01M3 18h.01"/></svg> <span data-i18n="nav.perspectives">Perspectives</span></a>
+      <a href="#/coverage" class="nav-coverage"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="12" cy="12" r="9"/><circle cx="12" cy="12" r="4"/><path d="M12 3v2M12 19v2M3 12h2M19 12h2"/></svg> <span data-i18n="nav.coverage">Coverage</span></a>
       <a href="#/secrets" class="nav-secrets"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><rect x="3" y="11" width="18" height="10" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg> <span data-i18n="nav.secrets">Secrets</span></a>
       <a href="#/prompts" class="nav-prompts"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 4h11l5 5v11a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1z"/><path d="M14 4v6h6"/><path d="M8 13h6M8 17h6"/></svg> <span data-i18n="nav.prompts">Prompts</span></a>
       <a href="#/jobs" class="nav-jobs"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M12 2v4M12 18v4M4.9 4.9l2.8 2.8M16.3 16.3l2.8 2.8M2 12h4M18 12h4M4.9 19.1l2.8-2.8M16.3 7.7l2.8-2.8"/></svg> <span data-i18n="nav.learning">Learning</span></a>
@@ -20369,6 +22501,34 @@ const HTML_BODY = `
       </div>
     </section>
 
+    <!-- ===== COVERAGE ===== -->
+    <section id="view-coverage" hidden>
+      <div class="page-bar">
+        <h1 data-i18n="coverage.title">Coverage</h1>
+        <span class="updated" id="cov-asof"></span>
+        <div class="spacer"></div>
+        ${refreshButton("cov-refresh")}
+      </div>
+      <div class="content">
+        <p id="cov-status" class="empty-note" hidden></p>
+        <div id="cov-body" hidden>
+          <div class="ov">
+            <div class="ov-inv" id="cov-inv"></div>
+            <div id="cov-axis"></div>
+            <div class="cov-note" id="cov-note" hidden data-i18n="coverage.noUniverse">This measurement carried no file inventory, so only reached files are shown; nothing can be called uncovered.</div>
+          </div>
+          <div class="toolbar">
+            <label class="search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><circle cx="11" cy="11" r="7"/><path d="m21 21-4.3-4.3"/></svg><input id="cov-q" type="search" data-i18n-ph="coverage.search" aria-label="Filter files"></label>
+            <button class="fchip" id="cov-unc" aria-pressed="false" type="button"><span data-i18n="coverage.filter.uncovered">Uncovered only</span><span class="fcount" id="cov-unc-n"></span></button>
+          </div>
+          <div class="cov-split">
+            <div class="cov-treewrap"><div id="cov-tree"></div><p class="empty-note" id="cov-no-hit" hidden data-i18n="coverage.noHit">No matching files.</p></div>
+            <div class="cov-detail" id="cov-detail"></div>
+          </div>
+        </div>
+      </div>
+    </section>
+
     <!-- ===== RUN DETAIL ===== -->
     <section id="view-detail" hidden>
       <div class="page-bar">
@@ -20737,6 +22897,8 @@ const CSS = `
      pass/fail ones, and read as a different kind of thing. */
   .badge.dr-found { background: var(--amber-bg); color: var(--amber); border-color: var(--amber-border); }
   .badge.dr-found .d { background: var(--amber); }
+  .badge.uncov { background: var(--amber-bg); color: var(--amber); border-color: var(--amber-border); }
+  .badge.uncov .d { background: var(--amber); }
   .badge.dr-clean { background: var(--pass-bg); color: var(--pass); border-color: var(--pass-border); }
   .badge.dr-clean .d { background: var(--pass); }
   .badge.dr-unknown { background: var(--surface-3); color: var(--muted); border-color: var(--border); }
@@ -20839,6 +23001,13 @@ const CSS = `
   .artifact-acc > summary { height: 34px; }
   .artifact-pre { margin: 2px 0 8px; padding: 10px 12px; background: var(--surface-2); border: 1px solid var(--border); border-radius: var(--radius-sm); font-family: var(--mono); font-size: 11.5px; line-height: 1.5; max-height: 320px; overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; }
   .section-label { font-size: 12px; font-weight: 600; color: var(--muted); margin-top: 4px; }
+  /* reached files: what the spec actually executed, plus what could not be placed */
+  .cov-counts { display: flex; flex-wrap: wrap; gap: 6px; padding: 2px 0 8px; }
+  .cov-count { font-size: 11px; color: var(--muted); border: 1px solid var(--border); border-radius: var(--radius-sm); padding: 1px 7px; white-space: nowrap; }
+  .cov-count b { color: var(--fg-dim); font-variant-numeric: tabular-nums; }
+  .cov-count.cov-warn { color: var(--fail); border-color: var(--fail); }
+  .cov-file { font-family: var(--mono); font-size: 12px; padding: 4px 4px; border-bottom: 1px solid var(--border); overflow-wrap: anywhere; }
+  .cov-file:last-child { border-bottom: none; }
   /* live run steps: stacked cards with large before/after frames */
   .step-card { border: 1px solid var(--border); border-left: 3px solid var(--border-strong); border-radius: var(--radius-sm); background: var(--surface-2); padding: 12px 14px; margin-top: 10px; }
   .step-card.passed { border-left-color: var(--border-strong); }
@@ -21132,6 +23301,38 @@ const CSS = `
   .d-note { margin-top: 12px; max-width: 900px; }
 
   .tblcard { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius); overflow: hidden; }
+
+  /* ── coverage: file tree ─────────────────────────────────────────── */
+  .cov-note { font-size: 12.5px; color: var(--amber); background: var(--amber-bg); border: 1px solid var(--amber-border); border-radius: var(--radius-md); padding: 8px 12px; }
+  .cov-split { display: grid; grid-template-columns: minmax(360px, 7fr) 5fr; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); overflow: hidden; }
+  .cov-treewrap { overflow-y: auto; max-height: 560px; padding: 6px 0; border-right: 1px solid var(--border); }
+  .cov-treewrap ul { list-style: none; margin: 0; padding: 0; }
+  .cov-treewrap ul ul { border-left: 1px solid var(--border); margin-left: 19px; }
+  .cov-row { display: flex; align-items: center; gap: 7px; width: 100%; padding: 3px 14px 3px 8px; border: 0; background: none; text-align: left; font-size: 13px; }
+  .cov-row:hover { background: var(--surface-2); }
+  .cov-row.sel { background: var(--info-bg); box-shadow: inset 2px 0 0 var(--info); }
+  .cov-row .chev { width: 12px; height: 12px; flex: none; color: var(--muted-2); transition: transform 0.15s; }
+  .cov-row .chev.open { transform: rotate(90deg); }
+  .cov-row svg.ic { width: 15px; height: 15px; flex: none; color: var(--muted-2); stroke-width: 1.7; fill: none; stroke: currentColor; }
+  .cov-row .nm { font-family: var(--mono); font-size: 12.5px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+  .cov-row .nm.dim { color: var(--muted); }
+  .cov-row .sp { flex: 1; }
+  .cov-row .dot { width: 7px; height: 7px; border-radius: 50%; flex: none; }
+  .cov-row .dot.ok { background: var(--pass); }
+  .cov-row .dot.no { background: var(--amber-fill); }
+  .cov-row .minibar { width: 60px; height: 5px; border-radius: 3px; background: var(--surface-3); overflow: hidden; flex: none; }
+  .cov-row .minibar i { display: block; height: 100%; background: var(--pass); }
+  .cov-row .frac { font-size: 11px; color: var(--muted); font-family: var(--mono); font-variant-numeric: tabular-nums; white-space: nowrap; min-width: 52px; text-align: right; flex: none; }
+  .cov-detail { padding: 16px 18px; overflow-y: auto; max-height: 560px; }
+  .cov-detail .ph { color: var(--muted-2); font-size: 13px; padding: 30px 10px; text-align: center; }
+  .cov-detail h4 { font-size: 13px; font-family: var(--mono); font-weight: 600; margin: 0 0 4px; word-break: break-all; }
+  .cov-detail .meta { font-size: 12.5px; color: var(--muted); margin-bottom: 12px; }
+  .cov-caselist { border-top: 1px solid var(--border); }
+  .cov-caselist a { display: flex; align-items: center; gap: 10px; padding: 8px 2px; border-bottom: 1px solid var(--border); text-decoration: none; font-size: 13px; color: inherit; }
+  .cov-caselist a:hover { background: var(--surface-2); }
+  .cov-caselist .cs { font-family: var(--mono); font-size: 12.5px; flex: 1; min-width: 0; word-break: break-all; }
+  .cov-hint { margin-top: 12px; padding: 9px 13px; border-radius: var(--radius-md); background: var(--amber-bg); border: 1px solid var(--amber-border); color: var(--amber); font-size: 12.5px; }
+  @media (max-width: 900px) { .cov-split { grid-template-columns: 1fr; } .cov-treewrap { border-right: 0; border-bottom: 1px solid var(--border); } }
   /* Badges across a case row must land on one line. Some of these cells carry
      only a badge, others a badge plus a sub-line (sha · when) or a two-line
      explanation, so middle-aligning the cells put each badge at a different
@@ -21238,7 +23439,20 @@ const CLIENT_JS = `
   var I18N = {
     en: {
       "nav.projects": "Projects", "nav.runs": "Runs", "nav.perspectives": "Perspectives", "nav.secrets": "Secrets",
-      "nav.prompts": "Prompts", "nav.learning": "Learning",
+      "nav.prompts": "Prompts", "nav.learning": "Learning", "nav.coverage": "Coverage",
+      "coverage.title": "Coverage",
+      "coverage.loading": "Loading coverage…",
+      "coverage.none": "No run with coverage yet. Run with --coverage and push the report to this hub.",
+      "coverage.search": "Filter by file path…",
+      "coverage.filter.uncovered": "Uncovered only",
+      "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.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",
+      "coverage.noHit": "No matching files.",
+      "coverage.case": "case", "coverage.cases": "cases",
       "app.project": "project", "app.profile": "profile", "app.disconnect": "Disconnect", "app.noProject": "no project",
       "app.newProfile": "New profile",
       "login.title": "Connect to your hub", "login.sub": "Enter your bearer token to continue.",
@@ -21267,6 +23481,27 @@ const CLIENT_JS = `
       "acc.reasoning": "Reasoning", "acc.evidence": "Evidence", "acc.steps": "Live run steps",
       "acc.assertions": "Assertions",
       "acc.artifacts": "Artifacts",
+      "acc.coverage": "Reached files",
+      "acc.coverage.hint": "Measured, not inferred: V8's counters in the browser and per-request instrumentation on the server.",
+      "cov.frontend": "browser", "cov.backend": "server",
+      "cov.unattributed": "server executions outside this spec's context",
+      "cov.unmappedScripts": "scripts with no usable source map",
+      "cov.unmappedRanges": "executed ranges that mapped nowhere",
+      "cov.outsideProject": "browser sources outside the project",
+      "cov.unresolvedSources": "browser sources that resolved to no project path",
+      "cov.uninstrumentedFiles": "server files that could not be instrumented",
+      "cov.uninstrumentedProcesses": "server processes that instrumented nothing at all",
+      "cov.droppedPushes": "reports the application could not deliver",
+      "cov.unmappedActorEvents": "events from identities this project does not declare",
+      "cov.outsideWindowEvents": "events from a declared identity outside its turn",
+      "cov.excludedDependencies": "dependency sources, excluded on purpose",
+      "cov.route.carrier": "attributed by carrier",
+      "cov.route.actorWindow": "actor-window",
+      "cov.route.events": "events",
+      "cov.noBackend": "no instrumented server process reported",
+      "cov.noFrontend": "the browser produced no result",
+      "cov.frontendStopped": "browser collection stopped early",
+      "cov.unavailable": "Nothing was measured:",
       "art.open": "Open", "art.loadFailed": "could not load (it may have been omitted from the push)",
       "acc.assertions.hint": "Test cases from the recorded spec run",
       "spec.kind.live": "Live", "spec.kind.det": "Deterministic",
@@ -21427,7 +23662,20 @@ const CLIENT_JS = `
     },
     ja: {
       "nav.projects": "プロジェクト", "nav.runs": "実行", "nav.perspectives": "テスト観点", "nav.secrets": "シークレット",
-      "nav.prompts": "プロンプト", "nav.learning": "学習",
+      "nav.prompts": "プロンプト", "nav.learning": "学習", "nav.coverage": "カバレッジ",
+      "coverage.title": "カバレッジ",
+      "coverage.loading": "カバレッジを読み込み中…",
+      "coverage.none": "カバレッジ付きの run がまだありません。--coverage で計測し、レポートをこの hub に push してください。",
+      "coverage.search": "ファイルパスで絞り込み…",
+      "coverage.filter.uncovered": "未到達のみ",
+      "coverage.reached": "到達", "coverage.uncovered": "未到達", "coverage.files": "ファイル",
+      "coverage.measured": "計測", "coverage.specsCombined": "spec 合算",
+      "coverage.noUniverse": "この計測にはファイル台帳が付いていないため、到達したファイルのみ表示しています。未到達は判定できません。",
+      "coverage.placeholder": "ファイルを選択すると、到達しているケースが表示されます",
+      "coverage.fileUncovered": "この計測では、どのケースもこのファイルに到達しませんでした。",
+      "coverage.casesReach": "ケースが到達",
+      "coverage.noHit": "一致するファイルがありません。",
+      "coverage.case": "ケース", "coverage.cases": "ケース",
       "app.project": "プロジェクト", "app.profile": "プロファイル", "app.disconnect": "切断", "app.noProject": "プロジェクト未選択",
       "app.newProfile": "新規プロファイル",
       "login.title": "ハブに接続", "login.sub": "続けるにはベアラートークンを入力してください。",
@@ -21456,6 +23704,27 @@ const CLIENT_JS = `
       "acc.reasoning": "推論", "acc.evidence": "根拠", "acc.steps": "実行ステップ",
       "acc.assertions": "アサーション",
       "acc.artifacts": "成果物",
+      "acc.coverage": "到達ファイル",
+      "acc.coverage.hint": "推定ではなく実測。ブラウザは V8 のカウンタ、サーバはリクエスト単位の計装。",
+      "cov.frontend": "ブラウザ", "cov.backend": "サーバ",
+      "cov.unattributed": "この spec の文脈外で走ったサーバ実行",
+      "cov.unmappedScripts": "source map を辿れなかったスクリプト",
+      "cov.unmappedRanges": "どこにも対応しなかった実行範囲",
+      "cov.outsideProject": "プロジェクト外に解決したブラウザのソース",
+      "cov.unresolvedSources": "プロジェクト内のパスに解決できなかったブラウザのソース",
+      "cov.uninstrumentedFiles": "計装できなかったサーバのファイル",
+      "cov.uninstrumentedProcesses": "何も計装できなかったサーバのプロセス",
+      "cov.droppedPushes": "アプリが送信できなかった報告",
+      "cov.unmappedActorEvents": "このプロジェクトが宣言していない主体のイベント",
+      "cov.outsideWindowEvents": "宣言済みの主体が持ち時間の外で起こしたイベント",
+      "cov.excludedDependencies": "意図的に除外した依存ライブラリのソース",
+      "cov.route.carrier": "carrier で帰属",
+      "cov.route.actorWindow": "actor-window",
+      "cov.route.events": "件",
+      "cov.noBackend": "計装されたサーバプロセスからの報告なし",
+      "cov.noFrontend": "ブラウザ側の結果なし",
+      "cov.frontendStopped": "ブラウザ側の収集が途中で停止",
+      "cov.unavailable": "計測できませんでした:",
       "art.open": "開く", "art.loadFailed": "読み込めませんでした（push時に省略された可能性があります）",
       "acc.assertions.hint": "記録したスペック実行のテストケース",
       "spec.kind.live": "ライブ", "spec.kind.det": "決定的",
@@ -22070,8 +24339,8 @@ const CLIENT_JS = `
 
   // ── view routing ────────────────────────────────────────────────────
 
-  var VIEWS = ["projects", "runs", "detail", "perspectives", "secrets", "prompts", "jobs"];
-  var NAV_FOR_VIEW = { projects: ".nav-projects", secrets: ".nav-secrets", prompts: ".nav-prompts", runs: ".nav-runs", detail: ".nav-runs", jobs: ".nav-jobs", perspectives: ".nav-perspectives" };
+  var VIEWS = ["projects", "runs", "detail", "perspectives", "coverage", "secrets", "prompts", "jobs"];
+  var NAV_FOR_VIEW = { projects: ".nav-projects", secrets: ".nav-secrets", prompts: ".nav-prompts", runs: ".nav-runs", detail: ".nav-runs", jobs: ".nav-jobs", perspectives: ".nav-perspectives", coverage: ".nav-coverage" };
   function showView(id) {
     // Any in-flight job poll belongs to the view we're leaving — bump the token
     // so its next tick is a no-op (see pollJob).
@@ -22090,6 +24359,7 @@ const CLIENT_JS = `
     var gated = !state.project;
     document.querySelector(".nav-runs").classList.toggle("disabled", gated);
     document.querySelector(".nav-perspectives").classList.toggle("disabled", gated);
+    document.querySelector(".nav-coverage").classList.toggle("disabled", gated);
     document.querySelector(".nav-secrets").classList.toggle("disabled", gated);
     document.querySelector(".nav-prompts").classList.toggle("disabled", gated);
     document.querySelector(".nav-jobs").classList.toggle("disabled", gated);
@@ -22106,6 +24376,7 @@ const CLIENT_JS = `
     var m = location.hash.match(/^#\\/runs\\/(.+)$/);
     if (m) { openRunDetail(decodeURIComponent(m[1])); return; }
     if (location.hash === "#/perspectives") { openPerspectives(); return; }
+    if (location.hash === "#/coverage") { openCoverage(); return; }
     if (location.hash === "#/secrets") { openSecrets(); return; }
     if (location.hash === "#/prompts") { openPrompts(); return; }
     var j = location.hash.match(/^#\\/jobs\\/(.+)$/);
@@ -22327,6 +24598,287 @@ 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.
+  var covState = { q: "", unc: false, model: null, selected: null, openDirs: null, loadToken: 0 };
+
+  function openCoverage() {
+    if (!state.project) { location.hash = "#/projects"; route(); return; }
+    showView("coverage");
+    if (covState.model) { renderCoverage(); return; }
+    loadCoverage();
+  }
+
+  function loadCoverage() {
+    var token = ++covState.loadToken;
+    var status = document.getElementById("cov-status");
+    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) {
+        if (token !== covState.loadToken) return;
+        if (!found) { status.textContent = t("coverage.none"); return; }
+        covState.model = covBuildModel(found.run, found.report);
+        covState.openDirs = null;
+        covState.selected = null;
+        status.hidden = true;
+        document.getElementById("cov-body").hidden = false;
+        renderCoverage();
+      })
+      .catch(function (err) {
+        if (token !== covState.loadToken) return;
+        status.textContent = "Error loading coverage: " + err.message;
+      });
+  }
+
+  // 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.
+  function covFindReport(runs, i, token) {
+    if (i >= runs.length || i >= 10 || token !== covState.loadToken) return Promise.resolve(null);
+    var run = runs[i];
+    return apiFetch("/api/v1/runs/" + encodeURIComponent(run.id) + "/report").then(function (report) {
+      var measured = !!report.coverageUniverse || (report.results || []).some(function (r) { return r.coverage; });
+      if (measured) return { run: run, report: report };
+      return covFindReport(runs, i + 1, token);
+    }).catch(function () { return covFindReport(runs, i + 1, token); });
+  }
+
+  function covBuildModel(run, report) {
+    // Null-prototype maps throughout: a path segment named "constructor" or
+    // "__proto__" must stay data, not resolve to an inherited property.
+    var byFile = Object.create(null);
+    var measuredSpecs = 0;
+    (report.results || []).forEach(function (row) {
+      if (!row.coverage) return;
+      measuredSpecs++;
+      var key = row.feature + "/" + row.spec;
+      (row.coverage.files || []).forEach(function (path) {
+        (byFile[path] = byFile[path] || []).push(key);
+      });
+    });
+    // universe ∪ reached: the enumeration's filters can never lose a result.
+    var universe = report.coverageUniverse ? report.coverageUniverse.files : null;
+    var all = Object.create(null);
+    (universe || []).forEach(function (path) { all[path] = true; });
+    Object.keys(byFile).forEach(function (path) { all[path] = true; });
+    var root = { name: "", dirs: Object.create(null), files: [], total: 0, covered: 0 };
+    var fileByPath = Object.create(null);
+    Object.keys(all).sort().forEach(function (path) {
+      var parts = path.split("/");
+      var node = root;
+      for (var i = 0; i < parts.length - 1; i++) {
+        node = node.dirs[parts[i]] = node.dirs[parts[i]] || { name: parts[i], dirs: Object.create(null), files: [], total: 0, covered: 0 };
+      }
+      var f = { name: parts[parts.length - 1], path: path, cases: byFile[path] || [] };
+      node.files.push(f);
+      fileByPath[path] = f;
+    });
+    covAnnotate(root);
+    return { run: run, report: report, root: root, fileByPath: fileByPath, hasUniverse: !!universe, measuredSpecs: measuredSpecs };
+  }
+
+  function covAnnotate(node) {
+    node.total = node.files.length;
+    node.covered = node.files.filter(function (f) { return f.cases.length > 0; }).length;
+    Object.keys(node.dirs).forEach(function (k) {
+      covAnnotate(node.dirs[k]);
+      node.total += node.dirs[k].total;
+      node.covered += node.dirs[k].covered;
+    });
+  }
+
+  function covDefaultOpen(model) {
+    // Root and its first level open by default; deeper stays folded until asked.
+    var open = Object.create(null);
+    open[""] = true;
+    Object.keys(model.root.dirs).forEach(function (k) { open[k] = true; });
+    return open;
+  }
+
+  function covFileVisible(f) {
+    if (covState.unc && f.cases.length > 0) return false;
+    if (covState.q && f.path.toLowerCase().indexOf(covState.q) === -1) return false;
+    return true;
+  }
+
+  function renderCoverage() {
+    var model = covState.model;
+    if (!model) return;
+    if (!covState.openDirs) covState.openDirs = covDefaultOpen(model);
+
+    var uncovered = model.root.total - model.root.covered;
+    var pct = model.root.total ? Math.round((model.root.covered / model.root.total) * 100) : 0;
+    var inv = document.getElementById("cov-inv");
+    clear(inv);
+    inv.appendChild(el("b", null, model.hasUniverse ? pct + "%" : String(model.root.covered)));
+    inv.appendChild(document.createTextNode(
+      model.hasUniverse
+        ? " — " + model.root.covered + " / " + model.root.total + " " + t("coverage.files")
+        : " " + t("coverage.files") + " (" + t("coverage.reached") + ")"
+    ));
+    var axis = document.getElementById("cov-axis");
+    clear(axis);
+    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;
+    // 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");
+    uncChip.hidden = !model.hasUniverse;
+    if (!model.hasUniverse && covState.unc) {
+      covState.unc = false;
+      uncChip.setAttribute("aria-pressed", "false");
+    }
+    document.getElementById("cov-unc-n").textContent = model.hasUniverse ? String(uncovered) : "";
+
+    var asof = document.getElementById("cov-asof");
+    var head = model.report.git && model.report.git.head ? String(model.report.git.head).slice(0, 7) : null;
+    asof.textContent = t("coverage.measured") + ": " + relTime(model.report.createdAt) +
+      (head ? " (" + head + ")" : "") + " - " + model.measuredSpecs + " " + t("coverage.specsCombined");
+
+    // The tree is rebuilt from scratch, which would otherwise snap the pane
+    // back to the top on every toggle deep in the hierarchy.
+    var wrap = document.querySelector(".cov-treewrap");
+    var scroll = wrap ? wrap.scrollTop : 0;
+    var host = document.getElementById("cov-tree");
+    clear(host);
+    var ul = document.createElement("ul");
+    var rootLi = covRenderDir(model.root, "");
+    document.getElementById("cov-no-hit").hidden = !!rootLi;
+    if (rootLi) ul.appendChild(rootLi);
+    host.appendChild(ul);
+    if (wrap) wrap.scrollTop = scroll;
+
+    // The detail pane re-renders with the tree: language toggles, refreshes
+    // and filters would otherwise leave it describing the previous state.
+    var sel = covState.selected ? model.fileByPath[covState.selected] : null;
+    if (sel && covFileVisible(sel)) {
+      covShowDetail(sel);
+    } else {
+      covState.selected = null;
+      var detail = document.getElementById("cov-detail");
+      clear(detail);
+      detail.appendChild(el("div", "ph", t("coverage.placeholder")));
+    }
+  }
+
+  function covRenderDir(node, path) {
+    var filtering = covState.unc || !!covState.q;
+    var isOpen = filtering || !!covState.openDirs[path];
+    // A closed, unfiltered directory renders as a single row \u2014 its counts come
+    // from covAnnotate \u2014 so the subtree is not walked at all. At the 20k-file
+    // ceiling that walk is the whole render cost.
+    var subs = [];
+    var visFiles = [];
+    if (isOpen) {
+      visFiles = node.files.filter(covFileVisible);
+      Object.keys(node.dirs).sort().forEach(function (k) {
+        var sub = covRenderDir(node.dirs[k], path ? path + "/" + k : k);
+        if (sub) subs.push(sub);
+      });
+      if (filtering && visFiles.length === 0 && subs.length === 0) return null;
+    }
+    var li = document.createElement("li");
+    if (path !== "") {
+      var row = el("button", "cov-row");
+      row.type = "button";
+      var chev = chevron();
+      if (isOpen) chev.classList.add("open");
+      row.appendChild(chev);
+      row.appendChild(covIcon(true));
+      row.appendChild(el("span", "nm", node.name + "/"));
+      row.appendChild(el("span", "sp"));
+      var mini = el("span", "minibar");
+      var fill = el("i");
+      fill.style.width = (node.total ? Math.round((node.covered / node.total) * 100) : 0) + "%";
+      mini.appendChild(fill);
+      row.appendChild(mini);
+      row.appendChild(el("span", "frac", node.covered + "/" + node.total));
+      row.addEventListener("click", function () {
+        if (covState.openDirs[path]) delete covState.openDirs[path];
+        else covState.openDirs[path] = true;
+        renderCoverage();
+      });
+      li.appendChild(row);
+    }
+    if (isOpen) {
+      var ul = document.createElement("ul");
+      if (path === "") ul.style.marginLeft = "0";
+      subs.forEach(function (sub) { ul.appendChild(sub); });
+      visFiles.forEach(function (f) { ul.appendChild(covRenderFile(f)); });
+      li.appendChild(ul);
+    }
+    return li;
+  }
+
+  function covRenderFile(f) {
+    var li = document.createElement("li");
+    var row = el("button", "cov-row" + (covState.selected === f.path ? " sel" : ""));
+    row.type = "button";
+    row.appendChild(el("span", "chev"));
+    row.appendChild(covIcon(false));
+    row.appendChild(el("span", "nm" + (f.cases.length > 0 ? " dim" : ""), f.name));
+    row.appendChild(el("span", "sp"));
+    row.appendChild(el("span", "dot " + (f.cases.length > 0 ? "ok" : "no")));
+    row.appendChild(el("span", "frac", f.cases.length > 0
+      ? f.cases.length + " " + (f.cases.length === 1 ? t("coverage.case") : t("coverage.cases"))
+      : "0"));
+    row.addEventListener("click", function () {
+      covState.selected = f.path;
+      renderCoverage();
+    });
+    li.appendChild(row);
+    return li;
+  }
+
+  function covIcon(isDir) {
+    var svg = svgIcon();
+    svg.setAttribute("class", "ic");
+    svg.appendChild(svgPath(isDir
+      ? "M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"
+      : "M6 2h8l5 5v13a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z"));
+    return svg;
+  }
+
+  function covShowDetail(f) {
+    var host = document.getElementById("cov-detail");
+    clear(host);
+    var title = el("h4", null, f.path);
+    host.appendChild(title);
+    if (f.cases.length === 0) {
+      var meta = el("div", "meta");
+      var badge = el("span", "badge uncov");
+      badge.appendChild(el("span", "d"));
+      badge.appendChild(document.createTextNode(" " + t("coverage.uncovered")));
+      meta.appendChild(badge);
+      host.appendChild(meta);
+      host.appendChild(el("div", "cov-hint", t("coverage.fileUncovered")));
+      return;
+    }
+    host.appendChild(el("div", "meta", f.cases.length + " " + t("coverage.casesReach")));
+    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.
+    f.cases.forEach(function (key) {
+      var a = document.createElement("a");
+      a.href = "#/runs/" + encodeURIComponent(runId);
+      a.appendChild(el("span", "cs", key));
+      list.appendChild(a);
+    });
+    host.appendChild(list);
+  }
+
   // Entering the view or refreshing it. The spend readout is a fixed window,
   // so a filter change reloads the list alone.
   function loadRuns() {
@@ -22656,6 +25208,75 @@ const CLIENT_JS = `
     return wrap;
   }
 
+  // ── run detail: reached files (--coverage) ─────────────────────────
+  //
+  // The gap counters sit above the list on purpose. Every one of them is an
+  // execution the measurement could not place, and an unplaced execution reads
+  // as "never reached" — the exact answer this section exists to give — so they
+  // belong next to the answer rather than in a log nobody opens.
+  function coverageSection(cov) {
+    var wrap = el("div");
+    wrap.appendChild(el("div", "assertions-hint muted", t("acc.coverage.hint")));
+    var gaps = cov.gaps || {};
+    var counts = el("div", "cov-counts");
+    [
+      { label: t("cov.frontend"), value: cov.frontendFiles, always: true },
+      { label: t("cov.backend"), value: cov.backendFiles, always: true },
+    ].forEach(function (count) {
+      var chip = el("span", "cov-count");
+      chip.appendChild(el("b", null, String(count.value || 0)));
+      chip.appendChild(document.createTextNode(" " + count.label));
+      counts.appendChild(chip);
+    });
+    // Which route the attribution came by. The carrier is always live; a
+    // declared identity is shown even at zero events, because a window that
+    // matched nothing is the failure and an omitted chip would hide it.
+    counts.appendChild(el("span", "cov-count muted", t("cov.route.carrier")));
+    (cov.actorWindows || []).forEach(function (w) {
+      var chip = el("span", w.events ? "cov-count" : "cov-count cov-warn");
+      chip.appendChild(document.createTextNode(t("cov.route.actorWindow") + "(" + w.key + ") "));
+      chip.appendChild(el("b", null, String(w.events || 0)));
+      chip.appendChild(document.createTextNode(" " + t("cov.route.events")));
+      counts.appendChild(chip);
+    });
+    // "That half never answered" and "that half reached nothing" render as the
+    // same zero, so the first is said in words.
+    [
+      { shown: cov.backendReported === false, label: t("cov.noBackend") },
+      { shown: cov.frontendReported === false, label: t("cov.noFrontend") },
+      { shown: cov.frontendStopped === true, label: t("cov.frontendStopped") },
+    ].forEach(function (flag) {
+      if (!flag.shown) return;
+      counts.appendChild(el("span", "cov-count cov-warn", flag.label));
+    });
+    [
+      "unattributed", "unmappedScripts", "unmappedRanges",
+      "outsideProject", "unresolvedSources", "uninstrumentedFiles",
+      "uninstrumentedProcesses", "droppedPushes",
+      "unmappedActorEvents", "outsideWindowEvents",
+    ].forEach(function (key) {
+      if (!gaps[key]) return;
+      var chip = el("span", "cov-count");
+      chip.appendChild(el("b", null, String(gaps[key])));
+      chip.appendChild(document.createTextNode(" " + t("cov." + key)));
+      counts.appendChild(chip);
+    });
+    // Last, and outside the gap list: excluded dependencies are not a hole in
+    // the measurement, and next to ones that are they would drown them out.
+    if (cov.excludedDependencies) {
+      var excluded = el("span", "cov-count muted");
+      excluded.appendChild(el("b", null, String(cov.excludedDependencies)));
+      excluded.appendChild(document.createTextNode(" " + t("cov.excludedDependencies")));
+      counts.appendChild(excluded);
+    }
+    wrap.appendChild(counts);
+    // One insertion for a list that can run to thousands of rows.
+    var files = document.createDocumentFragment();
+    (cov.files || []).forEach(function (f) { files.appendChild(el("div", "cov-file", f)); });
+    wrap.appendChild(files);
+    return wrap;
+  }
+
   // The parts a live step and a deterministic step render identically: the
   // status-railed card, a header (#index + instruction + a status badge unless
   // passed), and an optional "expects:"/reasoning meta block. Returns { card,
@@ -22979,6 +25600,18 @@ const CLIENT_JS = `
       any = true;
     }
 
+    if (r.coverage) {
+      var covFiles = r.coverage.files || [];
+      body.appendChild(detailsBlock(t("acc.coverage"), covFiles.length, coverageSection(r.coverage)));
+      any = true;
+    } else if (r.coverageUnavailable) {
+      // The run measured coverage but this spec could not be: say so, rather
+      // than leave a row that looks like it reached nothing.
+      body.appendChild(el("div", "section-label", t("acc.coverage")));
+      body.appendChild(el("div", "muted", t("cov.unavailable") + " " + r.coverageUnavailable));
+      any = true;
+    }
+
     if (any) card.appendChild(body);
     return card;
   }
@@ -25218,6 +27851,15 @@ const CLIENT_JS = `
   // ── project switching ───────────────────────────────────────────────
 
   function setProject(p) {
+    if (p !== state.project) {
+      // The coverage page caches its model per project; a stale one would
+      // draw the previous project's tree under the new project's header.
+      // Only on a real switch: setLang() calls this with the same project
+      // just to refresh labels.
+      covState.model = null;
+      covState.selected = null;
+      covState.openDirs = null;
+    }
     state.project = p;
     document.getElementById("project-current").textContent = p || "none";
     document.getElementById("sidebar-project").textContent = p || t("app.noProject");
@@ -25561,6 +28203,27 @@ const CLIENT_JS = `
     perspState.q = e.target.value.trim().toLowerCase();
     renderPerspectives();
   });
+
+  // Debounced, unlike persp-q: each keystroke rebuilds the whole tree, and
+  // the universe can hold thousands of files.
+  var covQTimer = null;
+  document.getElementById("cov-q").addEventListener("input", function (e) {
+    var value = e.target.value.trim().toLowerCase();
+    clearTimeout(covQTimer);
+    covQTimer = setTimeout(function () {
+      covState.q = value;
+      renderCoverage();
+    }, 150);
+  });
+  document.getElementById("cov-unc").addEventListener("click", function () {
+    covState.unc = !covState.unc;
+    document.getElementById("cov-unc").setAttribute("aria-pressed", String(covState.unc));
+    renderCoverage();
+  });
+  document.getElementById("cov-refresh").addEventListener("click", function () {
+    covState.model = null;
+    loadCoverage();
+  });
   document.querySelectorAll("#view-perspectives .fchip").forEach(function (b) {
     b.addEventListener("click", function () {
       // renderPerspectives -> syncPerspChips repaints aria-pressed from