ccqa 1.25.0 → 1.26.0

package/dist/bin/ccqa.mjs

@@ -4780,6 +4780,42 @@ function appendCostRecord(command, cost) {
 		appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
 	} catch {}
 }
+/**
+* Read back what `appendCostRecord` wrote. `null` when the file isn't there:
+* ccqa never ran, which is not the answer "ran and was billed nothing". An
+* unbilled line (`totalCostUsd: null`) adds nothing to the total but is still
+* an invocation — a killed job leaves a half-written last line, which is
+* neither.
+*/
+async function readCostFileTotal(path) {
+	let raw;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (err) {
+		if (err instanceof Error && err.code === "ENOENT") return null;
+		throw err;
+	}
+	let totalUsd = 0;
+	let invocations = 0;
+	let unreadable = 0;
+	for (const line of raw.split("\n")) {
+		if (line.trim().length === 0) continue;
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			unreadable++;
+			continue;
+		}
+		invocations++;
+		if (typeof record.totalCostUsd === "number") totalUsd += record.totalCostUsd;
+	}
+	return {
+		totalUsd,
+		invocations,
+		unreadable
+	};
+}
 //#endregion
 //#region src/cli/draft.ts
 const CATEGORY_LABEL = DRAFT_CATEGORY_LABEL;
@@ -7231,6 +7267,35 @@ AckSchema.extend({
 	profile: z.string(),
 	name: z.string()
 });
