ccqa 1.40.8 → 1.41.0

package/dist/bin/ccqa.mjs

@@ -6422,6 +6422,7 @@ var FrontendResolution = class {
 	coverageDir;
 	roots;
 	fetchText;
+	fetchStoredMap;
 	warn;
 	files = /* @__PURE__ */ new Set();
 	/**
@@ -6448,6 +6449,7 @@ var FrontendResolution = class {
 		this.coverageDir = opts.coverageDir;
 		this.roots = opts.roots;
 		this.fetchText = opts.fetchText;
+		this.fetchStoredMap = opts.fetchStoredMap;
 		this.warn = opts.warn;
 	}
 	async absorb(script) {
@@ -6538,24 +6540,46 @@ var FrontendResolution = class {
 	async fetchSourceMap(script) {
 		const source = await script.source();
 		if (source === void 0) return void 0;
+		for (const load of this.sourceMapLoaders(script, source)) {
+			const json = await load();
+			if (json === void 0) continue;
+			const map = parseSourceMap(json);
+			if (map !== void 0) return prepareSourceMap(map, source);
+		}
+	}
+	/**
+	* Ways to get a map for `script`, most authoritative first and none of them
+	* taken until the one before it fails. A map the script points at describes
+	* the code that ran, so the stored copy is only asked for when that is
+	* absent or turns out not to be a map — a catch-all route answers a missing
+	* `.map` with an HTML page, which is a body but not a map. Reading it
+	* eagerly would put a request on the wire for every script of every spec,
+	* nearly all of them misses on a deployment that pushes nothing.
+	*/
+	sourceMapLoaders(script, source) {
+		const loaders = [];
 		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;
+		if (reference !== void 0) {
+			const inline = decodeInlineSourceMap(reference);
+			if (inline !== void 0) loaders.push(() => Promise.resolve(inline));
+			else {
+				const target = absoluteOrUndefined(reference, script.url);
+				if (target !== void 0) loaders.push(() => this.fetchText(target));
 			}
-			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);
+		const stored = this.fetchStoredMap;
+		if (stored !== void 0) loaders.push(() => stored(script.url));
+		return loaders;
 	}
 };
+/** `reference` resolved against the script's URL, or undefined when it is not a URL. */
+function absoluteOrUndefined(reference, scriptUrl) {
+	try {
+		return new URL(reference, scriptUrl).toString();
+	} catch {
+		return;
+	}
+}
 function message$2(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -7149,6 +7173,7 @@ var Engine = class {
 			coverageDir: opts.coverageDir,
 			roots: opts.roots,
 			fetchText: (url) => this.fetchThroughBrowser(url),
+			fetchStoredMap: (scriptUrl) => this.storedMapFor(scriptUrl),
 			warn: opts.warn
 		});
 	}
@@ -7414,6 +7439,23 @@ var Engine = class {
 			return;
 		}
 	}
