@bongos/core 1.17.1 → 1.17.2

package/docs/onboarding/primer.md

@@ -2,15 +2,15 @@
 
 *Read this before you claim your first work. ~10 minutes.*
 
-You're about to build inside Off the Boats, a project that runs on a small purpose-built dev system. This primer is the one document that gives you enough context to ask Claude smart questions and ship your first task without getting lost. Read it linearly — it's short on purpose.
+You're about to build inside Example, a project that runs on a small purpose-built dev system. This primer is the one document that gives you enough context to ask Claude smart questions and ship your first task without getting lost. Read it linearly — it's short on purpose.
 
 When you're done, open [/builders](https://example.com/builders) and run `/builder-start`. There's no separate "I have read it" step anymore — reading the primer is on your honor, and the work queue is already open to you.
 
 ---
 
-## What Off the Boats is
+## What this project is
 
-Off the Boats is a web experience that drops visitors into a single, persistent, playable digital world set in ancient Greece. Inside the world, players can spend real money to buy **physical goods** (fulfilled by a third-party logistics company called Example) and **digital assets** that develop the shared world. The world is never wiped — every interaction is permanent. The brand is mythic and underground: prices feel like a discovered secret, and the world reads as ancient even though the inciting object is a literal shipping container washed ashore. Visit [example.com](https://example.com) to see it.
+This primer teaches the **platform** — how you claim work and ship it, the same on every Cloud Bongos instance. *What* you're building here — the product, its world, and its visual style — is specific to this instance and lives in **[`docs/project-context.md`](../project-context.md)**. Read that first for the product; everything below is the build system you'll use to make it.
 
 ## What the GDS is
 
@@ -66,13 +66,13 @@ Four ranks, in ancient-Greek-civilization order:
 
 So the sandbox is short: ship three small `newcomer_friendly` tasks and the city opens the whole queue to you on its own (the jump to **Metic** — with its triage/trust powers — is still a deliberate Archon promotion). Rank lives on the `builders.rank` column in the production database and is checked server-side on every privileged request — **with no caching**. A demotion takes effect on your next request. You cannot escalate your own rank by editing local files; the server is the source of truth. See [ADR 0016](../adr/<redacted>.md) and [ADR 0034](../adr/<redacted>.md) for the full trust model.
 
-## Drachmae and karma
+## Example and karma
 
-Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Drachmae & karma — how you get paid](drachmae-and-karma.md)**; here's the shape of it.
+Two parallel reputation tracks. You don't need to *do* anything special to earn either — claim a task, do good work, ship it, and the system tracks both. The full mechanics (formulas, the kind table, the budget cap, every karma source) live in **[Example & karma — how you get paid](example-and-karma.md)**; here's the shape of it.
 
