@bongos/core 1.19.882 → 1.19.884

package/tests/ship_land_proof.mjs

@@ -0,0 +1,218 @@
+// tests/ship_land_proof.mjs
+//
+// task 1004055 — the ship that merges to main and then refuses to record it.
+//
+// ship.js has three land paths. Two of them tell the server which commit is this
+// task's: ciLandLocal posts attest-gate after its push, ciLandServer gets it from
+// publish-branch. The LOCAL-merge path (mergeLocally, 'laptop' deploy mode) merged
+// into main and pushed it ITSELF, and told the server nothing — so
+// claims.published_head_sha stayed NULL. It also opens no PR and deletes the branch
+// on origin, so getPublishStatus finds nothing by head ref either. That left
+// deriveShipAssurance with neither of its two proofs, and the POST /ship three lines
+// later refused with ship_land_not_proven EVERY time, with the work already merged.
+// The task parked at 'confirmed', gating its builder's whole queue, until someone ran
+// attest-gate + ship by hand. Five consecutive ships on 2026-09-19; twelve refusals
+// in that day's audit log.
+//
+// What is pinned here:
+//   1. attestGateTrust REPORTS whether the tip landed, and never throws
+//   2. landProofRecorded's truth table — including the pinned-older-core fallback
+//   3. the warning is in the right TENSE for the path that emits it
+//   4. the local-merge path records a tip, before it deletes the branch
+//
+// DB-free and network-free: the only collaborator attestGateTrust has is cli-lib's
+// cliClient, stubbed through the require cache below. Nothing here spawns git, gh,
+// or a server.
+//
+// Run:  node tests/ship_land_proof.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+// The stub MUST be in place before ship-land.js is first required — it destructures
+// cliClient at module load.
+let nextAttest = null;
+const cliLibPath = require.resolve('../scripts/gds/cli-lib');
+require.cache[cliLibPath] = {
+  id: cliLibPath,
+  filename: cliLibPath,
+  loaded: true,
+  exports: {
+    cliClient: async () => ({
+      tasks: {
+        postTasksIdAttestGate: async ({ id, body }) => {
+          if (typeof nextAttest === 'function') return nextAttest({ id, body });
+          return nextAttest;
+        },
+      },
+    }),
+    isBoxScope: () => false,
+  },
+};
+
+const { attestGateTrust, landProofRecorded, landProofWarningLines } = require('../scripts/gds/ship-land.js');
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// attestGateTrust narrates to stdout; swallow that so the test output stays readable.
+async function quietly(fn) {
+  const real = console.log;
+  const said = [];
+  console.log = (...a) => said.push(a.join(' '));
+  try { return { value: await fn(), said: said.join('\n') }; }
+  finally { console.log = real; }
+}
+
+const MERGE_SHA = '5c4db10e2a1f4c6b8d3e9f70a1b2c3d4e5f60718';
+
+// --- 1. attestGateTrust reports, and never throws -----------------------------
+
+await t('a 200 carrying tip_recorded:true → recorded, and the sha is what we sent', async () => {
+  let seen = null;
+  nextAttest = ({ id, body }) => {
+    seen = { id, body };
+    return { ok: true, status: 200, data: { ok: true, attested: true, reason: null, tip_recorded: true } };
+  };
+  const { value } = await quietly(() => attestGateTrust(1004055, MERGE_SHA));
+  assert.equal(value.recorded, true);
+  assert.equal(value.attested, true);
+  assert.deepEqual(seen, { id: 1004055, body: { head_sha: MERGE_SHA } });
+});
+
+// The case the field exists for: the attestation succeeded, so the old code called
+// the whole thing a success — but no claim row matched, so nothing was recorded and
+// the ship was already doomed.
+await t('a 200 whose claim lookup matched nothing → NOT recorded, even though attested', async () => {
+  nextAttest = { ok: true, status: 200, data: { ok: true, attested: true, reason: null, tip_recorded: false } };
+  const { value } = await quietly(() => attestGateTrust(1004055, MERGE_SHA));
+  assert.equal(value.attested, true, 'the gate attestation did succeed');
+  assert.equal(value.recorded, false, 'but the land proof did not land');
+});
+
+await t('a 503 push_unconfigured still recorded the tip (the write precedes the credential check)', async () => {
+  nextAttest = { ok: false, status: 503, data: { error: { code: 'push_unconfigured', details: { tip_recorded: true } } } };
+  const { value } = await quietly(() => attestGateTrust(1004055, MERGE_SHA));
+  assert.equal(value.recorded, true);
+  assert.equal(value.attested, false);
+});
+
+await t('a 403 never reached the write → NOT recorded', async () => {
+  nextAttest = { ok: false, status: 403, data: { error: { code: 'not_your_task' } } };
+  const { value } = await quietly(() => attestGateTrust(1004055, MERGE_SHA));
+  assert.equal(value.recorded, false);
+});
+
+// The quietest of the old failure shapes: a bare `catch (_) {}` left no trace at all.
+await t('a thrown request is reported, not swallowed, and never propagates', async () => {
+  nextAttest = () => { throw new Error('fetch failed'); };
+  const { value, said } = await quietly(() => attestGateTrust(1004055, MERGE_SHA));
+  assert.equal(value.recorded, false);
+  assert.match(value.reason, /fetch failed/);
+  assert.match(said, /fetch failed/, 'the failure must reach the log too, not only the return value');
+});
+
+await t('no head SHA → not recorded, and no request is attempted', async () => {
+  nextAttest = () => { throw new Error('should not have been called'); };
+  const { value } = await quietly(() => attestGateTrust(1004055, null));
+  assert.equal(value.recorded, false);
+});
+
+// --- 2. landProofRecorded: the truth table ------------------------------------
+
+await t('explicit tip_recorded wins over any status reading', () => {
+  assert.equal(landProofRecorded({ ok: true, status: 200, data: { tip_recorded: true } }), true);
+  assert.equal(landProofRecorded({ ok: true, status: 200, data: { tip_recorded: false } }), false);
+  assert.equal(landProofRecorded({ ok: false, status: 503, data: { error: { details: { tip_recorded: false } } } }), false);
+});
+
+// A live instance runs a PINNED core, so it lags main by however long the pin sits
+// still — cloudbongos.com was serving 1.19.871 against a main declaring 1.19.881 on
+// the day this was diagnosed. Those servers send no tip_recorded at all, and reading
+// its absence as "not recorded" would make every healthy land cry wolf.
+await t('older core, no tip_recorded: 200 and 503 both mean the tip landed', () => {
+  assert.equal(landProofRecorded({ ok: true, status: 200, data: { ok: true, attested: false, reason: 'rank_below_metic' } }), true);
+  assert.equal(landProofRecorded({ ok: false, status: 503, data: { error: { code: 'push_unconfigured' } } }), true);
+});
+
+await t('older core: every other status → NOT recorded', () => {
+  for (const status of [400, 403, 404, 409, 500, 502]) {
+    assert.equal(
+      landProofRecorded({ ok: false, status, data: { error: { code: 'not_your_task' } } }),
+      false,
+      `HTTP ${status} must not count as a recorded tip`
+    );
+  }
+});
+
+await t('no response at all → NOT recorded', () => {
+  assert.equal(landProofRecorded(null), false);
+  assert.equal(landProofRecorded(undefined), false);
+  assert.equal(landProofRecorded({}), false);
+});
+
+// --- 3. the warning is in the right tense -------------------------------------
+
+await t('merged path: names the merge sha and gives the full two-call recovery', () => {
+  const lines = landProofWarningLines(1004055, MERGE_SHA).join('\n');
+  assert.match(lines, /NOT recorded/);
+  assert.match(lines, /merge IS on main/);
+  assert.ok(lines.includes(`"head_sha":"${MERGE_SHA}"`), 'must name the exact sha to re-record');
+  assert.match(lines, /POST \/tasks\/1004055\/attest-gate/);
+  assert.match(lines, /POST \/tasks\/1004055\/ship/);
+});
+
+// The PR path has only PUSHED — the land may still be minutes out, and telling a
+// builder their merge is on main when it is not is the same class of lie this whole
+// task is about.
+await t('un-merged path: does not claim the work is on main, and does not ship blind', () => {
+  const lines = landProofWarningLines(1004055, MERGE_SHA, 'HTTP 403', { merged: false }).join('\n');
+  assert.doesNotMatch(lines, /merge IS on main/);
+  assert.match(lines, /the PR still lands normally/);
+  assert.ok(!lines.includes('/ship --body'), 'must not hand over a ship call before anything merged');
+  assert.match(lines, /ship\.js 1004055/);
+});
+
+await t('the reason is surfaced, and a missing sha degrades to a placeholder', () => {
+  assert.match(landProofWarningLines(7, MERGE_SHA, 'HTTP 403').join('\n'), /HTTP 403/);
+  assert.match(landProofWarningLines(7, null).join('\n'), /<the merge commit on main>/);
+});
+
+// --- 4. the local-merge path records a tip at all -----------------------------
+//
+// mergeLocally has no dependency seam — it merges a real second checkout, runs smoke
+// and pushes main — so this is asserted against the source. Weaker than driving it,
+// but it is exactly the assertion that failed before the fix: the file contained no
+// reference to ANY of the three ways to record a tip, and the order of the two calls
+// is the other half of the bug (deleting the branch first destroys the only evidence
+// a later sweep could have used).
+
+const mergeSrc = fs.readFileSync(fileURLToPath(new URL('../scripts/gds/ship-merge.js', import.meta.url)), 'utf8');
+
+await t('ship-merge.js records the merge commit as this task\'s land proof', () => {
+  assert.match(mergeSrc, /attestGateTrust\(taskId, mergeSha\)/,
+    'the local-merge path must record a land proof — before the fix it recorded none');
+});
+
+await t('the proof is recorded BEFORE the origin branch is deleted', () => {
+  const attestAt = mergeSrc.indexOf('attestGateTrust(taskId, mergeSha)');
+  const deleteAt = mergeSrc.indexOf("'--delete'");
+  assert.ok(attestAt > 0, 'the attest call must be present');
+  assert.ok(deleteAt > 0, 'the branch delete must be present');
+  assert.ok(attestAt < deleteAt, 'the land proof must be recorded before the branch is deleted');
+});
+
+await t('a miss reaches the builder at the merge, not as an opaque 409 later', () => {
+  assert.match(mergeSrc, /landProofWarningLines\(taskId, mergeSha, proof\.reason\)/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/docs/recipes/builder-box-lifecycle.md

@@ -1,181 +0,0 @@
-# Recipe — per-builder dev box lifecycle (provision · auto-suspend · reclaim)
-
-> **Task [#598](https://example.com/builders#/task/598) · [ADR 0031](../adr/0031-cloud-dev-environments-for-builders.md) §2/§5/§9.3.** This is the operator guide for the per-builder DigitalOcean dev boxes. The code ships in the repo; **going live is a deliberate, money-spending operator action** (like `provision-staging.sh`) — nothing here runs until you set `DO_API_TOKEN` and pass `--apply`.
-
-## The shape
-
-Each builder gets **one** box (ADR 0031 §2). Its lifecycle is a small state machine tracked in the `builder_boxes` table:
-
-```
-none --provision--> active
-                     ^  |
-   wake (manual, or  |  | idle > BOX_IDLE_MINUTES (auto, hourly)
-   on next connect)  |  | park (manual)
-                     |  v
-                    parked --- parked > BOX_DORMANT_DAYS ---> destroyed
-                               (auto, daily, WARNS FIRST)     snapshot deleted
-
-  park keeps the SNAPSHOT (only the droplet is destroyed, to stop billing),
-  so it is reversible with `wake`. Dormant reclaim is the ONLY automated
-  path that destroys a snapshot, and it warns the builder first.
-```
-
-- **provision** — create + boot a droplet running the [#596](https://example.com/builders#/task/596) devcontainer. **Rank-gated.**
-- **idle park** (auto, hourly) — when an `active` box is idle > `BOX_IDLE_MINUTES`, snapshot it and **destroy the droplet only**, keeping the snapshot ([task 1002726](https://example.com/builders#/task/1002726)). Compute billing stops; the box is **reversible** via `wake`. An earlier revision ([task 804](https://example.com/builders#/task/804)) destroyed the snapshot too; that was reverted because it took uncommitted work with it (spike [task 837](https://example.com/builders#/task/837)).
-- **park** (the idle sweep, or an Archon by hand) — snapshot the droplet then **destroy the droplet**. A powered-off DO droplet still bills; only a destroyed one stops. The snapshot (~$0.30/mo) is the cheap residual you can `wake` from.
-- **wake** (manual, on demand) — recreate the droplet from its snapshot. New IP; the `hostname` is repointed via `BOX_DNS_HOOK`.
-- **dormant reclaim** (auto, daily) — destroy the snapshot of a box `parked` > `BOX_DORMANT_DAYS`. This is the **only automated path that destroys a snapshot**, so it **warns the builder first** and defers the reclaim if that warning was never delivered ([task 1002727](https://example.com/builders#/task/1002727)). Its input is whatever the idle sweep parked, plus any manual Archon park.
-
-### How "idle" is detected
-
-The idle sweep **parks** a box when its `last_activity_at` (else `active_since`) is older than `BOX_IDLE_MINUTES` **and** `claude_active` is not true. Both signals are set by **`infra/box-heartbeat.sh`**, which runs **inside the box** every ~5 min and POSTs `/api/gds/box/heartbeat` *only while the box is in use* — an interactive login session, an established SSH connection, an **open browser terminal** (ttyd websocket, [#1161](https://example.com/builders#/task/1161)), or non-trivial CPU load. Silence = the sweep is free to park it.
-
-> ⚠️ **The idle sweep's correctness depends on the box-side heartbeat reaching the server.** If it isn't pinging — no Bongos token on the box yet, a pre-[#1161](https://example.com/builders#/task/1161) script that can't see a browser terminal, or the cron not installed — `last_activity_at` never advances and the sweep falls back to `active_since`, i.e. it measures **uptime**, not activity, and will **park** a box someone is actively using. Because the idle path keeps the snapshot ([task 1002726](https://example.com/builders#/task/1002726)), that box can be restored with `wake` and no work is lost — it is disruptive, not destructive. The destructive case is the dormant sweep, which warns first ([task 1002727](https://example.com/builders#/task/1002727)).
->
-> **Live mitigation (2026-06-16):** `BOX_IDLE_MINUTES` is raised to **120** in `/etc/example/box.env` as a soak margin until [#1161](https://example.com/builders#/task/1161)'s browser-terminal heartbeat is verified on a newcomer box; lower it back toward the 10-min default once that's proven.
-
-Two sweeps automate the middle (both mirror `stale-claim-release` — dry-run first, idempotent, capped):
-
-| Sweep | Cadence | What it does | Threshold |
-|---|---|---|---|
-| `box-idle-suspend` | hourly | **park** `active` boxes with no activity — snapshot kept, droplet destroyed ([task 1002726](https://example.com/builders#/task/1002726)); reversible via `wake` | `BOX_IDLE_MINUTES` (default 10; **currently 120 live**) |
-| `box-dormant-reclaim` | daily | destroy the snapshot of long-`parked` boxes — the only automated snapshot delete, and it warns first ([task 1002727](https://example.com/builders#/task/1002727)) | `BOX_DORMANT_DAYS` (14) |
-
-> ⚠️ **Both sweeps are currently `enabled: false`** in `config/scheduled-routines.json` — retired with the dev-box module (goal 1000091, [task 1003886](https://example.com/builders#/task/1003886)). Neither fires; the CLI below still works by hand.
-
-## Why a self-built sweep (not Coder)
-
-ADR 0031 §9.3, resolved 2026-06-04: Coder needs an always-on control-plane droplet (~$12–24/mo fixed) + ops; a self-built sweep has ≈ $0 fixed cost and rides the existing sweep/timer pattern. See the ADR for the full rationale. (The original sweep snapshotted-and-parked idle boxes; [task 804](https://example.com/builders#/task/804) briefly simplified the idle path to a direct deprovision, and [task 1002726](https://example.com/builders#/task/1002726) reverted it — so the snapshot/wake machinery serves the automatic idle path again, as well as the manual `park`/`wake` commands.)
-
-## The CLI — `node scripts/gds/box.js`
-
-**Dry-run is the default. Nothing touches DigitalOcean or the DB without `--apply`.** Run any command once without `--apply` to see the plan.
-
-```bash
-node scripts/gds/box.js status                  # roster + cost (read-only)
-node scripts/gds/box.js provision <login|id>    # plan a provision
-node scripts/gds/box.js provision <login|id> --apply
-node scripts/gds/box.js park   <login|id> --apply
-node scripts/gds/box.js wake   <login|id> --apply
-node scripts/gds/box.js deprovision <login|id> --apply
-node scripts/gds/box.js sweep-idle              # plan; add --apply to act
-node scripts/gds/box.js sweep-dormant           # plan; add --apply to act
-node scripts/gds/box.js reconcile-drift         # DO⇄DB drift; add --apply to act
-```
-
-`<builder>` is a GitHub login or a numeric builder id.
-
-### Drift reconcile — `reconcile-drift` (task [#1289](https://example.com/builders#/task/1289), [ADR 0071](../adr/0071-box-confirm-before-destroyed-and-drift-reconcile.md))
-
-The teardown is now **confirm-before-destroyed**: `deprovision` only marks a box `destroyed` AFTER DigitalOcean confirms the droplet is deleted (idempotent + retried). A delete that genuinely fails parks the box at `state='error'` with `droplet_id` preserved and **throws** — it never silently leaves a running droplet behind a `destroyed` row (the old "zombie" bug).
-
-`reconcile-drift` is the backstop. It lists the real fleet droplets (a live read — needs `DO_API_TOKEN`, present in `box.env`) and reconciles against the Bongos rows **both ways**:
-
-- **Zombie** — a droplet no live box row claims → force-delete the droplet + its tunnel/DNS.
-- **Ghost** — a live row whose `droplet_id` vanished from DO → mark it `destroyed`.
-
-A droplet younger than 30 min is never killed (it may be a provision in flight). It runs hourly on the control plane via `box-drift-reconcile.timer` (see *Going live* below). Run it by hand (dry-run first) any time you suspect drift:
-
-```bash
-node scripts/gds/box.js reconcile-drift          # show the plan
-node scripts/gds/box.js reconcile-drift --apply  # repair
-```
-
-### Rank gate (ADR 0016 trust boundary)
-
-`provision` reads the builder's **live DB rank** (the same value `requireRank` reads — uncacheable, server-side) and refuses below `BOX_PROVISION_MIN_RANK`. Default floor is `xenos`: per ADR 0031 §5(b) even an onboarded newcomer gets an org-funded **starter** box. The **scope** differs by rank, not the right to a box:
-
-- **xenos → `scope='starter'`** — the box is tagged for the scoped surface [#600](https://example.com/builders#/task/600) will enforce.
-- **metic / archon → `scope='full'`** — full private-repo access (also [#600](https://example.com/builders#/task/600)).
-
-Raise the floor (e.g. boxes for Metic+ only) by setting `BOX_PROVISION_MIN_RANK=metic`.
-
-## Config (environment)
-
-Put these in `/etc/example/box.env` (chmod 600 — **secrets never go in the repo**, [ADR 0022](../adr/0022-secrets-policy.md)). The systemd units load it via `EnvironmentFile=`.
-
-| Var | Default | Meaning |
-|---|---|---|
-| `DO_API_TOKEN` | — | DigitalOcean API token. **Required for `--apply`**; absent ⇒ live calls throw clearly. |
-| `BOX_PROVISION_MIN_RANK` | `xenos` | provisioning rank floor |
-| `BOX_REGION` | `nyc3` | droplet region |
-| `BOX_SIZE` | `s-2vcpu-4gb` | droplet size (4 GB floor — the devcontainer sets a 4 GB Node heap) |
-| `BOX_BASE_IMAGE` | `ubuntu-24-04-x64` | first-provision base image (cloud-init installs Docker + the devcontainer) |
-| `BOX_IDLE_MINUTES` | `10` | idle-**park** threshold (minutes). **Currently overridden to `120` live** as a soak margin — see "How idle is detected". |
-| `BOX_DORMANT_DAYS` | `14` | dormant-reclaim threshold |
-| `BOX_SSH_KEY_IDS` | — | comma-list of DO SSH key ids/fingerprints to inject (so you can SSH in) |
-| `BOX_REPO_URL` | — | git URL the cloud-init clones into `/workspace`. The scoped **credential** is [#600](https://example.com/builders#/task/600); no identity is hardcoded. |
-| `BOX_DNS_HOOK` | — | optional shell command run on provision/wake with `BOX_HOSTNAME`/`BOX_IP` in env, to repoint the per-builder hostname |
-| `BOX_DNS_ZONE` | `dev.example.com` | the per-builder hostname zone (`box-<login>.<zone>`) |
-| `BOX_TAG` | `otb-builder-box` | DO tag applied to every box droplet |
-
-## Cost (Criterion C1 / cost)
-
-A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to example/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
-
-## Going live (one-time operator steps)
-
-These spend money and are intentionally manual.
-
-> **Hardware-verified end-to-end (2026-06-06, [#720](https://example.com/builders#/task/720)).** The lane now boots a *usable* box: auto-provision by draining the intent queue (`box.js run-intents` / `box-intent-runner.timer`), wake-on-connect from snapshot via `POST /box/ensure`, and SSH connect with the injected key. **`box-intent-runner.timer` is installed + enabled on the control plane as of [#720](https://example.com/builders#/task/720).** That run also found **[#724](https://example.com/builders#/task/724)**: the cloud-init template carried non-ASCII characters (em-dash, §) that cloud-init's strict YAML loader silently rejected — so *every* box before [#724](https://example.com/builders#/task/724) (including the [#699](https://example.com/builders#/task/699) lifecycle test) booted as a bare Ubuntu image with no devcontainer. **Keep `infra/builder-box-cloud-init.yaml` ASCII-only** (scan with `LC_ALL=C grep -nP '[^\x00-\x7f]' infra/builder-box-cloud-init.yaml`) and assert `cloud-init status` is `done` (not `degraded`) on the box after any provision change. Still deferred to **[#725](https://example.com/builders#/task/725)** (needs `BOX_SOURCE_*` GitHub tokens): the rank-gated source-fetch ([#600](https://example.com/builders#/task/600)) leg, full RC pairing, the fresh-account dry-run, plus the `box-source-fetch.sh` `HOME`-unbound fix. The idle/dormant sweeps are now LIVE — wired on the control plane 2026-06-15 ([#1101](https://example.com/builders#/task/1101)); they depend on the box-heartbeat, which needs the source clone (leg 1).
-
-> **Source + DNS verified (2026-06-06, [#725](https://example.com/builders#/task/725)).** **Leg 1 ✅** — `BOX_SOURCE_*` is wired on the **web** tier via `/etc/example/web-source.env` (a systemd drop-in `EnvironmentFile`, deliberately separate from `box.env` so the internet-facing web process never holds `DO_API_TOKEN`); `GET /box/source-access` issues a rank-scoped credential and the box clones into `/workspace` with the credential **scrubbed from `.git/config`**. **[#599](https://example.com/builders#/task/599) hostname cutover ✅ DONE** — in `box.env`: `CLOUDFLARE_API_TOKEN` (Zone:DNS:Edit, IP-locked to the droplet) + `BOX_DNS_HOOK=/home/lars/example/infra/box-dns-cloudflare.sh`; `box.js` runs it on every provision/wake so `box-<login>.dev.example.com` tracks the box IP (verified live: a park→wake gave a new IP and DNS auto-updated with no manual step; SSH via the hostname works). **The hook forces `curl -4`** — the control-plane droplet has IPv6 egress that would otherwise bypass an IPv4 token allow-list. Gotcha: a Cloudflare token IP-locked to the droplet's IPv4 returns "Invalid API Token" from `/user/tokens/verify` (and from any IPv6-sourced call) — test against the real op (`GET /zones`), not the verify endpoint, especially for account-scoped `cfat_`-prefixed tokens. Still partial: leg 5 (RC pairing needs a `claude` login on the box) + leg 6 (fresh-account needs a 2nd GitHub account). **DNS reliability hardened ([#1180](https://example.com/builders#/task/1180), 2026-06-16):** the hook now RETRIES every Cloudflare call with backoff — a transient auth blip during the provision call-burst used to leave the A record pinned at the prior (now-dead) IP while reporting a misleading "zone not found"; it now self-heals and, on a genuine failure, surfaces the real CF error code. `runDnsHook` no longer swallows a hook failure (it records a `box_events` `error` row and flags the box DNS-stale instead of logging a clean "✓ active"). The browser terminal is independent of this record (it rides the outbound tunnel). _(Root cause: @kingaonline's Claude Desktop hit "handshake timeout" SSHing to a hostname pinned at a dead IP.)_ **DNS teardown refined ([idea 309](https://example.com/builders#/idea/309) → task [#1234](https://example.com/builders#/task/1234)):** on deprovision `deprovisionOne` **repoints** the A record to a non-routable blackhole sentinel (`192.0.2.1`, TEST-NET-1 / RFC 5737) via `runDnsHookBlackhole` instead of **deleting** it. 1180 originally deleted the record on teardown so it couldn't dangle at a recycled DO IP — but delete-then-recreate across a reap→rebuild opened a window where the name returned `NXDOMAIN`, which resolvers negative-cache for the zone's SOA neg-TTL (~30 min on the Cloudflare `example.com` zone, not builder-editable); a client that queried mid-gap (e.g. an open Claude Desktop) then kept getting `ENOTFOUND` long after the box was back. A record that always resolves (to a guaranteed-dead sentinel) has nothing to negative-cache, yet still can't dangle at a recycled IP; the next provision/wake `PUT`s it straight to the live IP at the 60s record TTL, no gap. (Lowering the neg-TTL — the other lever floated in idea 309 — isn't used: Cloudflare's per-zone SOA neg-TTL isn't builder/API-editable, and the repoint makes it moot.) The hook's `BOX_DNS_DELETE=1` / `--delete` mode is retained for **manual** operator cleanup.
-
-1. **Token + config.** Create `/etc/example/box.env` (chmod 600) with at least `DO_API_TOKEN` and `BOX_SSH_KEY_IDS`. Apply migration 067 on the prod DB (`bash scripts/migrate.sh`).
-   > **`DO_API_TOKEN` must carry `tag:create` scope.** The first 2026-06-04 hardware run failed with `DO POST /droplets … missing the required permission tag:create` (the CLI applies `BOX_TAG` to every box). Use a **Full-Access** token, or a custom token that includes **tag write** alongside droplet + snapshot read/write.
-   > **Hardware-verified (2026-06-04, [#699](https://example.com/builders#/task/699)):** the full `provision → park → wake → deprovision` cycle has run on real DigitalOcean droplets (`box_events` ledger). Still unverified on hardware: the rank-gated source-fetch ([#600](https://example.com/builders#/task/600)) leg and the live Claude Desktop connect.
-2. **Try one box in dry-run, then live.**
-   ```bash
-   node scripts/gds/box.js provision <login>          # read the plan
-   node scripts/gds/box.js provision <login> --apply  # create it
-   node scripts/gds/box.js status
-   ```
-   SSH in (DO assigns the IP shown), confirm the devcontainer came up, then `park`/`wake` it once to confirm the snapshot round-trips.
-3. **Wire the box-side heartbeat** (so the idle sweep measures activity, not uptime). On the box, schedule `infra/box-heartbeat.sh` every ~5 min — e.g. `*/5 * * * * /workspace/infra/box-heartbeat.sh >> /tmp/box-heartbeat.log 2>&1` (or hang it off [#599](https://example.com/builders#/task/599)'s box service supervisor). Confirm `GET /api/gds/box/me` shows `last_activity_at` advancing while you're connected.
-4. **Wire the sweeps + the onboarding intent runner** (systemd units ship in `infra/`):
-   ```bash
-   sudo cp infra/box-idle-suspend.{service,timer} infra/box-dormant-reclaim.{service,timer} infra/box-intent-runner.{service,timer} infra/box-drift-reconcile.{service,timer} /etc/systemd/system/
-   sudo systemctl daemon-reload
-   sudo systemctl enable --now box-idle-suspend.timer box-dormant-reclaim.timer box-intent-runner.timer box-drift-reconcile.timer
-   systemctl list-timers 'box-*'        # confirm next-run times
-   ```
-   Tail `journalctl -u box-idle-suspend.service` for a day to confirm boxes park + wake cleanly.
-   > **`box-intent-runner.timer` ([#701](https://example.com/builders#/task/701)) is the on-ramp's responsiveness knob.** It runs `box.js run-intents --apply` every minute, draining the `box_intents` queue that `POST /api/gds/box/ensure` writes — so a builder who hits "connect" gets their box **auto-provisioned** (no box yet) or **woken** (parked) within ~1 min, with no operator CLI. It reads the SAME `/etc/example/box.env` as the sweeps. Without it installed, `ensure` still queues intents — they just sit pending until someone runs `box.js run-intents --apply` by hand. Confirm with `journalctl -u box-intent-runner.service` after a test `ensure`.
-   > **`box-drift-reconcile.timer` (task [#1289](https://example.com/builders#/task/1289)/[ADR 0071](../adr/0071-box-confirm-before-destroyed-and-drift-reconcile.md)) is the zombie backstop.** It runs `box.js reconcile-drift --apply` hourly, reading the live DO droplet list and repairing DO⇄DB drift both ways — force-deleting **zombie** droplets (running but no live box row claims them) and marking **ghost** rows destroyed (droplet gone from DO). Reads the SAME `/etc/example/box.env` (needs `DO_API_TOKEN` to enumerate droplets). Without it, the confirm-before-destroyed teardown still prevents *new* zombies, but a pre-existing one (or an out-of-band DO change) only heals on the next manual `reconcile-drift`. Confirm with `journalctl -u box-drift-reconcile.service`.
-   > **Chromebook / browser terminal ([#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/0038-chromebook-ttyd-cloudflare-tunnel.md), superseding the old `claude rc` pairing).** Research proved `claude rc` cannot run headless, so the box instead serves its OWN browser terminal — **ttyd** (127.0.0.1:7681, per-box basic-auth, drops into `/workspace`) exposed over an outbound-only **Cloudflare Tunnel** — where the builder runs normal interactive `claude`. A browser/Chromebook builder gets the URL + credential from `GET /api/gds/box/terminal` after their box is active — no SSH needed. The terminal/cloudflared units are inlined in cloud-init and start at first boot ([#774](https://example.com/builders#/task/774)). The deleted RC bits (`claude-rc.service`, `box-report-pairing.sh`, `/box/pairing(-link)`) are gone.
-
-## Cloudflare token: the edge cookie-strip rule (ADR 0053 / SR#11)
-
-`provision` applies two zone **rulesets** best-effort: the **cookie-strip Transform Rule** (removes the `Cookie` request header on `term-*`/`sandbox-*`, so the apex session cookie never rides the tunnel onto a box — a host outside the trust boundary) and the **sandbox cache-bypass Cache Rule**. Both need scopes beyond Tunnel + DNS, and a token that lacks them fails **silently** — the box provisions fine and the security control simply isn't there.
-
-Since task 1002511, `box.js provision` **read-probes** the ruleset phase before spending a cent (dry-run included) and prints a `⚠⚠ SECURITY` block naming the fix. Read the probe honestly: it is a `GET`, so it can only prove the scope is **missing** (401/403). A readable phase means *readable* — edit scope is not proven until the rule PUT actually runs, which is why the summary line after `✓ named tunnel ready` is the authoritative signal.
-
-**Fix — widen the token** (account owner only):
-
-> CF dashboard → **My Profile → API Tokens** → edit the token used as `CLOUDFLARE_API_TOKEN` → **Permissions** → add **Zone → Transform Rules → Edit** and **Zone → Cache Rules → Edit** → **Zone Resources → Include → Specific zone → `<your apex zone>`** → Continue → Save. Then re-run `node scripts/gds/box.js provision <login> --apply`.
-
-**Fallback — apply the rule by hand** (no token change; do it once per zone):
-
-> CF dashboard → the zone → **Rules → Transform Rules → Modify Request Header** → Create rule. Custom filter expression: `starts_with(http.host, "term-") or starts_with(http.host, "sandbox-")` (the exported `COOKIE_STRIP_EXPRESSION`). Action: **Remove** header `Cookie` (phase `http_request_late_transform`). Deploy. Give it the same description the code uses (`COOKIE_STRIP_RULE_DESC`) so a later widened-token run recognises and replaces it instead of adding a duplicate.
-
-**Verify:**
-
-```bash
-node scripts/gds/box.js provision <login>          # dry-run — prints the probe verdict, spends nothing
-curl -sI https://term-<login>.<apex>/ -H 'Cookie: x=1'   # from a box-facing check, confirm the origin sees no Cookie
-```
-
-> `/user/tokens/verify` is **not** a valid check here — an IP-locked token answers "Invalid API Token" there even when it is valid (see the [#725](https://example.com/builders#/task/725) note above). Always probe the real operation.
-
-## Boundaries (other ADR-0031 tasks)
-
-- **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.
-- **[#599](https://example.com/builders#/task/599)** — Claude Desktop managed-settings + the stable-hostname cutover the lifecycle records. (The browser-on-ramp is now the ttyd web terminal over a Cloudflare Tunnel — [#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/0038-chromebook-ttyd-cloudflare-tunnel.md) — not the retired `claude rc` Remote-Control service.)
-- **[#600](https://example.com/builders#/task/600)** — rank-gated **source access**: the scoped GitHub credential the box holds, granted/revoked by rank. [#598](https://example.com/builders#/task/598) records `scope`; [#600](https://example.com/builders#/task/600) enforces it.
-- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/example system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
-
-## Safety properties
-
-- **No HTTP provisioning — the web process never touches the DO API.** Lifecycle mutations (provision/park/wake/deprovision) run only on the control-plane CLI; `DO_API_TOKEN` lives only in `/etc/example/box.env`, never the web tier. The API surface is read (`GET /box/me`, `GET /boxes`, `GET /box/terminal`) plus own-scoped writes that **record a request, not an action**: `POST /box/heartbeat` and — [#701](https://example.com/builders#/task/701) — `POST /box/ensure`, which only writes a `box_intents` row. The control-plane `box.js run-intents` is what actually calls DO. A stolen builder token can, at most, queue a provision/wake of **its own** box (rank-gated, one open intent max) — it can never create, destroy, or reach another builder's infrastructure.
-- **Dry-run default + token-required-for-live.** You cannot accidentally spend money; a live call without `DO_API_TOKEN` throws rather than silently no-op'ing.
-- **Audited.** Every transition writes a `box_events` row (`provision`/`park`/`wake`/`deprovision`/`cost`/`error`) with the actor (`cli:<login>` / `sweep:idle` / `sweep:dormant`).

package/docs/recipes/devbox-app-release.md

@@ -1,103 +0,0 @@
-# Releasing the Dev Box desktop app
-
-How a new version of the Dev Box app (`devbox-app/`, ADR 0045) reaches builders.
-The chain: CI builds installers → operator publishes them to the PUBLIC
-releases repo → a one-line config bump re-points the branded
-`/downloads/devbox/*` redirects. Nothing binary ever rides the git deploy.
-
-## 0. What's where
-
-- **Source:** `devbox-app/` in the main (private) repo.
-- **CI:** `.github/workflows/build-devbox-app.yml` — builds on every push
-  touching `devbox-app/**` (mac dmg arm64+x64 on macos-14, NSIS exe x64+arm64 on
-  windows-latest). **Only `main` keeps the artifacts** (3-day retention); a
-  `claude/**` run builds both platforms as a CI signal and uploads nothing —
-  ~500MB per run had filled the shared Actions storage cap and blocked uploads
-  repo-wide. No publishing from CI either way.
-- **Public releases repo:** named in `config/devbox-app.json`
-  (`releases_repo`). Assets live on GitHub releases there; GitHub's CDN
-  serves the downloads, $0.
-- **Branded URLs:** `https://example.com/downloads/devbox/<target>`
-  (302 → release asset; targets `mac-arm64`, `mac-x64`, `win-x64`, `win-arm64` + aliases)
-  and `/downloads/devbox/latest.json` (what the app's update check reads).
-  Server side: `src/devbox-downloads.js`, mounted in `server.js`.
-- **Install-window backdrop ([#912](https://example.com/builders#/task/912), fixed in [#1235](https://example.com/builders#/task/1235)):** the backdrop
-  art is `build-resources/dmg-background.png` (+ `@2x`), drawn by
-  `scripts/gen-dmg-backdrop.py`. Committed art — re-run that script + commit if you change
-  the layout/copy. **The DMG is NOT styled by electron-builder.** electron-builder writes a
-  `.DS_Store` whose background reference includes a modern `pBBk` bookmark that Finder on
-  macOS ≥ Sonoma/Sequoia (verified white on 15.7.4) cannot resolve — so its install window
-  renders solid white even though the image is embedded (this is exactly what shipped broken
-  in v1.0.5/v1.0.6; it is NOT a Finder cache and NOT an OS limitation — macOS renders DMG
-  backgrounds fine). Instead, the CI step **"Apply install-window backdrop (dmgbuild)"**
-  (`scripts/apply-dmg-backdrop.sh` + `scripts/dmgbuild-settings.py`) re-packages the
-  signed+notarized `.app` out of electron-builder's DMG into the final DMG with
-  [`dmgbuild`](https://pypi.org/project/dmgbuild/), which writes an alias-only `.DS_Store`
-  (no `pBBk`) that DOES resolve and render. `dmgbuild` is headless (no Finder), so it runs in
-  CI; the `.app` is copied verbatim with `ditto`, so notarization is preserved; the DMG is an
-  unsigned carrier either way. Keep the icon coords + window/iconSize in
-  `scripts/dmgbuild-settings.py` matched to `electron-builder.yml` and the art's wells
-  (180,198 / 480,198, 660×400, size 100). **Verify after a mac release:** mount the published
-  arm64 DMG and confirm the backdrop draws — quick non-Finder check:
-  `hdiutil attach <dmg> -nobrowse -readonly -mountpoint /tmp/m && python3 -c "d=open('/tmp/m/.DS_Store','rb').read(); print('renders:', b'pBBk' not in d and b'.background' in d)"`
-  (`pBBk` must be **absent**).
-
-## 1. Cut a release
-
-1. Bump `devbox-app/package.json` version (e.g. `1.1.0`) and regenerate
-   icons only if they changed (`npm run icons`).
-2. Land the bump on `main` through the normal Bongos flow, then wait for
-   `build-devbox-app` to go green **on the `main` run** — that is the run that
-   carries the installers.
-3. Download the artifacts (they expire after 3 days — re-run the workflow on
-   `main` via `gh workflow run build-devbox-app.yml --ref main` if they aged out):
-   ```
-   gh run download -R example-owner/example -n devbox-app-mac -D /tmp/devbox-rel
-   gh run download -R example-owner/example -n devbox-app-win -D /tmp/devbox-rel
-   ```
-   **These commands only work against a `main` run.** Pointing them at a
-   `claude/**` run fails with nothing to download — the upload steps are gated to
-   `refs/heads/main` (see §0). To get an installer out of an unmerged branch,
-   build it locally instead: `cd modules/dev-box/app && npm run dist:mac` (or
-   `npm run dist:win` on Windows).
-4. Publish to the public releases repo (tag = `v<version>`, must match what
-   `src/devbox-downloads.js` composes):
-   ```
-   gh release create v1.1.0 -R example-owner/example-devbox \
-     --title "Dev Box v1.1.0" --notes "…" /tmp/devbox-rel/*.dmg /tmp/devbox-rel/*.exe
-   ```
-5. Update `config/devbox-app.json`: `version` + the four asset filenames
-   (they embed the version — `tests/devbox_downloads.mjs` fails the gate on a
-   half-bumped config).
-6. Ship the config change through the normal Bongos flow. **Bumping `config/devbox-app.json`
-   `version` is what triggers the in-app update banner in the field ([#924](https://example.com/builders#/task/924))** — running
-   apps poll `GET /downloads/devbox/version`, compare it to their own `package.json`
-   version with a proper semver compare (`devbox-app/src/updater.js`), and show
-   "Update available — v<x>" + a one-click Update button only when the published
-   version is STRICTLY newer. Apps re-check on open and every 12h, so a running app
-   surfaces a new release within ~12h (sooner if reopened). The config version must
-   therefore be ≥ the shipped `package.json` version, or no one is offered the update.
-   The hall `/settings` download card reads the same endpoint to show "Latest version: vX".
-
-## 2. Verify after deploy
-
-```
-curl -sI https://example.com/downloads/devbox/mac-arm64 | grep -i location
-curl -s  https://example.com/downloads/devbox/version     # { version, assets:{target:url} } — the app's update-check payload
-curl -s  https://example.com/downloads/devbox/latest.json # { version, assets:{target:{file,url}} } — the downloads page payload
-curl -sIL https://example.com/downloads/devbox/win-x64 -o /dev/null -w '%{http_code}\n'   # expect 200
-```
-
-## Gotchas
-
-- **The tag and asset filenames must match the config exactly** — the
-  redirect is `releases/download/v<version>/<asset>`; a renamed asset 404s.
-- **Unsigned builds:** until the Apple Developer ID / Windows cert decision
-  (open blocker), keep the "Open Anyway" / SmartScreen copy in the hall
-  onboarding + settings pages accurate. When certs land: sign + notarize in
-  CI, then revisit real auto-update.
-- **`devbox-app/build-resources/`** is committed source (the app icon); the
-  name avoids the root `.gitignore`'s global `build/` rule. Output goes to
-  `devbox-app/dist/` (ignored).
-- **The releases repo is public** — never attach anything but the installers
-  (no env files, no maps, no internal docs).