@bongos/core 1.17.0 → 1.17.2

package/modules/economy/CLAUDE.md

@@ -1,48 +1,15 @@
-# `economy` module — credits, cost ledger, streaks, achievements, leaderboard + the `reward` kernel port
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **third CORE-domain** carved into a module (BV1.R77, [ADR 0093](../../docs/adr/<redacted>.md) §1-2) — after memory (R72) and grading (R73). Like grading, it follows ADR 0091 §4's load-bearing pattern: **keep the lifecycle state machine whole, extract the capability it invokes behind a kernel seam.** The lifecycle no longer imports the credit/achievement code directly; it resolves a `reward` PORT this module registers.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-Owns the **builder economy**: the cost-plus + kind-multiplier credit-allocation model (the real-money credit ledger), the idea-promotion bonus, the flat session-token reward, the net-negative (simplification) ship bonus, the cost ledger + dashboard rollups, builder streaks, achievements/gamification, and the leaderboard. `default: true` in `module.json` — every instance rewards its own builders, so it mounts unconditionally unless explicitly disabled.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-## The boundary (the one rule)
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.7.0` — it needs the R77 doorway addition: `llmPricing`, the shared token→USD pricing lib). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches economy only through the `reward` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks; R70's `kernel-imports-no-domain` check keeps the kernel from reaching back in.
-
-## The `reward` kernel PORT (ADR 0093 §1-2 — the headline of this carve)
-
-- **Provides — port `reward`** → the economy module's reward surface (`modules/economy/reward.js`). Registered in `routes/reward.js`'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider duplicate guard).
-- **It is a TRANSACTION-PARTICIPANT port** (unlike the stateless `grade` port): the credit-allocation methods (`insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardNetNegativeBonus`, `awardSessionTokenReward`) and the claim/ship gamification hooks (`evaluateAfterClaim/Ship/CreditAward`) take the **caller's tx `client` as the first arg**. The core lifecycle opens the `withTx`, runs the state-machine SQL (FOR UPDATE, `task_grades` upsert, `UPDATE tasks status`, claim-holder lookup, `logGradeAttempt`) itself, and calls `reward.*(client, …)` inside that same transaction — so the credit write commits atomically with the status flip. Extract the capability; keep the state machine (ADR 0091 §4).
-- **Core consumes it WITHOUT importing this module:**
-  - the LIFECYCLE — `db.applyGrade` / `db.confirmTask` / `db.decideOverrideRequest` / `db.claimTask` / `db.upsertSessionRecordWithReward` resolve it via `seams.resolveOptional('reward')` and call the credit/achievement methods inside their own `withTx`.
-  - the READ routes — `routes/me.js` (achievement getters + streak preview + `getBuilderCostStatus`), `routes/public.js` (`costSummary` + `getLeaderboardWithAchievements`), `routes/builders.js` (`setBuilderMonthlyBudget`), `routes/sessions.js` (`sumCreditsForTasks`), and `publish-reconciler.js` (`reconcileSessionCosts`) resolve the same port and call its read surface. economy registers ONE port; its provider exposes both the lifecycle methods and the read surface (the grading precedent registers the whole module surface on its single port too).
-- This replaced the former `const achievements = require('./achievements')` / `cost` / `cost-summary-shape` core→domain requires in `db.js`, the `db.leaderboard`/`db.logCost`/etc. monolith helpers, and the `require('../streak')` core-route imports.
-
-## Files
-
-| File | What |
-|---|---|
-| `credits.js` | the credit-allocation model: `KIND_MULTIPLIERS`/`IDEA_BONUS_FRACTION`/`REWARD_MARGIN_PCT`, `applyKindMultiplier`, `computeSessionTokenReward`, `insertMultipliedConfirmCredit`, `maybeAwardIdeaPromotionBonus`, `awardSessionTokenReward`, `awardNetNegativeBonus` (+ `NET_NEGATIVE_BONUS`/`SUBTRACTOR_THRESHOLD`/`netNegativeBonusAmount`), the `leaderboard`, and `sumCreditsForTasks`. Writes `credit_log`. |
-| `cost.js` | the cost ledger: `logCost` (the one `cost_log` writer), `reconcileSessionCosts`, `costSummary`/`costCalibrationSummary`, `getBuilderCostStatus`, `setBuilderMonthlyBudget`, `autonomousApiSpendMtd`. |
-| `cost-classify.js` | pure cost-attribution audit + budget classification (`classifyCostStatus`, `auditCostAttribution`, `formatAuditReport`, `OWNERLESS_CATEGORIES`, `SOFT_CAP_FRACTION`). Moved from `src/bongos/cost.js` (renamed to avoid colliding with `cost.js`). |
-| `cost-summary-shape.js` | pure cost-summary dimension shapers (`shapeBySource`/`shapeByTier`/`shapeSavings`/`shapeCostCalibration`). |
-| `streak.js` | streak math + anti-gaming guards (`computeStreak`, `wouldExtendStreak`, …). Reaches the shared pool through the doorway. |
-| `achievements.js` | the achievement evaluators (`evaluateAfterClaim/Ship/CreditAward`, `alreadyUnlocked`, `unlockAchievement`, `filesForBadges`) PLUS the getter slice moved from `db.js` (`listAchievements`, `getBuilderAchievements`, `getLeaderboardWithAchievements`, `getLockedAchievementsProgress`, `renderProgressText`). `require('./streak')` is an intra-module sibling. |
-| `reward.js` | the `reward` port provider surface — DELEGATES (does not spread) to `credits`/`achievements`/`cost`/`streak` so test stubs bite at call time. |
-| `routes/reward.js` | registers the `reward` port (above); no HTTP endpoint. |
-| `routes/cost.js` | `POST /cost` — log a cost row (idempotent). Reaches auth/validators via the doorway; the writer via `../cost`. |
-| `routes/leaderboard.js` | `GET /leaderboard` — public drachmae-ordered leaderboard, via `../credits`. |
-
-## NOT in this module (deliberately left in core)
-
-- **`llm-pricing.js`** — the shared token→USD pricing lib stays core shared LLM-cost infra (consumed by BOTH this module's reward/cost paths AND core cost scripts `ship.js`/`session-cost.js`, so it can't be economy-owned). It is exposed to this module on the doorway as `api.llmPricing` (a tracked R73-style domain leak, like `api.llmCache`). It relocates behind a port if/when an llm-infra domain is carved (tranche 2). The economy scope-map glob lists `src/bongos/llm-pricing.js` for task-affinity even though the FILE stays in core.
-- **The recent-ships feed + estimation-drift + grade-trend reads** (`db.recentShippedTasks`, `<redacted>`, `getEstVsActualRatio`, `estimationDriftSummary`, `recentGradesForBuilder`, `builderRollingAvgGrade`, `rollingAvgGrade`, `gradeTrendByDay`) — these stay `db.*` (lifecycle/sessions reads, not economy ledger SQL); out of scope for this carve.
-- **The karma feed** (`recentKarmaForBuilder`, `karmaDelta30d`, `karma_log`) — stays in core `db.js` (a separate social-signal domain).
-- **The economy-owned CLIs** — a command travels with its domain but stays under `scripts/`: `backfill-cost.js` (requires `../../modules/economy/cost-classify`), `diagnose-achievements.js` (requires `../../modules/economy/streak`). (The memory/grading-carve precedent.)
-
-## Tables
-
-None owned. `credit_log`, `cost_log`, `cost_baseline`, `achievements`, `builder_achievements` (+ their migrations) were created before the module system and stay in core `migrations/` (the schema-migrations stem-key makes a later relocation a no-op). The module owns the *queries*; any **new** economy migration belongs in `modules/economy/migrations/` namespaced `economy_*` (the additive rule).
-
-## Tests
-
-`tests/credit_grant.mjs` (credits.js), `tests/cost.mjs`/`tests/cost_audit.mjs`/`tests/cost_budget_status.mjs` (cost-classify.js), `tests/cost_summary_shape.mjs`, `tests/streak.mjs`, and `tests/diff_derived_signals.mjs` import from `modules/economy/…`. The lifecycle-attribution tests (`tests/grade_attribution.mjs`, `tests/confirm_attribution.mjs`, `tests/grade_server_authoritative.mjs`, `tests/override_attribution.mjs`, `tests/override_request_ownership.mjs`) register the `reward` port (and stub `achievements` on the live module object) before driving `db.applyGrade`/`confirmTask`/`decideOverrideRequest`. See ADR 0093.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

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/grading/CLAUDE.md

@@ -1,42 +1,15 @@
-# `grading` module — the grade-a-diff adversarial panel + the `grade` kernel port
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> The **second CORE-domain** carved into a module (BV1.R73, [ADR 0091](../../docs/adr/<redacted>.md) §1+§4) — after memory (R72). It is the carve that proves ADR 0091 §4's load-bearing pattern: **keep the lifecycle state machine whole, extract the capability it invokes behind a kernel seam.** The lifecycle no longer imports the grader directly; it resolves a `grade` PORT this module registers.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-Owns the **quality gate**: the v4 adversarial worker panel (Narc / Quality / Hacker / Efficiency, unanimous-PASS), the deterministic pre-passes (route-rank + permission-path, run as panel inputs), and the scoring **rubric**. `default: true` in `module.json` — every instance grades its own ships, so it mounts unconditionally unless explicitly disabled.
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-## The boundary (the one rule)
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-This module reaches core **only** through the published doorway `../../src/module-api.js` (`coreVersion ^1.6.0` — it needs the R73 doorway additions: `routeRankCheck`, `permissionPathCheck`, `llmCache`). It must **never** `require()` a core internal directly, and never another module. Core, in turn, must never `require()` a file in here — it reaches grading only through the `grade` port (below). Both directions are enforced by the BV1.R44/R45 fitness checks; R70's `kernel-imports-no-domain` check keeps the kernel from reaching back in.
-
-## The `grade` kernel PORT (ADR 0091 §4 — the headline of this carve)
-
-- **Provides — port `grade`** → the grader module surface. Registered in `routes/grade.js`'s factory (the loader runs it at boot, and again whenever a test rebuilds the GDS router — `hasProvider`-guarded so re-instantiation never trips the single-provider duplicate guard).
-- **Core consumes it WITHOUT importing this module:**
-  - `routes/tasks.js` (the LIFECYCLE ship path, `POST /tasks/:id/grade`) resolves it via `seams.resolveOptional('grade')` and calls `grade.validateAndScore(...)` then `grade.serverSideGuards(...)`. A grading-disabled instance gets a clean `503 grading_unavailable` instead of a thrown `resolve()`.
-  - `routes/public.js` (`GET /public/grades`) resolves it the same way and reads `grade.RUBRIC.{threshold,version}`, falling back to `null` when grading is off.
-- This replaced the former `const grader = require('../grader')` core→domain import in both files — the edge ADR 0091 §4 set out to sever.
-
-Why a route factory for a module with **no HTTP routes**: `mountModuleRoutes` is the only loader hook that runs both in the live server and when a test rebuilds the GDS router, so it's where the port registration belongs. The factory returns an empty `express.Router()` purely as the mount vehicle.
-
-## Files
-
-| File | What |
-|---|---|
-| `grader.js` | the quality gate (~86 KB): v4 adversarial panel + `validateAndScore`/`serverSideGuards`/`gradeSubagent`/`RUBRIC`. The deterministic pre-passes reach `routeRankCheck`/`permissionPathCheck` through the doorway; `runSubagentCached` wraps spawns in the doorway's `llmCache`. |
-| `grader-workers/` | the four worker modules (`narc`/`quality`/`hacker`/`efficiency`) + shared kit (`fence`, `worker-prompt`, `worker-verdict`, `rubric`, `extract-json`, `index`). All intra-module relative requires — unchanged by the move. |
-| `grader-rubric.json` | the single-source scoring rubric (thresholds, per-worker config). Read by `grader.js` + `grader-workers/rubric.js` via `__dirname`-relative paths — survives the move. |
-| `routes/grade.js` | registers the `grade` port (above); no HTTP endpoint. |
-
-## NOT in this module (deliberately left in core)
-
-- **`cascade-dispatch.js`** — stays in `src/bongos/`. It is dormant System 3 (model-tier dispatch, `OTB_AUTONOMY_ENABLED`-gated; nothing calls it but its mock unit test), and its real dependencies are core `task-classifier` (lifecycle) + `skill-prefs` (builder-settings), **not** the grader (the grader is an injected `runner`, never imported). Moving it would force two gratuitous doorway domain-leaks (`classifyTaskKind`, `skill-prefs.getForBuilder`) for capabilities grading never uses — the "ceremony with no boundary benefit" ADR 0091 §Alternatives rejects. It stays a core lib (scoped to `grading` in `module-scope-map.js`) until autonomy/dispatch is carved (tranche 2). The grading scope-map glob lists it as a core file, not part of this dir.
-- **`scripts/gds/grade-smoke.js`** + the other grading-owned CLIs — a command travels with its domain but stays under `scripts/gds/` (the memory-carve precedent). They `require('../../modules/grading/grader')`.
-- **`llm-cache.js`** — shared LLM-cost infra core also uses (`routes/llm-cache.js`, the cost scripts); it stays core and is exposed to this module on the doorway as `api.llmCache` (a tracked R70 leak).
-
-## Tables
-
-None owned. The grade-attempt rows (`grades`, `grade_attempts`, …) are written by core `db.applyGrade` on the lifecycle side; grading only computes the verdict the route then persists. No `modules/grading/migrations/` yet.
-
-## Tests
-
-`tests/grader.mjs`, `tests/grader_panel.mjs`, `tests/grader_prompt_fencing.mjs`, `tests/grade_server_authoritative.mjs`, `tests/grade_unavailable_display.mjs` import from `modules/grading/…`. `tests/cascade-dispatch.mjs` still imports `src/bongos/cascade-dispatch.js` (it stayed core). `scripts/gds/grade-smoke.js` is the live panel smoke.
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

package/modules/hall-ui/CLAUDE.md

@@ -1,61 +1,15 @@
-# `hall-ui` module — the authenticated builders' hall
+# @bongos/core — installed platform dependency (not your project's CLAUDE.md)
 
-> A CORE-domain carve (BV1.R85, [ADR 0093](../../docs/adr/<redacted>.md) §1) — the **second WEB-SURFACE module** ([02-module-map §6](../../docs/design/modular-architecture/02-module-map.md): "a web surface is first-class"), after status-UI (BV1.R84), and the **largest** (~13k LOC). `default: true` — a Cloud Bongos instance ships its hall like it ships its status page, so it mounts unconditionally unless an instance disables it.
+This file is a placeholder shipped inside the **@bongos/core** package. The core's own
+internal agent notes are intentionally omitted from the published artifact so they cannot
+load into your instance's context.
 
-Owns the authenticated builders' hall served at **`builders.<apex>`** (`builders.example.com`) — the roster, the Work Board, standing/karma, the leaderboard, achievements, the citizen's primer, the system maps, the Repo Atlas, Settings, the dev-box pair page, and the Archon-only watch/harbor/gate pages. A no-framework single-page surface (`builders.js` + per-page `*.js`) that polls `/api/gds/*` and the read-only `/api/gds/public/*` surface (live updates ride the SSE channel, `routes/live.js`).
+**It does not govern this repository.** Your own root `CLAUDE.md`, your `.claude/`
+directory, and the live Bongos database are the source of truth for how work happens here
+and who may do what.
 
-## The shape: a static surface, but with DEDICATED serving (the difference from status-UI)
+You are seeing this only because an agent opened a file under `node_modules/@bongos/core/`.
+Nothing in here needs to be read to use the platform — run `bongos help` for commands.
 
-Like status-UI this module has **no `.js` backend, no `db.js` slice, no kernel port, and no routes**. It is purely:
-- `public/` — the static hall (HTML/CSS/JS/cursors/chime.wav), moved verbatim from the old repo-root `public-builders/`.
-- `module.json` — declares one **`contributes.webSurfaces`** entry `{ host: "builders.", dir: "public" }`.
-
-**But the hall is NOT served by the generic web-surface loop that serves status-UI.** The status page is a plain static surface; the hall has far richer serving that MUST be byte-identical:
-- the apex `/builders/*` tree + the `builders.<apex>` subdomain **rewrite shim** (#726),
-- the **canonical-URL redirects** (#744: `/builders/ranks` → `/ranks` on the subdomain; #739: apex `/builders/*` → `builders.<apex>`),
-- the **citizen/Archon page gates** (#488/#770: primer, diagrams, work, pair, settings, atlas are sign-in-gated; watch, harbor, gate are Archon-only — the real curl-proof access control),
-- per-page **asset-stamping** (#521 content-hash `?v=`),
-- the **module hall-widget injection** (BV1.R75 — `injectModuleHallWidgets`),
-- the diagram PNG + `primer.md` static mounts.
-
-So the manifest `webSurfaces` declaration is the **discovery + scope-map + `window.__MODULES__` record**; the bytes are served by the hall's dedicated block in `serve-internal.js`.
-
-## The serving seam (how the hall keeps its dedicated block + is still a module)
-
-`src/bongos/serve-internal.js` resolves `loader.moduleWebSurfaces({ isEnabled })` — the same seam status-UI uses — but **PARTITIONS the hall out** of the generic static loop on the builders-host predicate (`isBuildersHost`), so:
-- the **generic loop** owns every web surface EXCEPT the hall (status-UI today),
-- the hall's **dedicated block** owns the builders host and reads from `BUILDERS_DIR = modules/hall-ui/public/`.
-
-The filter is on the **host** (`isBuildersHost`), not the `"hall-ui"` key, so the kernel still names no module key ([ADR 0083](../../docs/adr/<redacted>.md) §Decision #4). `isModuleSurfaceHost` (which the dedicated `/builders` guards use to skip the GENERIC status surface) therefore deliberately EXCLUDES the builders host — the dedicated block is what serves it, so it must not self-skip.
-
-## The boundary
-
-This module reaches **nothing** in core (no doorway require — it has no JS the server requires; `builders.js` etc. are browser code). Core, in turn, must never `require()` a file in here — `serve-internal.js` resolves the surface through `loader.moduleWebSurfaces`/`BUILDERS_DIR`, never an import of `modules/hall-ui/*`. Both directions are enforced by the BV1.R44/R45 fitness checks.
-
-## The data it renders STAYS shared core (the judgment call)
-
-The `/api/gds/me`, `/api/gds/public/*`, and `/api/gds/leaderboard` read endpoints the hall polls **did not move** — they live in `src/bongos/routes/{me,public,builders}.js` and are consumed by the status surface and the off-box mirror too, not just this hall. A read shared by multiple surfaces is correctly core/shared, not hall-exclusive (the same call status-UI / economy / ideas made). So the carve moves the *surface*, not the reads it happens to render.
-
-## The hall-widget registry (BV1.R75)
-
-The hall's `<main>` is filled from a **registry** (`public/dom-utils.js` `contributeHallWidget`; the core set in `public/hall-widgets.js`; a module's own client script otherwise). No widget may be hardcoded as a literal `<section class="scroll">` in `index.html` — a fitness check (`scripts/gds/fitness.js`, `HALL_INDEX` now points at `modules/hall-ui/public/index.html`) reds the build if one creeps back. Module-contributed hall widgets are injected via `serve-internal.js`'s `injectModuleHallWidgets` (the `hallWidgetScripts` loader seam), served at `/modules/<key>/public/hall-widget.js`. (Known pre-existing limitation, idea #465: that asset path 404s on the builders *subdomain* because the rewrite shim shadows it — injection works on both hosts; serving works on the apex. No module ships a hall-widget today so it's a live no-op.)
-
-## Files & tooling
-
-| Path | What |
-|---|---|
-| `public/index.html` · `public/builders.js` · `public/style.css` | the hall shell + core script + stylesheet (no build step, no framework) |
-| `public/{work,roadmap,watch,harbor,gate,pair,settings,ranks,sessions,primer,diagrams,atlas,not-ready}.{html,js}` | the per-page surfaces |
-| `public/task.html` + `public/task.js` | the task-detail page (`/task/:id`, task 751) — a real, shareable page that replaced the old `#/task/N` overlay. Irregular routing: `serve-internal.js`'s `TASK_DETAIL_PAGE_RE` resolves the two-segment `/builders/task/:id` path to this one file (every other page is a single-segment slug). (The old read-only Task Board twin `board.html`/`board.js` was removed in task 1965 — `/board` now 301s to `/work`.) |
-| `public/goals.html` + `public/goals-page.js` | the Goals page (irregular basename — `goals.js` is the index's Goals hall-widget) |
-| `public/dom-utils.js` · `public/hall-widgets.js` | the hall-widget + settings-panel registries (browser IIFEs) |
-| `public/instances-panel.js` | the "Instances" hall widget (provisioning module, [ADR 0111](../../docs/adr/<redacted>.md) §1, task 1947) — self-registers **gated on `module:'provisioning'`** (`contributeHallWidget` drops it when the module is off); a self-fetching widget (the `goals.js` pattern) that reads the P1 `/provisioning/*` routes and renders own instances always + the Archon fleet + cost-ledger total when `/me` is `archon`. Read/state only. |
-| `public/new-project-wizard.js` | the "Start a project" hall widget (provisioning module, [ADR 0111](../../docs/adr/<redacted>.md) / goal 35, task 1983) — the **CREATE** flow the instances-panel deferred: the most accessible form of the canonical onboarding runbook (the `/new-project` skill task 1981 + `bongos onboard` CLI task 1982). Same `module:'provisioning'` gating; a form that files a **standalone** provisioning request (`POST /provisioning/instances` — the web tier only ENQUEUES, trust boundary intact) then renders the irreducibly-human steps UI-first (create repo, OAuth app with the pinned apex callback, first sign-in) + points at the Instances panel for status. |
-| `public/cursors/` · `public/chime.wav` | bronze cursors + the volume-slider preview chime |
-| `module.json` | `contributes.webSurfaces: [{ host: "builders.", dir: "public" }]`; no port, no routes |
-
-Generators that WRITE into this surface live under `scripts/` and were re-pointed at `modules/hall-ui/public/`: `scripts/gds/gen-atlas.js` (the `atlas.json` Repo Atlas data, gitignored — regenerated on deploy), `scripts/art/gen-cursors.py` (cursors), `.claude/sounds/generate.js` (the chime mirror).
-
-## Tests
-
-The loader seam is covered in `tests/module_loader.mjs` (`moduleWebSurfaces` + the live hall-ui surface); the manifest `webSurfaces` validation in `tests/module_manifest.mjs`; the carve discovery-key membership in `tests/fitness.mjs` / `tests/module_loader.mjs` / `tests/modules.mjs`; the browser settings-panel seam in `tests/module_contributions.mjs` (reads `public/dom-utils.js`); the Repo Atlas renderer contract in `tests/atlas.mjs`; and the carve proof in `scripts/gds/coreB-carve-proof.sh` (leg 4i).
+_To work ON the platform core itself, use the standalone @bongos/core source repository,
+not this vendored copy._

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,
+  });
+})();