+	/**
+	* The map a deploy stored for `scriptUrl`, if this run knows where to ask.
+	* Addressed by the path under the asset origin rather than the URL, so the
+	* push and the read agree without either knowing the other's host.
+	*/
+	async storedMapFor(scriptUrl) {
+		const stored = this.opts.fetchStoredSourceMap;
+		if (stored === void 0) return void 0;
+		const assetPath = assetPathOf(scriptUrl, [...this.opts.origins, ...this.opts.assetOrigins ?? []]);
+		if (assetPath === void 0) return void 0;
+		try {
+			return await stored(`${assetPath}.map`);
+		} catch (err) {
+			this.opts.warn(`could not read the stored source map for ${assetPath}: ${message(err)}`);
+			return;
+		}
+	}
 	async readStream(handle, sessionId) {
 		const parts = [];
 		for (;;) {
@@ -7428,6 +7470,25 @@ var Engine = class {
 function message(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+/**
+* The path a stored map is filed under: the URL with its origin removed, and
+* with any deploy-scoped prefix (`/assets/<sha>/`) left in place — that prefix
+* is part of what the browser asked for, so the push has to have used it too.
+* A URL from an origin the run never declared is not ours to look up.
+*/
+function assetPathOf(url, origins) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return;
+	}
+	const path = `${parsed.origin}${parsed.pathname}`;
+	for (const origin of origins) {
+		const base = origin.replace(/\/+$/, "");
+		if (path.startsWith(`${base}/`)) return path.slice(base.length + 1);
+	}
+}
 //#endregion
 //#region src/coverage/universe.ts
 /**
@@ -7503,8 +7564,20 @@ async function walk(abs, rel, out, warn) {
 const SETTLE_POLL_MS = 250;
 const SETTLE_QUIET_POLLS = 10;
 const SETTLE_CAP_MS = 1e4;
+/**
+* Origins with their `${VAR}`s resolved, refusing anything that is not an
+* absolute http(s) URL. An unset variable resolves to the empty string, which
+* would otherwise match nothing and take the feature down without a word.
+*/
+function resolveAbsoluteOrigins(origins, label) {
+	const resolved = origins.map((origin) => resolveEnvRefs(origin));
+	const unresolved = resolved.filter((origin) => !/^https?:\/\//i.test(origin));
+	if (unresolved.length > 0) throw new Error(`${label} must be absolute http(s) URLs after variable substitution; got ${unresolved.join(", ")}`);
+	return resolved;
+}
 var CoverageSession = class CoverageSession {
 	existing = /* @__PURE__ */ new Map();
+	fetchStoredSourceMap;
 	/**
 	* Undefined in hub mode: nothing binds on the runner, and every read-side
 	* answer here stays empty — interpretation lives in the hub's resolve
@@ -7525,13 +7598,15 @@ var CoverageSession = class CoverageSession {
 	cwd;
 	actors;
 	origins;
+	/** Where this project's assets come from — the cookie never goes here. */
+	assetOrigins;
 	/**
 	* The denominator, enumerated once at start, or undefined when
 	* `coverage.include` is unset — and always in hub mode, where it travels as
 	* a `universe` event instead of riding the report envelope.
 	*/
 	universe;
-	constructor(sink, inbox, runId, root, cwd, actors, origins, universe) {
+	constructor(sink, inbox, runId, root, cwd, actors, origins, assetOrigins, universe, fetchStoredSourceMap) {
 		this.sink = sink;
 		this.inbox = inbox;
 		this.runId = runId;
@@ -7539,12 +7614,12 @@ var CoverageSession = class CoverageSession {
 		this.cwd = cwd;
 		this.actors = actors;
 		this.origins = origins;
+		this.assetOrigins = assetOrigins;
 		this.universe = universe;
+		this.fetchStoredSourceMap = fetchStoredSourceMap;
 	}
 	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 origins = resolveAbsoluteOrigins(options.config.instrumentedOrigins, "coverage.instrumentedOrigins");
 		const actors = options.actors ?? NO_ACTORS;
 		let sink;
 		if (options.inbox === void 0) {
@@ -7560,7 +7635,7 @@ var CoverageSession = class CoverageSession {
 			include: [...universe.include],
 			files: [...universe.files]
 		});
-		return new CoverageSession(sink, options.inbox, options.runId, root, options.cwd, actors, origins, options.inbox === void 0 ? universe : void 0);
+		return new CoverageSession(sink, options.inbox, options.runId, root, options.cwd, actors, origins, resolveAbsoluteOrigins(options.config.assetOrigins ?? [], "coverage.assetOrigins"), options.inbox === void 0 ? universe : void 0, options.fetchStoredSourceMap);
 	}
 	/**
 	* Ties the stream's run id to the hub's run record. The session starts
@@ -7635,12 +7710,14 @@ var CoverageSession = class CoverageSession {
 			cdpUrl,
 			specId: specIdFor(this.runId, ref),
 			origins: this.origins,
+			assetOrigins: this.assetOrigins,
 			coverageDir,
 			roots: {
 				base: this.cwd,
 				root: this.root
 			},
-			warn: (text) => warn(`coverage: ${text}`)
+			warn: (text) => warn(`coverage: ${text}`),
+			fetchStoredSourceMap: this.fetchStoredSourceMap
 		});
 	}
 	/**
@@ -10843,6 +10920,177 @@ function readOctal(buf, offset, fieldLen) {
 	return str === "" ? 0 : parseInt(str, 8);
 }
 //#endregion
+//#region src/hub/core/storage/file/fs-helpers.ts
+/**
+* Defense-in-depth for a name this layer joins into a file path. The API's
+* `SAFE_SEGMENT` (api/validate.ts) is deliberately stricter — it also fixes a
+* charset and a length — and stays the rule for what a client may name; this
+* only refuses traversal, so it also covers callers that never came through
+* HTTP (tests, a library embedding the hub).
+*/
+function assertSafeName(value, label) {
+	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
+}
+/** Read and JSON-parse a file, returning `null` when it doesn't exist. Malformed JSON throws. */
+async function readJson(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		if (isNotFound(err)) return null;
+		throw err;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`corrupt JSON at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Write `data` to a temp file in the same directory, then atomically rename it
+* into place, so a concurrent reader only ever observes the old file or the
+* fully-written new one — never the empty/partial window a plain
+* truncate-then-write leaves open (e.g. a `putActualCause` writing a run's
+* triage file while an API request reads it). The temp file lives in the same
+* directory as its target to keep the rename on one filesystem, where it is
+* atomic.
+*/
+async function atomicWrite(path, data) {
+	await mkdir(dirname(path), { recursive: true });
+	const tmp = `${path}.${randomUUID()}.tmp`;
+	await writeFile(tmp, data);
+	await rename(tmp, path);
+}
+/** Write `value` as pretty JSON, creating parent directories as needed. */
+async function writeJson(path, value) {
+	await atomicWrite(path, JSON.stringify(value, null, 2) + "\n");
+}
+/**
+* Per-path serialization for read-modify-write JSON updates. Two concurrent
+* `updateJson` calls on the same path (e.g. two `putActualCause` calls racing
+* on the same run's triage file) would otherwise both read the same starting
+* state and the second writer's change would silently clobber the first's —
+* this queues the second call's read until the first's write has landed, so
+* updates apply in the order they were issued rather than racing. Scoped by
+* path (a `Map` of chained promises), not globally, so unrelated records still
+* update concurrently.
+*/
+const updateChains = /* @__PURE__ */ new Map();
+/**
+* Queue `work` behind whatever is already in flight for `path`. A delete takes
+* the same chain as the updates it removes: `writeJson` recreates the parent
+* directory, so an unordered delete would be silently undone by an update that
+* was already queued.
+*/
+async function serialize(path, work) {
+	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(work);
+	updateChains.set(path, next);
+	try {
+		return await next;
+	} finally {
+		if (updateChains.get(path) === next) updateChains.delete(path);
+	}
+}
+async function updateJson(path, mutate) {
+	return await serialize(path, async () => {
+		const updated = mutate(await readJson(path));
+		await writeJson(path, updated);
+		return updated;
+	});
+}
+/** Read a raw file, returning `null` when it doesn't exist. */
+async function readBytesOrNull(path) {
+	try {
+		const buf = await readFile(path);
+		return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+	} catch (err) {
+		if (isNotFound(err)) return null;
+		throw err;
+	}
+}
+async function writeBytes(path, bytes) {
+	await atomicWrite(path, bytes);
+}
+/** List entry names (files or dirs) directly under `dir`, or `[]` when it doesn't exist. */
+async function listDirOrEmpty(dir) {
+	try {
+		return await readdir(dir);
+	} catch (err) {
+		if (isNotFound(err)) return [];
+		throw err;
+	}
+}
+/**
+* Subdirectory names directly under `dir`, or `[]` when it doesn't exist.
+* Skips files and dot-entries so stray filesystem litter (e.g. a Finder
+* `.DS_Store`) never surfaces as a record id or project name.
+*/
+async function listSubdirsOrEmpty(dir) {
+	try {
+		return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
+	} catch (err) {
+		if (isNotFound(err)) return [];
+		throw err;
+	}
+}
+/** Every file path under `dir`, relative to `dir`, posix-separated. */
+async function listFilesRecursive(dir) {
+	const out = [];
+	async function walk(current) {
+		let entries;
+		try {
+			entries = await readdir(current, { withFileTypes: true });
+		} catch (err) {
+			if (isNotFound(err)) return;
+			throw err;
+		}
+		for (const entry of entries) {
+			const abs = join(current, entry.name);
+			if (entry.isDirectory()) await walk(abs);
+			else if (entry.isFile()) out.push(relative(dir, abs).split(sep).join("/"));
+		}
+	}
+	await walk(dir);
+	return out;
+}
+async function removePath(path) {
+	await rm(path, {
+		recursive: true,
+		force: true
+	});
+}
+function isNotFound(err) {
+	return err instanceof Error && "code" in err && err.code === "ENOENT";
+}
+//#endregion
+//#region src/coverage/frontend/reduce-map.ts
+/**
+* `json` reduced to the readable fields, or undefined when it is not a source
+* map this side can use — the same refusals `parseSourceMap` makes, applied at
+* push time so an unusable map is never stored.
+*/
+function reduceSourceMap(json) {
+	let parsed;
+	try {
+		parsed = JSON.parse(json);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return void 0;
+	const map = parsed;
+	if (map.sections !== void 0) return void 0;
+	if (map.version !== 3) return void 0;
+	if (typeof map.mappings !== "string") return void 0;
+	if (!Array.isArray(map.sources)) return void 0;
+	return {
+		version: 3,
+		sources: map.sources,
+		mappings: map.mappings,
+		...typeof map.sourceRoot === "string" ? { sourceRoot: map.sourceRoot } : {},
+		...typeof map.file === "string" ? { file: map.file } : {}
+	};
+}
+//#endregion
 //#region src/runtime/session-state.ts
 /** Default per-profile sessions root, relative to the project (`--cwd`). */
 const SESSIONS_SUBDIR = ".ccqa/sessions";
@@ -11401,6 +11649,7 @@ const CoverageActorsSchema = z.record(z.string().regex(/^[a-z0-9][a-z0-9._-]*$/i
 */
 const CoverageConfigSchema = z.object({
 	instrumentedOrigins: z.array(z.string().min(1)).min(1),
+	assetOrigins: z.array(z.string().min(1)).optional(),
 	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(),
@@ -12307,6 +12556,49 @@ const varRm = new Command("rm").description("Delete a variable from the hub.").a
 	info(`deleted variable "${name}" from the hub`);
 }));
 const varCommand = new Command("var").description("Manage environment variables stored on the hub (fetched at run time by `ccqa run` / `ccqa record`).").addCommand(varSet).addCommand(varLs).addCommand(varRm);
+const sourcemapPush = new Command("push").description("Upload the source maps a build produced, so `ccqa run --coverage` can name frontend files when the build keeps its maps off the CDN. Only the fields coverage reads are sent — the original source each map carries is dropped rather than stored.").argument("<dir>", "Directory holding the build output (e.g. `.next/static`).").requiredOption("--sha <sha>", "Commit these assets were built from — the same one the deploy is recorded under.").option("--asset-prefix <path>", "Path the files are served under, prepended to each stored path (e.g. `_next/static`). Match what the browser requests, minus the origin.", "").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (dirArg, opts) => {
+	const project = resolveProject(opts);
+	const hub = connect$2(opts);
+	const dir = resolve(resolveCwd(opts.cwd), dirArg);
+	if (!existsSync(dir)) throw new Error(`no such directory: ${dir}`);
+	const maps = (await listFilesRecursive(dir)).filter((f) => f.endsWith(".map"));
+	const prefix = opts.assetPrefix.replace(/^\/+|\/+$/g, "");
+	header("hub sourcemap push", `${project}@${opts.sha.slice(0, 12)}`);
+	meta("dir", dir);
+	if (maps.length === 0) {
+		warn(`no *.map under ${dir} — nothing to push (was the build run with source maps enabled?)`);
+		return;
+	}
+	let pushed = 0;
+	let bytes = 0;
+	const unusable = [];
+	for (const rel of maps) {
+		const reduced = reduceSourceMap(await readFile(join(dir, rel), "utf8"));
+		if (reduced === void 0) {
+			unusable.push(rel);
+			continue;
+		}
+		const body = new TextEncoder().encode(JSON.stringify(reduced));
+		await hub.putSourceMap(project, opts.sha, prefix ? `${prefix}/${rel}` : rel, body);
+		pushed++;
+		bytes += body.length;
+	}
+	if (unusable.length > 0) warn(`${unusable.length} map(s) were not source maps this side can read, e.g. ${unusable[0]}`);
+	await hub.sweepSourceMaps(project);
+	info(`pushed ${pushed} source map(s), ${Math.round(bytes / 1024)} KiB`);
+}));
+const sourcemapLs = new Command("ls").description("List the source maps stored for a commit.").requiredOption("--sha <sha>", "The commit to list.").option(...hubUrlOption).option(...hubTokenOption).option(...projectOption).option(...cwdOption).action(withHubErrors(async (opts) => {
+	const project = resolveProject(opts);
+	const paths = await connect$2(opts).listSourceMaps(project, opts.sha);
+	header("hub sourcemap ls", `${project}@${opts.sha.slice(0, 12)}`);
+	if (paths.length === 0) {
+		info("no source maps stored for this commit");
+		return;
+	}
+	for (const path of paths) meta("", path);
+	info(`${paths.length} source map(s)`);
+}));
+const sourcemapCommand = new Command("sourcemap").description("Manage the source maps coverage reads when a build keeps its maps off the CDN (pushed at deploy time, fetched during `ccqa run --coverage`).").addCommand(sourcemapPush).addCommand(sourcemapLs);
 function validatePromptName(rawName) {
 	if (!isPromptName(rawName)) {
 		error(`invalid prompt name "${rawName}"`);
@@ -12595,7 +12887,7 @@ async function runCoverageInspect(opts) {
 	const outside = Object.entries(h.outsideWindowEvents);
 	if (outside.length > 0) warn(`outside-window events (identity was driven while unclaimed): ${outside.map(([key, count]) => `${key}: ${count}`).join(", ")}`);
 }
-const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(coverageCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand).addCommand(attestCommand).addCommand(dismissCommand);
+const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(coverageCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(sourcemapCommand).addCommand(promptCommand).addCommand(attestCommand).addCommand(dismissCommand);
 /** Loose check that a fetched session is agent-browser storage-state, mirroring loadStorageState. */
 function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
@@ -16730,7 +17022,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, coverageInbox) : void 0;
+	const coverage = opts.coverage && forExecution ? await startCoverage(cwd, projectConfig.coverage, actors, dispatch, opts.teardown, coverageInbox, storedSourceMapReader(hubCtx, deployedSha), hubCtx !== null) : 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}`);
@@ -16933,13 +17225,7 @@ async function executeRun(targets, opts) {
 		reportDir
 	};
 }
-/**
-* 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. With
-* an `inbox`, nothing binds — the run streams its events to the hub instead.
-*/
-async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
+async function startCoverage(cwd, config, actors, dispatch, teardown, inbox, fetchStoredSourceMap, hubConfigured) {
 	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 {
@@ -16949,11 +17235,13 @@ async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
 			config,
 			actors,
 			specs: dispatch.external.flatMap((g) => g.specs),
-			...inbox ? { inbox } : {}
+			...inbox ? { inbox } : {},
+			...fetchStoredSourceMap ? { fetchStoredSourceMap } : {}
 		});
 	} catch (err) {
 		throw new RunUsageError(`could not start coverage collection: ${errMessage(err)}`);
 	}
+	if (fetchStoredSourceMap === void 0 && hubConfigured) warn("coverage: source maps pushed for this deploy cannot be read — the deployed commit is unknown here. Pass --hub-profile so the deploy log can be consulted.");
 	if (inbox !== void 0) meta("coverage", `streaming to hub inbox → ${session.origins.join(", ")}`);
 	else meta("coverage", `sink ${session.sinkUrl} → ${session.origins.join(", ")}`);
 	const unmeasured = dispatch.external.filter((g) => g.browserCoverage.browser === "none").length;
@@ -16962,6 +17250,28 @@ async function startCoverage(cwd, config, actors, dispatch, teardown, inbox) {
 	return session;
 }
 /**
+* 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. With
+* an `inbox`, nothing binds — the run streams its events to the hub instead.
+*/
+/**
+* Needs both a hub and the commit under test: without either there is nothing
+* to address a stored map by, and reading some other commit's maps would name
+* the wrong files. See `SourceMapStore`.
+*/
+function storedSourceMapReader(hubCtx, deployedSha) {
+	if (hubCtx === null || deployedSha === null) return void 0;
+	const seen = /* @__PURE__ */ new Map();
+	return async (assetPath) => {
+		const cached = seen.get(assetPath);
+		if (cached !== void 0 || seen.has(assetPath)) return cached;
+		const map = await hubCtx.hub.getSourceMap(hubCtx.project, deployedSha, assetPath) ?? void 0;
+		seen.set(assetPath, map);
+		return map;
+	};
+}
+/**
 * 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".
@@ -21466,6 +21776,20 @@ function mergeBucket(into, from) {
 //#endregion
 //#region src/hub/core/retention.ts
 /**
+* Drop the source maps of every commit past the newest `maxCommits`.
+*
+* Hung off a push for the same reason run retention hangs off a terminal run:
+* the hub whose disk grows is the one written to constantly and never
+* restarted. Best-effort — a lost sweep costs disk, while failing the push it
+* runs beside would cost the deploy.
+*/
+async function sweepSourceMapRetention(storage, project, maxCommits) {
+	try {
+		const commits = await storage.sourceMaps.listCommits(project);
+		for (const commit of commits.slice(maxCommits)) await storage.sourceMaps.delete(project, commit);
+	} catch {}
+}
+/**
 * Drop everything past the newest `maxRuns` of the (project, branch) that
 * `run` belongs to, taking each evicted run's artifacts and triage records
 * with it.
@@ -22402,6 +22726,58 @@ function createGetDriftLedgerHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/sourcemaps.ts
+/**
+* A source map is roughly the size of the code it describes, and a single
+* bundle chunk can be a few MB. Generous, but still a ceiling: a push is many
+* small requests rather than one archive, so no single body should approach it.
+*/
+const MAX_MAP_BYTES = 32 * 1024 * 1024;
+function createPutSourceMapHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		const assetPath = requireSafeRelPath(ctx.params.path, "source map path");
+		const body = await readBody(ctx.req, MAX_MAP_BYTES);
+		await storage.sourceMaps.put(project, commit, assetPath, body);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+function createGetSourceMapHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		const assetPath = requireSafeRelPath(ctx.params.path, "source map path");
+		const bytes = await storage.sourceMaps.read(project, commit, assetPath);
+		if (!bytes) throw new HttpError(404, "not_found", `no source map stored for "${assetPath}" at ${commit}`);
+		sendBytes(ctx.res, 200, bytes, "application/json; charset=utf-8");
+	};
+}
+/**
+* Ends a push: everything for this commit has landed, so older commits can go.
+* Separate from the PUTs because a push is hundreds of them, and sweeping on
+* each would walk the whole project every time.
+*/
+function createSweepSourceMapsHandler(storage) {
+	return async (ctx) => {
+		await sweepSourceMapRetention(storage, requireSafeSegment(ctx.params.project, "project"), 10);
+		ctx.res.statusCode = 204;
+		ctx.res.end();
+	};
+}
+function createListSourceMapsHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const commit = requireSafeSegment(ctx.params.commit, "commit");
+		sendJson(ctx.res, 200, {
+			project,
+			commit,
+			paths: await storage.sourceMaps.list(project, commit)
+		});
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/deploys.ts
 /** `changedPaths` for a wide refactor can run to tens of thousands of entries. */
 const MAX_DEPLOY_BODY_BYTES = 8 * 1024 * 1024;
@@ -30364,6 +30740,10 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/deploys", createGetDeployLogHandler(storage));
 	router.get("/api/v1/projects/:project/rerun", createGetRerunHandler(storage));
 	router.get("/api/v1/projects/:project/audit-needed", createGetAuditNeedHandler(storage));
+	router.put("/api/v1/projects/:project/sourcemaps/:commit/*path", createPutSourceMapHandler(storage));
+	router.post("/api/v1/projects/:project/sourcemaps/sweep", createSweepSourceMapsHandler(storage));
+	router.get("/api/v1/projects/:project/sourcemaps/:commit", createListSourceMapsHandler(storage));
+	router.get("/api/v1/projects/:project/sourcemaps/:commit/*path", createGetSourceMapHandler(storage));
 	router.post("/api/v1/projects/:project/locks", createAcquireLocksHandler(storage));
 	router.delete("/api/v1/projects/:project/locks", createReleaseLocksHandler(storage));
 	router.get("/api/v1/projects/:project/attestations", createGetAttestationsHandler(storage));
@@ -30418,149 +30798,6 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/learning-jobs/:jobId", createGetLearningJobHandler(storage));
 }
 //#endregion
