@bongos/core 1.17.0

package/docs/adr/0046-sandbox-first-review-gate.md

@@ -0,0 +1,72 @@
+# ADR 0046 — Sandbox-first review in the dev-box ship flow
+
+**Date:** 2026-06-11
+**Context:** GDS-V3, task [#927](https://example.com/builders#/task/927). Builds directly on [ADR 0044](<redacted>.md) (the per-box live game preview / "sandbox") and the three-state ship lifecycle in `scripts/gds/ship.js` (Phase 5). Companion to [ADR 0031](<redacted>.md) (dev boxes) and [ADR 0016](<redacted>.md) (the gate is a workflow aid, not an authority surface).
+**Status:** Accepted.
+**Track:** `internal` (dev-system / builder experience).
+
+## Problem
+
+ADR 0044 gave every named-tunnel dev box a live sandbox (`sandbox-<login>.example.com`) serving the box's `/workspace` working tree — but nothing in the development flow *uses* it. A builder on a box can still run `/builder-ship` on a game change they have never seen running, and the pipeline carries it straight toward prod. The sandbox exists; the methodology doesn't ask for it. Lars's directive (2026-06-11): anytime a builder is on a dev box, they should **first stage their work on their sandbox to see it, have the opportunity to suggest changes, and only then decide to complete it and ship to the main game**.
+
+## Decision
+
+**Make staging-and-reviewing on the sandbox a first-class, enforced step of the dev-box ship flow.** Two pieces:
+
+### 1. `/builder-stage` — staging as a named verb (`scripts/gds/sandbox-stage.js`)
+
+Staging = restart `box-game-preview.service` so the sandbox serves the current `/workspace` working tree, health-check `127.0.0.1:3000`, and write a **staged marker** (`otb-sandbox-staged.json` in the OS temp dir) recording a SHA-256 stamp of exactly what was staged. The stamp is a **content hash scoped to the previewable game surfaces** (`git ls-files` + `git hash-object` over `public/`, `src/world/`, `src/rooms/`, `server.js`, tracked + untracked): editing a game file — committed or not — changes it, while editing docs/GDS files or merely `git add`/committing the *same* content does not. So "staged" can never silently mean "staged some older version of the game", and the natural stage → review → commit → ship flow keeps the marker fresh. The command prints the sandbox URL and tells the builder to review before shipping. Sub-commands: `status` (is the sandbox current?), `url`.
+
+### 2. The ship gate — `ship.js` checks the marker before the claim resolves
+
+`shipMain()` runs the gate after local verification (scanner + smoke + empty-diff guard) and **before** `POST /claims/:id/resolve` — i.e. before anything counts, so an abort leaves the claim active and the builder iterates freely. Decision table (pure `decideShipGate()`, unit-tested):
+
+| Condition | Action |
+|---|---|
+| `--skip-stage` | skip (escape hatch; not routine) |
+| not a dev box (no `/etc/otb/box.env`) | skip — laptop/operator sessions unchanged |
+| diff touches no previewable game surface | skip — the sandbox shows the game; GDS/doc/infra diffs have nothing to look at there |
+| box on the quick tunnel (no `BOX_PREVIEW_HOSTNAME`) | skip with notice — ADR 0044 already scopes the sandbox to named-tunnel boxes |
+| staged marker matches the current tree stamp | pass — already staged + reviewable; proceed |
+| stale/absent marker, **interactive TTY** | stage now, print the URL, ask: "Reviewed on the sandbox — ship this to the main game? [y/N]" — No aborts with the claim intact |
+| stale/absent marker, **non-interactive** | stage so the sandbox shows the work, then **abort with the claim intact and the review URL** — never hangs on stdin, never silently skips the review. This is the dominant path: a builder's Claude session runs `ship.js` through a non-TTY shell, so the agent relays the URL, the human reviews (and suggests changes), and the re-run passes on the now-fresh marker |
+
+"Previewable game surfaces" = `public/`, `src/world/`, `src/rooms/`, `server.js` — the paths the sandbox host actually renders (host-routing sends `sandbox-*` to the game). The check covers both the committed diff **and** uncommitted working-tree edits, since the sandbox serves the working tree.
+
+### Failure posture: the gate is a review aid, not a wall
+
+If staging itself fails (service won't start, health-check times out), the ship **warns loudly and continues**. The hard quality gates remain the scanner, smoke, and the grader panel; a broken preview service must not be able to brick shipping. Likewise the gate runs client-side in `ship.js` by design — it shapes the cooperative builder's workflow; it is not a trust boundary (ADR 0016: server-side rank checks and the grader are what enforce).
+
+## Alternatives considered
+
+- **Server-side enforcement (refuse `resolve` without a staged attestation).** Rejected: the server cannot verify what a builder's box showed them — the attestation would be client-claimed anyway, adding schema + API surface for no real guarantee. Workflow nudges belong client-side; trust stays where ADR 0016 put it.
+- **Gate inside `/builder-ship`'s skill prose only (no code).** Rejected: skills guide the agent but nothing re-checks; the point is that an un-staged game change *reliably* pauses for review.
+- **Always require review for every diff.** Rejected: the sandbox renders the game; staging a `docs/` or GDS change shows nothing and just adds a restart + prompt of pure friction.
+
+## Consequences
+
+- The dev-box loop becomes: edit → `/builder-stage` → review at `sandbox-<login>` → iterate → `/builder-ship` (gate passes on the fresh marker) → main game. A builder who skips straight to ship gets staged + paused once, in-line.
+- The non-interactive abort is deliberately bypassable by an immediate re-run (the first run staged, so the marker is fresh). That is acceptable: the gate is cooperative workflow shaping, and the agent in between is instructed to put the URL in front of the human. A truly autonomous box run that must not pause passes `--skip-stage` explicitly.
+- Laptop sessions (no box.env) are completely unaffected — including the operator's own ships and `/merge-mode`.
+- `--skip-stage` exists for genuine breakage; like `--skip-grade` it is an escape hatch, not a routine flag.
+- The marker lives in the box's temp dir — it is per-box, survives within a boot, and is naturally invalidated by edits (stamp mismatch). No DB schema, no new API surface, $0.
+
+## Amendment — 2026-06-13, task [#1048](https://example.com/builders#/task/1048): record the approval + position the link in chat
+
+Lars's directive (2026-06-13), after the gate shipped: (1) the sandbox link must be **positioned prominently in chat** when a change is ready to review, and (2) the builder's review-and-approve must be **recorded**, not left as an ephemeral marker. Both are now built; this amendment supersedes two specific stances above.
+
+- **Prominent in-chat link.** `runShipGate` now prints a delimited `🔍 REVIEW REQUIRED` block with the sandbox URL alone on its own line (both the dominant non-TTY `stage_abort` path and the TTY prompt), and the `/builder-ship` skill instructs the agent to surface that URL as a standalone, clickable callout in chat — never buried in command output. The "agent relays the URL" hand-off in the Decision table is unchanged in mechanism; only its presentation is now first-class.
+
+- **Recorded self-approval (supersedes "no DB schema, no new API surface").** The approval is now a durable fact. When the builder approves a staged game change — a TTY `y`, or an explicit `--approved` re-run on the non-TTY path — `ship.js` threads `{ stamp, url, method }` through the existing `POST /claims/:id/resolve` call (no new endpoint); the server stamps `by` + `at` authoritatively and persists the blob to a new `tasks.sandbox_review jsonb` column (migration 093). The original ADR argued *against* persisting the attestation because the server "cannot verify what a builder's box showed them." That reasoning still holds for *verification* — this record is an explicit, server-attributed **sign-off** ("builder X approved this exact game-surface stamp at time T"), which is a real and useful audit fact, not a claim that review happened. The scope is unchanged: **dev-box + named-tunnel + game-surface only, self-approval (no second approver), failure-open.**
+
+- **The `--approved` flag records a sign-off; it never bypasses review.** It is honored only when the current game state is already staged-fresh (`decideShipGate → 'pass'`) — i.e. a re-run after a prior stage. A stale/absent marker still stages and pauses, so there is nothing to "pre-approve." A bare fresh-marker re-run *without* `--approved` still ships (back-compat / failure-open) but records nothing and prints a nudge.
+
+- **Cost:** one nullable `jsonb` column + a field on an existing request body. Still no new endpoint; ~$0.
+
+## Amendment — 2026-06-14, task [#1056](https://example.com/builders#/task/1056): the gate (and [#1048](https://example.com/builders#/task/1048)'s link + recorded approval) now also cover LOCAL clones
+
+ADR 0044/0052 gave dev boxes a sandbox; the gate above and [#1048](https://example.com/builders#/task/1048)'s prominent link + recorded self-approval were written for that box path. Builders working on a full **local** clone (laptop) now get the identical loop — served privately at `http://localhost:<port>` (default 3100, `$OTB_PREVIEW_PORT` to override), **no Cloudflare tunnel, no public URL, $0** — via `scripts/gds/local-preview.js` (`npm run preview`) running the same ADR 0052 game-only entry (`src/preview-server.js`). Lars's directive (2026-06-14): "make the sandbox available for those also building locally" + "follow 1048 practice for the local sandbox as well."
+
+- **One resolver, two contexts.** `resolvePreviewContext()` in `sandbox-stage.js` returns a uniform `{ kind, url, healthUrl, restart }` — **box** (keyed by `/etc/otb/box.env`) or **local** (keyed by the presence of `src/preview-server.js`). The whole gate flows through it unchanged: `decideShipGate`'s `onBox` became `gateActive` (box OR local), `stage()` (re)starts the resolved preview, and [#1048](https://example.com/builders#/task/1048)'s `🔍 REVIEW REQUIRED` block + the `{ stamp, url, method }` recorded approval carry the **local** URL; the marker carries `kind:'local'`.
+- **Enforcement parity (supersedes "Laptop sessions … are completely unaffected").** A game-surface ship from a full local clone now stages + pauses for review exactly as on a box, and a TTY `y` / `--approved` re-run records the same durable self-approval. The `--skip-stage` escape hatch is unchanged. A **partial** clone with no game (`src/preview-server.js` absent) still has no sandbox and is unaffected, and **`/merge-mode` is still unaffected** (it lands `confirmed` tasks outside `shipMain`). This does mean the operator's own laptop game-surface ships are now gated too — consistent with "enforced like the box"; `--skip-stage` covers the exceptions.
+- **Cost:** $0 — localhost, no tunnel, no new server surface (reuses [#1048](https://example.com/builders#/task/1048)'s `tasks.sandbox_review` + resolve field).

package/docs/adr/0047-discord-bugs-intake-anti-abuse.md

@@ -0,0 +1,36 @@
+# ADR 0047 — Discord `#bugs` intake → GDS tasks, straight-through, with a layered anti-abuse guard
+
+- **Status:** Accepted
+- **Date:** 2026-06-12
+- **Task:** [#931](https://example.com/builders#/task/931)
+- **Extends:** [ADR 0033](<redacted>.md) (Discord bot service principal, the `#ideas` → `idea_inbox` inbound path), [ADR 0016](<redacted>.md) (trust boundary), [ADR 0034](<redacted>.md) (the rank ladder this leans on)
+
+## Context
+
+Builders wanted somewhere to drop a small fix they've spotted without context-switching into a full claim. The `#ideas` channel already exists (ADR 0033 §F6), but ideas land in `idea_inbox` and wait for human triage (`/idea-triage`) before becoming work. Lars's directive (2026-06-12): **bugs skip triage and become GDS tasks (`kind='bug'`) directly** — claimable work, straight through.
+
+That directive carries an embedded red-team question the task made a hard requirement: *if bug-filing creates tasks with no triage gate, how do we stop someone injecting nonsense / spam / malicious bugs into the queue?* The straight-through path and the abuse guard are the **same** task — neither ships without the other.
+
+## Decision
+
+A `#bugs` Discord channel (added to `docs/discord/channels.json`) whose messages the bot turns into GDS tasks (`kind='bug'`) via a new in-process module `src/bongos/discord-bugs.js`, structurally parallel to `discord-inbound.js` but routing to `db.createTask` instead of `inbox.captureIdea`. The intake is guarded **in depth**, all server-side, all fail-closed:
+
+1. **Linked-builder-only.** An *unlinked* Discord author cannot create a task — their message is ignored (logged, not filed). Unlike `#ideas` (which captures unattributed ideas), making *claimable work* requires being an accountable, known builder who has completed the GitHub→Discord OAuth link. This is the single biggest anti-abuse lever: no anonymous injection.
+2. **Rank-aware landing.** A linked **Metic+** builder's bug lands `status='ready'` — instantly claimable, the true straight-through path their trust earns. A linked **Xenos/Thetes** builder's bug lands `status='backlog'`, where a Metic+ promotes it (`POST /tasks/:id/promote`, the one-click confirm-to-ready already used by `/idea-triage`). The landing is decided server-side from the reporter's **live** rank, never from anything in the message. This mirrors the trust ladder used everywhere else in the GDS.
+3. **Per-builder rate-limit.** At most N bug-tasks per builder per rolling hour (default 5, `DISCORD_BUGS_RATE_PER_HOUR`), counted from `audit_log` (`db.countRecentDiscordBugFilings`). Over-limit filings are ignored **and audited** (`response_status=429`, `surface='discord_bot'`) so a spammer surfaces in forensics. The count fails *open* (the linked-builder + audit trail still hold a spammer accountable) so a transient DB hiccup never loses a real report.
+4. **Body screen.** Empty / too-short (< 8 chars) / text-free (no letters) messages are rejected before any DB write; title + body are capped to the GDS limits.
+
+Every filing is audited with `surface='discord_bot'` (`route='discord:bugs'`), so the existing `GET /audit?surface=discord_bot` forensic surface covers this path with no new endpoint.
+
+### Why rank-aware landing rather than always-ready or always-backlog
+
+- *Always-ready* honors "straight-through" most literally but puts a newcomer's (or a freshly-compromised account's) unreviewed text straight into the claimable queue.
+- *Always-backlog + confirm* is safest but isn't really "straight-through" — it's just lighter triage, which defeats the point for the trusted builders this feature is for.
+- *Rank-aware* gives trusted builders (Metic+) the genuine straight-through path while gating exactly the population the red-team question worries about (newcomers / low-trust), at zero extra ceremony for the people who earned trust. It reuses machinery that already exists (rank, `promote`), so it adds a decision function, not a subsystem.
+
+## Consequences
+
+- **Config / go-live:** inert until `DISCORD_BUGS_CHANNEL_ID` (env, or `bugs_channel_id` in `~/.config/otb/discord-bot.json`) is set **and** the bot is enabled (`DISCORD_BOT_ENABLED=true`) with the Message Content intent — exactly like `#ideas`. The channel itself is created/edited by the ADR 0037 channel reconciler from `channels.json`.
+- **Version:** filed bugs default to `DISCORD_BUGS_VERSION_ID` (default `GDS-V3`, the open internal version, since most builder-filed bugs are about the dev system). An Archon can re-home a game bug to a product version. Reward defaults to `DISCORD_BUGS_CREDITS` (10).
+- **Trust boundary intact (ADR 0016):** the bot asserts only *who* posted; the landing state is derived from the live GDS rank, never trusted from the message. The bot grants nothing.
+- **Deferred:** a dedicated abuse-flag widget on the `/watch` red-team view. The audit trail (`surface='discord_bot'`, the 429 rejections) already makes abuse queryable; a bespoke view is a follow-up if volume warrants it.

package/docs/adr/0048-works-in-progress-ia-split.md

@@ -0,0 +1,32 @@
+# ADR 0048 — "Works in Progress" information-architecture split: work board owns it, status mirrors a thin slice
+
+- **Status:** Accepted
+- **Date:** 2026-06-12
+- **Task:** [#938](https://example.com/builders#/task/938)
+- **Supersedes presentation choices in:** the versions render on `public-status/` (PMS-V2 [#41](https://example.com/builders#/task/41) done-when checklist; Phase 5 / [#94](https://example.com/builders#/task/94) three-segment bar)
+
+## Context
+
+Two surfaces independently rendered a "Works in Progress" section, both reading the same public `/api/gds/public/progress` feed:
+
+- **status.example.com** (`public-status/`) — a public, no-auth, off-box mirror (ADR 0029). It showed every version with name, track tag, a 3-segment lifecycle bar, a "% complete" line, and an expandable done-when criteria checklist.
+- **The builders' work board** (`public-builders/work.html`, `builders.example.com/work`) — sign-in-gated. Its "Works in Progress" section (`#wip-scroll`) was authored to be the source of truth (live in-flight claims + the same bars) **but the section carried a `hidden` attribute that no code ever removed**, so it never displayed — the page jumped straight to the claimable queue.
+
+Lars asked that the work board become the canonical home of Works in Progress, and that the public status page keep only a thin mirror: the **active** endeavours, **title + short description only** — "as we are saying it should stay there."
+
+## Decision
+
+1. **The work board is the canonical home.** Unhide `#wip-scroll`. It shows, for **every** version: title, short description, the 3-segment progress bar, and the done-when criteria checklist — plus the live "borne by hand right now" in-flight table. (Fixing the never-unhidden bug is part of this.)
+
+2. **The public status page is a thin mirror.** It shows only **active** endeavours, each as **title + short description**. No bars, no counts, no criteria. The now-dead version-bar and done-when CSS/JS on `public-status/` is removed.
+
+3. **"Active" = underway, not past, and actually started.** A version qualifies when `status NOT IN ('shipped','frozen')` **and** it has at least one `done_when_criteria` seeded (`criteria_count > 0`). The criteria-count test is what excludes a *future placeholder* — e.g. the next-version stub created at version close (GDS-V4 today), which has no criteria yet — without needing a new schema flag. When that version is scoped in a planning session and gains criteria, it appears on the public board automatically.
+
+4. **"Short description" reuses `versions.done_when`.** No new column. `done_when` is the senate-voice narrative of what a version *is*; the criteria checklist (a separate `done_when_criteria` table) is "their criteria." The two map cleanly onto "short description" and "criteria," so no data model change was needed. `db.versionProgress()` now also returns `done_when` and `criteria_count` (a `db.js`-only join — no migration).
+
+## Consequences
+
+- The public page no longer leaks per-version progress detail; it reads as a short, dignified list of what the city is building. Builders who want the full picture (bars, criteria, in-flight) go to the work board.
+- The two surfaces still cannot share rendering code: `public-status/` is copied byte-identical to the off-box GitHub Pages mirror (ADR 0029) and cannot import from `public-builders/`. They remain parallel implementations of a shared **data** contract (`/api/gds/public/progress` + `/versions/:id/done-when`).
+- A version with an empty `done_when` shows as a bare title on both surfaces. V2 and V3 had empty `done_when`; short descriptions were written for them as part of [#938](https://example.com/builders#/task/938).
+- The "future placeholder" rule is conventional, not enforced: a version is hidden from the public board precisely while it has zero criteria. This is the desired lifecycle (scope it → it shows), but it does mean seeding a single criterion makes a version public.

package/docs/adr/0049-split-parallel-safety-contract.md

@@ -0,0 +1,46 @@
+# ADR 0049 — The split parallel-safety contract (detect-at-merge for humans, gate for the autonomous runner)
+
+**Date:** 2026-06-13
+**Context:** GDS-V3, task [#881](https://example.com/builders#/task/881), step [6/8] of the `touches[]` simplification cluster ([#875](https://example.com/builders#/task/875)–[#883](https://example.com/builders#/task/883)). Records the parallel-safety model that the cluster's code changes established — see the architect audit [`docs/audits/<redacted>.md`](../audits/<redacted>.md). Supersedes the *predictive* framing implicit in [ADR 0010](0010-pms-architecture.md) (GDS architecture) and [ADR 0015](<redacted>.md); complements [ADR 0017](<redacted>.md) (the "a hard block turned correct work into deferred backlog" lesson).
+**Status:** Accepted.
+**Track:** `internal` (development system / methodology).
+
+## Problem
+
+For most of GDS's life, parallel-safety rested on a **prediction**: every task declared a `touches[]` file list up front, and a stack of machinery tried to prove — *before any code existed* — that two claims wouldn't collide. The audit found this stack was three disagreeing matchers across a claim-time 409, a ship-time drift scanner, and a CI gate, mis-documented as a "warning" when it actually withheld credits. It was the felt source of "slowed builders": code legitimately wanders into files nobody predicted, and a wrong prediction blocked or de-credited correct, mergeable work.
+
+The audit's adversarial review (multi-builder, autonomous-runner, merge-reality lenses) reached a split verdict, **not** a blanket "delete prediction, detect at merge." A blanket pivot was REFUTED by two lenses: the autonomous `--parallel` runner pushes to `main` with **no human to resolve a conflict**, and `git` is blind to *semantic* clobbers between two edits that don't textually overlap. So the honest contract is conditional on **who** is building.
+
+## Decision
+
+Parallel-safety is a **split contract**, keyed on the build path:
+
+### (a) Interactive, single-human path — detect at merge
+
+The ground-truth collision detector is **`git merge`** at land time (`/builder-ship`'s auto-merge and `/merge-mode`). A real overlap surfaces as a merge conflict, resolved by a human at the authoritative moment — *after* the code exists.
+
+- **Single-task atomicity** is guaranteed by the `uniq_active_claim_per_task` partial unique index (`migrations/003_pms.sql:130-131`): two sessions cannot both hold an active claim on the same task. This is the one hard invariant that always holds.
+- The **claim-time `touches[]` overlap signal is advisory** (task [#880](https://example.com/builders#/task/880)): on overlap, `claimTask` returns an `overlap_warning` and the claim **succeeds**. `touches[]` is an advisory hint at the expected blast radius — not an editing fence (the ADR 0017 lesson).
+- The predictive **drift scanner + CI gate + expand-on-drift flow were deleted** (task [#879](https://example.com/builders#/task/879), ~737 LOC). The subagent grader reads the **real committed diff** (touches-independent since [#536](https://example.com/builders#/task/536)) and flags genuinely out-of-scope writes there.
+
+### (b) Autonomous `--parallel N` path — keep a mechanical disjointness gate
+
+The overnight runner fans concurrent, unsupervised sub-agents and direct-pushes to `main`. Here a **file-footprint disjointness precondition is retained as a HARD gate**, alongside `parallel_safe = true`:
+
+- `claim.js --enforce-touches` (which the `overnight-builder` routine always passes) sets `enforce_touches`, so `claimTask` / `claimTasksBatch` **refuse** with `TOUCHES_CONFLICT` on prefix-aware overlap rather than merely warning.
+- **`parallel_safe` and footprint-disjointness are orthogonal and both required.** `parallel_safe` covers *non-file* hazards the runner can't see in a diff — a server restart, a shared mutable DB row, a long deploy. Footprint-disjointness covers file adjacency. Neither subsumes the other; the runner needs both true.
+
+### Shared mechanics
+
+- One **prefix-aware matcher** (`src/bongos/path-match.touchesOverlap`) is the single definition of "adjacent" across `claimTask`, `claimTasksBatch`, and the session optimizer — so the planner, the advisory warning, and the parallel gate all agree.
+- The `claimable_tasks` **view stays on the permissive Postgres `&&` (exact-element) operator** by design: making the *display* filter prefix-strict would over-serialize the visible queue given V3's coarse top-level-dir `touches[]`. The view is a soft hint; the authoritative prefix-aware check lives in code.
+
+## Consequences
+
+- **Interactive builders are never blocked by a prediction.** They may be warned; they decide. Wrong predictions cost nothing.
+- **The autonomous runner stays safe** — it still refuses to fan two same-footprint tasks into concurrent agents.
+- The asymmetry is deliberate and must be preserved: do not "simplify" the autonomous path down to advisory, and do not promote the interactive path back to a hard block.
+
+## The future-review trigger (deferred, conditional)
+
+The full removal of the footprint gate — replacing it with **merge-time auto-park detection** (a `confirmed→shipped` `git merge` conflict auto-parks the task with a "rebase against main" note) **plus a runner-side post-fan-out footprint diff check** — was deliberately **deferred**. Revisit it **only when 2+ distinct human builders regularly edit concurrently** (today there is one human builder running many sessions under one identity — see the `feedback_parallel_sessions_not_anomaly` memory). At that point: either stand up the merge-time-detection + runner-footprint-check pair and drop the advisory column entirely, or keep the matcher-fixed advisory. Until then, the advisory signal + `parallel_safe` + the `uniq_active_claim_per_task` index are sufficient. Zero occurrences of the protected concurrent-human-edit scenario are documented at current scale.

package/docs/adr/0050-device-flow-admission-invite-gated-by-default.md

@@ -0,0 +1,43 @@
+# ADR 0050 — Device-Flow admission posture: invite-gated by default
+
+**Date:** 2026-06-13
+**Context:** GDS, security report SR-19 / task [#1000](https://example.com/builders#/task/1000). Closes an admission inconsistency between the two GitHub enrollment paths in `src/bongos/auth.js`. Extends the web-sign-in approval gate added 2026-05-30 (the `access_requests` `'invited'` model) and is governed by the trust-boundary rule in [ADR 0016](<redacted>.md) (the server enforces admission, not the client).
+**Status:** Accepted.
+**Track:** `internal` (development system / builder onboarding + access control).
+
+## Problem (SR-19)
+
+The two ways a GitHub account becomes a builder were gated **inconsistently**:
+
+- **`completeWebFlow`** (the web hall sign-in, `/api/gds/auth/web/callback`) refused a **first-time** GitHub account unless an Archon had marked their `access_requests` row `'invited'`. Established builders (a `builders` row already exists for their `github_id`) always passed.
+- **`pollDeviceFlow`** (the CLI `/builder-setup` device flow, `/api/gds/auth/device/poll`) called `upsertBuilder()` **unconditionally** the moment GitHub returned an access token. So **any GitHub account could self-enroll as a Xenos and mint a never-expiring CLI session with no Archon approval whatsoever** — simply by running `/builder-setup` and authorizing on github.com.
+
+This directly contradicted the documented posture that **Archon admission is the only gate** for new builders (CLAUDE.md / [ADR 0016](<redacted>.md) / [ADR 0035](<redacted>.md)). The web door was locked; the CLI door was wide open. The blast radius is bounded by the Xenos sandbox (a self-enrolled account lands at the lowest rank, can only claim `xenos_claimable` tasks, and is kept out of the permission/methodology core), but it is still an unauthorized foothold inside the trust boundary and an inconsistency an auditor will (and did) flag.
+
+## Decision
+
+**Make both enrollment paths consistent: invite-gated by default, with an env escape-hatch.**
+
+1. `pollDeviceFlow` now applies the **same gate** `completeWebFlow` applies, before `upsertBuilder`:
+   - Look up `getBuilderByGithubId(ghUser.id)`.
+   - If **no** existing builder row AND open enrollment is off AND the login has **no** `'invited'` access request → throw the same `NOT_APPROVED` error the web flow throws.
+   - **An existing builder ALWAYS passes.** The gate only blocks genuine first-time entries, so an already-approved builder can never be locked out of CLI re-enrollment (e.g. re-auth on a new box). This early-pass is the load-bearing invariant.
+
+2. Both paths share one **pure decision helper**, `firstTimeAdmissionBlocked({ existing, approved })`, so the web and CLI gates **cannot drift** out of sync the way they just did.
+
+3. **Escape-hatch:** `openEnrollmentEnabled()` reads the environment flag **`OTB_OPEN_XENOS_ENROLLMENT`** (truthy = `'1'` or `'true'`). When set, the invite gate is skipped in **both** paths and any GitHub account self-enrolls as a Xenos again — restoring the old fully-open behavior **without a code change or redeploy**, for an owner who deliberately wants open enrollment. **Default (unset) = invite required.**
+
+4. The CLI surfaces the refusal gracefully: the `device/poll` route returns a structured `403 { state: 'not_approved' }` (mirroring the web flow's `NOT_APPROVED` branch), and `scripts/gds/setup.js` prints a friendly "this account hasn't been approved yet — ask an Archon to invite you, then re-run `/builder-setup`" message instead of a raw error dump.
+
+## Alternatives considered
+
+- **Formally accept open Xenos enrollment** (document the device flow as intentionally open, relying on the Xenos sandbox to contain the risk). Rejected as the *default*: it contradicts the stated "Archon admission is the only gate" posture and leaves an un-audited self-enrollment door, even if low-privilege. It remains available **on demand** via `OTB_OPEN_XENOS_ENROLLMENT=1` — so this ADR doesn't foreclose it, it just makes "secure" the default and "open" the explicit, reversible owner choice.
+- **A repo-collaborator / GitHub-org check** as the gate. Rejected: newcomers build on hosted dev boxes with no repo access, so there is deliberately no collaborator check anywhere (2026-06-07). The `access_requests` `'invited'` model is the established admission signal; reusing it keeps one gate, not two.
+- **Gate inside `upsertBuilder`** (a DB-layer guard). Rejected: `upsertBuilder` is also the update path for existing builders and is called from non-admission contexts; pushing an admission policy into it would conflate "create a record" with "admit a person." The gate belongs at the two flow entry points, sharing one pure helper.
+
+## Consequences
+
+- **Secure by default:** a fresh GitHub account can no longer self-enroll via `/builder-setup` — it needs an Archon invite, exactly like the web hall.
+- **No existing builder is locked out:** the existing-row early-pass guarantees re-auth/re-enroll keeps working for anyone already admitted.
+- **Reversible without a deploy:** an owner who wants open enrollment flips `OTB_OPEN_XENOS_ENROLLMENT=1` in the systemd `EnvironmentFile` and restarts the process.
+- **No drift:** the shared `firstTimeAdmissionBlocked()` helper means a future change to admission policy lands in one place for both doors.

package/docs/adr/0051-full-session-transcript-corpus.md

@@ -0,0 +1,57 @@
+# ADR 0051 — Full session transcripts in the BFG corpus (with transcript-grade scrubbing)
+
+**Date:** 2026-06-13
+**Context:** GDS-V4, task [#1004](https://example.com/builders#/task/1004) (full-transcript capture) with hard precondition task [#1003](https://example.com/builders#/task/1003) (transcript-grade scrubber, extends [#723](https://example.com/builders#/task/723)) and coverage task [#965](https://example.com/builders#/task/965). **Amends the privacy/size posture of [ADR 0027](<redacted>.md)** (BFG session-inefficiency evaluator) and its schema (`migrations/062_session_records.sql`). Companion to [ADR 0026](<redacted>.md) (BFG charter + §6C transparency), [ADR 0020](<redacted>.md) (security-model posture), [ADR 0028](<redacted>.md), and [ADR 0016](<redacted>.md) (read access is server-enforced, not a doc claim). Read API: tasks [#541](https://example.com/builders#/task/541)/[#627](https://example.com/builders#/task/627). Coverage history: [#551](https://example.com/builders#/task/551)/[#608](https://example.com/builders#/task/608)/[#617](https://example.com/builders#/task/617)/[#620](https://example.com/builders#/task/620).
+**Status:** Proposed. Directive accepted (Lars, 2026-06-13); the **mechanism awaits review, and capture MUST NOT ship until the scrubber precondition (task 1003) is verified.**
+**Track:** `internal` (dev-system / BFG).
+
+## Problem
+
+[ADR 0027](<redacted>.md) made a deliberate choice, stated in `migrations/062_session_records.sql`:
+
+> *"the heavy transcript CONTENT is never uploaded. Each row holds per-turn METADATA (role, tool name, error flag, token usage, content length) + short secret-scrubbed snippets + token aggregates. That keeps rows small (KB, not MB) and the secret surface minimal."*
+
+That was the right call for an *efficiency metrics* evaluator. But it has a cost that surfaced concretely on 2026-06-13 while investigating why builder `IAMMASTERQUA` (id 25, Thetes) could not use the sandbox: pulling their 8 sessions from the corpus, the **assistant turns came back near-empty**. The corpus can compute ceremony-vs-work ratios and tool-error counts, but **neither the BFG nor an Archon can read what actually happened** — what the builder asked, what guidance they were given, where they hit a dead-end. The digest measures sessions; it cannot be *read*.
+
+Lars's directive (2026-06-13): **the BFG must hold the full transcript of every session, readable — with secrets still scrubbed (non-negotiable).**
+
+## Decision
+
+**Store the full, secret-scrubbed transcript of every session in the corpus, and reaffirm that read access is Archon/BFG-only + audited.** Four parts:
+
+### 1. Full per-turn content (replaces the thin snippet model)
+Capture the complete per-turn transcript — user prompts, assistant text, tool calls **and** their results — instead of length-bounded snippets. Stored as scrubbed text on each turn in `session_records` (new `transcript jsonb` column, or a widened `detail`; migration **085** reserved on claim 762). The per-turn *metadata* and `metrics` aggregates ADR 0027 relies on are kept — the evaluator logic is unchanged; only the stored fidelity grows.
+
+### 2. Every session, no silent gaps
+Coverage is already most of the way there: the `SessionEnd` hook (`scripts/gds/session-digest.js`) fires once per session end (not just on ship) and upserts **one record per `session_id`**, and `ship.js` covers the mid-session tail. This ADR keeps that invariant and pairs it with the coverage-reconciliation work (task 965) + the durable skip-logging (task 617) so a session that fails to upload is *visible*, never silently absent.
+
+### 3. Hard precondition — transcript-grade scrubbing (task 1003)
+Because the heavy content now leaves the box, the scrubber becomes load-bearing. Extend the secret-scrub in `scripts/gds/ship.js` + `scripts/gds/session-digest.js` (completing the still-open token-redaction task 723) to aggressively redact: API keys, GDS / Anthropic / Apple tokens, the contents of `~/.config/otb/gds-session.json` and `env`, `Authorization` headers, private keys, and high-entropy strings. **Scrubbing runs on the builder's box, before anything is uploaded.** A planted-secret test corpus must be caught in full before capture ships. **This task gates task 1004.**
+
+### 4. Access + retention posture (reaffirmed and bounded)
+- **Read access unchanged and reaffirmed:** full transcripts are sensitive. A builder may read their **own** sessions; any cross-builder read stays **Archon / BFG-principal only and fail-closed audited** (`/sessions/:id`, `/sessions/search` — the audit row is written *before* the query runs). This is server-enforced (ADR 0016), not a doc promise.
+- **Retention — keep forever** (Lars, 2026-06-13: *"keep forever; we will optimize storage costs in the future"*). Full content is retained indefinitely in the central corpus; rows grow from KB to MB and the nightly `pg_dump` (task [#412](https://example.com/builders#/task/412)) grows with them. Storage-cost optimization (compression, cold-tiering, or off-DB object storage) is an explicit **future** concern, filed for later — not designed in now.
+- **Server-side system of record, never on the boxes** (Lars, 2026-06-13: *"keep these on our server not on every dev box"*). The authoritative corpus is `session_records` in the central Postgres on the droplet. Dev boxes do **not** store, accumulate, or sync transcripts — a box scrubs its session at source and uploads it, holding only Claude Code's own transient local `.jsonl` (which we neither persist nor replicate across boxes). The home of record is single, and the standing secret surface on any individual box stays minimal.
+- **Transparency:** builders should know their full sessions are retained server-side for BFG. Surface it in the primer / per ADR 0026 §6C's transparent-correction posture.
+
+## The security trade-off (stated plainly)
+
+This **reverses ADR 0027's central safety margin** ("content never uploaded"). The replacement safety model is three-layered: content is (a) **aggressively scrubbed at the source** before it leaves the box, (b) **access-gated** to Archon/BFG + audited, and (c) **centralized on the server**, never spread across dev boxes. Note this model deliberately does *not* lean on retention bounding — Lars chose to keep transcripts forever — so (a) the source scrub and (b) the access gate carry the full weight. The residual risk is real and acknowledged: a scrubber miss now leaks actual content rather than a short snippet, and it leaks it permanently — which is exactly why task 1003 (scrubber + planted-secret test) is sequenced **first** and is a hard gate on task 1004. The forever-corpus also becomes a higher-value target; the existing nightly backup and any future restore drill inherit that sensitivity.
+
+## Consequences
+
+- **Pros:** the BFG (and an Archon) can finally *read* sessions — root-causing builder friction like the IAMMASTERQUA sandbox dead-end becomes possible; "honest measurement" (a GDS-V4 goal) gets the raw material it was missing.
+- **Cons / risks:** an ever-growing DB + backups (forever retention); a bigger, *permanent* secret-exposure surface if scrubbing regresses; full records of builders' work stored centrally (mitigated by scrub-at-source, audited gating, server-side centralization, and transparency — but explicitly **not** by retention limits).
+- **Supersedes** the ADR 0027 / migration 062 *storage* note only. ADR 0027's evaluator design and read-gating posture stand.
+
+## Alternatives considered
+
+- **Fuller snippets, not full transcripts** — smaller blast radius, but does not satisfy the directive (assistant reasoning/answers still truncated).
+- **Full transcripts, unscrubbed** — rejected outright: violates the non-negotiable secret constraint and our security posture.
+- **Store transcripts off-DB (object storage), pointer in the row** — keeps rows small and isolates the blast radius; deferred as a future option since it would fork the existing one-record-per-session read API. Revisit if DB size becomes the binding constraint.
+
+## Decisions recorded (Lars, 2026-06-13)
+
+- **Retention: keep forever.** Full transcript content is never aged out; storage-cost optimization is deferred to a future task, not built now.
+- **Storage location: central server only.** The corpus lives in the droplet's Postgres (`session_records`); dev boxes never accumulate or sync transcripts (see Decision §4).
+- **Consequence for sequencing:** with no retention bound to limit exposure, the source-scrub (task 1003) and the audited access gate are the *only* safety layers. Task 1003 is therefore a hard, non-skippable precondition for task 1004, and its planted-secret test must pass before any capture code ships.

package/docs/adr/0052-sandbox-for-everyone-game-only-preview.md

@@ -0,0 +1,70 @@
+# ADR 0052 — Sandbox for everyone: a game-only preview entrypoint + the game in the starter clone
+
+**Date:** 2026-06-13
+**Context:** GDS-V3, task [#1001](https://example.com/builders#/task/1001) (clone-scope + ungate) and task [#1002](https://example.com/builders#/task/1002) (hardware-verify). Builds on [ADR 0044](<redacted>.md) (the per-box live game preview / "sandbox") and [ADR 0031](<redacted>.md) (cloud dev boxes + rank-scoped source). Companion to [ADR 0046](<redacted>.md) (sandbox-first review) and [ADR 0016](<redacted>.md) (authority is server-enforced — source visibility grants nothing). **Reverses the full-clone gate from task [#903](https://example.com/builders#/task/903).** Decision by Lars, 2026-06-13.
+**Status:** Accepted. Mechanism implemented under task [#1001](https://example.com/builders#/task/1001) (game-only entry `src/preview-server.js` + shared `registerGameRooms()` helper, `STARTER_SPARSE_PATHS` widened by `src/world`/`src/rooms`/`public`, `box-game-preview.service` repointed at the game-only entry, `box-source-fetch.sh` ungated); **hardware-verified under task [#1002](https://example.com/builders#/task/1002) (2026-06-14)** — a fresh **Xenos starter-scope** box (`LarsCode`) served the playable game over the public tunnel at `sandbox-<login>.example.com` (HTTP 200, Phaser client + `/game/*` assets) while **(b)** `/api/gds/*` returned 404 through that host (game-only entry does not mount the internal API) and **(c)** `migrations/` was absent on the box (the game paths `src/world`/`src/rooms`/`public` were present). Box deprovisioned after the run.
+**Track:** `internal` (dev boxes / builder experience).
+
+## Problem
+
+ADR 0044's sandbox (`sandbox-<login>.example.com`) only works on a Metic+ **full-clone** box. A starter (Xenos/Thetes) box can't serve it, for two reasons found in the code:
+
+1. **The game isn't on the box.** `STARTER_SPARSE_PATHS` in `src/bongos/box-access.js` deliberately *excludes* the game — `src/world`, `src/rooms`, and the `public/` client are the "crown jewels" it protects.
+2. **`server.js` can't boot game-only.** `server.js` top-level-requires `./src/bongos/routes` and `./src/rooms/*` and mounts `/api/gds` — so `box-game-preview.service` (which runs `node /workspace/server.js`) cannot start without the full internal stack present.
+
+Task 903 therefore gated the preview on full-clone source. The concrete symptom (2026-06-13): builder `IAMMASTERQUA` (Thetes) — `curl localhost:3000` and the sandbox come up empty, with no explanation. Lars's directive: **the sandbox must work for all ranks.**
+
+## The finding that shaped the design
+
+Investigating the clone scope flipped our initial framing. A starter box **already carries the build tooling** — `scripts/`, `.claude/`, `src/bongos` (the GDS lib + API client; no secrets), `infra/`, `docs/`, `art/` — by deliberate choice (a 2026-06-07 note in `box-access.js`: *"usability wins so newcomers can actually interface with the builder skills"*; they need that tooling to run `/builder-*` at all). What a newcomer box lacks is the **game**. And per ADR 0016 authority is server-enforced, so reading source grants no privilege.
+
+So the privacy boundary that actually matters for a **public** per-box URL is **runtime, not source**: `server.js` also serves `/api/gds`, and the sandbox tunnel points at the whole server — so today `sandbox-<login>.../api/gds/*` is reachable (degraded) on full boxes. Lars's decision (2026-06-13): **runtime-only gating** — add the game everywhere, serve the sandbox game-only, and leave the existing source posture as-is (source-tightening, idea [#213](https://example.com/builders#/idea/213), stays deferred).
+
+## Decision
+
+Make the sandbox available on every box via two changes, keeping the source posture unchanged.
+
+### 1. Game in the starter clone
+Add the product/game paths the preview needs — `src/world`, `src/rooms`, `public/` — to `STARTER_SPARSE_PATHS` (`src/bongos/box-access.js`). `migrations/` stays excluded (DB schema; a degraded-DB preview doesn't need it). Every box can now materialize the game.
+
+### 2. A game-only preview entrypoint (the heart of "keep internals private")
+Add a dedicated, minimal game-only server entry (e.g. `src/preview-server.js`) that serves **only**:
+- `express.static(public/)` — the game client, and
+- the **game** Colyseus rooms (`WorldRoom` + `QueueRoom`) over the WS transport, plus
+- the minimal **game** HTTP endpoints the client needs to bootstrap (identity/queue/world — the implementer ports these from `server.js`'s non-`/api/gds`, non-`/builders` wiring).
+
+It explicitly does **not** mount `/api/gds`, the `BuildersHallRoom`, the Discord bot, the uptime poller, or the status-host routing. `box-game-preview.service` runs **this** entry instead of `server.js`. To avoid the two entrypoints drifting on the room list, factor the game-room registration into a shared `registerGameRooms(gameServer)` helper that both `server.js` and the preview entry call.
+
+Consequences of this split:
+- A box never needs to boot the full stack to show the game; the game-only entry has no `src/bongos` dependency, so the public sandbox never serves the internal API even though `src/bongos` is present on the box.
+- It **closes the current runtime exposure** where `sandbox-<login>.../api/gds/*` is reachable on full boxes — a net security improvement.
+- `server.js` (the prod, full-stack entry) is left untouched — no rank-conditional behavior bolted onto the sensitive shared file.
+
+### 3. Ungate the preview (reverse task 903)
+`infra/box-source-fetch.sh` enables `box-game-preview.service` on **every** box, not only full-clone ones, now that the game paths are in the starter clone and the game-only entry boots without `src/bongos`.
+
+## Why game-only entrypoint over a conditional mount
+
+The alternative was to make `server.js` lazily/conditionally mount `/api/gds` (guard the `require`, skip on a box). **Rejected:** `server.js` is sensitive shared infra; adding rank-conditional runtime behavior there is the riskier path — a wrong guard mounts the internal API on a public per-box URL — and it ships `server.js`'s full wiring to every box. A separate, minimal, auditable game-only entry has a tiny fixed surface that *cannot* expose `/api/gds`. The only cost — keeping two game-room registrations in sync — is neutralized by the shared `registerGameRooms()` helper.
+
+## Security posture
+
+- **Source unchanged.** Newcomers keep the tooling source they already have, plus the game. The game client already ships to every browser; the game server (`src/world`/`src/rooms`) is product code, not permission/secret code. Authority stays server-enforced (ADR 0016) — a starter box reading game source gains nothing.
+- **Runtime tightened.** The public sandbox serves game-only on every box; `/api/gds` and the BuildersHall are no longer reachable via `sandbox-<login>`. This is strictly safer than today.
+- **Degraded-DB unchanged** (ADR 0044): no Postgres on the box; the game-only entry runs DB-less exactly as the preview does today.
+
+## Consequences
+
+- Every builder, any rank, gets a working live sandbox — fixes the `IAMMASTERQUA` dead-end and lets newcomers actually see their work.
+- New small artifact (the game-only entry) + a shared room-registration helper to prevent drift; `box-game-preview.service` `ExecStart` changes; `STARTER_SPARSE_PATHS` widens by three game paths; task 903's gate is removed.
+- **Verification (task 1002):** provision a real starter-scope (Xenos/Thetes) box and confirm (a) `sandbox-<login>` serves the playable game, (b) `sandbox-<login>.../api/gds/*` is **not** reachable, and (c) `migrations/` (and anything else still gated) is absent on the box.
+
+## Alternatives considered
+
+- **Conditional `/api/gds` mount in `server.js`** — rejected (above): riskier on a sensitive shared file.
+- **Prebuilt game artifact, no source** — rejected per Lars's "just the game" choice; also breaks edit-then-preview.
+- **Full clone for every box** — rejected: pulls `migrations/` and everything with no benefit; source-privacy is moot given server-enforced authority, so there's no reason to widen beyond the game.
+
+## Follow-up (out of scope here)
+
+Finer-grained source tightening — removing `scripts`/`.claude`/`src/bongos` from newcomer boxes (idea [#213](https://example.com/builders#/idea/213)) — remains deferred. Lars chose runtime-only gating for this change; tightening source would require a separate tooling-delivery design so newcomers can still run `/builder-*`.

package/docs/adr/0053-scoped-dev-box-session.md

@@ -0,0 +1,55 @@
+# ADR 0053 — Scoped, short-lived dev-box session + apex-cookie strip at the tunnel
+
+**Date:** 2026-06-13
+**Context:** GDS, security reports SR[#2](https://example.com/builders#/task/2) (HIGH) + SR[#11](https://example.com/builders#/task/11) (HIGH) from the 2026-06-08 server audit ([#870](https://example.com/builders#/task/870)); task [#919](https://example.com/builders#/task/919). Owner decision 2026-06-09: do the proper redesign, not the interim named-tunnel disable. Governed by the trust-boundary rule in [ADR 0016](<redacted>.md) and the box subsystem in [ADR 0031](<redacted>.md) / [ADR 0038](<redacted>.md) / [ADR 0044](<redacted>.md).
+**Status:** Accepted.
+**Track:** `internal` (development system / builder dev boxes + access control).
+
+## Problem
+
+A dev box is **outside** the ADR 0016 trust boundary — the GDS authenticates against the box, never the reverse. Two channels nonetheless put a builder's **full-authority** GDS bearer onto the box:
+
+- **SR[#2](https://example.com/builders#/task/2) — baked full token.** `scripts/gds/box.js` mints a session and bakes it into cloud-init → `/root/.config/otb/gds-session.json`, so `box-source-fetch` can clone the rank-scoped repo on first boot (the [#818](https://example.com/builders#/task/818) chicken-and-egg: `/builder-setup` lives in the un-cloned repo). That session was `source='cli'`, and `source` was **purely informational** — `auth.requireBuilder` had no scope concept, so the baked token could claim/grade/ship and hit every `requireBuilder` route at the builder's live rank. Any on-box process, or the `169.254.169.254` metadata endpoint, could read it and act as the full builder.
+- **SR[#11](https://example.com/builders#/task/11) — apex cookie rides the tunnel.** The hall session cookie is `gds_session; Domain=.example.com` (apex-scoped so [#726](https://example.com/builders#/task/726) SSO works across `builders.example.com`). The browser therefore sends it to `term-<login>.example.com` (ttyd) and `sandbox-<login>.example.com` (game preview) — both fronted by the box. The builder's full hall bearer rides the tunnel onto the less-trusted box.
+
+## Decision
+
+**Two independent defenses; the box never holds, and never receives, a full-authority credential.**
+
+### 1. A third session source, `'box'`, that is deny-by-default (fixes SR[#2](https://example.com/builders#/task/2))
+
+- `box.js` mints the baked session as **`source='box'`** (migration 090 widens the `builder_sessions.source` CHECK to `('cli','web','box')` and retroactively flips already-baked `user_agent='box-provision'` rows in place).
+- `auth.requireBuilder` **rejects a `source='box'` session on every route** (`403 box_scope`) **except** the handful the on-box crons need, which opt in via a one-line `auth.allowBoxScope` middleware mounted ahead of `requireBuilder`. The allow-list IS the complete box surface:
+
+  | Route | On-box caller |
+  |---|---|
+  | `GET /box/source-access` | `box-source-fetch.sh` (cron */10) |
+  | `GET /box/authorized-keys` | `<redacted>.sh` (cron */10) |
+  | `POST /box/heartbeat` | `box-heartbeat.sh` (cron */5) |
+  | `POST /box/terminal` | `box-report-terminal.sh` (quick-tunnel credsync) |
+
+- **Fail closed:** a route *without* `allowBoxScope` denies a box session — so any route added later is automatically out of reach of a box token. No path-prefix matching (which drifts); the gate keys on an explicit per-route flag.
+- A builder who wants to do real work **from** the box runs `/builder-reauth` (interactive device flow), minting a normal `cli`/`web` session exactly like any laptop — never auto-baked.
+- The credential is still 24h refresh-on-use (unchanged since [#400](https://example.com/builders#/task/400); SR[#2](https://example.com/builders#/task/2)'s "non-expiring" predates that). The fix is **scope**, not lifetime: even a captured, still-valid box token can do nothing but bootstrap.
+
+### 2. Strip the `Cookie` request header at the edge for box subdomains (fixes SR[#11](https://example.com/builders#/task/11))
+
+- A **zone Transform Rule** (`http_request_late_transform` phase, action `rewrite` → `headers.Cookie.operation = remove`) removes the Cookie request header where `starts_with(http.host, "term-")` or `starts_with(http.host, "sandbox-")`, applied at the Cloudflare edge **before** the request enters the tunnel. ttyd uses basic-auth and the sandbox serves the game, so neither needs the cookie. One wildcard-prefix rule covers every builder's box.
+- Implemented as `CfTunnelApi.ensureCookieStripRule` (idempotent GET-merge-PUT that preserves other transform rules), wired **best-effort** into `ensureNamedTunnel` so a token lacking the scope warns but never blocks provisioning.
+- We do **not** narrow the apex cookie — that would break [#726](https://example.com/builders#/task/726) cross-subdomain SSO.
+
+## Alternatives considered
+
+- **Single-use enrollment code exchanged on first boot for the scoped token** (instead of baking a session). Cleaner provenance, but adds a stateful exchange + a first-boot failure mode; the baked-but-scoped session reuses the existing `createSession` path and the same exposure class as the already-baked SSH keys / tunnel token. Deferred — `source='box'` already removes the authority that made the bake dangerous.
+- **A dedicated `scope` column** rather than overloading `source`. Rejected: the audit specified `source='box'`, and `source` already means "how was this minted." One column, one migration.
+- **Path-prefix allow-list inside `requireBuilder`** (`/api/gds/box/...`). Rejected as fragile (prefix drift, and it would wrongly admit non-bootstrap `/box/*` routes like `/box/ssh-key`, `/box/ensure`, `GET /box/terminal`). The per-route opt-in flag is precise and fails closed.
+- **A Cloudflare Worker** to delete the cookie. Unnecessary — Cloudflare Transform Rules permit *removing* (not setting) the `Cookie` request header, which is exactly our need.
+- **Box-side cookie strip** (ttyd / origin). Rejected: the box is the untrusted party; the strip must be at the edge.
+
+## Consequences
+
+- A leaked or compromised dev-box credential can do **nothing but the 4 bootstrap endpoints** — no claiming, shipping, grading, or reading the builder surface.
+- `hasCliSession` (keyed on `source='cli'`) no longer auto-ticks the onboarding "Run /builder-setup" step purely from provisioning — more honest; it is display-only and never gates graduation.
+- `revokeAllSessionsForBuilder` (demotion/offboard) revokes `box` rows like any other → the clawback is unaffected.
+- **Operator action:** the cookie-strip rule needs the `CLOUDFLARE_API_TOKEN` to carry zone **Transform Rules (Account Rulesets) edit** scope. If absent, provisioning still succeeds and logs a warning; apply the rule once in the CF dashboard or add the scope. Tracked as an owner blocker.
+- Verified by `tests/box_scope_session.mjs` (the scope gate, in the CI unit gate) and `tests/cf_tunnel.mjs` (the edge-rule shape). Hardware verification of a fresh box boot under the box-scoped token is a follow-up ([#919](https://example.com/builders#/task/919) note).

package/docs/adr/0054-session-token-reward-cost-plus.md

@@ -0,0 +1,63 @@
+# ADR 0054 — Flat cost-plus session token reward (drachmae as equity)
+
+**Date:** 2026-06-13
+**Context:** GDS-V4, task [#1005](https://example.com/builders#/task/1005). Builds on [ADR 0023](<redacted>.md) (per-task kind-multiplied credits), [ADR 0028](<redacted>.md) (the `llm-pricing.js` token→USD table + session-cost capture), and [ADR 0027](<redacted>.md) (the `session_records` upload-on-ship path this reward rides). Complements — does **not** replace — the per-task `credits_reward × kind_multiplier` path. Related future work: the full-transcript capture ADR (planned, task [#1004](https://example.com/builders#/task/1004)) will give this reward a more trustworthy raw-usage source, and the token-feed hardening scoped in task [#1005](https://example.com/builders#/task/1005) itself.
+**Status:** Accepted.
+**Track:** `internal` (development system / methodology).
+
+## Problem
+
+We are about to onboard the first **incentivized** builders. Today the only payout is per-task `credits_reward` — a unitless number an author sets at task-creation time. It rewards declaring a big number, not doing expensive, real work. The owner's decision (2026-06-13) is to pay builders proportionally to the **true economic cost** of the work they did — the API token spend of the session — plus a margin, with drachmae standing in as **equity** in the project. It must go live today, be idempotent and reversible, and be impossible to inflate with a client-sent dollar figure.
+
+## Decision
+
+Per **shipped session** (the unit; per-task attribution is a later refinement — see the future-review trigger), grant a flat cost-plus reward:
+
+    drachmae = round(true_cost_usd × (1 + REWARD_MARGIN_PCT/100) × 100)   // integer cents
+    REWARD_MARGIN_PCT = 20
+
+- **`true_cost_usd` is computed SERVER-SIDE** from the per-model token counts the ship upload already carries (`session_records.model_usage`), priced via `src/bongos/llm-pricing.js` (the locked API list-price table). The client uploads token *counts*, never a dollar figure — that figure is never trusted from the client.
+- **`true_cost` is deliberately the API LIST price**, not the builder's discounted subscription cost. A builder on a flat Claude Code subscription obtained those tokens far below list, so paying list-cost + 20% routes the subscription-vs-list spread to the builder as profit *on top of* the margin. This is intended: it is how the reward funds the builder's time and ideas, and it rewards taking advantage of the subsidy.
+- **Margin is a code constant** (`REWARD_MARGIN_PCT` in `src/bongos/db.js`), owner-changed via a commit, not a settings UI — the same review-trail rationale as `KIND_MULTIPLIERS` ([ADR 0023](<redacted>.md)). A future migration can promote it to a per-builder/per-version table if the economics ever need live tuning. No rank above Archon is introduced; the knob is an owner-scoped policy constant.
+- **Idempotent per `session_id`**: a new `credit_log.reason = 'session.token_reward'` row carries a `session_id` column backed by a partial-unique index, plus a SELECT fast-path guard inside the upsert transaction. Re-uploading the same session (re-ship, retry) is a true no-op — no double payout.
+- The existing per-task credit path is untouched. Both the token reward and per-task credits accrue to `builders.total_credits` via the existing `pms_apply_credit` trigger.
+- **Drachmae = equity units** (owner framing). No special code — it is the interpretation of `total_credits`.
+
+### Two drachma conventions, one ledger (the load-bearing tension)
+
+We knowingly accept that a drachma now means two things on the same ledger: a *unitless author estimate* (the per-task path) and a *USD-cent of real cost + 20%* (this path). We accept this for MVP speed; a future version may reconcile them (re-denominate per-task credits in cents, or split the ledgers). This ADR records the inconsistency so it is a deliberate decision, not a latent bug.
+
+## The residual "rewards waste" risk + the equity mitigation
+
+A flat cost-plus reward pays **more** for a more expensive session — it can reward token *waste* (thrashing, re-reading, long unproductive loops) as much as productive spend. This was raised and explicitly accepted by the owner, for three reasons:
+
+1. **PASS-gated by construction.** Only a *successful ship* uploads a session record, so a session that burned tokens and shipped nothing earns nothing.
+2. **Drachmae are equity, not cash.** A builder who pads cost dilutes a pool they themselves hold; the incentive to waste is bounded by the fact that the payout currency is ownership in the thing being built. Early builders want their percentage to be worth something, so they self-police. Inflating the denominator hurts the inflator.
+3. **The waste signal already exists.** The BFG session-inefficiency evaluator ([ADR 0027](<redacted>.md)) flags wasteful sessions from the same uploaded digest; a later refinement can gate or discount the reward by a quality/efficiency factor, moving from flat cost-plus to cost-plus-adjusted-for-value. The owner's stated direction is to move toward **market dynamics** (bidding) once the builder pool is genuinely multi-party.
+
+## Consequences
+
+- **Migration 090** adds `session_records.model_usage` + `session_records.token_reward_drachmae`, `credit_log.session_id` + the partial-unique index `uniq_credit_session_token_reward`, and bumps the migration counter.
+- `llm-pricing.js` gains pure, tested `priceModelUsage` + `canonicalizeModelId`.
+- `db.js` gains `REWARD_MARGIN_PCT`, `computeSessionTokenReward`, `awardSessionTokenReward`, and the transactional `upsertSessionRecordWithReward` (the route now calls it instead of the bare upsert).
+- `scripts/gds/ship.js` accumulates per-model usage into the digest; `POST /api/gds/sessions` accepts `model_usage`, prices it, and returns `token_reward` on the 201.
+- The award is **append-only and reversible**: a compensating negative `credit_log` row reverses any reward without mutating history; the `total_credits` trigger nets it out automatically.
+- First incentivized builders can onboard tomorrow with no further code.
+
+## The future-review trigger
+
+Revisit when: (a) per-task token attribution lands (the unit becomes the task, not the session); (b) the grader/BFG efficiency score is wired into the reward (cost-plus → value-adjusted); (c) the two-drachma-conventions tension is reconciled into one unit; or (d) the builder pool becomes multi-party enough to move to market/bidding pricing.
+
+## Amendment — 2026-06-15 (task [#1138](https://example.com/builders#/task/1138)): 1 drachma = $1
+
+**Trigger (c), partial.** An audit of the first incentivized builder's ledger (owner request) found the cents convention had inflated the balance ~100× (one builder, 31 sessions → 295,218 drachmae ≈ $2,952 of cost-plus) and that summing cents-denominated token rewards with the unitless per-task credits made the total incoherent. The owner's decision: **re-denominate the token reward so 1 drachma = $1**, not 1 cent.
+
+**Change to the Decision formula** (supersedes the `× 100` in the formula above):
+
+    drachmae = round(true_cost_usd × (1 + REWARD_MARGIN_PCT/100))   // whole drachmae, 1 drachma = $1
+    REWARD_MARGIN_PCT = 20   // unchanged
+
+- The trailing `× 100` (cents) is **dropped**. A $100 true-cost session now mints `round(100 × 1.20) = 120` drachmae (was 12,000). A sub-$0.42 session now rounds to 0 (was ~50) — intended.
+- `computeSessionTokenReward` in `src/bongos/db.js` changed accordingly; `tests/credit_grant.mjs` updated; `llm-pricing.js` (the token→USD table) is **unchanged** — only the cents→dollars scale factor moved.
+- **History was re-denominated, not left mixed.** Per the "append-only, reversible" rule above, existing `session.token_reward` rows were **not mutated**; a single compensating `credit_log` row (`reason='redenominate.token_reward_dollars'`, `task_id` → [#1138](https://example.com/builders#/task/1138)) restates the running total from cents to dollars, and the `total_credits` trigger nets it automatically. The original cents rows remain as historical record; the `session_records.token_reward_drachmae` display mirror was divided by 100 to match. At amendment time builder `#1` (example-owner) was the only holder of token rewards, so this touched one builder.
+- **The per-task `credits_reward` path (ADR 0023) is untouched** — it stays a unitless author estimate. The two-conventions tension (§"Two drachma conventions, one ledger") is now *narrower* (both paths read on a ~dollar scale) but not formally reconciled; trigger (c) remains open for a full reconciliation.

package/docs/adr/0055-server-mediated-branch-publish.md

@@ -0,0 +1,47 @@
+# ADR 0055 — Server-mediated branch publish (the dev box holds no GitHub credential)
+
+**Date:** 2026-06-13
+**Context:** GDS, task [#1025](https://example.com/builders#/task/1025). A live "can I publish from a dev box?" test failed even after CI self-deploy ([#859](https://example.com/builders#/task/859) / [ADR 0042](<redacted>.md)) went live. Sits at the intersection of [ADR 0042](<redacted>.md) (ci deploy mode), [ADR 0053](0053-scoped-dev-box-session.md) (box-scoped session, [#919](https://example.com/builders#/task/919)), and the box on-ramp ([ADR 0038](<redacted>.md) browser-only builders, [ADR 0044](<redacted>.md), [ADR 0046](<redacted>.md) sandbox-first ship gate / [#927](https://example.com/builders#/task/927), which expects `/builder-ship` to run *on* a box). Governed by the trust boundary in [ADR 0016](<redacted>.md).
+**Status:** Accepted.
+**Track:** `internal` (development system / builder dev boxes + ship pipeline).
+
+## Problem
+
+A builder on a provisioned cloud dev box **cannot publish/ship** in `ci` deploy mode. Two independent, by-design controls combine to block it, and neither was reconciled when both shipped on 2026-06-13:
+
+1. **The box's GDS session is box-scoped.** Per [ADR 0053](0053-scoped-dev-box-session.md) the baked token is `source='box'` — deny-by-default, reaching only 4 bootstrap endpoints. `/builder-start`, claim, grade, ship all return `403 box_scope`.
+2. **The box has no GitHub push credential.** In `ci` mode, `ship.js ciLand()` publishes by `git push origin <branch>` + `gh pr create` + `gh pr merge --auto`. The box has a **credential-less HTTPS** origin (`box-source-fetch.sh` scrubs the clone token by design), no `gh` CLI, no `~/.git-credentials`, no `GH_TOKEN`. `git ls-remote` fails with exit 128.
+
+CI self-deploy ([#859](https://example.com/builders#/task/859)) fixed only the **last** leg — Actions deploys `main`→prod, so no machine holds the droplet key. It did nothing for the two **earlier** legs (a usable session + getting the branch onto GitHub), and [ADR 0053](0053-scoped-dev-box-session.md) deliberately *tightened* the first. The dev-box vision assumes ship-from-box works; nobody wired the box for `ci`-mode publishing. The server itself holds **no** GitHub push credential today (the only GitHub-related secret is the droplet SSH key inside Actions for `deploy-prod.yml`).
+
+## Decision
+
+**The box never holds a GitHub push credential. It uploads its branch to the GDS, and the server pushes it.**
+
+### 1. The box re-auths first (the box-scope model is untouched)
+
+A box-scoped token still cannot ship. The builder runs **`/builder-reauth`** (the existing UI-first browser device flow — [ADR 0053](0053-scoped-dev-box-session.md) §1) to mint a normal `cli` session. That real session — not the baked box token — authorizes the publish.
+
+### 2. A new authenticated publish endpoint, NOT box-scoped
+
+- `POST /api/gds/tasks/:id/publish-branch` — `auth.requireBuilder` + `gateTaskOwnership` (the same [#871](https://example.com/builders#/task/871) gate as `/grade`/`/confirm`/`/ship`), **deliberately without `auth.allowBoxScope`**, so a box-scoped session is `403 box_scope`. Accepts the branch as a **thin git bundle** (base64, `origin/main..HEAD`), `head_sha`, and `value_summary`. The server: writes the bundle to a per-request temp dir, fast `git clone --bare --local` of its own checkout for `main`'s objects (no network, no worktree touch → never races the `deploy-prod.yml` reset), unbundles, **verifies the bundle tip == the claimed `head_sha`** (binds the pushed code to the already-graded sha), then `git push` to GitHub via a **one-shot `x-access-token:<redacted> URL** (never persisted, never logged — the `box-source-fetch.sh` pattern), opens the PR, and enables auto-merge.
+- `GET /api/gds/tasks/:id/publish-status?branch=…` — ownership-gated; the server derives PR + deploy state live from GitHub so `ship.js` confirms the land WITHOUT `gh` on the box. No DB column added.
+- Implementation: [`src/bongos/github-push.js`](../../src/bongos/github-push.js) (push/PR/status via `execFile` arg-arrays + raw `fetch`, all behind test seams), routes in [`src/bongos/routes/tasks.js`](../../src/bongos/routes/tasks.js), the bundle body bypasses the global 64 KB JSON cap via the skip-list in [`src/bongos/routes.js`](../../src/bongos/routes.js) (route-scoped 32 MB parser + a 20 MB decoded-byte cap).
+
+### 3. `ship.js` chooses the path automatically
+
+`ciLand` splits into `ciLandLocal` (today's `git`+`gh`, byte-for-byte — laptop unchanged) and `ciLandServer` (bundle → `publish-branch` → poll `publish-status`). `pushVia()` picks: `OTB_PUSH_VIA_SERVER=1/0` overrides; otherwise a machine with an authenticated `gh` (laptop) is `local`, everything else (a dev box) is `server`. `doctor.js` reports the same path and no longer fails on missing `gh` when server-mediated.
+
+### 4. The server credential
+
+A **fine-grained GitHub PAT** scoped to the single repo: `Contents: read/write` + `Pull requests: read/write` + `Actions: read`, set as `GITHUB_PUSH_TOKEN` in the droplet EnvironmentFile ([ADR 0022](0022-secrets-policy.md)). It **cannot** push to branch-protected `main` and **cannot** bypass required checks — a leaked server token can only land code on a feature branch behind the same checks every PR faces. **Inert-safe:** with the token unset the endpoint returns `503 push_unconfigured` and laptops are unaffected.
+
+> **Update (2026-06-13, task 1028 — GitHub App):** the preferred server credential is now a **GitHub App**, not a standing PAT. The server holds only the App private key (`GITHUB_APP_ID` + `GITHUB_APP_INSTALLATION_ID` + `GITHUB_APP_PRIVATE_KEY`) and mints a short-lived (~1h), repo-scoped **installation token** per push window — so there's no standing push secret at rest. `github-push.js resolveToken()` prefers the App and falls back to the PAT (`GITHUB_PUSH_TOKEN`) during cutover; `isConfigured()` is true if **either** is set, so the route's inert-safe `503` is unchanged. The App JWT is RS256-signed with `node:crypto` (no new dependency). Same single-repo scopes (Contents r/w + PR r/w + Actions read) and the same can't-touch-`main` guarantee. **LIVE on prod as of 2026-06-13 (task 1043 cutover, blocker 31 resolved):** the App (App ID 4047551, installation 140135657, `repository_selection=selected`) is installed and its key is set in `/etc/example/web-source.env`; verified that the server mints + uses an installation token (`publish-status` → 200, and a broken key fails loud as `503`/error rather than falling back). The old `GITHUB_PUSH_TOKEN` was **removed** — there is now **no standing push secret at rest**, only the App private key.
+
+## Consequences
+
+- A dev-box builder ships end-to-end: `/builder-reauth` → claim → edit → `/builder-stage` ([ADR 0046](<redacted>.md)) → `/builder-ship`, with the GDS doing the push. The box holds no GitHub credential, so the [ADR 0053](0053-scoped-dev-box-session.md) blast-radius argument still holds.
+- The blast radius moves from "box holds a push credential" to "server holds a branch-push-only PAT." This is the direction blocker [#15](https://example.com/builders#/blocker/15) ([SEC #863](https://example.com/builders#/task/863)) already wants — a server identity holding the push credential, not builder machines.
+- **Follow-up (hardening) — DONE + LIVE (task 1028 code, task 1043 cutover):** the standing PAT is replaced by a **GitHub App** (the server holds only the App private key and mints short-lived, repo-scoped installation tokens per push). See the *Update* above — the App is live on prod and the PAT has been removed.
+- **Residual:** the server verifies the bundle tip == the claimed sha and that the caller holds the claim, but does not cheaply prove every commit in the bundle was authored under the claim — branch protection + required checks on `main` (which the credential cannot bypass) are the real gate, exactly as for any PR.
+- **Operator action — DONE (blocker 31, resolved 2026-06-13):** the GitHub App was created and `GITHUB_APP_ID` + `GITHUB_APP_INSTALLATION_ID` + `GITHUB_APP_PRIVATE_KEY` set on the droplet (task 1043); `GITHUB_PUSH_TOKEN` then removed. To rotate the key: generate a new private key in the App's settings, replace `GITHUB_APP_PRIVATE_KEY` (single-line, literal `\n`) in `/etc/example/web-source.env`, restart `example`. To roll back to the PAT: restore `web-source.env.bak-task1043` and set a fresh `GITHUB_PUSH_TOKEN` (with the App vars absent, `resolveToken()` falls back to the PAT).