@bongos/core 1.17.0

package/docs/recipes/cloudbongos-standup.md

@@ -0,0 +1,111 @@
+# Recipe — stand up cloudbongos.com (Customer 0, the vanilla dogfood instance)
+
+> Brings **cloudbongos.com** live as a real Cloud Bongos instance: the vanilla brand, its own database, no game code — Cloud Bongos running on Cloud Bongos (the C8 proof, [ADR 0062](../adr/<redacted>.md) §2, task [#1374](https://example.com/builders#/task/1374) + the proof ship [#1206](https://example.com/builders#/task/1206)). Owner-only inputs are tracked in blocker [#40](https://example.com/builders#/blocker/40).
+
+## Architecture (what we're building)
+
+Same droplet as OTB (`REDACTED_IP`), **separate process + separate database**, no new monthly cost. One checkout (`/home/lars/example`) runs **two** processes:
+
+| Instance | Entrypoint | Brand | Port | DB | Domain |
+|---|---|---|---|---|---|
+| OTB (game) | `server.js` | `config/branding.json` (default) | 3000 | `example` | example.com |
+| **Cloud Bongos** | `src/platform-server.js` | `config/branding.cloudbongos.json` (via `GDS_BRANDING_FILE`) | **3002** | **`cloudbongos`** | **cloudbongos.com** |
+
+The only difference between the two processes is **environment** — no divergent clone. The brand switch is `src/branding.js`'s `GDS_BRANDING_FILE` knob (task 1374). The landing page is served at the apex by `platform-server.js`; the Hall + status ride `builders.`/`status.` (host routing in `src/bongos/serve-internal.js`).
+
+## Phase ① — DNS  ✅ done
+
+Domain on Cloudflare (Free plan), nameservers switched, **SSL/TLS = Full (strict)**, three **proxied** A records → `REDACTED_IP`:
+`cloudbongos.com` (`@`), `builders`, `status`. (Until the origin cert + process are up, the site shows a TLS error — expected.)
+
+## Phase ② — GitHub OAuth App (builder sign-in)
+
+GitHub → Settings → Developer settings → **OAuth Apps** → **New OAuth App**:
+- **Application name:** `Cloud Bongos`
+- **Homepage URL:** `https://cloudbongos.com`
+- **Authorization callback URL:** `https://cloudbongos.com/api/gds/auth/web/callback` (PINNED — `auth.js` `WEB_REDIRECT_ORIGIN`; sign-in begun on `builders.` still calls back to the apex)
+- **Enable Device Flow:** ✅ (the CLI login uses it)
+
+Copy the **Client ID** + generate a **Client Secret** → they go in `/etc/cloudbongos/web.env` as `CLOUDBONGOS_GITHUB_CLIENT_ID` / `CLOUDBONGOS_GITHUB_CLIENT_SECRET` (resolved as `<ENVPREFIX>_GITHUB_*`; vanilla envPrefix = `CLOUDBONGOS`).
+
+## Phase ③ — Cloudflare Origin Certificate (own domain → own cert)
+
+cloudbongos.com is a different domain, so it needs its **own** Origin Cert (the example cert's SANs don't cover it). Cloudflare → **SSL/TLS → Origin Server → Create Certificate**:
+- Hostnames: `cloudbongos.com` **and** `*.cloudbongos.com`
+- Let Cloudflare generate the key; **copy both** the certificate and the private key.
+
+Install on the droplet (operator). **Caddy runs as user `caddy` and must be able to READ the key** — match the existing `origin.key` ownership (`640 root:caddy`). A root-only `600` key makes Caddy's reload fail and loop (the OTB site keeps serving the old config, but the new site never comes up — seen during the first bring-up). The `.crt` can be world-readable.
+```bash
+sudo install -m 644 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.crt   # paste cert, Ctrl-D
+sudo install -m 640 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.key   # paste key,  Ctrl-D
+```
+
+## Phase ④ — Droplet bring-up (operator)
+
+```bash
+# 1. The instance database (peer auth via the local socket, same as OTB)
+createdb cloudbongos
+
+# 2. GDS-only schema (skips migrations/game/*.sql — no game tables on this instance)
+cd /home/lars/example
+PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh
+
+# 3. Secrets file (from infra/cloudbongos.env.example)
+sudo mkdir -p /etc/cloudbongos
+sudo cp infra/cloudbongos.env.example /etc/cloudbongos/web.env
+sudo $EDITOR /etc/cloudbongos/web.env       # fill the OAuth client id + secret
+sudo chmod 600 /etc/cloudbongos/web.env && sudo chown lars:lars /etc/cloudbongos/web.env
+
+# 4. systemd service (from infra/cloudbongos.service)
+sudo cp infra/cloudbongos.service /etc/systemd/system/cloudbongos.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now cloudbongos
+curl -sS http://127.0.0.1:3002/healthz        # → "ok"
+
+# 5. Caddy — the three cloudbongos blocks are in infra/Caddyfile; apply + reload
+sudo cp infra/Caddyfile /etc/caddy/Caddyfile  # or merge the cloudbongos blocks in
+sudo systemctl reload caddy
+```
+
+## Phase ⑤ — Verify + first sign-in
+
+```bash
+curl -sS https://cloudbongos.com/healthz              # "ok" (through Cloudflare now)
+curl -sS https://cloudbongos.com/ | grep -o 'cloud bongos'   # the landing
+```
+- `https://cloudbongos.com` → the buddha landing.
+- `https://builders.cloudbongos.com` → the Hall. **Sign in with GitHub.** Because the pack sets `firstAdmin: "example-owner"`, that first sign-in auto-seats example-owner as **Owner/Archon** on the (empty) cloudbongos DB — no manual step (`auth.js` `maybeSeatFirstAdmin`).
+- `https://status.cloudbongos.com` → the dashboard.
+
+## Deploy automation (important — updated for the dedicated box)
+
+> **This changed with [ADR 0126](../adr/<redacted>.md).** cloudbongos.com no longer runs co-tenant on the OTB box. It runs on its **own dedicated droplet** (`REDACTED_IP`, checkout `/home/lars/cloudbongos`) and tracks `main` via a **pull-based `systemd` timer** — [ADR 0129](../adr/<redacted>.md), task [#2064](https://example.com/builders#/task/2064). The co-hosting box's CI deploy no longer touches it. (The historical "wire `sudo systemctl restart cloudbongos` into `~/deploy.sh`" note applied only while it was a co-tenant.)
+
+Once the box exists, the deploy is [`scripts/deploy/deploy-cloudbongos.sh`](../../scripts/deploy/deploy-cloudbongos.sh) fired by [`infra/cloudbongos-deploy.timer`](../../infra/cloudbongos-deploy.timer) every ~2 min: `git fetch` + reset `origin/main` → `npm ci` (if the lockfile changed) → `PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh` → `sudo systemctl restart cloudbongos` → 3002 healthz. After the first install it **self-heals** (each run refreshes `/home/lars/deploy.sh` + the units from the checkout).
+
+**One-time bootstrap** (operator, over SSH to the box — the box can't install its own first deploy automation). Run once the deploy files are on `main`:
+```bash
+# Executed as a STABLE copy outside the checkout (so `git reset --hard` can't
+# corrupt the running script — see ADR 0129):
+sudo -u lars install -m 0755 /home/lars/cloudbongos/scripts/deploy/deploy-cloudbongos.sh /home/lars/deploy.sh
+sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.service /etc/systemd/system/
+sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.timer   /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now cloudbongos-deploy.timer
+# Verify: one forced run brings the box current + smokes the chain
+sudo -u lars FORCE_DEPLOY=1 /home/lars/deploy.sh
+systemctl list-timers cloudbongos-deploy.timer --no-pager
+curl -sS https://cloudbongos.com/healthz     # → "ok"
+```
+
+## The C8 proof (task 1206) — ✅ DONE 2026-06-21
+
+With the instance live, **one real task** went through the full lifecycle **on cloudbongos.com** — claim → grade (the real 4-worker panel, PASS) → merge → ship, credits awarded — carrying zero game code: **cloudbongos task [#1](https://example.com/builders#/task/1)** (under version CB-V1), the `GDS_MODULES_FILE` fix that made Customer-0 advertise its modules correctly all-off. That shipped task is the C8 acceptance ("the GDS builds itself"). Full record + the operational mechanics for driving cloudbongos.com's GDS from the CLI: [2026-06-21 — C8 self-build proof](../session-logs/<redacted>.md). Closes task [#1206](https://example.com/builders#/task/1206).
+
+## Files this recipe uses
+
+- `config/branding.cloudbongos.json` — the customer-0 brand pack (deltas over `config/branding.neutral.json`).
+- `src/branding.js` — the `GDS_BRANDING_FILE` selector.
+- `src/platform-server.js` — GDS-only entrypoint + the apex landing mount.
+- `public-landing/index.html` — the landing page (mascot at `public-landing/buddha.png`).
+- `infra/cloudbongos.service`, `infra/cloudbongos.env.example`, `infra/Caddyfile` (the cloudbongos blocks).

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

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

package/docs/recipes/devbox-app-windows-test.md

@@ -0,0 +1,128 @@
+# Hardware-verifying the Dev Box app on Windows (Parallels runbook)
+
+The app's logic is covered by the stub self-test (`OTB_DEVBOX_AUTOFLOW`, see
+`devbox-app/README.md`), but four things only a real Windows session can
+prove: the UAC elevation write of the Claude Desktop connection file, the
+`icacls` SSH-key lock, native notifications + tray behavior, and the full
+switch-on → <redacted> → switch-off loop. This runbook walks a
+tester through all of them in ~20 minutes. Written for **Windows 11 in
+Parallels on an Apple-silicon Mac** (that's ARM64 Windows — use the ARM
+build); everything applies unchanged to a physical PC.
+
+## 0. Setup
+
+- Windows 11 VM up to date; **Claude Desktop for Windows** installed inside
+  the VM and signed in.
+- A GitHub account that's an approved builder (the test account
+  @largekristensen-svg is ideal — it has lived the broken flow).
+- Sign into the builders' hall once in the VM's browser (Edge/Chrome
+  *inside* Windows, not the Mac side): `https://builders.example.com`.
+- Parallels quirks that bite this test:
+  - Do the whole test **inside the VM** — if the pairing browser tab opens on
+    the macOS side you're testing the wrong machine's cookies.
+  - Windows "Do not disturb" / Focus suppresses toast notifications — turn it
+    off (Settings → System → Notifications) or step 5 can't be judged.
+  - The VM clock must be right (Parallels usually syncs it) — TLS and the
+    10-minute pairing TTL both care.
+
+## 1. Download + install (tests: branded redirect, SmartScreen path)
+
+1. In the VM browser: `https://example.com/downloads/devbox/win-arm64`
+   (Parallels = ARM64 Windows; on an Intel PC use `win-x64`).
+2. Expect the browser to warn about an uncommon download — keep it.
+3. Run the installer. **SmartScreen will interpose** (unsigned until blocker
+   [#18](https://example.com/builders#/task/18)'s Windows half): "Windows protected your PC" → **More info** → **Run
+   anyway**. ✅ Record that this matches the onboarding copy's wording.
+4. One-click install; the app launches itself and the panel window opens.
+   ✅ The tray (bottom-right, may be behind the ^ chevron) shows the
+   container icon.
+   - ARM64 check: Task Manager → Details → `OTB Dev Box.exe` → the
+     Architecture column should say **ARM64**, not x64-emulated (column may
+     need enabling via right-click on the headers).
+
+## 2. Pairing sign-in (tests: app-pair flow on Windows)
+
+1. Click **Sign in through the hall**. ✅ The default browser opens
+   `/builders/pair?code=XXXX-XXXX`; the code on the page matches the code in
+   the panel.
+2. Click **Approve — sign the app in as me**. ✅ Within ~5s the panel flips
+   to signed-in (the @login shows in the header) with no further input.
+3. ✅ A "Signed in" toast notification appears.
+4. ✅ `%USERPROFILE%\.config\otb\gds-session.json` now exists.
+
+## 3. SSH key + Claude Desktop connection file (tests: icacls, UAC write)
+
+Right after sign-in the app generates/registers the key and asks to install
+the Claude Desktop connection file:
+
+1. In PowerShell:
+   ```powershell
+   icacls $env:USERPROFILE\.ssh\otb_builder
+   ```
+   ✅ Exactly one ACE — your user with full control. **No** `BUILTIN\Users`
+   or `Everyone` lines (the 644-key bug the old flow shipped).
+2. ```powershell
+   Get-Content $env:USERPROFILE\.claude\settings.json
+   ```
+   ✅ Contains an `sshConfigs` entry `name` = "Example Dev Box",
+   `sshHost` = `root@box-<your-login>.dev.example.com`. Since v1.0.3
+   (#910) THIS per-user file is what makes the environment appear in the
+   picker — written with **no elevation**; "✓ Claude Desktop is linked"
+   refers to it.
+3. ✅ A **UAC prompt** may also appear once — that's the OPTIONAL hardening
+   layer (the system `managed-settings.json` host allowlist, written to both
+   `C:\Program Files\ClaudeCode\` and `C:\ProgramData\ClaudeCode\`).
+   Declining it does NOT break the link — the panel must still show
+   "✓ Claude Desktop is linked".
+
+## 4. The switch (tests: box lifecycle end-to-end)
+
+1. Flip the switch ON. ✅ Status walks `Raising thy box…` (a first-ever box
+   shows the one-time Archon-approval wait instead — the panel says so).
+2. ✅ Within ~3 min: status **ON**, host/size rows fill in, a "Your dev box
+   is ready" toast fires, the tray icon switches to the filled variant.
+3. ✅ **Open the browser terminal** works (ttyd page, user `otb`, password
+   from the panel's copy row).
+4. ✅ `Get-Content $env:USERPROFILE\.ssh\known_hosts` contains fresh
+   `box-<login>.dev.example.com` lines (the app replaces them each
+   activation — the Desktop ssh2 fix). Since v1.0.2 (#909) the panel shows
+   this live: "✓ Box identity pinned" (it retries by itself while the box's
+   SSH service boots; a stuck "not pinned yet" row has a **Retry now**
+   button). If it never pins, read the app log:
+   `Get-Content $env:APPDATA\otb-devbox-app\devbox.log -Tail 30`.
+
+## 5. Claude Desktop connect (the step the old flow could never reach)
+
+1. **Restart Claude Desktop** inside the VM (it reads managed-settings at
+   launch).
+2. Code tab → Environment picker. ✅ **"Example Dev Box"** is listed.
+3. Select it. ✅ It connects with **no host-verification error** (this is the
+   known_hosts fix paying off) and lands in `/workspace`.
+4. Ask Claude something trivial (`ls`) to prove the session is live.
+
+## 6. Switch off + idle behavior
+
+1. Flip the switch OFF. ✅ `Resting thy box…` → OFF within ~2 min; tray icon
+   back to outline; "Your dev box closed" toast.
+2. (Optional, 15 min) Flip ON, never connect, walk away. ✅ The box
+   self-reclaims (~10–15 min idle sweep) and the panel flips itself off with
+   the "closed after sitting idle" notification — the app deliberately sends
+   no keep-alive.
+3. Quit via tray right-click → Quit. Relaunch. ✅ Still signed in (no
+   re-pairing), state re-syncs.
+
+## Recording results
+
+File outcomes against the verification task in the GDS. For any failure
+grab: the panel state, `%TEMP%`/console output if launched from a terminal
+(`& "$env:LOCALAPPDATA\Programs\OTB Dev Box\OTB Dev Box.exe"` shows logs),
+the relevant PowerShell output from steps 3–4, and a screenshot. The fastest
+diagnosis channel is the box-side state: `GET /api/gds/box/me` via
+`node scripts/gds/api.js` from any authed checkout.
+
+## Known-unsigned caveats (until blocker #18 lands)
+
+SmartScreen "Run anyway" (step 1) and the unsigned-publisher UAC dialog
+(step 3) are EXPECTED today. When the Windows signing decision lands (Azure
+Trusted Signing vs EV cert), re-run steps 1 and 3 — both prompts should then
+name the verified publisher, and the SmartScreen interstitial disappears.

package/docs/recipes/failed-ship-recovery-proof.md

@@ -0,0 +1,102 @@
+# Failed-ship recovery proof (V4.R38)
+
+**Criterion:** `failed-ship-never-strands` — V4.R38, cross-refs V4.R03 + V4.R08.
+
+This document is the live transcript proof that both failure modes — working-tree-dirty preflight abort and grade fail — leave the task recoverable in ≤1 command, and that `claim_consumed_on_fail` does **not** fire.
+
+---
+
+## Setup
+
+A throwaway staging task ([task 1666](https://example.com/builders#/task/1666)) was created for this walkthrough. It held claim `#1397`, touches `docs/`, and had a single committed change (`docs/architecture.md +2 lines`).
+
+---
+
+## Failure mode 1 — working-tree-dirty (drift fail)
+
+The working tree was dirtied with an uncommitted tracked change before attempting ship:
+
+```
+$ echo "# draft" >> docs/architecture.md
+$ git status --short
+ M docs/architecture.md
+
+$ node scripts/gds/ship.js 1666 --no-surprise
+Verifying claim #1397 on task #1666: V4.R38 staging — throwaway proof task
+Preflight (working tree + branch freshness)...
+  preflight: working tree has uncommitted tracked changes:
+    - docs/architecture.md
+  Stage + commit these (or revert them) before shipping.
+Ship aborted: working-tree-dirty. No claim resolved, no credits awarded.
+```
+
+**Result:** task stayed at `active`, claim `#1397` **intact** — not consumed. Recovery: clean the working tree and re-run `ship.js 1666`. Zero extra steps; no re-claim needed.
+
+---
+
+## Failure mode 2 — grade fail (claim consumed, task stranded at `completed`)
+
+The preflight was cleared. Claim resolution was performed (simulating ship.js step 1) directly via the API to land the task at `completed` and consume the claim:
+
+```
+POST /api/gds/claims/1397/resolve   → taskStatus: "completed"
+```
+
+A failing grade was then POSTed (score 3/10, `passed: false`):
+
+```
+POST /api/gds/tasks/1666/grade  { passed: false, score: 3 }
+                                → taskStatus: "completed", creditsAwarded: 0
+```
+
+At this point: task at `completed`, claim `#1397` consumed, no active claim on 1666.
+
+**Active claims after grade fail:** `#1210, #974` — claim `#1397` is gone.
+
+### Recovery — the ≤1-command proof
+
+```
+$ node scripts/gds/ship.js 1666 --no-surprise
+Task #1666 is at 'completed' (grade stalled) and you last held the claim
+— resuming the grade (no re-claim needed).
+Re-grading task #1666: V4.R38 staging — throwaway proof task (ship after test)
+  eligibility: you last held this claim (owner)
+```
+
+`evaluateResumeAction` (V4.R03, task 941) detected `completed` + last-claim ownership and routed to `resume-grade`. **No "don't have an active claim" error.** `claim_consumed_on_fail` did **not** fire.
+
+The grader ran on the re-grade; it returned another failure (trivial diff, shot errored). The task stayed at `completed`. The builder's path forward remains the same: fix the work, commit, and run `ship.js 1666 --regrade` — still ≤1 command.
+
+---
+
+## V4.R08 — grade-record reuse (unit-test coverage)
+
+The `shouldReuseGrade` predicate (ship.js) and `applyGrade` diff-hash storage (lifecycle/db.js) are covered by 15 unit tests in [`tests/grade_diff_hash.mjs`](../../tests/grade_diff_hash.mjs):
+
+| Test | Branch covered |
+|---|---|
+| `diffHash` deterministic, hex, null-safe | pure hash helper |
+| `shouldReuseGrade` → true: PASS + matching hash | happy-path reuse |
+| `shouldReuseGrade` → false: FAIL + same hash | fail never reuses |
+| `shouldReuseGrade` → false: PASS + different hash | diff changed → re-grade |
+| `shouldReuseGrade` → false: null storedGrade, null hash, no diff_hash | edge cases |
+| `applyGrade` stores diff_hash as $10 | DB write |
+| `applyGrade` stores null when omitted | backward compat |
+| `getTaskGrade` exported | API contract |
+
+End-to-end reuse path (in production, when grader is live): `gradeAndRecord` calls `GET /tasks/:id?include=grade`, checks `shouldReuseGrade(stored, currentHash)`, and on a match re-POSTs the stored PASS result with `reused_from_diff_hash` in signals — skipping the adversarial panel entirely.
+
+> **Note:** The server-side `implausible_pass` guard (confirmed during this walkthrough) correctly rejects direct API attempts to forge a PASS grade, so end-to-end reuse can only be observed with a real grader PASS on an unchanged diff.
+
+---
+
+## Summary
+
+| Failure mode | Claim consumed? | Recovery | Command count |
+|---|---|---|---|
+| Working-tree-dirty (preflight abort) | **No** — ship aborted before resolve | Fix tree → `ship.js <id>` | 1 |
+| Grade fail (completed, claim gone) | Yes — at resolve step | `ship.js <id>` → auto-routes to `resume-grade` | 1 |
+
+`claim_consumed_on_fail` — the session evaluator's footgun detector (regex: `"don't have an active claim" / "no active claim" / "stays at completed"`) — did **not** fire in either case.
+
+Cross-references: V4.R03 ([task 941](https://example.com/builders#/task/941) — `evaluateResumeAction`), V4.R08 ([task 946](https://example.com/builders#/task/946) — diff fingerprint + grade reuse).

package/docs/recipes/figma-design-loop.md

@@ -0,0 +1,129 @@
+# Recipe: Figma round-trip loop
+
+> End-to-end guide for the repo ↔ Figma sync cycle — the human escape hatch in ADR 0081.
+> ADR: [ADR 0081](../adr/<redacted>.md).
+> Adapter: `src/ui/adapters/figma/index.js`.
+> CLI: `scripts/gds/figma-design-sync.js`.
+> Skill: `.claude/skills/figma-design-sync/SKILL.md`.
+>
+> Not to be confused with `otb-figma-sync` (pixel-art tile review, a separate Figma file, a separate concern).
+
+---
+
+## When to use this
+
+- A designer wants to make a manual edit to a UI surface directly in Figma (the "human escape hatch").
+- Tokens or surfaces changed and the Figma file is stale — push before the designer opens it.
+- A Figma edit is done (via Code Connect or a raw canvas change) and you want to land it as a GDS task.
+
+---
+
+## Prerequisites
+
+- **Rank: Metic+** for the handoff step (task authoring / commit under a claim).
+- **Claimed GDS task** — required when you `export()` and commit the generated code.
+- **Figma MCP write capability** in your session (`mcp__figma__*` write tools, or `use_figma`). Read-only tools alone are not enough to push. If unavailable, stop and surface the gap rather than faking the push — see `otb-figma-sync`'s own capability check for the same pattern.
+
+---
+
+## 1. Build the push plan
+
+```bash
+node scripts/gds/figma-design-sync.js
+```
+
+Output (JSON on stdout):
+
+```json
+{
+  "planPath": "/tmp/otb-figma-plan-XXXXX",
+  "files": ["figma-plan.json", "surfaces.json", "tokens.json"],
+  "surfaceIds": ["hall-ui", "status-ui"],
+  "summary": "plan → /tmp/otb-figma-plan-XXXXX · 2 surface(s) · frames: colors, typography, 2 surface ref(s)"
+}
+```
+
+**To scope to one surface:**
+```bash
+node scripts/gds/figma-design-sync.js --surface hall-ui
+```
+
+`figma-plan.json` describes the frames to create — a color-swatch frame, a typography-specimen frame, and one reference frame per surface (naming its current tool + source URL).
+
+---
+
+## 2. Push to Figma
+
+Confirm the target Figma file with the builder — this skill does not hard-code a file id (unlike `otb-figma-sync`, which is locked to the pixel-art tile file). Then use the live Figma MCP write tool to realize each `figma-plan.json` frame as real nodes: rectangles for swatches, text nodes for typography specimens.
+
+---
+
+## 3. A designer edits in Figma
+
+The designer opens the pushed frames (or an existing component) and makes a manual change.
+
+---
+
+## 4. Land the edit as a GDS task
+
+**a. Claim a GDS task** (if not already done).
+
+**b. Run the export step.** Figma hands back one of two shapes:
+
+**Code Connect output (ready code):**
+```js
+const adapter = require('./src/ui/adapters/figma/index.js');
+const result = await adapter.export({
+  repoRoot: process.cwd(),
+  surfaceId: 'hall-ui',
+  toolOutput: { files: [{ path: 'TaskCard.js', content: '...' }] },
+  taskId: '1234',
+});
+```
+
+**Raw Figma MCP node snapshot (no Code Connect mapping):**
+```js
+const result = await adapter.export({
+  repoRoot: process.cwd(),
+  surfaceId: 'hall-ui',
+  toolOutput: { snapshot: { nodes: [/* Figma node objects: id, name, type, absoluteBoundingBox, fills, children, characters */] } },
+  taskId: '1234',
+});
+```
+
+The adapter translates frames/text/solid-fill rectangles into `.js` + `.css` files, preferring a `--dt-color-*` token reference over a raw hex when the fill matches a known token. A node with an image or vector fill comes back in `result.warnings` telling you to export it as an asset under `assets/ui/<surfaceId>/` instead of code — never silently dropped, never forced into code it can't represent.
+
+**c. Commit + ship.**
+
+```bash
+git add src/ui/hall-ui/ config/design-sources.json
+git commit -m "ui(hall-ui): Figma export (task 1234)"
+node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+```
+
+---
+
+## Iterating
+
+- Re-run `node scripts/gds/figma-design-sync.js` + re-push whenever tokens change, so the designer never opens a stale file.
+- The `export()` call is **idempotent** — files with identical content are skipped.
+- `config/design-sources.json` tracks which surface was last synced, by which tool, and when.
+
+---
+
+## Code-canonical vs. Figma-canonical
+
+Code-canonical is the default: the repo is authoritative, the Figma file is a synced view. A surface may be flagged `"figmaCanonical": true` in its `config/design-sources.json` entry (docs/design-contract.md §3.4) as an explicit exception for a design-system foundation a dedicated designer actively iterates on in Figma. All other surfaces stay code-canonical.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `figma export: repoRoot is required` | Run from the repo root. |
+| `path-escape` error from `export()` | The Figma output named a path with `../` — reject it and re-check the surfaceId. |
+| Warning: "not code-representable" | Expected for icons/illustrations/freeform canvas art — export it as an asset under `assets/ui/<surfaceId>/` instead of forcing it into code. |
+| Warning: "no matching design token" | The designer used a color outside the token palette — either add it to `config/design-tokens.json` or accept the raw hex. |
+| Figma MCP write tool not available | Session-specific — stop and surface the gap rather than faking the sync (see `otb-figma-sync`'s capability check for the same pattern). |
+| Plan is stale after a token edit | Re-run `node scripts/gds/figma-design-sync.js` and re-push. |