cursedops 0.10.5 → 0.10.7

package/README.md

@@ -8,7 +8,7 @@ bun add cursedops
 
 | subpath | what it is |
 |---|---|
-| `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path — and the `cd` prefix of a printed command that RUNS when pasted (`repoCd`, 0.5.0) |
+| `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path — and the `cd` prefix of a printed command that RUNS when pasted (`repoCd`, 0.5.0); a worktree is followed to its primary from its `.git` file, once per directory, never a `git` per call (0.10.7) |
 | `cursedops/paths` | the generation's whole-tree laws (`check-paths`, `check-doc-citations`, plus any `--also`) run over ONE repo, from a checkout or a worktree — and its `forge-paths` bin (0.5.0) |
 | `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 |
@@ -27,6 +27,7 @@ bun add cursedops
 | `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/relay` | the WORKER half of a relay — a Worker in front of a Mac-bound app over ONE outbound WebSocket: the frames (station's wire, byte for byte), the key-digest door (`acceptLink`), and `RelayLink`, the Durable Object an app subclasses with its name, body ceiling, timeout and (optionally) station's per-cookie offline cache. No `node:` import (0.10.0, lifted from station for roms, task 065) |
 | `cursedops/relay-link` | the MAC half — `dialLink` (answer each frame with the app's own `fetch`, redial 1 s → 60 s on close, no timer otherwise), `readLinkSettings` for `<APP>_LINK_URL`/`<APP>_LINK_KEY`, and `rotateLinkKey` (digest to the Worker FIRST, the key to the 0600 file only if it took) (0.10.0) |
+| `cursedops/relay-stage` | the signed-in STAGE WALK's skeleton both relay apps shared — `stageByteCheck` (SHA-256 of every built file, a stale byte re-asked 4 × 10 s), `putStageLinkDigest` (`--env stage` only), `grantStageOwner` (auth-stage's 2FA grant, never production's), `oldKeyRefused` (the rotation leg: 20 s refused window, 3 min ceiling), `awaitSystemResolver`, `servedPath`, `STAGE_AUTH_URL`. With `relayWorkerDeployCli` in `cursedops/worker-deploy`, a relay app's whole `worker:deploy` as data (0.10.6) |
 | `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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "cursedops",
-	"version": "0.10.5",
-	"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 each app's worker:secrets and worker:smoke main as one function of its data), the relay a Worker fronts a Mac-bound app with (the Durable Object, the frames, the Mac's dialer and key rotation — lifted from station for roms), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, 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.10.7",
+	"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 each app's worker:secrets and worker:smoke main as one function of its data), the relay a Worker fronts a Mac-bound app with (the Durable Object, the frames, the Mac's dialer and key rotation — lifted from station for roms — and the signed-in stage walk's skeleton and the relay app's whole worker:deploy), the Worker import-graph and await-port checks every Worker app's suite runs over its own source, 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",
@@ -133,6 +133,12 @@
 			"bun": "./src/relayLink.ts",
 			"source": "./src/relayLink.ts",
 			"import": "./src/relayLink.ts"
