@bongos/core 1.17.0

package/src/bongos/routes/backup.js

@@ -0,0 +1,104 @@
+// Backup status + trigger routes.
+//
+// GET  /backup/status   — latest local dump info + offsite indicator (metic+archon)
+// POST /backup/trigger  — fire a fresh local dump asynchronously       (metic+archon)
+//
+// The server process runs as the `lars` user on the droplet, so it can read
+// /var/backups/gds/ and spawn the existing db-backup-nightly.sh directly —
+// no SSH, no sudo, no extra credentials. A builder with no shell access calls
+// these routes instead.
+//
+// Design notes:
+//   - trigger is fire-and-forget: 202 Accepted immediately; the dump runs
+//     in the background. The builder polls status to see it land.
+//   - concurrent triggers: a simple in-memory flag prevents two dumps from
+//     running simultaneously (one droplet, one disk, no need for DB state).
+//   - the backup dir and script paths default to the on-droplet locations but
+//     can be overridden via env vars for local tests.
+
+const express = require('express');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const auth = require('../auth');
+const { branding } = require('../../branding');
+const { asyncHandler } = require('./_helpers');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const BACKUP_DIR = process.env.GDS_BACKUP_DIR || '/var/backups/gds';
+// The DB name comes from the branding pack (branding.db.database), never a
+// hardcoded host brand (ADR 0062 §3) — a non-OTB instance dumps its own DB.
+const DB_NAME = process.env.GDS_BACKUP_DB
+  || (() => { try { return branding().db && branding().db.database; } catch { return null; } })()
+  || 'gds';
+const BACKUP_SCRIPT = process.env.GDS_BACKUP_SCRIPT
+  || path.join(REPO_ROOT, 'scripts', 'gds', 'db-backup-nightly.sh');
+
+// In-memory guard: true while a trigger-initiated dump is running.
+let triggerRunning = false;
+
+function latestDump() {
+  let files;
+  try {
+    files = fs.readdirSync(BACKUP_DIR);
+  } catch {
+    return null;
+  }
+  const dumps = files
+    .filter(f => f.startsWith(`${DB_NAME}-`) && f.endsWith('.sql.gz'))
+    .sort();
+  if (!dumps.length) return null;
+  const name = dumps[dumps.length - 1];
+  const full = path.join(BACKUP_DIR, name);
+  let size_bytes = null;
+  try { size_bytes = fs.statSync(full).size; } catch { /* ok */ }
+  // Filename: <db>-<YYYY-MM-DDTHHMMSSZ>.sql.gz — extract timestamp from it.
+  const ts = name.replace(`${DB_NAME}-`, '').replace('.sql.gz', '');
+  return { filename: name, timestamp: ts, size_bytes, count: dumps.length };
+}
+
+module.exports = function buildBackupRouter() {
+  const router = express.Router();
+
+  // rank: metic+archon — any working builder may check or trigger a backup.
+  router.get('/backup/status', auth.requireBuilder, auth.requireRank('metic', 'archon'),
+    asyncHandler('GET /backup/status', async (_req, res) => {
+      const dump = latestDump();
+      res.json({
+        backup_dir: BACKUP_DIR,
+        db_name: DB_NAME,
+        latest_dump: dump,
+        trigger_running: triggerRunning,
+      });
+    }));
+
+  // rank: metic+archon
+  router.post('/backup/trigger', auth.requireBuilder, auth.requireRank('metic', 'archon'),
+    asyncHandler('POST /backup/trigger', async (req, res) => {
+      if (triggerRunning) {
+        return res.fail('backup_already_running', { status: 409, message: 'A backup is already in progress — poll /backup/status to see it land.' });
+      }
+      triggerRunning = true;
+      const startedAt = new Date().toISOString();
+      const builderId = req.builder && req.builder.id;
+      console.log(`[gds] backup triggered by builder ${builderId} at ${startedAt}`);
+
+      execFile('bash', [BACKUP_SCRIPT], { cwd: REPO_ROOT, timeout: 120_000 }, (err, stdout, stderr) => {
+        triggerRunning = false;
+        if (err) {
+          console.error(`[gds] backup trigger failed (builder ${builderId}):`, err.message);
+          if (stderr) console.error('[gds] backup stderr:', stderr.toString().trim());
+        } else {
+          console.log(`[gds] backup trigger completed (builder ${builderId})`);
+        }
+      });
+
+      res.status(202).json({
+        ok: true,
+        message: 'Backup started — poll GET /api/gds/backup/status to see the new dump land (usually < 30 s).',
+        started_at: startedAt,
+      });
+    }));
+
+  return router;
+};

