cursedops 0.6.0 → 0.7.1

package/README.md

@@ -13,6 +13,7 @@ bun add cursedops
 | `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent, and the port a LIVE job serves on (`livePort`, 0.5.0) |
 | `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code — the one check no app owns (every address of a deployment serving the same built client), and since 0.5.0 its VERDICTS: the origin asked on loopback, the smoke's own environment, a network that lies about DNS, and a version that has settled |
 | `cursedops/worker-deploy` | the sequence that ships a Cloudflare Worker — clean tree, stage first, schema, `--var` stamp, secrets, smoke — and the readers it needs (0.5.0) |
+| `cursedops/worker-deploy` (CPU) | a `wrangler tail` around the traffic a deploy already sends, each request's BILLED CPU charged to its declared route, red on an undeclared, over-budget or uncapped route — and `runWorkerDeploy`'s `stageWalk` + `cpuTail` that wrap the walk and the smoke in it (0.7.0, task 2134, lifted from collections) |
 | `cursedops/worker-secrets` | a Worker holding EXACTLY its deployment's secrets, uploaded over a pipe, read back (0.5.0) |
 | `cursedops/worker-rollback` | a hostname back on its Mac origin: origin first, route second, the route found rather than typed (0.5.0) |
 | `cursedops/edge-fetch` | a request to a deployed Worker as a script must make it — curl pinned past the Mac's negative DNS cache (0.5.0) |
@@ -418,12 +419,28 @@ most fragile part (a hand-rolled HTTP parser) in two places.
 | `edgeFetch` (curl `--resolve` past the negative DNS cache) | **moved** — `createEdgeFetch`; the Access header now THROWS on an incomplete token instead of sending empty headers |
 | the import's literal and row-for-row proof | **moved** — `sqlLiteral`, `rowDigest`, `sameRows`, `rowDifferences`, `wranglerRows` |
 | the steady `/healthz` wait | **moved**, into `cursedops/smoke` as `steadyHealth` |