+/**
+* What one batch of ccqa invocations spent on Claude, as the job that ran them
+* reported it (see `SpendStore`). `label` is the consumer's name for the batch
+* — its job name — and the only thing that says where the money went.
+*/
+const SpendEntrySchema = z.object({
+	id: z.string(),
+	at: z.string(),
+	costUsd: z.number(),
+	label: z.string(),
+	ciRunId: z.string().optional(),
+	runUrl: z.string().optional()
+});
+z.object({ entries: z.array(SpendEntrySchema).default([]) });
+/** Body of `POST /projects/:project/spend` — one batch's total. `at` defaults to now. */
+const RecordSpendRequestSchema = z.object({
+	costUsd: z.number().nonnegative(),
+	label: z.string().min(1).max(200),
+	at: z.string().refine((v) => !Number.isNaN(Date.parse(v)), "at must be an ISO-8601 instant").optional(),
+	ciRunId: z.string().optional(),
+	runUrl: z.string().optional()
+});
+z.object({
+	project: z.string(),
+	since: z.string().nullable(),
+	until: z.string().nullable(),
+	totalUsd: z.number(),
+	entries: z.array(SpendEntrySchema)
+});
 //#endregion
 //#region src/run/hub-selection.ts
 /**
@@ -8245,6 +8310,19 @@ function githubRunUrl(env = process.env) {
 function githubRunId(env = process.env) {
 	return env["GITHUB_RUN_ID"] ?? null;
 }
+/**
+* The CI provenance every hub record carries, ready to spread into a request
+* body. Empty outside Actions, so a local invocation sends neither field
+* rather than a null one.
+*/
+function ciProvenance(env = process.env) {
+	const ciRunId = githubRunId(env);
+	const runUrl = githubRunUrl(env);
+	return {
+		...ciRunId ? { ciRunId } : {},
+		...runUrl ? { runUrl } : {}
+	};
+}
 //#endregion
 //#region src/cli/deploy-paths.ts
 /**
@@ -9036,6 +9114,36 @@ function describeSelection(selection, diffAvailable) {
 	return `${values.filter((s) => s.verdict === "needed").length} needed / ${values.filter((s) => s.verdict === "unknown").length} unknown / ${values.length} specs`;
 }
 const deployCommand = new Command("deploy").description("Report deploys to the hub, the input behind `ccqa run --only-hub-rerun-needed`.").addCommand(deployRecord);
+const costPush = new Command("push").description("Record what this job spent on Claude: sum the cost file every ccqa invocation appended to ($CCQA_COST_FILE) and push the total to the hub as one spend entry. Run it last, once. A budget reads these totals INSTEAD OF summing the hub's runs: most commands that call Claude leave no run behind, and a batch already includes the ones that do, so adding both double-counts.").requiredOption("--label <name>", "What this batch was — typically the CI job's name. Required: an unlabelled entry tells a reader nothing about where the money went.").option("--from <path>", "Cost file to read. Defaults to $CCQA_COST_FILE.").option("--project <name>", "Project the spend is recorded against. Defaults to the current directory's name.").option(...cwdOption).option(...hubUrlOption).option(...hubTokenOption).action(withHubErrors(runCostPush));
+async function runCostPush(opts) {
+	const path = opts.from ?? process.env.CCQA_COST_FILE;
+	if (!path) {
+		error("no cost file to read (--from <path> or CCQA_COST_FILE)");
+		process.exit(2);
+	}
+	const project = resolveProject(opts);
+	const hub = connect(opts);
+	header("hub cost push", opts.label);
+	meta("project", project);
+	const total = await readCostFileTotal(path);
+	if (total === null) {
+		warn(`no cost file at ${path}; recorded nothing — ccqa never ran here, which is not a spend of zero`);
+		return;
+	}
+	if (total.invocations === 0) {
+		warn(`${path} holds no invocations; recorded nothing`);
+		return;
+	}
+	await hub.recordSpend(project, {
+		costUsd: total.totalUsd,
+		label: opts.label,
+		...ciProvenance()
+	});
+	meta("invocations", String(total.invocations));
+	if (total.unreadable > 0) warn(`${total.unreadable} line(s) of ${path} could not be read, so the total below is a floor: what they cost is not in it, and the hub now holds the short number`);
+	info(`recorded $${total.totalUsd.toFixed(4)} of spend on the hub`);
+}
+const costCommand = new Command("cost").description("Report what a CI job spent on Claude to the hub — the number a budget reads.").addCommand(costPush);
 const pushCommand = new Command("push").description("Upload the report directory of a finished `ccqa run --report` to the hub as a run. Run this after `ccqa run` (use `if: always()` in CI so failing runs are pushed too).").option("--report-dir <dir>", `Report directory to push. Default: ${DEFAULT_REPORT_DIR}/`).option("--project <name>", "Logical project name for the run. Defaults to the current directory's name.").option("--branch <name>", "Branch label. Defaults to $GITHUB_HEAD_REF / $GITHUB_REF_NAME / current git branch.").option("--profile <name>", "Profile (environment) the run executed against. Recorded for display; runs are not scoped by profile.").option(...hubUrlOption).option(...hubTokenOption).option("--cwd <path>", "Directory the report dir is resolved against (defaults to the current directory).").action(withHubErrors(async (opts) => {
 	const cwd = resolveCwd(opts.cwd);
 	const reportDir = join(cwd, opts.reportDir ?? "ccqa-report");
@@ -9070,7 +9178,7 @@ const pushCommand = new Command("push").description("Upload the report directory
 	meta("specs", `${run.specs.passed}/${run.specs.total} passed`);
 	info(`${resolveBaseUrl(opts)}/#/runs/${run.id}`);
 }));
-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(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
+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(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
 /** 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);
@@ -11929,8 +12037,6 @@ function requireReportToHubConnection(conn) {
 */
 async function openHubRun(kind, conn, cwd, profile) {
 	const [branch, gitHead] = await Promise.all([detectBranch(cwd), getGitHead(cwd)]);
-	const ciRunId = githubRunId();
-	const runUrl = githubRunUrl();
 	try {
 		const run = await conn.hub.openRun({
 			project: conn.project,
@@ -11938,8 +12044,7 @@ async function openHubRun(kind, conn, cwd, profile) {
 			...branch ? { branch } : {},
 			...profile ? { profile } : {},
 			...gitHead ? { gitHead } : {},
-			...ciRunId ? { ciRunId } : {},
-			...runUrl ? { runUrl } : {}
+			...ciProvenance()
 		});
 		return {
 			hub: conn.hub,
@@ -12649,16 +12754,13 @@ async function executeRun(targets, opts) {
 	let hubPublishBroken = false;
 	if (hubCtx != null && opts.reportToHub) try {
 		const branch = await detectBranch(cwd);
-		const ciRunId = githubRunId();
-		const runUrl = githubRunUrl();
 		const opened = await hubCtx.hub.openRun({
 			project: hubCtx.project,
 			...branch ? { branch } : {},
 			...opts.hubProfile ? { profile: opts.hubProfile } : {},
 			...git.head ? { gitHead: git.head } : {},
 			...deployedSha ? { deployedSha } : {},
-			...ciRunId ? { ciRunId } : {},
-			...runUrl ? { runUrl } : {},
+			...ciProvenance(),
 			kind: "run"
 		});
 		hubRunId = opened.id;
@@ -17032,11 +17134,15 @@ function mergeBucket(into, from) {
 //#endregion
 //#region src/hub/api/validate.ts
 /**
-* Validators for URL path parameters that flow into the storage layer's file
-* path construction (secret store scope/name, artifact relative paths).
+* Validators for the request parameters handlers read straight off the wire:
+* the URL path parameters that flow into the storage layer's file path
+* construction (secret store scope/name, artifact relative paths), and the
+* query params bounding a listing's time window.
+*
 * Router params come from `decodeURIComponent`-ed path segments, so a client
-* can put `..`, `/`, or `\` in them — these guards reject anything that
-* could escape the intended directory before it ever reaches disk I/O.
+* can put `..`, `/`, or `\` in them — the path validators below reject
+* anything that could escape the intended directory before it ever reaches
+* disk I/O.
 */
 const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** Validate a single URL path parameter (e.g. `:profile`, `:name`) as a bare name. Throws 400 if unsafe. */
@@ -17051,6 +17157,26 @@ function requireSafeSegment(value, paramName) {
 function requireProfileParam(url) {
 	return requireSafeSegment(url.searchParams.get("profile") ?? "default", "profile");
 }
+/**
+* The `?since=`/`?until=` window a listing takes, in the shape its store's
+* `list` takes it. Half-open on purpose: a caller asking for one day passes
+* that day's start and the next day's start, and no record is counted twice
+* at a boundary.
+*/
+function requireWindowParams(url) {
+	const since = requireInstant(url.searchParams.get("since"), "since");
+	const until = requireInstant(url.searchParams.get("until"), "until");
+	return {
+		...since ? { since } : {},
+		...until ? { until } : {}
+	};
+}
+/** Rejected rather than ignored: a typo would otherwise read as "nothing that day". */
+function requireInstant(raw, name) {
+	if (raw === null || raw === "") return null;
+	if (Number.isNaN(Date.parse(raw))) throw new HttpError(400, "invalid_param", `invalid ${name}: must be an ISO-8601 instant`);
+	return raw;
+}
 /** Validate a `*path`-captured relative path (multiple segments allowed) as safe to join under a root dir. Throws 400 if unsafe. */
 function requireSafeRelPath(relPath, paramName) {
 	const segments = relPath.split("/");
@@ -17426,7 +17552,7 @@ function createPatchRunHandler(config) {
 		sendJson(ctx.res, 200, updated);
 	};
 }
-/** GET /api/v1/runs?project&branch&status&kind&limit */
+/** GET /api/v1/runs?project&branch&status&kind&since&until&limit */
 function createListRunsHandler(storage) {
 	return async (ctx) => {
 		const project = ctx.url.searchParams.get("project");
@@ -17439,6 +17565,7 @@ function createListRunsHandler(storage) {
 			...branch ? { branch } : {},
 			...status ? { status } : {},
 			...kindsRaw ? { kinds: kindsRaw.split(",").map(requireKind) } : {},
+			...requireWindowParams(ctx.url),
 			...limitRaw ? { limit: Number(limitRaw) } : {}
 		});
 		sendJson(ctx.res, 200, { runs: await Promise.all(runs.map((r) => withGradedDrift(storage, r))) });
@@ -18132,7 +18259,7 @@ function createGetAuditNeedHandler(storage) {
 //#endregion
 //#region src/hub/api/handlers/locks.ts
 /** A spec-key list and three short strings; nothing here should approach this. */
-const MAX_BODY_BYTES$2 = 1024 * 1024;
+const MAX_BODY_BYTES$3 = 1024 * 1024;
 /**
 * POST /api/v1/projects/:project/locks?profile=
 *
@@ -18146,7 +18273,7 @@ function createAcquireLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, AcquireLocksRequestSchema, "lock request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$3, AcquireLocksRequestSchema, "lock request");
 		let result = {
 			granted: [],
 			denied: []
@@ -18175,7 +18302,7 @@ function createReleaseLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, ReleaseLocksRequestSchema, "release request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$3, ReleaseLocksRequestSchema, "release request");
 		await storage.locks.update(project, profile, (current) => releaseAll(current, body.holder));
 		ctx.res.writeHead(204).end();
 	};
@@ -18188,7 +18315,7 @@ function createReleaseLocksHandler(storage) {
 * 5000 keys of 256 `\uXXXX`-escaped characters — so a conforming client is
 * never answered 413 by a limit the documented bounds don't mention.
 */
-const MAX_BODY_BYTES$1 = 8 * 1024 * 1024;
+const MAX_BODY_BYTES$2 = 8 * 1024 * 1024;
 function requireAckKey(ctx) {
 	return {
 		project: requireSafeSegment(ctx.params.project, "project"),
@@ -18215,7 +18342,7 @@ function createGetAckHandler(storage) {
 function createPutAckHandler(storage) {
 	return async (ctx) => {
 		const key = requireAckKey(ctx);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, PutAckRequestSchema, "ack body");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, PutAckRequestSchema, "ack body");
 		const ack = await storage.acks.put(key.project, key.profile, key.name, body.keys);
 		sendJson(ctx.res, 200, {
 			...key,
@@ -18224,6 +18351,46 @@ function createPutAckHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/spend.ts
+/** One entry is a handful of short fields; anything larger is a malformed client. */
+const MAX_BODY_BYTES$1 = 4 * 1024;
+/**
+* POST /api/v1/projects/:project/spend
+*
+* What a batch of ccqa invocations cost, as the job that ran them reported it —
+* the number a budget reads instead of summing runs (ADR-0017).
+*/
+function createRecordSpendHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$1, RecordSpendRequestSchema, "spend body");
+		const entry = await storage.spend.append(project, {
+			id: randomUUID(),
+			at: new Date(body.at ?? Date.now()).toISOString(),
+			costUsd: body.costUsd,
+			label: body.label,
+			...body.ciRunId ? { ciRunId: body.ciRunId } : {},
+			...body.runUrl ? { runUrl: body.runUrl } : {}
+		});
+		sendJson(ctx.res, 201, entry);
+	};
+}
+/** GET /api/v1/projects/:project/spend?since=&until= — newest first, plus the window's total. */
+function createGetSpendHandler(storage) {
+	return async (ctx) => {
+		const project = requireSafeSegment(ctx.params.project, "project");
+		const window = requireWindowParams(ctx.url);
+		const entries = await storage.spend.list(project, window);
+		sendJson(ctx.res, 200, {
+			project,
+			since: window.since ?? null,
+			until: window.until ?? null,
+			totalUsd: entries.reduce((sum, e) => sum + e.costUsd, 0),
+			entries
+		});
+	};
+}
+//#endregion
 //#region src/hub/core/rerun.ts
 /**
 * When each deployed commit reached the environment. A baseline read at that
@@ -19060,10 +19227,32 @@ const HTML_BODY = `
       <div class="page-bar">
         <h1 data-i18n="runs.title">Runs</h1>
         <span class="total" id="runs-total-cost" hidden></span>
+        <span class="total" id="runs-capped" hidden></span>
+        <!-- Ruled off from the two above because it counts something else: the
+             project's whole spend, not what the listed runs cost. -->
+        <span class="total apart" id="runs-spend-24h" hidden></span>
         <div class="spacer"></div>
         ${refreshButton("runs-refresh")}
       </div>
       <div class="content">
+        <!-- Deliberately selects and a native date input, not the .fchip
+             toggles the rest of the page uses: these three refetch, and a chip
+             group beside a date box would be the odd one out. Their options
+             are built by syncRunsFilters. -->
+        <div class="toolbar">
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-date" data-i18n="runs.filter.date">Date</label>
+            <input class="fctl" type="date" id="runs-f-date">
+          </div>
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-kind" data-i18n="runs.filter.kind">Kind</label>
+            <select class="fctl" id="runs-f-kind"></select>
+          </div>
+          <div class="fgroup">
+            <label class="fgroup-label" for="runs-f-status" data-i18n="runs.filter.status">Status</label>
+            <select class="fctl" id="runs-f-status"></select>
+          </div>
+        </div>
         <div class="card" id="runs-card">
           <div class="table-wrap">
             <table>
@@ -19424,6 +19613,7 @@ const CSS = `
   .page-bar .back svg { width: 15px; height: 15px; }
   .page-bar .filters { display: flex; gap: 8px; margin-left: 8px; }
   .page-bar .total { font-size: 12px; color: var(--muted); font-variant-numeric: tabular-nums; white-space: nowrap; }
+  .page-bar .total.apart { padding-left: 12px; border-left: 1px solid var(--border); }
   .page-bar .spacer { flex: 1; }
   .content { padding: 18px 24px 48px; }
 
@@ -19852,6 +20042,13 @@ const CSS = `
   .fchip[aria-pressed="true"] { background: var(--accent); color: var(--accent-fg); border-color: var(--accent); }
   .fchip .fcount { margin-left: 6px; font-variant-numeric: tabular-nums; color: var(--muted-2); }
   .fchip[aria-pressed="true"] .fcount { color: var(--accent-fg); opacity: 0.7; }
+  /* A filter control that picks one value out of many (the runs bar's date box
+     and selects), sized to itself — .input is the full-width form field the
+     sheets use, which in a toolbar row swallows the whole line. */
+  .fctl { height: 32px; padding: 0 8px; border: 1px solid var(--border-strong); border-radius: var(--radius-sm); background: var(--surface); color: var(--fg); font: inherit; font-size: 13px; }
+  /* Native chrome (the date picker's glyph, the select's arrow) takes its
+     colours from the color-scheme property, not from any class of ours. */
+  .dark .fctl { color-scheme: dark; }
 
   .chip.live { background: var(--info-bg); color: var(--info); border-color: var(--info-border); }
   .badge.ok { background: var(--pass-bg); color: var(--pass); border-color: var(--pass-border); }
@@ -19956,7 +20153,10 @@ const CLIENT_JS = `
   var PREDICTED_LABELS = ${JSON.stringify(PREDICTED_LABELS)};
   var AGENT_BROWSER_TARGET = ${JSON.stringify(AGENT_BROWSER_TARGET)};
   var GUIDANCE_KINDS = ${JSON.stringify(GUIDANCE_KINDS)};
-  var state = { token: "", project: "", profile: "default", detailRunId: "", jobPollToken: 0 };
+  // Every status a run can be in, from the contract that defines them, so the
+  // runs filter offers exactly what a row's badge can say.
+  var RUN_STATUSES = ${JSON.stringify(RunStatusSchema.options)};
+  var state = { token: "", project: "", profile: "default", detailRunId: "", jobPollToken: 0, runsLoadToken: 0, spendLoadToken: 0 };
   var knownProfiles = [];
   var TOKEN_KEY = "ccqa-hub-token";
   var LANG_KEY = "ccqa-hub-lang";
@@ -19981,9 +20181,13 @@ const CLIENT_JS = `
       "projects.title": "Projects", "projects.new": "New project",
       "runs.title": "Runs", "runs.empty": "Select a project to see its runs.",
       "runs.none": "No runs yet for this project.", "projects.none": "No projects yet. Create one to get started.", "projects.noneShort": "No projects yet",
+      "runs.noMatch": "No runs match this filter.",
       "runs.col.run": "Run", "runs.col.branch": "Branch", "runs.col.status": "Status",
       "runs.col.specs": "Specs", "runs.col.cost": "Cost", "runs.col.created": "Created",
-      "runs.totalCost": "Cost of these {n}:",
+      "runs.totalCost": "Cost of these {n}:", "runs.capped": "showing the first {n}",
+      "runs.spend24h": "All spend, last 24h:",
+      "runs.filter.date": "Date", "runs.filter.kind": "Kind", "runs.filter.status": "Status",
+      "runs.filter.all": "All",
       "detail.back": "Runs", "detail.specs": "Specs",
       "detail.download": "Download artifacts",
       "detail.triage": "Triage",
@@ -20140,9 +20344,13 @@ const CLIENT_JS = `
       "projects.title": "プロジェクト", "projects.new": "新規プロジェクト",
       "runs.title": "実行", "runs.empty": "プロジェクトを選択すると実行一覧が表示されます。",
       "runs.none": "このプロジェクトにはまだ実行がありません。", "projects.none": "まだプロジェクトがありません。作成して始めましょう。", "projects.noneShort": "プロジェクトなし",
+      "runs.noMatch": "条件に一致する実行はありません。",
       "runs.col.run": "実行", "runs.col.branch": "ブランチ", "runs.col.status": "ステータス",
       "runs.col.specs": "スペック", "runs.col.cost": "コスト", "runs.col.created": "作成",
-      "runs.totalCost": "この {n} 件のコスト:",
+      "runs.totalCost": "この {n} 件のコスト:", "runs.capped": "先頭 {n} 件のみ表示",
+      "runs.spend24h": "直近 24 時間の全支出:",
+      "runs.filter.date": "日付", "runs.filter.kind": "種類", "runs.filter.status": "結果",
+      "runs.filter.all": "すべて",
       "detail.back": "実行", "detail.specs": "スペック",
       "detail.download": "アーティファクトをダウンロード",
       "detail.triage": "トリアージ",
@@ -20310,6 +20518,9 @@ const CLIENT_JS = `
     for (var i = 0; i < nodes.length; i++) { nodes[i].textContent = t(nodes[i].getAttribute("data-i18n")); }
     var phs = document.querySelectorAll("[data-i18n-ph]");
     for (var j = 0; j < phs.length; j++) { phs[j].placeholder = t(phs[j].getAttribute("data-i18n-ph")); }
+    // The runs filters' options are built rather than marked up, so they are
+    // not reached by the two loops above.
+    syncRunsFilters();
     document.documentElement.lang = lang;
   }
 
@@ -20777,13 +20988,58 @@ const CLIENT_JS = `
 
   // ── runs list ────────────────────────────────────────────────────────
 
+  var RUNS_LIMIT = 50;
+  // Outlives every render, so a refresh or a language switch comes back to the
+  // list the operator was looking at.
+  var runsFilter = { date: "", kind: "", status: "" };
+  function runsFilterActive() { return !!(runsFilter.date || runsFilter.kind || runsFilter.status); }
+
+  function runsQuery() {
+    var q = "/api/v1/runs?project=" + encodeURIComponent(state.project) + "&limit=" + RUNS_LIMIT;
+    if (runsFilter.kind) q += "&kind=" + encodeURIComponent(runsFilter.kind);
+    if (runsFilter.status) q += "&status=" + encodeURIComponent(runsFilter.status);
+    if (runsFilter.date) {
+      // The picked day becomes [local midnight, next local midnight). The API
+      // takes instants and carries no timezone, so the day has to be resolved
+      // here — against the clock of whoever picked it.
+      var p = runsFilter.date.split("-");
+      var start = new Date(+p[0], +p[1] - 1, +p[2]);
+      var next = new Date(+p[0], +p[1] - 1, +p[2] + 1);
+      q += "&since=" + encodeURIComponent(start.toISOString()) + "&until=" + encodeURIComponent(next.toISOString());
+    }
+    return q;
+  }
+
+  // Both selects take their values from the tables that label the rows, so a
+  // filter cannot name a kind or a status differently from the run it hides.
+  // Called on boot and on a language switch — the only times the labels move.
+  function syncRunsFilters() {
+    document.getElementById("runs-f-date").value = runsFilter.date;
+    fillRunsFilter("runs-f-kind", Object.keys(KINDS), function (k) { return t(kindOf(k).label); }, runsFilter.kind);
+    fillRunsFilter("runs-f-status", RUN_STATUSES, function (s) { return t("status." + s); }, runsFilter.status);
+  }
+
+  function fillRunsFilter(id, values, labelOf, selected) {
+    var sel = document.getElementById(id);
+    clear(sel);
+    var any = el("option", null, t("runs.filter.all"));
+    any.value = "";   // the empty value is what the query omits
+    sel.appendChild(any);
+    values.forEach(function (v) {
+      var opt = el("option", null, labelOf(v));
+      opt.value = v;
+      sel.appendChild(opt);
+    });
+    sel.value = selected;
+  }
+
   // What the listed runs cost together — the accumulating number an operator
   // reads to decide how often CI should run, so it follows whatever filter
   // produced the list. Hidden when no listed run carries a cost at all, since
   // a "$0.0000" total would read as "CI is free" rather than "nothing measured".
   //
-  // The label names the run count on purpose. The list is capped (limit=50), so
-  // an unqualified "total" would quietly under-report a project's spend the
+  // The label names the run count on purpose. The list is capped (RUNS_LIMIT),
+  // so an unqualified "total" would quietly under-report a project's spend the
   // moment it has more runs than that — the one number this feature exists to
   // get right.
   function renderRunsTotalCost(runs) {
@@ -20805,14 +21061,38 @@ const CLIENT_JS = `
     }
   }
 
+  // The project's whole spend over the last 24 hours — deliberately not the
+  // list's window or filter: the two numbers differ by everything that calls
+  // Claude without leaving a run behind, which is why both are here. Hidden
+  // when nothing was reported, since "$0.0000" would claim a free day.
+  function loadRunsSpend() {
+    var span = document.getElementById("runs-spend-24h");
+    span.hidden = true;
+    var token = ++state.spendLoadToken;
+    var since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    apiFetch("/api/v1/projects/" + encodeURIComponent(state.project) + "/spend?since=" + encodeURIComponent(since))
+      .then(function (data) {
+        if (token !== state.spendLoadToken) return;
+        if (!data.entries.length) return;
+        span.hidden = false;
+        span.textContent = t("runs.spend24h") + " " + costText(data.totalUsd);
+      })
+      .catch(function () { /* the runs list is the page; a missing total must not replace it with an error */ });
+  }
+
   function renderRunsList(runs) {
     var tbody = document.getElementById("runs-tbody");
     clear(tbody);
     renderRunsTotalCost(runs);
+    // A full page is almost certainly a truncated one, and under a date filter
+    // that turns the total beside it into a day's spend that stops at the cap.
+    var capped = document.getElementById("runs-capped");
+    capped.hidden = runs.length < RUNS_LIMIT;
+    capped.textContent = t("runs.capped").replace("{n}", RUNS_LIMIT);
     var empty = document.getElementById("runs-empty");
     if (runs.length === 0) {
       empty.hidden = false;
-      empty.textContent = t("runs.none");
+      empty.textContent = t(runsFilterActive() ? "runs.noMatch" : "runs.none");
       return;
     }
     empty.hidden = true;
@@ -20879,19 +21159,33 @@ const CLIENT_JS = `
     });
   }
 
-  function loadRuns() {
-    var empty = document.getElementById("runs-empty");
-    empty.hidden = true;
-    apiFetch("/api/v1/runs?project=" + encodeURIComponent(state.project) + "&limit=50")
-      .then(function (data) { renderRunsList(data.runs); })
+  // Compared against the live token before painting, so a slower earlier
+  // response cannot land last: holding an arrow key down in the date box fires
+  // one request per day passed, and the table would end up on the wrong one.
+  function loadRunsList() {
+    var token = ++state.runsLoadToken;
+    document.getElementById("runs-empty").hidden = true;
+    apiFetch(runsQuery())
+      .then(function (data) {
+        if (token !== state.runsLoadToken) return;
+        renderRunsList(data.runs);
+      })
       .catch(function (err) {
-        clear(document.getElementById("runs-tbody"));
-        renderRunsTotalCost([]);
+        if (token !== state.runsLoadToken) return;
+        renderRunsList([]);
+        var empty = document.getElementById("runs-empty");
         empty.hidden = false;
         empty.textContent = "Error loading runs: " + err.message;
       });
   }
 
+  // Entering the view or refreshing it. The spend readout is a fixed window,
+  // so a filter change reloads the list alone.
+  function loadRuns() {
+    loadRunsSpend();
+    loadRunsList();
+  }
+
   // ── run detail: header ──────────────────────────────────────────────
 
   function renderRunHead(run) {
@@ -23720,6 +24014,14 @@ const CLIENT_JS = `
 
   document.getElementById("detail-back").addEventListener("click", function () { location.hash = "#/runs"; });
   document.getElementById("runs-refresh").addEventListener("click", loadRuns);
+  // Every control refetches: the window and the kinds are the server's to
+  // apply, so filtering client-side would only narrow the same capped page.
+  [["runs-f-date", "date"], ["runs-f-kind", "kind"], ["runs-f-status", "status"]].forEach(function (pair) {
+    document.getElementById(pair[0]).addEventListener("change", function (e) {
+      runsFilter[pair[1]] = e.target.value;
+      loadRunsList();
+    });
+  });
   document.getElementById("learn-run").addEventListener("click", startLearn);
   document.getElementById("jobs-refresh").addEventListener("click", loadJobs);
   // Wrap so the click PointerEvent isn't passed as loadSecrets' statusAfter
@@ -24192,6 +24494,8 @@ function registerRoutes(router, config, queue) {
 	router.delete("/api/v1/projects/:project/locks", createReleaseLocksHandler(storage));
 	router.get("/api/v1/projects/:project/acks/:name", createGetAckHandler(storage));
 	router.put("/api/v1/projects/:project/acks/:name", createPutAckHandler(storage));
+	router.post("/api/v1/projects/:project/spend", createRecordSpendHandler(storage));
+	router.get("/api/v1/projects/:project/spend", createGetSpendHandler(storage));
 	const sessionConfig = {
 		store: storage.sessions,
 		encryptionKey: config.encryptionKey
@@ -24376,6 +24680,7 @@ function isNotFound(err) {
 *   deploys/<project>/<profile>/log.json         (DeployLog, ring-buffered)
 *   deploys/<project>/<profile>/touch.json       (SpecTouchIndex derived from the log)
 *   acks/<project>/<profile>/<name>.json         (Ack: a consumer's acted-on keys)
+*   spend/<project>.json                         (SpendLog, pruned to its retention window)
 *
 * IDs and names are validated by their callers (run ids are server-minted
 * UUIDs; project/profile/name come from validated request params) before
@@ -24470,6 +24775,9 @@ function specLocksPath(root, project, profile) {
 function ackPath(root, project, profile, name) {
 	return join(root, "acks", project, profile, `${name}.json`);
 }
+function spendPath(root, project) {
+	return join(root, "spend", `${project}.json`);
+}
 //#endregion
 //#region src/hub/core/storage/file/ack-store.ts
 function assertSafeKey(project, profile, name) {
@@ -24752,6 +25060,22 @@ function createFilePromptStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/time-window.ts
+/**
+* The half-open `[since, until)` window the run and spend listings both take,
+* as a predicate over a record's ISO-8601 timestamp. Compared as instants, not
+* as strings: the ends come off the wire in whatever offset the caller wrote
+* them in, while the stored field is always UTC.
+*/
+function windowFilter(q) {
+	const from = q.since === void 0 ? null : Date.parse(q.since);
+	const to = q.until === void 0 ? null : Date.parse(q.until);
+	return (at) => {
+		const instant = Date.parse(at);
+		return (from === null || instant >= from) && (to === null || instant < to);
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/run-store.ts
 /**
 * Read one run record for an aggregate scan, tolerating a bad entry: a
@@ -24784,8 +25108,12 @@ function createFileRunStore(root) {
 				};
 			});
 		},
-		async list({ project, branch, status, kinds, limit }) {
+		async list({ project, branch, status, kinds, since, until, limit }) {
 			const ids = await listSubdirsOrEmpty(runsDir(root));
+			const inWindow = windowFilter({
+				since,
+				until
+			});
 			const runs = [];
 			for (const id of ids) {
 				const run = await readRunOrSkip(root, id);
@@ -24794,6 +25122,7 @@ function createFileRunStore(root) {
 				if (branch !== void 0 && run.branch !== branch) continue;
 				if (status !== void 0 && run.status !== status) continue;
 				if (kinds !== void 0 && !kinds.includes(run.kind)) continue;
+				if (!inWindow(run.createdAt)) continue;
 				runs.push(run);
 			}
 			runs.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
@@ -24866,6 +25195,55 @@ function createFileSecretStore(root, kind) {
 		}
 	};
 }
+/** Spend storage: one JSON document per project, pruned as it is appended to. */
+function createFileSpendStore(root) {
+	return {
+		async append(project, entry) {
+			assertSafeName(project, "project");
+			const path = spendPath(root, project);
+			const cutoff = Date.now() - 2160 * 60 * 60 * 1e3;
+			await updateJson(path, (current) => {
+				return { entries: [...readEntries(current, path).filter((e) => Date.parse(e.at) >= cutoff && !supersededBy(e, entry)), entry] };
+			});
+			return entry;
+		},
+		async list(project, window) {
+			assertSafeName(project, "project");
+			const path = spendPath(root, project);
+			const inWindow = windowFilter(window);
+			return readEntries(await readJson(path), path).filter((e) => inWindow(e.at)).sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+		}
+	};
+}
+/**
+* A second push from the same CI run under the same label replaces the first
+* rather than adding to it: a retried job really does spend again, but it also
+* rewrites its cost file from scratch, so its new total is the whole of it.
+*/
+function supersededBy(stored, incoming) {
+	return incoming.ciRunId !== void 0 && stored.ciRunId === incoming.ciRunId && stored.label === incoming.label;
+}
+/**
+* Entries parsed one at a time, keeping the survivors: a whole-document parse
+* would answer "this project spent nothing" for one bad entry, and a budget
+* reads that as zero rather than as an error. What is lost is logged, since
+* nothing else would ever say so.
+*/
+function readEntries(raw, path) {
+	if (raw === null || raw === void 0) return [];
+	const stored = raw.entries;
+	if (!Array.isArray(stored)) {
+		console.error(`hub: spend log at ${path} is not a spend document; ignoring what it holds`);
+		return [];
+	}
+	const entries = [];
+	for (const value of stored) {
+		const parsed = SpendEntrySchema.safeParse(value);
+		if (parsed.success) entries.push(parsed.data);
+	}
+	if (entries.length < stored.length) console.error(`hub: skipping ${stored.length - entries.length} unreadable spend entries in ${path}`);
+	return entries;
+}
 //#endregion
 //#region src/hub/core/storage/file/triage-store.ts
 function createFileTriageStore(root) {
@@ -24906,7 +25284,8 @@ function createFileHubStorage(dataDir) {
 		driftLedger: createFileDriftLedgerStore(dataDir),
 		deploys: createFileDeployStore(dataDir),
 		locks: createFileLockStore(dataDir),
-		acks: createFileAckStore(dataDir)
+		acks: createFileAckStore(dataDir),
+		spend: createFileSpendStore(dataDir)
 	};
 }
 //#endregion

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

@@ -396,6 +396,49 @@ declare const DriftLedgerResponseSchema: z.ZodObject<{
   }, z.core.$strip>>;
 }, z.core.$strip>;
 type DriftLedgerResponse = z.infer<typeof DriftLedgerResponseSchema>;
+/**
+ * What one batch of ccqa invocations spent on Claude, as the job that ran them
+ * reported it (see `SpendStore`). `label` is the consumer's name for the batch
+ * — its job name — and the only thing that says where the money went.
+ */
+declare const SpendEntrySchema: z.ZodObject<{
+  id: z.ZodString;
+  at: z.ZodString;
+  costUsd: z.ZodNumber;
+  label: z.ZodString;
+  ciRunId: z.ZodOptional<z.ZodString>;
+  runUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SpendEntry = z.infer<typeof SpendEntrySchema>;
+/** Body of `POST /projects/:project/spend` — one batch's total. `at` defaults to now. */
+declare const RecordSpendRequestSchema: z.ZodObject<{
+  costUsd: z.ZodNumber;
+  label: z.ZodString;
+  at: z.ZodOptional<z.ZodString>;
+  ciRunId: z.ZodOptional<z.ZodString>;
+  runUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RecordSpendRequest = z.infer<typeof RecordSpendRequestSchema>;
+/**
+ * Body of `GET /projects/:project/spend?since=&until=`, newest first. `since`
+ * and `until` echo the window that was asked for (null for an open end), so a
+ * reader of `totalUsd` can tell what it totals.
+ */
+declare const SpendLogResponseSchema: z.ZodObject<{
+  project: z.ZodString;
+  since: z.ZodNullable<z.ZodString>;
+  until: z.ZodNullable<z.ZodString>;
+  totalUsd: z.ZodNumber;
+  entries: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    at: z.ZodString;
+    costUsd: z.ZodNumber;
+    label: z.ZodString;
+    ciRunId: z.ZodOptional<z.ZodString>;
+    runUrl: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type SpendLogResponse = z.infer<typeof SpendLogResponseSchema>;
 //#endregion
 //#region src/prompts/prompt-names.d.ts
 /**
@@ -950,6 +993,16 @@ interface HubClient {
     profile: string;
     limit?: number;
   }): Promise<DeployLogResponse>;
+  /**
+   * Report what one batch of ccqa invocations cost (`ccqa hub cost push`).
+   * Read instead of a sum over runs, never alongside one (ADR-0017).
+   */
+  recordSpend(project: string, body: RecordSpendRequest): Promise<SpendEntry>;
+  /** The project's spend over `[since, until)`, newest first, with the window's total. */
+  getSpend(project: string, q?: {
+    since?: string;
+    until?: string;
+  }): Promise<SpendLogResponse>;
   putSession(project: string, profile: string, name: string, storageState: unknown): Promise<void>;
   getSession(project: string, profile: string, name: string): Promise<unknown>;
   listSessions(project: string, profile: string): Promise<{

package/dist/hub-client/index.mjs

@@ -201,6 +201,19 @@ function createHubClient(opts) {
 				limit: q.limit
 			})}`);
 		},
+		recordSpend(project, body) {
+			return json(spendPath(project), {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		getSpend(project, q = {}) {
+			return json(`${spendPath(project)}?${queryString({
+				since: q.since,
+				until: q.until
+			})}`);
+		},
 		async listProjects() {
 			const { projects } = await json("/api/v1/projects");
 			return projects;
@@ -286,6 +299,9 @@ function promptsPath(project) {
 function deploysPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/deploys`;
 }
+function spendPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/spend`;
+}
 function locksPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/locks`;
 }

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.25.0",
+  "version": "1.26.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.25.0",
+  "version": "1.26.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {