cursedops 0.5.3 → 0.7.0

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) |
@@ -21,6 +22,8 @@ bun add cursedops
 | `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser and the default 404 body. No `node:` import, so it mounts inside a Worker |
 | `cursedops/build-info` | which commit a checkout-served process is running and whether its tree was dirty — read once at load, and a `null` retried in the background rather than cached for the life of the process. `node:child_process`, so never in a Worker |
 | `cursedops/bound-lists` | the static check that no SQL builds an `IN (…)` list one `?` per value — the shape D1 500s on past 100 ids. Test-time only; the recorded third exception, see below |
+| `cursedops/staged-client` | the IMMUTABLE client a checkout-served app serves — a build staged into `<APP_DATA_DIR>/client/<commit>/` behind `CURRENT`, so another agent's `vite build` in the checkout never changes live bytes — and its `forge-client stamp` / `forge-client stage` bin (0.6.0, lifted from family, flix, roms, station) |
+| `cursedops/deploy-tree` | the two refusals a checkout-served deploy needs — never deploy a dirty tree, never `git revert` in one (`readTreeStatus`, `refuseToDeploy`, `refuseToRevert`; 0.6.0, lifted from nine apps) |
 | `cursedops/public-surface` | the ratchet on a LIBRARY's public surface — a symbol count per export subpath against a committed baseline that may only fall — and its `public-surface` bin. Not an app's: the one entry here admitted for three published libraries, see below |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
@@ -416,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.5.3",
-	"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.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, 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",
@@ -97,11 +97,24 @@
 			"source": "./src/d1Import.ts",
 			"import": "./src/d1Import.ts"
 		},
-		"./package.json": "./package.json"
+		"./package.json": "./package.json",
+		"./staged-client": {
+			"types": "./src/stagedClient.ts",
+			"bun": "./src/stagedClient.ts",
+			"source": "./src/stagedClient.ts",
+			"import": "./src/stagedClient.ts"
+		},
+		"./deploy-tree": {
+			"types": "./src/deployTree.ts",
+			"bun": "./src/deployTree.ts",
+			"source": "./src/deployTree.ts",
+			"import": "./src/deployTree.ts"
+		}
 	},
 	"bin": {
 		"public-surface": "./src/publicSurface.ts",
-		"forge-paths": "./src/paths.ts"
+		"forge-paths": "./src/paths.ts",
+		"forge-client": "./src/stagedClient.ts"
 	},
 	"files": [
 		"src",

package/src/deployTree.ts

@@ -0,0 +1,181 @@
+/**
+ * `cursedops/deploy-tree` — is this checkout in a state where a deploy's rollback would be a rollback?
+ *
+ * Lifted 2026-09-23 (0.6.0) from the nine apps that each carried `scripts/deployTree.ts` —
+ * collections, desk, family, flix, music, patterns, roms, station and vault; identical in logic,
+ * differing only in comments and indentation. vault's `deployTree.test.ts` came with it.
+ *
+ * ```ts
+ * import { readTreeStatus, refuseToDeploy, refuseToRevert } from "cursedops/deploy-tree";
+ * ```
+ *
+ * ## The incident this exists because of — 2026-09-18, six of eight apps
+ *
+ * A fleet deploy ran `bun run deploy` in eight app checkouts. Six failed, all on the same
+ * smoke check and none on their own code:
+ *
+ * ```
+ * ✗ clean-tree — 🔴 the served checkout has uncommitted changes — `git revert` would not undo this deploy
+ * ```
+ *
+ * Every other check passed in every app; the apps installed and served correctly. The trees
+ * were dirty because somebody else's in-flight sweep was sitting in them, uncommitted.
+ *
+ * 🔴 **Then the failure did something far worse than fail.** A non-edge smoke failure rolls
+ * back with `git revert`, and the rollback ran in that same dirty tree. Both outcomes were
+ * bad, and both happened inside four minutes:
+ *
+ *  · **It succeeded** in `family`, `flix`, `music` and `roms` — landing a commit that reverted
+ *    work a stranger had written and had never been told was touched. (`706d1106`, `50aa95ed`,
+ *    `c6ef8cb6`, `88fececc`; each reverted-back the same session.)
+ *  · **It failed** in `station` — `error: Your local changes to src/api/console.ts would be
+ *    overwritten by merge … fatal: revert failed`, then `🔴 THE ROLLBACK DID NOT LAND.`, which
+ *    leaves a live hostname on a deploy the script had already decided to undo.
+ *
+ * ## The shape of the bug, which is the reason this is a module and not an `if`
+ *
+ * 🔴 **The rollback was unsafe in exactly the condition that triggered it.** `clean-tree` fires
+ * only when the tree is dirty; `git revert` is only safe when it is not. The two met on every
+ * run. Nothing else in this generation can commit on an agent's behalf, and this did it to a
+ * stranger's work.
+ *
+ * So the fix is two refusals, not one, and they are here rather than inline in `deploy.ts`
+ * because a refusal nobody can test is a comment:
+ *
+ *  1. {@link refuseToDeploy} — run BEFORE the build, so the deploy never starts. A dirty tree
+ *     means the thing that would deploy is not the thing `HEAD` names, so there is no commit a
+ *     revert could undo. A pre-flight refusal costs a second; not having one cost four commits.
+ *  2. {@link refuseToRevert} — run immediately before `git revert`, because the pre-flight
+ *     passing is not a promise about ten minutes later. A build, a stage run, or another agent
+ *     working in this same checkout can all dirty the tree between the two, and one agent per
+ *     checkout is a convention, not a lock.
+ *
+ * Neither takes an override flag, deliberately. `deploy.ts`'s own `--allow-empty` note records
+ * what an escape hatch on a gate that fires every day turns into: the flag becomes the habit,
+ * and the habit is what lets the real case through.
+ */
+
+/** One uncommitted path, with the two-letter porcelain code git gave it. */
+export type DirtyPath = {
+	/** The index/worktree code, e.g. `" M"`, `"D "`, `"??"`. */
+	code: string;
+	path: string;
+};
+
+export type TreeStatus = {
+	clean: boolean;
+	paths: DirtyPath[];
+	/**
+	 * The subset that are DELETIONS. Called out separately because a rollback landing one is
+	 * the worst case of all: `apps/music` and `apps/station` both sat with
+	 * `D scripts/guardrails.ts` uncommitted — a deleted guardrails script, one blanket commit
+	 * away from being deleted for real, by a script whose whole job was to be safe.
+	 */
+	deletions: DirtyPath[];
+};
+
+/**
+ * One porcelain v1 line: `XY<space><path>`, `X` the index state and `Y` the worktree state.
+ *
+ * 🔴 The second branch is not hypothetical — it is the bug this module shipped with for about
+ * ten minutes. `deploy.ts`'s `shell()` helper `.trim()`s the output it returns, which strips
+ * the LEADING SPACE off the first line of ` M scripts/deploy.ts` and nothing else. The
+ * fixed-offset parse then read one character late and reported `M  cripts/deploy.ts` — a path
+ * that does not exist, in a refusal whose whole job is to name paths a person can go and look
+ * at. `deploy.ts` now reads the status untrimmed; this branch means a caller that forgets
+ * still gets the right answer rather than a plausible wrong one.
+ */
+function parseLine(line: string): DirtyPath {
+	const [code, rest] = line[2] === " " ? [line.slice(0, 2), line.slice(3)] : [` ${line.slice(0, 1)}`, line.slice(2)];
+	const path = rest.trim();
+	// A rename is `R  old -> new`; keep the destination, which is the path that exists on disk.
+	const arrow = path.indexOf(" -> ");
+	return { code, path: arrow >= 0 ? path.slice(arrow + 4).trim() : path };
+}
+
+/** Parse `git status --porcelain` output. */
+export function readTreeStatus(porcelain: string): TreeStatus {
+	const paths: DirtyPath[] = [];
+	for (const line of porcelain.split("\n")) {
+		if (line.trim() === "") continue;
+		paths.push(parseLine(line));
+	}
+	return {
+		clean: paths.length === 0,
+		paths,
+		deletions: paths.filter((p) => p.code.includes("D")),
+	};
+}
+
+/** `git status --porcelain`'s own rendering of a path, for an error message. */
+function listed(paths: DirtyPath[], limit = 8): string {
+	const shown = paths.slice(0, limit).map((p) => `    ${p.code} ${p.path}`);
+	if (paths.length > limit) shown.push(`    … and ${paths.length - limit} more`);
+	return shown.join("\n");
+}
+
+/**
+ * The pre-flight. Returns the refusal to print, or `null` if the deploy may proceed.
+ *
+ * 🔴 This runs before the build — before anything is built, staged, installed or swapped — so
+ * that the deploy simply does not start. The alternative, which is what happened, is that the
+ * deploy runs all the way to the smoke, the smoke's `clean-tree` check fails on this exact
+ * condition, and the rollback then commits against a stranger.
+ */
+export function refuseToDeploy(status: TreeStatus): string | null {
+	if (status.clean) return null;
+	const lines = [
+		`\n✗ clean-tree — this checkout has ${status.paths.length} uncommitted path(s), so it must not deploy.`,
+		"",
+		"  What deploys here is the WORKING TREE — there is no artifact to swap back. With",
+		"  uncommitted changes in it, the code that would go live is not the code HEAD names,",
+		"  so there is no commit a `git revert` could undo. The rollback this script would reach",
+		"  for is not a rollback, and on 2026-09-18 it committed reverts of four other agents'",
+		"  work rather than admit that. Nothing has been built, installed or swapped.",
+		"",
+		listed(status.paths),
+	];
+	if (status.deletions.length > 0) {
+		lines.push(
+			"",
+			`  🔴 ${status.deletions.length} of those is a DELETION. If this is not your work, do not commit it —`,
+			"     two app checkouts on this fleet sat with a guardrails script deleted and uncommitted,",
+			"     one blanket commit away from losing the file. This module's header names them.",
+		);
+	}
+	lines.push(
+		"",
+		"  Commit them, or find whoever owns them and let them land — then deploy. `git status`",
+		"  and `git diff` say whose they are; the runner commits by name, so a tree it left dirty",
+		"  is somebody's live work, not litter.",
+	);
+	return lines.join("\n");
+}
+
+/**
+ * The rollback guard. Returns the refusal to print, or `null` if `git revert` is safe to run.
+ *
+ * 🔴 Never `git revert` in a dirty tree AT ALL — not only when `clean-tree` was the failing
+ * check. `station` proves the other half: its revert hit `error: Your local changes to
+ * src/api/console.ts would be overwritten by merge`, aborted, and left the live host on a
+ * deploy the script had decided to undo. A revert that half-lands is worse than one that never
+ * started, because the second one still has an honest error message.
+ */
+export function refuseToRevert(status: TreeStatus, sha: string): string | null {
+	if (status.clean) return null;
+	return [
+		`\n🔴 NOT ROLLING BACK. The deploy failed, and ${sha.slice(0, 8)} is still what this checkout serves.`,
+		"",
+		`  This tree has ${status.paths.length} uncommitted path(s), and \`git revert\` in a dirty tree either`,
+		"  commits somebody else's work as reverted or aborts halfway and leaves the host on the",
+		"  code it was told to undo. Both happened on 2026-09-18. Neither is a rollback, so this",
+		"  script will not do it — a deploy that needs a person is a better outcome than a commit",
+		"  nobody asked for.",
+		"",
+		listed(status.paths),
+		"",
+		"  A person: land or set aside the paths above, then `git revert --no-edit " +
+			`${sha.slice(0, 8)}\`, then`,
+		"  `bun run build && bun run deploy` — the app's own deploy doc, § 'by hand', is the long form.",
+	].join("\n");
+}