-//#region src/hub/core/storage/file/fs-helpers.ts
-/**
-* Defense-in-depth for a name this layer joins into a file path. The API's
-* `SAFE_SEGMENT` (api/validate.ts) is deliberately stricter — it also fixes a
-* charset and a length — and stays the rule for what a client may name; this
-* only refuses traversal, so it also covers callers that never came through
-* HTTP (tests, a library embedding the hub).
-*/
-function assertSafeName(value, label) {
-	if (value.length === 0 || value === "." || value === ".." || value.includes("/") || value.includes("\\")) throw new Error(`invalid ${label}: must be a bare name without path separators or '..'`);
-}
-/** Read and JSON-parse a file, returning `null` when it doesn't exist. Malformed JSON throws. */
-async function readJson(path) {
-	let raw;
-	try {
-		raw = await readFile(path, "utf8");
-	} catch (err) {
-		if (isNotFound(err)) return null;
-		throw err;
-	}
-	try {
-		return JSON.parse(raw);
-	} catch (err) {
-		throw new Error(`corrupt JSON at ${path}: ${err instanceof Error ? err.message : String(err)}`);
-	}
-}
-/**
-* Write `data` to a temp file in the same directory, then atomically rename it
-* into place, so a concurrent reader only ever observes the old file or the
-* fully-written new one — never the empty/partial window a plain
-* truncate-then-write leaves open (e.g. a `putActualCause` writing a run's
-* triage file while an API request reads it). The temp file lives in the same
-* directory as its target to keep the rename on one filesystem, where it is
-* atomic.
-*/
-async function atomicWrite(path, data) {
-	await mkdir(dirname(path), { recursive: true });
-	const tmp = `${path}.${randomUUID()}.tmp`;
-	await writeFile(tmp, data);
-	await rename(tmp, path);
-}
-/** Write `value` as pretty JSON, creating parent directories as needed. */
-async function writeJson(path, value) {
-	await atomicWrite(path, JSON.stringify(value, null, 2) + "\n");
-}
-/**
-* Per-path serialization for read-modify-write JSON updates. Two concurrent
-* `updateJson` calls on the same path (e.g. two `putActualCause` calls racing
-* on the same run's triage file) would otherwise both read the same starting
-* state and the second writer's change would silently clobber the first's —
-* this queues the second call's read until the first's write has landed, so
-* updates apply in the order they were issued rather than racing. Scoped by
-* path (a `Map` of chained promises), not globally, so unrelated records still
-* update concurrently.
-*/
-const updateChains = /* @__PURE__ */ new Map();
-/**
-* Queue `work` behind whatever is already in flight for `path`. A delete takes
-* the same chain as the updates it removes: `writeJson` recreates the parent
-* directory, so an unordered delete would be silently undone by an update that
-* was already queued.
-*/
-async function serialize(path, work) {
-	const next = (updateChains.get(path) ?? Promise.resolve()).catch(() => {}).then(work);
-	updateChains.set(path, next);
-	try {
-		return await next;
-	} finally {
-		if (updateChains.get(path) === next) updateChains.delete(path);
-	}
-}
-async function updateJson(path, mutate) {
-	return await serialize(path, async () => {
-		const updated = mutate(await readJson(path));
-		await writeJson(path, updated);
-		return updated;
-	});
-}
-/** Read a raw file, returning `null` when it doesn't exist. */
-async function readBytesOrNull(path) {
-	try {
-		const buf = await readFile(path);
-		return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
-	} catch (err) {
-		if (isNotFound(err)) return null;
-		throw err;
-	}
-}
-async function writeBytes(path, bytes) {
-	await atomicWrite(path, bytes);
-}
-/** List entry names (files or dirs) directly under `dir`, or `[]` when it doesn't exist. */
-async function listDirOrEmpty(dir) {
-	try {
-		return await readdir(dir);
-	} catch (err) {
-		if (isNotFound(err)) return [];
-		throw err;
-	}
-}
-/**
-* Subdirectory names directly under `dir`, or `[]` when it doesn't exist.
-* Skips files and dot-entries so stray filesystem litter (e.g. a Finder
-* `.DS_Store`) never surfaces as a record id or project name.
-*/
-async function listSubdirsOrEmpty(dir) {
-	try {
-		return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name);
-	} catch (err) {
-		if (isNotFound(err)) return [];
-		throw err;
-	}
-}
-/** Every file path under `dir`, relative to `dir`, posix-separated. */
-async function listFilesRecursive(dir) {
-	const out = [];
-	async function walk(current) {
-		let entries;
-		try {
-			entries = await readdir(current, { withFileTypes: true });
-		} catch (err) {
-			if (isNotFound(err)) return;
-			throw err;
-		}
-		for (const entry of entries) {
-			const abs = join(current, entry.name);
-			if (entry.isDirectory()) await walk(abs);
-			else if (entry.isFile()) out.push(relative(dir, abs).split(sep).join("/"));
-		}
-	}
-	await walk(dir);
-	return out;
-}
-async function removePath(path) {
-	await rm(path, {
-		recursive: true,
-		force: true
-	});
-}
-function isNotFound(err) {
-	return err instanceof Error && "code" in err && err.code === "ENOENT";
-}
-//#endregion
 //#region src/hub/core/storage/file/paths.ts
 /**
 * On-disk layout for the local-directory `HubStorage` backend, all rooted
@@ -30598,6 +30835,12 @@ function runMetaPath(root, id) {
 function artifactsRunDir(root, runId) {
 	return join(root, "artifacts", runId);
 }
+function sourceMapProjectDir(root, project) {
+	return join(root, "sourcemaps", project);
+}
+function sourceMapCommitDir(root, project, commit) {
+	return join(sourceMapProjectDir(root, project), commit);
+}
 function jobsDir(root) {
 	return join(root, "jobs");
 }
@@ -30966,6 +31209,56 @@ function parseLine(rawLine) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/sourcemap-store.ts
+/**
+* Defense-in-depth: the HTTP layer validates the asset path before it gets
+* here, but this store joins it onto a directory, so it re-checks rather than
+* trusting the caller.
+*/
+function assertSafeAssetPath(assetPath) {
+	const segments = assetPath.split("/");
+	if (assetPath.length === 0 || assetPath.startsWith("/") || assetPath.includes("\\") || segments.includes("..") || segments.includes(".")) throw new Error("invalid source map path: must be relative, without '.' or '..' segments");
+}
+/** Marks when a commit last received a push; see `listCommits`. */
+const PUSHED_AT = "pushed-at.json";
+function createFileSourceMapStore(root) {
+	return {
+		async put(project, commit, assetPath, bytes) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			assertSafeAssetPath(assetPath);
+			const dir = sourceMapCommitDir(root, project, commit);
+			await writeBytes(join(dir, assetPath), bytes);
+			await writeJson(join(dir, PUSHED_AT), { at: Date.now() });
+		},
+		async read(project, commit, assetPath) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			assertSafeAssetPath(assetPath);
+			return readBytesOrNull(join(sourceMapCommitDir(root, project, commit), assetPath));
+		},
+		async list(project, commit) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			return (await listFilesRecursive(sourceMapCommitDir(root, project, commit))).filter((file) => file !== PUSHED_AT);
+		},
+		async listCommits(project) {
+			assertSafeName(project, "project");
+			const dir = sourceMapProjectDir(root, project);
+			const commits = await listSubdirsOrEmpty(dir);
+			return (await Promise.all(commits.map(async (commit) => ({
+				commit,
+				at: (await readJson(join(dir, commit, PUSHED_AT)).catch(() => null))?.at ?? 0
+			})))).sort((a, b) => b.at - a.at).map((entry) => entry.commit);
+		},
+		async delete(project, commit) {
+			assertSafeName(project, "project");
+			assertSafeName(commit, "commit");
+			await removePath(sourceMapCommitDir(root, project, commit));
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/deploy-store.ts
 function createFileDeployStore(root) {
 	const readLog = async (project, profile) => await readJson(deployLogPath(root, project, profile)) ?? emptyDeployLog();
@@ -31409,7 +31702,8 @@ function createFileHubStorage(dataDir) {
 		spend: createFileSpendStore(dataDir),
 		attestations: createFileAttestationStore(dataDir),
 		auditDismissals: createFileAuditDismissalStore(dataDir),
-		coverageEvents: createFileCoverageEventStore(dataDir)
+		coverageEvents: createFileCoverageEventStore(dataDir),
+		sourceMaps: createFileSourceMapStore(dataDir)
 	};
 }
 //#endregion

package/dist/hub-client/index.d.mts

@@ -1159,6 +1159,16 @@ interface HubClient {
   getCoverage(project: string, q?: {
     runId?: string;
   }): Promise<HubCoverageAnswer>;
+  /**
+   * Source maps for what a commit deployed, addressed by the asset path the
+   * browser requests. Coverage falls back to these when the build keeps its
+   * maps out of the CDN, which is the usual choice — a map hands out source.
+   */
+  putSourceMap(project: string, commit: string, assetPath: string, map: Uint8Array): Promise<void>;
+  getSourceMap(project: string, commit: string, assetPath: string): Promise<string | null>;
+  listSourceMaps(project: string, commit: string): Promise<string[]>;
+  /** Ends a push, letting the hub drop the commits it no longer keeps. */
+  sweepSourceMaps(project: string): Promise<void>;
   getTriage(id: string): Promise<RunTriage>;
   putActualCause(id: string, c: {
     feature: string;

package/dist/hub-client/index.mjs

@@ -153,6 +153,28 @@ function createHubClient(opts) {
 				runId: q.runId
 			})}`);
 		},
+		putSourceMap(project, commit, assetPath, map) {
+			return request(`${sourceMapPath(project, commit)}/${encodeAssetPath(assetPath)}`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: toBodyInit(map)
+			}).then(() => void 0);
+		},
+		async getSourceMap(project, commit, assetPath) {
+			try {
+				return await text(`${sourceMapPath(project, commit)}/${encodeAssetPath(assetPath)}`);
+			} catch (err) {
+				if (err instanceof HubApiError && err.status === 404) return null;
+				throw err;
+			}
+		},
+		sweepSourceMaps(project) {
+			return noBody(`/api/v1/projects/${encodeURIComponent(project)}/sourcemaps/sweep`, "POST");
+		},
+		async listSourceMaps(project, commit) {
+			const { paths } = await json(sourceMapPath(project, commit));
+			return paths;
+		},
 		getTriage(id) {
 			return json(`/api/v1/runs/${encodeURIComponent(id)}/triage`);
 		},
@@ -366,6 +388,17 @@ function auditDismissalsPath(project) {
 function perspectivesPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/perspectives`;
 }
+/** `/api/v1/projects/<project>/sourcemaps/<commit>` — the scope a push and a read share. */
+function sourceMapPath(project, commit) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/sourcemaps/${encodeURIComponent(commit)}`;
+}
+/**
+* Asset paths keep their separators — the route matches the rest of the URL as
+* one wildcard segment — so only the parts between them are escaped.
+*/
+function encodeAssetPath(assetPath) {
+	return assetPath.split("/").map(encodeURIComponent).join("/");
+}
 function queryString(params) {
 	const out = new URLSearchParams();
 	for (const [key, value] of Object.entries(params)) if (value !== void 0) out.set(key, String(value));

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.40.8",
+  "version": "1.41.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.40.8",
+  "version": "1.41.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {