cursedops 0.13.1 → 0.14.0

package/README.md

@@ -6,490 +6,41 @@ Build-and-ops answers that the apps here wrote independently and identically.
 bun add cursedops
 ```
 
+See `docs/decisions.md` for why this library exists, its entry rules, and what was
+deliberately left in the apps instead. See `docs/reference.md` for every subpath's
+import shape, worked example, and the incident each one is pinned to.
+
 | 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); 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 |
-| `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); `readWranglerFile(root)` since 0.9.0, lifted from four apps' `readWrangler` (task 2153); since 0.10.25 every run, red or green, appends a `kind: "deploy"` line with each leg's wall clock (`install`, `stage`, `walk`, `build`, `schema`, `upload`, `secrets`, `smoke`) to the generation's ledger (task 2246) |
-| `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) — and read again, up to five times, before a set that is not exact is believed: the list lags the puts (0.11.1) |
-| `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); a request's own `maxTimeSec` over the instance's (0.11.1) |
-| `cursedops/d1-columns` | the schema step's first half: any COLUMN `db/schema.sql` has and a live D1 table lacks, read in one `pragma_table_info` query and added by `ALTER TABLE … ADD COLUMN` — refusing a key, UNIQUE, or NOT NULL-without-DEFAULT column. `runWorkerDeploy` runs it for every app with a `databaseName` (0.13.0, task 2488, lifted from roms) |
-| `cursedops/d1-import` | a cutover's data proof — SQL literals and the row-for-row comparison, never a count (0.5.0); and `d1SchemaText`, the generated `db/schema.sql` that refuses a statement spanning lines, because D1's exec splits on newlines (0.9.0, lifted from five apps, task 2153) — and its `forge-d1-schema` bin (0.9.1), so no app carries its own schema script at all |
-| `cursedops/backups` | `BACKUP_KEEP`, the fleet's one retention for dated snapshots — six apps each exported `KEEP = 14` (0.9.0, task 2153); `BACKUP_STAMP_PATTERN`, `backupStamp` and its inverse `stampTime` — the local-time run name every backup script writes and station's audit reads (0.11.2) |
+| `cursedops/roots` | finding a generation's roots and a checkout's package root without knowing a path, and `repoCd`/`repoCommand`, the `cd` prefix of a printed command that RUNS when pasted |
+| `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 |
+| `cursedops/launchd` | installing, replacing and removing a macOS launchd user agent, and the port a LIVE job serves on (`livePort`) |
+| `cursedops/smoke` | the scaffolding of a deployed smoke (ledger, fetch, DNS hint, exit code) — the one check no app owns — plus 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 — plus a billed-CPU tail wrapped around the walk and the smoke, and a ledger line per run |
+| `cursedops/worker-secrets` | a Worker holding EXACTLY its deployment's secrets, uploaded over a pipe, read back up to five times before an inexact set is believed |
+| `cursedops/worker-rollback` | a hostname back on its Mac origin — origin first, route second, the route found rather than typed |
+| `cursedops/edge-fetch` | a request to a deployed Worker the way a script must make it — curl pinned past the Mac's negative DNS cache |
+| `cursedops/d1-columns` | the schema step's first half — any column `db/schema.sql` has that a live D1 table lacks, added by `ALTER TABLE … ADD COLUMN` |
+| `cursedops/d1-import` | a cutover's data proof — row-for-row, never a count — and `d1SchemaText`/its `forge-d1-schema` bin, the generated schema no app hand-writes |
+| `cursedops/backups` | `BACKUP_KEEP`, the fleet's one retention for dated snapshots; `BACKUP_STAMP_PATTERN`, `backupStamp` and `stampTime` |
 | `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 |
