@bongos/core 1.17.0

package/docs/adr/0028-honest-llm-spend-accounting.md

@@ -0,0 +1,109 @@
+# ADR 0028 — Honest LLM-spend accounting (grader envelope cost + session transcript pricing)
+
+- **Status:** Accepted
+- **Date:** 2026-05-30
+- **Deciders:** spike [#483](https://example.com/builders#/task/483) (design), commissioned by spike [#482](https://example.com/builders#/task/482) audit ([docs/audits/<redacted>.md](../audits/<redacted>.md))
+- **Supersedes the implicit "log cost manually" posture** that left `cost_log`'s `api` category at $0.60 across the whole project.
+
+## Context
+
+The [#482](https://example.com/builders#/task/482) audit established that the dominant real cost of the project — Claude API/token spend — is essentially uncaptured. `cost_log` has one writer (`db.logCost`) reached only by manual `POST /api/gds/cost` and the art-pipeline backfill. Two large, *automatic* sources of spend land nowhere:
+
+1. **The per-ship grader panel** — 4 workers (Narc, Quality, Hacker, Efficiency), each an Opus/Sonnet `claude -p` subprocess, run on every confirm (149+ GDS-V3 ships).
+2. **The interactive builder sessions** — the Opus 4.x 1M-context sessions builders actually work in.
+
+The audit's F4 lesson: a capture that requires a manual step won't happen (17 consecutive $0 days proved it). Capture must be **automatic** and sit at a seam that always executes.
+
+This ADR decides *how* spend is captured for each source. It is the design deliverable of spike [#483](https://example.com/builders#/task/483) and the blocking input for the two implementation tasks ([#486](https://example.com/builders#/task/486) grader; the session-capture task).
+
+## Decision
+
+Capture the two sources at **two different seams**, because their cost data lives in two different places. Do **not** force one mechanism to cover both.
+
+### 1. Grader cost — read it from the subprocess envelope (client-side, exact)
+
+`grader.runSubagent` spawns each worker as `claude -p --print --output-format json` ([src/bongos/grader.js](../../src/bongos/grader.js)). With `--output-format json`, the CLI returns a result envelope that includes **`total_cost_usd`** (and a `usage` block) — *verified* on a real call: `{type, …, total_cost_usd: 0.198, usage, modelUsage}`. The old `extractAssistantResult` parsed only `env.result` and **discarded the cost**.
+
+> **Correction (made during [#486](https://example.com/builders#/task/486) implementation):** the panel does **not** run server-side. `gradeSubagent` is invoked **client-side in `scripts/gds/ship.js`** (and `conductor-dispatch.js`); the server's `/tasks/:id/grade` route only *validates/scores* the result ship.js POSTs. So there is no in-process DB handle at grade time — the cost is logged over HTTP, exactly like the session path. The substance below (exact envelope cost, no pricing table) is unchanged; only the seam moved from `db.logCost` to `POST /api/gds/cost`.
+
+**Decision:** stop discarding it. `runSubagent` now attaches `cost_usd` (from `extractCostUsd(stdout)`); `runWorker` carries it onto each `WorkerResult`; `aggregatePanel`/`aggregateShots` sum it into **`panel_cost_usd`**. After the grade POST succeeds, `ship.js` POSTs one `cost_log` row:
+
+```
+POST /api/gds/cost {
+  task_id,                          // the task being graded
+  amount_usd: panel_cost_usd,       // Σ env.total_cost_usd across workers/shots
+  category: 'api',
+  source: 'grader',
+  source_ref: `grade-${taskId}-${headSha}`,  // idempotent; a new commit = a new row
+  // builder_id defaults to the authed shipper server-side
+}
+```
+
+- **Exact, not estimated** — the CLI computes `total_cost_usd` itself, so no pricing table is needed on this path. This is why the grader path is decoupled from the pricing module below.
+- **Idempotent** — `source='grader'` + `source_ref=grade-<task>-<shortSha>` rides the existing `ON CONFLICT (source, source_ref) DO NOTHING`. A re-ship at the **same** HEAD is a no-op; a re-grade after new commits is a distinct row (a real, countable event per ADR 0027's grade-attempt log).
+- **Best-effort, never blocks the gate** — the POST runs after the grade is already recorded, checks `.ok`, and only logs a line on failure. A cost-logging failure can never fail or roll back a grade, and it runs on **both** pass and fail (the panel costs money either way).
+- **Fallback:** if a future CLI omits `total_cost_usd`, `extractCostUsd` returns null → `panel_cost_usd` is 0 → no row written (graceful degrade). Pricing `env.usage` via the shared module is a possible later fallback; not needed while the envelope carries cost.
+
+### 2. Session cost — price the transcript JSONL (client-side, table-priced)
+
+The interactive session is not a `-p` subprocess, so there is no envelope. But Claude Code writes a per-session transcript at `~/.claude/projects/<encoded-cwd>/<session-id>.jsonl`, and **each assistant turn carries `message.usage`** (`input_tokens`, `output_tokens`, `cache_creation_input_tokens` with a `cache_creation.{ephemeral_5m,ephemeral_1h}` breakdown, `cache_read_input_tokens`) and `message.model`. *(Verified on this machine 2026-05-30: 6/23 lines carried usage; model `claude-opus-4-8`.)*
+
+**Decision:** a client-side script `scripts/gds/session-cost.js` reads a transcript, sums usage per model, prices it via a shared `src/bongos/llm-pricing.js` table, and POSTs one row to `/api/gds/cost` (`category='api'`, `source='session'`, `source_ref=<session-id>`, builder defaults to the authed caller). It runs automatically via a **`SessionEnd` hook** (`.claude/settings.json`).
+
+> **Correction (made during [#560](https://example.com/builders#/task/560) implementation):** the first draft said "wired into the `builder-exit` skill." That was wrong — `builder-exit` is Archon **offboarding** (deactivate a builder), not a per-session seam. The correct seam is the Claude Code **`SessionEnd`** hook, which fires *exactly once* when a session ends and receives `{ session_id, transcript_path, cwd, reason }` on stdin (confirmed against the hooks docs). `Stop` was rejected: it fires at the end of *every* turn (many times per session), so it would need an upsert to avoid undercounting — `SessionEnd` needs none (one POST at end, idempotent `DO NOTHING` on `session_id`). The hook pipes its stdin payload to `session-cost.js`, which is also runnable by hand (`--transcript`/`--session`, or newest-for-cwd) and supports `--dry-run`.
+
+- **Table-priced** — the transcript has tokens, not dollars, so a small auditable `model → $/Mtok` table is required. One file, easy to update when prices change; a `decision`-worthy change gets its own task.
+- **Idempotent on session-id** — re-running on the same transcript is a no-op (`ON CONFLICT`). A long session re-run after more turns would need a re-priced delta; v1 keeps it simple: one row per session, written once at exit. (A periodic delta-capture is a later refinement; see Consequences.)
+- **`task_id` is null** — a session is not 1:1 with a task (it may span several or none). Session spend is attributed to the **builder**, not a task. Grader spend (path 1) is the task-attributed path. Together they give per-builder totals; only the grader path gives per-task.
+- **Pricing model (per Mtok), v1 table** (Anthropic public list, editable):
+  | family | input | output | cache-write 5m (1.25×) | cache-write 1h (2×) | cache-read (0.1×) |
+  |---|---|---|---|---|---|
+  | opus | $15 | $75 | $18.75 | $30 | $1.50 |
+  | sonnet | $3 | $15 | $3.75 | $6 | $0.30 |
+  | haiku | $0.80 | $4 | $1.00 | $1.60 | $0.08 |
+
+  Family is matched by substring on `message.model` (`opus`/`sonnet`/`haiku`), mirroring `grader.js`'s existing family-token convention. Unknown model → priced at the opus rate (conservative over-estimate) **and** a warning, so an unpriced model is loud, not silently $0.
+
+### 3. Shared pricing module
+
+`src/bongos/llm-pricing.js` exports `priceUsage(model, usage) → usd` and the `PRICES` table. Owned by the session-capture task; imported by the session script and available to the grader as its envelope-absent fallback. Pure, unit-tested, no I/O.
+
+## Source/category conventions (so the audit can reason about completeness)
+
+| source | category | written by | builder_id | task_id |
+|---|---|---|---|---|
+| `grader` | `api` | `ship.js` → `POST /api/gds/cost` (path 1) | shipper | the graded task |
+| `session` | `api` | `POST /api/gds/cost` (path 2) | authed builder | null |
+| `art-cost-ledger` | `art`/`api` | backfill import | null (shared) | null |
+| `manual` | any | `/builder-cost` | authed builder | optional |
+
+`auditCostAttribution`'s completeness check (the [#485](https://example.com/builders#/task/485) task) keys off these: real `category='api'` spend from `source IN ('grader','session')` should be non-trivial relative to ship volume; if it's ~$0, that is the F1 finding re-detected.
+
+## Capture boundary & non-double-counting ([#562](https://example.com/builders#/task/562), [#563](https://example.com/builders#/task/563))
+
+What the paths read is **disjoint** — confirmed by inspecting the on-disk transcripts:
+
+- **Path 2 (session)** prices the interactive session's transcript — the file the `SessionEnd` hook passes via `transcript_path` (only the interactive model's own turns: verified all `claude-opus-4-8`, **0 sidechain**).
+- **Path 1 (grader)** takes its number from each worker's `claude -p` result **envelope** (`total_cost_usd`) — never from a transcript.
+- **Path 3 (subagents, [#563](https://example.com/builders#/task/563))** prices this session's ad-hoc `Agent`/`Task` subagents, which persist at `<project-dir>/<session-id>/subagents/...` (a sibling subtree of the main transcript FILE), **skipping any grader-signature transcript** so the envelope-captured grader (path 1) is never re-priced.
+- The grader workers DO persist their own transcripts (separate `claude-sonnet-4-6` files), but no path prices a grader transcript. So there is **no double count**.
+
+> **INVARIANT (do not violate):** a grader `claude -p` transcript MUST NOT be priced by the session or subagent paths — its cost is already captured via the envelope (path 1). The grader CAN nest inside a `subagents/` dir (an autonomous-builder subagent that ran a ship), so exclusion is by the **grader-worker signature**, not by location. Both the session fallback and the subagent walk (`priceSubagents`) enforce this; the `SessionEnd` hook is also safe by construction. Any future "price all transcripts" idea must apply the same signature skip.
+
+**Subagent capture ([#563](https://example.com/builders#/task/563)) — closed.** `Agent`/`Task`-tool subagents (e.g. a `claude-code-guide` lookup, an autonomous builder) write to `<session-id>/subagents/agent-*.jsonl`; `session-cost.js` now walks that subtree, prices each non-grader transcript via the same model table, and folds it into the one `source='session'` row (the description breaks out `main` vs `N subagent(s)`). Measured impact on a real session: the two ad-hoc subagents added **$5.45** that previously leaked. With this, the `honest-spend-accounting` criterion (proposal-146) is met for **main session + grader + ad-hoc subagents**. (Residual edge: a subagent killed before its transcript flushes, or one nested under a session that itself never fires `SessionEnd`, is still uncaptured — small, noted, not chased.)
+
+## Consequences
+
+- **Positive:** the `api` category stops being a rounding error; per-builder spend renders real numbers; the grader's own cost becomes visible (and gradeable for efficiency); the audit can detect *missing* spend, not just mis-attribution.
+- **Cost:** a small pricing table to maintain (prices drift), and session-capture only fires if the `SessionEnd` hook runs (a session killed before clean exit is uncaptured). The grader path has neither weakness — it's exact and always runs on the ship path.
+- **Deliberately deferred (later refinements, not blockers):**
+  - **Conductor-dispatch grader spend.** `conductor-dispatch.js` also invokes `gradeSubagent` (mid-flight, advisory — no gate, no credits). Its workers now carry `cost_usd` (free, via the shared `runSubagent` change), but only `ship.js` aggregates+logs it. The dispatch path is lower-volume and not on the credit-bearing ship path, so capturing it is a fast-follow, not a [#486](https://example.com/builders#/task/486) blocker (panel-flagged nit on the [#486](https://example.com/builders#/task/486) re-grade; filed to idea_inbox).
+  - Mid-session delta capture (today: one row at exit). A crashed session that never hits `builder-exit` is uncaptured; the Stop hook narrows this.
+  - Cost calibration medians à la migration 015 (idea_inbox [#132](https://example.com/builders#/idea/132)) — needs this real data first.
+  - Reconciling against the true Anthropic billing API — out of scope; the transcript + envelope are the cheapest honest proxy.
+
+## Implementation tasks
+
+- **[#486](https://example.com/builders#/task/486)** — grader envelope cost → `cost_log` (path 1). Decoupled (no pricing dep).
+- **[#560](https://example.com/builders#/task/560)** — `llm-pricing.js` + `session-cost.js` + `SessionEnd`-hook wiring (path 2 + module 3). *(Task title says "builder-exit wiring" — superseded by the SessionEnd seam; see the path-2 correction above.)*
+- **[#485](https://example.com/builders#/task/485)** — `auditCostAttribution` completeness check keyed off the source conventions above.

package/docs/adr/0029-status-page-outage-resilience.md

@@ -0,0 +1,59 @@
+# 0029 — Status-page outage resilience: measure from outside, host off-box, prevent at the source
+
+- **Status:** Accepted. **Slice 1 (external prober) built this session** under task **[#565](https://example.com/builders#/task/565)**: `.github/workflows/status-probe.yml` + `scripts/status-probe.mjs` + this ADR. **Follow-up B (page off-box) has since SHIPPED** — `status.example.com` is served off the droplet from GitHub Pages (repo `example-owner/example-status`), synced by `.github/workflows/sync-status-mirror.yml`. Incident-backfill (follow-up C) is **not yet built**.
+- **Date:** 2026-06-03
+- **Deciders:** Lars Kristensen (Archon), Claude
+- **Track:** `internal` (the status dashboard / The Watch)
+- **Context tasks:** **[#565](https://example.com/builders#/task/565)** (slice 1 — external prober + alert + this ADR) · **blocker [#6](https://example.com/builders#/blocker/6)** (DigitalOcean backup payment + billing alerts — root-cause prevention, Lars-only) · follow-up **B** (move `public-status/` off-box + CORS on `/api/gds/public/*` + repoint `status.` DNS) · follow-up **C** (backfill the 2026-06-03 incident into the honest uptime history).
+- **Relates to:** [ADR 0003 — Cloudflare Origin Cert](<redacted>.md) (the CF↔origin leg) · the in-process poller [`src/bongos/uptime-poller.js`](../../src/bongos/uptime-poller.js) (now demoted from public source-of-truth) · [`docs/recipes/ops-gotchas.md`](../recipes/ops-gotchas.md) (the new "status page shared fate" gotcha).
+
+## Context
+
+On **2026-06-03, ~10:00–14:39 UTC (~4h 39m)**, DigitalOcean **powered off the production droplet after a payment-method charge failed**. The game *and* the status page went dark together, and Lars discovered it by eye — via a Cloudflare 522 — with no alert.
+
+Three independent design flaws turned a billing hiccup into a silent, invisible outage:
+
+1. **The status page shares fate with the product.** `status.example.com` is served by the **same Node process on the same droplet** as the game. Whatever kills the product kills the status page. A status page's entire job is to be up when the product is down.
+2. **It measures itself from inside itself.** [`src/bongos/uptime-poller.js`](../../src/bongos/uptime-poller.js) runs *in that Node process* and probes `http://127.0.0.1`. When the droplet died, the poller died — so it wrote **zero rows** during the outage (not "down" rows — *none*). The Watch renders that gap as 100% green. **A monitor that lives inside the thing it monitors can never witness its own death.** It also can't see Cloudflare, DNS, or "is the box reachable from the world" — only "can the server talk to itself."
+3. **Nothing alerted a human.** Detection depended on someone noticing.
+
+The cardinal industry rule (GitHub → `githubstatus.com` on Atlassian's infra; status accounts on a separate platform as a backup channel) is: **a status page must not share fate with the system it reports on, and availability must be measured from outside it.**
+
+## Decision
+
+Keep The Watch's custom design (Lars's call), but fix all three flaws as three independent layers:
+
+### 1. Measure from outside (built this session — slice 1, [#565](https://example.com/builders#/task/565))
+An **external prober runs on GitHub-hosted runners** — off our DigitalOcean infrastructure — and probes the **public** URL exactly as a visitor would:
+- [`scripts/status-probe.mjs`](../../scripts/status-probe.mjs) — dependency-free Node; probes `https://example.com/healthz` with in-run confirmation retries (UP if any of 3 attempts is a 200; DOWN only if all fail, which suppresses transient blips). Appends to `history.jsonl`, rewrites `status.json` (snapshot + 24h/7d/90d uptime), prunes to 90 days.
+- [`.github/workflows/status-probe.yml`](../../.github/workflows/status-probe.yml) — `*/5` cron + `workflow_dispatch`; publishes the result to an **orphan `status-data` branch** (off-box, web-readable, survives a droplet outage); **fails the job when the site is confirmed down**, which emails the repo owner — the alert.
+
+### 2. Host the page off-box (follow-up B — SHIPPED)
+`status.example.com` is now served off the droplet from **GitHub Pages** (repo `example-owner/example-status`), synced by [`.github/workflows/sync-status-mirror.yml`](../../.github/workflows/sync-status-mirror.yml); the page no longer shares fate with the product. Original plan, for the record:
+Move `public-status/` to free static hosting **separate from the droplet** (Cloudflare Pages or GitHub Pages). The page shell + the **uptime/incident section** are served off-box and read the `status-data` source, so they stay truthful during an outage. The rich GDS panels (treasury, grades, progress) keep loading client-side from `example.com/api/gds/public/*` and **degrade gracefully** to "origin unreachable" when the droplet is down (requires adding CORS to those public routes). Then repoint `status.example.com` DNS at the off-box host.
+
+### 3. Prevent at the source + alert (blocker [#6](https://example.com/builders#/blocker/6))
+The actual root cause was billing. Add a **backup payment method + billing/balance alerts** on DigitalOcean (Lars-only — DO account access). Preventing the outage beats reporting it. The slice-1 prober is the detection net if prevention ever fails.
+
+## Why this mechanism (and the trade-offs)
+
+- **Free and already-owned.** The repo is on GitHub (`example-owner/example`); GitHub Actions + a git branch cost $0 and run off our droplet. Prior art: the open-source **Upptime** project is exactly this pattern (Actions probe → commit to git → issues on downtime → Pages status site); we build a minimal, theme-preserving version instead of adopting its UI.
+- **Trade-offs, accepted for a bootstrapped project:**
+  - GitHub cron granularity is **5 min** and runs can be delayed under load → detection latency is minutes, not seconds.
+  - Scheduled workflows fire **only from the default branch**, so the monitor is live only once [#565](https://example.com/builders#/task/565) merges to `main`; use the "Run workflow" button until then.
+  - GitHub disables schedules after **60 days of repo inactivity** (not a concern at our daily-commit cadence).
+  - The alert is a **failed-run email** to the repo owner; richer alerting (auto-opened issue, Google-Chat webhook reusing `scripts/chat/`, or Better Stack SMS/phone) is a documented upgrade path.
+
+## Alternatives considered
+
+- **Hosted status SaaS (Better Stack / UptimeRobot / Atlassian Statuspage).** The most common professional answer; $0 on free tiers; sub-minute checks + real SMS/phone alerting + their own hosted page. **Rejected as the primary** because Lars wants to keep the custom Greek "The Watch" design and full ownership. Retained as the **upgrade path** if we later want faster checks or phone alerts — it composes with this design (it can be the prober feeding our off-box page).
+- **Keep self-measurement but render gaps as "unknown" (grey) instead of green.** Makes the page honest but still dies with the product and still can't alert. Insufficient on its own.
+- **A second always-on box to host the status page.** Defeats the cost posture ($5k/yr budget) and just moves the shared-fate problem.
+
+## Consequences
+
+- [`src/bongos/uptime-poller.js`](../../src/bongos/uptime-poller.js) is **no longer the public source of truth** for availability. It stays useful as an *internal* component-liveness signal (can the process reach its own DB?), but The Watch's availability section will read the off-box `status-data` (follow-up B). Whether to retire the in-process poller entirely is decided in B.
+- Honest uptime history starts accumulating off-box from the first prober run.
+- The 2026-06-03 incident is backfilled into the record (follow-up C) so The Watch stops claiming 100%.
+- The lesson — "a status page must not share fate with the product, and cannot measure itself" — is captured as **GDS learning `#35`** and a new "Status page + monitoring" section in [`docs/recipes/ops-gotchas.md`](../recipes/ops-gotchas.md) (incl. the 522 / total-outage diagnostic runbook).
+- Because it's off-box, `status.example.com` doubles as the fallback when the hall (`example.com/builders`, CLAUDE.md's canonical doc-reading surface — [#758](https://example.com/builders#/task/758)) is unreachable — it won't render full docs, but it stays up to show whether the droplet itself is down.

package/docs/adr/0030-builders-hall-live-updates.md

@@ -0,0 +1,59 @@
+# ADR 0030 — Builders-hall live updates via Postgres NOTIFY → WebSocket
+
+- **Status:** Accepted — **transport superseded by [ADR 0069](<redacted>.md)** (the hall now delivers nudges over SSE, not a Colyseus WebSocket room, so it works on a game-less Cloud Bongos boot; R55). The **change-signal layer below (§1 — `NOTIFY` + `src/bongos/live-channel.js`) is unchanged and still authoritative**; only the §2 delivery transport moved.
+- **Date:** 2026-06-03
+- **Deciders:** task [#569](https://example.com/builders#/task/569) (commissioned by Lars — "these checks aren't very live, need to refresh every time"); transport chosen by Lars (WebSocket)
+- **Track:** `internal` (the builders hall)
+
+## Context
+
+The builders hall (`public-builders/`) fetched **every panel exactly once** at `DOMContentLoaded` via `loadAll()` and then never refreshed. Onboarding checklist, standing (drachmae/karma), claimable works, leaderboard, karma feed, bounty table — all frozen until the visitor manually reloaded. The only things that updated without a reload were the two buttons a builder clicks themselves (mark primer read, pick a craft).
+
+The reported symptom: a builder runs `/builder-ship` in the terminal, the "Ship thy first work" onboarding step clears server-side, but the open hall tab keeps showing the stale checklist. The underlying gap is broader than onboarding — the page had **no live-update mechanism at all**.
+
+A large share of the staleness comes from changes the *browser's own actions never caused*: background routines (autonomous builders, the BFG), another builder climbing the leaderboard, and **direct `psql` writes** (which the methodology explicitly treats as first-class work). Any fix that only re-broadcasts from API route handlers would miss all of those.
+
+## Decision
+
+A live-push channel in two layers — a transport-agnostic change-signal, and a WebSocket delivery path.
+
+### 1. Change signal — Postgres `NOTIFY` from statement-level triggers (migration 066)
+
+A single generic trigger function `gds_notify_live()` fires `pg_notify('gds_live', '{"table":…,"op":…}')`. One `AFTER INSERT OR UPDATE OR DELETE … FOR EACH STATEMENT` trigger is attached to each table that backs a live panel: `tasks`, `claims`, `builders`, `builder_onboarding_state`, `credit_log`, `karma_log`.
+
+- **Trigger lives in the DB, below the application** → it catches *every* write path, including direct `psql`. This is the decisive property; it's why the signal is a DB trigger and not an app-layer emit.
+- **Statement-level, not row-level** → the payload carries no row data (only table + op), so we don't need `OLD`/`NEW`, and a bulk write coalesces to one nudge instead of N. Negligible overhead on these low-volume internal tables.
+
+The GDS process holds **one persistent `LISTEN` connection** (`src/bongos/live-channel.js`, a dedicated `pg.Client` — *not* a pooled checkout, since `LISTEN` must stay pinned to one connection) and fans each notification out to subscribers. It opens lazily on the first subscriber and closes when the last leaves.
+
+### 2. Transport — a Colyseus WebSocket room, not SSE or a new HTTP route
+
+Delivery to the browser rides the game's **existing Colyseus WebSocket server**. A broadcast-only room `builders_hall` (`src/rooms/BuildersHallRoom.js`, a sibling of `QueueRoom` with no state schema) subscribes to the `live-channel` relay in `onCreate` and `broadcast('nudge', {})` on each notification — an **opaque "something changed" signal**, not the `{table, op}` (see the security note below). The hall page joins via `client.joinOrCreate('builders_hall')` and, on each `nudge`, re-runs `loadAll()` **debounced (~700 ms)** so a burst coalesces into one refresh. The room is `autoDispose: true` — created on the first viewer, disposed (and the `LISTEN` connection dropped) when the last one leaves.
+
+**Why WebSocket / Colyseus** (the chosen option):
+
+- It **reuses infrastructure that already exists and is proven through the Caddy → Cloudflare proxy** — the game has run Colyseus WS in production since V1, so there's no new transport to validate against the edge. The hall is same-origin (`example.com`), so `wss://example.com` and the vendored `/vendor/colyseus.js` client are both already reachable.
+- A `Room` is a natural fan-out primitive: `broadcast()` to all members is one call, and Colyseus owns the connection lifecycle.
+- It keeps the hall's live path on the **same stack as the rest of the realtime system**, rather than introducing a second long-lived-connection style (SSE) alongside it.
+
+**No row data crosses this channel** — and, after the hacker dispatch on [#569](https://example.com/builders#/task/569), not even the `{table, op}`: the relay passes `{table, op}` to the room internally, but the room broadcasts only an empty `{}` so an unauthenticated client can't read internal table names. The hall ignores the payload regardless (it refreshes on any nudge), so this costs nothing. The room is therefore left **unauthenticated**, matching the game rooms (`world`/`queue`); access control stays where the data actually is, on the authenticated per-panel endpoints the hall re-fetches. The only residual signal is *that* a write happened (a timing oracle) — no more than the public status dashboard already exposes.
+
+### Resilience & client guards
+
+- **Reconnect:** unlike `EventSource`, a Colyseus room doesn't auto-reconnect — so the client retries `joinOrCreate` on `onLeave`/error with a fixed 4 s backoff, and refreshes once on reconnect (it may have missed a nudge while offline).
+- **No mid-interaction clobber:** the debounced refresh is deferred (and re-armed) while a user is focused on an input/textarea/select or the tab is hidden, so a nudge can't overwrite unsent input or re-render mid-interaction.
+- **Backstop:** the hall also refreshes on tab `visibilitychange` (regaining focus), and re-opens a dropped room then — covering anything missed while the laptop slept.
+
+## Alternatives considered
+
+- **Server-Sent Events (`GET /api/gds/live`)** — initially built. SSE is arguably the textbook fit for a *receive-only* dashboard (no client lib, native auto-reconnect, plain HTTP GET). Rejected in favor of WebSocket to **reuse the game's existing, proxy-proven WS stack** rather than stand up and maintain a second long-lived-connection mechanism. The change-signal layer (NOTIFY + `live-channel.js`) is identical either way, so this was purely a delivery-path choice.
+- **Per-table → per-panel routing** — mapping each changed table to a subset of panels instead of a full `loadAll()`. Rejected as fragile: a single task ship touches ~6 panels at once, so the mapping is large and easy to get wrong. A full reload is strictly correct (never misses a derived panel) and cheap (cached GETs, only when something actually changed).
+- **Naive client polling** (`setInterval`) — simplest, but either wasteful (polls when nothing changed) or laggy (long interval), and still wouldn't feel live. The push model costs nothing when idle.
+
+## Consequences
+
+- The hall now feels live: finishing a step in the terminal reflects in the open tab within ~1 s, no manual reload.
+- New realtime surface: a `builders_hall` Colyseus room + a persistent Postgres `LISTEN` connection (lazy — zero cost when the hall is empty). The hall page now loads `/vendor/colyseus.js`.
+- **Deliberate omission:** `peer_votes` (the acclaim feed, which spans all builders and loads fire-and-forget) is *not* triggered — it's the least time-sensitive panel, and keeping it out avoids hall-wide refreshes on every cross-builder vote. Easy to add later.
+- Not applied to the public status dashboard (`status.example.com`) — out of scope; that surface already has its own polling cadence.
+- The unauthenticated room is acceptable only because the payload is non-sensitive `{table, op}`. If a future change ever puts row data on this channel, it must gain an `onAuth` cookie/session gate first.

package/docs/adr/0031-cloud-dev-environments-for-builders.md

@@ -0,0 +1,222 @@
+# ADR 0031 — Cloud dev environments for builders (hybrid: Claude Desktop → SSH → containerized DigitalOcean box)
+
+**Date:** 2026-06-04
+**Context:** GDS-V3, task [#595](https://example.com/builders#/task/595) (claim `#477`). Feeds done-when criteria **C1** (`onboarding ≤ 2h`) and **C8** (`cloneable repo / local-first memory, server-canonical on ship`). Companion to [ADR 0016](<redacted>.md) (trust boundary — same server-enforced posture), [ADR 0018](<redacted>.md) (Xenos → Metic → Archon), [ADR 0022](0022-secrets-policy.md) (no secrets in repo — precondition for a cloneable box), [ADR 0024](<redacted>.md) (memory follows the builder — unchanged by where the box runs), and [ADR 0002](<redacted>.md) (we already run on DigitalOcean).
+**Status:** Accepted. *Decision recorded this session; implementation tasks to be seeded separately (see the Implementation sub-tasks at the end).*
+**Track:** `internal` (dev-system architecture).
+
+> This is a decision record, not an implementation. Nothing here is built yet. The point is to lock the shape so a future session can build it without relitigating the design.
+
+## Problem
+
+Today there is exactly one builder (`example-owner`) on one laptop. GDS-V3 opens the system to many builders, and "every builder runs Claude Code locally" has two problems we want to solve *before* we onboard people:
+
+1. **Accessibility.** Local-only requires each builder to own a capable computer (RAM, disk, CPU) *and* hand-install a toolchain (Homebrew, Node 22, Python 3.10, a native `sharp` build, env vars). That toolchain step is the single biggest onboarding failure today, and it's exactly the kind of thing the non-engineer audience we want to attract cannot debug. It directly blocks the C1 "onboard in ≤2h" goal.
+2. **Cost at scale.** Builders will eventually be **paid real money per task**, and the project runs on a ~$5,000/yr budget. We want builders to bear and optimize their own tooling cost (so the incentive to be efficient sits with them), without the org taking on a fixed per-builder cost that grows linearly and untenably with headcount.
+
+The decisive reframe (established during scoping): **two very different costs get bundled as "the cost of running Claude," and they differ by 10–100×.**
+
+- **Inference** — what the AI model costs to *think* (Claude tokens). **$400–1,200+/mo** for a heavy builder. This is the dominant cost, and it is already remote (Anthropic's servers).
+- **Compute / "the box"** — the machine that holds the repo and runs the dev server + art pipeline. **~$3–30/mo.** This is what "local vs cloud" is actually about. It is the *small* cost.
+
+So the cost lever that matters is **inference, not the box.** The box can be a near-trivial, bounded line item. This single fact shapes every choice below.
+
+## The mental model (preserve this for onboarding)
+
+> This explainer is the canonical "how you'll run Claude" framing. It now lives in the onboarding primer — see [`docs/onboarding/primer.md`](../onboarding/primer.md) § "Where your work runs — screen, worker, brain" — so new builders meet it on day one. It was carried there during the ADR 0035 primer rewrite ([#718](https://example.com/builders#/task/718)); keep the two in sync if you revise the model (task 601).
+
+Claude Code is **three pieces that can live in different places**:
+
+1. **The screen** (the interface) — the window you look at and type into. **Always on your device** (the Claude Desktop app, or a browser tab). It just displays files/diffs and sends prompts.
+2. **The worker** (the agent) — the part that opens files, runs commands, edits code, runs the dev server. Runs in **one place you choose.**
+3. **The brain** (the AI model) — the intelligence. **Always on Anthropic's servers**, no matter what. This is the "inference" the subscription pays for.
+
+You only ever choose **where the worker goes**. The screen is always local; the brain is always Anthropic's.
+
+```
+   YOUR DEVICE                  THE BOX (worker)                ANTHROPIC
+   ┌───────────┐   SSH /        ┌────────────────────┐          ┌──────────┐
+   │  screen   │── Remote ─────▶│ containerized DO box│──tokens─▶│  brain   │
+   │ (Desktop/ │   Control      │ repo · dev server · │◀─────────│ (model)  │
+   │  browser) │◀──────────────▶│ art pipeline · git  │          └──────────┘
+   └───────────┘                └─────────┬───────────┘
+                                          │ HTTPS (GDS API) · git push (GitHub)
+                                          ▼
+                                 GDS Postgres · GitHub (private repo) · CI deploy
+```
+
+In our model the device is a **window**, the **box** is where the code lives and the work happens, and **Anthropic's servers** are the brain. The repo never lands on the builder's personal disk.
+
+## Decision
+
+We will adopt a **hybrid** model with a single shared foundation. In plain terms: **a clean Claude Desktop GUI on the builder's own device, driving Claude Code on an org-controlled, containerized DigitalOcean box, with the builder bringing their own Claude subscription.**
+
+### 1. UI — Claude Desktop is the primary interface
+
+> **Superseded in part (2026-06-06, [ADR 0038](<redacted>.md)):** the thin-device `claude rc` always-on-service on-ramp described in the Thin-device bullet below is retired. Headless `claude rc` can't bootstrap (Trusted-Devices enrollment is interactive-only); the browser-only on-ramp is now a box-served `ttyd` web terminal over an outbound Cloudflare Tunnel where the builder runs normal interactive `claude`. See [ADR 0038](<redacted>.md) (and [ADR 0040](<redacted>.md) for in-session Remote Control as the default browser experience). The Desktop→SSH and Local paths below are unchanged.
+
+Most builders want a clean GUI, not a terminal or an IDE. The redesigned Claude Desktop app (April 2026) has a **Code** tab whose session **Environment** selector offers three mutually-exclusive choices for *where the worker runs*: **Local**, **Remote** (Anthropic-managed cloud VM), and **SSH** (a machine the org controls). We build on **SSH**.
+
+- **Desktop builders (Mac/Windows): Claude Desktop → SSH → our box.** Point-and-click; Desktop auto-installs Claude Code on the remote on first connect. We pre-distribute and lock the connection via Desktop **managed settings** (`sshConfigs` + `sshHostAllowlist`) so a non-technical builder sees exactly one approved box ("Example Dev Box") and cannot misconfigure or wander off it.
+- **Thin-device builders (Chromebook/iPad/phone): browser/mobile → Remote Control → the same box.** On the web (`claude.ai/code`) the "your own box" path is **Remote Control**: `claude rc` runs on the box (as an always-on service) and the builder drives it from the browser. Same destination as SSH, different on-ramp. *Caveat: Claude Desktop is macOS/Windows-only — a literal Chromebook uses the web/Remote-Control path, not the Desktop app.*
+- **Power users:** Claude Desktop **Local** (native toolchain on a capable machine) or the VS Code dev-container flow remain available off the same container spec (§3). Not the default.
+
+### 2. Execution substrate — an org-controlled, containerized DigitalOcean box, one per builder
+
+The worker runs on a **DigitalOcean droplet (or a container on a DO host) that the org controls**, reached over SSH/Remote-Control. **One box per builder** (a shared box collides on files, ports, the DB connection, and breaks per-builder isolation). DigitalOcean over GitHub Codespaces — see §7 and Alternatives.
+
+### 3. The container — the box is defined as code
+
+The box is defined by a **`devcontainer.json` + Dockerfile** committed to the repo: base Linux + Node 22 + Python 3.10 and the five art-pipeline libs + `sharp` build deps + git + Anthropic's Claude Code container feature (which installs Claude Code and a **default-deny outbound firewall** allow-listing only the Anthropic API, GitHub, and npm). Today's `setup-builder.sh` work folds into the container's first-run step; `doctor.js` becomes its health check. There is **no containerization in the repo today** — this is greenfield. The same spec runs identically on a DO box, on a laptop (Docker Desktop), or in Codespaces — so the substrate stays portable and we are not locked to DO.
+
+### 4. Inference — bring-your-own Claude subscription, no API key
+
+Every builder authenticates Claude Code with **their own Pro/Max subscription**. The org provisions **no shared Anthropic API key.** This is both the cheapest path (a flat subscription is 15–30× cheaper than per-token API for heavy users) and the cleanest contributor model (the 1099 "bring your own tools" arrangement). It also means the org's inference cost is **$0**.
+
+- **Interactive sessions** (Desktop-SSH or web-Remote-Control) are "ordinary use of Claude Code" under Anthropic's terms — subscription auth is permitted, and the consumer GUI/Remote-Control paths do **not** accept API keys anyway.
+- **Autonomous runs** (`overnight-builder`, MAS dispatch) are launched **as scheduled Claude Code sessions under a subscription**, which the decider judges to be ordinary Claude Code use, not the prohibited Agent-SDK/`--bare`/shared-key path. *Residual risk (recorded, accepted): unattended subscription sessions could trip Anthropic's abuse heuristics, and a 15 Jun 2026 change alters how subscription-based automation draws credits. Re-verify before scaling the autonomous lane; this is the one place an API key might later become unavoidable.*
+
+### 5. Cost & access model — org fronts an auto-suspended starter box; builders self-fund from earnings
+
+Two rules dissolve the "front every box (linear cost) vs. gate by payment (barrier)" dilemma:
+
+**(a) Auto-suspend is mandatory.** A box that runs only while the builder is working costs **~$3–6/mo** instead of ~$24–30/mo always-on. DigitalOcean has no native auto-suspend, so we **build it** (snapshot-and-park on idle, recreate on demand, or a Coder layer — see Open questions below). Dormant/abandoned boxes get de-provisioned (a stale-claim-style sweep).
+
+**(b) Cost follows proven value, not signup** — riding the existing rank ladder + onboarding funnel:
+
+| Stage | How they work | Org cost | Builder cost |
+|---|---|---|---|
+| **Newcomer** (Xenos / onboarding) | Org provisions an **auto-suspended starter box** so there is zero payment barrier to begin | A bounded ~$5/active-newcomer (suspends when idle; de-provisioned if dormant) | Just their Claude subscription |
+| **Proven** (graduated → Metic) | Keeps a box | Transitions toward $0 | **Self-funds** (own DO account, or org provisions + rebills via the `costs` table, deducted from drachmae/earnings) |
+| **Established** | Own box, runs it how they like | **$0** | Self-funds (1099 own-tools) |
+
+The barrier to *start* is zero (org pays the first box, per the decision to **not** use Anthropic's Cloud VM for onboarding). Real cost attaches only to builders who are earning. **Scale math:** naïve 100 builders × $30 always-on ≈ $36k/yr (untenable); this model ≈ $0 ongoing + a small bounded starter-box pool. None of it needs new machinery — it rides the rank ladder, the onboarding funnel, the drachmae/credits system, and the cost-logging we already have.
+
+### 6. Security — the container is the rank-gated source-access boundary
+
+The repo is **private** (today under a personal account — see §7; a move to a GitHub Organization would change the enforcement options below). Putting the worker on a box we control, reached only through the GUI, turns repo access from *"every builder holds a permanent local clone forever"* into *"access is to a box we own — gated, revocable, audited, egress-restricted."*
+
+- **Gate source access by rank.** Below a chosen rank: no box, no source. The box (not the builder) holds the scoped GitHub credential; below-rank builders have no direct clone rights. Extends the [ADR 0016](<redacted>.md) trust boundary from "writes are gated" to "source access is gated."
+- **No permanent local copy** (the code lives on the box; SSH/Remote-Control bypass any local folder).
+- **Central revocation + clean offboarding** (revoke rank → de-provision box → source access gone).
+- **Prod deploy moves to CI** (GitHub Actions, like staging already is), so **no builder box ever holds the production droplet SSH key.**
+- **Honest limit (recorded):** an authorized, logged-in builder can still read/copy code they have a session on. This is defense-in-depth, revocation, and audit — **not** insider-proof DRM.
+
+### 7. Substrate — DigitalOcean, not Codespaces
+
+**DigitalOcean** is the org substrate because it fits the decisions above:
+
+- **Clean fit for Claude Desktop SSH** (a real IP/port/key) and for an always-on `claude rc` service; Codespaces' SSH is a `gh` CLI tunnel (no stable host) and its 30-min auto-suspend kills `claude rc`.
+- **Full host control** → we are root, the builder is a guest, so the firewall/lockdown/idle policy are *enforceable*. On a **personal** repo, Codespaces gives the collaborator root of their own box and the org **cannot enforce** environment/network/idle policy (those are <redacted> features).
+- **Org can fund the first box.** On a personal repo, GitHub bills the Codespace *creator* and a personal account has **no mechanism to pay on a collaborator's behalf** — directly incompatible with the "org pays the first box" decision (it would require converting to a paid GitHub Org, which then flips billing org-wide).
+- **Unified stack** (we already run DO; existing deploy tooling) and **flexible billing** (org account or the builder's own DO account).
+- **Escape hatch:** because the devcontainer is portable, a VS-Code-preferring builder may **self-fund their own Codespaces** off the same spec. Codespaces is an opt-in individual lane, not the foundation.
+
+## Alternatives considered
+
+- **Fully remote with centralized inference (org runs everything on one provider + a shared API key).** Rejected. Centralizing inference forces the 15–30× more expensive per-token rate onto the org and concentrates provider/price/sunset risk (cf. AWS Cloud9's 2024 closure) — exactly the margin pressure we want to avoid. The hybrid contains "fully remote" as one configuration without forcing centralized inference.
+- **GitHub Codespaces as the org substrate.** Rejected as the *default* (kept as an opt-in self-funded lane). On our private *personal* repo it preserves access-control and revocation (those live in GitHub permissions, independent of who pays) but **loses enforced environment control** (the collaborator is root), is **awkward to drive from Claude Desktop**, its auto-suspend **kills Remote Control**, and the org **cannot pay the first box**. Its genuine strengths (native self-funding, native auto-suspend, zero ops) collide with three firmer priorities (Desktop-first UI, org-funded onboarding, enforced control).
+- **Anthropic-managed Cloud VM for onboarding.** Rejected by the decider. Though free to the org (runs on the builder's subscription), it is ephemeral, GitHub-centric, network-restricted, cannot host our full stack, and cannot cleanly SSH out to deploy. We pay for a real starter box instead.
+- **Pure bring-your-own box (builder creates + pays from day one).** Rejected as the entry path — it reintroduces the payment/signup barrier that suppresses early growth. It is the *destination* (the "established" stage), not the on-ramp.
+- **Shared org Anthropic API key.** Rejected — 15–30× costlier than subscriptions and the wrong side of the headless-use terms. BYO-subscription is both cheaper and cleaner.
+- **Keep local-only.** Rejected — it fails C1 (toolchain install is the worst onboarding burden) and excludes builders without capable hardware.
+
+## Consequences
+
+**Good:**
+- Onboarding drops from "install a toolchain and hope" to "open Claude Desktop, pick the Example Dev Box" — the direct lever on C1 (≤2h).
+- Org inference cost = $0 (BYO subscription); org compute cost ≈ $0 ongoing (auto-suspend + self-funding), bounded by a small starter-box pool.
+- The container is a real security upgrade: rank-gated source access, no permanent local clones, central revocation, clean offboarding, egress restriction — strengthening [ADR 0016](<redacted>.md).
+- The box stays portable (devcontainer), so we are not locked to DigitalOcean, and VS-Code power-users can self-fund Codespaces off the same spec.
+- [ADR 0024](<redacted>.md) memory sync is unaffected — it keys on `builder_id`, not on where the box runs.
+
+**Costs / what it commits us to:**
+- Real build work: author + test the devcontainer across a DO box and a laptop (the `sharp` native build is the usual snag), build the auto-suspend automation (DO has none native), wire prod-deploy to CI, build rank-gated box provisioning, and write the onboarding primer page.
+- An ongoing operational surface: per-builder box lifecycle (provision, suspend, de-provision), managed-settings distribution, and the `claude rc` service for thin-device builders.
+- The autonomous-lane ToS posture (§4) is a judgment call with a recorded residual risk to re-verify.
+
+**Operationally:**
+- Auto-suspend and prod-deploy-to-CI should land before the first non-Lars builder, or the cost and security properties this ADR promises aren't real yet.
+- The onboarding repo-access wrinkle (see Open questions) must be resolved before a Xenos's starter box is provisioned.
+
+## Open questions (flagged, not blocking)
+
+1. **Per-builder box ownership transition.** Mechanics of moving a builder from the org-funded starter box to self-funding — recreate on their own DO account vs. org-provisions-and-rebills via the `costs` table. Lean: rebill-via-drachmae for simplicity; revisit.
+2. **Onboarding repo-access scoping.** ✅ **RESOLVED 2026-06-05 ([#600](https://example.com/builders#/task/600)) — rank-gated, server-issued, fetched-not-baked.** A Xenos box sparse-checks out only the safe surface; full creds arrive at graduation; the box fetches a scoped credential gated on live rank rather than holding a baked one. See the resolution note below.
+3. **Auto-suspend implementation.** ✅ **RESOLVED 2026-06-04 ([#598](https://example.com/builders#/task/598)) — snapshot-and-park, NOT Coder.** See the resolution note below.
+4. **Thin-device on-ramp friction.** ✅ **RESOLVED 2026-06-06 ([#701](https://example.com/builders#/task/701)) — box reports its pairing link UP to the GDS; the builder reads it from the web.** See §9.4 below.
+5. **Codespaces self-fund lane.** Confirm (empirically) that a collaborator self-funds on the private personal repo, and decide whether to actively support the VS-Code lane or merely allow it.
+6. **Desktop SSH on the chosen DO image.** SSH-to-macOS/Linux and the redesign are recent (April 2026, parts research-preview); pin versions and verify on the actual image before rollout.
+
+## Open-question resolutions
+
+### §9.2 — Onboarding repo-access scoping: rank-gated, server-issued, fetched-not-baked (2026-06-05, [#600](https://example.com/builders#/task/600))
+
+**Decision: the box holds NO baked credential — it fetches a rank-scoped clone spec from the GDS at boot + on a cron, gated on the builder's LIVE rank.** This extends the [ADR 0016](<redacted>.md) trust boundary from "writes are gated" to "source is gated": `GET /api/gds/box/source-access` (`requireBuilder`; the scope + allow/deny decided inside from the live DB rank, not a static `requireRank`) returns either a 403 or a scope-appropriate spec + a short-lived, operator-supplied credential.
+
+- **Scope by rank** (`src/bongos/box-access.js`, `boxScopeForRank` from [#598](https://example.com/builders#/task/598)): **Xenos → `starter`** (cone-mode sparse-checkout of `.devcontainer`, `art`, `docs`, `public-status`, `generative-ideas.md` — the "first tasks on a scoped surface" this question asked for); **Metic+ → `full`**. Graduation rescopes the box (the box re-clones the full surface on its next refresh). Fail-closed: any unknown scope collapses to `starter`.
+- **Credential is fetched, never baked** (`src/bongos/box-credential.js`, env-backed default; the secret lives in the prod env per [ADR 0022](0022-secrets-policy.md), `configured:false` until set). The box clones via a one-shot authenticated URL then scrubs the token from `.git/config` (`infra/box-source-fetch.sh`). Because access is re-checked live on every fetch, **revocation is instant at the credential layer** — a demoted/deactivated builder is 403'd on their next refresh.
+- **The clawback (clean offboarding).** `setBuilderRank` / `deactivateBuilder` flag a box reconcile post-commit; `scripts/gds/box.js reconcile` deprovisions below-floor / inactive boxes and rescopes graduated ones. Credential revocation is instant; droplet teardown is the async control-plane half. Every grant/denial/reconcile is audited to `box_events`.
+- **Honest limit (recorded, unchanged from §6).** Git cannot sub-path-scope a single private repo and sparse-checkout is client-side, so the default `starter` surface is **defense-in-depth + audit + revocation, not insider-proof DRM**. A HARD boundary is available via `BOX_SOURCE_STARTER_REPO_URL` (a physically separate starter repo) — left as an operator choice.
+
+Operator runbook: `docs/recipes/managed-settings-remote-control.md` Part 4. **The <redacted> leg (a live box fetching + sparse-cloning against a configured GitHub credential) is unverified on hardware** — same posture as [#598](https://example.com/builders#/task/598)/[#599](https://example.com/builders#/task/599); the decision core, the route, the clawback, the cloud-init injection, and the box-side script are verified hermetically (`tests/box_access.mjs`, `scripts/gds/smoke-box.sh`).
+
+### §9.3 — Auto-suspend: snapshot-and-park, not a Coder control-plane (2026-06-04, [#598](https://example.com/builders#/task/598))
+
+**Decision: build snapshot-and-park.** When a box goes idle, snapshot the droplet then **destroy** it; recreate from the snapshot on demand. Implemented in `scripts/gds/box.js` (the lifecycle CLI), `src/bongos/boxes.js` (the pure decision core), `src/bongos/do-api.js` (the DO client), the `builder_boxes` + `box_events` tables (migration 067), and two control-plane sweeps (`box-idle-suspend` every 15 min, `box-dormant-reclaim` daily).
+
+**Why not Coder.** Coder is a full control-plane: it needs an **always-on droplet to host it** (~$12–24/mo fixed) plus its own Postgres, auth, and an upgrade treadmill. That is exactly the *builder-count-independent fixed cost* this ADR's §5 cost model is built to avoid, and a heavy new operational surface for a project that has one builder today. Snapshot-and-park rides `doctl`/the DO API + the existing systemd-timer sweep pattern (it is the direct analogue of `stale-claim-release`), so its fixed cost is ≈ $0 — a parked box costs only its snapshot (~$0.30/mo for a ~5 GB image) instead of ~$24/mo running. Coder's genuine wins (a polished per-workspace model, web terminal) are not things we need: the UI is Claude Desktop (§1), and the per-builder model is one droplet keyed by `builder_id` in our own table.
+
+**The DO footgun this encodes.** A *powered-off* DigitalOcean droplet **still bills** (its disk/resources stay reserved). So "park" is not "power off" — it is snapshot → **destroy**, keeping only the cheap snapshot; "wake" is recreate-from-snapshot. This is why the schema's `droplet_id`/`ip` are NULL while parked but `snapshot_id` persists, and why a box accrues compute cost only while `state='active'`.
+
+**Stable hostname (handoff to [#599](https://example.com/builders#/task/599)).** A recreated droplet gets a new IP. The lifecycle records a per-builder `hostname` (`box-<login>.dev.example.com`) and offers a `BOX_DNS_HOOK` to repoint it on each wake; the actual Desktop managed-settings cutover to that hostname is [#599](https://example.com/builders#/task/599).
+
+## Decision update — container pool rejected; droplet-per-builder confirmed; hardware status (2026-06-06, [#699](https://example.com/builders#/task/699))
+
+Two things were settled this session.
+
+### Newcomer substrate: a shared-host container pool was investigated and REJECTED.
+
+The question raised: should the Xenos/newcomer substrate be a **pool of containers packed onto a shared host** (denser, cheaper) instead of the §2 one-droplet-per-builder model? Investigated via two research threads plus a hardware check. Findings:
+
+- **Plain Docker is not a security boundary for this workload.** Builders run an AI agent executing arbitrary code — "hostile by default." Containers share one host kernel, so a single kernel/`runc` escape exposes every co-tenant's source, scoped credential, and Claude session. The escape cadence is roughly annual (runc "Leaky Vessels" Jan 2024; a runc CVE cluster Nov 2025, several of which **bypass AppArmor/SELinux**; Dirty-Pipe-class kernel LPEs every 1–2 years). Revealed preference confirms it: every vendor that runs strangers' untrusted code — AWS Lambda/Fargate, Fly.io, e2b, Vercel, CodeSandbox (Firecracker), Modal, Google Cloud Run (gVisor) — moved **off** plain Docker.
+- **A *secure* pool needs gVisor or Firecracker/Kata microVMs**, plus the full in-container hardening checklist, plus a placement/pool manager, plus snapshot-suspend to reclaim idle RAM. DO **does** expose `/dev/kvm` (verified on the prod droplet: `vmx` flag, `kvm_intel` loaded), so microVMs are technically viable here.
+- **The cost win is real but modest, and the "less middleware" premise is inverted.** The ~$0/idle-container economics depend on scale-to-zero *plain* containers, which security forbids. Secure warm cost ≈ $1.65–2.65/tenant/mo (≈ $0.30–0.60 with Firecracker snapshot-suspend) vs ≈ $5–12 for a per-builder droplet — i.e. cheaper only at dozens of concurrent newcomers. And the droplet model gets isolation **free** from the VM boundary, whereas the pool must *re-engineer* isolation (security runtime + pool manager + snapshot orchestration) — strictly **more** to build and run, plus a hard network-isolation requirement (a pool host co-locating many builders' credentials must not be able to reach the control plane / GDS Postgres).
+
+**Decision: droplet-per-builder only — §2's "one box per builder" stands unqualified. The container pool is rejected.** At one builder it earns nothing; it pays off only at scale, and even then trades dollars for multi-tenant security engineering. Revisit *only* if concurrent-newcomer volume reaches the dozens **and** the gVisor/microVM security work is funded. (Sources: [runc Nov-2025 CVEs](https://www.sysdig.com/blog/runc-container-escape-vulnerabilities), [container-isolation consensus](https://www.aquasec.com/blog/container-isolation/), [microVM isolation 2026](https://emirb.github.io/blog/microvm-2026/).)
+
+### Hardware-verification status (sharpens the §9.2 note).
+
+- **The §9.3 lifecycle ([#598](https://example.com/builders#/task/598)) is verified on real hardware (2026-06-04).** `box_events` records a full `provision → park → wake → deprovision` cycle that day (droplets `575387789`/`575388325`, snapshot `231499516`). **Operator gotcha:** the first attempt failed with `DO POST /droplets … missing the required permission tag:create` — the `DO_API_TOKEN` must carry **tag-create** scope (use a Full-Access token, or a custom token that includes tag write).
+- **The [#685](https://example.com/builders#/task/685) builder-side `connect.sh` is verified on a real Mac (2026-06-06)** — GitHub device sign-in, `~/.ssh/otb_builder` key generation + registration, and `managed-settings.json` install all succeeded end-to-end.
+- **Still unverified on hardware:** the §9.2 ([#600](https://example.com/builders#/task/600)) source-fetch leg (sparse clone against a configured GitHub credential — `BOX_REPO_URL`/credential were not set), the operator `box.js onboard` welcome-packet on a live box, and the actual Claude Desktop **connect to a running box**. The token was removed after the 2026-06-04 run, so no `box.env` is currently configured.
+
+### The real remaining onboarding gap → ✅ CLOSED ([#701](https://example.com/builders#/task/701), 2026-06-06).
+
+Droplet-vs-pool was a *backend* choice; it did not address the newcomer on-ramp. For a non-technical / Chromebook builder, three server-side pieces were unbuilt: **auto-provision** (no builder-held DO token, no manual operator CLI), **wake-on-connect** (a returning builder's parked box wakes itself), and the **web/Chromebook Remote-Control pairing** path. All three shipped under [#701](https://example.com/builders#/task/701) — see §9.4.
+
+### §9.4 — Box onboarding middleware: an intent queue, never the DO token in the web process (2026-06-06, [#701](https://example.com/builders#/task/701))
+
+> **Superseded in part (2026-06-06, [ADR 0038](<redacted>.md)):** the `claude rc` Remote-Control pairing path in this section — `infra/box-report-pairing.sh`, the `box/pairing` + `box/pairing-link` routes, and the "box reports its link UP" Chromebook flow — is retired. `claude rc` can't run headless on a box (see ADR 0038 *Problem*). The browser-only on-ramp is now a box-served `ttyd` web terminal over a Cloudflare Tunnel. The intent-queue / `box/ensure` auto-provision + wake-on-connect machinery below is **unaffected**.
+
+**Decision: the web process records a REQUEST (an "intent"); the control-plane runner executes it.** The hard constraint (§6 + the `routes/box.js` header) is that the internet-facing Node process must never hold `DO_API_TOKEN` — a stolen builder token could otherwise spin up or destroy infrastructure. So [#701](https://example.com/builders#/task/701) does NOT move provisioning into the web tier. Instead:
+
+- **Auto-provision + wake-on-connect = one primitive: `POST /api/gds/box/ensure`** (`requireBuilder`; allow/deny + the chosen action decided inside from the builder's LIVE rank+status via `boxes.decideEnsureAction`, mirroring `/box/source-access`). It writes a row to the new **`box_intents`** queue (migration 070): `provision` when the builder has no box (auto-provision), `wake` when their box is parked (wake-on-connect), a no-op heartbeat when already active. At most ONE open intent per builder (a partial unique index), so a flaky Chromebook tab can't pile up duplicates.
+- **The control-plane runner drains the queue.** `scripts/gds/box.js run-intents --apply`, on a 1-minute `box-intent-runner.timer` (the same systemd-timer pattern as the idle/dormant sweeps), claims each pending intent (`FOR UPDATE SKIP LOCKED`) and calls the SAME `cmdProvision`/`cmdWake` an operator uses — with a small attempt cap so a poison intent retires to `error` rather than looping. The web tier stays powerless over infra; it can only ask.
+- **Web/Chromebook pairing: the box reports its link UP.** A Chromebook has no Claude Desktop, so its on-ramp is the `claude rc` Remote-Control pairing link — which previously existed only in the box's journal (reachable only via SSH, defeating the purpose). Now `infra/box-report-pairing.sh` (a 1-min box cron, authenticated as the builder via the GDS token already on the box) POSTs the current link to **`POST /api/gds/box/pairing`** (stored on `builder_boxes.remote_pairing_url`, only while the box is `active`), and the builder reads it from the browser via **`GET /api/gds/box/pairing-link`** (returned only to the box's own builder). The Chromebook flow: `POST /box/ensure` → poll `GET /box/pairing-link` until a link appears → open it.
+
+**Honest limit (recorded).** The server-side decision core (`decideEnsureAction`, the intent queue, the three routes, the runner) is verified hermetically (`tests/boxes.mjs` 33 assertions, `scripts/gds/smoke-box.sh`). The **live legs are unverified on hardware** — same posture as §9.2/§9.3: a real box actually being auto-provisioned by the timer, a parked box waking on `ensure`, and `claude rc` publishing a real pairing link that reaches the browser. The `box-intent-runner.timer` + `box-report-pairing` cron must be installed on the control plane / baked into the box (the cloud-init wires the box cron; the operator installs the control-plane timer per the lifecycle recipe).
+
+## Implementation sub-tasks (proposed — to be seeded in a planning/triage session)
+
+Not yet created; listed so the build session has a starting decomposition.
+
+| Proposed task | What it builds | Criterion |
+|---|---|---|
+| Devcontainer foundation | `devcontainer.json` + Dockerfile (Node 22, Python + art libs, `sharp` deps, Claude Code feature + firewall); fold in `setup-builder.sh`; `doctor.js` as health check | C1 |
+| Prod-deploy to CI | Move prod deploy to GitHub Actions (mirror `deploy-staging.yml`) so no builder box holds the droplet key | C8 / security |
+| DO box provisioning + auto-suspend | Per-builder box provision, idle snapshot/park + recreate, dormant de-provision; rank-gated | C1 / cost |
+| Managed-settings + Remote Control service | Distribute the locked `sshConfigs`/`sshHostAllowlist`; always-on `claude rc` for thin devices | C1 |
+| Rank-gated source access | Box holds the scoped GitHub credential; access granted/revoked by rank; offboarding clawback | C2 / C7 / C9 |
+| Onboarding primer page ✅ | **Done** — the §"mental model" explainer lives in [`docs/onboarding/primer.md`](../onboarding/primer.md) § "Where your work runs" (extracted in the ADR 0035 rewrite, [#718](https://example.com/builders#/task/718); closed by task 601) | C1 |
+| Cost passthrough wiring | Org-funded starter → self-fund transition via `costs`/drachmae | cost |

package/docs/adr/0032-discord-mirror-of-gds.md

@@ -0,0 +1,50 @@
+# ADR 0032 — Discord as a one-way mirror of the GDS (outbound broadcast moves off Google Chat)
+
+**Date:** 2026-06-04
+**Context:** GDS-V3, task [#607](https://example.com/builders#/task/607) (claim `#482`). Stands up a Discord server for Off the Boats / Example — one server, permission-walled into a player wing and a builder wing — and moves the ship-broadcast off Google Chat. Companion to [ADR 0016](<redacted>.md) (the trust boundary — the load-bearing constraint here), [ADR 0018](<redacted>.md) (Xenos → Metic → Archon, the ranks Discord roles mirror), [ADR 0022](0022-secrets-policy.md) (webhook URLs are secrets, kept out of the repo), and [ADR 0008](0008-google-chat-oauth-user-auth.md) (the Google Chat broadcast this supersedes for outbound).
+**Status:** Accepted. Phase 2 (outbound ship broadcast → Discord) implemented in [#607](https://example.com/builders#/task/607). Phases 3+ (interaction bot, inbound retirement, role sync) scoped below, not yet built.
+**Track:** `internal` (dev-system / team communication).
+
+## Problem
+
+The project is opening to multiple builders (GDS-V3) and will eventually have players (the game is live; the purchase loop lands in V3-product). We want one community home with two audiences — builders and players — and a single legible place where build progress is announced and where the community can react.
+
+Two existing surfaces are relevant:
+
+- The **ship broadcast** posts a plain-language "what shipped" summary to the Example team **Google Chat** space ([ADR 0008](0008-google-chat-oauth-user-auth.md); fired from `scripts/gds/ship.js` on deploy). Google Chat is a closed business space — fine for the Example owners, wrong as a builder+player community hub.
+- The **GDS** already holds all authoritative state: ranks, tasks, karma (`peer_upvote` is an existing reason), idea_inbox, drachmae, the builders' hall.
+
+The temptation, standing up Discord, is to let it *own* things — roles that grant power, votes that live in Discord, a second scoreboard. That would fracture the source of truth and — for roles — quietly punch a hole in the trust boundary.
+
+## Decision
+
+**Discord is a one-way mirror of, and input surface for, the GDS — never a source of authority or truth.**
+
+1. **One server, two role families, permission-walled.** A public (player) wing and a builder-only wing in a single server. Builder roles **mirror** the live GDS ranks (Xenos / Metic / Archon) and gate the builder wing; players get a `Citizen` baseline (a `Patron` tier later, once purchases ship).
+
+2. **Discord roles are cosmetic, never authoritative ([ADR 0016](<redacted>.md)).** A Discord "Archon" badge unlocks Discord *channels* and nothing else. Authority stays in `builders.rank` on the prod DB, re-checked server-side per request. A Discord role is a *sticker*; the GDS holds the *keys*. Roles reflect what the DB already says — they never decide it. When a future bot auto-assigns roles, it reads `builders.rank` and writes the Discord role, never the reverse.
+
+3. **The GDS stays the single source of truth.** Logs mirror *into* Discord (webhooks, one-way). "Upvotes" arrive as Discord reactions that a bot writes *back* to the GDS as `peer_upvote` karma / idea votes — Discord is the input device, the GDS records the fact. No state's canonical home moves to Discord.
+
+4. **Outbound ship broadcast moves from Google Chat to Discord `#ship-news`** (this task, [#607](https://example.com/builders#/task/607)). `scripts/gds/ship.js` posts the task `--summary` to a Discord webhook via `scripts/discord/`. Same posting rules as before (plain-language, business-facing, no jargon — see [`../google-chat-broadcast.md`](../google-chat-broadcast.md)). Webhook URLs are secrets ([ADR 0022](0022-secrets-policy.md)) at `~/.config/otb/discord-webhooks.json` (mode 600), never committed; the broadcast runs on the operator's machine during `/builder-ship`, so the droplet needs no secret.
+
+### Phasing
+
+- **Phase 2 (this task, [#607](https://example.com/builders#/task/607)):** outbound `#ship-news` broadcast. **Done.**
+- **Phase 3:** a Discord bot on the droplet for reactions → `peer_upvote` karma / idea votes, and retirement of the Google Chat **inbound** path (team messages → idea pipeline). Reading messages needs a bot, not a webhook. Account-linking (Discord user ↔ GDS builder) must be UI-first — browser clicks, no terminal token paste.
+- **Later:** auto-sync `builders.rank` → Discord role; build out the player wing when the purchase loop ships.
+
+## Consequences
+
+- The team's "what shipped" updates now land in a community Discord that builders and players can share, instead of a closed business chat.
+- The trust boundary stays intact and legible: exactly zero authority lives in Discord; the one rule to defend in review is "roles mirror the DB, never grant."
+- Google Chat is **half-retired**: outbound is gone (Discord), inbound (`chat-intake-daily`) still runs until Phase 3. `scripts/chat/` stays in the tree until then.
+- A leaked webhook URL is low blast-radius (write-only to one channel) and rotated with one click in Discord — no code change.
+
+## Alternatives considered
+
+- **Separate servers for builders vs players.** Rejected — one server with a permission-walled builder wing is the standard pattern and keeps the community in one place.
+- **Discord roles grant real permissions.** Rejected outright — violates [ADR 0016](<redacted>.md). Anything a builder's Discord membership could grant must be re-derived server-side from `builders.rank`.
+- **Move idea votes / karma canonical into Discord.** Rejected — the GDS stays source of truth; Discord is an input surface whose reactions a bot writes back.
+- **Mirror outbound to both Google Chat and Discord.** Rejected — replace, don't double-post; the community consolidates on Discord. Google Chat keeps only its inbound role until Phase 3.
+- **A Discord bot (gateway) for outbound too.** Rejected for Phase 2 — a webhook is a one-line HTTP POST with no token or process to host; the bot is only needed for *reading* (Phase 3).