-- **Drachmae** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your drachmae now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
+- **Example** (called "credits" in code) are your **equity** in the project — a score and a stake, *not* a currency you spend on anything. They only go up, and they persist if you leave and come back. Most of your example now come from a **cost-plus reward on each shipped session**: the server prices the LLM tokens your work actually burned and pays you that real cost **plus 20%** ([ADR 0054](../adr/<redacted>.md)). On top of that, each task pays its `credits_reward` adjusted by the *kind* of work (a captured learning or a resolved blocker is worth 1.5×; cleanup 0.8×), and capturing an idea that someone else then ships earns you a 25% bonus ([ADR 0023](../adr/<redacted>.md)). Credits land at the `completed → confirmed` edge — when verification passes, not at deploy. See the standings on [/builders](https://example.com/builders).
 
-- **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains drachmae and loses karma; a builder who ships thoughtfully gains both.
+- **Karma** is a *separate* signal that measures **peer trust** — how other builders rate the *way* you work, not how much you ship. It's earned when Metic-and-above builders upvote your confirmed work (tallied weekly), when a proposal of yours is ratified, and when you capture ideas; it can also go *down* if you break things. Karma shows up on your profile (with a 30-day trend) and as a sortable column on the leaderboard, and it feeds your "builder strength" score. **It does not gate rank promotions** — those happen automatically by ship count (Xenos → Thetes after three ships) or by an Archon's deliberate decision. A builder who ships fast but breaks things gains example and loses karma; a builder who ships thoughtfully gains both.
 
 One more thing worth knowing: builders are **uncapped by default** — your spend is tracked (it's the cost side of the same coin the reward is computed from) but never blocks you. There's no default budget. An Archon *can* set a per-builder **monthly budget cap** as a manual brake on a runaway; if one is set for you, you get a warning at 80% and `/builder-ship` pauses at 100% until it's raised ([ADR 0085](../adr/<redacted>.md)).
 
@@ -111,7 +111,7 @@ The whole project's source-of-truth index is [`CLAUDE.md`](../../CLAUDE.md). Two
 
 Other depth, in roughly the order you'll need it:
 
-- [`docs/onboarding/drachmae-and-karma.md`](drachmae-and-karma.md) — the full reward economy: how drachmae and karma are earned, the cost-plus session reward, and the monthly budget cap
+- [`docs/onboarding/example-and-karma.md`](example-and-karma.md) — the full reward economy: how example and karma are earned, the cost-plus session reward, and the monthly budget cap
 - [`docs/architecture.md`](../architecture.md) — live system: droplet, stack, schema, API surface
 - [`docs/modules-contract.md`](../modules-contract.md) — the product is built as a small core plus swappable `modules/<key>/` (dev boxes, the game, Discord, art, and more); this is the live roster and how a task lands inside one
 - [`docs/canonical-permissions.md`](../canonical-permissions.md) — who can do what (rank gates)
@@ -190,7 +190,7 @@ If a `/builder-*` command ever says "no GDS session," just run `/builder-setup`
 
 Run `/builder-start` to see what you can claim — no acknowledgment step needed, the queue is open. New builders see only `newcomer_friendly` tasks — small, well-scoped, easy to finish in one sitting. Pick one that looks interesting, claim it with `/builder-claim N`, do the work, and ship it with `/builder-ship`.
 
-When you ship your **first** task, drachmae land in your column and you're inducted as a citizen of Example. Ship your **third** and you graduate to **Thetes** — the one-claim limit lifts and the whole general queue opens to you. Welcome.
+When you ship your **first** task, example land in your column and you're inducted as a citizen of Example. Ship your **third** and you graduate to **Thetes** — the one-claim limit lifts and the whole general queue opens to you. Welcome.
 
 ## Your own dev box
 

package/docs/recipes/audit-replay.md

@@ -15,7 +15,7 @@ Run by an Archon when investigating an incident, a suspected compromise, or a "w
 |---|---|---|
 | `CLAIM` | `claims.claimed_at` | Builder claimed a task — task locked to this session. |
 | `CLAIM_END` | `claims.released_at` + `outcome` | Claim resolved — `outcome` says whether the work shipped, was abandoned, partially completed, or expired. |
-| `CREDIT` | `credit_log.recorded_at` | Drachmae moved (`task.confirmed`, `ship.net_negative`, rank-change audit, etc.) — `delta` is the integer amount. |
+| `CREDIT` | `credit_log.recorded_at` | Example moved (`task.confirmed`, `ship.net_negative`, rank-change audit, etc.) — `delta` is the integer amount. |
 | `COST` | `cost_log.recorded_at` | The builder logged a USD spend — `category` (api / compute / infra / domain / art / other) + `source`. |
 | `SESSION_START` / `SESSION_END` | `session_logs.started_at` / `ended_at` | Claim-scoped working session boundaries. Pair with `outcome` for "shipped / partial / abandoned." |
 | `HTTP_<METHOD>` | `audit_log.recorded_at` | Every authenticated POST / PATCH / PUT / DELETE the builder made — route, status, IP. The forensic fine-grain. |
@@ -23,7 +23,7 @@ Run by an Archon when investigating an incident, a suspected compromise, or a "w
 Notably absent — and worth knowing about so you can ask follow-up questions if needed:
 
 - **GET requests** are not in `audit_log` (by design; high volume, low signal). Read patterns aren't part of this replay.
-- **Builder rank changes** show up as `HTTP_PATCH route=/api/gds/builders/:id/rank` rows and as `CREDIT` rows when the rank change carries a drachmae adjustment. The new rank value lives in `audit_log.request_body_redacted`.
+- **Builder rank changes** show up as `HTTP_PATCH route=/api/gds/builders/:id/rank` rows and as `CREDIT` rows when the rank change carries a example adjustment. The new rank value lives in `audit_log.request_body_redacted`.
 - **Game-server WebSocket events** (movement, world state) live in `world_events` and are NOT included here — this script is GDS-scoped. If a game-side investigation is needed, query `world_events` separately.
 
 ## Running the script

package/docs/recipes/builder-box-lifecycle.md

@@ -105,7 +105,7 @@ Put these in `/etc/example/box.env` (chmod 600 — **secrets never go in the rep
 
 ## Cost (Criterion C1 / cost)
 
-A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to drachmae/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
+A box accrues compute cost **only while `active`**. At park/deprovision the CLI computes `active hours × the size's hourly rate` and writes it to both the `box_events` ledger and `cost_log` (category `compute`, builder-attributed) — so the public status dashboard's per-builder split sees real box spend. `box.js status` prints the active monthly run-rate + total spent. The **rebill to example/earnings** (org-funded starter → self-fund) is a separate task, [#602](https://example.com/builders#/task/602).
 
 ## Going live (one-time operator steps)
 
@@ -143,7 +143,7 @@ These spend money and are intentionally manual.
 - **[#596](https://example.com/builders#/task/596)** (done) — the devcontainer (box-as-code) this provisions.
 - **[#599](https://example.com/builders#/task/599)** — Claude Desktop managed-settings + the stable-hostname cutover the lifecycle records. (The browser-on-ramp is now the ttyd web terminal over a Cloudflare Tunnel — [#760](https://example.com/builders#/task/760)/[ADR 0038](../adr/<redacted>.md) — not the retired `claude rc` Remote-Control service.)
 - **[#600](https://example.com/builders#/task/600)** — rank-gated **source access**: the scoped GitHub credential the box holds, granted/revoked by rank. [#598](https://example.com/builders#/task/598) records `scope`; [#600](https://example.com/builders#/task/600) enforces it.
-- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/drachmae system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
+- **[#602](https://example.com/builders#/task/602)** — cost passthrough (org-funded starter → self-fund via the `costs`/example system). [#598](https://example.com/builders#/task/598) logs the cost; [#602](https://example.com/builders#/task/602) rebills it.
 
 ## Safety properties
 

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

@@ -61,7 +61,7 @@ node scripts/gds/design-sync.js --surface hall-ui
 Use the DesignSync MCP tool in your Claude Code session:
 
 ```
-list_projects      → pick the OTB project (or create "Off the Boats — Design System")
+list_projects      → pick the OTB project (or create "Example — Design System")
 finalize_plan      → stage all files from manifest.files, rooted at bundlePath
 write_files        → push the bundle
 ```

package/docs/recipes/ops-gotchas.md

@@ -119,7 +119,7 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 - **Symptom:** Visitor clicks "Sign in with GitHub" on /builders, GitHub renders its red "Be careful!" warning page or returns `?error=redirect_uri_mismatch`, and the visitor never lands back on the hall.
 - **Root cause:** The GitHub OAuth app's **Authorization callback URL** field must match exactly what the server tells GitHub. Our server sends `${publicOrigin}/api/gds/auth/web/callback` — easy to misconfigure as just `https://example.com/` or `/auth/callback` when registering a fresh OAuth app.
-- **Fix:** In github.com → Settings → Developer settings → OAuth Apps → (the Off the Boats app) → **Authorization callback URL**, set:
+- **Fix:** In github.com → Settings → Developer settings → OAuth Apps → (the Example app) → **Authorization callback URL**, set:
   ```
   https://example.com/api/gds/auth/web/callback
   ```

package/docs/recipes/private-npm-distribution.md

@@ -47,6 +47,23 @@ npm pack ./clients/bongos-client --dry-run        # token-free content preview
 npm publish ./clients/bongos-client               # real (publishConfig makes it restricted; needs npm login)
 ```
 
+## Cutting a core release (the policy — [ADR 0137](../adr/<redacted>.md))
+
+Publishing is a **manual, owner-gated step** — merges to `main` do **not** auto-publish (no npm write-token lives in CI). The update subscription ([ADR 0136](../adr/<redacted>.md)) consumes whatever the owner has published, so a release is exactly: bump → publish → the subscription picks it up on its next sweep.
+
+1. **Bump `CORE_VERSION`** in [`src/module-api.js`](../../src/module-api.js) (semver; a **patch** for a fix, **minor** for additive surface — a **major** is a deliberate, human-only event) and add a one-line changelog entry in the same file. This bump is a normal claimed task, not a release-tool side effect — the version's provenance stays in the git history + changelog.
+2. **Publish** (owner, from a clean checkout of the released commit):
+   ```sh
+   node scripts/gds/package-core.js --publish        # DRY-RUN: runs the fail-closed no-leak gate, previews @bongos/core@<version>
+   npm login                                          # once per machine (+ 2FA), or use a Classic Automation token
+   node scripts/gds/package-core.js --publish --live  # permanent; the no-leak gate must pass or nothing is built/uploaded
+   ```
+   The no-leak / mirror-redact gate is **built into the build** — a leaking artifact is never produced, so `--publish` cannot upload one.
+3. **Tag the release** (optional but recommended — the deliberate, auditable marker): `git tag core-v<version> && git push origin core-v<version>`. The tag documents intent; it triggers no CI.
+4. **Done.** Subscribed instances on the `patch`/`minor` channel take it automatically on their next routine sweep; `pinned` instances wait for a manual `bongos upgrade`. A stale (un-bumped) version is rejected by npm as a duplicate — a natural guard.
+
+> **Automating this** (a tag-triggered CI publish) is deferred to the managed-fleet epic ([#1948](https://example.com/builders#/task/1948)); revisit when the manual step becomes a real bottleneck. See [ADR 0137](../adr/<redacted>.md) "When to revisit".
+
 ## Install a private package (any consumer machine or instance)
 
 Add a one-line `.npmrc` (repo-root or `~/.npmrc`) that reads the token from the environment:

package/docs/recipes/staging-environment.md

@@ -65,7 +65,7 @@ If `*.example.com` is **not** in the output:
 The prod OAuth app points its callback at `example.com/api/gds/auth/web/callback`. Staging needs its own:
 
 1. github.com → Settings → Developer settings → OAuth Apps → New OAuth App.
-2. Application name: `Off the Boats — staging`.
+2. Application name: `Example — staging`.
 3. Homepage URL: `https://staging.example.com`.
 4. Authorization callback URL: `https://staging.example.com/api/gds/auth/web/callback`.
 5. Note the **Client ID** and **Client Secret** — they go into `/home/lars/example-staging/.env` (see step 4 of the provisioning script).

package/docs/recipes/upgrading-the-core.md

@@ -13,6 +13,7 @@
 5. **materialize `.claude/`** — refresh skills/settings/hooks from the new core (`materializeClaude`), rewriting invocations to the `bongos` bin.
 6. **restart** — `--service <unit>` or `--restart-cmd "<cmd>"`.
 7. **verify** — installed version == target (+ optional `--health-url`).
+8. **auto-rollback on failure** (task [#2149](https://example.com/builders#/task/2149), default ON) — if `npm install`/`migrate` fails or the step-7 health check fails, revert the pin → reinstall the previous core → restart → re-verify → write a `rolled_back:` ledger row. Opt out with `--no-rollback-on-failure`. See the section below.
 
 Run bare (`bongos upgrade`, no `--to`) it stays the module-compat **pre-check** only.
 
@@ -50,6 +51,60 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 6. **Update the repo of record** — run the channel on the laptop clone (`--skip-migrate`, no DB there), commit the pin bump (drop the superseded tarball), `git push origin`.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
+## Auto-rollback on failure (task 2149)
+
+By default (`--rollback-on-failure`, ON unless `--no-rollback-on-failure`) the channel self-heals a failed bump. If **`npm install` fails**, **`npm run migrate` fails**, or the **post-restart health check fails**, `bongos upgrade` automatically:
+
+1. reverts the `@bongos/core` pin to the exact pre-upgrade dep string (snapshotted the instant the pin moved),
+2. `npm install`s the previous core back,
+3. restarts the service,
+4. re-verifies (installed == previous, health recovers),
+5. records a `rolled_back: <reason> (attempted N → N+1, restored N)` row in `core_upgrades`.
+
+**The DB is NOT rolled back — only the code pin.** Core migrations are additive + forward-safe (the core migration rule), so an already-applied migration is left in place; a *failed* migration is never recorded in `schema_migrations`, so a retry re-runs it cleanly. The reversal is recorded via the always-present `note` column (not a new `outcome` column) so it lands even in the failed-migrate path — where a newer column wouldn't yet exist on that instance.
+
+**Proven live on demo.cloudbongos.com** (task [#2157](https://example.com/builders#/task/2157)): demo, on rollback-capable 1.17.3, was upgraded to a canary carrying a deliberately-failing migration. Migrate raised → the channel auto-reverted the pin to 1.17.3, reinstalled + restarted it, `/healthz` stayed 200 (**zero downtime** — the failure was at migrate, before the restart), and a `rolled_back` ledger row was written. This is the safety gate the unattended patch-only auto-upgrade subscription (task [#2150](https://example.com/builders#/task/2150)) depends on.
+
+## Subscribing to updates — unattended patch-only auto-upgrade (task 2150 / ADR 0136)
+
+The sections above are the *manual* `bongos upgrade`. The **subscription** runs it for you, on a cadence, safely — the "subscribe to regular updates" experience. Policy: **patch-only by default, health-gated with auto-rollback, opt-in, autonomy-gated** (full rationale in [ADR 0136](../adr/<redacted>.md)).
+
+**Per-instance channel** bounds how far an unattended upgrade may jump:
+
+| channel | takes | example (from `1.17.1`) |
+|---|---|---|
+| `pinned` | nothing (manual only) | — |
+| `patch` *(default)* | higher patch, same `x.y` | `→ 1.17.4`, never `1.18.0` |
+| `minor` | higher minor, same major | `→ 1.18.0`, never `2.0.0` |
+
+A **major** is never automatic; prereleases are never auto-targeted.
+
+**Enrolling an instance** — add it to [`config/update-subscriptions.json`](../../config/update-subscriptions.json) (ships empty). `env` carries per-instance vars merged into the upgrade child — set `PGDATABASE` so `migrate` hits the right DB (see the Gotchas):
+
+```json
+{
+  "defaultChannel": "patch",
+  "instances": [
+    { "slug": "demo", "dir": "/srv/cloudbongos/demo", "service": "demo.service",
+      "healthUrl": "https://demo.cloudbongos.com/healthz", "channel": "patch",
+      "env": { "PGDATABASE": "demo" } }
+  ]
+}
+```
+
+**Preview vs run** — dry-run is the default; the scheduled step passes `--apply`:
+
+```bash
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js            # plan only
+node .claude/scheduled-tasks/core-update-subscription/subscribe.js --apply    # upgrade
+```
+
+Each subscribed instance: read its installed core → ask the registry (`npm view`, needs `NPM_TOKEN`) → resolve the newest version its channel permits → if newer, `bongos upgrade --to <v> --registry` with **auto-rollback ON**. It prints one line per instance plus a tally; a non-zero exit means an upgrade failed (already auto-reverted).
+
+**Triple-gated, so nothing moves by accident:** the `core-update-subscription` routine is `requiresAutonomy: true` + **default OFF** in [`config/scheduled-routines.json`](../../config/scheduled-routines.json), the roster ships empty, and every upgrade is health-gated. Arm it by enabling the routine's timer on the control plane once autonomy is on.
+
+**Not covered:** multi-host / SSH orchestration across a real fleet (the deferred fleet-control-plane epic, task [#1948](https://example.com/builders#/task/1948)); and *publishing* new patches, which stays a gated owner step (ADR 0134) — a follow-up task decides whether merges auto-publish.
+
 ## Gotchas
 
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.

package/docs/research/cursor-competitive-analysis.md

@@ -1,6 +1,6 @@
 # Cursor (Anysphere) — Competitive-Threat Analysis for Cloud Bongos
 
-**A competitor-research document for Cloud Bongos / Off the Boats**
+**A competitor-research document for Cloud Bongos / Example**
 Prepared 2026-06-22 · the **first committed competitor doc** in this repo · companion to the (uncommitted) `component-based-dev-research.md` deep-research doc · task [#1403](https://example.com/builders#/task/1403)
 
 ---

package/docs/research/llm-model-agnostic-and-cheaper-grader.md

@@ -1,6 +1,6 @@
 # LLM Model-Agnostic Platform + Cheaper Grader — Tools Audit & Architecture Path
 
-**A research/architecture spike for Cloud Bongos / Off the Boats**
+**A research/architecture spike for Cloud Bongos / Example**
 Prepared 2026-06-28 · task [#1069](https://example.com/builders#/task/1069) · GDS-V4 · track `internal`
 
 ---

package/modules/discord/module.json

@@ -10,5 +10,6 @@
     "uiSections": []
   },
   "provides": ["discord.isLinked"],
-  "consumes": ["ideas.capture"]
+  "consumes": ["ideas.capture"],
+  "dependencies": { "discord.js": "^14.26.4" }
 }

package/modules/economy/achievements.js

@@ -424,7 +424,15 @@ async function getLeaderboardWithAchievements(limit = 10, perBuilderCap = 5) {
                    ORDER BY a.sort_order
                    LIMIT $2
                 ) t
-            ), ARRAY[]::text[]) AS achievements
+            ), ARRAY[]::text[]) AS achievements,
+            -- task 1473: mirror of credits.leaderboard's tokens_used — total
+            -- transcript tokens across this builder's sessions, so the public
+            -- leaderboard shows efficiency (tokens per drachma) beside credits.
+            COALESCE((
+              SELECT SUM(sr.total_tokens)
+                FROM session_records sr
+               WHERE sr.builder_id = b.id
+            ), 0)::bigint AS tokens_used
        FROM builders b
        ORDER BY b.total_credits DESC, b.created_at ASC
        LIMIT $1`,

package/modules/economy/credits.js

@@ -37,7 +37,16 @@ async function leaderboard(limit = 20) {
                    ORDER BY a.sort_order
                    LIMIT 5
                 ) t
-            ), ARRAY[]::text[]) AS achievements
+            ), ARRAY[]::text[]) AS achievements,
+            -- task 1473: total transcript tokens across all of this builder's
+            -- recorded sessions, so the hall leaderboard can show efficiency
+            -- (tokens spent per drachma earned) next to credits. Mirrored in
+            -- achievements.getLeaderboardWithAchievements (the /public query).
+            COALESCE((
+              SELECT SUM(sr.total_tokens)
+                FROM session_records sr
+               WHERE sr.builder_id = builders.id
+            ), 0)::bigint AS tokens_used
        FROM builders
        ORDER BY total_credits DESC, created_at ASC
        LIMIT $1`,

package/modules/hall-ui/public/builders.js

@@ -1782,6 +1782,45 @@
     }).join('');
   }
 
+  // ---- idea-inbox triage cue (task 1471) -----------------------------------
+
+  // Render the Metic+ triage widget: the open-idea count + a few recent titles,
+  // each deep-linking to the #/idea/N overlay (which carries the Metic+ Discard
+  // control). Only ever called for a Metic+ viewer (loadAll gates the fetch), so
+  // reaching here is what un-hides the section — a non-triager never loads or
+  // sees any idea data. Fully failure-isolated by its caller.
+  function renderTriageInbox(data) {
+    const section = document.getElementById('triage-inbox');
+    if (!section) return;
+    const open = (data && Array.isArray(data.ideas) ? data.ideas : [])
+      .filter((i) => i && i.status === 'open');
+    const openCount = data && data.open_count != null ? data.open_count : open.length;
+
+    const countEl = document.getElementById('triage-inbox-count');
+    if (countEl) {
+      countEl.textContent = `${fmtNum(openCount)} open`;
+      countEl.hidden = false;
+    }
+    const listEl = document.getElementById('triage-inbox-list');
+    if (listEl) {
+      if (!open.length) {
+        listEl.innerHTML = '<li class="triage-inbox__empty">Inbox clear — nothing awaiting triage.</li>';
+      } else {
+        listEl.innerHTML = open.slice(0, 8).map((i) => {
+          const title = escapeHtml(i.title || `idea #${i.id}`);
+          const kind = i.kind
+            ? `<span class="triage-inbox__kind">${escapeHtml(i.kind)}</span>`
+            : '';
+          return `<li class="triage-inbox__item">`
+            + `<a class="triage-inbox__link" href="#/idea/${encodeURIComponent(i.id)}">${title}</a>`
+            + kind
+            + `</li>`;
+        }).join('');
+      }
+    }
+    section.hidden = false;
+  }
+
   // ---- leaderboard ---------------------------------------------------------
 
   // Locked at 8 for V2 (per limitations/pms-v2.md). Hardcoding here avoids an
@@ -1816,7 +1855,7 @@
     page: 0,
     pageSize: 25,   // task 1750: top-100 Roll — 25/page keeps it to a few pages
 
-    sortBy: 'drachmae',     // 'rank' | 'drachmae' | 'karma'
+    sortBy: 'drachmae',     // 'rank' | 'drachmae' | 'karma' | 'tokens'
     sortDir: 'desc',        // 'desc' | 'asc'
   };
 
@@ -1852,6 +1891,23 @@
         })
         .map(({ row }) => row);
     }
+    if (lbState.sortBy === 'tokens') {
+      // task 1473: sort by total tokens used. tokens_used arrives as a string
+      // (pg bigint), so coerce. Tie-break on drachmae DESC then server order,
+      // matching the karma branch.
+      return indexed
+        .sort((a, b) => {
+          const at = Number(a.row.tokens_used) || 0;
+          const bt = Number(b.row.tokens_used) || 0;
+          const diff = (at - bt) * dir;
+          if (diff !== 0) return diff;
+          const ac = Number(a.row.total_credits) || 0;
+          const bc = Number(b.row.total_credits) || 0;
+          if (ac !== bc) return bc - ac;
+          return a.idx - b.idx;
+        })
+        .map(({ row }) => row);
+    }
     if (lbState.sortBy === 'drachmae') {
       // Server already DESCs by drachmae, so the default mode is a no-op
       // copy. The ASC branch flips it.
@@ -1869,13 +1925,14 @@
   }
 
   // Map a sortable column id → the lbState.sortBy key. Adding a new sortable
-  // column means adding an entry here + a header in index.html with id
-  // `lb-sort-<key>`. The handler walks aria-sort across all three headers so
+  // column means adding an entry here + a header in hall-widgets.js with id
+  // `lb-sort-<key>`. The handler walks aria-sort across all sortable headers so
   // only one column shows its arrow at a time.
   const LB_SORT_HEADERS = {
     rank: 'lb-sort-rank',
     drachmae: 'lb-sort-drachmae',
     karma: 'lb-sort-karma',
+    tokens: 'lb-sort-tokens',
   };
 
   // #757: this builder's place on the Roll, ranked by drachmae (total_credits)
@@ -1902,7 +1959,7 @@
     const tbody = $('#leaderboard tbody');
 
     if (!slice.length) {
-      tbody.innerHTML = emptyRow(5, 'No more builders to show.');
+      tbody.innerHTML = emptyRow(6, 'No more builders to show.');
     } else {
       tbody.innerHTML = slice.map((b, i) => {
         const place = start + i + 1;
@@ -1922,6 +1979,7 @@
             <td class="ledger__rank">${rank}</td>
             <td class="ledger__drachmae">${fmtNum(b.total_credits)}</td>
             <td class="ledger__drachmae">${fmtNum(b.karma)}</td>
+            <td class="ledger__drachmae" title="${Number(b.total_credits) > 0 ? `${fmtNum(Math.round(Number(b.tokens_used) / Number(b.total_credits)))} tokens per drachma` : 'no drachmae earned yet'}">${fmtNum(b.tokens_used)}</td>
           </tr>
         `;
       }).join('');
@@ -2633,6 +2691,15 @@
     applyNewcomerGate();
     renderNav(me.builder, me.onboarding || null);
 
+    // task 1471: idea-inbox triage cue — Metic+ only (triage is a Metic+ action).
+    // Fetched fire-and-forget so a slow/large inbox can't hold up the hall; the
+    // widget is hiddenByDefault, so a non-triager never loads or sees idea data.
+    if (['metic', 'archon'].includes(normalizeRank(me.builder?.rank))) {
+      getJSON(`${API}/inbox`)
+        .then((data) => renderTriageInbox(data))
+        .catch(() => { /* nice-to-have; never break the hall */ });
+    }
+
     // Then the rest, in parallel. Any individual section failure shouldn't take
     // down the page — log and show an inline placeholder.
     // #726: the per-skill model picker (Voices) moved to /builders/settings,

package/modules/hall-ui/public/goal-inbox.js

@@ -0,0 +1,191 @@
+// goal-inbox.js — the home-page, two-sided goal-membership inbox (task 1954, ADR 0112).
+//
+// Surfaces the actionable slice of a builder's private-goals queue in ONE place:
+//   • "Invitations to you" — pending invites addressed to me (Accept / Decline).
+//   • "Requests to approve" — pending join-requests on goals I own or manage
+//                             (Approve / Deny).
+//   • a quiet "your pending requests" line for my own outstanding asks.
+// Reads GET /goals/inbox (task 1952) which already scopes each bucket to the caller.
+// Registers into the window.OTB hall-widget registry (dom-utils.js) exactly like
+// goals.js — same IIFE guard, same BongosClient result-mode getJSON, view:'home'.
+//
+// The whole card is HIDDEN when the inbox is empty, so a quiet home page pays nothing
+// for it. On an older server without the route (404) — or a signed-out visitor (401) —
+// it renders nothing (feature-detect), never an error card.
+(function () {
+  'use strict';
+  if (!window.OTB || typeof window.OTB.contributeHallWidget !== 'function') return;
+  const { escapeHtml, toast, rankLabel } = window.OTB;
+  const API = '/api/bongos';
+  // The generated typed client (served as window.BongosClient), result-mode so the
+  // status-inspecting control flow below (401/404 → render nothing) reads 1:1.
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  async function getJSON(path) {
+    const res = await api.request('GET', path);
+    if (res.status === 401) { const e = new Error('auth-needed'); e.code = 'auth-needed'; throw e; }
+    if (res.status === 404) { const e = new Error('not-found'); e.code = 'not-found'; throw e; }
+    if (!res.ok) throw new Error(`${path} → ${res.status}`);
+    return res.data;
+  }
+  async function postJSON(path, body) {
+    const res = await api.request('POST', path, { body: body || {} });
+    if (!res.ok) { const e = new Error(`${path} → ${res.status}`); e.status = res.status; e.data = res.data; throw e; }
+    return res.data;
+  }
+
+  let host = null;
+  let busy = false;
+
+  // The goal-detail hash route on the Goals page (matches goals.js's row link).
+  const goalHref = (goalId) => `/goals#/goal/${encodeURIComponent(goalId)}`;
+  const noteHtml = (note) => (note ? `<p class="ginbox__note">“${escapeHtml(note)}”</p>` : '');
+
+  function invitationRow(inv) {
+    const who = inv.invited_by_name || inv.invited_by_login || 'someone';
+    return `<li class="ginbox__item" data-goal="${escapeHtml(String(inv.goal_id))}">
+        <div class="ginbox__body">
+          <a class="ginbox__goal" href="${goalHref(inv.goal_id)}" title="Open ${escapeHtml(inv.goal_title || 'goal')}">${escapeHtml(inv.goal_title || 'a goal')}</a>
+          <span class="ginbox__sub">invited by ${escapeHtml(who)}</span>
+          ${noteHtml(inv.note)}
+        </div>
+        <div class="ginbox__actions">
+          <button class="btn-ghost" type="button" data-accept-inv="${escapeHtml(String(inv.id))}">Accept</button>
+          <button class="btn-ghost" type="button" data-decline-inv="${escapeHtml(String(inv.id))}">Decline</button>
+        </div>
+      </li>`;
+  }
+
+  function requestRow(r) {
+    const who = r.display_name || r.github_login || 'a builder';
+    const rank = r.rank ? ` · ${escapeHtml(rankLabel(r.rank, { empty: '' }))}` : '';
+    return `<li class="ginbox__item" data-goal="${escapeHtml(String(r.goal_id))}">
+        <div class="ginbox__body">
+          <a class="ginbox__goal" href="${goalHref(r.goal_id)}" title="Open ${escapeHtml(r.goal_title || 'goal')}">${escapeHtml(r.goal_title || 'a goal')}</a>
+          <span class="ginbox__sub">${escapeHtml(who)}${rank} asks to join</span>
+          ${noteHtml(r.note)}
+        </div>
+        <div class="ginbox__actions">
+          <button class="btn-ghost" type="button" data-approve-req="${escapeHtml(String(r.id))}">Approve</button>
+          <button class="btn-ghost" type="button" data-deny-req="${escapeHtml(String(r.id))}">Deny</button>
+        </div>
+      </li>`;
+  }
+
+  function pendingLine(myPending) {
+    if (!myPending.length) return '';
+    const links = myPending
+      .map((r) => `<a href="${goalHref(r.goal_id)}">${escapeHtml(r.goal_title || 'a goal')}</a>`)
+      .join(', ');
+    const noun = myPending.length === 1 ? 'request' : 'requests';
+    return `<p class="ginbox__pending card-foot">Your pending join ${noun}: ${links} — awaiting approval.</p>`;
+  }
+
+  function render(inbox) {
+    const invitations = inbox.invitations || [];
+    const joinRequests = inbox.joinRequests || [];
+    const myPending = inbox.myPendingRequests || [];
+    // Hide the whole card when there is nothing to see OR act on.
+    if (!invitations.length && !joinRequests.length && !myPending.length) {
+      host.hidden = true;
+      host.innerHTML = '';
+      return;
+    }
+    const actionable = invitations.length + joinRequests.length;
+    let html = `<h2 id="goal-inbox-h" class="scroll__h">Goal inbox${actionable ? `<span class="count-pill">${actionable}</span>` : ''}</h2>`;
+    if (actionable) {
+      html += '<p class="scroll__lede">Invitations and join-requests waiting on you.</p>';
+    }
+    if (invitations.length) {
+      html += '<h3 class="ginbox__sec-h">Invitations to you</h3>';
+      html += `<ul class="ginbox">${invitations.map(invitationRow).join('')}</ul>`;
+    }
+    if (joinRequests.length) {
+      html += '<h3 class="ginbox__sec-h">Requests to approve</h3>';
+      html += `<ul class="ginbox">${joinRequests.map(requestRow).join('')}</ul>`;
+    }
+    html += pendingLine(myPending);
+    host.innerHTML = html;
+    host.hidden = false;
+  }
+
+  async function load() {
+    if (!host) return;
+    try {
+      const inbox = await getJSON(`${API}/goals/inbox`);
+      render(inbox);
+    } catch (err) {
+      // Signed out (401) or an older server without the route (404) → render nothing.
+      host.hidden = true;
+      host.innerHTML = '';
+      if (err.code !== 'auth-needed' && err.code !== 'not-found') {
+        console.error('[hall] goal inbox load failed', err);
+      }
+    }
+  }
+
+  // One action, then refresh the widget (the row it acted on disappears, and the
+  // count-pill/live counter re-derive from the fresh inbox). Disable while in flight
+  // so a double-click can't fire the resolve twice (the server 409s a re-resolve, but
+  // the UI shouldn't invite it).
+  async function act(fn, okMsg) {
+    if (busy) return;
+    busy = true;
+    host.querySelectorAll('button').forEach((b) => { b.disabled = true; });
+    try {
+      await fn();
+      toast(okMsg);
+      await load();
+    } catch (err) {
+      toast((err && err.data && err.data.message) || 'Could not do that just now — refresh and retry.');
+      host.querySelectorAll('button').forEach((b) => { b.disabled = false; });
+    } finally {
+      busy = false;
+    }
+  }
+
+  function onClick(e) {
+    const item = e.target.closest('.ginbox__item');
+    const goalId = item && item.dataset.goal;
+    if (!goalId) return;
+
+    const accept = e.target.closest('[data-accept-inv]');
+    if (accept) {
+      act(() => postJSON(`${API}/goals/${encodeURIComponent(goalId)}/invitations/${encodeURIComponent(accept.dataset.acceptInv)}/respond`, { action: 'accept' }),
+        'Invitation accepted — you’re now a member.');
+      return;
+    }
+    const decline = e.target.closest('[data-decline-inv]');
+    if (decline) {
+      act(() => postJSON(`${API}/goals/${encodeURIComponent(goalId)}/invitations/${encodeURIComponent(decline.dataset.declineInv)}/respond`, { action: 'decline' }),
+        'Invitation declined.');
+      return;
+    }
+    const approve = e.target.closest('[data-approve-req]');
+    if (approve) {
+      act(() => postJSON(`${API}/goals/${encodeURIComponent(goalId)}/requests/${encodeURIComponent(approve.dataset.approveReq)}/respond`, { action: 'approve' }),
+        'Approved — they’re now a member.');
+      return;
+    }
+    const deny = e.target.closest('[data-deny-req]');
+    if (deny) {
+      act(() => postJSON(`${API}/goals/${encodeURIComponent(goalId)}/requests/${encodeURIComponent(deny.dataset.denyReq)}/respond`, { action: 'deny' }),
+        'Request denied.');
+    }
+  }
+
+  function mount(hostEl) {
+    host = hostEl;
+    host.hidden = true; // stays hidden until load() finds something actionable
+    host.addEventListener('click', onClick);
+    load();
+  }
+
+  // order 24 → sits at the top of the Home main zone (just above the idea-triage
+  // inbox), since it is personal + actionable. hiddenByDefault so an empty inbox
+  // costs nothing until load() un-hides it.
+  window.OTB.contributeHallWidget({
+    id: 'goal-inbox-scroll', label: 'Goal inbox', order: 24, mount,
+    labelledby: 'goal-inbox-h', view: 'home', zone: 'home-main', hiddenByDefault: true,
+  });
+})();