cursedops 0.10.25 → 0.11.0

package/README.md

@@ -25,6 +25,7 @@ bun add cursedops
 | `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/ship` | the owner's FAST SHIPPING switch as every deploy reads it — `readShipSetting` (`$FORGE_STATE/state/autopilot/ship.json`; absent or unreadable is `fast`, no generation is `each`), `deferral`/`shipDeferral` (the sentence a production deploy prints instead of deploying, or `null`), `FORGE_SHIP_NOW=1` to ship now whatever it says. `runWorkerDeploy` asks it before installing anything; a Mac-side `bun run deploy` calls `shipDeferral` first (0.11.0) |
 | `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) |
@@ -95,6 +96,13 @@ Workers — so the choice was two more copies of the scanner or one here. Copies
 It is mechanism only: each app passes its own root and directories and keeps its own
 "not vacuous" assertion about which files the scan must reach.
 
+🔴 **`ship` is the fourth recorded exception: no app wrote it, because it is the switch the
+deploys themselves obey.** The owner's ruling (2026-09-28) was that agents run the same commands
+whatever the switch says and the commands deal with it — so it has to live in the one seam every
+production deploy passes through, which is `runWorkerDeploy` here and `deploy-tree`'s callers.
+It reads a file the runner owns and knows no app: rule 2 holds, and the header of `src/ship.ts`
+says why every failure reads as `fast`.
+
 ### What was deliberately left in the apps
 
 The comparison that produced this library found three areas that are genuinely

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedops",
-	"version": "0.10.25",
+	"version": "0.11.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 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": {
@@ -122,6 +122,12 @@
 			"source": "./src/deployTree.ts",
 			"import": "./src/deployTree.ts"
 		},
+		"./ship": {
+			"types": "./src/ship.ts",
+			"bun": "./src/ship.ts",
+			"source": "./src/ship.ts",
+			"import": "./src/ship.ts"
+		},
 		"./relay": {
 			"types": "./src/relay.ts",
 			"bun": "./src/relay.ts",

package/src/relayLink.ts

@@ -318,7 +318,7 @@ export async function rotateLinkKey(spec: RotateSpec): Promise<{ ok: true; file:
 	const put =
 		spec.putSecret ??
 		((name: string, value: string) => {
-			const r = spawnSync("bunx", ["wrangler@4", "secret", "put", name, ...(spec.env ? ["--env", spec.env] : [])], {
+			const r = spawnSync("bunx", ["wrangler", "secret", "put", name, ...(spec.env ? ["--env", spec.env] : [])], {
 				cwd: spec.appDir,
 				input: value,
 				env: { ...process.env, ...spec.credential },

package/src/relayStage.ts

@@ -54,6 +54,37 @@ export async function until(ms: number, ok: () => Promise<boolean>, clock: Clock
 	return false;
 }
 
+/**
+ * True once `isLinked` has said yes on every ask for a whole `windowMs` (default 15 s) — false if that
+ * never happens within `maxMs` (default 2 min). A throw counts as no, and restarts the window.
+ *
+ * 🔴 Why not a sleep and then {@link until}: a digest put is a new Worker version that reaches the
+ * edge in its own time, and `until` passes the first instant the link is up. Measured 2026-09-28 on
+ * station, beside three other deploys: the walk slept its fixed 10 s, the link came up, then flapped
+ * (`1002 Expected 101` — an edge still on the old digest refusing the new key) and the first
+ * signed-in read got the offline 503. `oldKeyRefused` already records that 15 s was not always
+ * enough. So the walk waits for a link that STAYS up, and how long that took is printed.
+ */
+export async function linkedSteadily(spec: {
+	isLinked: () => Promise<boolean>;
+	windowMs?: number;
+	maxMs?: number;
+	clock?: Clock;
+}): Promise<{ steady: boolean; seconds: number }> {
+	const clock = spec.clock ?? realClock;
+	const window = spec.windowMs ?? 15_000;
+	const started = clock.now();
+	let upSince: number | null = null;
+	while (clock.now() - started < (spec.maxMs ?? 120_000)) {
+		const up = await spec.isLinked().catch(() => false);
+		if (!up) upSince = null;
+		else if (upSince === null) upSince = clock.now();
+		else if (clock.now() - upSince >= window) return { steady: true, seconds: Math.round((clock.now() - started) / 1000) };
+		await clock.sleep(1_000);
+	}
+	return { steady: false, seconds: Math.round((clock.now() - started) / 1000) };
+}
+
 /** 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"] ?? "" };
@@ -142,10 +173,11 @@ export interface DigestPut {
 /**
  * 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.
+ * stderr. A secret put is a new version that reaches the edge in its own time: the caller waits for
+ * a link that stays up ({@link linkedSteadily}), never a fixed sleep.
  */
 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"], {
+	const done = (put.run ?? realRun)(["bunx", "wrangler", "secret", "put", put.secretName, "--env", "stage"], {
 		cwd: put.cwd,
 		input: await sha256Hex(put.key),
 		env: put.credential,

package/src/ship.ts

@@ -0,0 +1,149 @@
+/**
+ * 🚢 FAST SHIPPING — the owner's switch for when a production deploy happens: after each task
+ * (`each`), or once, at the end of a run of tasks (`fast`, the default).
+ *
+ * The owner's ruling, 2026-09-28:
+ *
+ * > *"While on, agents do not publish or do long running things at all if they block task
+ * > completions. Instead they keep doing tasks until the end and do a final test run and if
+ * > everything is perfect then they publish … While the toggle is off, things work like today …
+ * > I will generally want it on because a few hours of a broken deploy is generally not a deal
+ * > breaker if we can get a big increase in tasks completed."*
+ *
+ * and, on how agents should meet it: *"the same commands no matter what the toggle is set to and
+ * the automation commands deal with the changes automatically."* So this module is read by the
+ * COMMANDS — `runWorkerDeploy` and every Mac-side `bun run deploy` — not by an agent deciding
+ * whether to call them. Measured 2026-09-28 (`autopilot phases`): deploys ~110 min/day, publishes
+ * 45–120 min/day and the waits on them ~115 min/day had become the slowest things a task does,
+ * and a batch that touches one app three times deployed it three times.
+ *
+ * ## The contract — one small file the runner owns
+ *
+ * `$FORGE_STATE/state/autopilot/ship.json`, written only by `autopilot ship-mode` (the station
+ * console's switch runs it). This module only READS it, the same way `recordDeployEvent` writes the
+ * runner's `events.jsonl` without importing the runner: the file shape is the interface.
+ *
+ *     { "mode": "fast" | "each", "setBy": "owner", "at": "<ISO>", "reason"?: "…" }
+ *
+ * - **Absent → `fast`.** The owner asked for it on by default.
+ * - **Unreadable or a mode it does not know → `fast`**, the same answer as absent. Fast never puts
+ *   anything unproven on a production URL — it only makes the deploy LATER — so there is no
+ *   direction of a bad read that ships something it should not.
+ * - **No generation at all → `each`.** A checkout outside any `forge.env` has no runner to ship
+ *   for it later, so deferring there would defer for ever.
+ *
+ * ## The overrides, both directions
+ *
+ * `FORGE_SHIP_NOW=1` in the environment ships now whatever the switch says: the ship task's own
+ * deploys, an outage fix, and a deploy the owner asked for in words (his sentence beats a switch he
+ * flipped yesterday — the precedence the retired `fastMode.ts` settled on 2026-08-13). A stage
+ * deploy is never deferred: it IS the fast way to see a change on a real edge.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { forgeState } from "cursedops/roots";
+
+export const SHIP_MODES = ["fast", "each"] as const;
+export type ShipMode = (typeof SHIP_MODES)[number];
+
+/** The mode when the file is absent or unreadable — the owner's ruling, see the header. */
+export const DEFAULT_SHIP_MODE: ShipMode = "fast";
+
+/** `$FORGE_STATE/<this>` is the switch. The runner's `paths.ts` names the same file. */
+export const SHIP_FILE = join("state", "autopilot", "ship.json");
+
+/** The variable that ships now regardless of the switch. */
+export const SHIP_NOW_VAR = "FORGE_SHIP_NOW";
+
+export interface ShipSetting {
+	mode: ShipMode;
+	/** Who set it — `default` when no file says. */
+	setBy: string;
+	/** ISO, or `null` when nothing was ever written. */
+	at: string | null;
+	/** Why it reads as it does when the file could not be believed — shown, never thrown. */
+	unreadable?: string;
+}
+
+/** The switch as the file says it, with every failure read as {@link DEFAULT_SHIP_MODE}. */
+export function readShipSetting(state: string | null): ShipSetting {
+	if (state === null) return { mode: "each", setBy: "no generation", at: null };
+	const file = join(state, SHIP_FILE);
+	if (!existsSync(file)) return { mode: DEFAULT_SHIP_MODE, setBy: "default", at: null };
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf8")) as { mode?: unknown; setBy?: unknown; at?: unknown };
+		if (!SHIP_MODES.includes(raw.mode as ShipMode)) {
+			return { mode: DEFAULT_SHIP_MODE, setBy: "default", at: null, unreadable: `mode ${JSON.stringify(raw.mode)} is not one of ${SHIP_MODES.join(", ")}` };
+		}
+		return {
+			mode: raw.mode as ShipMode,
+			setBy: typeof raw.setBy === "string" && raw.setBy ? raw.setBy : "unknown",
+			at: typeof raw.at === "string" ? raw.at : null,
+		};
+	} catch (cause) {
+		return { mode: DEFAULT_SHIP_MODE, setBy: "default", at: null, unreadable: (cause as Error).message };
+	}
+}
+
+/** Is `FORGE_SHIP_NOW` set to something that means yes? */
+export function shipNowAsked(env: NodeJS.ProcessEnv = process.env): boolean {
+	const v = env[SHIP_NOW_VAR]?.trim().toLowerCase();
+	return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * The sentence a production deploy prints INSTEAD of deploying, or `null` to deploy now.
+ *
+ * The deploy then exits 0: it did what the mode asks of it. The app stays behind prod on purpose,
+ * and the runner's ship task — filed when the queue empties or the oldest owed commit is too old —
+ * deploys every app that is behind, once. `autopilot ship` lists what is owed.
+ */
+export function deferral(what: string, setting: ShipSetting, env: NodeJS.ProcessEnv = process.env): string | null {
+	if (setting.mode !== "fast" || shipNowAsked(env)) return null;
+	const by = setting.setBy === "default" ? "the default" : `set by ${setting.setBy}${setting.at ? ` at ${setting.at}` : ""}`;
+	return [
+		`🚢 ${what}: DEFERRED — fast shipping is on (${by}${setting.unreadable ? `; ship.json unreadable: ${setting.unreadable}` : ""}).`,
+		"   Nothing was deployed, and that is the intended result, not a failure: this app is now owed to",
+		"   the ship, which deploys every app behind its HEAD once, when the queue empties. Carry on with",
+		"   the next task — file this one as done once it is landed and gated, saying the deploy is owed.",
+		`   \`autopilot ship\` lists what is owed. To deploy now anyway (an outage fix, the ship itself, or`,
+		`   the owner asked for it): ${SHIP_NOW_VAR}=1 <the same command>.`,
+	].join("\n");
+}
+
+/**
+ * {@link deferral} for the checkout at `cwd` — what a Mac-side `bun run deploy` asks first:
+ *
+ *     const deferred = shipDeferral(appRoot(), "roms production deploy");
+ *     if (deferred) { console.log(deferred); process.exit(0); }
+ */
+export function shipDeferral(cwd: string, what: string, env: NodeJS.ProcessEnv = process.env): string | null {
+	return deferral(what, readShipSetting(forgeState(cwd, env)), env);
+}
+
+/** The ledger line a deferred production deploy leaves — what `autopilot ship` counts. */
+export interface ShipEventLine {
+	at: string;
+	kind: "ship";
+	what: "deferred";
+	repo: string;
+	env: string;
+	commit: string;
+	dirty: boolean;
+}
+
+/**
+ * Append one JSON line to the generation's ledger (`$FORGE_STATE/state/autopilot/events.jsonl`).
+ * Never throws; `false` when it did not write — a ledger that can fail a deploy is worse than none.
+ */
+export function appendLedger(state: string | null, line: object): boolean {
+	if (!state) return false;
+	try {
+		const file = join(state, "state", "autopilot", "events.jsonl");
+		mkdirSync(dirname(file), { recursive: true });
+		appendFileSync(file, `${JSON.stringify(line)}\n`);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/workerDeploy.ts

@@ -53,9 +53,10 @@
  * refusal without wrangler, git or a network.
  */
 import { spawn, spawnSync } from "node:child_process";
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { forgeState } from "cursedops/roots";
+import { appendLedger, deferral, readShipSetting, type ShipEventLine, type ShipSetting } from "cursedops/ship";
 
 /** The two deployments every Worker app here has. */
 export type WorkerEnv = "production" | "stage";
@@ -308,12 +309,26 @@ export interface DeployDeps {
 	error?: (line: string) => void;
 	/** The clock the legs are timed on. Default `Date.now`. */
 	now?: () => number;
+	/** Whether a path in the checkout exists — the local wrangler. Default `existsSync` against the process's cwd. */
+	exists?: (path: string) => boolean;
+	/** The unpublished library builds in `node_modules` ({@link previewMarks}). Default: read the process's cwd. */
+	previews?: () => PreviewMark[];
 	/**
 	 * Where the run's {@link DeployEventLine} goes, on EVERY exit — refused, red or green.
 	 * {@link workerDeployDeps} appends it to the generation's ledger; absent, nothing is recorded.
 	 * A throw here is swallowed: a ledger that can fail a deploy is worse than none.
 	 */
 	record?: (line: DeployEventLine) => void;
+	/**
+	 * The owner's fast-shipping switch ({@link readShipSetting}). {@link workerDeployDeps} reads the
+	 * generation's `ship.json`; absent here, the deploy behaves as it always did — so a suite that
+	 * builds its own deps never reads this Mac's switch.
+	 */
+	ship?: () => ShipSetting;
+	/** Where `FORGE_SHIP_NOW` is read from. Default `process.env`. */
+	env?: NodeJS.ProcessEnv;
+	/** Where a deferred production deploy's `ship` line goes. {@link workerDeployDeps} appends it to the ledger. */
+	recordShip?: (line: ShipEventLine) => void;
 }
 
 /**
@@ -349,15 +364,7 @@ export interface DeployEventLine {
 
 /** Append one line to the ledger under a state root. Never throws; `false` when it did not write. */
 export function recordDeployEvent(state: string | null, line: DeployEventLine): boolean {
-	if (!state) return false;
-	try {
-		const file = join(state, "state", "autopilot", "events.jsonl");
-		mkdirSync(dirname(file), { recursive: true });
-		appendFileSync(file, `${JSON.stringify(line)}\n`);
-		return true;
-	} catch {
-		return false;
-	}
+	return appendLedger(state, line);
 }
 
 export interface DeployResult {
@@ -400,6 +407,10 @@ export function workerDeployDeps(cwd: string): DeployDeps {
 		record: (line) => {
 			recordDeployEvent(forgeState(cwd), line);
 		},
+		ship: () => readShipSetting(forgeState(cwd)),
+		recordShip: (line) => {
+			appendLedger(forgeState(cwd), line);
+		},
 	};
 }
 
@@ -548,6 +559,90 @@ export function judgeSchemaApply(code: number, stdout: string): { applied: boole
  * Run the sequence in the header's order, stopping at the first red with a sentence. Never
  * exits — the caller does, with {@link DeployResult.code}.
  */
+/** Where an app's OWN wrangler is, once `bun install` has run. */
+export const LOCAL_WRANGLER = "node_modules/.bin/wrangler";
+
+/**
+ * Refuse a deploy whose app has no wrangler of its own — `null` when it has one.
+ *
+ * 🔴 Why (task 2260): with no local install, `bunx wrangler` resolves into ONE directory shared by
+ * every process on the Mac (`$TMPDIR/bunx-<uid>-wrangler@latest`), and bunx refreshes it in place.
+ * On 2026-09-28 it was rewritten at 12:17 while four deploys ran, and station's stage walk died on
+ * `Cannot find module './lib/websocket-server'` — a half-extracted `ws`. A version spec
+ * (`wrangler@4`) is worse: bunx then skips a local install even when there is one. So every app
+ * declares `wrangler` in its own `devDependencies`, locked by its own `bun.lock`, and nothing here
+ * passes bunx a version (`workerDeploy.test.ts` scans `src/` for one).
+ */
+export function localWranglerRefusal(exists: (path: string) => boolean): string | null {
+	if (exists(LOCAL_WRANGLER)) return null;
+	return `this app has no wrangler of its own (${LOCAL_WRANGLER} is missing), so \`bunx wrangler\` would use the one install every deploy on this Mac shares — and concurrent deploys have corrupted it mid-run. Run \`bun add -d wrangler@^4\` in the app and commit package.json and bun.lock. Nothing was deployed.`;
+}
+
+/** The file `tools/lib-preview.ts` writes INSIDE a package it overlaid with an unpublished build. */
+export const PREVIEW_MARK = ".lib-preview.json";
+
+/** One unpublished library build sitting in `node_modules` — what its {@link PREVIEW_MARK} says. */
+export interface PreviewMark {
+	lib: string;
+	/** The version in the library's own tree — never the one `bun.lock` names. */
+	version: string;
+	/** The library tree's HEAD when it was packed, `-dirty` when it had uncommitted changes. */
+	commit: string;
+}
+
+/**
+ * Every package under `nodeModules` (top level and `@scope/name`) carrying a {@link PREVIEW_MARK}.
+ *
+ * The mark lives inside the package's own directory, never beside it, so it cannot outlive the bytes
+ * it describes: an install that replaces the package (a lockfile bump, `--force`) removes it too.
+ * `bun install --frozen-lockfile` leaves an overlay whose `package.json` version matches the lock, so
+ * the preview writes the locked version there and its real one here (measured 2026-09-28).
+ */
+export function previewMarks(nodeModules = "node_modules"): PreviewMark[] {
+	const marks: PreviewMark[] = [];
+	const read = (dir: string): void => {
+		const file = join(dir, PREVIEW_MARK);
+		if (!existsSync(file)) return;
+		try {
+			const mark = JSON.parse(readFileSync(file, "utf8")) as Partial<PreviewMark>;
+			marks.push({ lib: mark.lib ?? dir, version: mark.version ?? "?", commit: mark.commit ?? "?" });
+		} catch {
+			marks.push({ lib: dir, version: "?", commit: "unreadable mark" });
+		}
+	};
+	let names: string[] = [];
+	try {
+		names = readdirSync(nodeModules);
+	} catch {
+		return marks;
+	}
+	for (const name of names) {
+		if (name.startsWith("@")) {
+			let scoped: string[] = [];
+			try {
+				scoped = readdirSync(join(nodeModules, name));
+			} catch {}
+			for (const inner of scoped) read(join(nodeModules, name, inner));
+		} else if (!name.startsWith(".")) read(join(nodeModules, name));
+	}
+	return marks;
+}
+
+/** `<lib>@<version> (<commit>)`, joined — how a deploy names what it would ship unpublished. */
+export function describePreviews(marks: readonly PreviewMark[]): string {
+	return marks.map((m) => `${m.lib}@${m.version} (${m.commit})`).join(", ");
+}
+
+/**
+ * Production never ships an unpublished library (task 2252) — `null` when nothing is previewed. A
+ * stage deploy ships it, says so, and stamps itself dirty: `/healthz` then says the bytes are not
+ * the commit's, which is true.
+ */
+export function previewRefusal(env: WorkerEnv, marks: readonly PreviewMark[]): string | null {
+	if (env !== "production" || marks.length === 0) return null;
+	return `node_modules holds an UNPUBLISHED build of ${describePreviews(marks)} — production ships only published libraries. Publish it (\`tools/publish-libs.sh\`), bump this app to it, or put the locked version back with \`bun $FORGE/tools/lib-preview.ts --restore\`. Nothing was deployed.`;
+}
+
 /** What {@link runWorkerDeploy} runs first: `node_modules` exactly as `bun.lock` says. */
 export const INSTALL: readonly string[] = ["bun", "install", "--frozen-lockfile"];
 
@@ -600,6 +695,21 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 	const unmeasured: string[] = [];
 
 	if (!commit) return stop("head", "this checkout has no readable HEAD — there is no commit to stamp, so nothing could prove the deploy.");
+	// 🚢 Fast shipping (`./ship.ts`): a production deploy made while the switch is on is owed to the
+	// runner's ship instead — asked before anything installs or builds, so deferring costs nothing.
+	// Its `ship` line, not a `deploy` one: a deferral is not a deploy, and would drag every median.
+	if (spec.env === "production" && deps.ship) {
+		const deferred = deferral(`${spec.app} production deploy`, deps.ship(), deps.env ?? process.env);
+		if (deferred) {
+			log(`\n${deferred}`);
+			try {
+				deps.recordShip?.({ at: new Date(started).toISOString(), kind: "ship", what: "deferred", repo: spec.app, env: spec.env, commit: commit.slice(0, 8), dirty });
+			} catch {
+				// never the deploy's verdict — see DeployDeps.record
+			}
+			return { code: 0, step: "deferred", detail: deferred, commit, dirty };
+		}
+	}
 	if (spec.env === "production" && dirty) {
 		return stop("clean-tree", `the tree is dirty — production would report ${commit.slice(0, 8)} and run something else:\n${porcelain}`);
 	}
@@ -631,6 +741,13 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 	if (deps.run(INSTALL, {}) !== 0) {
 		return stop("install", `\`${INSTALL.join(" ")}\` failed — node_modules cannot be made to match bun.lock, so nothing was built or deployed.`);
 	}
+	const noWrangler = localWranglerRefusal(deps.exists ?? existsSync);
+	if (noWrangler) return stop("wrangler", noWrangler);
+	const previews = (deps.previews ?? previewMarks)();
+	const previewed = previewRefusal(spec.env, previews);
+	if (previewed) return stop("preview", previewed);
+	if (previews.length > 0) log(`\n🟡 ${tag} this stage deploy ships an UNPUBLISHED ${describePreviews(previews)} — stamped dirty; production will refuse it until it is published`);
+	const shipsDirty = dirty || previews.length > 0;
 	if (spec.env === "production") {
 		for (const command of spec.stageFirst ?? []) {
 			step(`the stage first — production waits on it: ${command.join(" ")}`);
@@ -683,9 +800,9 @@ export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): Deplo
 			log(`  ${verdict.line}`);
 		}
 	}
-	step(`deploy ${spec.workerName} @ ${commit.slice(0, 8)}${dirty ? " (dirty — stage only)" : ""}`);
+	step(`deploy ${spec.workerName} @ ${commit.slice(0, 8)}${shipsDirty ? " (dirty — stage only)" : ""}`);
 	const stamp = spec.stampVars
-		? ["--var", `${spec.stampVars.commit}:${commit}`, "--var", `${spec.stampVars.dirty}:${dirty ? "true" : "false"}`]
+		? ["--var", `${spec.stampVars.commit}:${commit}`, "--var", `${spec.stampVars.dirty}:${shipsDirty ? "true" : "false"}`]
 		: [];
 	enter("upload");
 	if (deps.run(["bunx", "wrangler", "deploy", ...envArgs, ...stamp], spec.credential) !== 0) return stop("deploy", "wrangler deploy failed.");
@@ -1144,13 +1261,13 @@ export interface WorkerCpuDeps {
 	error: (line: string) => void;
 }
 
-/** The real {@link WorkerCpuDeps}: `bunx wrangler@4 tail`, pinned to the major whose JSON shape the parser reads. */
+/** The real {@link WorkerCpuDeps}: `bunx wrangler tail` — the APP's own wrangler, whose major (4) its `devDependencies` pin: {@link localWranglerRefusal}. */
 export function workerCpuDeps(): WorkerCpuDeps {
 	return {
 		startTail: (workerName, cwd, env) => {
 			let out = "";
 			let err = "";
-			const child = spawn("bunx", ["wrangler@4", "tail", workerName, "--format", "json"], {
+			const child = spawn("bunx", ["wrangler", "tail", workerName, "--format", "json"], {
 				cwd,
 				env: { ...process.env, ...env },
 				stdio: ["ignore", "pipe", "pipe"],