+| the Worker CPU tail and its judgement (`worker-cpu.ts` + `workerCpu.ts`) | **moved** (0.7.0, task 2134) — `runWorkerCpuTail`, `judgeTailCapture`, `workerBudgets`; `runWorkerDeploy({ stageWalk, cpuTail })` runs the walk and the smoke under it |
+| the Worker BUDGET TABLE (routes, numbers, the unlock's ceiling) | **stays** — what a route may cost is the app |
 | the deployment table (`workerEnvs.ts`: names, database, URLs, secret map, which file) | **stays** — identity, rule 2 |
 | the smoke's CHECKS (gated-route census, health identity fields, shell/CSP) | **stays** — the same argument as the rest of `smoke` |
 | the walk (`workerWalk.ts`) and the stage walk's grant through `apps/auth-stage` | **stays** — what a signed-in owner does is the app |
 | the import's table PLAN (what is skipped, parents first, what is rebuilt: FTS, `art_lookups`) | **stays** — the app's schema |
 | minting a stage's secret FILE (which keys are copied from production, which are throwaway) | **stays** — `throwawaySecret` and `writeSecretsFile` are the mechanism it uses |
 
+### The Worker CPU check, in `cursedops/worker-deploy` (0.7.0, task 2134)
+
+`collections` wrote it on 2026-09-23 after averaging 489 billed CPU-ms per request with a 15 s
+p99 and every check green; `vault` was measured in the same state the same day (argon2id at
+4,089 CPU-ms per create, 4,458 per unlock, on its stage). The billed number exists only on the
+trace a tail receives, so this tails the Worker around the walk and the smoke, charges each
+request's `cpuTime` to its declared route with `cursedbelt-server/bench`, and fails on an
+undeclared route, one over its budget, or an EXEMPT route past its `noticeAboveMs` (the library
+only notices; a Worker is killed at 30 s of CPU, and a killed unlock reads as a wrong password).
+An exempt route with no ceiling is red on its own. `bench` is passed in (`import * as bench`),
+because `cursedbelt-server` depends on this package. It lives in `worker-deploy` rather than a subpath of its own because a shipped file may not
+import a sibling (`publishShape.test.ts`). An app adopts it with a budget table, a
+ten-line `scripts/worker-cpu.ts`, and `stageWalk` + `cpuTail` on its `runWorkerDeploy` spec.
+
 ## `cursedops/public-surface`
 
 ```sh

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.6.0",
-	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — the API floor that keeps an unmatched /api/... from ever being answered with the app shell, the commit and dirty flag a checkout-served process reports, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof), and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
+	"version": "0.7.1",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — the API floor that keeps an unmatched /api/... from ever being answered with the app shell, the commit and dirty flag a checkout-served process reports, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof, the billed-CPU tail check around a deploy's walk and smoke), and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",

package/src/workerDeploy.ts

@@ -49,7 +49,7 @@
  * Everything that shells out is behind {@link DeployDeps}, so the suite proves the order and every
  * refusal without wrangler, git or a network.
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 
 /** The two deployments every Worker app here has. */
@@ -136,6 +136,18 @@ function readIfThere(path: string): string | null {
 	return existsSync(path) ? readFileSync(path, "utf8") : null;
 }
 
+/**
+ * `command` under the app's Worker CPU wrapper, in the argv {@link parseWorkerCpuArgv} reads.
+ *
+ * 🔴 `--env` is ALWAYS spelled, production included. `bun run <file> -- x` swallows a `--` that
+ * comes straight after the file, so `bun run scripts/worker-cpu.ts -- bun run smoke.ts` reached
+ * the wrapper with no separator and exited on its usage line — measured on collections'
+ * production smoke, 2026-09-23, after the Worker had already shipped (cursedops 0.7.0).
+ */
+export function underCpuTail(wrapper: readonly string[], env: WorkerEnv, command: readonly string[]): string[] {
+	return [...wrapper, "--env", env, "--", ...command];
+}
+
 /** A refusal an app adds to the sequence: a sentence saying why not, or `null` to proceed. */
 export type Refusal = () => string | null;
 
@@ -154,6 +166,17 @@ export interface WorkerDeploySpec {
 	build: readonly string[] | null;
 	/** Run in order BEFORE a production deploy; any red and production is not touched. Ignored for the stage. */
 	stageFirst?: readonly (readonly string[])[];
+	/**
+	 * The signed-in walk of the stage, run after `stageFirst` and before production is touched — and,
+	 * unlike `stageFirst`, under {@link WorkerDeploySpec.cpuTail} when that is set. Ignored for the stage.
+	 */
+	stageWalk?: readonly (readonly string[])[];
+	/**
+	 * The app's Worker CPU wrapper (see {@link runWorkerCpuTail}), e.g. `["bun", "run", "scripts/worker-cpu.ts"]`. When
+	 * set, every `stageWalk` command and the `smoke` run UNDER it (`underCpuTail`), so the traffic a
+	 * deploy already sends is charged its billed CPU and judged against the app's Worker budgets.
+	 */
+	cpuTail?: readonly string[];
 	/** Before the stage (and before anything is built): the app's own refusals. */
 	beforeStage?: readonly Refusal[];
 	/** After the build, before anything ships — e.g. "the build output is really there". */
@@ -227,6 +250,11 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 			step(`the stage first — production waits on it: ${command.join(" ")}`);
 			if (deps.run(command, {}) !== 0) return stop("stage", `\`${command.join(" ")}\` failed — production was NOT touched.`);
 		}