+		},
+		"./relay-stage": {
+			"types": "./src/relayStage.ts",
+			"bun": "./src/relayStage.ts",
+			"source": "./src/relayStage.ts",
+			"import": "./src/relayStage.ts"
 		}
 	},
 	"bin": {

package/src/relayStage.ts

@@ -0,0 +1,231 @@
+/**
+ * `cursedops/relay-stage` — the skeleton every RELAY app's signed-in stage walk shares (0.10.6).
+ * `cursedops/relay` is the Worker half, `cursedops/relay-link` the Mac half; this is how a deploy
+ * proves the two together on `<app>-stage` before production is touched.
+ *
+ * Lifted from `apps/station/scripts/worker-stage.ts` (task 048) and `apps/roms/scripts/worker-stage.ts`
+ * (roms-stage, 2026-09-24), which had become one walk with two Mac ends — and each had learned a
+ * lesson the other lacked: station the edge-propagation re-ask on the byte check, roms the wait for
+ * this Mac's own resolver. A fix to one copy was a fix to ONE of them.
+ *
+ * What stays in each app: how its Mac end starts (station runs `apps/station/scripts/link.ts`, roms
+ * boots its own `apps/roms/server.ts`), the environment allowlist that fences it from production, and its signed-in legs.
+ *
+ * Every step that shells out or waits takes its effect as a parameter with the real one as default,
+ * so the suite drives each red — a stale byte, a refused put, a short grant, a key that never stops
+ * working, a name that never resolves — without wrangler, a Worker or a network.
+ */
+import { type SpawnSyncReturns, spawnSync } from "node:child_process";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { sha256Hex } from "cursedops/relay";
+
+/** The accounts door every stage signs in at — `apps/auth` deployed a second time. */
+export const STAGE_AUTH_URL = "https://auth-stage.cursedalchemy.com";
+
+/** `assets/x.js` (relative to `dist/`) → `/assets/x.js`; `index.html` → `/` — the path the byte check asks for. */
+export function servedPath(file: string): string {
+	return file === "index.html" ? "/" : `/${file.split("\\").join("/")}`;
+}
+
+/** Every file under `dir`, recursively, as absolute paths. */
+export function filesUnder(dir: string): string[] {
+	return readdirSync(dir).flatMap((name) => {
+		const path = join(dir, name);
+		return statSync(path).isDirectory() ? filesUnder(path) : [path];
+	});
+}
+
+export interface Clock {
+	now: () => number;
+	sleep: (ms: number) => Promise<void>;
+}
+
+export const realClock: Clock = { now: () => Date.now(), sleep: (ms) => Bun.sleep(ms) };
+
+/** Ask `ok` once a second until it says yes (true) or `ms` passes (false). A throw counts as no. */
+export async function until(ms: number, ok: () => Promise<boolean>, clock: Clock = realClock): Promise<boolean> {
+	const started = clock.now();
+	while (clock.now() - started < ms) {
+		if (await ok().catch(() => false)) return true;
+		await clock.sleep(1_000);
+	}
+	return false;
+}
+
+/** The Access service token, as the pair a Mac end's two variables and a roster socket carry. */
+export function accessPair(headers: Record<string, string>): { id: string; secret: string } {
+	return { id: headers["CF-Access-Client-Id"] ?? "", secret: headers["CF-Access-Client-Secret"] ?? "" };
+}
+
+export interface ByteCheckSpec {
+	/** The build the deploy uploaded. */
+	dist: string;
+	/** GET a served path on the stage — the app's `edgeFetch`, with the Access token. */
+	fetch: (path: string) => Promise<Response>;
+	/** Default four re-asks. */
+	retries?: number;
+	/** Default 10 s between re-asks. */
+	retryMs?: number;
+	clock?: Clock;
+}
+
+/**
+ * Whether the stage serves the EXACT bytes of every built file — SHA-256, not a health check, which a
+ * stale deploy passes. `differ` names each file still wrong (a non-2xx, other bytes, or no answer), empty when green;
+ * `files` 0 is red too (an empty `dist/` proves nothing).
+ *
+ * 🔴 A just-uploaded asset can read stale at the edge for a few seconds. Measured 2026-09-24 on
+ * station: the walk straight after `--env stage` found two unchanged chunks differing, and the same
+ * URLs served the exact bytes a minute later — the deploy was right and the walk refused production
+ * over propagation. So a mismatch is re-asked, and only one that PERSISTS is red. A stale deploy
+ * still fails: it never converges.
+ */
+export async function stageByteCheck(spec: ByteCheckSpec): Promise<{ files: number; differ: string[] }> {
+	const clock = spec.clock ?? realClock;
+	const files = filesUnder(spec.dist).map((path) => relative(spec.dist, path));
+	const differs = async (file: string): Promise<string | null> => {
+		const served = await spec.fetch(servedPath(file));
+		const want = new Bun.CryptoHasher("sha256").update(readFileSync(join(spec.dist, file))).digest("hex");
+		const got = new Bun.CryptoHasher("sha256").update(new Uint8Array(await served.arrayBuffer())).digest("hex");
+		return !served.ok || got !== want ? file : null;
+	};
+	/** A fetch that throws (the edge unreachable) is a file that differs, never a crash of the walk. */
+	const ask = (file: string): Promise<string | null> => differs(file).catch(() => file);
+	let differ: string[] = [];
+	for (const file of files) {
+		const d = await ask(file);
+		if (d) differ.push(d);
+	}
+	for (let retry = 1; retry <= (spec.retries ?? 4) && differ.length > 0; retry++) {
+		await clock.sleep(spec.retryMs ?? 10_000);
+		const again: string[] = [];
+		for (const file of differ) {
+			const still = await ask(file);
+			if (still) again.push(still);
+		}
+		differ = again;
+	}
+	return { files: files.length, differ };
+}
+
+export type Run = (argv: readonly string[], options: { cwd: string; input?: string; env?: Record<string, string>; timeout?: number }) => {
+	status: number | null;
+	stdout: string;
+	stderr: string;
+};
+
+/** The real {@link Run}: `spawnSync`, utf8, the env overlaid on this process's. */
+export const realRun: Run = (argv, options) => {
+	const done: SpawnSyncReturns<string> = spawnSync(argv[0] as string, argv.slice(1), {
+		cwd: options.cwd,
+		encoding: "utf8",
+		...(options.input !== undefined ? { input: options.input } : {}),
+		...(options.timeout !== undefined ? { timeout: options.timeout } : {}),
+		env: { ...process.env, ...options.env },
+	});
+	return { status: done.status, stdout: done.stdout ?? "", stderr: done.stderr ?? "" };
+};
+
+export interface DigestPut {
+	/** The app's checkout, where `wrangler.jsonc` is. */
+	cwd: string;
+	/** The Worker secret holding the key's digest — the app's `LinkNames.digest`, spelled whole. */
+	secretName: string;
+	key: string;
+	/** `cloudflareCredential(...)`. */
+	credential: Record<string, string>;
+	run?: Run;
+}
+
+/**
+ * Put `key`'s digest on the STAGE Worker (`--env stage`, always — this module has no production
+ * path). A per-run key for the walk, and again for the rotation leg. `ok: false` carries wrangler's
+ * stderr. A secret put is a new version: the caller gives it a few seconds to reach the edge.
+ */
+export async function putStageLinkDigest(put: DigestPut): Promise<{ ok: boolean; stderr: string }> {
+	const done = (put.run ?? realRun)(["bunx", "wrangler@4", "secret", "put", put.secretName, "--env", "stage"], {
+		cwd: put.cwd,
+		input: await sha256Hex(put.key),
+		env: put.credential,
+	});
+	return { ok: done.status === 0, stderr: done.stderr };
+}
+
+/**
+ * Sign the stage owner in through auth-stage's emailed second factor and grant `app`'s stage —
+ * `apps/auth-stage/scripts/inbox.ts` `grant <app>`, whose last stdout line is the grant.
+ * Never production's accounts service: nothing under test signs in there (`tools/check-prod-auth.ts`).
+ */
+export function grantStageOwner(spec: { forge: string; app: string; run?: Run; stderr?: (text: string) => void }): { ok: boolean; grant: string } {
+	const done = (spec.run ?? realRun)(["bun", "run", "scripts/inbox.ts", "grant", spec.app], {
+		cwd: join(spec.forge, "apps", "auth-stage"),
+		timeout: 300_000,
+	});
+	(spec.stderr ?? ((text) => process.stderr.write(text)))(done.stderr);
+	const grant = done.stdout.trim().split("\n").pop() ?? "";
+	return { ok: done.status === 0 && grant.length > 100, grant };
+}
+
+export interface RotationSpec {
+	/** Stop the Mac end, resolving once it has exited. */
+	stop: () => Promise<void>;
+	/** Start the Mac end with the key it held BEFORE the rotation. */
+	start: () => void;
+	/** Whether the stage's `/healthz` says the link is connected. */
+	isLinked: () => Promise<boolean>;
+	/** How long the old key must stay refused to count. Default 20 s. */
+	windowMs?: number;
+	/** Past this a still-working old key is a real fault. Default 3 min. */
+	maxMs?: number;
+	clock?: Clock;
+}
+
+/**
+ * After a new digest is put, prove the OLD key no longer connects: restart the Mac end on it until
+ * it stays unlinked for a whole {@link RotationSpec.windowMs} — never past {@link RotationSpec.maxMs}.
+ * A secret put reaches the edge in its own time (measured on station: 15 s was not always enough),
+ * so how long it took is the measurement. Leaves the Mac end STOPPED; the caller re-provisions it.
+ */
+export async function oldKeyRefused(spec: RotationSpec): Promise<{ refused: boolean; seconds: number }> {
+	const clock = spec.clock ?? realClock;
+	const rotatedAt = clock.now();
+	let refused = false;
+	while (!refused && clock.now() - rotatedAt < (spec.maxMs ?? 180_000)) {
+		await spec.stop();
+		await until(30_000, async () => !(await spec.isLinked()), clock);
+		spec.start();
+		// Every pass costs real time, whatever `isLinked` does: a loop whose answers all come back at
+		// once would otherwise spin without the ceiling ever arriving.
+		await clock.sleep(1_000);
+		refused = !(await until(spec.windowMs ?? 20_000, spec.isLinked, clock));
+	}
+	await spec.stop();
+	return { refused, seconds: Math.round((clock.now() - rotatedAt) / 1000) };
+}
+
+/**
+ * Wait until `host` resolves through THIS Mac's resolver, which `edgeFetch`'s 1.1.1.1 pin does not
+ * reach — true at once when it already does, false after `maxMs` (default the zone's 1800 s negative
+ * TTL). Measured 2026-09-24 on the first deploy of `roms-stage`: the smoke asked for the custom domain
+ * seconds after wrangler created it, the upstream resolver cached the NXDOMAIN, and every Mac-end
+ * dial failed 1006 while every edgeFetch succeeded. So a walk waits here, saying why, instead of
+ * failing on a dial.
+ */
+export async function awaitSystemResolver(spec: {
+	host: string;
+	lookup?: (host: string) => Promise<{ address: string }>;
+	maxMs?: number;
+	log?: (line: string) => void;
+	clock?: Clock;
+}): Promise<boolean> {
+	const lookup = spec.lookup ?? dnsLookup;
+	const resolves = async () => Boolean((await lookup(spec.host)).address);
+	if (await resolves().catch(() => false)) return true;
+	const maxMs = spec.maxMs ?? 1_800_000;
+	(spec.log ?? console.log)(
+		`  · ${spec.host} does not resolve on this Mac yet (a cached NXDOMAIN from before the domain existed) — waiting up to ${Math.round(maxMs / 60_000)} min`,
+	);
+	return until(maxMs, resolves, spec.clock);
+}

package/src/roots.ts

@@ -54,7 +54,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -86,30 +86,90 @@ function walkUp(from: string, marker: string): string | null {
 	return null;
 }
 
+/**
+ * The primary checkout's git directory for the repo `from` is in, read from DISK — or `undefined`
+ * when the files do not say, and only `git` can.
+ *
+ * A worktree's `.git` is a FILE, `gitdir: <primary>/.git/worktrees/<slug>`, and that directory's
+ * `commondir` names the primary's `.git` relative to it. A primary checkout or a clone has a `.git`
+ * DIRECTORY, which is its own common directory. Both are what `git rev-parse --git-common-dir`
+ * answers, without a process.
+ */
+function commonGitDirOnDisk(from: string): string | undefined {
+	let dir = resolve(from);
+	for (let hops = 0; hops < MAX_HOPS; hops++) {
+		const dotGit = join(dir, ".git");
+		if (existsSync(dotGit)) {
+			if (statSync(dotGit).isDirectory()) return realpathSync(dotGit);
+			const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"))?.[1]?.trim();
+			if (!pointer) return undefined;
+			const gitDir = resolve(dir, pointer);
+			const commonFile = join(gitDir, "commondir");
+			// A submodule's `.git` points at `.git/modules/<name>`, which has no `commondir`: it IS its own.
+			const common = existsSync(commonFile) ? resolve(gitDir, readFileSync(commonFile, "utf8").trim()) : gitDir;
+			return existsSync(common) ? realpathSync(common) : undefined;
+		}
+		const up = dirname(dir);
+		if (up === dir) return undefined;
+		dir = up;
+	}
+	return undefined;
+}
+
+/**
+ * One answer per starting directory, for the life of the process. Which primary a worktree was cut
+ * from cannot change while a process runs, and every `forgeState(from)` in a worktree lands here.
+ */
+const viaWorktree = new Map<string, string | null>();
+
+/** For a test that must watch the lookup happen again. */
+export function __forgetWorktreeRoots(): void {
+	viaWorktree.clear();
+}
+
 /**
  * The generation above the checkout a git WORKTREE at `from` was cut from, or `null`.
  *
- * `git rev-parse --git-common-dir` names the primary checkout's git directory; the
- * ordinary walk runs from the directory holding it. For a primary checkout, a clone
- * or a plain repo that is its own `.git`, so the answer is exactly what the walk up
- * from `from` already said. `null` on anything unexpected — no git, not a repo, a
- * directory that is not there — because inventing a root is the failure this module
- * is against.
+ * The primary checkout's git directory names the checkout; the ordinary walk runs from the
+ * directory holding it. For a primary checkout, a clone or a plain repo that is its own `.git`,
+ * so the answer is exactly what the walk up from `from` already said. `null` on anything
+ * unexpected — no git, not a repo, a directory that is not there — because inventing a root is
+ * the failure this module is against.
+ *
+ * 🔴 Read from the files first, and remembered, because `git` here was a HANG. Until 0.10.7 this
+ * spawned `git rev-parse --git-common-dir` on EVERY call, and in a worktree every call reaches it:
+ * roms' suite made 593 of them per run (`forgeState` ← `assertTestSafeDbPath`, `requireState`, …).
+ * Measured 2026-09-24 in a roms worktree: under `bun test --parallel=6`, about one run in three
+ * left a test worker spinning at 99% CPU inside `Bun.spawnSync` beside a `<defunct>` git child —
+ * Bun had missed the exit, and the 5 s `timeout` never fired. One gate stood 23 minutes. The
+ * primary checkout never saw it, because its walk up finds `forge.env` and never asks git. The
+ * same run from files: zero spawns. `git` remains only for a layout the files do not settle.
  */
 export function findForgeRootViaWorktree(from: string): string | null {
+	const key = resolve(from);
+	const remembered = viaWorktree.get(key);
+	if (remembered !== undefined) return remembered;
+	let answer: string | null = null;
 	try {
-		const git = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
-			cwd: from,
-			encoding: "utf8",
-			timeout: 5_000,
-		});
-		if (git.status !== 0) return null;
-		const common = (git.stdout ?? "").trim();
-		if (!common.startsWith("/")) return null;
-		return walkUp(dirname(common), MARKER);
+		const common = commonGitDirOnDisk(key) ?? commonGitDirFromGit(key);
+		answer = common ? walkUp(dirname(common), MARKER) : null;
 	} catch {
-		return null;
+		answer = null;
 	}
