@bongos/core 1.19.1072 → 1.19.1074

package/docs/recipes/managed-settings-remote-control.md

@@ -1,416 +0,0 @@
-# Recipe - managed-settings SSH + browser-terminal on-ramps
-
-> **Task [#599](https://example.com/builders#/task/599) · [ADR 0031](../adr/0031-cloud-dev-environments-for-builders.md) §1.** This is the operator guide for distributing a locked Claude Desktop SSH connection to builders and for serving the browser web-terminal on the box. It assumes a box is already provisioned and running; the lifecycle runbook that explained how to get one (`builder-box-lifecycle.md`) was retired with the rest of the published dev-box recipes (task 1004013, [ADR 0305](../adr/0305-a-recipe-lives-with-what-it-documents.md)). This recipe documents the same module and is queued to follow it.
-
-> **Chromebook/browser path (ADR 0038 → [ADR 0040](../adr/0040-remote-control-default-browser-onramp.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)):** the box serves its own web terminal - `ttyd` bound to localhost, exposed via an outbound-only Cloudflare Tunnel - and the builder runs a NORMAL interactive `claude` inside it from any browser. Because there is a real human at a real browser-backed terminal, `/login`, workspace-trust, and Trusted-Devices enrollment all succeed (the things that made headless `claude rc` unworkable). **ADR 0040 narrows that terminal to a one-time launchpad:** the builder logs in there once, runs the in-session **`/remote-control`** slash command, and then drives the box from the Claude web/mobile app — the terminal is no longer their daily surface. **The SSH path (Mac/Windows) below is unaffected and works.**
-
----
-
-## The two on-ramps
-
-| Builder's device | Path | What this recipe wires |
-|---|---|---|
-| **Mac / Windows** | Claude Desktop → SSH → box | Pre-distributed `managed-settings.json` (locked `sshConfigs`) |
-| **Chromebook / any browser** | Browser -> `ttyd` web terminal over an outbound Cloudflare Tunnel -> box (reached at `GET /box/terminal`) -> log in once, then `/remote-control` -> drive the box from the Claude web/mobile app (ADR 0040) | `box-terminal.service` (ttyd, localhost-only) + `cloudflared.service` (outbound tunnel) + `box-report-terminal` cron |
-
-Both paths land the builder on the same box and the same `/workspace`. The choice is which GUI they prefer, not which machine they reach.
-
----
-
-## Part 0 — the one-command flow ([#685](https://example.com/builders#/task/685), the default)
-
-> **This is the path to use now.** Parts 1, 3 and 4 below document the underlying
-> pieces (and the manual fallbacks); [#685](https://example.com/builders#/task/685) collapses the builder's side to a single
-> command and the operator's side to a single command. Nobody has to `scp` a JSON
-> file, paste a public key into `authorized_keys`, or `sudo cp` anything by hand.
-
-**The split:**
-
-| Who | Runs | What it does |
-|---|---|---|
-| **Builder** (own Mac/Windows) | `/builder-connect` — or, on a bare laptop, the hosted bootstrap (below) | GitHub sign-in → create+register their SSH key → install `managed-settings.json` |
-| **Operator** (control plane) | `node scripts/gds/box.js onboard <login> --apply` | provision the box (bakes the builder's registered key) + print the welcome packet |
-
-**Builder side** — guided in Claude Desktop (`/builder-connect`), or paste the hosted bootstrap on a bare laptop:
-
-```bash
-# macOS / Linux
-curl -fsSL https://example.com/api/bongos/box/connect.sh | bash
-# Windows (PowerShell)
-irm https://example.com/api/bongos/box/connect.ps1 | iex
-# Plain-text guide (no auth):  https://example.com/api/bongos/box/connect
-```
-
-The bootstrap (`infra/box-connect.sh` / `.ps1`, served by `GET /box/connect.sh|.ps1`)
-is self-contained — only `curl` + `ssh-keygen` (or PowerShell). It device-flow signs
-the builder in, creates `~/.ssh/otb_builder` if absent, registers the **public** key
-(`POST /box/ssh-key`), and downloads + installs `managed-settings.json`
-(`GET /box/managed-settings`) at the OS path. The private key never leaves the machine;
-the token is held only in memory for the two authenticated calls (passed to `curl` via a
-0600 config file, never on the command line).
-
-> **Operator note (staging):** the served script's `GDS_API_BASE` is pinned to
-> `GDS_PUBLIC_ORIGIN` (default `https://example.com`) — the SAME env var the OAuth
-> `redirect_uri` uses — and is **never** derived from a request header, so a spoofed
-> `Host` can't redirect a victim's `curl … | bash`. On staging, set
-> `GDS_PUBLIC_ORIGIN=https://staging.example.com` in the server env (you already do,
-> for OAuth) and the connect scripts target staging automatically.
-
-**Operator side:**
-
-```bash
-node scripts/gds/box.js onboard <login>          # dry-run: shows the plan + key count
-node scripts/gds/box.js onboard <login> --apply  # provision + print the welcome packet
-```
-
-`onboard` refuses if the builder has **no registered SSH key** (the box would have no
-way in) — the canonical order is **builder connects first, then operator onboards**.
-Override with `--allow-no-keys` only if you will re-provision once they register a key.
-
-**How the key reaches the box without an operator SSH round-trip:** `box.js` reads the
-builder's registered keys from the DB and **bakes** them into the cloud-init managed
-block at provision (so the first login works before the box has any Bongos token). From
-then on, `infra/<redacted>.sh` (a 10-min cron on the box, wired by the
-cloud-init) keeps `authorized_keys` in sync via `GET /box/authorized-keys` — which is
-**gated on the builder's LIVE rank+status** exactly like source access ([#600](https://example.com/builders#/task/600)). A
-demoted/deactivated builder gets a 403 and the cron empties the managed block — instant
-SSH-login revocation — **without touching the operator's own key** (only the lines
-between the `otb-managed` markers are rewritten). The droplet teardown follows via
-`box.js reconcile`.
-
-The rest of this recipe is the manual decomposition + fallbacks.
-
----
-
-## Part 1 — Claude Desktop SSH (Mac / Windows)
-
-### How it works
-
-The builder installs Claude Desktop (free; no paid plan needed for the app shell). You pre-distribute a `managed-settings.json` that contains the SSH connection for their box. When they open Claude Desktop → Code → Environment, they see exactly one entry: **"Example Dev Box"** — no configuration required on their end.
-
-Claude Desktop SSHes to the box, auto-installs Claude Code on the host (on first connect), and starts a Code session directly in `/workspace`. The builder is ready to work.
-
-### Step 1 — Provision the box
-
-```bash
-node scripts/gds/box.js provision <login> --apply
-```
-
-This creates the DigitalOcean droplet, runs the cloud-init, and registers the box. The builder's hostname is `box-<login>.dev.example.com`.
-
-### Step 2 — Generate the managed-settings.json
-
-```bash
-bash infra/gen-managed-settings.sh <login> > /tmp/<login>-managed-settings.json
-cat /tmp/<login>-managed-settings.json
-```
-
-The output is a small JSON file, e.g.:
-
-```json
-{
-  "sshConfigs": [
-    {
-      "id": "otb-alice",
-      "name": "Example Dev Box",
-      "sshHost": "root@box-alice.dev.example.com",
-      "sshIdentityFile": "~/.ssh/otb_builder",
-      "startDirectory": "/workspace"
-    }
-  ],
-  "sshHostAllowlist": ["*.dev.example.com"]
-}
-```
-
-### Step 3 — Give it to the builder
-
-Send them the file and these instructions (copy-paste friendly):
-
-> **Mac:** Open Terminal and run:
-> ```bash
-> sudo mkdir -p "/Library/Application Support/ClaudeCode"
-> sudo cp ~/Downloads/<login>-managed-settings.json "/Library/Application Support/ClaudeCode/managed-settings.json"
-> ```
-> Then restart Claude Desktop. You'll see "Example Dev Box" in Code → Environment.
->
-> **Windows:** Save the file to `C:\Program Files\ClaudeCode\managed-settings.json` (create the folder if it doesn't exist; needs Administrator). Restart Claude Desktop.
-
-> ⚠️ **The directory is `ClaudeCode`, not `Claude`.** Claude Code reads managed settings from `/Library/Application Support/ClaudeCode/` (macOS) and `%ProgramFiles%\ClaudeCode\` (Windows). A file under `…/Claude/` or `%ProgramData%\Claude\` is silently ignored and the box never appears in the Environment picker (the [#808](https://example.com/builders#/task/808) onboarding bug). The legacy `%ProgramData%\ClaudeCode\` Windows path was dropped in v2.1.75.
-
-### Step 4 — Builder's SSH key
-
-The `managed-settings.json` points to `~/.ssh/otb_builder` as the identity file. The builder needs this key pair generated on their machine, and you need to add the **public key** to the box.
-
-**Builder runs (once):**
-```bash
-ssh-keygen -t ed25519 -f ~/.ssh/otb_builder -C "otb-builder"
-cat ~/.ssh/otb_builder.pub
-```
-
-**Operator adds the public key to the box:**
-```bash
-ssh root@box-<login>.dev.example.com \
-  "echo '<public key here>' >> ~/.ssh/authorized_keys"
-```
-
-Or, if the builder's key is already registered as a DO SSH key, pass it via `BOX_SSH_KEY_IDS` at provision time so it's injected automatically.
-
-### What `sshHostAllowlist` does
-
-The `sshHostAllowlist: ["*.dev.example.com"]` entry prevents the builder from using Claude Desktop SSH to connect to arbitrary hosts. Their SSH picker only shows the pre-configured OTB box — they can't misconfigure or wander off it. This is a `managed-settings`-only field; user-level settings cannot override it.
-
----
-
-## Part 2 - Browser on-ramp: terminal launchpad -> Remote Control (Chromebook / any browser) - ADR 0038 -> [ADR 0040](../adr/0040-remote-control-default-browser-onramp.md), [#760](https://example.com/builders#/task/760) / [#824](https://example.com/builders#/task/824)
-
-### How it works
-
-The box serves its own web terminal. Two systemd units do the work:
-
-- **`box-terminal.service`** runs `ttyd` (a web-terminal daemon) bound to `127.0.0.1:7681`, basic-auth protected with a per-box generated password, dropping whoever connects into a shell in `/workspace`. It listens on localhost only - the box opens **no inbound port**.
-- **`cloudflared.service`** (via `infra/cloudflared-run.sh`) runs a Cloudflare Tunnel that makes that localhost terminal reachable from a browser. The tunnel is **outbound-only**: the box dials out to Cloudflare, so nothing has to be opened in the firewall.
-
-The builder opens the tunnel URL in any browser, authenticates at the basic-auth prompt, and then runs a **normal interactive `claude`** in the terminal. The first `claude` run prompts a normal browser `/login`; because there is a real human at a real browser-backed terminal, `/login`, workspace-trust, and Trusted-Devices enrollment all succeed - the exact steps that headless `claude rc` could never perform.
-
-**The terminal is a one-time launchpad, not the daily surface (ADR 0040).** Once the builder is signed in to that interactive `claude` session, they run the in-session **`/remote-control`** slash command. It prints a pairing link; opening that link drives the box from the Claude web/mobile app. From there the builder lives in the Claude app — the ttyd terminal is just where they logged in and kicked RC off.
-
-> ⚠️ **Use the in-session `/remote-control` slash command — NOT the standalone `claude rc` shell command.** The standalone command mis-checks workspace trust ([anthropics/claude-code#35817](https://github.com/anthropics/claude-code/issues/35817)): it reports `Workspace not trusted` even when the directory is trusted, and a plain shell can't accept the trust dialog. Starting RC from *inside* an already-running, already-trusted `claude` session is the working path (verified live 2026-06-07). Closing the terminal window ends the remote session and closes the box — a property of the session lifecycle, stated up front so builders aren't surprised.
-
-> **Workspace trust is pre-seeded ([#824](https://example.com/builders#/task/824)).** The cloud-init writes `/root/.claude.json` with `<redacted>` for `/root` + `/workspace`, so the first `claude` launch usually skips the trust dialog entirely. This is **non-load-bearing** (ADR 0040): the seed is best-effort and only written when the file is absent (upstream pre-seeding is flaky, [#9113](https://github.com/anthropics/claude-code/issues/9113)). If it doesn't take, the builder just accepts trust once — the flow works either way.
-
-The cloud-init wires both units automatically (and `infra/box-source-fetch.sh` re-installs them on its post-clone bring-up, so a box provisioned before this shipped picks them up on its next refresh). It copies `infra/box-terminal.service` and `infra/cloudflared.service` to `/etc/systemd/system/`, enables them with `systemctl enable --now`, and wires `infra/box-report-terminal.sh` as a 1-minute cron that publishes the terminal URL + credential **up** to Bongos (`POST /box/terminal`) so the builder's self-serve flow can read them back.
-
-**Tunnel modes:**
-
-- **Quick tunnel (default, zero operator secrets).** `cloudflared` opens a tokenless quick tunnel and gets a random `https://<id>.trycloudflare.com` hostname. Nothing to configure - works out of the box.
-- **Named tunnel (production upgrade, stable hostname).** When `/etc/otb/box.env` carries `BOX_TUNNEL_TOKEN` + `BOX_TERMINAL_HOSTNAME`, `cloudflared` runs a named tunnel instead and the terminal is reachable at a stable `term-<login>.example.com` host. As of [#771](https://example.com/builders#/task/771) the control plane **creates and bakes those automatically** on `box.js provision` (and tears them down on `deprovision`) — see the [named-tunnel automation](#<redacted>) section below.
-
-### Getting onto the terminal (builder self-serve)
-
-No SSH and no pairing script - two API calls:
-
-```bash
-# 1. Get a box (provisions or wakes it; see Part 0 / #701):
-POST /api/bongos/box/ensure
-
-# 2. Poll until the box has reported its terminal up:
-GET /api/bongos/box/terminal
-#    -> {"url": "https://<id>.trycloudflare.com", "credential": "<redacted>"}
-```
-
-Then:
-
-1. Open the returned `url` in a browser.
-2. At the browser's basic-auth prompt, enter username **`otb`** and the password (the `credential` value).
-3. In the terminal, type `claude` and press enter. On first run it walks the normal browser `/login` (workspace trust is pre-seeded, [#824](https://example.com/builders#/task/824), so the trust dialog usually doesn't appear; accept once if it does). You're now in an interactive Claude Code session in `/workspace`.
-4. Inside that session, run the **`/remote-control`** slash command. It prints a pairing link.
-5. Open that link to drive the box from the Claude web/mobile app. The terminal was the launchpad — work from the Claude app from here. (Closing the terminal window ends the remote session and closes the box.)
-
-### Service lifecycle
-
-| State | What happens |
-|---|---|
-| Box first boots | `box-terminal.service` (ttyd) + `cloudflared.service` start; `box-report-terminal` cron publishes the URL + credential to Bongos within ~1 min |
-| Builder connects (first time) | Opens the tunnel URL, basic-auths as `otb`, runs `claude` (one-time browser `/login`), then `/remote-control` to get a pairing link and drive the box from the Claude app (ADR 0040) |
-| Builder works (each session) | Lives in the Claude web/mobile app via the RC link; the ttyd terminal is only the launchpad they logged in through |
-| Session ends | Builder closes the browser tab; the terminal + tunnel stay up for the next visit |
-| Box is parked (idle-suspend) | Both units stop naturally when the droplet is destroyed; they restart clean on wake and the cron re-publishes a fresh URL |
-
-
-### Checking the services
-
-```bash
-# On the box:
-sudo systemctl status box-terminal      # the ttyd web terminal
-sudo systemctl status cloudflared        # the outbound tunnel
-journalctl -u box-terminal -f            # live tail
-journalctl -u cloudflared -f             # tunnel logs - quick-tunnel URL appears here
-journalctl -u cloudflared -n 100         # last 100 lines
-sudo systemctl restart box-terminal cloudflared
-```
-
-The quick-tunnel hostname is printed in the `cloudflared` journal; the same value is published to Bongos by the `box-report-terminal` cron (verify with `crontab -l | grep box-report-terminal`).
-
-### Named-tunnel automation (control plane, [#771](https://example.com/builders#/task/771))
-
-The named-tunnel upgrade is automated on the control plane (`scripts/gds/box.js` + `src/bongos/cf-tunnel.js`). It is **OPT-IN, default OFF** — leave it off and every box uses the zero-secret quick tunnel.
-
-**Turning it on (operator, in the control-plane `box.env` — the same file that holds `DO_API_TOKEN`, NEVER the web tier):**
-
-```bash
-BOX_NAMED_TUNNEL=1
-CLOUDFLARE_API_TOKEN=<token with Account:Argo Tunnel:Edit + Zone:DNS:Edit>
-CLOUDFLARE_ACCOUNT_ID=<the Cloudflare account id>
-# optional (defaults shown):
-CLOUDFLARE_ZONE=example.com      # the DNS zone the record lives in
-BOX_TERMINAL_ZONE=example.com    # hostname suffix → term-<login>.example.com
-```
-
-This reuses the **same `CLOUDFLARE_API_TOKEN`** as `box-dns-cloudflare.sh` (the [#725](https://example.com/builders#/task/725) `BOX_DNS_HOOK`) — just add the Tunnel scope to it. In the Cloudflare token UI the permission is **Account → Argo Tunnel → Edit** (the older label for the Cloudflare Tunnel / `cfd_tunnel` API; "Cloudflare Tunnel" on newer accounts). Keep the existing **Zone → DNS → Edit**.
-
-> ⚠️ **TLS coverage — why the host is at the apex, not `dev.*` ([#771](https://example.com/builders#/task/771)).** The terminal rides a **proxied** tunnel (Cloudflare terminates HTTPS at its edge), so the hostname needs an edge certificate. Free **Universal SSL covers `example.com` and `*.example.com` (one label) but NOT a two-label host** like `term-x.dev.example.com` — a `dev.*` host fails the TLS handshake at the edge (verified live). So `BOX_TERMINAL_ZONE` defaults to the **apex** (`term-<login>.example.com`, one label, covered for free). Only override it to `dev.example.com` if you've bought an **Advanced Certificate** for `*.dev.example.com`. (The SSH A-record path stays on `dev.*` — it's `proxied=false`/direct-IP and needs no edge cert.)
-
-**What the lifecycle does when it's on:**
-
-| Op | Tunnel action |
-|---|---|
-| `provision` | create-or-reuse a per-builder named tunnel (`otb-term-<login>`), point its ingress at `127.0.0.1:7681`, route a proxied CNAME `term-<login>.example.com → <tunnel-id>.cfargotunnel.com`, fetch the connector token, and **bake** `BOX_TUNNEL_TOKEN` + `BOX_TERMINAL_HOSTNAME` into the box's `/etc/otb/box.env` via cloud-init. The tunnel is created **before** the droplet so its token is present at first boot. |
-| `park` → `wake` | nothing — the tunnel + DNS are IP-independent and durable, and `box.env` rides the snapshot, so the stable hostname survives park/wake with no control-plane call. |
-| `deprovision` (incl. `sweep-dormant` / `reconcile` clawback) | best-effort teardown: delete the CNAME and the tunnel (the droplet is already gone, so connections have dropped). Never blocks the deprovision. |
-
-`box.js provision` (dry-run, the default) prints the tunnel plan without touching Cloudflare; pass `--apply` to create it for real. If `BOX_NAMED_TUNNEL=1` but the token/account id are missing, provision **fails loudly** rather than silently falling back.
-
-**Per-box manual override (no automation):** you can still set the two values by hand on a single box and restart — `cloudflared-run.sh` detects the token and switches modes:
-
-```bash
-# In /etc/otb/box.env on the box:
-BOX_TUNNEL_TOKEN=<redacted> named-tunnel token>
-BOX_TERMINAL_HOSTNAME=term-<login>.example.com
-sudo systemctl restart cloudflared
-```
-
-### Verifying the browser on-ramp end-to-end ([#771](https://example.com/builders#/task/771))
-
-The build is unit- and smoke-covered, but the loop crosses real hardware + a human at a browser. Run this once per change to `ttyd`/`cloudflared`/the terminal routes. **Operator deps:** a box provision (small DO cost) and, for the named-tunnel leg, the CF token with Tunnel scope.
-
-**Leg A — quick tunnel (zero secrets).**
-
-1. Provision a box for a test builder: `node scripts/gds/box.js onboard <login> --apply` (builder must have a registered SSH key, or `--allow-no-keys`). Confirm cloud-init finished: SSH in and `cloud-init status --wait` → `done`; `systemctl is-active box-terminal cloudflared` → `active`.
-2. Confirm the box published its terminal: `tail /tmp/box-report-terminal.log` should show `terminal access reported`. Then as the builder: `GET /api/bongos/box/terminal` (or `/builder-box`) → returns `{ url: https://<id>.trycloudflare.com, credential }`.
-3. Open the `url` in a browser. Basic-auth as **`otb`** + the `credential`. You should land in a `/workspace` shell.
-4. In that terminal run `claude`. Complete the browser `/login` (trust is pre-seeded, [#824](https://example.com/builders#/task/824) — accept once if still prompted) and Trusted-Devices enrollment. Confirm an interactive session starts. **This is the leg `claude rc` could never do** ([#745](https://example.com/builders#/task/745)).
-5. Inside that session, run **`/remote-control`** (the slash command, NOT `claude rc`). Confirm it prints a pairing link; open the link and confirm the Claude web/mobile app drives the box (ADR 0040, verified live 2026-06-07).
-6. Full Chromebook loop: from a browser-only device, `POST /box/ensure` → poll `GET /box/terminal` → open → `claude` → `/remote-control` → drive from the Claude app. No SSH, no Desktop.
-
-**Leg B — named tunnel (stable hostname).**
-
-1. With the CF token (Tunnel + DNS scope) in the control-plane `box.env`, set `BOX_NAMED_TUNNEL=1` + `CLOUDFLARE_ACCOUNT_ID`. Dry-run first: `node scripts/gds/box.js provision <login>` — confirm it prints the `term-<login>.example.com` plan and the CF calls without touching anything.
-2. `node scripts/gds/box.js provision <login> --apply`. Confirm in the Cloudflare dashboard: a tunnel `otb-term-<login>` exists with one healthy connector, and a proxied CNAME `term-<login>.example.com → <id>.cfargotunnel.com`.
-3. `GET /box/terminal` returns the stable `https://term-<login>.example.com`. Open it, basic-auth, `claude` — same as Leg A but on the stable host.
-4. Teardown: `node scripts/gds/box.js deprovision <login> --apply`. Confirm the tunnel **and** the CNAME are gone from the Cloudflare dashboard.
-
-### Gotchas surfaced by hardware verification ([#771](https://example.com/builders#/task/771))
-
-- **Packaged ttyd collision (fixed).** The Ubuntu `ttyd` apt package ships its OWN auto-started `ttyd.service` that binds `127.0.0.1:7681` with **no `--credential`** and runs `login`. It both blocks our `box-terminal.service` (the unit crash-loops on `EADDRINUSE`) and — because the tunnel fronts whatever sits on 7681 — would expose an **unauthenticated** terminal. Cloud-init and the `box-source-fetch` post-clone bring-up now `systemctl mask ttyd` so only our basic-auth ttyd binds the port. On a box provisioned before this fix: `sudo systemctl disable --now ttyd && sudo systemctl mask ttyd && sudo systemctl restart box-terminal`.
-- **IPv4-only Cloudflare calls (fixed).** The CF API token is IP-locked to the droplet's IPv4 (least privilege). The droplet also has IPv6 egress; `cf-tunnel.js` pins IPv4 (undici `Agent{connect:{family:4}}`) or every call 401s — mirroring `box-dns-cloudflare.sh`'s `curl -4`.
-- **⚠ Browser-only bootstrap gap (OPEN — follow-up).** The `ttyd`/`cloudflared` systemd units live in the repo (`/workspace/infra/*.service`), so they only start **after** `box-source-fetch` clones — which needs the **builder's Bongos token on the box**. A pure Chromebook builder has no SSH and no terminal yet, so there is **no first-boot path to place that token** → the terminal never comes up for them. Today it only works if the token is seeded another way (SSH, or an operator). The fix (a follow-up) is to bring ttyd up at **first boot independent of the clone** — e.g. cloud-init writes the unit inline rather than copying it from the repo. Until then, the browser on-ramp is verified to work *given a token on the box*, not from a truly bare browser-only device.
-
----
-
-## Part 3 — The box-heartbeat cron
-
-The cloud-init also wires `infra/box-heartbeat.sh` as a 5-minute cron job. This pings `/api/bongos/box/heartbeat` while the box is in active use (interactive SSH session or CPU load > 0.2). Silence = the idle-suspend sweep ([#598](https://example.com/builders#/task/598)) is free to park the box.
-
-Without this cron the idle sweep measures **uptime** instead of **activity** and may park a box someone is actively using. Always verify it's wired:
-
-```bash
-crontab -l | grep box-heartbeat
-```
-
-If missing (pre-[#599](https://example.com/builders#/task/599) box):
-```bash
-(crontab -l 2>/dev/null; echo "*/5 * * * * /workspace/infra/box-heartbeat.sh >> /tmp/box-heartbeat.log 2>&1") | crontab -
-```
-
----
-
-## Part 4 — Rank-gated source access ([#600](https://example.com/builders#/task/600), ADR 0031 §6 / §9.2)
-
-The box holds **no baked credential**. Instead it fetches a rank-scoped clone spec
-from Bongos at boot and on a 10-minute cron, via `infra/box-source-fetch.sh`
-(carried onto the box as base64 inside the cloud-init `write_files`). The flow:
-
-1. The box reads the builder's Bongos session token (it appears after they authenticate
-   Claude Code / run `/builder-reauth` — so the **first clone lands after the builder
-   connects**, not at boot).
-2. It calls `GET /api/bongos/box/source-access`. Bongos checks the builder's **live**
-   rank + status (ADR 0016 — unforgeable from the box):
-   - **403 `SOURCE_ACCESS_REVOKED`** — builder demoted below the floor or deactivated.
-     The script cuts the credentialed remote (box-side clawback); `box.js reconcile`
-     deprovisions the droplet.
-   - **200 `configured:false`** — the server's source credential isn't set yet (see
-     env below); the box logs guidance and no-ops.
-   - **200 `configured:true`** — returns the scope-appropriate spec + a short-lived
-     credential. The box clones/refreshes `/workspace`, **never persisting the token
-     in `.git/config`** (clones via a one-shot authenticated URL, then resets the
-     remote to the token-less URL).
-3. **Scope by rank** (`src/bongos/box-access.js`): a **Xenos → `starter`** sparse-checkout
-   of the safe surface (`.devcontainer`, `art`, `docs`, `modules/status-ui`,
-   `generative-ideas.md` — the §9.2 "first tasks on a scoped surface"); a **Metic+ →
-   `full`** clone. Graduation (`box.js reconcile`) rescopes a starter box to full; the
-   box re-clones on its next refresh.
-
-**Operator: configure the source credential** (in the **prod env**, never the repo —
-ADR 0022). The default provider (`src/bongos/box-credential.js`) is env-backed:
-
-```bash
-# In the prod environment (e.g. the droplet's systemd unit / .env):
-BOX_SOURCE_REPO_URL=https://github.com/<org>/example.git
-BOX_SOURCE_FULL_TOKEN=<redacted> PAT or installation token, contents:read>
-# Optional — make 'starter' a HARD boundary (a physically separate repo that cannot
-# read the crown jewels) instead of the default sparse-checkout defense-in-depth:
-BOX_SOURCE_STARTER_REPO_URL=https://github.com/<org>/example-starter.git
-BOX_SOURCE_STARTER_TOKEN=<token scoped to the starter repo>
-# Optional — advisory token TTL (how often the box re-fetches + re-checks live rank):
-BOX_SOURCE_TOKEN_TTL_SECONDS=3600
-```
-
-> **Honest limit (ADR 0031 §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**. Set
-> `BOX_SOURCE_STARTER_REPO_URL` for a hard boundary. Every grant/denial is audited to
-> `box_events` (`source_grant` / `source_deny` / `source_revoke` / `source_rescope`).
-
-**The clawback (clean offboarding).** Revoking rank or deactivating a builder cuts
-source on two timelines: the **credential layer is instant** (their next
-`/box/source-access` fetch 403s), and the **droplet teardown** follows when the
-control plane runs reconcile:
-
-```bash
-node scripts/gds/box.js reconcile            # dry-run: show what would change
-node scripts/gds/box.js reconcile --apply    # deprovision below-floor/inactive boxes,
-                                             # rescope graduated ones (run on a schedule)
-```
-
-Verify the source-fetch cron + check progress on the box:
-
-```bash
-crontab -l | grep box-source-fetch
-tail /tmp/box-source-fetch.log
-WORKSPACE=/workspace /usr/local/bin/box-source-fetch.sh   # manual run
-```
-
----
-
-## Quick reference: full operator flow
-
-```bash
-# 0. One-time: set BOX_SOURCE_REPO_URL + BOX_SOURCE_FULL_TOKEN in the prod env (Part 4)
-
-# 1. Provision the box
-node scripts/gds/box.js provision alice --apply
-
-# 2. Add the builder's SSH public key to the box
-ssh root@box-alice.dev.example.com "echo '...' >> ~/.ssh/authorized_keys"
-
-# 3. Generate and send managed-settings.json (Desktop / SSH path)
-bash infra/gen-managed-settings.sh alice > /tmp/alice-managed-settings.json
-# → email/DM to builder with placement instructions
-
-# 4. For thin-device (Chromebook) path: the web terminal is ready automatically
-#    (box-terminal.service + cloudflared.service start at boot; box-report-terminal
-#    publishes the URL + credential to Bongos within ~1 min)
-#    Builder self-serves: POST /api/bongos/box/ensure, then poll GET /api/bongos/box/terminal
-#    -> open the url, basic-auth as user 'otb' with the returned credential, run: claude
-#    -> then /remote-control to drive the box from the Claude app (ADR 0040)
-
-# 5. When the builder is done for the day, the idle sweep parks the box:
-node scripts/gds/box.js sweep-idle --apply   # control plane / prod cron
-
-# 6. Source materializes automatically once the builder authenticates on the box
-#    (the box-source-fetch cron clones the rank-scoped surface). Nothing to do here.
-
-# 7. Offboarding / demotion: the credential is cut on the builder's next fetch;
-#    reconcile then deprovisions the box (run on a schedule alongside the sweeps):
-node scripts/gds/box.js reconcile --apply
-```

package/modules/dev-box/CLAUDE.md

@@ -1,15 +0,0 @@
-# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
-
-This file is a placeholder shipped inside the **@bongos/core** package. The core's own
-internal agent notes are intentionally omitted from the published artifact so they cannot
-load into your instance's context.
-
-**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
-directory, and the live Bongos database are the source of truth for how work happens here
-and who may do what.
-
-You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
-Nothing in here needs to be read to use the platform — run `bongos help` for commands.
-
-_To work ON the platform core itself, use the standalone @bongos/core source repository,
-not this vendored copy._