+		for (const walk of spec.stageWalk ?? []) {
+			const command = spec.cpuTail ? underCpuTail(spec.cpuTail, "stage", walk) : [...walk];
+			step(`walk the stage signed in${spec.cpuTail ? ", under a CPU tail" : ""}: ${command.join(" ")}`);
+			if (deps.run(command, {}) !== 0) return stop("stage", `\`${command.join(" ")}\` failed — production was NOT touched.`);
+		}
 	}
 	if (spec.build) {
 		step("build");
@@ -255,8 +283,9 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 		}
 	}
 	if (spec.smoke) {
-		step("smoke every address this deployment answers on");
-		if (deps.run(spec.smoke, {}) !== 0) {
+		step(`smoke every address this deployment answers on${spec.cpuTail ? ", under a CPU tail" : ""}`);
+		const smoke = spec.cpuTail ? underCpuTail(spec.cpuTail, spec.env, spec.smoke) : spec.smoke;
+		if (deps.run(smoke, {}) !== 0) {
 			return stop(
 				"smoke",
 				"the Worker is deployed and its smoke FAILED. Nothing was rolled back: `bunx wrangler rollback` puts the previous version back in one command.",
@@ -267,3 +296,403 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 	log(`\n✅ ${detail}`);
 	return { code: 0, step: "done", detail, commit, dirty };
 }
+
+// ═════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * THE WORKER CPU CHECK (0.7.0, task 2134) — what a Worker's requests REALLY cost, asserted on every deploy: a
+ * `wrangler tail` around traffic the deploy already sends (the signed-in stage walk, the smoke),
+ * each request's billed `cpuTime` charged to its declared route, and a red for a route that is
+ * undeclared, over its budget, or — exempt or not — heading for the platform's 30 s kill.
+ *
+ * ```ts
+ * // scripts/worker-cpu.ts — the whole app side, besides a budget table
+ * import * as bench from "cursedbelt-server/bench";
+ * import { parseWorkerCpuArgv, runWorkerCpuTail } from "cursedops/worker-deploy";
+ *
+ * const { env, command } = parseWorkerCpuArgv(process.argv.slice(2));
+ * const d = deploymentFor(env);
+ * const result = await runWorkerCpuTail({
+ *   app: "vault", workerName: d.workerName, base: d.previewUrl ?? d.publicUrl, command, cwd: ROOT,
+ *   credential, fetch: (url) => edgeFetch(url), bench, config: VAULT_WORKER_CPU_BUDGETS,
+ * });
+ * process.exit(result.code);
+ *
+ * // scripts/worker-deploy.ts — the sequence wraps the walk and the smoke itself
+ * runWorkerDeploy({ …, stageWalk: [["bun", "run", "scripts/worker-stage-walk.ts"]],
+ *                   cpuTail: ["bun", "run", "scripts/worker-cpu.ts"] }, deps);
+ * ```
+ *
+ * ## 🔴 Why it exists
+ *
+ * `collections` averaged **489 CPU-ms per request on 2026-09-22 with a 15.2 s p99**, and nothing
+ * in its gate could see it: its `cpuBudget.spec.ts` benches the Mac, where the same unlock cost
+ * ~1.6 s rather than 8.5–15 s, and a Worker handler has no clock to read its own CPU time. The
+ * billed number exists only on the trace a tail receives. `vault` was the next app in the same
+ * state — pure-JS argon2id at 4,089 CPU-ms per create and 4,458 per unlock on its stage, with
+ * every check green (task 2134). Collections wrote this wrapper in `scripts/`; a copy in vault
+ * would have been the fourth hand-kept copy of a deploy step this toolkit exists to own.
+ *
+ * ## Why `bench` is a parameter, not an import
+ *
+ * The recorder, the tail parser and the assertion are `cursedbelt-server/bench`'s — and
+ * `cursedbelt-server` depends on THIS package, so importing it back would be a cycle. The app
+ * already depends on it for its proxy table, so it hands the module in (`import * as bench`) and
+ * {@link TailBench} names, structurally, the seven functions used. The app's typecheck is what
+ * proves the two still agree.
+ *
+ * ## The decisions it makes about a capture (each one a way it went wrong or could)
+ *
+ *   1. **A non-API GET is the static tier, `GET *`** — but only when the table DECLARES `GET *`.
+ *      A Worker that ends in `app.get("*")` serves the shell and every client-side route there;
+ *      declaring `GET /*` as a pattern instead would swallow an undeclared `GET /api/…`, which is
+ *      exactly what `requireDeclared` exists to name. So the label is decided here, never for a
+ *      path under an API prefix, and an app with no `GET *` gets its unknown GETs named instead.
+ *   2. **`minSamples: 1`.** A walk makes one request per route; a p99 of one reading is that reading.
+ *   3. 🔴 **An exempt route over its `noticeAboveMs` FAILS here**, where the library only notices —
+ *      and an exempt route with NO `noticeAboveMs` is a red of its own (`exempt-uncapped`). Exempt
+ *      is from the per-request money budget, never from the platform: an invocation is killed at
+ *      30 s of CPU, and a killed unlock reads as a wrong password.
+ *   4. **Only this Worker's invocations are charged** (`scriptName`), so the stage's walk cannot be
+ *      excused by production's traffic on a shared tail, or the reverse.
+ *   5. **A tail that never connects is a failure, never an empty pass**; neither is a runtime that
+ *      stops reporting `cpuTime` (`recordTailTraces` skips it; the empty report is `no-samples`).
+ *
+ * ## How it knows the tail is listening, and that it has heard everything
+ *
+ * `wrangler tail --format json` prints nothing until a request arrives, so there is no banner to
+ * wait for. It sends `GET /healthz?cpu-tail=<nonce>` until that request comes back on the tail
+ * (connected), runs the command, then `…=<nonce>-end` until THAT comes back (drained). The marker
+ * requests are real traffic, so `GET /healthz` must be declared like any other route.
+ *
+ * 🔴 The command's own exit code wins: a walk that failed is reported as the walk failing, and the
+ * CPU verdict is still printed but does not mask it.
+ */
+
+/** A route's budget as `cursedbelt-server/bench` declares it — structural. */
+export type RouteBudgetLike = number | { cpuMs: number } | { exempt: true; reason: string; noticeAboveMs?: number };
+
+/** `CpuBudgetConfig`, structurally. */
+export interface CpuBudgetConfigLike {
+	defaultCpuMs?: number;
+	routes?: Record<string, RouteBudgetLike>;
+}
+
+/** The fields of a `CpuViolation` this reads. */
+export interface CpuViolationLike {
+	kind: string;
+	key: string;
+	fails: boolean;
+	message: string;
+}
+
+/** `TailRecordResult`, structurally. */
+export interface TailRecordLike {
+	recorded: number;
+	notFetch: number;
+	noCpuTime: number;
+	unmatched: number;
+	unmatchedPaths: string[];
+}
+
+/**
+ * The seven functions of `cursedbelt-server/bench` this uses — pass the module itself
+ * (`import * as bench from "cursedbelt-server/bench"`). Method syntax on purpose: the parameters
+ * are checked bivariantly, so the real, narrower signatures are assignable.
+ */
+export interface TailBench {
+	parseTailLines(text: string): readonly unknown[];
+	tailCpuClock(): unknown;
+	createCpuRecorder(opts: { clock: never; config?: never }): { report(): unknown };
+	recordTailTraces(recorder: never, traces: never, opts: { route?: (method: string, path: string) => string | null; scriptName?: string }): TailRecordLike;
+	routeMatcher(keys: readonly string[]): (method: string, path: string) => string | null;
+	checkCpuBudgets(report: never, opts: { requireDeclared?: boolean; minSamples?: number }): readonly CpuViolationLike[];
+	formatCpuBudgetReport(report: never): string;
+}
+
+/** The static tier's label — decision 1. Its key in a table is `GET *`. */
+export const STATIC_TIER = "*";
+const STATIC_TIER_KEY = `GET ${STATIC_TIER}`;
+
+/** Paths that are never the static tier unless a table declares them. */
+export const DEFAULT_API_PREFIXES: readonly string[] = ["/api"];
+
+const underPrefix = (path: string, prefixes: readonly string[]): boolean =>
+	prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix.replace(/\/$/, "")}/`));
+
+/**
+ * `(method, path)` → the declared route it is charged to, or `null` (undeclared).
+ *
+ * 🔴 The `GET *` key itself is NOT given to the matcher: as a pattern it is `.*`, and it would
+ * charge an undeclared `GET /api/…` to the static tier — the swallowing decision 1 forbids.
+ */
+export function tierRoute(
+	bench: Pick<TailBench, "routeMatcher">,
+	config: CpuBudgetConfigLike,
+	apiPrefixes: readonly string[] = DEFAULT_API_PREFIXES,
+): (method: string, path: string) => string | null {
+	const keys = Object.keys(config.routes ?? {});
+	const hasStaticTier = keys.includes(STATIC_TIER_KEY);
+	const declared = bench.routeMatcher(keys.filter((key) => !/(^|\s)\*$/.test(key)));
+	return (method, path) => {
+		const hit = declared(method, path);
+		if (hit !== null) return hit;
+		return hasStaticTier && method.toUpperCase() === "GET" && !underPrefix(path, apiPrefixes) ? STATIC_TIER : null;
+	};
+}
+
+/** A red this module adds on top of the library's violations. */
+export interface WorkerCpuFailure {
+	kind: string;
+	key: string;
+	message: string;
+}
+
+export interface TailVerdict {
+	ok: boolean;
+	/** Every violation that fails this check — decision 3 included. */
+	failures: WorkerCpuFailure[];
+	/** `CpuBudgetReport` — hand it to `formatCpuBudgetReport`. */
+	report: unknown;
+	recorded: TailRecordLike;
+	/** Traces parsed out of the capture, this Worker's or not. */
+	traces: number;
+}
+
+export interface JudgeOpts {
+	bench: TailBench;
+	/** The Worker's REAL-reading budget table (`noticeAboveMs` on every exempt route). */
+	config: CpuBudgetConfigLike;
+	/** Only this deployment's invocations are charged — decision 4. */
+	scriptName: string;
+	/** Paths that are never the static tier. Default {@link DEFAULT_API_PREFIXES}. */
+	apiPrefixes?: readonly string[];
+	/** Replace the labeller entirely. Default {@link tierRoute}. */
+	route?: (method: string, path: string) => string | null;
+}
+
+/** Exempt routes with no ceiling — each one a route the 30 s kill could reach with every check green. */
+export function uncappedExemptions(config: CpuBudgetConfigLike): string[] {
+	return Object.entries(config.routes ?? {})
+		.filter(([, budget]) => typeof budget === "object" && "exempt" in budget && budget.noticeAboveMs === undefined)
+		.map(([key]) => key);
+}
+
+/** Judge one `wrangler tail --format json` capture. Pure: no Worker, no network. */
+export function judgeTailCapture(text: string, opts: JudgeOpts): TailVerdict {
+	const { bench, config } = opts;
+	const traces = bench.parseTailLines(text);
+	const recorder = bench.createCpuRecorder({ clock: bench.tailCpuClock() as never, config: config as never });
+	const route = opts.route ?? tierRoute(bench, config, opts.apiPrefixes);
+	const recorded = bench.recordTailTraces(recorder as never, traces as never, { scriptName: opts.scriptName, route });
+	const report = recorder.report();
+	const failures: WorkerCpuFailure[] = uncappedExemptions(config).map((key) => ({
+		kind: "exempt-uncapped",
+		key,
+		message:
+			`${key} is exempt with no noticeAboveMs — on a Worker every route needs a CEILING, because an invocation is ` +
+			"killed at 30 s of CPU whatever the table calls it. Give it the ceiling its real readings justify.",
+	}));
+	for (const v of bench.checkCpuBudgets(report as never, { requireDeclared: true, minSamples: 1 })) {
+		if (v.kind === "exempt-notice") {
+			failures.push({ kind: v.kind, key: v.key, message: `${v.message} 🔴 On a Worker this is red: an exempt route is still killed at 30 s of CPU.` });
+		} else if (v.fails) {
+			failures.push({ kind: v.kind, key: v.key, message: v.message });
+		}
+	}
+	return { ok: failures.length === 0, failures, report, recorded, traces: traces.length };
+}
+
+/** The verdict in words, for the deploy log. */
+export function formatTailVerdict(verdict: TailVerdict, bench: Pick<TailBench, "formatCpuBudgetReport">, scriptName: string): string {
+	const r = verdict.recorded;
+	const lines = [
+		`Worker CPU for ${scriptName} — ${r.recorded} request(s) charged from ${verdict.traces} trace(s)` +
+			(r.notFetch ? `, ${r.notFetch} cron/other skipped` : "") +
+			(r.noCpuTime ? `, ${r.noCpuTime} with no cpuTime` : ""),
+		bench.formatCpuBudgetReport(verdict.report as never),
+	];
+	if (r.unmatchedPaths.length > 0) lines.push(`undeclared paths: ${r.unmatchedPaths.join(", ")}`);
+	for (const failure of verdict.failures) lines.push(`✗ ${failure.message}`);
+	lines.push(verdict.ok ? "✓ every request inside its declared Worker budget" : "🔴 Worker CPU budget FAILED");
+	return lines.join("\n");
+}
+
+/**
+ * A Worker table derived from a Mac-proxy table, the rule `collections` measured its way to:
+ * **`max(floorMs, overProxy × proxy budget)`** per route, plus the Worker-only routes, with each
+ * exempt route given its ceiling from `ceilings`. THROWS on an exempt route with no ceiling, and
+ * on a ceiling for a route that is not exempt — both are a table that says something untrue.
+ *
+ * Why a rule rather than forty fitted numbers: the proxy already RANKS the routes, the ratio
+ * (3.5–5.3× Mac→workerd, measured three ways on 2026-09-23) carries the ranking to the platform,
+ * and the floor is the cold-isolate cost every request pays whatever it does — at a few hundred
+ * requests a day almost every request lands on a cold isolate.
+ */
+export function workerBudgets(
+	proxy: CpuBudgetConfigLike,
+	opts: { floorMs: number; overProxy: number; workerOnly?: Record<string, RouteBudgetLike>; ceilings?: Record<string, number> },
+): { routes: Record<string, RouteBudgetLike> } {
+	const routes: Record<string, RouteBudgetLike> = {};
+	const ceilings = opts.ceilings ?? {};
+	for (const [key, budget] of Object.entries(proxy.routes ?? {})) {
+		if (typeof budget === "object" && "exempt" in budget) {
+			const ceiling = ceilings[key] ?? budget.noticeAboveMs;
+			if (ceiling === undefined) throw new Error(`workerBudgets: ${key} is exempt and has no ceiling — pass ceilings["${key}"].`);
+			routes[key] = { ...budget, noticeAboveMs: ceiling };
+			continue;
+		}
+		const cpuMs = typeof budget === "number" ? budget : budget.cpuMs;
+		routes[key] = Math.max(opts.floorMs, opts.overProxy * cpuMs);
+	}
+	for (const key of Object.keys(ceilings)) {
+		const budget = routes[key];
+		if (!(typeof budget === "object" && "exempt" in budget)) throw new Error(`workerBudgets: a ceiling for ${key}, which is not an exempt route.`);
+	}
+	return { routes: { ...(opts.workerOnly ?? {}), ...routes } };
+}
+
+/**
+ * `[--env stage] -- <command…>` → the deployment and the command. THROWS a usage line on a missing
+ * command. The `--env` spelling rules are {@link parseWorkerEnv}'s.
+ */
+export function parseWorkerCpuArgv(argv: readonly string[]): { env: WorkerEnv; command: string[] } {
+	const split = argv.indexOf("--");
+	const own = split >= 0 ? argv.slice(0, split) : argv;
+	const command = split >= 0 ? argv.slice(split + 1) : [];
+	if (command.length === 0) throw new Error("usage: worker-cpu [--env stage] -- <command…>");
+	return { env: parseWorkerEnv(own), command };
+}
+
+
+/** A running `wrangler tail`. */
+export interface TailProcess {
+	/** Everything it has printed on stdout so far. */
+	captured(): string;
+	/** The tail of its stderr, for a failure message. */
+	errors(): string;
+	exited(): boolean;
+	stop(): void;
+}
+
+export interface WorkerCpuDeps {
+	/** Start `wrangler tail <worker> --format json`. */
+	startTail: (workerName: string, cwd: string, env: Record<string, string>) => TailProcess;
+	/** Run the command, inheriting stdio; its exit code. */
+	run: (argv: readonly string[], cwd: string) => number;
+	sleep: (ms: number) => Promise<void>;
+	now: () => number;
+	log: (line: string) => void;
+	error: (line: string) => void;
+}
+
+/** The real {@link WorkerCpuDeps}: `bunx wrangler@4 tail`, pinned to the major whose JSON shape the parser reads. */
+export function workerCpuDeps(): WorkerCpuDeps {
+	return {
+		startTail: (workerName, cwd, env) => {
+			let out = "";
+			let err = "";
+			const child = spawn("bunx", ["wrangler@4", "tail", workerName, "--format", "json"], {
+				cwd,
+				env: { ...process.env, ...env },
+				stdio: ["ignore", "pipe", "pipe"],
+			});
+			child.stdout.on("data", (chunk: Buffer) => {
+				out += chunk.toString("utf8");
+			});
+			child.stderr.on("data", (chunk: Buffer) => {
+				err += chunk.toString("utf8");
+			});
+			return {
+				captured: () => out,
+				errors: () => err.trim().slice(-800),
+				exited: () => child.exitCode !== null || child.signalCode !== null,
+				stop: () => {
+					if (child.exitCode === null) child.kill("SIGINT");
+				},
+			};
+		},
+		run: (argv, cwd) => spawnSync(argv[0] as string, argv.slice(1), { cwd, stdio: "inherit" }).status ?? 1,
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		now: () => Date.now(),
+		log: (line) => console.log(line),
+		error: (line) => console.error(line),
+	};
+}
+
+export interface WorkerCpuTailSpec extends Omit<JudgeOpts, "scriptName"> {
+	/** For the messages. */
+	app: string;
+	/** The Worker to tail — also the only `scriptName` charged. */
+	workerName: string;
+	/** Where the markers are sent: an address of THIS deployment that reaches the Worker. */
+	base: string;
+	command: readonly string[];
+	cwd: string;
+	/** The env overlay wrangler runs with — `cloudflareCredential` from `cursedops/worker-deploy`. */
+	credential: Record<string, string>;
+	/** A GET the app's scripts can make (the stage is behind Access) — `cursedops/edge-fetch`. */
+	fetch: (url: string) => Promise<unknown>;
+	connectMs?: number;
+	drainMs?: number;
+	/** How long a marker is watched for before it is sent again. Default 3 s. */
+	markerWaitMs?: number;
+}
+
+export interface WorkerCpuTailResult {
+	/** 0 green; the command's own code when it failed; 1 for any CPU or tail failure. */
+	code: number;
+	/** Where it stopped: `connect`, `command`, `drain`, `budget` or `done`. */
+	step: "connect" | "command" | "drain" | "budget" | "done";
+	verdict: TailVerdict | null;
+}
+
+/** Run `spec.command` under a tail of `spec.workerName` and judge what it cost. Never exits. */
+export async function runWorkerCpuTail(spec: WorkerCpuTailSpec, deps: WorkerCpuDeps = workerCpuDeps()): Promise<WorkerCpuTailResult> {
+	const connectMs = spec.connectMs ?? 60_000;
+	const drainMs = spec.drainMs ?? 45_000;
+	const markerWaitMs = spec.markerWaitMs ?? 3_000;
+	const nonce = `${deps.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+	const tag = `[${spec.app}]`;
+	const base = spec.base.replace(/\/$/, "");
+
+	deps.log(`\n▸ ${tag} Worker CPU: tailing ${spec.workerName} around \`${spec.command.join(" ")}\``);
+	const tail = deps.startTail(spec.workerName, spec.cwd, spec.credential);
+
+	/** Send the marker until the tail has carried it back, or give up. */
+	const awaitMarker = async (marker: string, withinMs: number): Promise<boolean> => {
+		const deadline = deps.now() + withinMs;
+		while (deps.now() < deadline) {
+			if (tail.exited()) return false;
+			await spec.fetch(`${base}/healthz?cpu-tail=${marker}`).catch(() => null);
+			const seenBy = deps.now() + markerWaitMs;
+			while (deps.now() < seenBy) {
+				// The closing quote: `<nonce>` must not be satisfied by `<nonce>-end`.
+				if (tail.captured().includes(`cpu-tail=${marker}"`)) return true;
+				await deps.sleep(250);
+			}
+		}
+		return false;
+	};
+
+	if (!(await awaitMarker(nonce, connectMs))) {
+		tail.stop();
+		deps.error(
+			`🔴 ${tag} wrangler tail never delivered a request from ${base} within ${Math.round(connectMs / 1000)}s — nothing could be measured.\n${tail.errors()}`,
+		);
+		return { code: 1, step: "connect", verdict: null };
+	}
+
+	const ran = deps.run(spec.command, spec.cwd);
+	const drained = await awaitMarker(`${nonce}-end`, drainMs);
+	// Traces are not strictly ordered; a moment more lets a straggler behind the end marker land.
+	await deps.sleep(2_000);
+	tail.stop();
+
+	const verdict = judgeTailCapture(tail.captured(), { ...spec, scriptName: spec.workerName });
+	deps.log(`\n${formatTailVerdict(verdict, spec.bench, spec.workerName)}`);
+	if (!drained) deps.error(`🔴 ${tag} the end marker never came back — the capture may be missing the command's last requests.`);
+
+	if (ran !== 0) return { code: ran, step: "command", verdict };
+	if (!drained) return { code: 1, step: "drain", verdict };
+	return verdict.ok ? { code: 0, step: "done", verdict } : { code: 1, step: "budget", verdict };
+}