+	viaWorktree.set(key, answer);
+	return answer;
+}
+
+/** `git rev-parse --git-common-dir` — the fallback for a layout {@link commonGitDirOnDisk} cannot read. */
+function commonGitDirFromGit(from: string): string | null {
+	const git = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+		cwd: from,
+		encoding: "utf8",
+		timeout: 5_000,
+	});
+	if (git.status !== 0) return null;
+	const common = (git.stdout ?? "").trim();
+	return common.startsWith("/") ? common : null;
 }
 
 /**

package/src/workerDeploy.ts

@@ -357,6 +357,95 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 	return { code: 0, step: "done", detail, commit, dirty };
 }
 
+/**
+ * A RELAY app's whole `worker:deploy` (0.10.6) — the Worker holds no session and no D1 (the gate is
+ * the Mac's, answering down `cursedops/relay`), so the sequence is: the stage first, walked signed
+ * in, then build, ship with the `--var` stamp, smoke. `station` and `roms` each carried this as a
+ * 56-line script differing only in data (`tools/check-copies.baseline`, 2026-09-24).
+ *
+ * ```ts
+ * // the app's worker-deploy script, whole
+ * process.exit(relayWorkerDeployCli({ app: "roms", root: appRoot(), stateRoot: forgeState(), … }));
+ * ```
+ *
+ *     bun run worker:deploy                   # the stage, walked signed in; then build, ship, smoke production
+ *     bun run worker:deploy -- --env stage    # the stage alone: build, ship, smoke
+ *     bun run worker:deploy -- --no-build     # ship what is already in dist/
+ *
+ * No secrets step: the one secret, the link key's digest, is the app's `link:key` to set, because
+ * minting it is also rotating it. Returns the exit code — 2 for a missing credential or a bad
+ * `--env`, before anything runs — and never exits itself.
+ */
+export interface RelayWorkerDeploySpec {
+	/** For the messages, and the production Worker's script name unless {@link productionWorker} says otherwise. */
+	app: string;
+	/** The app's checkout — where every command runs. */
+	root: string;
+	/** `$FORGE_STATE` — the credential is `<stateRoot>/secrets/cloudflare.env`. */
+	stateRoot: string;
+	stampVars: { commit: string; dirty: string };
+	/** The build, run unless `--no-build`. It must produce what the stage walk's byte check compares. */
+	build: readonly string[];
+	/** `wrangler.jsonc` `env.stage.name`. */
+	stageWorker: string;
+	/** Default {@link RelayWorkerDeploySpec.app}. */
+	productionWorker?: string;
+	/** Printed after a green production deploy. */
+	previewUrl: string;
+	/** Printed after a green stage deploy. */
+	stageUrl: string;
+	/** Default `process.argv.slice(2)`. */
+	argv?: readonly string[];
+	/** The app's own scripts, relative to {@link RelayWorkerDeploySpec.root}. Defaults: `scripts/worker-deploy.ts`, `scripts/worker-stage.ts`, `scripts/worker-smoke.ts`. check-doc-citations:ignore app-relative defaults, in the consuming app's tree */
+	scripts?: { deploy?: string; stageWalk?: string; smoke?: string };
+	beforeStage?: readonly Refusal[];
+	beforeShip?: readonly Refusal[];
+	cpuTail?: readonly string[];
+}
+
+/** The {@link WorkerDeploySpec} a relay app's deploy runs — pure, so a suite can hold every field. */
+export function relayWorkerDeploySpec(spec: RelayWorkerDeploySpec, env: WorkerEnv, noBuild: boolean, credential: Record<string, string>): WorkerDeploySpec {
+	const script = { deploy: "scripts/worker-deploy.ts", stageWalk: "scripts/worker-stage.ts", smoke: "scripts/worker-smoke.ts", ...spec.scripts };
+	return {
+		app: spec.app,
+		env,
+		workerName: env === "stage" ? spec.stageWorker : (spec.productionWorker ?? spec.app),
+		databaseName: null,
+		stampVars: spec.stampVars,
+		build: noBuild ? null : spec.build,
+		stageFirst: [["bun", "run", script.deploy, "--env", "stage", ...(noBuild ? ["--no-build"] : [])]],
+		stageWalk: [["bun", "run", script.stageWalk]],
+		secrets: null,
+		smoke: ["bun", "run", script.smoke, ...(env === "stage" ? ["--env", "stage"] : [])],
+		credential,
+		...(spec.beforeStage ? { beforeStage: spec.beforeStage } : {}),
+		...(spec.beforeShip ? { beforeShip: spec.beforeShip } : {}),
+		...(spec.cpuTail ? { cpuTail: spec.cpuTail } : {}),
+	};
+}
+
+export function relayWorkerDeployCli(
+	spec: RelayWorkerDeploySpec,
+	deps: DeployDeps = workerDeployDeps(spec.root),
+	readCredential: (file: string) => Record<string, string> = cloudflareCredential,
+): number {
+	const argv = spec.argv ?? process.argv.slice(2);
+	const error = deps.error ?? ((line: string) => console.error(line));
+	const log = deps.log ?? ((line: string) => console.log(line));
+	let env: WorkerEnv;
+	let credential: Record<string, string>;
+	try {
+		env = parseWorkerEnv(argv);
+		credential = readCredential(join(spec.stateRoot, "secrets", "cloudflare.env"));
+	} catch (why) {
+		error(`[${spec.app}] ${why instanceof Error ? why.message : why}`);
+		return 2;
+	}
+	const result = runWorkerDeploy(relayWorkerDeploySpec(spec, env, argv.includes("--no-build"), credential), deps);
+	if (result.code === 0) log(`   ${env === "stage" ? spec.stageUrl : spec.previewUrl}`);
+	return result.code;
+}
+
 // ═════════════════════════════════════════════════════════════════════════════════════════════
 /**
  * THE WORKER CPU CHECK (0.7.0, task 2134) — what a Worker's requests REALLY cost, asserted on every deploy: a