package/src/bongos/routes/builders.js

@@ -0,0 +1,526 @@
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+const express = require('express');
+const auth = require('../auth');
+const db = require('../db');
+const { validateOrRespond, LIMITS, parseId } = require('./_helpers');
+// The onboarding state machine carved into modules/onboarding/ (BV1.R81 / ADR
+// 0093 §1): GET /builders/:id/onboarding resolves the `onboarding` kernel port
+// for the roster-visible checklist (read/shape) — never a direct require.
+const { pool } = require('../pool');
+const seams = require('../../module-seams');
+const { branding } = require('../../branding');
+// The lifecycle (tasks · claims · ship) carved to modules/lifecycle/ (BV1.R86 /
+// ADR 0093 §3): the Archon roster, the per-builder stale-claim view, the
+// per-builder grade breakdown, and the shipped-count read resolve the `lifecycle`
+// kernel PORT (lc()). The rank/identity mutations (setBuilderRank/deactivate/
+// reactivate) stay core db (this domain is builder identity, not the lifecycle).
+const lc = () => seams.resolveOptional('lifecycle');
+// Dev-box "has this builder ever connected a box?" read through the kernel seam
+// instead of a direct `require('../boxes')` (a forbidden core→module edge once
+// dev-box moved to modules/dev-box/, ADR 0083 / BV1.R43). The dev-box module
+// provides the `box.hasEverConnected` port when enabled; degrades to false on a
+// box-less instance (the box_connect onboarding step just never auto-clears).
+const boxHasEverConnected = (builderId) =>
+  seams.resolveOptional('box.hasEverConnected', async () => false)(builderId);
+
+// The discord "has this builder linked their Discord account?" signal, read
+// through the kernel seam instead of a direct `db.getDiscordLink` (a forbidden
+// core→module edge once discord moved to modules/discord/, ADR 0083 / BV1.R47).
+// The discord module provides the `discord.isLinked` port when enabled; degrades
+// to false on a discord-less instance (the discord onboarding step never clears).
+const discordIsLinked = (builderId) =>
+  seams.resolveOptional('discord.isLinked', async () => false)(builderId);
+
+// Builder administration routes (V3.R07 #232).
+//
+// PATCH /builders/:id/rank — the SINGLE chokepoint for rank changes. Archon-
+// only (enforced server-side via requireRank — ADR 0016). Promotion AND
+// demotion go through here so there's exactly one audited path that can alter
+// authority. The promotion/demotion ceremony (V3.R28 #249) bolts on three
+// signals after a successful rank change: the credit_log row (handled by
+// db.setBuilderRank — +5 on promotion, 0 on demotion), a Mediterranean-tone
+// Discord broadcast (fired here, best-effort, non-blocking), and a Claude
+// SessionStart greeting (the `.claude/hooks/rank-change-greeting.js` hook
+// picks up the latest credit_log row via GET /me/pending-rank-change). Audit
+// log proper lands later (R36).
+
+// Resolve the repo root from this file. Used to invoke scripts/discord/post.js
+// regardless of where the node process was started from.
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// Map a rank id (db enum string) to its display form used in the Discord
+// broadcast — capitalized, no surprises. Centralized here so the wording is
+// consistent everywhere ceremony surfaces the rank.
+function displayRank(rank) {
+  if (!rank || typeof rank !== 'string') return rank;
+  return rank.charAt(0).toUpperCase() + rank.slice(1);
+}
+
+// Build the Mediterranean-tone Discord message. Promotion is celebratory
+// ("raised to the rank of"); demotion is dignified ("stepped down to the rank
+// of" — no "demoted", no shaming). Lateral (impossible at the call site since
+// RANK_UNCHANGED short-circuits earlier, but defensive) reads as a neutral
+// "moves to". The display_name is what the team sees in Discord.
+function buildRankChangeBroadcast({ displayName, direction, newRank }) {
+  const who = displayName || 'a builder';
+  const rank = displayRank(newRank);
+  // "Citizens of <worldName>" — the salutation reads the instance world name
+  // from the branding pack, never a hardcoded host brand (ADR 0062 §3), so a
+  // non-OTB instance addresses its own citizens.
+  const worldName = (() => { try { return branding().identity?.worldName || 'the city'; } catch { return 'the city'; } })();
+  if (direction === 'promotion') {
+    return `Citizens of ${worldName} — ${who} has been raised to the rank of ${rank}.`;
+  }
+  if (direction === 'demotion') {
+    return `Citizens of ${worldName} — ${who} has stepped down to the rank of ${rank}.`;
+  }
+  return `Citizens of ${worldName} — ${who} now holds the rank of ${rank}.`;
+}
+
+// Fire the rank-change broadcast in the background. Best-effort: a post
+// failure must never undo a successful rank change. We detach (no callback
+// wait) and let stderr surface in server logs if the post script errors.
+// Outbound moved from Google Chat to Discord #ship-news per ADR 0032 / #607
+// (scripts/chat/ is inbound-only now). The CHAT_DRY_RUN env var short-circuits
+// to a "[broadcast dry-run]" log line — used by the smoke path so a test rank
+// flip doesn't actually hit Discord. The name is a legacy artifact; it gates
+// all broadcast transports, not just Chat.
+function fireDiscordBroadcast(text) {
+  if (!text) return;
+  if (process.env.CHAT_DRY_RUN === '1') {
+    console.log(`[gds] [broadcast dry-run] would post: ${text}`);
+    return;
+  }
+  try {
+    execFile(
+      'node',
+      ['scripts/discord/post.js', text],
+      { cwd: REPO_ROOT, timeout: 10_000 },
+      (err, _stdout, stderr) => {
+        if (err) {
+          console.log('[gds] rank-change broadcast failed (non-blocking):', err.message);
+          if (stderr) console.log('[gds] discord stderr:', stderr.toString().trim());
+        }
+      }
+    );
+  } catch (e) {
+    console.log('[gds] rank-change broadcast spawn failed (non-blocking):', e && e.message);
+  }
+}
+
+module.exports = function buildBuildersRouter() {
+  const router = express.Router();
+
+  // rank: archon — sole chokepoint that mutates builders.rank; ADR 0016 §enforcement.
+  router.patch('/builders/:id/rank', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      rank: { required: true, type: 'string', maxLength: 32 },
+    })) return;
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    const newRank = req.body && req.body.rank;
+    if (!newRank || !db.RANKS.includes(newRank)) {
+      return res.fail('bad_rank', 400, { valid: db.RANKS });
+    }
+    // #706: `thetes` IS manually grantable by an Archon. It is reachable two
+    // ways — the automatic 3-shipped-tasks graduation (db.maybeAutoGraduateToThetes)
+    // AND a deliberate Archon promotion through this route. (An earlier #704 cut
+    // wrongly refused manual set-to-thetes; that block is removed.)
+    // No last-Archon footgun: an Archon cannot change their own rank (this
+    // covers self-demotion, which could otherwise strand the system with no
+    // Archon). Another Archon must do it.
+    //
+    // Compare as strings: req.builder.id is a string (node-postgres returns
+    // bigint as text) while targetId is a Number, so `===` would never match
+    // and the guard would silently fail. (Fixed in #348 after a live self-
+    // demotion lockout.)
+    if (String(targetId) === String(req.builder.id)) {
+      return res.fail('cannot_change_own_rank', 403);
+    }
+    try {
+      const result = await db.setBuilderRank({
+        builderId: targetId,
+        newRank,
+        actorBuilderId: req.builder.id,
+      });
+      // V3.R28 / #249 — ceremony signal #2: Discord broadcast.
+      // Fire-and-forget; failure does NOT roll back the rank change. The
+      // credit_log ceremony row was already written inside setBuilderRank
+      // (signal #1), and the SessionStart hook (signal #3) reads from there.
+      const broadcastText = buildRankChangeBroadcast({
+        displayName: result.builder.display_name || result.builder.github_login,
+        direction: result.direction,
+        newRank: result.builder.rank,
+      });
+      fireDiscordBroadcast(broadcastText);
+      // F5 role-sync (ADR 0033 §4): push the new rank to the builder's Discord
+      // role badge. Fire-and-forget — a Discord failure must not roll back the
+      // rank change. No-op if the builder hasn't linked Discord / the bot is off.
+      // Emit to the discord module's listener (ADR 0083 / BV1.R47 — no core→module
+      // import). Fire-and-forget; the listener repairs the Discord rank-role badge.
+      seams.emit('builder.role-sync-needed', { builderId: targetId });
+      res.json({
+        builder: result.builder,
+        previous_rank: result.previous_rank,
+        direction: result.direction,
+        credit_delta: result.credit_delta,
+        broadcast: broadcastText,
+      });
+    } catch (err) {
+      if (err && err.code === 'BUILDER_NOT_FOUND') {
+        return res.fail('builder_not_found', 404);
+      }
+      if (err && err.code === 'RANK_UNCHANGED') {
+        return res.fail('rank_unchanged', 409, { rank: err.rank });
+      }
+      // #707: a manual promotion may only advance one live rung at a time.
+      if (err && err.code === 'MULTI_RUNG_PROMOTION') {
+        return res.fail('multi_rung_promotion', { status: 400, message: `Promotions advance one rung at a time. From ${err.from}, the next rung is ${err.next_rung} — promote there first.`, details: { from: err.from, to: err.to, next_rung: err.next_rung } });
+      }
+      console.error('[gds] PATCH /builders/:id/rank', err);
+      res.fail('rank_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /builders/:id/status — graceful exit + reactivation (V3.R88 #307).
+  // Archon-only. { status: 'inactive', reason? } deactivates (releases active
+  // claims, seals their session_logs, rank → xenos, blocks new claims while
+  // preserving all credit/history); { status: 'active' } reactivates. Cannot
+  // change your own status (no last-Archon footgun — same guard as /rank).
+  // rank: archon — deactivation/reactivation; preserves credit history but blocks claims.
+  router.patch('/builders/:id/status', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      status: { required: true, type: 'string', enum: ['active', 'inactive'] },
+      reason: { type: 'string', maxLength: LIMITS.NOTES },
+    })) return;
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    const status = req.body && req.body.status;
+    if (status !== 'inactive' && status !== 'active') {
+      return res.fail('bad_status', 400, { valid: ['active', 'inactive'] });
+    }
+    if (String(targetId) === String(req.builder.id)) {
+      return res.fail('cannot_change_own_status', 403);
+    }
+    try {
+      if (status === 'inactive') {
+        const result = await db.deactivateBuilder({
+          builderId: targetId,
+          reason: req.body.reason ?? null,
+          actorBuilderId: req.builder.id,
+        });
+        return res.json(result);
+      }
+      const result = await db.reactivateBuilder({
+        builderId: targetId,
+        actorBuilderId: req.builder.id,
+      });
+      return res.json(result);
+    } catch (err) {
+      if (err && err.code === 'BUILDER_NOT_FOUND') {
+        return res.fail('builder_not_found', 404);
+      }
+      if (err && err.code === 'ALREADY_INACTIVE') {
+        return res.fail('already_inactive', 409);
+      }
+      if (err && err.code === 'NOT_INACTIVE') {
+        return res.fail('not_inactive', 409, { status: err.status });
+      }
+      console.error('[gds] PATCH /builders/:id/status', err);
+      res.fail('status_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /builders/:id/budget — set or clear a builder's monthly spend ceiling
+  // (V3.R84 #302, criterion C3). Archon-only. Body: { monthly_budget_usd: <num> }
+  // sets the per-builder override — the manual emergency brake; a positive value
+  // engages the warn/over thresholds. { monthly_budget_usd: null } clears it: the
+  // builder becomes UNCAPPED (there is no default cap — ADR 0085). This is the
+  // "budget per-builder configurable by Archon" done-when. 404 if no such builder.
+  // rank: archon — changes another builder's cost ceiling.
+  router.patch('/builders/:id/budget', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    if (validateOrRespond(req, res, { monthly_budget_usd: {} })) return;  // number ≥0, or null to clear; validated below
+    const raw = req.body ? req.body.monthly_budget_usd : undefined;
+    let budget;
+    if (raw === null) {
+      budget = null; // clear → uncapped (no default cap; ADR 0085)
+    } else if (typeof raw === 'number' && Number.isFinite(raw) && raw >= 0) {
+      budget = raw;
+    } else {
+      return res.fail('bad_budget', { status: 400, message: 'monthly_budget_usd must be a non-negative number, or null to clear' });
+    }
+    try {
+      // setBuilderMonthlyBudget carved to modules/economy/ (BV1.R77 / ADR 0093
+      // §1-2): resolve the `reward` kernel port (economy is default-on). The
+      // archon rank gate on this route is unchanged.
+      const updated = await seams.resolveOptional('reward').setBuilderMonthlyBudget(targetId, budget);
+      if (!updated) return res.fail('builder_not_found', 404);
+      res.json({ builder: updated });
+    } catch (err) {
+      console.error('[gds] PATCH /builders/:id/budget', err);
+      res.fail('budget_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/roster — V3.R14 (#238) onboarding observability.
+  //
+  // Archon-only roster of every builder with their identity + onboarding
+  // signals + active-claim posture. Powers the management panel in the
+  // /builders hall so the Archon can promote / demote / release-stale-claim
+  // without dropping into psql.
+  //
+  // Optional query param: ?stale_hours=N (default 24). Defines what counts
+  // as "stale" for the per-row stale_claim flag — mirrors the threshold the
+  // stale-claim-release sweeper uses but exposed as a roster knob so the
+  // Archon can dial it in if needed.
+  //
+  // rank: archon — surfaces every builder's onboarding state.
+  router.get('/builders/roster', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    let staleHours = 24;
+    if (req.query && req.query.stale_hours != null) {
+      const n = Number(req.query.stale_hours);
+      if (!Number.isFinite(n) || n <= 0 || n > 720) {
+        return res.fail('bad_stale_hours', 400, { expected: '1..720' });
+      }
+      staleHours = n;
+    }
+    try {
+      const builders = await lc().getBuildersRoster({ staleHours });
+      res.json({ builders, stale_hours: staleHours });
+    } catch (err) {
+      console.error('[gds] GET /builders/roster', err);
+      res.fail('roster_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/directory — the any-builder-readable picker roster (task 1877):
+  // every ACTIVE builder's identity, for a client-side invite dropdown (the Goals
+  // invite control, task 1762) that shouldn't be limited to GET /leaderboard's
+  // top-100-by-credits window. Deliberately narrower than /builders/roster — no
+  // onboarding/stale-claim/box data, which stays Archon-only; id/login/name/
+  // avatar/rank is no more sensitive than what /leaderboard already exposes
+  // publicly, just without the credits cutoff.
+  // rank: any-builder.
+  router.get('/builders/directory', auth.requireBuilder, async (req, res) => {
+    try {
+      const builders = await db.listActiveBuilders();
+      res.json({ builders });
+    } catch (err) {
+      console.error('[gds] GET /builders/directory', err);
+      res.fail('directory_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /grades/by-builder?days=30 — per-builder grade breakdown (#726).
+  //
+  // Archon-only monitoring read backing the MARKS section of the /watch page:
+  // who is passing/failing the grader, over a window. Aggregated from
+  // task_grades joined through tasks.shipped_by. Mirrors the rank gate on the
+  // roster + audit-log reads — it exposes cross-builder quality data, so it is
+  // the Ruling Hand's alone (the project-wide aggregate stays public via
+  // /public/grades; this per-builder split does not).
+  //
+  // rank: archon.
+  router.get('/grades/by-builder', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    let days = 30;
+    if (req.query && req.query.days != null) {
+      const n = Number(req.query.days);
+      if (!Number.isFinite(n) || n <= 0 || n > 365) {
+        return res.fail('bad_days', 400, { expected: '1..365' });
+      }
+      days = Math.floor(n);
+    }
+    try {
+      const builders = await lc().gradeByBuilder(days);
+      res.json({ window_days: days, builders });
+    } catch (err) {
+      console.error('[gds] GET /grades/by-builder', err);
+      res.fail('grades_by_builder_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/:id/active-claims — V3.R14 (#238).
+  //
+  // Archon-only detail view of a single builder's active claims, with the
+  // same stale_claim flag the roster computes. The roster only carries
+  // boolean "has any stale claim?"; this endpoint surfaces *which* claim
+  // is stale so the Archon can target the release.
+  //
+  // rank: archon — privileged read of another builder's work surface.
+  router.get('/builders/:id/active-claims', auth.requireBuilder, auth.requireRank('archon'), async (req, res) => {
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    let staleHours = 24;
+    if (req.query && req.query.stale_hours != null) {
+      const n = Number(req.query.stale_hours);
+      if (!Number.isFinite(n) || n <= 0 || n > 720) {
+        return res.fail('bad_stale_hours', 400, { expected: '1..720' });
+      }
+      staleHours = n;
+    }
+    try {
+      const claims = await lc().getActiveClaimsForBuilderWithStale(targetId, { staleHours });
+      res.json({ builder_id: targetId, claims, stale_hours: staleHours });
+    } catch (err) {
+      console.error('[gds] GET /builders/:id/active-claims', err);
+      res.fail('active_claims_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/:id/onboarding — V3.R75 (#294) onboarding checklist read.
+  //
+  // Returns the builder's onboarding state machine row, shaped for the
+  // /builders hall checklist UI:
+  //   {
+  //     builder_id, current_stage, completed_stages, started_at, completed_at,
+  //     progress: { cleared, total },
+  //     stages: [{ id, label, hint, cleared, is_current }, ...],
+  //     graduated: boolean
+  //   }
+  //
+  // Public read (no auth). Spec says the hall renders other builders'
+  // checklists read-only — a builder's onboarding progress is roster-visible
+  // signal, same posture as rank or drachmae shown on the leaderboard. The
+  // builder's own row is also surfaced inside /api/gds/me; this endpoint is
+  // what the hall hits for the CURRENT viewer AND for any other builder
+  // whose card is rendered.
+  //
+  // rank: public — onboarding progress is a roster-visible signal.
+  router.get('/builders/:id/onboarding', async (req, res) => {
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    try {
+      // The onboarding state machine carved into modules/onboarding/ (BV1.R81 /
+      // ADR 0093 §1): resolve the `onboarding` kernel port for the read + shape —
+      // never a direct require of a module. Default-on (present in prod); degrades
+      // to a null state row (shapeForApi synthesizes the "nothing cleared" view).
+      const onboarding = seams.resolveOptional('onboarding');
+      const [state, shipCount, discordLink, boxConnected, cliAuthed] = await Promise.all([
+        onboarding ? onboarding.getState(pool, targetId) : null,
+        lc().countShippedTasksForBuilder(targetId),
+        discordIsLinked(targetId),
+        boxHasEverConnected(targetId),
+        db.hasCliSession(targetId),
+      ]);
+      // shipCount drives the terminal 'ship_three' stage's "N of 3" counter.
+      // The box/discord/cli steps clear from LIVE signals (not the onboarding_state
+      // row), so they must be passed in exactly as GET /me does — otherwise they
+      // default to false and this route renders box_connect/join_discord/cli_setup
+      // perpetually unchecked even after the builder cleared them (task 1444).
+      const shaped = onboarding ? onboarding.shapeForApi(state, {
+        shipCount,
+        discordLinked: !!discordLink,
+        boxConnected: !!boxConnected,
+        cliAuthed: !!cliAuthed,
+      }) : null;
+      // Light cache — onboarding state changes a few times per builder, ever.
+      res.set('Cache-Control', 'private, max-age=10');
+      res.json({ builder_id: targetId, onboarding: shaped });
+    } catch (err) {
+      console.error('[gds] GET /builders/:id/onboarding', err);
+      res.fail('onboarding_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/:id/profile — the viewable builder profile page's read
+  // (task 1467, goal 25 "bx-identity"). Returns ONE builder's public portfolio:
+  // identity + rank + economy counters + shipped-work count + recent ships +
+  // unlocked achievements. Backs the shareable /builders/profile page.
+  //
+  // rank: public — every field returned here is ALREADY world-readable: the
+  // leaderboard (GET /public/leaderboard, no auth) exposes rank, total_credits,
+  // karma, and the top achievement ids; GET /builders/:id/onboarding is likewise
+  // an unauthenticated roster-visible read. This route is a per-builder re-
+  // presentation of the SAME already-public data, so a portfolio link is
+  // shareable without a sign-in wall (that IS the feature). It deliberately
+  // WHITELISTS the public column subset off the full builder row — the private
+  // columns getBuilderById also returns (anthropic_email / anthropic_user_id /
+  // monthly_budget_usd / system_role / box_blocked*) are NEVER spread into the
+  // JSON. A leak-prevention unit test (tests/profile_route.mjs) asserts their
+  // absence + the 404-on-unknown-id behaviour.
+  router.get('/builders/:id/profile', async (req, res) => {
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    try {
+      const b = await db.getBuilderById(targetId);
+      if (!b) return res.fail('builder_not_found', 404);
+      // Recent ships + shipped-count read the lifecycle port; the achievement
+      // shelf reads the reward port. Both resolveOptional — on a vanilla instance
+      // without economy the achievement shelf degrades to empty, not a 500.
+      const reward = seams.resolveOptional('reward');
+      const [shippedCount, recentShips, achievements] = await Promise.all([
+        lc().countShippedTasksForBuilder(targetId),
+        lc().recentShippedTasksByBuilder(targetId, 5),
+        reward ? reward.getBuilderAchievements(targetId) : [],
+      ]);
+      // WHITELIST — only the leaderboard-equivalent public field set. Never spread
+      // the raw row: it carries anthropic_email / anthropic_user_id /
+      // monthly_budget_usd / system_role / box_blocked* / deactivated_reason,
+      // none of which are public.
+      const builder = {
+        id: b.id,
+        github_login: b.github_login,
+        display_name: b.display_name,
+        avatar_url: b.avatar_url,
+        rank: b.rank,
+        total_credits: b.total_credits,
+        karma: b.karma,
+        created_at: b.created_at,
+        preferred_disciplines: b.preferred_disciplines,
+      };
+      // Identity + counters change rarely; a short public cache matches
+      // /public/leaderboard's posture.
+      res.set('Cache-Control', 'public, max-age=60');
+      res.json({
+        builder,
+        shipped_count: shippedCount,
+        recent_ships: recentShips,
+        achievements,
+      });
+    } catch (err) {
+      console.error('[gds] GET /builders/:id/profile', err);
+      res.fail('profile_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // GET /builders/me/pending-rank-change — V3.R28 / #249 ceremony signal #3.
+  //
+  // Returns the calling builder's most recent rank-change credit_log row, or
+  // { change: null } when they've never had a rank change. The local
+  // SessionStart hook (`.claude/hooks/rank-change-greeting.js`) calls this on
+  // every session start and dedupes via a local "seen" marker — so the
+  // server doesn't need to track acknowledgment. That means this endpoint is
+  // a pure read; it never mutates anything.
+  //
+  // Why this lives on /builders/me/* (not /me/*): the route is part of the
+  // ceremony surface that V3.R28's touches[] explicitly covers
+  // (src/bongos/routes/builders.js). Routing it under /builders avoids editing
+  // /me.js (outside touches[]) while keeping the URL semantically clean.
+  //
+  // rank: any-builder — own rank-change history; mirrors /me/* posture.
+  router.get('/builders/me/pending-rank-change', auth.requireBuilder, async (req, res) => {
+    try {
+      const change = await db.getLatestRankChangeForBuilder(req.builder.id);
+      if (!change) {
+        return res.json({ change: null });
+      }
+      // Echo the broadcast text the hook will print. Built the same way the
+      // PATCH route built it, so the wording is identical to what went to
+      // Discord — that consistency is the ceremony.
+      const greeting = buildRankChangeBroadcast({
+        displayName: req.builder.display_name || req.builder.github_login,
+        direction: change.direction,
+        newRank: change.new_rank || req.builder.rank,
+      });
+      res.json({ change, greeting });
+    } catch (err) {
+      console.error('[gds] GET /builders/me/pending-rank-change', err);
+      res.fail('pending_rank_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/src/bongos/routes/healthz.js

@@ -0,0 +1,16 @@
+const express = require('express');
+const auth = require('../auth');
+
+module.exports = function buildHealthzRouter() {
+  const router = express.Router();
+
+  // rank: public — liveness probe; status.amazonprimea.com hits this anonymously.
+  router.get('/healthz', async (_req, res) => {
+    res.json({
+      ok: true,
+      auth_configured: auth.authConfigured(),
+    });
+  });
+
+  return router;
+};