cursedops 0.4.0 → 0.5.0

package/README.md

@@ -8,9 +8,15 @@ bun add cursedops
 
 | subpath | what it is |
 |---|---|
-| `cursedops/roots` | finding a generation's roots, and a checkout's package root, without knowing a path |
-| `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent |
-| `cursedops/smoke` | the scaffolding of a deployed smoke — the ledger, the fetch, the DNS hint, the exit code — and the one check no app owns: every address of a deployment serving the same built client |
+| `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/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 |
+| `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-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) |
+| `cursedops/d1-import` | a cutover's data proof — SQL literals and the row-for-row comparison, never a count (0.5.0) |
 | `cursedops/serve` | the static tier's four helpers — the path-traversal guard, the MIME table, the hashed-asset test, the crash handlers |
 | `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 |
@@ -99,8 +105,15 @@ needs to read it:
 `deploy.ts` is a fourth: the two scripts share a shape and roughly thirty lines of
 helpers, but they sequence genuinely different steps and a shared deploy driver is
 exactly the 277-file mistake starting again. What they share instead is the **exit-code
-contract** in `cursedops/smoke` — `0` keep, `1` roll back, `2` edge fault, do not roll
-back — which is the only part both deploy scripts actually read.
+contract** in `cursedops/smoke` — `0` keep, `1` roll back, `2` not the app (the edge, the
+network, or the smoke's own environment), do not roll back — which is the only part both
+deploy scripts actually read.
+
+🔴 **The WORKER deploy is the other way round, and `cursedops/worker-deploy` is not this
+mistake made again.** The Mac `deploy.ts` scripts sequence genuinely different steps; the
+four Worker `worker-deploy.ts` scripts sequence the SAME nine, and a `diff` says so — what
+differed between them was which of the nine each copy had forgotten. So the sequence is
+shared and every step's command is data the app passes; see "The Worker toolkit" below.
 
 ## `cursedops/roots`
 
@@ -127,6 +140,54 @@ runs from there. A clone is its own primary and still gets `null`.
 library that hardcoded `$HOME/.<name>` would be correct for exactly one generation and
 silently wrong for its successor — which is the defect this replaced.
 
+### `repoCd` — a printed command that RUNS (0.5.0, task 092)
+
+```ts
+import { otherRepoCommand, repoCommand } from "cursedops/roots";
+
+const REPO_IN_FORGE = "apps/auth";            // the ONE thing the app keeps
+repoCommand(REPO_IN_FORGE, "bun run geo:build", import.meta.dir);
+// → source "…/forge.env" && cd "$FORGE/apps/auth" && bun run geo:build
+otherRepoCommand("apps/station", REPO_IN_FORGE, "bun run geo", import.meta.dir);
+```
+
+Rule 1: four repos wrote it — `apps/binary-server/src/repoCommand.ts` (the original,
+2026-09-18), `apps/auth/src/kit/repoCommand.ts`, and `scripts/forgeRoot.ts` in `family` and
+`roms`. Rule 3: `check-paths`' `deadCd` rule measured twelve printed commands in five repos
+`cd`-ing into directories two generations gone, each read at a moment something was already
+wrong. The segment is always the CALLER's (the library may not know a repo's name) and is
+refused if it is not a plain relative path; `from` is REQUIRED, because a default would be this
+library's own directory inside `node_modules`. A `$FORGE` with no `forge.env` in it is stale and
+is not honoured (`verifiedForgeRoot`; `forgeCodeRoot` keeps its older contract). Every fallback is
+a directory that EXISTS, and nothing composed here ever spells `cd ~/`. `repoCommand.test.ts`
+asserts on the COMPOSED string, which is the only thing `check-paths` cannot see.
+
+### The state root (task 160)
+
+Nothing new was needed: `forgeState(from, env)` / `requireForgeState(from, env)` already read
+`FORGE_STATE` out of the `forge.env` above the calling module, which is what a launchd job with
+no environment and a worktree both need. An app's hand-spelled `join(HOME, ".code", "<name>")`
+becomes `requireForgeState(import.meta.dir, env)`. Text generated for ANOTHER machine (a systemd
+unit, a shell installer) interpolates the VALUE — `relative(homedir(), requireForgeState(…))`
+after `%h/` or `$HOME/` — never the generation's name.
+
+## `cursedops/paths` (0.5.0, task 2089)
+
+```jsonc
+"paths": "forge-paths"                                 // check-paths + check-doc-citations
+"paths": "forge-paths --also check-gate-graph.ts"      // cursedbelt's extra law, as an OPTION
+```
+
+Rule 1, eighteen times: `scripts/paths.ts` was in every app, `autopilot` and every library,
+sixteen byte-identical and three already forked (`cursedbelt` +`check-gate-graph.ts`, `station`
++`check-no-clock.ts`, `autopilot` split into its own `generation.ts`). `check-copies` prices
+exported definitions and this file exports nothing, so eighteen copies read as zero. Rule 3: the
+wrapper exists because `bun ../../tools/check-paths.ts .` died on its first step in every
+worktree (2026-09-17). The walk and the worktree follow-back are the copies' own; **no
+generation is still no pass** — a lone clone exits 1 saying which walk came back empty. Every
+argument that is not `--also` passes through to the laws (`bun run paths --prune`). This repo
+dogfoods it: `"paths": "bun src/paths.ts"`, and its own copy is gone.
+
 ## `cursedops/launchd`
 
 ```ts
@@ -140,6 +201,10 @@ if (boot.code !== 0) throw new Error(boot.out);
 if (!(await answering(`http://127.0.0.1:${port}/healthz`))) throw new Error("a pid is not a service");
 ```
 
+`livePort(label)` (0.5.0) reads `PORT` out of the LIVE job's own `environment` block — the
+declaration the tunnel routes to — never `package.json`, which advertised the dev pair in eight
+of eight apps (`autopilot doctor`'s `ports` section, 2026-09-15, lifted with its fixture).
+
 `RunAtLoad` and `KeepAlive` are **not defaulted** — a server wants both, a nightly
 snapshot wants neither, and a kit that decides gets one of them wrong.
 
@@ -175,6 +240,40 @@ Only same-origin `.js`/`.css` references are compared, because the zone injects
 Analytics beacon in front of the edge and not on loopback — a check that reds on a
 healthy deploy is one somebody turns off.
 
+### The verdicts (0.5.0, task 069)
+
+```ts
+import { livePort } from "cursedops/launchd";
+import { createSmoke, probeOrigin } from "cursedops/smoke";
+
+const smoke = createSmoke({ base: PUBLIC_URL });
+if (!smoke.requireEnvironment({ CF_ACCESS_CLIENT_ID: env.CF_ACCESS_CLIENT_ID }, "source $FORGE_STATE/secrets/cloudflare-access.env")) {
+  process.exit(smoke.report());                    // 2 — the smoke could not judge; not the app
+}
+await probeOrigin(smoke, livePort(LABEL), { label: LABEL });   // a dead origin is 1, always
+// … the app's own checks against the public hostname …
+process.exit(await smoke.settle());                // asks the NETWORK before charging the app
+```
+
+A deployed smoke lied three ways, and each is now a verdict with a test of its failure path
+(`src/smokeVerdict.test.ts`):
+
+| lie | measured | verdict | exit |
+|---|---|---|---:|
+| PASSED about a dead origin | `patterns` and `collections` served a cached 200 over a 503 origin, every check green; four smokes made no loopback request at all | `origin` — `probeOrigin` asks `127.0.0.1:<livePort>`; no live port is no origin | **1**, whatever else the run saw |
+| FAILED about a healthy app, for want of the smoke's own credential | `desk`: `✗ FAILED — 5 of 6` because only the deploy script loaded the Access token | `environment` — `requireEnvironment` / `refuseEnvironment` | 2 |
+| FAILED about a healthy app, because the network substituted DNS | 2026-09-19, airline wifi answered `1.1.1.1` for a proxied host → `403 · Error 1034` | `network` — `settle()` runs `diagnoseNetwork`, `tools/check-public-dns.ts`' range invariant lifted | 2 |
+
+🔴 **No new exit code**, on purpose: every deploy script reads `0` keep, `2` stop without
+reverting, anything else REVERT (`apps/collections/scripts/deploy.ts:413-424` and four
+siblings). A `3` for "credential missing" would be reverted by all five. The distinction is in
+`verdict()` and in the sentence printed. And the network diagnosis **never retries and never
+pins an address** — the deliverable is the distinction, not a way around the network.
+
+`steadyHealth(ask, ready)` is the Worker smoke's wait: `ready` must hold for THREE reads in a
+row, because on `music`'s first deploy (2026-09-23, `a54ef71`) one good `/healthz` was followed
+by thirteen routes answering the pre-secrets version. It returns what answered and never judges.
+
 Nothing else. The checks are the part `desk` and `flix` wrote differently on purpose,
 and a shared kit that starts absorbing route lists and health-payload shapes is how the
 last one reached 277 files.
@@ -274,6 +373,40 @@ input the eight copies refused refused, at the same cost. A symlinked ancestor o
 root cancels out — which is the failure a one-sided `realpath` would have shipped to
 every app on this machine, and is its own test.
 
+## The Worker toolkit (0.5.0, task 2097)
+
+`cursedops/worker-deploy`, `/worker-secrets`, `/worker-rollback`, `/edge-fetch`, `/d1-import`.
+Rule 1, four times: `collections`, `vault`, `patterns` and `music` (copied from `vault` on
+2026-09-23) each carried the toolkit in `scripts/`, which `check-copies` did not scan. Rule 3:
+the copies had drifted in ways that cost something — `patterns` never refused a dirty tree nor
+stamped the commit, `vault` and `collections` judged a deploy after one `/healthz` read,
+`collections`' secrets upload never deleted an extra, `patterns`' rollback typed its route id,
+and only `collections`' import normalised a REAL. Each module header names its incident.
+Everything that shells out (wrangler, git, curl, dig) is injectable; the suite never touches a
+network.
+
+🔴 **`edge-fetch` is the fourth recorded exception.** Rule 1 asks for two INDEPENDENT
+implementations and this has one: `vault` wrote it and `music` copied it byte for byte. What
+admits it is that a verbatim copy is precisely what `check-copies` exists to refuse, the task
+that asked for this move named it, and every other part of the toolkit it serves is here — a
+Worker smoke that had to keep its transport in the app would keep a copy of the toolkit's
+most fragile part (a hand-rolled HTTP parser) in two places.
+
+| part | verdict |
+|---|---|
+| the deploy SEQUENCE (HEAD, clean tree, app refusals, stage first, build, schema, `--var` stamp, secrets, smoke) | **moved** — `runWorkerDeploy(spec, deps)`; the commands are data |
+| `parseWorkerEnv`, `wranglerEnvArgs`, `readWranglerJsonc`, `readEnvFile`, `cloudflareCredential` | **moved** — identical or converged in all four |
+| exact-set secrets over a pipe, read back | **moved** — `planSecrets` + `syncSecrets` + `wranglerSecretPut`; `envFileLines` carries `collections`' pre-quoted-seed fix |
+| origin-first rollback, route found by pattern | **moved** — `rollbackToOrigin`, `findWorkerRoute`, `deleteWorkerRoute` |
+| `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 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 |
+
 ## `cursedops/public-surface`
 
 ```sh

package/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "cursedops",
-	"version": "0.4.0",
-	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots without knowing a path, macOS launchd agent install/replace/remove, the scaffolding of a deployed smoke, and the static-serving helpers eight apps copied — the path-traversal guard among them — and 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, retried rather than cached when git loses a boot race — 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.5.0",
+	"description": "The build-and-ops answers this generation's apps wrote independently and identically: finding a generation's roots — and printing a command that runs when pasted — without knowing a path, the generation's whole-tree laws run over one repo from a checkout or a worktree, macOS launchd agent install/replace/remove and the live port a job serves, the scaffolding and verdicts of a deployed smoke (origin probe, the smoke's own environment, a network that lies about DNS, a settled version), the static-serving helpers eight apps copied — the path-traversal guard among them — the API floor that keeps an unmatched /api/... from ever being answered with the app shell, the commit and dirty flag a checkout-served process reports, the Cloudflare Worker deploy toolkit four apps copied (the deploy sequence, exact-set secrets over a pipe, origin-first rollback, the curl edge fetch, the row-for-row D1 import proof), and the public-surface ratchet three published libraries each carried a forked copy of. Mechanism only — no app knows its name from here. Bun, zero runtime dependencies (typescript is an optional peer, for public-surface only), ships source.",
 	"type": "module",
 	"scripts": {
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"lint": "biome check .",
 		"test": "bun test src",
-		"paths": "bun run scripts/paths.ts",
+		"paths": "bun src/paths.ts",
 		"verify": "bun run paths && bun run typecheck && bun run lint && bun run test",
 		"prepublishOnly": "bun run verify"
 	},
@@ -60,10 +60,47 @@
 			"source": "./src/publicSurface.ts",
 			"import": "./src/publicSurface.ts"
 		},
+		"./paths": {
+			"types": "./src/paths.ts",
+			"bun": "./src/paths.ts",
+			"source": "./src/paths.ts",
+			"import": "./src/paths.ts"
+		},
+		"./worker-deploy": {
+			"types": "./src/workerDeploy.ts",
+			"bun": "./src/workerDeploy.ts",
+			"source": "./src/workerDeploy.ts",
+			"import": "./src/workerDeploy.ts"
+		},
+		"./worker-secrets": {
+			"types": "./src/workerSecrets.ts",
+			"bun": "./src/workerSecrets.ts",
+			"source": "./src/workerSecrets.ts",
+			"import": "./src/workerSecrets.ts"
+		},
+		"./worker-rollback": {
+			"types": "./src/workerRollback.ts",
+			"bun": "./src/workerRollback.ts",
+			"source": "./src/workerRollback.ts",
+			"import": "./src/workerRollback.ts"
+		},
+		"./edge-fetch": {
+			"types": "./src/edgeFetch.ts",
+			"bun": "./src/edgeFetch.ts",
+			"source": "./src/edgeFetch.ts",
+			"import": "./src/edgeFetch.ts"
+		},
+		"./d1-import": {
+			"types": "./src/d1Import.ts",
+			"bun": "./src/d1Import.ts",
+			"source": "./src/d1Import.ts",
+			"import": "./src/d1Import.ts"
+		},
 		"./package.json": "./package.json"
 	},
 	"bin": {
-		"public-surface": "./src/publicSurface.ts"
+		"public-surface": "./src/publicSurface.ts",
+		"forge-paths": "./src/paths.ts"
 	},
 	"files": [
 		"src",

package/src/d1Import.ts

@@ -0,0 +1,124 @@
+/**
+ * `cursedops/d1-import` — the half of a cutover's data step that is the same in every app: turn
+ * a SQLite row into a SQL literal, and prove, ROW FOR ROW, that the source and D1 hold the same
+ * thing. Which tables move, in what order, and what is rebuilt rather than copied stay the app's.
+ *
+ * ```ts
+ * import { rowDifferences, sameRows, sqlLiteral, wranglerRows } from "cursedops/d1-import";
+ *
+ * const there = wranglerRows(d1(["--command", `SELECT ${cols} FROM "${table}"`]));
+ * const verdict = sameRows(here, there, columns);            // { same, here, there }
+ * const which = rowDifferences(here, there, columns, "id");  // the rows, not "some differ"
+ * ```
+ *
+ * ## 🔴 Row for row, never a count
+ *
+ * Two tables can hold the same NUMBER of different rows, and a count is exactly the check that
+ * cannot tell — on `collections`' catalogue that would have been a caption, a rotation or a
+ * checksum silently replaced by another file's. `collections`, `vault`, `patterns` and `music`
+ * each wrote this comparison (task 2097); the `rowDigest` bodies had drifted:
+ *
+ *   · `collections` normalised numbers — `bun:sqlite` hands back `0` where D1's JSON carries
+ *     `0.0`, and float noise past twelve significant digits — because `duration_seconds` is REAL
+ *     on 39 of its rows and a comparison that called those different reported the catalogue
+ *     corrupt on every run. `vault` and `music` did not normalise, and would have.
+ *   · `vault` and `music` spelled a BLOB as `X'…'` for the insert; `patterns` could not carry one.
+ *
+ * The body here is the union: numbers normalised, blobs compared as hex whichever side they came
+ * from (a `Uint8Array` from `bun:sqlite`, an array of bytes from D1's JSON), booleans as 0/1.
+ */
+
+/** A SQL literal for a value read out of our OWN database. Not an escaping library for input. */
+export function sqlLiteral(value: unknown): string {
+	if (value === null || value === undefined) return "NULL";
+	if (typeof value === "boolean") return value ? "1" : "0";
+	if (typeof value === "bigint") return String(value);
+	if (typeof value === "number") {
+		if (Number.isNaN(value)) return "NULL";
+		if (!Number.isFinite(value)) return value > 0 ? "9e999" : "-9e999";
+		return String(value);
+	}
+	if (value instanceof Uint8Array) return `X'${Buffer.from(value).toString("hex")}'`;
+	return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function cell(value: unknown): string | number | null {
+	if (value === null || value === undefined) return null;
+	if (typeof value === "boolean") return value ? 1 : 0;
+	if (typeof value === "bigint") return Number.isSafeInteger(Number(value)) ? Number(value) : String(value);
+	if (typeof value === "number") return Number.isInteger(value) ? value : Number(value.toPrecision(12));
+	if (value instanceof Uint8Array) return `blob:${Buffer.from(value).toString("hex")}`;
+	if (Array.isArray(value) && value.every((b) => typeof b === "number" && b >= 0 && b <= 255 && Number.isInteger(b))) {
+		return `blob:${Buffer.from(value as number[]).toString("hex")}`;
+	}
+	return String(value);
+}
+
+/** One row flattened to a comparable string over `columns` — see the header for the normalisation. */
+export function rowDigest(row: Readonly<Record<string, unknown>>, columns: readonly string[]): string {
+	return JSON.stringify(columns.map((column) => cell(row[column])));
+}
+
+/** Are the two sides the same MULTISET of rows over `columns`? Order-insensitive. */
+export function sameRows(
+	here: readonly Readonly<Record<string, unknown>>[],
+	there: readonly Readonly<Record<string, unknown>>[],
+	columns: readonly string[],
+): { same: boolean; here: number; there: number } {
+	const a = here.map((row) => rowDigest(row, columns)).sort();
+	const b = there.map((row) => rowDigest(row, columns)).sort();
+	return { same: a.length === b.length && a.every((digest, i) => digest === b[i]), here: a.length, there: b.length };
+}
+
+/**
+ * WHICH rows differ, by `key` — a row missing from D1, a column that differs, and (unless
+ * `allowExtras`) a row D1 has that the source does not. A cutover that has to go looking is a
+ * cutover that gets abandoned, so this names them rather than saying that some do.
+ *
+ * `allowExtras` is `collections`' SEED mode: a stage seeded from fixtures is then USED by its
+ * browser walk, so rows it gained are the stage working, not corruption. A MIRROR (production)
+ * never allows them — a row in production that is not in the source is a row from somewhere.
+ */
+export function rowDifferences(
+	here: readonly Readonly<Record<string, unknown>>[],
+	there: readonly Readonly<Record<string, unknown>>[],
+	columns: readonly string[],
+	key: string | readonly string[],
+	{ allowExtras = false } = {},
+): string[] {
+	const keys = typeof key === "string" ? [key] : [...key];
+	const id = (row: Readonly<Record<string, unknown>>) => rowDigest(row, keys);
+	const label = (row: Readonly<Record<string, unknown>>) => keys.map((k) => `${k}=${String(row[k])}`).join(",");
+	const byKey = new Map(there.map((row) => [id(row), row]));
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const row of here) {
+		const digest = id(row);
+		seen.add(digest);
+		const other = byKey.get(digest);
+		if (!other) {
+			out.push(`${label(row)} is in the source and not in D1`);
+			continue;
+		}
+		for (const column of columns) {
+			if (rowDigest(row, [column]) !== rowDigest(other, [column])) {
+				out.push(`${label(row)} · ${column}: source ${rowDigest(row, [column])} ≠ D1 ${rowDigest(other, [column])}`);
+			}
+		}
+	}
+	if (!allowExtras) for (const row of there) if (!seen.has(id(row))) out.push(`${label(row)} is in D1 and not in the source`);
+	return out;
+}
+
+/**
+ * The rows out of `wrangler d1 execute --json` stdout. wrangler prints banner text before the
+ * JSON on some versions, so the parse starts at the first `[` that opens an array; none at all THROWS — an empty
+ * read reported as "no rows" is how a comparison passes against a database it never saw.
+ */
+export function wranglerRows(stdout: string): Array<Record<string, unknown>> {
+	// The first `[` that opens a JSON array — `[{` or `[]` — never the `[ERROR]` of a failure banner.
+	const start = stdout.search(/\[\s*[{\]]/);
+	if (start < 0) throw new Error(`wrangler returned no JSON: ${stdout.slice(0, 200)}`);
+	const parsed = JSON.parse(stdout.slice(start)) as Array<{ results?: Array<Record<string, unknown>> }>;
+	return parsed.flatMap((result) => result.results ?? []);
+}

package/src/edgeFetch.ts

@@ -0,0 +1,152 @@
+/**
+ * `cursedops/edge-fetch` — a request to a deployed Worker as a SCRIPT must make it: `curl` with
+ * `--resolve` pinned to what Cloudflare's own resolver answers, plus whatever headers the app
+ * says a host needs (the fleet's Access service token on `*-stage`).
+ *
+ * ```ts
+ * import { cloudflareAccessHeaders, createEdgeFetch } from "cursedops/edge-fetch";
+ *
+ * export const edgeFetch = createEdgeFetch({
+ *   headersFor: (host) => (/-stage\./.test(host) ? cloudflareAccessHeaders(readFileSync(accessFile, "utf8")) : {}),
+ * });
+ * const response = await edgeFetch("https://thing-stage.example.com/healthz");
+ * ```
+ *
+ * ## 🔴 Why not `fetch`
+ *
+ * This Mac caches a NEGATIVE DNS answer, for the zone's SOA minimum, for a hostname asked before
+ * its record existed — and a stage's custom domain is created by its own first deploy, seconds
+ * before the smoke asks it. Flushing that cache needs sudo. The smoke and the walk are about the
+ * Worker, not this laptop's resolver, so they ask `1.1.1.1` directly. `vault` wrote it; `music`
+ * copied it byte for byte on 2026-09-23 (task 2097).
+ *
+ * 🔴 **This is a transport for proving a WORKER, not a verdict on a network.** Pinning the address
+ * is exactly why it cannot tell you whether the network a person is sitting on is lying — that
+ * question is `diagnoseNetwork` in `cursedops/smoke`, which never pins and never retries. Pass
+ * `resolve: null` to ask through the system resolver instead.
+ *
+ * Bytes go through a temporary file, so a binary body (ciphertext, audio) arrives unmangled, and
+ * the response body after the LAST header block is bytes — an interim `1xx` block precedes it.
+ */
+import { spawnSync } from "node:child_process";
+import { rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface CurlRun {
+	status: number | null;
+	stdout: Buffer;
+}
+
+export interface EdgeFetchOptions {
+	/** Extra headers for a host — an Access service token, say. Default: none. */
+	headersFor?: (host: string) => Record<string, string>;
+	/**
+	 * The IPv4 address to pin a host to, or `null`/`""` for none. Default: `dig +short <host> @1.1.1.1`.
+	 * Pass `null` (not a function) to never pin.
+	 */
+	resolve?: ((host: string) => string | null) | null;
+	/** Injected for tests. Runs curl with `args`. */
+	curl?: (args: readonly string[]) => CurlRun;
+	/** Where a request body is staged. Default: the OS temp dir. */
+	tmpDir?: string;
+	/** curl's `--max-time`. Default 60. */
+	maxTimeSec?: number;
+}
+
+function digCloudflare(host: string): string | null {
+	const dig = spawnSync("dig", ["+short", host, "@1.1.1.1"], { encoding: "utf8" });
+	return (
+		(dig.stdout ?? "")
+			.split("\n")
+			.map((line) => line.trim())
+			.find((line) => /^\d+\.\d+\.\d+\.\d+$/.test(line)) ?? null
+	);
+}
+
+/**
+ * `curl -s -i` output → a `Response`. THROWS on empty output (nothing answered), which a caller
+ * must see as a failure and never as a status.
+ */
+export function parseCurlResponse(raw: Buffer, origin = "the edge", exit: number | null = null): Response {
+	if (raw.length === 0) throw new Error(`no answer from ${origin} (curl exit ${exit})`);
+	let offset = 0;
+	let head: string[] = [];
+	for (;;) {
+		const end = raw.indexOf("\r\n\r\n", offset);
+		const stop = end < 0 ? raw.length : end;
+		head = raw.subarray(offset, stop).toString("latin1").split("\r\n");
+		offset = end < 0 ? raw.length : end + 4;
+		if (!/^HTTP\/\S+ 1\d\d/.test(head[0] ?? "") || raw.subarray(offset, offset + 5).toString("latin1") !== "HTTP/") break;
+	}
+	const status = Number(/HTTP\/\S+ (\d+)/.exec(head[0] ?? "")?.[1] ?? 0);
+	const headers = new Headers();
+	for (const line of head.slice(1)) {
+		const i = line.indexOf(":");
+		if (i > 0) headers.append(line.slice(0, i).trim(), line.slice(i + 1).trim());
+	}
+	const body = raw.subarray(offset);
+	return new Response(status === 204 || status === 304 ? null : new Uint8Array(body), { status: status || 599, headers });
+}
+
+/** A `fetch`-shaped function over curl — see the header. Each host is resolved once per instance. */
+export function createEdgeFetch(options: EdgeFetchOptions = {}): (url: string, init?: RequestInit) => Promise<Response> {
+	const pinned = new Map<string, string>();
+	const resolve = options.resolve === undefined ? digCloudflare : options.resolve;
+	const curl =
+		options.curl ??
+		((args: readonly string[]): CurlRun => {
+			const out = spawnSync("curl", [...args], { maxBuffer: 256 * 1024 * 1024 });
+			return { status: out.status, stdout: out.stdout ?? Buffer.alloc(0) };
+		});
+	let sequence = 0;
+	return async (url, init = {}) => {
+		const target = new URL(url);
+		if (resolve && !pinned.has(target.hostname)) pinned.set(target.hostname, resolve(target.hostname) ?? "");
+		const ip = pinned.get(target.hostname);
+		const port = target.port || (target.protocol === "http:" ? "80" : "443");
+		const args = ["-s", "-i", "--max-time", String(options.maxTimeSec ?? 60), ...(ip ? ["--resolve", `${target.hostname}:${port}:${ip}`] : [])];
+		for (const [k, v] of Object.entries(options.headersFor?.(target.hostname) ?? {})) args.push("-H", `${k}: ${v}`);
+		new Headers(init.headers).forEach((v, k) => {
+			args.push("-H", `${k}: ${v}`);
+		});
+		if (init.method) args.push("-X", init.method);
+		let bodyFile: string | null = null;
+		if (init.body !== undefined && init.body !== null) {
+			bodyFile = join(options.tmpDir ?? tmpdir(), `edge-fetch-${process.pid}-${++sequence}-${Date.now()}.bin`);
+			const body = init.body;
+			writeFileSync(
+				bodyFile,
+				typeof body === "string" ? body : body instanceof Uint8Array ? body : new Uint8Array(await new Response(body as BodyInit).arrayBuffer()),
+			);
+			args.push("--data-binary", `@${bodyFile}`);
+		}
+		try {
+			const out = curl([...args, target.toString()]);
+			return parseCurlResponse(out.stdout, target.origin, out.status);
+		} finally {
+			if (bodyFile) rmSync(bodyFile, { force: true });
+		}
+	};
+}
+
+/**
+ * The Access service-token headers out of an env file holding `CF_ACCESS_CLIENT_ID` and
+ * `CF_ACCESS_CLIENT_SECRET`. THROWS, naming what is missing, rather than sending empty headers —
+ * an empty token reads at the far end as "Access refused the app", which is the exact
+ * misattribution a smoke must not make.
+ */
+export function cloudflareAccessHeaders(envText: string): Record<string, string> {
+	const value = (key: string) =>
+		(envText.split("\n").find((line) => line.trim().replace(/^export\s+/, "").startsWith(`${key}=`)) ?? "")
+			.trim()
+			.replace(/^export\s+/, "")
+			.slice(key.length + 1)
+			.trim()
+			.replace(/^['"]|['"]$/g, "");
+	const id = value("CF_ACCESS_CLIENT_ID");
+	const secret = value("CF_ACCESS_CLIENT_SECRET");
+	const missing = [...(id ? [] : ["CF_ACCESS_CLIENT_ID"]), ...(secret ? [] : ["CF_ACCESS_CLIENT_SECRET"])];
+	if (missing.length > 0) throw new Error(`the Access service token is incomplete: no ${missing.join(" and no ")}`);
+	return { "CF-Access-Client-Id": id, "CF-Access-Client-Secret": secret };
+}

package/src/launchd.ts

@@ -403,3 +403,43 @@ export async function answering(
 		await sleep(stepMs);
 	}
 }
+
+/**
+ * The `PORT` a `launchctl print` dump says the job is handed, or `null`.
+ *
+ * 🔴 Only the job's OWN `environment = {` block. The same dump carries `inherited environment`
+ * and `default environment`, and a `PORT` leaking in from the session that bootstrapped the job
+ * is not what launchd hands the next start — reading one of those reports a number nothing
+ * serves on. Lifted from `autopilot/src/ports.ts` (`portFromPrint`), whose fixture this carries.
+ */
+export function portFromPrint(printed: string): number | null {
+	let inside = false;
+	for (const line of printed.split("\n")) {
+		if (/^[ \t]*environment[ \t]*=[ \t]*\{[ \t]*$/.test(line)) {
+			inside = true;
+			continue;
+		}
+		if (!inside) continue;
+		if (/^[ \t]*\}[ \t]*$/.test(line)) break;
+		const m = line.match(/^[ \t]*PORT[ \t]*=>[ \t]*(\d+)[ \t]*$/);
+		if (m?.[1]) return Number(m[1]);
+	}
+	return null;
+}
+
+/**
+ * The port the LIVE job `label` serves on — read off launchd, never off the repo — or `null`
+ * when the job is not loaded or declares no `PORT`.
+ *
+ * 🔴 Measured 2026-09-15 by `autopilot doctor`'s `ports` section: `package.json` advertised the
+ * wrong port in **eight of eight** apps (it is the dev pair), and a smoke that asked it would
+ * prove nothing about the process traffic reaches. The declaration launchd holds is what the
+ * tunnel routes to and what the next start is handed, so it is the one a deployed smoke's
+ * origin probe asks. A `null` is not a pass: the caller records it as "there is no origin".
+ */
+export function livePort(label: string, ops: Partial<LaunchdOps> = {}): number | null {
+	const { run, domain } = realOps(ops);
+	const printed = run("print", `${domain}/${label}`);
+	if (printed.code !== 0) return null;
+	return portFromPrint(printed.out);
+}