@bongos/core 1.17.0

package/docs/adr/0073-builder-needs-signal-and-byok-gemini-key.md

@@ -0,0 +1,64 @@
+# ADR 0073 — A consistent "the system needs an input from you" signal, and pragmatic BYOK for the per-builder Gemini key
+
+- **Status:** Accepted
+- **Date:** 2026-06-20
+- **Track:** internal
+- **Builds on:** [ADR 0068](<redacted>.md) (the shared newcomer key — this is the Phase 2 it explicitly deferred), [ADR 0016](<redacted>.md) (rank enforced server-side, no caching — the entitlement axis here), [ADR 0054](<redacted>.md) (cost-plus economics — *we pay up front* for newcomers, builders pay their own bill after)
+- **Task:** [#1013](https://example.com/builders#/task/1013)
+
+## Context
+
+[ADR 0068](<redacted>.md) shipped the *infrastructure* that hands a shared Gemini key to newcomers (rank `xenos`) so their first art task works — **we pay up front.** It closed by naming the deferred half:
+
+> 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.
+
+This ADR is that Phase 2. Two problems remained:
+
+1. **Nothing told the builder anything.** A newcomer never learned we were covering their art spend; a builder who graduated to Thetes (when the shared key is withdrawn) was never told they now need their own key — their next art task just failed. The owner framed the real need broadly: *we want one consistent way to flag to a builder that the system needs a specific input from them to run* — not a one-off banner bolted onto the Gemini case.
+2. **The own key was CLI-only and local-only.** A builder's own Gemini key could only be entered during `/builder-setup` and lived only in `~/.config/otb/gds-session.json#gemini_api_key`. A browser-first / non-technical builder had no way to set it and was never told they needed one — and per the `feedback_auth_flows_ui_first` rule, a non-technical builder must be able to do credential setup with browser clicks alone.
+
+## Decision
+
+Two coupled pieces: a **reusable signal** (the general mechanism the owner asked for) and **pragmatic BYOK** (the specific input it first carries).
+
+### 1. The `needs` signal — one consistent way to flag a required input
+
+A new pure module, [`src/bongos/builder-needs.js`](../../src/bongos/builder-needs.js), is a small **registry**. Each thing the system needs from a builder to run a capability — today the Gemini image key; tomorrow a Stripe key, a first-party Anthropic link, … — is one `(ctx) => need|null` entry. The server computes the live list on `GET /api/gds/me` (`needs: { items, action_needed_count, has_action_needed }`); every surface renders the **same** shape. Adding a future input is one registry entry — the renderers don't change.
+
+A need is always in exactly one of three states:
+
+| State | Meaning | How it surfaces |
+|---|---|---|
+| `covered` | The system is handling it for them right now — nothing to do. | Calm note (the "we cover it" line for newcomers). |
+| `action_needed` | The system needs the input **now** or a capability won't run. | Loud: amber banner + action button (hall), one line at session start (CLI), and a friendly stop at point-of-use. |
+| `satisfied` | They've provided it. | Quiet (✓) or nothing. |
+
+Three renderers consume the one data shape:
+
+- **Hall Standing card** ([`public-builders/builders.js`](../../public-builders/builders.js)) — an "Action needed" / "we cover it" banner, same grid slot + warm/amber tones as the budget banner ([ADR 0054]/C3).
+- **CLI session nudge** (`printNeedsNudge` in [`scripts/gds/cli-lib.js`](../../scripts/gds/cli-lib.js), called by `/builder-start`) — one line per `action_needed` item, on the builder's private surface (mirrors `printCostWarning`).
+- **Point-of-use stop** — the art pipeline's "no key" error ([`art/pipeline/gen_api.py`](../../art/pipeline/gen_api.py)) now points at the web Settings page first.
+
+The owner picked "visible **and** block-at-use" (the builder can't miss it or hit a confusing failure), with newcomer coverage copy that **foreshadows the hand-off** so the later `action_needed` is never a surprise.
+
+### 2. Pragmatic BYOK — the own Gemini key, server-stored and synced
+
+The own key moves from local-file-only to **encrypted server storage that becomes the source of truth**, managed in the hall Settings page, synced down to the builder's own machine at session start — the same rail [ADR 0068](<redacted>.md) built for the shared key.
+
+- **Encrypted at rest** ([`src/bongos/secret-box.js`](../../src/bongos/secret-box.js)): AES-256-GCM, master key (`BUILDER_SECRET_KEY`) in **server env only** — never the DB, never the repo — so a DB dump alone can't decrypt. Migration 122 adds `gemini_key_enc` / `gemini_key_last4` / `gemini_key_set_at` to `builders`. Fails **closed**: no/invalid master key → set-key 503s, the feature stays dark (exactly the [ADR 0068] rollout shape).
+- **Write-only Settings UI** (`GET/PUT/DELETE /api/gds/me/art-key/own`): set / replace / remove; masked (last-4) after save, like GitHub/Stripe; a get-one link; "needed only if you generate art." Own-scoped — a builder reads/writes only their own key.
+- **Validate on save**: one cheap, non-billable call to Google (list models) catches a typo. A *network* failure on our side does not block the save (`validated:false`).
+- **Box sync** (`scripts/gds/fetch-art-key.js`, already wired into SessionStart): the own key lands in the local `gemini_api_key` slot — which already wins over the shared key in the pipeline cascade — tagged `_managed` so removing it on the server withdraws *our* copy without clobbering a legacy hand-entered local key.
+
+### Why server-stored (not local-only, not a server-side proxy)
+
+- A web form can't write a file on the builder's box, and the box runs the pipeline — so for UI-first entry the server must hold and deliver the key.
+- A server-side proxy would mean moving art generation onto the droplet (cost + latency on us) and would break per-builder cost attribution (the C3 property: each pays their own Google bill). Rejected.
+- The one new risk — the server holds N builder keys so it can sync them — is contained by encryption-at-rest with an env-only master key.
+
+## Consequences
+
+- **One pattern for "we need input from you."** Future credentials/links register one `needs` entry and inherit all three surfaces. This is the durable win; the Gemini key is just its first consumer.
+- **A new server secret.** `BUILDER_SECRET_KEY` (32 bytes, hex or base64) must be set in `/etc/example/web-source.env` on the droplet before the own-key feature works — see the linked blocker. Until then: newcomers stay covered, the Settings card shows a "being set up" notice, no plaintext is ever stored.
+- **Legacy local-only keys keep working.** A builder who only ever set a key via the CLI (server has none) is untouched by the sync; they'll see one mild "add your key" nudge until they re-enter it in Settings (one-time), at which point the server becomes the source of truth.
+- **The `satisfied` state is server-knowable only for server-stored keys.** A Thetes+ builder with a working *local-only* legacy key shows as `action_needed` until they re-save it in Settings. Accepted: the population is tiny and the nudge is mild.

package/docs/adr/0073-secrets-scan-exclude-uri-detector.md

@@ -0,0 +1,37 @@
+# ADR 0073 — The secrets scan excludes TruffleHog's generic URI detector
+
+**Date:** 2026-06-20
+**Context:** Secrets-scanning gate (`.github/workflows/secrets-scan.yml` + the `.husky/pre-commit` early-catch). Tasks [#1318](https://example.com/builders#/task/1318) and [#1320](https://example.com/builders#/task/1320). Relates to [ADR 0022](0022-secrets-policy.md) (secrets policy) and [ADR 0071](<redacted>.md) (dev-box teardown — the trigger).
+**Status:** Accepted.
+**Track:** `internal` (development system / CI gates).
+
+## Problem — a noisy detector turned a green gate red repo-wide
+
+The CI gate runs `trufflehog git` over the branch's **full history** with `--results=verified,unknown --fail`. TruffleHog's generic **URI** detector flags any `scheme://<userinfo>@host` string as an embedded credential. Two things in this repo match that shape and are **not** secrets:
+
+1. **A rejection-test fixture** — `tests/box_terminal_ssrf.mjs` asserts the SSRF guard *rejects* terminal URLs that carry userinfo credentials, so the fixtures contain exactly that shape on purpose.
+2. **Per-builder tunnel hostnames** that no longer resolve. The detector "verifies" a URI by DNS/connection; an unresolvable host yields an `unknown` (unverifiable) result, which `--results=verified,unknown` reports.
+
+This was latent until 2026-06-20: when a builder's dev box was torn down ([ADR 0071](<redacted>.md)) its tunnel host stopped resolving, flipping the fixture's result to a gating failure — reddening **every** PR built off `main` (caught while landing Bongos `R01`, task [#1296](https://example.com/builders#/task/1296)).
+
+The first attempt (task [#1318](https://example.com/builders#/task/1318)) added the fixture file to `--exclude-paths`. That failed for two compounding reasons, and is the load-bearing lesson here:
+
+- **TruffleHog scans commit messages, not just file contents.** `--exclude-paths` filters by file path; it has no effect on a finding that lives in a commit message.
+- The [#1318](https://example.com/builders#/task/1318) fix **quoted the offending URL in its own commit message** (and in an allowlist comment). That commit is now permanent in `main`'s history, so a path exclude can never suppress it.
+
+## Decision
+
+Exclude the **URI** detector from both scan surfaces: add `--exclude-detectors=URI` to the CI `trufflehog git` invocation and to the `.husky/pre-commit` `trufflehog filesystem` invocation. Remove the [#1318](https://example.com/builders#/task/1318) path-allowlist entry (superseded; its comment also carried the offending shape).
+
+**This loses no meaningful coverage.** The high-value credentials-in-URL case — database connection strings (`postgres://`, `mysql://`, `redis://`, `mongodb://`, JDBC, …) — is caught by TruffleHog's **dedicated** connection-string detectors, which remain enabled. Verified locally (TruffleHog 3.95.6): a Postgres connection string with a password is still detected with the URI detector excluded. The generic URI detector adds only <redacted> matching, whose signal here is dominated by test fixtures and documentation.
+
+**Operational rules that fall out of this:**
+
+- **Keep commit messages free of credential-shaped URLs.** The scan reads them; history is immutable. Describe such strings in prose, never paste them.
+- **A noisy detector is excluded at the detector level, not by path-allowlisting individual files** — path excludes cannot reach commit-message or cross-file recurrences of the same shape.
+
+## Consequences
+
+- The gate is green repo-wide again; the permanent commit-message false positive in the [#1318](https://example.com/builders#/task/1318) fix commit is neutralized without rewriting `main`'s history.
+- A real credential embedded in a *non-database* URL (e.g. `<redacted>) would no longer be flagged by the URI detector. Judged acceptable: that pattern is rare in this codebase, the dedicated detectors cover the common high-value cases, and the alternative (per-host regex allowlists that every new dev-box hostname must be added to) is more fragile.
+- Revisit if TruffleHog gains a way to scope a detector by path/ref, or a finding-level (not path-level) allowlist — that would let us re-enable URI with the fixtures suppressed surgically.

package/docs/adr/0074-memory-map-stays-light.md

@@ -0,0 +1,32 @@
+# ADR 0074 — The memory map stays light (budget guard + auto-tidy + drawer)
+
+**Status:** Accepted (2026-06-20) · task [#1362](https://example.com/builders#/task/1362)
+
+## Context
+
+A builder's durable memory is two layers:
+
+- **The map** — `MEMORY.md` (`~/.claude/projects/<proj>/memory/`). The Claude Code harness loads it **in full at the start of every session**. By design it's an *index*: one line per memory — title + pointer + a one-line hook, just enough to judge relevance.
+- **The drawer** — the per-topic `*.md` files holding the full facts. They sync to the GDS server (`builder_memory`, via `ship.js`/`pull-memory.js`) and are indexed by `/recall` (ADR 0060). They cost **zero** session tokens until something fetches them.
+
+Only the map is paid for every session, so it must stay small. But nothing kept it small: every session that wrote a memory appended a line, and the "≤200-char, one-line" rule was unenforced. The map re-bloated (entries ballooned into full paragraphs) until the harness's ~24.4 KB hard limit silently **truncated** it — i.e. it started dropping information, undetected. The token-cost audit (tasks 1283/1285/1286) compressed it once by hand, but a one-time fix doesn't hold.
+
+The relevance-fetch half of "load only what's relevant" already exists — `/recall` searches the server memory, and `recall-hints.js` surfaces task-relevant memories at session start for an active claim. The missing piece was keeping the always-loaded map itself light, automatically.
+
+## Decision
+
+Make the map self-maintaining, in `scripts/gds/memory-map.js` (pure, tested) driven from the session-start hook `.claude/hooks/pull-memory.js`:
+
+1. **Guard** — measure `MEMORY.md` each session start; emit one warning line when it's over a soft byte budget *or* has over-long index lines. Silent when healthy.
+2. **Auto-tidy** — when it crosses a higher threshold, **demote** the oldest non-rule entries until back under target. *Demote = remove the entry's line from `MEMORY.md` only.* The topic file is untouched — still on disk, on the server, and in `/recall`. Nothing is deleted; cold memories are one query away.
+3. **Keep-always** — standing rules (`feedback_*` / `type: user`) and any entry with `pin: true` in its frontmatter are never demoted, regardless of age. Pinning is how the live-version pointer and standing security alerts stay on the map even when they aren't the newest.
+4. **Parallel-safe write** — the builder runs many concurrent sessions, so the rewrite is optimistic: re-read just before writing and skip if the file changed since (another session's edit is never clobbered; it tidies next session).
+
+Budgets are tunable constants in `memory-map.js` (`WARN_BYTES`, `TIDY_BYTES`, `TARGET_BYTES`, `MAX_LINE_CHARS`, `KEEP_NEWEST`).
+
+## Consequences
+
+- The always-loaded cost stays bounded automatically; truncation can't sneak up.
+- "Newest + rules + pinned" is a deliberately simple relevance proxy. It can demote a still-useful old note — acceptable because demotion is lossless and `/recall` resurfaces it on demand. Pinning is the escape hatch for evergreen entries.
+- `.claude/hooks/` is a gate hard-floor, so changes here ship via an owner-approved Gate PR (ADR 0043) — the heavy logic lives in `scripts/gds/memory-map.js` (not a hard floor) to keep the hook diff minimal.
+- Future refinement (not built here): a `/memory-compact` skill + a BFG hygiene pass (ADR 0026) that scores relevance richer than recency.

package/docs/adr/0075-per-system-cost-attribution.md

@@ -0,0 +1,37 @@
+# ADR 0075 — Per-system cost attribution + the savings counterfactual ledger
+
+**Status:** Accepted (2026-06-20) · tasks [#1343](https://example.com/builders#/task/1343) [#1344](https://example.com/builders#/task/1344) [#1345](https://example.com/builders#/task/1345) [#1346](https://example.com/builders#/task/1346) · System 1 of the Cloud Bongos LLM-reduction redesign (spike [#1326](https://example.com/builders#/task/1326))
+
+## Context
+
+The 2026-06-20 efficiency audit ([`docs/audits/gds-efficiency-2026-06-20.md`](../audits/gds-efficiency-2026-06-20.md)) found real spend ~2× the annual budget, with **~82% concentrated in a few dozen Opus "marathon" sessions** whose cost is overwhelmingly `cache_read` (a growing context re-billed every turn for hours). But that finding was an **inference**: the ledger could not prove it, because `cost_log` lumped every LLM call into one untagged `amount_usd` row with no tier breakdown, and the price table had drifted to Opus 4.1 rates (3× too high). You cannot greenlight, tune, or defend a cut you cannot see — so the redesign's first system makes the spend *queryable per call-site and per tier*, and gives every later system a dollar-denominated place to prove its savings.
+
+## Decision
+
+Four shipped changes turn the inference into instrumentation:
+
+1. **1M-pricing correction (task 1343).** `llm-pricing.js` is corrected to the live Anthropic list rates — opus (4.8/4.7) **$5 in / $25 out**, sonnet (4.6) $3/$15, haiku (4.5) $1/$5 — **flat across the full 1M window with no long-context premium** (verified against the platform models/pricing page). There is deliberately **no `>200K` tier table**: do not add one unless Anthropic introduces a long-context surcharge. `priceUsage()` now also returns a per-tier `components` split (fresh input / cache-read / cache-write 5m+1h / output) that it previously computed and discarded.
+
+2. **Source taxonomy (task 1344).** The single legacy `source='session'` `cost_log` row is split into **two call-site-tagged rows per session**, distinct on the `(source, source_ref)` idempotency index:
+   - `session:<redacted> — the builder's own transcript (`source_ref = <session-id>`).
+   - `session:<redacted> — that session's ad-hoc Agent/Task subagents (`source_ref = <session-id>:sub`); grader-signature transcripts stay excluded (already captured via the [#486](https://example.com/builders#/task/486) worker envelope — the ADR 0028 non-double-count invariant).
+   - A **cron-launched** session sets `OTB_COST_CRON_ROUTINE=<name>`, so its rows are tagged `cron:<routine>:interactive` / `cron:<routine>:subagent`. Wiring each routine to export this var is follow-on (System 4); until then cron sessions fall back to `session:*`.
+
+   Each row carries a four-tier USD split persisted in new **nullable** `cost_log` columns (migration 123): `fresh_input_usd`, `cache_read_usd`, `cache_write_usd` (5m+1h summed), `output_usd`. For session/cron rows the four sum to `amount_usd` by construction; legacy and non-LLM rows (manual/infra/`box-lifecycle` compute) stay NULL.
+
+3. **The savings counterfactual ledger (task 1345).** A tiny new table `cost_baseline` (migration 124) is where each later system records what a run cost (`amount_usd`) versus what it *would* have cost had the system not acted (`baseline_usd`), tagged by `system`. **Contract: `baseline_usd` is ALWAYS computed server-side from real token counts via `priceUsage()` — never a client-supplied dollar figure** (the same trust rule as the cost-plus reward, ADR 0054). The saving is `SUM(baseline_usd − amount_usd)` grouped by system. `db.costSummary()` gains three **additive** blocks — `by_source`, `by_tier` (with the headline `cache_read_pct`), and `savings` — shaped by a pure, unit-tested module (`cost-summary-shape.js`).
+
+4. **Additive endpoint contract.** All of the above surfaces through the **unchanged** `GET /api/gds/public/cost-summary` passthrough: every pre-existing key keeps its exact shape; the new keys are added alongside. The `savings` query is guarded against a missing `cost_baseline` table (`42P01`) so a pre-migration window degrades to empty savings rather than 500ing the public status dashboard. The audit (`cost.js auditCostAttribution` / `formatAuditReport`, task 1346) folds in `by_source`, the `cache_read` share of LLM-priced spend, and per-system `eliminated_usd`, plus a **tripwire** (`savings_without_baseline`) that warns when a system appears in the savings ledger with no `priceUsage` baseline behind it — a saving that cannot be verified.
+
+## Consequences
+
+- The 82%-cache_read claim is now a column (`cost_log.cache_read_usd`) and a headline (`by_tier.cache_read_pct`), not an inference — the baseline System 2 reads and must move.
+- Every later system (2–5) reports its savings into one comparable, server-priced ledger; "we saved X" becomes a query, not a slide.
+- **Migrations 123 + 124 are additive only** (nullable columns / a new table / indexes) and must deploy *before or with* the code (the morning `~/deploy.sh` runs migrations then restarts, so co-deploy is safe; the guard covers any gap).
+- The historical `cost_log` is still ~3× overstated on the pre-correction opus rows, and the drachma reward over-paid ~3× for opus work before task 1343. **Recomputing/backfilling that history is an owner decision** (clawing back reward history is explicitly out of scope for the overnight build) — the correction fixes spend and rewards going forward only.
+- The cron-source tags are inert until the cron routines export `OTB_COST_CRON_ROUTINE` (System 4 wires them); session-cost.js reading the var is the mechanism, not the wiring.
+
+## Reproduce / verify
+
+- Live: `node scripts/gds/api.js GET /api/gds/public/cost-summary` → now carries `by_source`, `by_tier`, `savings`.
+- Pure tests (DB-free): `tests/llm-pricing.mjs`, `tests/session_cost.mjs`, `tests/cost_summary_shape.mjs`, `tests/cost.mjs`.

package/docs/adr/0076-in-session-deterministic-compaction.md

@@ -0,0 +1,58 @@
+# ADR 0076 — In-session deterministic compaction (retrieval-first context)
+
+**Status:** Accepted (2026-06-20) · tasks [#1347](https://example.com/builders#/task/1347) [#1348](https://example.com/builders#/task/1348) [#1349](https://example.com/builders#/task/1349) [#1350](https://example.com/builders#/task/1350) · hardened [#1364](https://example.com/builders#/task/1364) · System 2 of the Cloud Bongos LLM-reduction redesign (spike [#1326](https://example.com/builders#/task/1326)) · builds on [ADR 0075](<redacted>.md) (the ledger that measures it) and [ADR 0060](0060-gds-retrieval-layer.md) (the recall layer it recovers through)
+
+## Context
+
+The efficiency audit's central finding ([ADR 0075](<redacted>.md)): **~82% of token spend is a few dozen Opus "marathon" sessions**, and their cost is overwhelmingly `cache_read` — a context prefix that grows monotonically and is **re-billed on every assistant turn for hours**. Marathon cost is therefore the *integral of a growing prefix over hundreds of turns*, and the prefix is dominated by stale tool output: file reads later edited, the same file read repeatedly, large `Grep`/`Glob`/`ls`/`Bash` dumps acted on once and never referenced again. **This is the only pool large enough to matter — no cache, model-router, or cron-gate can touch it. Only bounding the live context can.**
+
+Spike [#1347](https://example.com/builders#/task/1347) measured the realized headroom on 7 real OTB Opus transcripts: **~24% of tool-output tokens are provably stale** by three conservative deterministic rules (superseded reads 7.3%, stale dumps 7.9%, duplicate reads 0.2%; per-session range 4–73%). That is the *floor* — the classifier deliberately counts only what it can prove — so System 2's 20–40% estimate is validated as plausible-to-conservative.
+
+## Decision
+
+A **deterministic eviction pass batched at the PreCompact boundary** drops stale tool output so the re-billed prefix stops growing; recovery is **retrieval-first** through the existing `/recall` layer.
+
+### Why the PreCompact boundary, not per-turn
+
+Rewriting the prefix mid-session invalidates the prompt cache: the next turn re-pays a full **cache-write** ($6.25/Mtok opus) instead of a cache-read ($0.50/Mtok). Doing that every turn costs far more than it saves. But compaction **already** resets the cache and pays one cache-write — so an eviction batched *there* is free of marginal cache cost, and every later turn reads the smaller, longer-lived working set. So: **evict only at PreCompact, never per-turn.**
+
+### Always-live vs retrieve-on-demand
+
+The classifier (`.claude/hooks/eviction-policy.js`, pure + hermetically tested) only ever targets `tool_result` blocks, and only these three classes:
+
+| Reason | Rule | Why safe to drop |
+|---|---|---|
+| `superseded` | a **whole-file** `Read` whose file was later `Edit`/`Write`-n | a definitive newer source of truth exists (the edit); the old read is stale |
+| `duplicate` | an older `Read` whose line range is later **covered** by another `Read` of the same file | the later read fully contains it; it is the current truth |
+| `stale_dump` | a `Grep`/`Glob`/`LS`/**reproducible** `Bash` result ≥ dumpMin tokens, older than the recency floor, **not cited** by a later turn | bulk output acted on once; re-derivable by re-running the tool |
+
+**Never-evict (always-live):** user turns, assistant text + reasoning, the claim **context-pack**, **worktree-path guidance**, harness `system-reminder`s, the **last N turns** (the live working set), the **newest read of any file**, and any **non-reproducible/side-effectful `Bash` output** (a generated secret, a timestamp, a migration result — re-running yields a different value, so it is irrecoverable). A **backward-reference liveness scan** is the final safety: a dump whose distinct line is quoted *or* whose distinctive identifiers/paths are reused by a *later* assistant turn (a paraphrase) is kept (it is still being cited). When in doubt, keep — the system must never break a session to save tokens.
+
+### Retrieval-first recovery (the evict-stub → /recall loop)
+
+Each evicted block is replaced by a **one-line stub** naming what is gone and a **one-step recovery**: a file `re-Read`, or — for a dump — a concrete `` /recall "<pattern>" `` query (which routes through `src/bongos/search.js` `searchChunks` / RRF, the same rank-scoped layer [ADR 0060](0060-gds-retrieval-layer.md) and the session-start `recall-hints.js` precedent use) **or** a re-run of the same tool. The PreCompact hook emits a **one-time** directive stating the recovery rule once — *recover on demand, do NOT pre-fetch* — which is what prevents a retrieval loop (the agent re-fetching everything it just evicted and undoing the compaction). `search_chunks` already dedups by `content_hash`, so re-ingested/duplicate content costs nothing extra.
+
+### Wire, don't arm
+
+The PreCompact hook (`.claude/hooks/pre-compact.js`, task 1349) is gated behind the per-builder **`OTB_INSESSION_COMPACT`** flag, **OFF by default** — an instant no-op for every builder until explicitly enabled. On a harness build without a PreCompact event the hook degrades to a Stop-hook *advisory* (stderr only, never blocks, never per-turn-rewrites). The directive is emitted as `hookSpecificOutput.additionalContext`; an older harness that ignores it simply compacts as usual.
+
+## Consequences
+
+- The single largest lever in the redesign (20–40% of total spend) is built and inert, ready for the owner to arm per-builder.
+- Savings are **measurable**: once armed, each compaction can record its counterfactual into `cost_baseline` (ADR 0075) — the priced size of what was evicted vs. what re-reading it would have cost — so the system proves itself in dollars rather than asserting.
+- Recovery never silently loses data: every evicted block is on disk (re-Read), in `/recall` (file content), or re-derivable (re-run the tool); the stub says which.
+- **Risk owned:** the directive is *guidance* to the compaction step, which is itself an LLM — eviction is advisory, not a hard transcript edit. The conservative classifier + never-evict list bound the blast radius; arming should start on one builder and watch `by_tier.cache_read_pct` (ADR 0075) before rollout.
+
+### Hardening before arming (task [#1364](https://example.com/builders#/task/1364))
+
+Three soundness gaps in the original classifier were closed before the flag is armed — each tightens a rule toward *keep* (the safety direction), so none can newly evict something that was previously kept:
+
+1. **Non-reproducible/side-effectful `Bash` is never a `stale_dump`.** The recovery stub said "re-run `Bash`", but re-running `openssl rand`, a `date`, a one-time generated value, or an `apply migration` yields a *different* value or has already mutated state — the affordance was actively wrong. A volatile-command detector (randomness, timestamps, mutations, file-writing redirects) excludes these from eviction; pure read commands (`cat`/`grep`/`ls`/`find`/…) stay evictable.
+2. **`duplicate`/`superseded` respect `Read` `offset`/`limit`.** They keyed on `file_path` alone, so a later read of a *different slice* marked the earlier slice `duplicate`, and a 1-line `Edit` marked an *entire* prior read `superseded` — dropping content never actually superseded. Now a read is `duplicate` only when a later read's line range **covers** it, and `superseded` fires only on a **whole-file** read (a partial read can't be located against a line-range-less `Edit`).
+3. **Liveness catches paraphrase.** The backward-reference scan matched only verbatim ≥40-char line quotes; an agent that re-stated a still-needed dump in its own words lost it. A distinctive-identifier/path overlap heuristic now keeps a dump when a later turn reuses several of its salient tokens.
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/eviction_policy.mjs` (classifier, 22 cases incl. the task 1364 hardening), `tests/pre_compact.mjs` (gate + directive).
+- Dry-run against a real transcript: `OTB_INSESSION_COMPACT=1` piped a `{hook_event_name:'PreCompact', transcript_path}` payload to `pre-compact.js` → emits the directive; unset → no-op.
+- Spike methodology + numbers: task [#1347](https://example.com/builders#/task/1347).

package/docs/adr/0077-content-addressed-llm-cache.md

@@ -0,0 +1,32 @@
+# ADR 0077 — Content-addressed LLM cache
+
+**Status:** Accepted (2026-06-20) · tasks [#1358](https://example.com/builders#/task/1358) [#1359](https://example.com/builders#/task/1359) [#1360](https://example.com/builders#/task/1360) · System 5 of the Cloud Bongos LLM-reduction redesign (spike [#1326](https://example.com/builders#/task/1326)) · reports savings into [ADR 0075](<redacted>.md); reuses the content-hash convention of [ADR 0060](0060-gds-retrieval-layer.md)
+
+## Context
+
+Several GDS-internal model calls are **idempotent**: they re-process inputs that haven't changed. The nightly `architect-audit` re-audits a `main` that is often unchanged since the last run; `onboarding-analyze` re-runs over **immutable** session transcripts. Each is a full Opus call billed in full every time, for an answer byte-identical to one already produced. This is the residual after Systems 3 (autonomy gate) and 4 (deterministic-first cron) — the lowest-magnitude lever (est 2–5%), and the safety net that catches what slips through them.
+
+Every GDS-internal model call already funnels through **one** spawn primitive — `grader.runSubagent` — which makes a single wrap point the whole surface.
+
+## Decision
+
+Memoize idempotent model runs at `runSubagent`, keyed on the **content** of the request, with validity bound to the **git SHA of the inputs**.
+
+- **Cache key** = `sha256(normalized-prompt | model | task_type | scope_sha)` (`src/bongos/llm-cache.js`, table `llm_cache`, migration 125). `scope_sha` is the git tree/blob SHA of the embedded inputs (`git rev-parse HEAD:<path>`), so **a stale answer is only ever returned when the inputs are provably unchanged** — the moment the tree changes, the key changes and the cache misses. This is the correctness backbone.
+- **The normalizer registry is the other correctness surface.** A per-`task_type` normalizer strips only **provably-volatile** lines (timestamps, run-ids, the architect's `version=` echo) so two logically-identical prompts hash the same — *without* ever collapsing two genuinely-different requests. Adding a task type means adding a normalizer; that is where a reviewer looks to verify a cache can't return a wrong answer.
+- **Store only on a clean run.** A result is cached only when `exit_code === 0` and stdout is present — **never a timeout or a non-zero exit**. A cache must never pin a failure.
+- **The wrap is opt-in and behavior-preserving.** `grader.runSubagentCached({prompt, opts, cache})` checks the cache then falls through to the **untouched** `runSubagent`; with no `cache` spec it is exactly today's call. A hit returns `{stdout, cost_usd: 0, cached: true}`, so the $0 flows automatically through the existing `extractCostUsd → session-cost` ledger, and the saving is recorded into `cost_baseline` (`system5:llm-cache`, [ADR 0075](<redacted>.md)) — `baseline_usd` = what the run *would* have cost, `amount_usd` = 0 — so the system proves its savings in dollars.
+- **First plug-ins (highest rerun value):** `architect-audit` (key scoped to the git tree-hash of `--paths`) and `onboarding-analyze` (key on the immutable session id). Both are best-effort: any `llm_cache` error degrades to an ordinary uncached run — the cache can never take down the thing it accelerates.
+- **v1 is exact-match.** Semantic / near-match caching is deferred; a v1 key either matches exactly (after normalization) or misses. That keeps correctness obvious.
+
+## Consequences
+
+- An unchanged-`main` `architect-audit` re-run, or a re-`onboarding-analyze` of a session, returns at **zero new tokens**, with `hit_count` incremented and the saving in `cost_baseline`.
+- Because validity is git-SHA-scoped, the cache is **self-invalidating** — no manual purges; a real code change always re-runs.
+- The blast radius of a wrong normalizer is bounded to its one `task_type`; the default normalizer only trims.
+- **Runtime verification is deferred to a deployed run.** These caches sit on Opus subagent calls that this overnight build does not execute (and `architect-audit.js` is independently known to mis-parse its Opus output — a pre-existing defect, see the efficiency audit's meta-note). The pure key/normalizer/scope-sha logic is unit-tested DB-free; the lookup/store/hit-count/$0 path is verified on first real post-deploy run.
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/llm-cache.mjs` (sha256, normalizers, key composition, scope-sha invalidation).
+- Post-deploy: run `architect-audit --paths <p>` twice over an unchanged tree → the 2nd logs `cost_usd=0`, `cached:true`, `llm_cache.hit_count` increments, and a `cost_baseline` `system5:llm-cache` row appears.

package/docs/adr/0078-deterministic-first-cron.md

@@ -0,0 +1,48 @@
+# ADR 0078 — Deterministic-first cron harness
+
+**Status:** Accepted (2026-06-20) · tasks [#1355](https://example.com/builders#/task/1355) [#1356](https://example.com/builders#/task/1356) [#1357](https://example.com/builders#/task/1357) · System 4 of the Cloud Bongos LLM-reduction redesign (spike [#1326](https://example.com/builders#/task/1326)) · cost visibility via [ADR 0075](<redacted>.md)
+
+## Context
+
+Several of the ~17 scheduled routines are an **Opus session wrapping a single committed deterministic script**. `peer-vote-tally` literally instructs the model "do NOT compute anything by hand — run `tally.js`"; `diagram-drift` runs `check.js --file-idea`; `dep-audit-nightly` and `main-audit` run a scan script. Booting a model, loading CLAUDE.md, and paying per-turn `cache_read` just to shell one `node` command is pure waste — the model adds nothing a cron line couldn't do. (Est 3–6% of total token spend.)
+
+## Decision
+
+A routine **declares its run mode** in SKILL.md frontmatter, and a dispatcher runs it at the cheapest sufficient tier — for deterministic routines, **no model is launched at all**.
+
+- **`scripts/gds/run-routine.js <name>`** (task 1355) reads `mode:` + a `steps:` list (`command` + `sink: discord|gds|none`) from the routine's SKILL.md frontmatter:
+  - **`deterministic`** — `execFileSync` each step as plain node; route stdout by sink; non-zero exit → best-effort `#ops` alert + non-zero exit. **This is the whole execution — no `claude -p`.**
+  - **`hybrid`** — run the deterministic prefix as code; spawn `claude -p` *only* when a step emits a non-empty `{"needs_judgment": …}` payload, feeding the model only that payload.
+  - **`judgment`** — the status quo: a wrapped session over the SKILL body.
+  - Steps run with `OTB_COST_CRON_ROUTINE=<name>` so System 1 ([ADR 0075](<redacted>.md)) tags any (hybrid) spend `cron:<routine>:*` — making "did demoting this to deterministic actually cost ~$0?" a queryable fact.
+- **Convert only the provably-deterministic wrappers (task 1356).** `peer-vote-tally` and `diagram-drift` already do their whole job in one self-contained, self-filing script — converted to `mode: deterministic`. **`main-audit` and `dep-audit-nightly` were NOT converted:** `main-audit.js` is trust-boundary core (SEC [#863](https://example.com/builders#/task/863) / [ADR 0043](<redacted>.md)) and neither script self-files its findings (the model currently does the per-finding `idea_inbox` / `vulnerability_report` filing), so demoting them blindly would silently drop alerting. They need a self-filing flag added to their (security) scripts first — a separate, security-reviewed task.
+- **A fitness check stops the boundary from rotting (task 1357).** `fitness.checkDeterministicRoutines` fails CI if a `mode: deterministic` SKILL body contains a judgment/mutation instruction (`git push`/`commit`, `deploy.sh`, an `Edit`/`Write` tool instruction, free-text synthesis) — *negated* mentions ("never pushes", "does NOT edit") are allowed as descriptive boundaries — or if a fenced `node …` command diverges from the declared `steps:`. The pure core (`scanDeterministicBody`) is unit-tested both ways (clean passes, each violation class is caught). This is the structural cure for the markdown-graveyard pattern: a deterministic routine can never quietly become a wrapped session again.
+
+## Consequences
+
+- Two nightly/weekly Opus sessions become zero-model cron lines; the pattern is now declared, enforced, and ready for more routines to adopt as their scripts gain self-sufficiency.
+- **Operator action required (not in-repo):** the cron entries for `peer-vote-tally` + `diagram-drift` must be repointed from `claude -p <skill>` to `node scripts/gds/run-routine.js <name>`. The schedules live in the operator/MCP layer (`~/.claude/scheduled-tasks/` is symlinked to the repo), so the repo holds the SKILL definitions but not the launch command.
+- The fitness check means the SKILL *body* of a deterministic routine is now documentation only — it must describe, not instruct. Remediation steps move to a separate claimed task (the routine *detects*; a human *fixes*).
+- Composes with the rest of the redesign: System 3 (autonomy gate) decides whether a *judgment* routine fires; this decides a *deterministic* routine needs no model at all; System 5 (cache) catches a same-model-run-twice.
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/run_routine.mjs` (frontmatter parser + tokenizer), `tests/fitness.mjs` (the deterministic-boundary check, clean + catches).
+- `node scripts/gds/run-routine.js peer-vote-tally --dry-run` → prints the one command it would run, no model.
+- Post-deploy: System 1's `by_source` shows `cron:peer-vote-tally:*` / `cron:diagram-drift:*` at ~$0.
+
+## Amendment (2026-06-21) — server-internal-timer realization for server-call routines
+
+**Status:** Accepted · task [#1382](https://example.com/builders#/task/1382) · supersedes the "operator wires cron" consequence above for `peer-vote-tally`.
+
+**What we found.** The original decision built an external dispatcher (`scripts/gds/run-routine.js`) and left the *scheduling* to the operator/MCP layer. Nothing was ever durably scheduled — **every scheduler layer was empty** (the local app tasks, the in-session cron, and the claude.ai cloud routines all returned nothing; the "overnight build" was a manually-pasted brief). So both routines' realized run count was **zero**, and a deterministic routine that never fires saves no tokens because it does no work. (Confirmed in the System 4 effectiveness eval, task [#1371](https://example.com/builders#/task/1371).)
+
+**What changed.** `peer-vote-tally`'s real work is server-side and needs no model, so the durable realization is an **in-process timer** inside the always-on Node process — the same pattern as `src/bongos/publish-reconciler.js` and `src/bongos/uptime-poller.js`. `src/bongos/routine-timers.js` runs **peer-vote-tally weekly**, calling `db.tallyPeerVotes()` directly (the exact transaction the Archon-gated `POST /tasks/peer-votes/tally` route runs, now extracted to `db.js` so route + timer share one path). The route's Archon gate is an HTTP-auth concern; an in-process call has no requester and the SQL writes `karma_log` with `granted_by = NULL`. Idempotent (only matured, untallied votes) and protected by a `FOR UPDATE OF pv` row lock — the real multi-instance guard.
+
+The timer is **unref'd**, **best-effort** (a throw logs `[routine-timers]` and waits for the next tick — never crashes the game/API), kill-switched by `ROUTINE_TIMERS_DISABLED=1`, and a **no-op anywhere the DB is unreachable** (builder laptops/boxes), so it is safe to start unconditionally on the game boot. Started/stopped in `server.js` beside `publishReconciler` — and **only** in `server.js` (the game/droplet entrypoint), not `src/platform-server.js`, so a future second always-on instance can't double-run; if one ever shares the `example` DB, set `ROUTINE_TIMERS_DISABLED=1` on the secondary.
+
+**`diagram-drift` was intentionally NOT made a timer.** All five onboarding diagrams already auto-regenerate from live facts on every deploy (`gen-diagrams.js`), so a daily drift check is near-redundant, and an in-process loopback read would add a needless request surface. The manual `node scripts/gds/run-routine.js diagram-drift` remains for on-demand use.
+
+**What we KEPT.** `run-routine.js`, the SKILLs' `mode: deterministic` declarations, `tally.js`, `check.js`, and the `checkDeterministicRoutines` fitness guard are all unchanged. `run-routine.js` remains the manual/on-demand front door (and keeps `tests/run_routine.mjs` meaningful); the timer is the always-on front door. Both reach the same deterministic work. The amendment is documented HERE and in `docs/recipes/ops-gotchas.md`, **never** in a deterministic SKILL body (a stray `node …` line there would fail the prose↔steps divergence check).
+
+**Operator action retired.** The original "repoint the cron entries from `claude -p` to `node run-routine.js`" step is no longer required for `peer-vote-tally` — the server schedules it itself.

package/docs/adr/0079-value-gated-autonomous-engagement.md

@@ -0,0 +1,39 @@
+# ADR 0079 — Value-gated autonomous engagement (BUILT DISABLED)
+
+**Status:** Accepted, **shipped inert** (2026-06-20) · tasks [#1351](https://example.com/builders#/task/1351) [#1352](https://example.com/builders#/task/1352) [#1353](https://example.com/builders#/task/1353) [#1354](https://example.com/builders#/task/1354) · System 3 of the Cloud Bongos LLM-reduction redesign (spike [#1326](https://example.com/builders#/task/1326)) · cost visibility via [ADR 0075](<redacted>.md); reuses [ADR 0043](<redacted>.md) protected-path matcher
+
+## Context
+
+The largest lever in the ~18% non-marathon remainder is *autonomous* model spend: nightly routines that boot a full Opus session even when there's nothing to do, default every spawn to the dearest model, and split a single code-review finding across three Opus sessions (review → triage → rebuild). Three eliminations sit here, and they're really two decisions about every spawn — **whether** to fire, and **which** model — plus collapsing the triple-spend. (Est 8–14%.)
+
+## Decision
+
+Three mechanisms, merged so each spawn decision lives in exactly one place — **all built behind a single off-by-default flag.**
+
+1. **Whether to fire — the autonomy precheck** ([#1351](https://example.com/builders#/task/1351)). A $0 deterministic `decide()` (`scripts/gds/autonomy-gate.js`) runs as a routine's Step 0: NO-GO (and nothing boots) when there's no claimable autonomous work *and* `origin/main` is unchanged since the last run, or no open ideas to triage, or the autonomous (`cron:%`) month-to-date spend has hit a **hard spend-brake** ceiling. Exposed at `GET /autonomy/precheck` (archon) and audited in `autonomy_runs` (migration 126) so every skip is a queryable fact.
+
+2. **Which model — the cascade router** ([#1352](https://example.com/builders#/task/1352)). `src/bongos/cascade-dispatch.js` `dispatch()` drafts a spawn on the cheapest sufficient model (mechanical→haiku, bug/refactor/feature→sonnet via the shared `task-classifier`) and **escalates a rung only on an objective signal** — a schema-validate fail or a self-reported `CONFIDENCE: low` / `ESCALATE: yes` trailer — capped at 2 escalations and **never above the builder's configured model ceiling** (`skill-prefs.getForBuilder`). Wired into the routines' spawns + a fail-open `cascade-route.js` PreToolUse hook for in-session subagent spawns ([#1353](https://example.com/builders#/task/1353)).
+
+3. **Collapse the triple-spend — the safe_autofix lane** ([#1354](https://example.com/builders#/task/1354)). A code-review finding may be fixed-and-shipped in ONE run instead of review→triage→rebuild, but `autofixAllowed()` permits it **only** when ALL hold: the gate is armed, the grader is **LIVE** (never auto-fix while `GRADER_BYPASS_ENABLED` is on), the change is **not** a protected path (`permission-path-check.matchProtected`), and the finding is **high-confidence + single-file**. Anything failing one check stays on the inbox→promote, human-in-the-loop path. Untrusted finding text is fenced per SR-12 (data, never instructions). Plus a **batched-context dispatch**: the overnight builder, when armed, claims `optimizeSession`'s touches-**disjoint** set and fans its workers from one supervisor that loads orientation once (the merge/ship leg stays serialized).
+
+## BUILT DISABLED — wire, don't arm (owner directive, 2026-06-20)
+
+Per the owner directive, System 3 ships **inert**, gated OFF together with the grader; turn it on only when the owner enables it alongside the grader rework. The master switch is **`OTB_AUTONOMY_ENABLED`** (unset by default):
+
+- `decide()` returns **GO** when the flag is off → a routine's Step 0 is a no-op; the routine runs exactly as before.
+- `cascade-route.js` emits nothing when off; `cascade-dispatch` is a library nothing calls until armed.
+- `autofixAllowed()` returns **false** by default (its defaults are the refusing values), and is **double-gated**: even when the flag is armed, it stays off while `GRADER_BYPASS_ENABLED` is on — which it currently is. So the auto-ship lane cannot fire until BOTH the autonomy flag is armed AND the grader is live.
+
+The pure decision cores (`decide`, `autofixAllowed`, `cascade-dispatch.dispatch`) are unit-tested DB-free, including the inert-by-default and ceiling-never-exceeded properties.
+
+## Consequences
+
+- The system is fully built and reviewable, but changes nothing in production until the owner arms it — no autonomous behavior shifts on deploy.
+- When armed, the spend-brake protects against a runaway autonomous fleet; **security routines (dep-audit) should be exempted from the brake at arming time** — a skipped vuln scan is a security hole, not a saved dollar (noted in the routine).
+- This system does **NOT** address marathon (interactive `cache_read`) spend — that is System 2 ([ADR 0076](<redacted>.md)), the only lever on the 82% pool. System 3 attacks the autonomous remainder.
+- Arming guidance: enable `OTB_AUTONOMY_ENABLED` first with the grader live, watch `autonomy_runs` (skips) + System 1's `by_source` `cron:%` spend, then let the safe_autofix lane follow once the cascade + gate behavior is trusted.
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/autonomy_gate.mjs` (decide + autofixAllowed, inert-by-default), `tests/cascade-dispatch.mjs` (ceiling clamp + escalation).
+- `node scripts/gds/autonomy-gate.js overnight-builder` → with the flag unset, prints `GO — autonomy gate disabled … (inert)`.

package/docs/adr/0080-llm-cache-api-transport-and-trust-model.md

@@ -0,0 +1,46 @@
+# ADR 0080 — LLM-cache API transport + trust model
+
+**Status:** Accepted (2026-06-21) · task [#1381](https://example.com/builders#/task/1381) · transport for the content-addressed cache of [ADR 0077](<redacted>.md); savings ledger contract per [ADR 0075](<redacted>.md) / `migrations/124_cost_baseline.sql`; reuses the rank trust boundary of [ADR 0016](<redacted>.md)
+
+## Context
+
+System 5 ([ADR 0077](<redacted>.md)) memoizes idempotent model runs in the `llm_cache` Postgres table via `src/bongos/llm-cache.js` (`lookup`/`store`/`recordSaving`), all of which use a **direct `pg` pool**. But its two consumers — `architect-audit.js` and `onboarding-analyze.js` — run as CLI/cron on **builder machines**, where the pool is unreachable (peer-socket only; TCP is scram-only). So every cache op silently degraded to miss/no-store and the cache **could never hit organically** (verified empirically in the System-5 effectiveness eval, task [#1372](https://example.com/builders#/task/1372): 0 rows, 0 hits, despite correct logic — proven only when the DB was reached via a forwarded socket).
+
+The fix is a transport: reach the cache DB from any consumer machine. The hard part is **trust** — a cache *store* writes a `result_stdout` that a later run **replays at $0 and trusts** (for `architect-audit` it becomes `audit_md` written to `docs/audits/` and `seed_ideas` filed to `idea_inbox`). An open store endpoint is a content-injection vector into the planning pipeline and a metrics-integrity vector into the public savings number.
+
+## Decision
+
+**Expose the cache over the GDS API; keep the in-process pool as the server fast path; inject the API transport into the consumers — never statically couple the core to the CLI layer.**
+
+- **`src/bongos/routes/llm-cache.js`** exposes `POST /api/gds/llm-cache/lookup` and `POST /api/gds/llm-cache/store`, each mapping 1:1 onto the existing `llm-cache.js` DB helper (the route never reimplements SQL). `/store` mounts its own 512 KB `express.json` (a full subagent stdout exceeds the global 64 KB cap; `routes.js` skips the global parser for that path).
+- **`llm-cache.js` self-routes.** `lookup`/`store` try the pool first (`poolReachable()` — a memoized `SELECT 1`; `true` is sticky, `false` is **never** memoized so a transient boot blip can't permanently disable the server cache), then fall back to an **injected** `apiCall` (`setApiFallback(fn)`). The consumers — which already import `cli-lib` — inject `apiCall`; the core never statically requires the CLI layer (that would drag session/fetch plumbing into the always-on server and cross the core↔host boundary the fitness gate guards). Best-effort is preserved end-to-end: any pool/network/auth error degrades to miss/no-store and **never throws** (the fallback passes `allowUnauthenticated:true` so an expired session can't `process.exit` the audit it rides on).
+
+### Trust model (the load-bearing part)
+
+| Control | What it stops |
+|---|---|
+| **Metic+ gate** on both routes (`requireRank('metic','archon')`, read live per-request — [ADR 0016](<redacted>.md)) | Xenos/Thetes seeding a result a high-value audit later replays. There is no legitimate sub-Metic consumer. |
+| **`cache_key` must be `/^[0-9a-f]{64}$/`** | malformed / SQL-shaped keys; a key is a sha256 by construction. |
+| **`task_type` ∈ the registered `NORMALIZERS`** | caching arbitrary (non-idempotent) producers; bounds stores to the known idempotent ones. |
+| **`owner_builder_id` pinned to `req.builder.id`** (client value ignored) | a caller falsifying write-attribution. (The cache is **shared-on-read by content address** — `lookup` keys on `cache_key` only, not on owner. Isolation comes from the key itself: an entry is only readable by someone who can reconstruct its exact `prompt+model+task_type+scope_sha`, and only at Metic+ — not from an owner filter.) |
+| **`scope_sha` in the key** (pre-existing) | blast radius: a poisoned entry is only ever replayed for the exact `(prompt, model, task_type, git-tree)` it was stored under — a changed tree misses. |
+| **No `/record-saving` route — `recordSaving` stays pool-only** | the migration-124 contract: the saving lands in the **public** `cost_baseline` → `/public/cost-summary`, so it must be a server-side-priced figure, never a client dollar amount. |
+| audit middleware + rate limiter (automatic) | a forensic record of every store; poisoning velocity capped at 30 writes/min/IP. |
+
+### The savings-booking gap (deliberate, interim)
+
+`result_cost_usd` on `/store` is **clamped** (`[0, OTB_LLM_CACHE_MAX_COST_USD]`, default $10) and stored **only as informational metadata** on the internal `llm_cache` row — it is **never booked to the public ledger**. Because there is no API path for `recordSaving`, an off-server hit **records the hit** (`hit_count` bumped in `lookup`) but **does not book a dollar saving**. This honors the migration-124 contract ("`baseline_usd` is ALWAYS computed server-side from token counts via `priceUsage()` — NEVER a client-supplied dollar figure") by booking *nothing* rather than an unverified client figure.
+
+**Follow-up (filed):** have the consumers forward the subagent envelope's token `usage` so `/store` can re-price the saving server-side via `priceUsage`, then book *that* into `cost_baseline`. Until then, System 5's realized savings show as **hit counts, not dollars** — which is the honest state.
+
+## Consequences
+
+- The cache becomes functional from any builder machine: an unchanged-input re-run replays at $0 with `hit_count++`, from the laptop/box where the audit actually runs.
+- The public savings number stays at $0 for off-server hits until the re-pricing follow-up lands — by design, so the first real numbers are trustworthy.
+- A poisoned store is bounded to Metic+ actors, one immutable tree-snapshot of one scope, audit-logged, and rate-limited. The grader being bypassed (`GRADER_BYPASS_ENABLED=1`) is irrelevant here — the cache rides `runSubagent`, the spawn primitive, not the grading panel.
+- Organic hit rate is expected to be **low** (an audit must re-run over an unchanged tree before a relevant commit lands), so this is a correctness/enablement fix, not a large dollar lever — consistent with the System-5 eval's "low end of 2–5% latent."
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/llm-cache.mjs` (transport fallback: pool-unreachable → injected apiCall; `recordSaving` never calls the API), `tests/llm-cache-route.mjs` (hex-key + task_type validation, cost clamp, owner pinning, never-500).
+- `node tests/fitness.mjs` → "no route bypasses server-side rank checks (ADR 0016)" passes with the new route's inline `requireRank`.

package/docs/adr/0081-tool-agnostic-design-layer.md

@@ -0,0 +1,62 @@
+# ADR 0081 — Tool-agnostic design layer: repo-canonical, Claude Design + Figma as adapters
+
+**Status:** Accepted (2026-06-21) · this ADR [#1375](https://example.com/builders#/task/1375) · implementation cluster [#1376](https://example.com/builders#/task/1376) [#1377](https://example.com/builders#/task/1377) [#1378](https://example.com/builders#/task/1378) [#1379](https://example.com/builders#/task/1379) [#1380](https://example.com/builders#/task/1380) · applies the core↔host pattern of [ADR 0062](<redacted>.md) to design; grader/ship changes ride the gate-review hard floor of [ADR 0043](<redacted>.md)
+
+## Context
+
+Developers collaborate through Git because code is text: it diffs line-by-line and 3-way-merges automatically. Design has no equivalent — a Figma `.fig` is a proprietary vector scene-graph and a PNG is a binary blob; neither line-diffs or auto-merges. Designers never adopted the merge model: they co-edit live (Figma's multiplayer), snapshot versions, and publish component libraries. So "how does a designer's work reach GitHub?" has never had a clean answer here.
+
+Three forces made this worth deciding now:
+
+1. **UI is becoming real work.** Today the GDS has three disciplines — `engineer | artist | ideator` — and "design/figma/UI" tasks fall into `artist`, the pixel-art lane. UI (HUD, menus, the builders' hall, status dashboard, landing pages) is a different problem from world tiles and deserves its own lane.
+2. **The grader is secretly two systems.** The GDS ship pipeline (`confirm → grade → merge → deploy → credits`) does **not** branch by discipline — every task rides the same rails. But the *grade* step is the code panel [`grader.js`](../../src/bongos/grader.js) (reads a git diff; scores code quality), while pixel art is really gated by a *separate* Gemini vision pipeline ([`art/pipeline/review.py`](../../art/pipeline/review.py)) that runs **upstream** in `/paint`, not at ship. Art passes the ship-time grader as a near-rubber-stamp because a text-only panel can't see pixels. Two grader codebases is a maintenance trap.
+3. **Claude Design changed the calculus.** [Claude Design](https://www.anthropic.com/news/claude-design-anthropic-labs) (Anthropic Labs, beta, 2026) **writes code and renders it** — it has no vector canvas. Its output is HTML/CSS/JS, and its June 2026 update added tight Claude Code sync (`/design-sync` imports a repo's design system in; a finished design hands off to Claude Code "where the designer left off"). So for Claude Design, *design is code* — it merges like any other code.
+
+Owner (Lars) requirements, reached in the 2026-06-21 design conversation:
+
+- **No vendor lock-in.** A competitor may ship a rival design tool; the system must not depend on Claude Design specifically.
+- **Human escape hatch.** A talented designer must be able to make manual changes directly in Figma.
+- **One grader, one regen flow for every task type.** Type-dependent criteria are fine; two grader *systems* are not.
+
+## Decision
+
+**The repo is the single source of truth; every design tool is a swappable adapter against a neutral contract.** This is the [ADR 0062](<redacted>.md) core↔host decoupling applied to design: the system depends on the *contract*, not on any tool.
+
+1. **Neutral design contract = the repo.** The canonical representation is design tokens (extending [`config/branding.json`](../../config/branding.json)) + component code + exported assets, plus a per-surface "design source pointer" (which tool authored it, where its editable source lives). Tools read from and write to this contract; nothing else is canonical. ([#1377](https://example.com/builders#/task/1377))
+
+2. **Tools are adapters, not integrations.** Claude Design and Figma are the first two adapters; a future tool is just a third. Each adapter does two things: import the repo design system *into* the tool, and emit a tool change back as a *committed diff*.
+   - **Claude Design adapter** ([#1378](https://example.com/builders#/task/1378)): `/design-sync` exports our design system in; the Claude Code handoff lands generated UI code under a claimed GDS task. No translation layer — the output is already code.
+   - **Figma adapter** ([#1379](https://example.com/builders#/task/1379)): a human edit → generate component code/tokens (Code Connect / Figma MCP) → commit; and the repo syncs *back* to Figma (the code→Figma bridge) so the designer never edits a stale file. This is the human escape hatch.
+
+3. **`ui` becomes its own discipline** ([#1376](https://example.com/builders#/task/1376)), split out of `artist`. `ui` = design-as-code (graded by diff + rendered screenshot); `artist`/graphics = pixel art (graded by vision). Each routes to its own work-mode (a new `/design`, mirroring `/paint`).
+
+4. **Code-canonical round-trip.** Structured UI (components, layout, tokens — the design-system vocabulary) round-trips as code. Freeform visual work that doesn't translate cleanly is exported as a committed *asset* (the graphics path), not round-tripped. A surface a human truly wants to own canvas-first can be flagged "Figma-canonical" as an explicit exception; code-canonical is the default.
+
+5. **One grader, one regen flow — parameterized by type, not forked** ([#1380](https://example.com/builders#/task/1380)). Collapse the code panel and the Gemini pipeline into a single engine: a rubric registry keyed by task type (code-quality / visual / UI+a11y), evidence chosen by type (git diff for code+UI; render→screenshot for visual), one **multimodal** Claude grade call that subsumes the separate vision pass, and one shared regen loop — `spec → generate → grade → fail? regenerate → pass? commit` — identical across types. Because Claude Design emits code, UI rides the *same* git-diff grader as engineer code; only pixel art needs the vision modality, which the multimodal grader already covers.
+
+## Consequences
+
+- **No lock-in.** Tools plug into the repo contract; adding or dropping one (Claude Design, Figma, a future rival) doesn't touch the core. That is the explicit insurance the owner asked for.
+- **Designers keep Figma.** Manual Figma edits are first-class for structured/design-system changes and round-trip into the repo via a normal GDS task + the same grader. The honest limit: the Figma→code round-trip is lossy for arbitrary canvas art — that work becomes a committed asset, not round-tripped code.
+- **One grader to maintain, not two.** The standalone Gemini review path is retired into the unified engine. Code doesn't auto-regen today (a failed grade = human fixes + re-ships); unifying gives every type the same generate→grade→regenerate loop.
+- **Graphics is unchanged.** World pixel art stays on the Claude Code + Gemini pipeline; Figma stays its viewer ([`otb-figma-sync`](../../.claude/skills/otb-figma-sync/SKILL.md)). This ADR adds the `ui` lane beside it, it does not disturb the art pipeline.
+- **Gate-review floor applies.** [#1380](https://example.com/builders#/task/1380) touches [`grader.js`](../../src/bongos/grader.js) + [`ship.js`](../../scripts/gds/ship.js) — the gate-review **hard floor** ([ADR 0043](<redacted>.md)). It needs owner Gate approval even for Archon, and the multimodal call path wants a security review.
+
+## Rejected alternatives
+
+- **Fork the GDS / keep two grader sets** (an earlier draft of this design). Rejected by the owner: separate grader systems per discipline is a maintenance trap. One engine + type-parameterized rubric/evidence achieves the same ends with one codebase.
+- **Claude Design only.** Cleanest GitHub path (code-native), but bets the system on one beta — the lock-in the owner explicitly wants to avoid.
+- **Figma only.** Mature and multiplayer, but its source is a vector file, so every change needs a code-generation translation step with an imperfect round-trip. Kept as an adapter, not as the single tool.
+- **Figma-canonical (or per-tool source of truth) by default.** Two masters and lossy reconciliation. Code-canonical with Figma round-tripping *in* keeps one master; per-surface Figma-canonical remains available as an explicit exception.
+
+## Implementation
+
+The cluster is seeded and dependency-wired in the GDS (this ADR is [#1375](https://example.com/builders#/task/1375)):
+
+- [#1376](https://example.com/builders#/task/1376) — `ui` discipline + work-mode (→ [#1375](https://example.com/builders#/task/1375))
+- [#1377](https://example.com/builders#/task/1377) — neutral design contract + adapter interface (→ [#1375](https://example.com/builders#/task/1375))
+- [#1378](https://example.com/builders#/task/1378) — Claude Design adapter (→ [#1377](https://example.com/builders#/task/1377))
+- [#1379](https://example.com/builders#/task/1379) — Figma round-trip adapter (→ [#1377](https://example.com/builders#/task/1377))
+- [#1380](https://example.com/builders#/task/1380) — unify the grader (→ [#1376](https://example.com/builders#/task/1376), [#1377](https://example.com/builders#/task/1377))
+
+Acceptance, when built: a UI surface authored in Claude Design *and* one hand-edited in Figma both reach prod through one GDS task and the one grader; the standalone Gemini review path is gone; editing Figma always opens a design synced from current `main`.

package/docs/adr/0082-productized-key-storage-provisioning.md

@@ -0,0 +1,32 @@
+# ADR 0082 — Productized key-storage provisioning (server-generated master key, zero SSH)
+
+**Status:** Accepted (2026-06-21) · task [#1398](https://example.com/builders#/task/1398) · resolves blocker 41 · extends the per-builder secret-box (task 1013; `src/bongos/secret-box.js`) · sibling of the UI-first intake work (task [#1391](https://example.com/builders#/task/1391))
+
+> Note: `secret-box.js`'s header cites "ADR 0071" for the original design, but 0071 on disk is a different (dev-box) decision — that reference is stale. This ADR is the authoritative record for the master-key *provisioning* path; the encryption scheme itself shipped under task 1013.
+
+## Context
+
+The per-builder Gemini key feature (task 1013) encrypts each builder's key at rest with an AES-256-GCM **master key** that, by design, lives ONLY in server env (`BUILDER_SECRET_KEY`) or a local `~/.config/otb/builder-secret.key` (0600) operator file — never in the DB, repo, or chat. The feature shipped its endpoints + settings UI, but the master key was **never provisioned in prod**, so `secretBox.isConfigured()` is false → `GET /me/art-key/own` returns `storage_configured:false` → the settings card is a dead-end ("Key storage is being set up by an Archon — check back shortly") with no input. The result: **no builder can store a key at all**, blocking the art pipeline for everyone past the shared-newcomer tier (surfaced live when an Archon hit it on task 587).
+
+The only documented fix was a manual one: SSH to the droplet and hand-add `BUILDER_SECRET_KEY` to the systemd EnvironmentFile. The owner declined that — provisioning should be a **product action**, not a terminal ritual.
+
+## Decision
+
+An **Archon initializes key storage from the UI** — the server generates and persists the master key; no human touches a secret.
+
+- **`secretBox.provisionMasterKey({ file?, env? })`** generates 32 crypto-random bytes (`crypto.randomBytes`) and writes them (64-hex) to the operator file (`~/.config/otb/builder-secret.key`) as **0600** — the path the loader already honors as its file-fallback source, so it survives restarts. It is **idempotent and never overwrites**: if a valid key already resolves (env or file) it's a no-op (`created:false`); if a file is present but *doesn't* decode, it writes with the `wx` (exclusive-create) flag and **refuses on EEXIST** rather than clobber — overwriting the master key would make every already-stored builder key permanently undecryptable. `opts` exist only for the hermetic unit test.
+- **`POST /api/gds/me/art-key/storage-init`** (in `routes/me.js`), gated `requireRank('archon')` — a server-wide admin action that happens to live under `/me/art-key/*` for client locality. It calls `provisionMasterKey()` and returns `{ ok, created, storage_configured }`; a refusal (present-but-invalid file) is a `409` that tells the operator to look, never a silent overwrite.
+- **The settings card** (`public-builders/settings.js`), in the `storage_configured:false` state, now shows an Archon a **"Set up key storage"** button (the server enforces the rank regardless — the client check only decides what to render; divine tiers above archon also pass). Non-Archons keep the wait-for-an-Archon message. On success the card drops straight into the key-entry state.
+
+## Consequences
+
+- Turning on key storage is now one click by any Archon — **zero SSH, zero hand-edited prod secrets**. Re-clicking after it's up is a safe no-op.
+- **Durability trade-off (accepted):** the master key lives in a 0600 file beside the encrypted blobs on the prod droplet. A `DB dump alone still cannot decrypt` (the key isn't in the DB). If the *droplet's disk* is lost without the file, stored keys become undecryptable — but this is BYOK: builders simply re-add their own keys. Crypto-RNG-to-file also beats a human-chosen secret (no weak/reused values, never pasted anywhere). Backing up the file with the other droplet secrets is recommended but not required for correctness.
+- **Idempotency is load-bearing.** The never-overwrite guard is the one property that must never regress — a unit test asserts a second call leaves the key bytes unchanged and that a present-but-invalid file is refused, not clobbered.
+- Security surface: this touches secret-box + an auth-gated route, so it runs the hacker/security review and gate-review will flag it. The provisioning endpoint exposes no secret material in any response (only `{ ok, created, storage_configured }`).
+
+## Reproduce / verify
+
+- Pure tests (DB-free): `tests/secret_box.mjs` — `provisionMasterKey` creates a 0600 64-hex file, is idempotent (no overwrite / no brick), short-circuits on a valid env key, and refuses a present-but-invalid file.
+- Route gate: `tests/route_rank_check.mjs` confirms the new privileged route classifies to its rank.
+- End-to-end: on a server with no master key, an Archon clicks "Set up key storage" → `storage_configured` flips true → a key can be added via Settings and syncs to the box (`fetch-art-key.js`).