@bongos/core 1.17.0

package/docs/adr/0063-generated-repo-map-symbol-skeleton.md

@@ -0,0 +1,44 @@
+# ADR 0063 — Generated code symbol skeleton (the repo map)
+
+- **Status:** Accepted
+- **Date:** 2026-06-18
+- **Track:** internal
+- **Builds on:** [ADR 0061](<redacted>.md) (the content charter + nested per-module `CLAUDE.md` — this generates their *factual half*), [ADR 0060](0060-gds-retrieval-layer.md) (the lexical recall layer — this is its structural/code complement), [ADR 0062](<redacted>.md) §9 (Path B, folded into the Medusa portable core)
+- **Task:** [#1224](https://example.com/builders#/task/1224) (V4.R75) — Path B of the 2026-06-18 context-cliff plan.
+
+## Context
+
+As an AI-authored repo grows, an agent's ability to make safe changes degrades: it cannot hold the whole tree in context, so it either reads too many files (burning budget) or guesses (drifting). [ADR 0061](<redacted>.md) added nested per-module `CLAUDE.md` docs whose hand-written "Key files / public surface" section is exactly the kind of fact that **drifts** — the moment a function is renamed or a file added, the prose lies, and nothing forces it back into sync.
+
+Path B (the 2026-06-18 research) is the fix: a committed, **generated** symbol skeleton, regenerated mechanically so it cannot drift — the same "generate, don't narrate" discipline `gen-diagrams.js` already applies to the onboarding diagrams (task 357). It gives an agent an **altitude map** (à la Aider's repo map): the most central symbols and per-file signatures, so it can navigate without reading every file. It complements the recall layer ([ADR 0060](0060-gds-retrieval-layer.md)), which indexes *prose* (docs + DB rows) — the repo map indexes *code*.
+
+## Decision
+
+Ship `scripts/gds/gen-repo-map.js`, a deterministic generator that produces two artifacts and is wired into the deploy regen:
+
+1. **`docs/repo-map.md`** — the global altitude map: the top exported symbols ranked by reference frequency, plus per-directory exported signatures.
+2. **A delimited generated block** (`<!-- BEGIN/END GENERATED REPO-MAP -->`) injected into each nested `CLAUDE.md` (`src/bongos/`, `src/bongos/routes/`, `scripts/gds/`) — the **factual half**. The hand-written interpretive prose above it (purpose, gotchas, ADR links) is left untouched; only the factual signature list is regenerated, so the two halves can't drift apart.
+
+**Regenerated on every ship** by `regenerateRepoMap()` in `ship.js` (alongside `regenerateDiagrams()`), and gated in CI by `gen-repo-map.js --check` (exit 2 if stale) — the enforcement is Path C / [#1225](https://example.com/builders#/task/1225). Deterministic (no timestamps, stable sort) so `--check` is a clean idempotent gate.
+
+### Why zero-dependency (not tree-sitter, despite the task name)
+
+The task is named "tree-sitter repo map." We use a **zero-dependency line+regex extractor** instead, deliberately:
+
+- **Portability is the whole point.** Paths B+C exist to keep *every* Medusa instance navigable cheaply. A portable-core capability that needs a native `node-gyp` build (`tree-sitter`) or a fetched WASM grammar (`web-tree-sitter`) adds an install/build step to CI and to every dev box — the opposite of the goal, and a recurring source of breakage.
+- **The codebase is CommonJS JS**, formatted with col-0 top-level declarations — a regex extractor keyed on that is accurate enough.
+- **The output is advisory**, not a compiler input. An imperfect signature in a navigation aid costs nothing; a broken CI build costs every ship.
+- **Bootstrap budget** ([CLAUDE.md](../../CLAUDE.md) §4): no new dependency.
+
+`extractFile()` is the seam: a tree-sitter/WASM backend can replace it later for a **polyglot** instance (a Python or Go host) behind the same interface, without touching the ranking or rendering. Until an instance needs more than one language, the regex backend wins on every axis that matters.
+
+### Known limitation: reference frequency is a corpus token tally
+
+"Refs" is the count of a symbol's name across the scanned corpus — a cheap centrality proxy (à la Aider's repo map, minus the PageRank graph). It does **not** resolve scope, so two distinct symbols sharing a name (e.g. several files' exported `start()`) share one count. Ranking only the **exported** surface (cross-file-reachable in CommonJS) plus a generic-name stoplist (`main`/`log`/`err`/…) removes the worst noise; the residual same-name conflation is acceptable for an altitude map and documented here so a reader doesn't over-trust the exact number.
+
+## Consequences
+
+- Nested-doc file/signature lists can no longer silently drift — they're regenerated on every deploy and gated in CI.
+- An agent gets a cheap, always-fresh structural map of the codebase, complementing prose recall.
+- Scope today: server-side JS (`server.js`, `src/`, `scripts/`, `.claude/hooks/`). Extending coverage (e.g. `public/game/`) or languages is a one-line `SCAN_ROOTS` change / an `extractFile()` backend swap.
+- The generator is itself in `scripts/gds/` and so appears in its own map — editing it changes its own skeleton, so a regen+commit must be the last step before shipping any source change (the `--check` gate enforces this).

package/docs/adr/0064-rename-medusa-to-cloud-bongos.md

@@ -0,0 +1,49 @@
+# ADR 0064 — Rename the platform: Medusa → Cloud Bongos
+
+- **Status:** Accepted
+- **Date:** 2026-06-19
+- **Track:** internal
+- **Amends:** [ADR 0062](<redacted>.md) (the instance-model build platform, formerly named "Medusa"). The 0062 architecture — portable core / host instance / gated feature-modules, the branding contract, feature-module selection — is **unchanged**; only the platform's name changes.
+- **Task:** 1242 (this rename). Sibling: task 1216 / V4.R74 (the Cloud Bongos visual brand pack — the look this name wears).
+
+## Context
+
+The build platform decoupled out of the GDS in [ADR 0062](<redacted>.md) was named **Medusa** (a working name from the 2026-06-17 planning session). While designing the vanilla "customer 0" brand pack (task 1216 / V4.R74), the owner settled on a different identity and renamed the platform to **Cloud Bongos** — a light, joyful, "playing in the clouds" developer tool where *building software is laying down a beat*.
+
+The visual direction is recorded with the brand pack (task 1216), not here: a Lion-King sunrise backdrop, Apple-style liquid-glass "cloud" cards, a bongo-pair mark with an equalizer/beat motif, and the type pairing **baloo 2** (lowercase wordmark) · **Quicksand** (interface) · **Fira Code** (numbers & code). *This* ADR records only the name and the rename's scope.
+
+## Decision
+
+1. **The platform is named Cloud Bongos** (was "Medusa"). This is the whole platform: the product name, the AGPL open-source project (C9 / R68–R73), the future `cloudbongos` CLI (`init`/`upgrade`, R65/R72), the canonical config identity, and all forward-facing docs.
+2. **Scope = whole-platform rename, history preserved** (owner choice, 2026-06-19). Forward-facing surfaces are renamed; the historical record keeps "Medusa" as what was decided when, each reachable via this ADR.
+3. **Canonical identity** lives in `config/branding.neutral.json` (customer 0): `identity.productName` / `identity.worldName` = `"Cloud Bongos"`, `envPrefix` = `"CLOUDBONGOS"`. The branding contract resolver and schema (ADR 0062 §3, `src/branding.js`) are unchanged — only the values move; `tests/branding.mjs` updated to match.
+4. **The Greek rank ladder (Xenos · Thetes · Metic · Archon) is unchanged.** It is core methodology, not brand flavor (locked in the 0062 planning); the rename does not touch it.
+5. **Capitalization:** the wordmark renders lowercase ("cloud bongos"); prose and identifiers use "Cloud Bongos".
+
+## What this touches
+
+**Renamed now (forward-facing):**
+- `config/branding.neutral.json` (identity + envPrefix) and `tests/branding.mjs`; `src/branding.js` default env prefix.
+- `CLAUDE.md` methodology-core framing (platform-name references; the §13 session-log index is left as history).
+- `docs/branding-contract.md`, `docs/branding-fill-prompt.md`, `docs/project-context.md`, `docs/project-context.template.md`.
+- Comments in `scripts/gds/fitness.js` and `scripts/gds/gen-repo-map.js`.
+- This ADR + the [ADR index](README.md) row; a pointer note on ADR 0062.
+- **Live DB strings** (follow-up, task 1244 / migration `<redacted>.sql`): the GDS-V4 **C8 + C9** done-when criteria and the **R67** proof-task title/description — rewritten forward because the API serves them to users (/status, the hall, /recall). Display text only; the `medusa-*` `criterion_id` keys and the `schema_migrations` version strings are untouched.
+
+**Left as history (NOT rewritten):**
+- ADR 0062 body (carries a pointer note to here), [ADR 0063](<redacted>.md).
+- `docs/session-logs/<redacted>.md` and other logs.
+- Applied migrations `110_medusa_planning_seed.sql`, `<redacted>.sql` (immutable once applied).
+- `scripts/gds/seed-medusa-tasks.js` (the historical seed tooling; its filename and the **other 23** V4.R50–R74 task titles/descriptions that say "Medusa" — the R67 proof task + the C8/C9 criteria were rewritten live via migration 114 / task 1244; the rest stay as history per the owner's choice).
+- `docs/repo-map.md` (generated — regenerates on deploy).
+
+## Consequences
+
+- `envPrefix: "CLOUDBONGOS"` only changes a *fresh* instance's branding env-**override** variable names (e.g. `CLOUDBONGOS_PUBLIC_ORIGIN`). Customer 1 (Example / OTB) keeps `OTB_*`; no live instance used a `MEDUSA_*` **branding-override** prefix, so there is nothing to shim there. *(Separately, the R52 migration-mode flag `MEDUSA_GDS_ONLY` in `scripts/migrate.sh` — a different namespace, not the branding prefix — does still carry the old name; it is unset by every live instance, so it is harmless today, and is slated for a neutral rename under V4.R71. Tracked in task 1244.)*
+- Follow-on work inherits the new name: the visual brand pack (task 1216 / V4.R74); the config-namespace + env/CLI rename with back-compat shims (V4.R71) now targets the Cloud Bongos namespace; the AGPL repo + governance docs (C9, R68–R73) use "Cloud Bongos."
+- A transitional split is expected and intentional: forward docs say "Cloud Bongos," the 0062-era record says "Medusa," and this ADR bridges them. Future agents should treat "Medusa" in historical records as the former name of Cloud Bongos.
+
+## Rejected alternatives
+
+- **Rewrite history too** (also rename ADRs, logs, migrations, the 24 task descriptions): rejected by the owner — it destroys the record of what was decided when, for little forward value.
+- **Brand-pack-only** (keep the platform internally named "Medusa," show "Cloud Bongos" only as the default instance's brand): rejected — the owner wants the platform itself renamed.

package/docs/adr/0065-agpl-nonprofit-ai-first-governance.md

@@ -0,0 +1,69 @@
+# ADR 0065 — Cloud Bongos is AGPL-3.0, non-profit, and AI-first
+
+- **Status:** Accepted
+- **Date:** 2026-06-19
+- **Track:** internal
+- **Task:** [#1207](https://example.com/builders#/task/1207) (V4.R68) — the foundational decision for the C9 open-source track.
+- **Builds on:** [ADR 0062](<redacted>.md) (the instance-model build platform — defines the portable core / host instance / feature-module cut-line this ADR releases), [ADR 0064](<redacted>.md) (the platform is named **Cloud Bongos**), [ADR 0016](<redacted>.md) (the server-enforced trust boundary — survives open-sourcing untouched).
+- **Gates:** [#1208](https://example.com/builders#/task/1208) (R69 LICENSE file), [#1209](https://example.com/builders#/task/1209) (R70 governance docs), [#1210](https://example.com/builders#/task/1210) (R71 public mirror + carve-out), [#1211](https://example.com/builders#/task/1211) (R72 delayed export pipeline), [#1212](https://example.com/builders#/task/1212) (R73 lineage-consistency proof). This ADR is the decision those five tasks implement.
+
+## Context
+
+[ADR 0062](<redacted>.md) decoupled the GDS into **Cloud Bongos** — a configurable, self-hostable build platform where AI agents claim tasks and ship code, with a human owner setting scope and the hard gates. Example (the Off the Boats game) becomes **customer 1** running on it; Cloud Bongos runs on its own plain vanilla brand as **customer 0** and builds itself.
+
+Criterion **C9 (`medusa-open-and-protected`)** commits Cloud Bongos to being *open, free, and protected from capture*: released to the public as open source on a deliberate, delayed cadence. Three questions had to be answered before any of R69–R73 could be built, because each is downstream of the answer:
+
+1. **Which license?** The choice determines whether a well-funded operator can take the code, host it as a closed SaaS, and out-compete the project that produced it.
+2. **What is the governance posture?** Whether the project is a commercial concern that monetizes its contributors, or a non-profit commons.
+3. **Who writes the code, and is that a rule or a norm?** Cloud Bongos is AI-first by construction; the open-source release has to say what that means for outside contributors.
+
+The owner locked the answers in the 2026-06-17 planning session ([log](../session-logs/<redacted>.md)). This ADR records them and the alternatives rejected, so R69–R73 build against one decision instead of re-litigating it five times.
+
+## Decision
+
+### 1. License: AGPL-3.0
+
+Cloud Bongos is released under the **GNU Affero General Public License, version 3.0 (AGPL-3.0)**.
+
+The AGPL's distinguishing clause (§13) closes the **hosted-closed-fork loophole**: anyone who runs a modified Cloud Bongos as a *network service* must offer that service's complete corresponding source to its users. A plain GPL would let a SaaS operator modify the platform and never distribute a binary — the modifications stay private because nothing is "distributed" in the GPL sense. The AGPL treats "you can use it over the network" as the trigger. This is the **only license consistent with the anti-monopoly goal** in C9: it keeps the platform a commons even when it is operated, not just when it is shipped.
+
+The license covers the **publishable subset only** — the portable methodology core, the Cloud Bongos platform code, the neutral (customer-0) branding, and sanitized docs/ADRs. It does **not** attach to a host instance's private identity, secrets, content, or operational infrastructure (see §4). An instance owner's own branding pack and game/world content remain theirs.
+
+### 2. Governance: non-profit, capture-resistant
+
+The project is run as a **non-profit**: it is **not monetized from its contributors**, and it is structured so no single party can capture it.
+
+- No contributor pays to contribute, and no contribution is resold as a proprietary add-on by the project.
+- The drachmae/credit economy ([ADR 0054](<redacted>.md)) is an **instance-internal** mechanism — it rewards builders on a given instance out of that instance's own budget; it is not the project monetizing the commons. It ships as a feature an instance configures, not as a revenue stream flowing to a central owner.
+- The AGPL is the legal backstop; the non-profit posture is the social one. Together they are the "protected from capture" half of C9.
+
+Optional **managed-hosting** (operating instances for owners) was captured as a post-C8 idea in the planning session. If it is ever built, it is a service offered *on top of* the same AGPL artifact — it does not change the artifact's license or the non-profit posture of the platform itself.
+
+### 3. AI-first is a documented norm, not a technical gate
+
+Cloud Bongos is **AI-first**: the expectation is that **AI agents write the code** — a human owner sets scope, direction, and the hard gates (rank, approval, deploy); the day-to-day building is done by AI agents claiming tasks.
+
+This is a **documented norm folded into governance/methodology, not a technical gate**. We do *not* add machinery that detects or blocks human-authored commits. The norm is stated in CONTRIBUTING (R70) and lives in the portable methodology core (CLAUDE.md, [ADR 0061](<redacted>.md)); enforcement is cultural and reviewable, the same way the "every change is backed by a claimed task" rule is. An instance is free to relax it; the project ships it as the default expectation because the whole methodology — the grader, the session-token economy, the claim lifecycle — is designed around agents as the primary authors.
+
+### 4. The public-mirror boundary (jointly defined with R50)
+
+What is published is the **portable core + platform, never a host's private surface**. Concretely, the publishable subset is:
+
+- **Published:** the portable methodology core (CLAUDE.md framing, the claim→ship lifecycle, the trust-boundary/rank machinery), the GDS platform code (`src/bongos/*`, `scripts/gds/*` minus instance literals), the neutral customer-0 branding (`config/branding.neutral.json`), the docs/ADRs (sanitized), and the skills that drive the methodology.
+- **Not published:** secrets and credentials, a host instance's identity literals (domains, IPs, owner, OAuth app, repo), live DB contents, prod operational infra, customer-1 (Example) game/art content and brand pack, and **anything inside the redaction window** — the public mirror lags the private repo by **~6 months** so an operator can never track head-of-line development in real time (R72).
+
+The mirror is **generated** from the private Example repo by the delayed-export pipeline (R72), not maintained as a hand-curated fork; R73 proves private↔public lineage consistency and no-leak. This boundary is the same §1 cut-line ADR 0062 drew (portable core / host instance / gated feature-modules) — open-sourcing it just means the *core* side of that line is the thing that ships, and R71 carves the subtree to match.
+
+## Alternatives considered (rejected)
+
+- **MIT / BSD / Apache-2.0 (permissive).** Maximum adoption, but a permissive license **does not close the hosted-closed-fork loophole** at all — a funded operator could fork, close, and out-host the commons with zero obligation. Directly contradicts "protected from capture." Apache-2.0's explicit patent grant is a real virtue, but not enough to outweigh the capture risk. Rejected.
+- **GPL-3.0 (copyleft, no network clause).** Copyleft on *distribution*, but the **SaaS loophole** stays open: run a modified copy as a network service and you never "distribute," so the modifications stay private. For a platform whose primary deployment mode is *being operated over the network*, GPL is copyleft with the relevant case carved out. AGPL is GPL-3.0 plus exactly the clause we need. Rejected in favor of AGPL.
+- **Source-available / BSL (Business Source License), commons-clause, "open-core."** Would let the project monetize hosting or gate features, but it is **not open source** (fails the OSI definition / DFSG), conflicts with the non-profit posture, and reintroduces the central-capture risk we are trying to design out. Rejected.
+- **Dual-license / CLA-backed relicensing.** A contributor license agreement assigning rights to a central entity is the standard path to *later* relicensing (i.e., the capture move we are guarding against). Rejected as inconsistent with the non-profit, capture-resistant posture. Inbound contributions are inbound=outbound under the AGPL (the standard for AGPL projects).
+
+## Consequences
+
+- **R69–R73 have one decision to build against.** R69 drops the AGPL-3.0 `LICENSE` file; R70 writes GOVERNANCE/CONTRIBUTING/CODE_OF_CONDUCT encoding the non-profit + AI-first norms decided here; R71 carves the publishable subtree to the §4 boundary; R72 builds the 6-month-delayed redacted export; R73 proves lineage + no-leak.
+- **The trust boundary and rank ladder are unaffected.** Server-enforced permissions ([ADR 0016](<redacted>.md)) and the Greek rank enum ([ADR 0062](<redacted>.md) planning lock) are core methodology; open-sourcing the code does not weaken them — an instance's authority still lives in its own DB, checked server-side, regardless of who can read the source.
+- **Downstream operators inherit the AGPL obligation.** Anyone hosting a modified Cloud Bongos owes their users source. That is the intended effect, not a side effect.
+- **No new infrastructure or recurring cost** from this decision itself; it is a license + posture choice. The export pipeline (R72) has its own cost profile, evaluated under its task.

package/docs/adr/0066-generated-file-map-sections.md

@@ -0,0 +1,51 @@
+# ADR 0066 — Generated file-map sections (skills + scheduled-tasks) with a sidecar of notes
+
+- **Status:** Accepted
+- **Date:** 2026-06-19
+- **Track:** internal
+- **Builds on:** [ADR 0063](<redacted>.md) (generated symbol skeleton — same "generate, don't narrate" discipline + the `git-merge-regen` self-heal), [ADR 0062](<redacted>.md) §8–§9 (Path C fitness gate + the gen-on-deploy pattern), [ADR 0061](<redacted>.md) (the context-layer docs this keeps honest)
+- **Task:** [#1276](https://example.com/builders#/task/1276)
+
+## Context
+
+`docs/file-map.md` is the repo's "where things live" index. Every other self-knowledge doc had already been moved off the honor system: the onboarding diagrams (`gen-diagrams.js`, task 357), the code symbol skeleton (`gen-repo-map.js`, [ADR 0063](<redacted>.md)), and the session-log index (`gen-session-index.js`, [ADR 0062](<redacted>.md) §8) are all **generated and CI-enforced** — so an agent physically cannot forget to update them. `file-map.md` was the last one still hand-maintained.
+
+The cost showed up concretely: task 1267/1269/1272 shipped three new skills (`/ideate`, `/paint`, `/dev`) without adding them to `file-map.md`, which then needed a *separate* doc-hygiene task ([#1274](https://example.com/builders#/task/1274)) just to catch the map up. Worse, an audit while building this found the two enumerable sections had silently drifted into curated **subsets**: `.claude/skills/` had 28 dirs on disk but the map listed ~18 (`recall`, `status`, `builder-box`, `priority-session`, … were simply absent), and `.claude/scheduled-tasks/` had 17 but listed ~6. The map looked complete and wasn't.
+
+The owner's directive: if this logging is critical for the system to know itself, it should happen automatically, not via a hand-filed follow-up task.
+
+## Decision
+
+Generate the two sections of `file-map.md` that are genuinely **"list every item" sets** — `.claude/skills/` and `.claude/scheduled-tasks/` — from what is on disk, and keep the per-entry one-line notes (the prose after the `←`) in a **sidecar** the generator reads.
+
+`scripts/gds/gen-file-map.js` (zero-dependency, deterministic — dirs sorted by name, no timestamps):
+
+1. Walks the immediate subdirectories of each section's dir and renders an aligned tree between sentinel markers (`<!-- BEGIN/END GENERATED FILE-MAP <section>/ -->`) placed **outside** the fenced code block so they don't render. The surrounding prose stays hand-written.
+2. Pulls each entry's note from **`docs/file-map.notes.json`** — keyed by section → dir name. This is the one place a human writes these notes (a directory walk can't know what a skill *does*).
+3. `--check` mode (the CI gate) fails (exit 2) on any of: a rendered block that differs from what's committed (drift); a dir on disk with **no note** (a skill can't land undescribed); a note whose dir no longer exists (no ghosts).
+
+Wiring (the established three-point pattern):
+- **Freshness gate** — added to `fitness.js` `checkGeneratedArtifactsFresh()`, so the DB-free `unit` required check enforces it on every PR (no new workflow).
+- **Regenerate-on-deploy** — `ship.js` `regenerateFileMap()` runs it on the same beat as the repo map + session index and commits any change, so the map self-heals even if a builder forgets.
+- **Merge self-heal** — `file-map.md` joins the `otb-regen` merge driver (`git-merge-regen.js` + `.gitattributes`): two parallel branches that each add a skill conflict only in the generated block, and the one correct resolution is to 3-way-merge the prose then re-inject both sections from the merged tree.
+
+### Why a sidecar, not per-file markers
+
+The pitch floated a `// @map:` comment in each file. Rejected: it can't work for `.json`/`.sql` files (no comments), the skills' frontmatter `description:` is the verbose Skill-tool trigger blurb (wrong register for a one-line map note), and it would scatter the notes across ~45 files. A single sidecar is uniform across file types, keeps the notes in one reviewable place, and still forces a one-line addition per new skill in the same PR (the gate fails otherwise) — the same "can't forget" property, less churn.
+
+### Why `scripts/gds/` is NOT generated
+
+`file-map.md`'s `scripts/gds/` listing is a deliberately **curated highlight reel** (~20 of ~70 files) and sits mid-tree inside the big fenced repo tree where HTML-comment markers can't live cleanly. Auto-generating it would either bloat it 3× with low-signal entries or require a curation list for little benefit. It stays hand-curated. The two generated sections cover the actual failure mode (a new skill/routine going missing).
+
+## Consequences
+
+- A new skill or scheduled task **cannot** ship without a note in `file-map.notes.json` — the `unit` gate fails — so the doc-hygiene follow-up task (the 1274 pattern) is structurally retired.
+- The generation back-filled the ~10 skills + ~11 routines that had silently fallen out of the map; both sections are now exhaustive.
+- One more sidecar file to keep in mind, but it's the *only* place those notes live and the gate points an author straight at it.
+- Generating only two of file-map.md's many sections is a deliberate scope line; if another section later becomes a churny enumerable set, it can join `SECTIONS` the same way.
+
+## Alternatives considered
+
+- **Presence-only fitness check** (assert every skill/routine appears *somewhere* in the hand-written map). Lighter, but leaves the author hand-writing the line and doesn't fix the tree-art/ordering drift or the latent omissions. The owner chose generation.
+- **Fully generate the entire `file-map.md` tree.** Throws away the hand-written framing prose (the intro, the droplet layout, the curated `scripts/` highlights) and the editorial notes; a bare `ls -R` is less useful, not more.
+- **Per-file `// @map:` markers** — see "Why a sidecar" above.

package/docs/adr/0067-session-start-fast-forward-pull.md

@@ -0,0 +1,43 @@
+# ADR 0067 — Fast-forward the checkout to origin/main at session start (when safe)
+
+- **Status:** Accepted
+- **Date:** 2026-06-19
+- **Track:** internal
+- **Builds on:** the warn-only freshness step ([#1258]) it replaces; the dev-box source-materialization cron (`infra/box-source-fetch.sh`, [ADR 0031](<redacted>.md)); the existing memory pull-on-session-start (`.claude/hooks/pull-memory.js`, [#275]) whose best-effort/fail-open discipline this mirrors for the code checkout.
+- **Task:** [#1277](https://example.com/builders#/task/1277) — owner request ("make sure we pull on every session start").
+
+## Context
+
+A builder's working checkout can run **stale** relative to `origin/main`, and several startup-loaded surfaces — `CLAUDE.md`, the file-based memory, and the SessionStart hooks themselves — are read **once** per session. A session that starts behind `main` therefore runs old methodology and old code with no self-heal during the session.
+
+Two existing mechanisms only partly cover this:
+
+1. **The dev-box cron** (`box-source-fetch.sh`, every ~10 min) does `git pull --ff-only` on the box's `/workspace` checkout. But it only freshens `/workspace` (not per-task worktrees), only fast-forwards, and lags by up to its interval — so a *new* session opened between ticks can still be behind.
+2. **The warn-only freshness step** ([#1258]) did a bounded, non-mutating `git fetch origin main` and, if behind, *warned* but never pulled. Its stated reasons for not pulling: dirty trees can't fast-forward, and the Mac's iCloud-synced checkout has an mmap risk on big working-tree git ops.
+
+The owner asked for the obvious fix — pull on session start — but the naive alternative (shorten the cron toward "every few seconds") is wrong on the merits: `cron` can't go sub-minute, every tick is an authenticated `GET /box/source-access` round-trip against the single prod droplet, and a frequent pull risks rewriting files **under an active session**. The right lever is **event-driven**: freshen once, at the moment work begins, not by polling faster.
+
+## Decision
+
+Upgrade the SessionStart freshness step (`freshenOrWarn()` in `.claude/hooks/session-start.js`, renamed from `printFreshnessWarning()`) from *fetch-and-warn* to *fast-forward-when-safe, else warn*. After the same bounded `git fetch origin main`, it computes `behind = HEAD..origin/main` and, if behind, runs `git merge --ff-only origin/main` **only** when **all** of these hold:
+
+- **on branch `main`** — never pull `origin/main` into a feature branch / worktree (that is a rebase, not this hook's job; it cleanly no-ops the common laptop case);
+- **zero local commits ahead** (`origin/main..HEAD == 0`) — strictly behind, so the merge is a real fast-forward, never a merge commit;
+- **no modified/staged tracked files** (untracked/ignored are fine, so a box with stray logs still qualifies) — a fast-forward then cannot shadow uncommitted work;
+- **a full clone, not a partial/blobless one** — on a `--filter=blob:none` box, checkout lazily fetches blobs over the network, which the bounded merge could interrupt; those are left to the cron.
+
+Everything stays **bounded + fail-open**: a slow/offline network or any git error never blocks or delays session start — it falls through to the existing warning. The kill-switches (`OTB_FRESHNESS_CHECK_OFF`, `OTB_SUBAGENT` subagent skip) are preserved. On a successful pull the hook prints a one-line confirmation that also notes the caveat below.
+
+This **reverses** the "nothing pulls at session start, by design" rule the [#1258] comment documented. That rule is preserved exactly for every case *outside* the safe gate (feature-branch worktrees, dirty trees, diverged history, partial clones), which still get the warning.
+
+## Consequences
+
+- **A fresh session on a clean `main` full clone starts current** — the box `/workspace` and a laptop's main checkout fast-forward at startup instead of waiting up to a cron interval (or forever, for a between-ticks session). This is the owner's asked-for behavior.
+- **Never worse than before.** Where the safe gate doesn't hold, behavior is byte-identical to the warn-only step. Where it does, a fast-forward on a clean `main` is local + fast, so the bounded merge effectively never trips; if it ever did, the box cron remains the backstop.
+- **The iCloud-mmap risk is sidestepped, not ignored.** The merge only runs on a clean `main`; Mac sessions are overwhelmingly feature-branch worktrees, which take the (unchanged) warn path. A main-checkout pull on the Mac is bounded and fail-open.
+- **Worktrees and loaded-once surfaces are out of scope.** Per-task worktrees aren't auto-advanced (you don't pull `main` into a feature branch), and even after a successful code pull, the `CLAUDE.md` / hooks / memory already loaded for *this* session reflect the pre-pull state until the next session — the success line says so. The real reset for those surfaces remains a fresh session.
+- **Starter (partial-clone) boxes** keep relying on the cron for freshness; they are deliberately excluded to avoid interrupting lazy blob fetches. If that matters later, the gate can be relaxed once a partial-clone-safe pull path exists.
+- **No new dependency, no new network load.** One extra local `git merge` on the qualifying path; the prod API is untouched (this is the cheap event-driven alternative to a faster cron).
+
+[#1258]: https://example.com/builders#/task/1258
+[#275]: https://example.com/builders#/task/275

package/docs/adr/0068-shared-art-key-for-newcomers.md

@@ -0,0 +1,38 @@
+# ADR 0068 — Shared Gemini art key delivered from the GDS to newcomers
+
+- **Status:** Accepted
+- **Date:** 2026-06-20
+- **Track:** internal
+- **Builds on:** [ADR 0016](<redacted>.md) (rank enforced server-side, no caching — the gate here is `builders.rank`), [ADR 0054](<redacted>.md) (cost-plus economics — this is the org choosing to absorb newcomer art spend), and the existing per-builder BYOK key path in `art/pipeline/gen_api.py` (V3.R11 [#91](https://example.com/builders#/task/91))
+- **Task:** [#1281](https://example.com/builders#/task/1281)
+
+## Context
+
+A newcomer's (rank `xenos`) three first chores include an **art** task — "generate one in-world asset" via `/otb-tile-generate` (`scripts/gds/newcomer-floor.templates.json`). That pipeline needs a Google AI Studio (Gemini) key. Until now the only ways a builder had one were (a) pasting their own during `/builder-setup` (`gemini_api_key` in their local session file) or (b) an operator hand-placing one in `~/.config/otb/env` on the machine. A brand-new builder has neither, so their very first art task fails with a "set `GOOGLE_AI_STUDIO_KEY`" error — a hostile first impression for a task we explicitly want them to complete.
+
+The owner's intent: **we pay up front** for a newcomer's first art tasks. Once they prove themselves (graduate `xenos → thetes` after three shipped tasks) they bring their own key. This ADR records the Phase-1 *infrastructure* decision; the newcomer-facing *experience* (copy explaining we pay, the on-promotion walkthrough to add a personal key, a rank-aware setup prompt) is a deliberate Phase 2.
+
+## Decision
+
+The GDS becomes the source of a **shared** Gemini key, delivered to entitled builders and consumed by riding the art pipeline's existing key-resolution cascade.
+
+1. **Storage = server secret, not the DB.** The shared key is an operator-provisioned env var `SHARED_ART_GEMINI_KEY` in `/etc/example/web-source.env` (env-first, then `~/.config/otb/gemini-shared.json#api_key` for local dev) — the exact pattern `auth.js` already uses for the GitHub/Discord secrets (`src/bongos/art-key.js`). It is **never** written to the database or its backups, so a DB dump is never a key-disclosure event.
+
+2. **Entitlement = `xenos` only, server-enforced.** `GET /api/gds/me/art-key` (`src/bongos/routes/me.js`) reads the builder's live rank and returns `{ entitled, configured, reason, shared_key }`. The secret is attached **only** when `entitled && configured`. The boundary is a single named constant `SHARED_ART_KEY_MAX_TIER = REQUIRES_RANK_TIER.xenos`, so widening it later (e.g. "any builder without their own key") is a one-line change. Thetes+ get a `200` with `entitled:false` — **not** a 403 — so the client can tell "withdraw the key" apart from an auth failure.
+
+3. **Delivery = a distinct, self-healing session slot.** A SessionStart sync (`scripts/gds/fetch-art-key.js`, a port of `fetch-sound-prefs.js`) calls the endpoint each session and writes/removes a **new** `shared_gemini_api_key` field in `~/.config/otb/gds-session.json` — separate from the builder's own `gemini_api_key`, so "ours" and "theirs" never blur. Re-deriving it every session means promotion to Thetes automatically withdraws the key on the next session start; `setup.js` also fetches it once at onboarding so the first task works immediately.
+
+4. **Resolution = own key always wins.** `gen_api.py` gains one tier, slotted **below** the builder's own key and **above** the manual dotenv fallbacks: `env → own (gds) → own (pms) → shared (gds) → ~/.config/otb/env → .env.local`. A builder who sets their own key is never affected; the shared key is only ever a floor.
+
+5. **Attribution.** `gen_api.api_key_source()` returns `own|shared|env|dotenv`, and `cost_ledger.log_call` stamps it as `key_source` on each row, so shared-key spend (the org's dime) is distinguishable from own-key spend on the cost dashboard.
+
+## Consequences
+
+- **Trust widening, bounded deliberately.** We hand a paid key to a low-trust newcomer (it lands in their mode-600 session file, the same tier as their GitHub token). A `xenos` could extract it and run up spend outside the pipeline. We accept this for newcomers and bound the blast radius by: (a) recommending a **dedicated** key with a Google-side **billing/quota cap** ([blocker for the owner](../../blockers/blockers.md)); (b) the server-side rank gate; (c) trivial rotation (change one env var, redeploy). The key is never logged and the endpoint is `no-store`.
+- **Ships safely before the key exists.** With `SHARED_ART_GEMINI_KEY` unset the endpoint returns `configured:false` and nothing changes for anyone — newcomers see today's behavior. Provisioning is decoupled from the code landing.
+- **No schema change.** Entitlement is computed from the existing `builders.rank`; no migration, no encryption layer, nothing in `migrations/`.
+
+## Alternatives considered
+
+- **Encrypted key in the DB + an Archon paste-in-browser UI.** More owner-friendly (no SSH) but adds an encryption layer, a migration, and a web surface, and puts the secret in the DB/backups. Rejected by the owner in favor of the server-secret-file path (simplest, most secure, matches every other secret on the project).
+- **Reuse the existing `~/.config/otb/env` shared slot for delivery.** Zero pipeline change, but it's a plain shared dotenv that an operator may have set by hand — the sync could clobber a deliberate choice, and it can't cleanly distinguish "GDS-delivered" from "manual." Rejected for the dedicated, self-healing `shared_gemini_api_key` session field.

package/docs/adr/0069-hall-live-channel-sse-decouple.md

@@ -0,0 +1,35 @@
+# ADR 0069 — Builders-hall live updates move from Colyseus WebSocket to SSE
+
+- **Status:** Accepted
+- **Date:** 2026-06-20
+- **Deciders:** task [#1194](https://example.com/builders#/task/1194) (V4.R55) — part of the Cloud Bongos standalone-instance work (C8, [ADR 0062](<redacted>.md))
+- **Track:** `internal` (the builders hall)
+- **Supersedes:** the *transport* decision of [ADR 0030](<redacted>.md) §2 (WebSocket/Colyseus). The change-signal layer of ADR 0030 (Postgres `NOTIFY` + `src/bongos/live-channel.js`) is **unchanged** and still authoritative.
+
+## Context
+
+[ADR 0030](<redacted>.md) gave the hall live updates in two layers: a transport-agnostic change-signal (a statement-level `NOTIFY` trigger relayed by one persistent `LISTEN` connection in `live-channel.js`) and a **delivery transport** — a broadcast-only Colyseus room (`builders_hall`) riding the game's existing WebSocket server. ADR 0030 explicitly considered SSE, called it "arguably the textbook fit for a receive-only dashboard," and rejected it for one reason only: to **reuse the game's already-proxy-proven Colyseus stack** rather than stand up a second long-lived-connection mechanism.
+
+That reason is exactly what the Cloud Bongos decoupling (C8) removes. The GDS-only entrypoint (`src/platform-server.js`, [R51](<redacted>.md)) boots the build platform with **no Colyseus in the process**. A `builders_hall` room cannot exist there, so on a game-less instance the hall's only live feature was dead — it would freeze at load exactly as it did before ADR 0030. The transport was load-bearing on the game runtime, which a standalone Cloud Bongos instance does not have.
+
+## Decision
+
+Move the hall live transport to **Server-Sent Events**: `GET /api/gds/live` (`src/bongos/routes/live.js`), mounted **unconditionally** in the GDS router (`buildGdsRouter`). Because that router mounts in *both* entrypoints (`server.js` and `platform-server.js`), the hall refreshes live whether or not the game is in the process — which is the R55 done-when.
+
+- **Signal layer untouched.** The endpoint `subscribe()`s to the same `live-channel.js` relay the room used. Triggers, channel, and fan-out logic are identical (ADR 0030 §1 still governs them).
+- **Same zero-leak contract.** It emits an opaque `nudge` event with an empty `{}` body — never the relay's `{table, op}` (leaking internal table names was a hacker-dispatch finding on [#569](https://example.com/builders#/task/569)). The hall re-runs its authenticated per-panel fetches on any nudge, so access control stays where the data is.
+- **Auth + abuse control.** `requireBuilder` gates the stream (mirrors the room's [#983](https://example.com/builders#/task/983) signed-in requirement; the `gds_session` cookie rides the same-origin `EventSource` GET). A per-IP concurrent-connection cap is kept **inline** in the route — deliberately *not* imported from `src/rooms/hall-join-guard.js` — so the GDS live channel carries **zero game-code dependency**, which is the point of R55.
+- **Client simplifies.** `public-builders/builders.js` opens an `EventSource` instead of joining a Colyseus room. `EventSource` reconnects natively, so the manual 4 s rejoin backoff is gone; the debounced `loadAll()`, the don't-clobber-active-input guard, and the `visibilitychange` backstop are kept. The hall no longer loads `/vendor/colyseus.js`.
+- **Dead code removed.** `src/rooms/BuildersHallRoom.js`, `src/rooms/hall-join-guard.js`, and `tests/builders_hall_room.mjs` are deleted; `server.js` no longer defines `builders_hall`. The game still serves `/vendor/colyseus.js` for itself — only the hall stopped depending on it.
+
+## Alternatives considered
+
+- **Keep the Colyseus room AND add SSE (pick per boot).** Rejected: it leaves two parallel live mechanisms — precisely the "second long-lived-connection style" ADR 0030 wanted to avoid — and doubles the maintenance surface for a tiny internal feature. SSE works in both boots, so the room is pure dead weight after the client rewire.
+- **A raw `ws` endpoint instead of SSE.** Rejected: the channel is strictly receive-only, so WebSocket's bidirectionality buys nothing, and `ws` would reintroduce a long-lived-connection lib and a hand-rolled reconnect/heartbeat the browser's `EventSource` gives for free.
+
+## Consequences
+
+- The hall is live on a game-less Cloud Bongos boot — the executable R55 done-when lives in `tests/platform_boot.mjs` (`GET /api/gds/live` is mounted + auth-gated, not 404) and `tests/live_sse.mjs` (SSE framing, bare-nudge no-leak, per-IP cap).
+- One fewer long-lived-connection style on the internal surface; the hall's realtime path no longer touches the game runtime.
+- SSE must traverse Caddy → Cloudflare. It rides plain HTTP with `Cache-Control: no-cache, no-transform` + `X-Accel-Buffering: no`, and a 25 s heartbeat comment keeps the stream under Cloudflare's ~100 s idle timeout.
+- If a future change ever puts row data on this channel, the `requireBuilder` gate already in place must stay (ADR 0030's "add an `onAuth` gate first" caveat is satisfied by construction here).

package/docs/adr/0070-deterministic-session-card-delivery.md

@@ -0,0 +1,44 @@
+# ADR 0070 — Deterministic delivery of in-session cards (hook-delivered, read-only vs mutating)
+
+- **Status:** Accepted
+- **Date:** 2026-06-20
+- **Track:** internal
+- **Builds on:** the deterministic-card lineage — task 1273 (script owns the card markup, same shape every session), task 1279 (per-builder "render widgets" knob; OFF ⇒ no HTML), task 1282 (in-band `[otb-card]` relay directive so the contract doesn't live only in the skill). Hook discipline mirrors [`.claude/hooks/conductor.js`](../../.claude/hooks/conductor.js) (the `UserPromptSubmit` MAS Conductor, [ADR 0024](<redacted>.md)).
+- **Task:** [#1288](https://example.com/builders#/task/1288)
+
+## Context
+
+A session review found the `/builder-start` "pane" rendering unreliably. The card's *content* had been deterministic since tasks 1273/1279/1282 — `start.js` owns the markup — but its *delivery* was not. The skill asked the model to run a multi-step routine every session: detect whether `show_widget` exists → call `read_me` → run the script → branch on the first character of stdout → parse stderr directives → render. Every step is a place a probabilistic model can diverge.
+
+The sharpest failure is structural, not behavioral. The exported session ran on a **cloud/remote** surface where the `mcp__visualize` server (which provides `show_widget`/`read_me`) **was not present at all** — so the skill's documented "normal case in the app" path was impossible, and the model either called a missing tool or dumped raw HTML as text. The same class of miss happens whenever the model "summarizes" instead of relaying.
+
+We confirmed the hook boundary against the Claude Code docs:
+
+- A hook **cannot** render UI or call an MCP tool (`show_widget`), and **cannot** detect which tools/MCP servers exist in the session (no tool manifest reaches a hook). Only the model can emit the visible card, and only the model knows its own tool set.
+- `UserPromptSubmit` (and `SessionStart`/`UserPromptExpansion`) inject **stdout as context**; `PostToolUse` injects model-visible context via **`hookSpecificOutput.additionalContext`** (placed next to the tool result, read on the next model request).
+
+So fully-deterministic *pixels* are not achievable today. The achievable win is to move the deterministic 5 of the 6 steps **out of the model and into a hook**, leaving the model only the irreducible "emit" step — with the finished card and a one-step directive handed to it.
+
+## Decision
+
+Make card **delivery** deterministic via hooks, and split the vehicle by whether the owning script **mutates state** — because that determines whether a hook may run it.
+
+1. **Read-only cards** (`/builder-start`, `/status`; future: `/recall`) → **[`session-cards.js`](../../.claude/hooks/session-cards.js)**, a `UserPromptSubmit` hook. On a matching intent it runs the script's `--hook` mode, which emits a one-fetch JSON envelope `{widgets_enabled, html, markdown, warnings}`, and injects the finished card + a one-step "render this once" directive. Registry-driven: adding a read-only card is one `CARDS` entry (a matcher, a script, an arg-extractor). Safe to pre-run because these scripts only fetch + render.
+
+2. **Mutating / lifecycle cards** (`/builder-claim`, `/builder-ship`; `release` matched, emits none today) → **[`lifecycle-card.js`](../../.claude/hooks/lifecycle-card.js)**, a `PostToolUse`/Bash hook. These **must never be pre-run** — claiming or shipping as a side effect of merely typing would be catastrophic. Instead the model runs the script itself; the hook fires immediately after, reads the `[otb-card-html] <path>` marker the shared emitter ([`src/bongos/ship-card.js`](../../src/bongos/ship-card.js)) wrote, reads that file, and injects the card + directive next to the tool result.
+
+Both hooks honor the task-1279 widgets knob (OFF ⇒ no HTML injected, the plain-text card stands), carry **exactly two** fence markers around each payload (no extraction ambiguity), and follow the standard hook discipline: silent-fail (any miss/parse/IO error → exit 0, no output), zero model calls, a kill-switch (`OTB_SESSION_CARDS_OFF`) and the `OTB_SUBAGENT` guard. The skills (`builder-start`, `status`, `builder-claim`, `builder-ship`) are slimmed to **defer to the injected directive**, keeping their old run-the-script logic as the fallback when no directive appears (hook disabled, an older checkout, or a silent failure).
+
+## Consequences
+
+- **Reliability up across every surface.** The card data + render instruction reach the model deterministically on app, cloud/remote, plain terminal, and cron — independent of whether `show_widget` exists. Where it doesn't, the directive says "paste the markdown," so the failure mode becomes a plain card instead of a broken widget or a raw-HTML dump.
+- **Interactivity preserved.** The rich, click-to-claim / click-to-drill widget still renders where `show_widget` exists; it's now a reliable enhancement rather than the sole, fragile path.
+- **The render is still a model action.** This is a hard platform limit — a hook can instruct but cannot force a tool call. Reliability equals the model's compliance with an unmissable, pre-computed instruction (high), not a hard guarantee. If a forced-render primitive ever exists, `/feedback` is the channel.
+- **Token cost.** When widgets are ON the hook injects both the HTML and the markdown form (it can't detect `show_widget`, so the model must be able to branch). Bounded: it fires only on an explicit card intent, not every prompt.
+- **`/status` gained a card.** It previously emitted freeform text the skill was told to "interpret + relay" (per-session improvisation); it now owns a deterministic widget + markdown card, and its stale default version was bumped `GDS-V3` → `GDS-V4` (GDS-V3 is closed).
+
+## Alternatives considered
+
+- **Bulletproof the skill only** (reword so markdown is the default, widget the exception). Improves the odds but leaves delivery a model decision — same failure class, just rarer. Rejected as a mitigation, not a fix; kept as the fallback layer.
+- **Auto-render at `SessionStart`.** Rejected: a builder runs many parallel sessions, so a card on every session open is noise. Delivery fires on explicit intent instead.
+- **One hook for both events.** Rejected: read-only (pre-run on intent) and mutating (post-run on tool use) have genuinely different trigger logic; two single-responsibility hooks read more clearly than one dispatching on `hook_event_name`.

package/docs/adr/0071-box-confirm-before-destroyed-and-drift-reconcile.md

@@ -0,0 +1,59 @@
+# ADR 0071 — Dev-box teardown confirms the droplet is gone before marking 'destroyed'; a bidirectional drift reconcile is the backstop
+
+**Date:** 2026-06-20
+**Context:** GDS / dev boxes, task [#1289](https://example.com/builders#/task/1289). Builds on [ADR 0031](<redacted>.md) (cloud dev environments) and [ADR 0053](0053-scoped-dev-box-session.md) (scoped dev-box session). Touches `scripts/gds/box.js`, `src/bongos/boxes.js`, `src/bongos/do-api.js`, `infra/box-drift-reconcile.{service,timer}`.
+**Status:** Accepted.
+**Track:** `internal` (development system / builder dev boxes).
+
+## Problem — the "zombie" box
+
+A dev box could reach GDS `box_state='destroyed'` while its DigitalOcean droplet kept **running and SSH-reachable**. Confirmed 2026-06-20 on `box-example-owner.dev.example.com` (builder LarsCode, xenos, id 3): `GET /api/gds/box/source-access` returned `403 {"reason":"NO_ACTIVE_BOX","box_state":"destroyed"}`, the box had no git `origin` remote, and it was frozen at an old commit — it could never pull new code again, which silently broke a newcomer feature (the box never fetched `scripts/gds/fetch-art-key.js`).
+
+The impact is three-fold: **cost** (a "destroyed" droplet keeps billing), **security** (a box the control plane considers gone is still SSH-reachable and holds a live session token + repo clone), and **UX** (every task on a zombie box silently fails because the code can't update — a baffling "it's just not working").
+
+### Root cause
+
+`deprovisionOne()` deleted the droplet with a swallowed error and then set `destroyed` unconditionally:
+
+```js
+if (box.droplet_id) await doApi.deleteDroplet(box.droplet_id).catch((e) => console.log(`  ⚠ droplet delete: ${e.message}`));
+// ...
+await boxes.setBoxState(pool, box.builder_id, 'destroyed', { droplet_id: null, ... });
+```
+
+A transient DO failure (API blip, rate limit, token issue) was logged and ignored; the row flipped to `destroyed` and **nulled `droplet_id`** — losing the only reference to a droplet that was still alive. Worse, `canTransition('deprovision','destroyed')` is `false`, so the existing tooling could never re-attempt the teardown: the zombie was unreachable by id, forever.
+
+## Decision
+
+### 1. Confirm-before-destroyed (the primary fix)
+
+The droplet delete is the **gate** for the `destroyed` transition. In `deprovisionOne()`:
+
+- Delete the droplet via an **idempotent, retried** helper (`deleteWithRetry`): a `404` means "already gone" = success; transient failures retry a few times.
+- If the delete genuinely fails after the retry budget, the box is parked at **`state='error'` with `droplet_id` PRESERVED** (not nulled) and an `error_note`, an `error` event is recorded, and the function **throws**. The row never reaches `destroyed` while a droplet is still alive.
+- Snapshot / Cloudflare-tunnel / DNS teardown stay best-effort (a leftover snapshot is cost-only; the droplet — the thing that bills and is SSH-reachable — is gone by then), but the snapshot delete is now idempotent too.
+
+This makes the DB row **truthful by construction**: `destroyed` now means "DO confirmed the droplet is gone."
+
+### 2. A bidirectional drift reconcile (the backstop)
+
+`box.js reconcile-drift` lists the real fleet droplets (`DoApi.listDroplets({ tag })` — a live read even in dry-run, since listing is non-mutating) and compares them to the GDS box rows via a pure `boxes.planDropletDrift()`:
+
+- **Zombie** — a droplet no live box row claims (row is `destroyed`/`error`/`none`, or its `droplet_id` was nulled) → force-delete the droplet + tear down its tunnel/DNS.
+- **Ghost** — a box row in a droplet-holding state whose `droplet_id` is gone from DO → mark `destroyed` (clearing the dead `droplet_id` + SSH host keys per idea 310) so the DB stops claiming a running box.
+
+An **in-flight guard** protects provisions: a droplet created within `minAgeMinutes` (default 30) is never treated as a zombie — its box may still be `provisioning` (the row's `droplet_id` isn't written until the droplet settles `active`). Skipped-young droplets are reported, never deleted.
+
+Dry-run is the default; `--apply` executes. A new hourly timer (`infra/box-drift-reconcile.{service,timer}`) runs it `--apply` so drift self-heals hands-off — hourly because a zombie bills continuously, so the daily dormant sweep is far too slow to catch one.
+
+## Alternatives considered
+
+- **Poll `getDroplet` until 404 after the DELETE.** Stronger confirmation, but adds latency + API calls; the DELETE returning 204/404 is sufficient acceptance, and `reconcile-drift` is the backstop for anything that still slips through. Rejected as over-engineering.
+- **Box-side self-termination on `NO_ACTIVE_BOX`.** A box *cannot* delete its own droplet (no DO token; the builder firewall doesn't allow-list the DO API), and `poweroff` does **not** stop DigitalOcean billing. So self-termination can't actually reclaim the droplet — only the control-plane reconcile can. The box-side loop is harmless churn; we left `box-source-fetch.sh` unchanged rather than touch a fleet-auto-installed, permission-path-sensitive script ([ADR 0043](<redacted>.md)) for no real gain.
+- **Reconcile snapshots too.** Out of scope: a leaked snapshot is ~$0.30/mo, not SSH-reachable, and not the reported bug. The reconcile is droplet-focused, matching the task.
+
+## Consequences
+
+- A failed teardown is now **visible** (`state='error'`, queryable) instead of a silent zombie, and self-heals on the next reconcile tick or `box.js deprovision`.
+- One new operator step: `systemctl enable --now box-drift-reconcile.timer` on the prod droplet (mirrors the idle/dormant sweep units). `reconcile-drift` requires `DO_API_TOKEN` (always present in `/etc/example/box.env`).
+- Pure decision (`planDropletDrift`) + idempotent delete (`deleteWithRetry`) are unit-tested hermetically in `tests/boxes.mjs` (no DO, DB, or clock).

package/docs/adr/0072-bongos-app-mac-signed-first-windows-deferred.md

@@ -0,0 +1,35 @@
+# ADR 0072 — Bongos app ships Mac-signed + notarized first; Windows code signing deferred (reuse the Dev Box app's signing posture)
+
+**Date:** 2026-06-20
+**Context:** Bongos App `BONGOS-V1` / criterion C1 (signed-installable), task [#1296](https://example.com/builders#/task/1296) (`BV1.R01`). Builds on [ADR 0045](<redacted>.md) (the Dev Box desktop app) and [ADR 0004](0004-example-name-and-trademark-acceptance.md) (brand discipline). The bongos app forks the Dev Box app's Electron shell ([#1298](https://example.com/builders#/task/1298) `BV1.R03`), so it inherits that app's signing machinery; this ADR pins which parts it inherits now and which it defers.
+**Status:** Accepted.
+**Track:** `internal` (development system → the Cloud Bongos desktop app line; bongos succeeds the GDS after GDS-V4).
+
+## Problem — an unsigned mic + screen app reads as hostile
+
+Bongos is a floating OS toolbar that asks for **Screen Recording + Microphone** on first run. An unsigned app making those requests is treated as hostile by the OS: on macOS the permission grants may not persist across launches (and arm64 won't launch at all without at least an ad-hoc signature), and on Windows SmartScreen blocks the first launch outright. So a code-signing path is a launch gate, and `R01` exists to **decide** that path up front so packaging (`R15`/`R16`) is unblocked — not to leave it open until packaging time.
+
+The Dev Box app already walked this road ([ADR 0045](<redacted>.md)):
+
+- **macOS — solved and wired.** `.github/workflows/build-devbox-app.yml` carries an *inert-until-armed* Mac signing block: with no secrets it builds unsigned (ad-hoc); arming is purely adding repo secrets (`MAC_CSC_LINK` + `MAC_CSC_KEY_PASSWORD`, plus optional `MAC_NOTARIZE_*` for notarization) — no workflow edit. The secrets are bound to the cert env vars **only on the trusted `main` ref** (the SR-13/SR-14 hardening, [#993](https://example.com/builders#/task/993)) so a `claude/**` feature branch can never exfiltrate the Developer ID cert. A post-build `dmgbuild` re-package (task [#1235](https://example.com/builders#/task/1235)) preserves notarization while fixing the install-window backdrop.
+- **Windows — never resolved.** Windows signing stays unwired pending a cert-vendor decision: blocker [#20](https://example.com/builders#/blocker/20) (Azure Trusted Signing vs. a traditional EV cert). Today Dev Box Windows users get the SmartScreen "More info → Run anyway" first-run friction, documented in the hall onboarding copy.
+
+(The committed `devbox-app/electron-builder.yml` header comment still says "no Apple Developer ID… in the budget yet." That comment is **stale** — the CI workflow is the live truth, and the only signing blocker still open is the Windows-only [#20](https://example.com/builders#/blocker/20). Corrected as a side-note below.)
+
+## Decision (owner — Lars)
+
+**Ship the bongos app Mac-signed + notarized only at first; defer Windows code signing — the same posture as the Dev Box app.** Concretely:
+
+1. **macOS — reuse the Dev Box app's signing identity verbatim.** No new Apple Developer ID, no separate cert. The bongos build workflow (authored in `R15`/`R16`) copies the Dev Box app's inert-until-armed Mac block — `CSC_LINK` / `CSC_KEY_PASSWORD` + `APPLE_ID` / `APPLE_APP_SPECIFIC_PASSWORD` / `APPLE_TEAM_ID`, **`main`-ref-gated** per SR-13/SR-14 — so the same Developer ID that signs Dev Box signs bongos. Sign **and** notarize for a Gatekeeper-clean first launch.
+2. **Windows — defer, do not block V1.** Bongos does **not** acquire a Windows code-signing cert as part of `BONGOS-V1`. It ships either Mac-only at first, or with an **unsigned** Windows build carrying the same "More info → Run anyway" onboarding copy the Dev Box app uses. Windows signing rides the **existing** decision in blocker [#20](https://example.com/builders#/blocker/20) — there is no separate bongos Windows-cert decision and no new spend now.
+3. **One cert decision, two apps.** When blocker [#20](https://example.com/builders#/blocker/20) resolves (Azure Trusted Signing vs. EV) it resolves for **both** apps at once — the absorbed Dev Box module and the bongos toolbar share the umbrella app's installer ([#1298](https://example.com/builders#/task/1298)), so Windows signing arms once for the whole umbrella.
+
+This satisfies `R01`'s done-when: the Windows approach is decided (explicit interim "Mac-signed only" recorded here), and the Mac path is confirmed to reuse the existing Dev Box Apple Developer ID rather than minting a new one.
+
+## Consequences
+
+- **`R15` (electron-builder signing config) and `R16` (branded download + updater) inherit the Dev Box pattern, not a fresh design.** They copy the inert-until-armed Mac block and its `main`-ref-only secret gating verbatim into the umbrella build workflow. Re-deriving signing from scratch in those tasks is wasted work — point them at `.github/workflows/build-devbox-app.yml` and this ADR.
+- **Budget: $0 new recurring cost from this decision.** It rides the Apple Developer ID already paid for Dev Box and explicitly declines a Windows cert for now (CLAUDE.md §4 — any new recurring cost needs the owner's go-ahead; this defers it).
+- **Windows users see first-run friction until [#20](https://example.com/builders#/blocker/20) resolves.** Acceptable for V1: the early audience is Mac-first (the owner + the existing Dev Box builders), and the SmartScreen "Run anyway" copy is already written and proven for Dev Box.
+- **The bongos app must not mint a second Apple Developer ID or duplicate the Mac signing block as a sibling.** Reuse is the rule — the umbrella app is one signed app ([#1298](https://example.com/builders#/task/1298)), one Developer ID, one notarization flow.
+- **Side-note / cleanup, not in scope here:** `devbox-app/electron-builder.yml`'s "UNSIGNED for now — no Apple Developer ID" header comment contradicts the armed CI workflow and the closed-Apple / open-Windows blocker state. Worth a one-line fix under a Dev Box-scoped claim; flagged, not done here (this is a `decision` task touching `bongos-app/`, not `devbox-app/`).

package/docs/adr/0072-dev-box-code-staleness-visibility.md

@@ -0,0 +1,39 @@
+# ADR 0072 — Dev-box code-staleness: make it visible, never auto-reset
+
+- **Status:** Accepted
+- **Date:** 2026-06-20
+- **Track:** internal
+- **Builds on:** [ADR 0031](<redacted>.md) (per-builder dev boxes), the `box-source-fetch.sh` self-update machinery ([#600](https://example.com/builders#/task/600), [#985](https://example.com/builders#/task/985)), and task [#1187](https://example.com/builders#/task/1187) (the box host-key reporter — the report-up cron pattern this mirrors)
+- **Task:** [#1316](https://example.com/builders#/task/1316) (from idea [#332](https://example.com/builders#/idea/332))
+
+## Context
+
+A builder (LarsCode) repeatedly hit cryptic dev-box failures: the shared Gemini art key never reached the box, and Claude Desktop connect failed with "host verification failed." Both traced to **one cause — the box was running stale code.** Its box was provisioned 2026-06-07, before two features existed: the shared-art-key delivery rail ([ADR 0068](<redacted>.md), `fetch-art-key.js` + the `gen_api.py` shared tier) and the host-key reporter ([#1187](https://example.com/builders#/task/1187)).
+
+Investigation refined the problem. Boxes **already auto-update**: `infra/box-source-fetch.sh` runs every ~10 min and `git pull --ff-only`s `/workspace`, *and* self-updates its own baked scripts/crons ([#985](https://example.com/builders#/task/985)). So any box provisioned *after* that machinery landed self-heals. The residual gaps:
+
+1. A box provisioned **before** the self-update machinery has no self-update cron — it can never pull the fix, so it's stuck stale forever. Only a rebuild (deprovision → fresh provision) helps.
+2. When `pull --ff-only` can't fast-forward (a diverged/dirty tree), `box-source-fetch.sh` logs and leaves the tree as-is — stale, **silently**.
+3. **There was no visibility.** A stale box fails cryptically and the builder has no way to know the cause is old code.
+
+## Decision
+
+Add a **visibility** layer, not more auto-magic.
+
+- The box reports its `/workspace` HEAD commit (sha + commit date) via a new cron `infra/box-report-version.sh` → `POST /box/version` (`allowBoxScope`, own resource), wired into the existing `box-source-fetch.sh` self-heal cron list so current boxes pick it up with no re-provision. Migration 121 adds `code_sha` / `code_committed_at` / `code_reported_at` to `builder_boxes` (same report-up shape as the host-keys columns, migration 105).
+- The server computes staleness (`boxes.computeCodeStaleness`, pure + unit-tested) by comparing the box's reported commit date to the server's **own deployed commit date** (`src/build-info.js` `commitDate`). A box is stale when it's > 2 days behind, **or** when an active box past a 30-min provision grace has **never reported a version** — which is exactly the signature of a box too old to even run the reporter (the ancient pre-machinery box).
+- Surfaced on `GET /box/me` and the `/boxes` Archon roster (via the shared `publicBox` projection), and rendered in the hall as an amber "This box is running old code — Close box, then provision a fresh one to update" banner (`public-builders/box-panel.js`), pointing at the existing Close-box affordance.
+
+### Why visibility, not auto-reset
+
+The tempting "durable fix" is to have the box force itself current (`git reset --hard origin/main`). **Rejected:** a dev box holds the builder's in-progress, uncommitted work. Auto-resetting would silently destroy it — a far worse failure than running slightly old code. `box-source-fetch.sh` already makes the safe move (`pull --ff-only`, which refuses to clobber). When that can't fast-forward, the right answer is to *tell the builder* (so they can commit/stash and rebuild), not to overwrite their tree. Rebuild is the builder's explicit, informed choice.
+
+### Why a rebuild is the only fix for ancient boxes
+
+A box that predates the self-update machinery has no mechanism to pull the fix — including no mechanism to pull *this* reporter. So it never reports, the server flags it stale on the "never reported while active" rule, and the surfaced remedy is a rebuild (Close box → provision fresh, which re-clones current `main` from cloud-init). There is no in-place path; that's inherent, and the flag makes it visible instead of cryptic.
+
+## Consequences
+
+- Stale boxes become **visible and self-explanatory** instead of failing cryptically. Going forward, post-machinery boxes self-update; the flag catches the legacy stragglers and any box whose pull has silently wedged.
+- Thresholds (30-min grace, 2-day lag) live in code with the tests, not the schema — tunable without a migration. The 2-day window is deliberately generous so a box mid-pull right after a deploy is never false-flagged; the target is weeks-stale boxes.
+- **Follow-ups (out of scope here):** surfacing the same flag in the Dev Box Electron app (a separate release artifact); and optionally a one-click "rebuild" in the hall (today it's the existing Close box → provision).