package/src/roots.ts

@@ -163,15 +163,29 @@ export function readForgeVar(marker: string, name: string, env: NodeJS.ProcessEn
 	} catch {
 		return null;
 	}
-	const known: Record<string, string> = { HOME: env.HOME?.trim() ?? "" };
+	// 🔴 `null` is UNRESOLVABLE, and it propagates: a value that references an unset or empty
+	// variable — `$HOME` from an env that has none — is not a path with a hole in it. Until 0.5.4
+	// an empty HOME expanded `"$HOME/.code/$FORGE_NAME"` to `/.code/cursedforge`, a root-relative
+	// state root that exists on no machine, and `assertTestSafeDbPath(…, { env: {} })` compared
+	// against it — the guard against a test opening the owner's database was silently OFF (task 2130).
+	const home = env.HOME?.trim();
+	const known: Record<string, string | null> = { HOME: home ? home : null };
 	for (const line of text.split("\n")) {
 		const match = /^\s*export\s+([A-Z_][A-Z0-9_]*)=(.*)$/.exec(line);
 		if (!match) continue;
 		const [, key, rawValue] = match as unknown as [string, string, string];
 		const unquoted = rawValue.trim().replace(/^"(.*)"$/s, "$1").replace(/^'(.*)'$/s, "$1");
-		const expanded = unquoted.replace(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g, (_whole, ref: string) => known[ref] ?? "");
-		known[key] = expanded;
-		if (key === name) return expanded || null;
+		let unresolved = false;
+		const expanded = unquoted.replace(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g, (_whole, ref: string) => {
+			const value = known[ref];
+			if (value === null || value === undefined || value === "") {
+				unresolved = true;
+				return "";
+			}
+			return value;
+		});
+		known[key] = unresolved ? null : expanded;
+		if (key === name) return unresolved ? null : expanded || null;
 	}
 	return null;
 }