-| `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). Since 0.12.0 `shipNowVerdict` honours ship-now under `$AUTOPILOT_BATCH` only for a batch holding a live claim on the ship task or a `prod-down:` incident, with `FORGE_SHIP_NOW_WHY` set, and every ask is a `kind: "ship-now"` ledger row (task 2384) |
-| `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-client` | does a relay app's PUBLIC hostname serve the client this release built? `comparePublicClient` (built assets the shells name, never bodies), `stagedShell`, `publicShell` (cache-busted, Access headers as an option), `recordPublicClient` — the smoke's `public-client` row, an EDGE fault (exit 2, never a rollback) — and `shipClientIfBehind`, the deploy step that runs `worker:deploy` when the public shell is behind. Lifted from roms for station (0.10.8). `stagedBuild` + `publicBuild` (0.10.18): pass `stagedBuild` and the commit the public `/build.json` names must be this release's too — `/`'s asset names cannot see a change to another page or a fixed-name file. `builtClient(dir)` (0.10.20): the commit and entry chunk a built `dist/` carries — what a relay smoke's `awaitConverged` asks the edge for |
-| `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 |
+| `cursedops/worker-safety` | the two static checks every Worker app's suite runs over its own source — the import-graph walk an app's own test does from `worker/index.ts` (a value import of `bun:sqlite` or a Bun-only subpath is a deploy that goes green and a Worker that never starts), and the await port's silent shapes (`rows.filter(async …)` keeps every row) |
+| `cursedops/api-floor` | the rule that an unmatched `/api/...` is a phrase and never the app shell — the namespace predicates, the trailing-slash normaliser, the default 404 body |
+| `cursedops/build-info` | which commit a checkout-served process is running and whether its tree was dirty, read once at load. `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 |
+| `cursedops/staged-client` | the IMMUTABLE client a checkout-served app serves — a build staged into `<APP_DATA_DIR>/client/<commit>/` behind `CURRENT` |
+| `cursedops/deploy-tree` | the two refusals a checkout-served deploy needs — never deploy a dirty tree, never `git revert` in one |
+| `cursedops/ship` | the owner's FAST SHIPPING switch as every deploy reads it — `readShipSetting`, `shipDeferral`, `FORGE_SHIP_NOW=1` to ship now whatever it says |
+| `cursedops/relay` | the WORKER half of a relay — a Worker in front of a Mac-bound app over ONE outbound WebSocket, the frame wire, the key-digest door, and the Durable Object an app subclasses |
+| `cursedops/relay-link` | the MAC half — `dialLink`, `readLinkSettings`, `rotateLinkKey` |
+| `cursedops/relay-stage` | the signed-in STAGE WALK's skeleton both relay apps shared |
+| `cursedops/public-client` | does a relay app's PUBLIC hostname serve the client this release built? — `comparePublicClient`, `recordPublicClient`, `shipClientIfBehind` |
+| `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 |
 
 Bun, zero runtime dependencies, ships TypeScript source. Nothing here knows an app's
 name, a hostname, a port or a route. `typescript` is an **optional** peer: only
 `cursedops/public-surface` imports it, and nothing else here ever loads it.
 