package/src/stagedClient.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+/**
+ * `cursedops/staged-client` — the IMMUTABLE client a checkout-served app serves: a build copied
+ * into `<APP_DATA_DIR>/client/<commit>/`, named by `CURRENT`, so another agent's `vite build` in
+ * the shared checkout can never change the bytes production is serving.
+ *
+ * ── Why (tasks 163-314, 2026-09-17 → 23) ────────────────────────────────────
+ * The launchd agent runs `server.ts` out of `$FORGE/apps/<app>`, and until this module it also
+ * served that checkout's `dist/` — so any `bun run verify` or `bun run build` by anybody in the
+ * checkout rewrote the live client under a server built from a different commit. Measured on
+ * station first (`/healthz` said one commit, `dist/index.html` another, a page asking for routes
+ * its server had never heard of); family, flix and roms had the same shape and took the same
+ * module. It lived as a byte-identical `src/server/clientDir.ts` in those four apps, with
+ * `scripts/stamp-build.ts` (four) and `scripts/stage-client.ts` (family, roms); lifted here 0.6.0.
+ *
+ * ```ts
+ * import { resolveClientDir, stageClient } from "cursedops/staged-client";
+ * const client = resolveClientDir({ appDir, dataDir: config.dataDir }); // serve client.dir
+ * ```
+ *
+ * ```jsonc
+ * "build": "vite build && forge-client stamp"        // writes dist/build.json — the commit
+ * // deploy: stageClient({ from: dist, dataDir, commit }), or `forge-client stage`
+ * ```
+ *
+ * `stageClient` copies FULLY, verifies the shell arrived, and only then moves `CURRENT`, so a
+ * failed stage leaves the previous release serving. The directory is keyed on the commit (a
+ * dirty build gets `-dirty`), so a rollback is a directory that is still there, and
+ * {@link pruneStagedClients} keeps the newest few plus whatever `CURRENT` names. Nothing staged
+ * falls back to `<appDir>/dist` and SAYS so (`staged: false`), because dev, preview and e2e serve
+ * the bytes vite just wrote, and a production instance falling back is worth a log line.
+ *
+ * Standalone by construction: node builtins only, and `cursedops/roots` by its package name for
+ * the one CLI default that needs the state root (a shipped file imports no sibling by path).
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The directory under the app's state root that holds every staged build. */
+export const CLIENT_ROOT = "client";
+
+/** The file inside {@link CLIENT_ROOT} naming the build that should be served. */
+export const CURRENT_FILE = "CURRENT";
+
+/** What `bun run build` stamps beside the shell so a build can name its own commit. */
+const BUILD_STAMP = "build.json";
+
+/** How many staged builds are kept. Enough for a rollback, not a disk leak. */
+const KEEP_BUILDS = 3;
+
+export interface BuildStamp {
+	/** The full 40-char commit the client was built from, or `null` if unreadable. */
+	commit: string | null;
+	/** Whether the tree was dirty when it was built. */
+	dirty: boolean | null;
+	/** When it was built — ISO 8601. */
+	builtAt: string;
+}
+
+/** A directory is a usable client only if it actually holds the shell. */
+export const holdsShell = (dir: string): boolean => existsSync(join(dir, "index.html"));
+
+/** The stamp a build wrote, or `null`. Never throws: an unreadable stamp is a `null` commit. */
+export function readBuildStamp(dir: string): BuildStamp | null {
+	try {
+		const parsed = JSON.parse(readFileSync(join(dir, BUILD_STAMP), "utf8")) as Partial<BuildStamp>;
+		if (typeof parsed !== "object" || parsed === null) return null;
+		return {
+			commit: typeof parsed.commit === "string" && /^[0-9a-f]{40}$/.test(parsed.commit) ? parsed.commit : null,
+			dirty: typeof parsed.dirty === "boolean" ? parsed.dirty : null,
+			builtAt: typeof parsed.builtAt === "string" ? parsed.builtAt : "",
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Write the stamp. `forge-client stamp` calls it immediately after `vite build`. */
+export function writeBuildStamp(dir: string, stamp: BuildStamp): void {
+	writeFileSync(join(dir, BUILD_STAMP), `${JSON.stringify(stamp, null, "\t")}\n`);
+}
+
+/**
+ * The staged build this app should serve, or `null` when nothing is staged.
+ *
+ * 🔴 A `CURRENT` naming a directory that is missing or shell-less answers `null`
+ * rather than throwing. The fallback to `dist/` keeps the app UP, and the smoke's
+ * `client-commit` row is what makes the miss loud — an app that refuses to boot
+ * because a pointer file is stale is a worse outcome than one serving the previous
+ * client and saying so.
+ */
+export function stagedClientDir(dataDir: string): string | null {
+	const root = join(dataDir, CLIENT_ROOT);
+	let named: string;
+	try {
+		named = readFileSync(join(root, CURRENT_FILE), "utf8").trim();
+	} catch {
+		return null;
+	}
+	// One path segment, never joined from anything a request can influence — but the
+	// file is on disk and a hand edit is exactly how this would become a traversal.
+	if (!/^[A-Za-z0-9._-]+$/.test(named) || named === "." || named === "..") return null;
+	const dir = join(root, named);
+	return holdsShell(dir) ? dir : null;
+}
+
+export interface ResolvedClient {
+	/** The directory to serve. */
+	dir: string;
+	/** True when it came from the state root, false when it is the checkout's `dist/`. */
+	staged: boolean;
+	/** The commit the served client was BUILT from, full sha, or `null`. */
+	commit: string | null;
+}
+
+/**
+ * Where this process's client lives. `dataDir` is `null` in a context with no state
+ * root at all, which resolves to the checkout exactly as before.
+ */
+export function resolveClientDir(options: { appDir: string; dataDir: string | null }): ResolvedClient {
+	const staged = options.dataDir ? stagedClientDir(options.dataDir) : null;
+	const dir = staged ?? join(options.appDir, "dist");
+	return { dir, staged: staged !== null, commit: readBuildStamp(dir)?.commit ?? null };
+}
+
+/**
+ * Copy a build into the state root and point `CURRENT` at it. Returns the directory.
+ *
+ * 🔴 The order is the whole safety property: copy fully, verify the shell arrived,
+ * and only THEN write `CURRENT`. A pointer is never updated to a half-copied build,
+ * so the worst a failed stage can do is leave the previous release serving.
+ *
+ * 🔴 The directory is keyed on the commit, so re-staging the same commit is
+ * idempotent and a rollback is a directory that is still there. `dirty` builds get a
+ * suffix, because two dirty builds of the same commit are genuinely different bytes
+ * and must not collide.
+ */
+export function stageClient(options: {
+	from: string;
+	dataDir: string;
+	commit: string;
+	dirty?: boolean;
+	keep?: number;
+}): string {
+	if (!holdsShell(options.from)) {
+		throw new Error(`${options.from} holds no index.html — there is no built client to stage`);
+	}
+	const root = join(options.dataDir, CLIENT_ROOT);
+	mkdirSync(root, { recursive: true });
+	const name = options.dirty ? `${options.commit.slice(0, 12)}-dirty` : options.commit.slice(0, 12);
+	const dir = join(root, name);
+	rmSync(dir, { recursive: true, force: true });
+	cpSync(options.from, dir, { recursive: true });
+	if (!holdsShell(dir)) throw new Error(`staging ${options.from} into ${dir} did not produce an index.html`);
+	writeFileSync(join(root, CURRENT_FILE), `${name}\n`);
+	pruneStagedClients(options.dataDir, options.keep ?? KEEP_BUILDS);
+	return dir;
+}
+
+/** Keep the newest `keep` staged builds plus whatever `CURRENT` names. */
+export function pruneStagedClients(dataDir: string, keep: number = KEEP_BUILDS): string[] {
+	const root = join(dataDir, CLIENT_ROOT);
+	if (!existsSync(root)) return [];
+	let current = "";
+	try {
+		current = readFileSync(join(root, CURRENT_FILE), "utf8").trim();
+	} catch {
+		// No pointer — every directory here is a candidate but the newest still stay.
+	}
+	const dirs = readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => ({ name: entry.name, at: statSync(join(root, entry.name)).mtimeMs }))
+		.sort((a, b) => b.at - a.at);
+	const removed: string[] = [];
+	for (const [index, entry] of dirs.entries()) {
+		if (index < keep || entry.name === current) continue;
+		rmSync(join(root, entry.name), { recursive: true, force: true });
+		removed.push(entry.name);
+	}
+	return removed;
+}
+
+
+// ── the `forge-client` bin ────────────────────────────────────────────────────────────────
+
+/** The commit and dirtiness of the checkout at `root`, read from git; `null`s when unreadable. */
+export function checkoutState(root: string): { commit: string | null; dirty: boolean | null } {
+	const git = (args: string[]): string | null => {
+		try {
+			const result = spawnSync("git", args, { cwd: root, encoding: "utf8", timeout: 5_000 });
+			return result.status === 0 ? (result.stdout ?? "").trim() : null;
+		} catch {
+			return null;
+		}
+	};
+	const sha = git(["rev-parse", "HEAD"]);
+	const status = git(["status", "--porcelain"]);
+	return { commit: sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null, dirty: status === null ? null : status.length > 0 };
+}
+
+/** The nearest directory at or above `from` holding a `package.json` — the app. */
+function packageRoot(from: string): string | null {
+	let dir = resolve(from);
+	for (let hops = 0; hops < 16; hops++) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const up = dirname(dir);
+		if (up === dir) return null;
+		dir = up;
+	}
+	return null;
+}
+
+/**
+ * `forge-client stamp [dir]` writes `build.json` into a build (default `<app>/dist`);
+ * `forge-client stage [--data-dir <dir>]` stages `<app>/dist` into the app's data directory —
+ * `--data-dir`, else `APP_DATA_DIR`, else `<FORGE_STATE>/apps/<package name>` — and refuses a
+ * build whose stamp is not this checkout's HEAD. Returns the exit code.
+ */
+export async function runClientCli(argv: readonly string[], cwd: string = process.cwd(), env: NodeJS.ProcessEnv = process.env): Promise<number> {
+	const [command, ...rest] = argv;
+	const app = packageRoot(cwd);
+	if (!app) {
+		console.error(`✗ no package.json above ${cwd} — run this from an app.`);
+		return 2;
+	}
+	if (command === "stamp") {
+		const dir = rest[0] ? resolve(cwd, rest[0]) : join(app, "dist");
+		if (!holdsShell(dir)) {
+			console.error(`✗ ${dir} holds no index.html — nothing to stamp. Did the build run?`);
+			return 1;
+		}
+		const { commit, dirty } = checkoutState(app);
+		writeBuildStamp(dir, { commit, dirty, builtAt: new Date().toISOString() });
+		console.log(`  stamped ${dir}/build.json — ${commit?.slice(0, 8) ?? "no commit"}${dirty ? " (dirty)" : ""}`);
+		return 0;
+	}
+	if (command === "stage") {
+		const at = rest.indexOf("--data-dir");
+		let dataDir = at >= 0 ? rest[at + 1] : env.APP_DATA_DIR?.trim() || undefined;
+		if (!dataDir) {
+			const { forgeState } = await import("cursedops/roots");
+			const state = forgeState(app, env);
+			const name = (JSON.parse(readFileSync(join(app, "package.json"), "utf8")) as { name?: string }).name;
+			if (!state || !name) {
+				console.error("✗ no --data-dir, no APP_DATA_DIR, and no state root (or no package name) to derive one from.");
+				return 2;
+			}
+			dataDir = join(state, "apps", name);
+		}
+		const dist = join(app, "dist");
+		const stamp = readBuildStamp(dist);
+		const head = checkoutState(app).commit;
+		if (!stamp?.commit) {
+			console.error(`✗ ${dist} carries no build.json commit — build first (\`forge-client stamp\` runs after vite).`);
+			return 1;
+		}
+		if (stamp.commit !== head) {
+			console.error(`✗ ${dist} was built from ${stamp.commit.slice(0, 8)}, but HEAD is ${head?.slice(0, 8) ?? "unreadable"}.`);
+			console.error("  Staging it would serve a client that is not this commit. Build again first.");
+			return 1;
+		}
+		const where = stageClient({ from: dist, dataDir, commit: stamp.commit, dirty: stamp.dirty !== false });
+		console.log(`✓ staged ${where}${stamp.dirty !== false ? " (from a DIRTY tree)" : ""}`);
+		return 0;
+	}
+	console.error("usage: forge-client stamp [dir] | forge-client stage [--data-dir <dir>]");
+	return 2;
+}
+
+if (import.meta.main) {
+	process.exit(await runClientCli(process.argv.slice(2)));
+}

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,11 @@ 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. */
+export function underCpuTail(wrapper: readonly string[], env: WorkerEnv, command: readonly string[]): string[] {
+	return [...wrapper, ...(env === "stage" ? ["--env", "stage"] : []), "--", ...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 +159,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 +243,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 +276,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 +289,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 };
+}