-## 🔴 The ceiling, and why this library has one
-
-This exists because `apps/desk` and `apps/flix` answered the same six build-and-ops
-questions independently, and **three of the six came out the same**. It does not exist
-because sharing is good.
-
-The library it replaces reached **277 files** in a previous generation, on the reasoning
-that a module used by 8 of 8 apps is a module worth sharing. What that produced was an
-app whose entire `vite.config.ts` was one line it could not read, a build system no app
-could opt out of, and a monorepo that could not be relocated. Every one of those 277
-files was individually defensible.
-
-So the entry rule here is arithmetic, not judgement:
-
-1. **Two apps wrote it independently.** Not one app and a plan for a second — two
-   working implementations, in the tree, that a `diff` says are the same.
-2. **It is mechanism, not identity.** If a function would need to know an app's name,
-   port, hostname, routes or health-payload shape, it belongs in the app. Every
-   function here takes those as arguments or does not see them at all.
-3. **It is a trap somebody paid for.** Each thing in here is a measured incident turned
-   into a check — the file headers carry the dates and the costs. A convenience that
-   has never prevented anything is not a reason to add a dependency to eight apps.
-
-A fourth rule follows from the first three: **an addition that only one app will use
-does not go in.** That is a library that exists to be refactored later.
-
-🔴 **`sameDeployedShell` is the one entry that rule 1 did not let in, and it is recorded
-here rather than quietly excepted.** It was written once, by `patterns`, not twice —
-what admits it is rule 3 at a size rule 1 cannot measure: the fault it catches was
-invisible for six days on the app that had it, and the other five apps behind or moving
-behind an edge Worker still cannot tell a working deploy from a working cache. A check
-told ONE NAME is a check about that name; this one is about a property every deployment
-with two addresses has. It buys the exception by being pinned to a failure it has
-actually caught — `src/smoke.test.ts` runs it against the genuine 2026-09-12 shell.
-
-🔴 **`public-surface` is the second recorded exception, and the first whose callers are
-not apps.** Rule 1 is met — more than met — but by three LIBRARIES: `cwip`, `cursedbelt`
-and `cursedbelt-server` each carried `scripts/publicSurface.ts` (430, 455 and 476 lines),
-and by 0.2.6 the bodies had already forked, which is what admits it. Measured 2026-09-22:
-`cwip`'s threw on a bare-specifier `export *` where the other two resolved and counted
-it, so the three numbers were not commensurable; and when the ESM-extension fix (task
-269) made `./x.js` the spelling of an internal specifier, `cursedbelt-server`'s and
-`cursedbelt`'s copies each had to be taught `./x.js` → `./x.ts` by hand, separately,
-while `cwip`'s never was. Each library is published on its own and its gate must pass
-from a lone checkout, so neither a `file:` import nor a reach into `$FORGE/tools` could
-share it; a published version could, and this package is already that for the fleet.
-It is a devDependency of each library, so nothing their consumers install changed. On
-adoption all three measured **identical per-subpath counts** to their own copies
-(`cwip` 60 subpaths/2,089 symbols, `cursedbelt` 51/1,837, `cursedbelt-server` 34/992) —
-a consolidation that moves a count has changed the measurement, not the plumbing.
-
-🔴 **`bound-lists` is the third recorded exception, admitted by rule 3 at three consumers.**
-It was written once, by `collections` (`src/server/boundLists.test.ts`, 2026-09-22), after
-the shape it refuses drew an empty gallery for every folder over 100 files on D1. The same
-day `music` was found carrying 24 sites and `vault` four — the identical trap in two more D1
-Workers — so the choice was two more copies of the scanner or one here. Copies are what
-`check-copies` exists to refuse, and a forked scanner is a check that quietly stops matching.
-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
-different and must stay that way. `tasks/Procedures/graduate-an-app.md` in the
-generation repo carries the full verdict table, because the next app to graduate is who
-needs to read it:
-
-- **the build** — `desk` compiles a single binary with `bun build --compile`; `flix` is
-  a Vite SPA with an asset budget. Not the same problem.
-- **the supervisor** — `desk` runs a watcher that rebuilds on a commit; `flix`
-  deliberately has none, and its deploy reinstalls the agent instead. That difference
-  changes what a rollback *is* in each app.
-- **the app config** — how an app decides it is deployed, and what that turns on, is the
-  app.
-
-`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` 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`
-
-```ts
-import { forgeRootFrom, packageRootFrom, requireForgeState } from "cursedops/roots";
-
-const generation = forgeRootFrom(import.meta.url);   // string | null
-const checkout = packageRootFrom(import.meta.url);   // string | null
-const state = requireForgeState(import.meta.dir);    // string, or a thrown message
-```
-
-A generation is defined by a `forge.env` above the checkout — the same rule its
-`check-paths` and its runner use, so the three cannot disagree. Everything returns
-`null` rather than guessing, because a function that invented a root would write files
-into a stranger's tree.
-
-🔴 **A git worktree counts** (0.2.5). Worktrees live outside every generation by
-construction, so the walk up alone answered `null` there and a repo whose gate asks for
-the root was red in every worktree — the runner's subset gate included. When the walk
-fails, `git rev-parse --git-common-dir` leads back to the primary checkout and the walk
-runs from there. A clone is its own primary and still gets `null`.
-
-🔴 The state root is **read out of `forge.env`**, never spelled here. A published
-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
-"gate":  "forge-paths --only gate.ts"                  // 0.5.3: the shared gate runner, and ONLY it
-```
-
-`--only <law>` (0.5.3, task 474) replaces the default laws instead of adding to them, so a repo's
-`gate` reaches `$FORGE/tools/gate.ts` through the same walk without running `check-paths` a
-second time or handing it `--force`. A law it names that is missing from `tools/` exits 1.
-
-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`/`--only` passes through to the laws (`bun run paths --prune`).
-
-🔴 **Until the roster rule can read the bin, the wrapper is two lines that NAME the laws.**
-`check-doc-citations`' `pathsRunsThis` proves a repo runs it by reading the `paths` command or
-the one `scripts/` file it delegates to, so a bare `forge-paths` reads as unwired. The form that
-passes today — and the one this repo uses — is:
-
-```ts
-// scripts/paths.ts, with "paths": "bun run scripts/paths.ts"
-import { runGenerationLaws } from "cursedops/paths";
-process.exit(runGenerationLaws(import.meta.dir, { laws: ["check-paths.ts", "check-doc-citations.ts"], argv: process.argv.slice(2) }));
-```
-
-## `cursedops/launchd`
-
-```ts
-import { renderPlist, replaceAgent, answering, declaredBy } from "cursedops/launchd";
-
-const conflict = await declaredBy(LABEL, "managed-by=olddeployer");
-if (conflict) throw new Error(`a retired deployer still declares ${LABEL}: ${conflict}`);
-
-const { boot } = await replaceAgent(LABEL, renderPlist(spec), { also: LEGACY_LABELS });
-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.
-
-## `cursedops/smoke`
-
-```ts
-import { createSmoke, guarded } from "cursedops/smoke";
-
-const smoke = createSmoke({ base: process.env.MYAPP_SMOKE_URL ?? "https://…" });
-await guarded(smoke, "gate", async () => {
-  const response = await smoke.anonymous("/api/v1/private");
-  smoke.record("gate", response.status === 401, `anonymous → ${response.status}`);
-});
-smoke.finish();   // exits 0, 1 or 2
-```
-
-One check, and it is about the ADDRESSES of a deployment rather than about any app:
-
-```ts
-import { sameDeployedShell } from "cursedops/smoke";
-
-// every address of one deployment, not "edge vs origin" — an app may have no
-// origin left. A Worker's second address is its uncached *.workers.dev preview.
-await sameDeployedShell(smoke, [smoke.base, `http://127.0.0.1:${port}`]);
-```
-
-🔴 It refuses when the addresses name different built assets, and it records that as an
-**edge fault (exit 2), never a rollback** — the origin is serving what this checkout
-built, and reverting it cannot reach the Worker, cache rule or Assets binding in front.
-Measured 2026-09-18 on `patterns`: the edge served a shell built 2026-09-12 out of a
-Worker nobody knew about, and every automated surface stayed green for **six days**.
-Only same-origin `.js`/`.css` references are compared, because the zone injects a Web
-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.
-A read that THROWS (0.11.1) is a bad read asked again, bounded by `deadlineMs` (240 s), and only
-a LAST read that threw is thrown to the caller: the 2026-09-29 ship reported family and music red
-on a first `/healthz` that timed out twice while the edge was between versions (task 2291).
-`runWorkerSmoke` asks each of those reads with a 10 s curl `--max-time`
-(`HEALTH_READ_MAX_TIME_SEC`, passed as `EdgeRequestInit.maxTimeSec`), so the window costs 20 s a
-read instead of 120.
-
-`awaitConverged(probes)` (0.10.19) is the same wait over SEVERAL paths: every probe must agree
-three rounds in a row, bounded (120 s), before any leg is judged — a Worker's code and its static
-assets reach the edge separately (roms `f9273ea`, task 2196: `/healthz` at HEAD while the old
-script answered `/host/install.sh` and the new chunk 404'd). A wait that runs out says
-`never converged in Ns — <what lagged>`, and the caller records it as a red row.
-
-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.
-
-## `cursedops/api-floor`
-
-```ts
-import { API_PREFIX, apiNotFoundBody, canonicalApiPath, canonicalApiRequest } from "cursedops/api-floor";
-
-// AFTER the app's routes, BEFORE the static catch-all, and `all` not `get`.
-const floor = (c) => {
-  const urlPath = new URL(c.req.url).pathname;
-  // A trailing slash is never meaningful under /api/ — re-dispatch, once.
-  if (canonicalApiPath(urlPath) !== null) return app.fetch(canonicalApiRequest(c.req.raw));
-  return Response.json(apiNotFoundBody(c.req.method, urlPath, "myapp", commit), { status: 404 });
-};
-app.all(API_PREFIX, floor);
-app.all(`${API_PREFIX}/*`, floor);
-```
-
-🔴 Measured 2026-09-17 on `station`: a page that had never loaded on any commit, because
-its client asked for `/api/openclaw/`, Hono mounts a sub-app's `get("/")` at the mount
-point without the trailing slash and matches strictly, and the miss fell into
-`app.get("*")` and came back as 1.7 KB of `index.html` **with a 200**. The client read
-that HTML honestly — *"an API older than this page"* — and sent the owner to deploy a
-commit that could not have helped.
-
-🔴 Wire it **inside the router**, never as a wrapper around the host's `fetch`. A router
-has more callers than `Bun.serve` — a Worker's `export default`, and every harness that
-drives `app.fetch` — and a wrap installed at one of them is absent from the rest. That is
-the exact fault the previous generation's artifact shipped for six days with a green
-harness.
-
-Both patterns are registered although `"/api/*"` alone already matches a bare `/api` on
-hono@4.13.7 (measured 2026-09-18) — that is an undocumented property of one matcher
-version, and one extra route registration is cheaper than a floor with a hole in it the
-day it tightens.
-
-No `node:` import, no `Bun.` global, no `process` — asserted by `apiFloor.test.ts`, not
-by this paragraph — so it mounts unchanged inside a Cloudflare Worker, which is where
-`patterns` mounts it. `apiNotFoundBody` is the DEFAULT body and not the only one: an app
-whose API namespace is not behind a gate keeps a terser phrase of its own and takes the
-predicates.
-
-## `cursedops/serve`
-
-```ts
-import { contentTypeFor, fileWithin, installCrashHandlers, isHashedAsset } from "cursedops/serve";
-
-installCrashHandlers("myapp");                        // one log line, then exit 1
-const file = fileWithin(clientDir, url.pathname);     // null unless it is really inside
-if (!file) return c.notFound();
-return new Response(Bun.file(file), {
-  headers: {
-    "content-type": contentTypeFor(file),
-    "cache-control": isHashedAsset(url.pathname) ? ONE_YEAR : "no-cache",
-  },
-});
-```
-
-🔴 `fileWithin` is the reason this subpath exists rather than the convenience of the
-other three. It is the check that stops `%2e%2e%2f` reaching the filesystem, and on
-2026-09-17 there were **eight** of it — one per app, character-identical, with nothing in
-the generation counting them. Eight copies of a security guarantee are eight guarantees:
-a fix in one is a fix in one.
-
-### The verdict for every symbol in the `serve.ts` family
-
-Measured 2026-09-17 across `collections`, `family`, `flix`, `music`, `patterns`, `roms`,
-`station` and `vault` — the eight apps that have a `src/server/serve.ts`. The files are
-247–387 lines and all eight differ, which is why no `diff` ever flagged them; the bodies
-below were compared with whitespace and comments normalised away.
-
-| symbol | identical in | verdict |
-|---|---:|---|
-| `fileWithin` | 8 of 8 | **moved.** The traversal guard. Entry rule 3 — a trap somebody paid for — in its purest form |
-| `installCrashHandlers` | 8 of 8 | **moved.** The app's name is a parameter; it is the only app-shaped thing the four touch |
-| `contentTypeFor` | 8 of 8 | **moved.** Extension → MIME, plus its private `CONTENT_TYPES` table, which was also 8 of 8 |
-| `isHashedAsset` | 8 of 8 | **moved.** Vite's own output convention, which is the bundler's identity and not the app's |
-| `clientDirOf` | 6 of 6 that have it | **stays.** One line, and six apps pin it with their own `clientDir.test.ts` against their own `vite.config.ts`. WHERE an app's build writes is app identity — entry rule 2 — and it is the line that once served `public/` and took a live app down |
-| `createServer` / `createApp` | 0 — all eight differ | **stays.** Route tables, health payloads, gates and body limits. This is the 277-file mistake's front door |
-| `parseRange` / `fileResponse` | `flix` and `station` only | **stays for now.** Two apps, so rule 1 is satisfiable, but rule 3 is not: nothing has been paid for yet, and a `Range` implementation shared by two apps that stream different things is a guess. The trigger to revisit is a THIRD app that needs byte ranges |
-| `API_PREFIX`, `isApiPath`, `canonicalApiPath`, `canonicalApiRequest`, `apiNotFoundBody` | `station` only | **stays.** One app, and rule 4 says an addition one app will use does not go in. `apiNotFoundBody` also writes a sentence the owner reads on a page — identity, not mechanism |
-
-🔴 **The task that ordered this move recorded `contentTypeFor` and `isHashedAsset` as
-7 of 8, with `station` differing. They did not differ.** All four bodies were identical
-in all eight apps when the move was made, so nothing had to converge and no app's
-behaviour changed on adoption. The count came from a census of the whole `serve.ts`
-family rather than of these two bodies; `bun tools/check-copies.ts` in the generation
-repo is the live answer either way.
-
-One behaviour is NOT a byte-for-byte carry, and `src/serve.ts`'s header argues it in
-full: the eight copies checked containment lexically and were therefore blind to a
-symlink under the root pointing out of it. `fileWithin` here resolves the real path of
-**both** sides after the lexical check, which refuses the escape while leaving every
-input the eight copies refused refused, at the same cost. A symlinked ancestor of the
-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; `--mint` carries the keys `mintCarries` names (0.10.13; default `FILE_TOKEN_PRIVATE_KEY`, flix's is `PLEX_ACCOUNT_TOKEN`) |
-| origin-first rollback, route found by pattern | **moved** — `rollbackToOrigin`, `findWorkerRoute`, `deleteWorkerRoute`; the whole `worker:rollback` main is `runWorkerRollback(spec, argv)` (0.10.13 — flix and music were one copied file) |
-| `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
-# in the library's package.json — `bun run surface` / `bun run surface --prune`
-"surface": "public-surface"            # cwip adds --peers
-```
-
-```ts
-import { run } from "cursedops/public-surface";
-
-const { fresh, grown, stale, peers } = await run({ root: packageDir });   // all four [] when clean
-```
-
-`publicSurface.baseline` at the package root is one `<count>  <subpath>` line per
-export subpath. It fails on a subpath the baseline does not list, on one that GREW, and
-on an entry that shrank or matches nothing — so a deleted module cannot leave an
-allowance behind. `--prune` only ever lowers; new surface is a line added by hand in a
-commit that says why. What a count includes and excludes, and the three measurements
-that each produced a copy of this, are in the header of `src/publicSurface.ts`.
-
-It is a check a library runs on ITSELF. It never asks who imports the library — that
-is cross-repo, and a repo's gate proves that repo.
-
 ## Verifying
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedops",
-	"version": "0.13.1",
+	"version": "0.14.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": {

package/src/workerSecrets.ts

@@ -36,6 +36,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 // The package's own subpath, never `./workerDeploy.ts`: shipped source may not import a sibling
 // by relative path (`publishShape.test.ts` says why), and a self-reference resolves through the
 // same `exports` map every consumer's does.
@@ -168,14 +169,40 @@ export interface ApiResult {
 
 export type CloudflareApi = (path: string, init?: RequestInit) => Promise<ApiResult>;
 
-/** A Cloudflare v4 API caller for `token`. `fetch` injectable for tests. */
-export function cloudflareApi(token: string, send: typeof fetch = fetch): CloudflareApi {
+/** Tries per idempotent (GET/DELETE) call whose fetch THROWS — see {@link cloudflareApi}. */
+export const API_IDEMPOTENT_ATTEMPTS = 3;
+
+/**
+ * A Cloudflare v4 API caller for `token`. `fetch` and the backoff `pause` injectable for tests.
+ *
+ * 🔴 **A GET or DELETE whose fetch throws is tried again, up to {@link API_IDEMPOTENT_ATTEMPTS}
+ * times.** On 2026-10-04 (ship run 16-39-21) desk-stage and collections-stage both died in the
+ * same second on the first secrets list — `The socket connection was closed unexpectedly` — and
+ * were left uploaded with no secrets, serving nothing. Asking again changes nothing a GET or DELETE
+ * did not already change. An HTTP status is an ANSWER and is returned as-is; a thrown POST/PUT/PATCH
+ * is never retried, because it may have landed.
+ */
+export function cloudflareApi(
+	token: string,
+	send: typeof fetch = fetch,
+	pause: (ms: number) => Promise<void> = (ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)),
+): CloudflareApi {
 	return async (path, init = {}) => {
-		const response = await send(`https://api.cloudflare.com/client/v4${path}`, {
-			...init,
-			headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-			signal: init.signal ?? AbortSignal.timeout(30_000),
-		});
+		const method = (init.method ?? "GET").toUpperCase();
+		const attempts = method === "GET" || method === "DELETE" ? API_IDEMPOTENT_ATTEMPTS : 1;
+		let response: Response | undefined;
+		for (let tries = 1; !response; tries++) {
+			try {
+				response = await send(`https://api.cloudflare.com/client/v4${path}`, {
+					...init,
+					headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+					signal: init.signal ?? AbortSignal.timeout(30_000),
+				});
+			} catch (error) {
+				if (tries >= attempts || init.signal?.aborted) throw error;
+				await pause(1_000 * tries);
+			}
+		}
 		return (await response.json().catch(() => ({ success: false, errors: [`HTTP ${response.status}, not JSON`] }))) as ApiResult;
 	};
 }
@@ -248,6 +275,43 @@ export const THROWAWAY_SECRETS = {
 	FILE_TOKEN_PRIVATE_KEY: "FILE_TOKEN_PRIVATE_KEY",
 } as const;
 
+/**
+ * binary-server's delete barrier for STAGE tenants (forge tasks 2795, 2797). `DELETE /media` takes
+ * binary-server's `STAGE_DELETE_SECRET` in place of the fleet's shared secret only when the token
+ * resolves to an `<app>-stage` tenant — so a stage holding it deletes its own bytes and none of
+ * production's. Without it every delete on a stage failed: `remove requires internalSecret`.
+ *
+ *   · `worker` — the name the app's binary store reads it under, the same as production's.
+ *   · `file` — the key it is kept under in `<app>-worker-stage.env`, so nobody mistakes it there for
+ *     the fleet secret.
+ *   · `source` — where a mint copies it from: `STAGE_DELETE_SECRET` in `binary-server.env`, the sibling
+ *     of the app's own `<app>.env`. A copy, never a mint: binary-server must hold the same value.
+ */
+export const STAGE_DELETE_SECRET = {
+	worker: "BINARY_SERVER_INTERNAL_SECRET",
+	file: "BINARY_SERVER_STAGE_DELETE_SECRET",
+	source: { file: "binary-server.env", key: "STAGE_DELETE_SECRET" },
+} as const;
+
+/** Every stage that deletes media on binary-server: the throwaway set, plus {@link STAGE_DELETE_SECRET}. */
+export const STAGE_SECRETS = {
+	...THROWAWAY_SECRETS,
+	[STAGE_DELETE_SECRET.worker]: STAGE_DELETE_SECRET.file,
+} as const;
+
+/**
+ * binary-server's stage delete secret, read from `binary-server.env` in `secretsDir`
+ * (`$FORGE_STATE/secrets`), or null when that file or the key is absent.
+ */
+export function readStageDeleteSecret(secretsDir: string, read: (path: string) => string | null = readIfThere): string | null {
+	const value = readEnvFile(read(join(secretsDir, STAGE_DELETE_SECRET.source.file)) ?? "")[STAGE_DELETE_SECRET.source.key]?.trim();
+	return value || null;
+}
+
+function readIfThere(path: string): string | null {
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
 /** What {@link runWorkerSecrets} needs to know about ONE app's ONE deployment — data, no logic. */
 export interface WorkerSecretsSpec {
 	/** `family`, `music` — prefixes every message and names the Mac's `<app>.env`. */
@@ -311,6 +375,18 @@ export async function runWorkerSecrets(
 			}
 			carried[key] = value;
 		}
+		// A set that names the stage delete secret gets binary-server's own value, so a re-mint keeps
+		// the stage able to delete instead of dropping the key the upload then refuses without.
+		if (Object.values(spec.secrets).includes(STAGE_DELETE_SECRET.file)) {
+			const value = readStageDeleteSecret(dirname(spec.macSecretsFile), read);
+			if (!value) {
+				console.error(
+					`${tag} ${STAGE_DELETE_SECRET.source.file} carries no ${STAGE_DELETE_SECRET.source.key} — without it this stage cannot delete its own media.`,
+				);
+				return 2;
+			}
+			carried[STAGE_DELETE_SECRET.file] = value;
+		}
 		const who = spec.env === "stage" ? "the STAGE" : "the PREVIEW";
 		(deps.write ?? writeSecretsFile)(
 			spec.secretsFile,