@bongos/core 1.17.0

package/modules/sessions/routes/sessions.js

@@ -0,0 +1,331 @@
+// Session records router — the BFG session-inefficiency evaluator's data plane
+// (ADR 0027). 6D.1 shipped the WRITE path (POST /sessions); 6D.2 adds the READ
+// paths the BFG (a local Claude Code routine, 6D.3) calls to search the corpus
+// and deep-dive interesting sessions:
+//
+//   POST /sessions          — upload your OWN session digest (6D.1). Owner is
+//                             forced to the caller; body builder_id is ignored.
+//   GET  /sessions/mine     — your own sessions (self-serve summary list).
+//   GET  /sessions/search   — cross-builder search over session + builder facets
+//                             (rank/karma/drachmae/tenure). Archon-gated +
+//                             audited (the BFG principal posture until 6C.1).
+//   GET  /sessions/:id       — one session's full detail for deep-dive. Owner
+//                             self-serve; cross-builder requires Archon + audit.
+//
+// Cross-builder reads are GETs, which the global audit middleware does NOT
+// instrument — so each writes its own audit_log row (fail-closed: logged BEFORE
+// the data is served). This mirrors the memory router's Archon forensic read.
+// "Archon" stands in for the dedicated BFG service principal until 6C.1 lands
+// (ADR 0026 §6C / ADR 0027) — the gate tightens to the exact principal then.
+//
+// Body size: the global GDS json parser is capped at 64 KB (routes.js); a
+// session digest runs larger, so routes.js skips the global parser for
+// POST /sessions and this router mounts its own (mirroring the memory router).
+
+const express = require('express');
+// CARVED into modules/sessions/ (BV1.R82 / ADR 0093 §1): the session-records
+// data plane reaches the kernel ONLY through the published doorway. auth gates +
+// the audit-log writer + the request validators come off `api`; the session
+// records db slice is the module's own `../db`; sumCreditsForTasks (economy) is
+// resolved through the `reward` kernel port, never a direct sibling-module require.
+const api = require('../../../src/module-api');
+const auth = api; // requireBuilder / requireRank live on the doorway surface
+const db = require('../db');
+const seams = api; // resolveOptional('reward') — the economy port, kernel-mediated
+const { validateOrRespond, parseId } = api;
+
+const UPLOAD_BODY_LIMIT = '4mb';
+const MAX_DETAIL_TURNS = 5000; // a hard ceiling; ship.js bounds well under this
+
+// Disk-fill defense (SR-17 / task 997). The 4 MB body limit + maxItems=5000 cap
+// the SHAPE of the payload, but neither bounds the BYTES a single low-rank
+// builder can persist: an element can be arbitrarily large (only the count was
+// capped), and a digest row lands in jsonb on the single droplet that also hosts
+// the game's Postgres. Sustained POSTs of fat rows fill the disk → outage. The
+// two caps below bound the stored bytes per request; they're sized far above a
+// legitimate digest (each real detail element is a short tool/step record — role,
+// timestamps, token counts, and a snippet hard-capped at 160 chars in ship.js's
+// snippetOf, so ~200-300 B/element; a full 4000-turn digest is ~1.2 MB).
+//
+//   - MAX_DETAIL_ELEMENT_BYTES — reject any single detail[] element whose
+//     serialized size exceeds this. 4 KB is >10x a real element, so it can't
+//     reject a legitimate snippet-bearing turn, but blocks stuffing MBs into one
+//     element to dodge the maxItems count cap.
+//   - MAX_DETAIL_TOTAL_BYTES — reject the request if the whole detail[] payload
+//     serializes larger than this. 2 MB sits under the 4 MB body limit and well
+//     above the ~1.2 MB legit ceiling, so it bounds one row's footprint.
+//
+// Residual (NOT closed here): a builder can still spread bytes across many
+// distinct session_id values (one row each). That vector is bounded by the
+// existing per-IP (30/min) and per-session (60/min) write limiters in
+// middleware/rate-limit.js, which already cover POST /sessions — so the sustained
+// write RATE is capped even though the distinct-row COUNT isn't. A per-builder
+// aggregate-bytes guard would need a SUM over session_records on every upload
+// (a heavy query on the hot path); deferred. Retention/rotation of the corpus is
+// also a follow-up — see SR-17 notes.
+const MAX_DETAIL_ELEMENT_BYTES = 4 * 1024;        // 4 KB per detail[] element
+const MAX_DETAIL_TOTAL_BYTES = 2 * 1024 * 1024;   // 2 MB total detail[] payload
+// The three LIVE ranks (ADR 0018) — deliberately NOT db.RANKS, which is the full
+// 16-entry historical enum. Only these three are ever assigned to a builder, so
+// the search filter validates against them (a query for any other rank is a 400).
+const VALID_RANKS = new Set(['xenos', 'thetes', 'metic', 'archon']);
+
+// Per-builder read limiter for the session corpus (mirrors the memory router's
+// forensic-read limiter). Reads aren't covered by the global write limiter.
+const READ_RATE_WINDOW_MS = 60_000;
+const READ_RATE_LIMIT = 60;
+const readBuckets = new Map();
+function readRateLimit(req, res, next) {
+  const now = Date.now();
+  // Opportunistic prune (only when the map has grown) so idle builders' buckets
+  // don't accumulate indefinitely in a long-running process (#541 grade).
+  if (readBuckets.size > 256) {
+    const cutoffAll = now - READ_RATE_WINDOW_MS;
+    for (const [k, b] of readBuckets) {
+      if (!b.length || b[b.length - 1] < cutoffAll) readBuckets.delete(k);
+    }
+  }
+  const key = String(req.builder.id);
+  let bucket = readBuckets.get(key);
+  if (!bucket) {
+    bucket = [];
+    readBuckets.set(key, bucket);
+  }
+  const cutoff = now - READ_RATE_WINDOW_MS;
+  while (bucket.length && bucket[0] < cutoff) bucket.shift();
+  if (bucket.length >= READ_RATE_LIMIT) {
+    const retryAfter = Math.max(1, Math.ceil((bucket[0] + READ_RATE_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    return res.fail('rate_limited', 429, { scope: 'per-builder-session-read', retry_after_seconds: retryAfter });
+  }
+  bucket.push(now);
+  return next();
+}
+
+// recordSessionRead — audit a cross-builder read. GETs bypass the global audit
+// middleware, so we log explicitly. The caller AWAITS this and, on rejection,
+// returns 500 + withholds the response — so no cross-builder data is ever
+// SERVED without a durable audit row. For /search the audit is written BEFORE
+// the query runs (a failed audit means no query); for /:id the row must be
+// fetched first to know the owner, so the audit precedes only the response, not
+// the DB read (same idiom as the memory router). The true HTTP verb is carried
+// in the body (action + http_method) because audit_log.method is CHECK-
+// constrained to a write verb; auditors query by `action`, not `method`.
+// insertAuditLog already returns a Promise, so we return it directly. It's a
+// KERNEL write, reached through the doorway (api.insertAuditLog), not the
+// module's session-records db slice.
+function recordSessionRead(req, { route, targetBuilderId, target }) {
+  return api.insertAuditLog({
+    builderId: req.builder.id,
+    route,
+    method: 'POST',
+    requestBodyRedacted: {
+      action: 'bfg_session_read',
+      http_method: 'GET',
+      target_builder_id: targetBuilderId,
+      target,
+    },
+    // Always 200: the row records the INTENT, written before (search) or just
+    // before serving (:id) — there is no non-200 path that reaches this call.
+    responseStatus: 200,
+    ip: req.ip || (req.socket && req.socket.remoteAddress) || null,
+    userAgent: (req.headers && req.headers['user-agent']) || null,
+  });
+}
+
+module.exports = function buildSessionsRouter() {
+  const router = express.Router();
+  const uploadJson = express.json({ limit: UPLOAD_BODY_LIMIT });
+
+  // rank: any-builder — upload your OWN session digest. Owner is forced to the
+  // authenticated caller; the body cannot attribute a record to another builder.
+  router.post('/sessions', auth.requireBuilder, uploadJson, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      session_id: { required: true, type: 'string', maxLength: 256, minLength: 1 },
+      task_ids: { type: 'array', maxItems: 500, itemsType: 'integer' },
+      total_tokens: { type: 'integer', min: 0 },
+      duration_seconds: { type: 'integer', min: 0 },
+      started_at: { type: 'string', maxLength: 64 },
+      ended_at: { type: 'string', maxLength: 64 },
+      detail: { type: 'array', maxItems: MAX_DETAIL_TURNS },
+      metrics: { type: 'object' },
+      model_usage: { type: 'object' }, // per-model token map for the cost-plus reward (task 1005)
+      // drachmae_earned is NOT accepted from the client — computed server-side.
+      // model_usage carries TOKEN COUNTS only; the reward USD is priced server-side.
+    })) return;
+
+    const body = req.body || {};
+    // Format guard: session_id lands in an indexed column the BFG searches, and
+    // the canonical value is a UUID-shaped token. Reject anything else so a
+    // direct API caller can't pollute the corpus with newlines / path-like junk.
+    if (!/^[A-Za-z0-9_-]{1,256}$/.test(body.session_id)) {
+      return res.fail('bad_session_id', 400);
+    }
+    // Empty-session guard: a digest with 0 total tokens carries no real LLM work
+    // — it's an aborted start or a failed/empty subagent spawn (e.g. a grader
+    // worker that 429'd: one synthetic turn, no usage). These have nothing for
+    // the BFG to analyze and only skew the corpus aggregates, so we never log
+    // them. Benign 200 skip (not an error) so the best-effort upload-on-ship
+    // path treats it as a clean no-op.
+    if (!(Number(body.total_tokens) > 0)) {
+      return res.status(200).json({ skipped: true, reason: 'empty' });
+    }
+    // Byte-bound the detail[] payload (SR-17). maxItems already capped the
+    // element COUNT; these cap the element + total BYTES so one upload can't
+    // write a fat jsonb row that fills the droplet's disk. We measure the
+    // serialized size element-by-element (so we can name the offending index)
+    // and accumulate the total. Returns 413 (payload too large) with the
+    // existing { error, message } envelope.
+    const detailArr = Array.isArray(body.detail) ? body.detail : [];
+    let detailTotalBytes = 0;
+    for (let idx = 0; idx < detailArr.length; idx++) {
+      const elemBytes = Buffer.byteLength(JSON.stringify(detailArr[idx]) || 'null', 'utf8');
+      if (elemBytes > MAX_DETAIL_ELEMENT_BYTES) {
+        return res.fail('detail_element_too_large', { status: 413, message: `detail[${idx}] is ${elemBytes} bytes; the per-element cap is ${MAX_DETAIL_ELEMENT_BYTES} bytes` });
+      }
+      detailTotalBytes += elemBytes;
+      if (detailTotalBytes > MAX_DETAIL_TOTAL_BYTES) {
+        return res.fail('detail_payload_too_large', { status: 413, message: `detail[] exceeds the ${MAX_DETAIL_TOTAL_BYTES}-byte total cap` });
+      }
+    }
+    const requestedTaskIds = Array.isArray(body.task_ids)
+      ? body.task_ids.map(Number).filter(Number.isFinite)
+      : [];
+    try {
+      // Keep only task IDs the builder actually claimed — a direct API caller
+      // can't associate (and thus pollute the corpus with) others' work.
+      const taskIds = await db.filterTaskIdsClaimedBy(req.builder.id, requestedTaskIds);
+      // Drachmae is the AUTHORITATIVE credit_log delta for this upload's owned
+      // task(s), computed server-side — never trusted from the client.
+      const drachmaeEarned = await seams.resolveOptional('reward').sumCreditsForTasks(req.builder.id, taskIds);
+      // Dedup: total_tokens has its own column, so strip it from the metrics
+      // jsonb to avoid two sources of truth in the same row.
+      const metrics = body.metrics && typeof body.metrics === 'object' ? { ...body.metrics } : {};
+      delete metrics.total_tokens;
+      delete metrics.model_usage; // promoted to its own column; avoid two copies
+      const modelUsage = body.model_usage && typeof body.model_usage === 'object'
+        ? body.model_usage : {};
+      // upsert + cost-plus token reward in ONE transaction (task 1005). The
+      // reward USD is priced server-side from modelUsage's TOKEN COUNTS via
+      // llm-pricing.js — the client never sends a dollar figure.
+      const record = await db.upsertSessionRecordWithReward({
+        sessionId: body.session_id,
+        builderId: req.builder.id, // owner = caller, never the body
+        taskIds,
+        drachmaeEarned,
+        totalTokens: body.total_tokens ?? 0,
+        durationSeconds: body.duration_seconds ?? null,
+        startedAt: body.started_at ?? null,
+        endedAt: body.ended_at ?? null,
+        detail: detailArr,
+        metrics,
+        modelUsage,
+      });
+      if (!record) {
+        // Ownership-guard no-op: the session_id exists but belongs to another
+        // builder. Report a benign skip (don't confirm the foreign ownership).
+        return res.status(200).json({ skipped: true });
+      }
+      res.status(201).json({ session: record, token_reward: record.tokenReward });
+    } catch (err) {
+      console.error('[gds] POST /sessions', err);
+      res.fail('upload_failed', 500);
+    }
+  });
+
+  // GET /sessions/search + /sessions/mine are declared BEFORE /sessions/:id so
+  // Express matches the literal paths first (the numeric :id never swallows them).
+
+  // rank: archon — cross-builder corpus search (BFG-principal posture until 6C.1).
+  router.get('/sessions/search', auth.requireBuilder, auth.requireRank('archon'), readRateLimit, async (req, res) => {
+    const q = req.query || {};
+    const rank = q.rank ? String(q.rank) : null;
+    if (rank && !VALID_RANKS.has(rank)) {
+      return res.fail('bad_rank', 400, { valid: Array.from(VALID_RANKS) });
+    }
+    const numOrNull = (v) => {
+      if (v == null) return null;
+      const n = Number(v);
+      return Number.isFinite(n) ? n : null;
+    };
+    const filters = {
+      rank,
+      minKarma: numOrNull(q.min_karma),
+      minDrachmae: numOrNull(q.min_drachmae),
+      minTokens: numOrNull(q.min_tokens),
+      minToolErrors: numOrNull(q.min_tool_errors),
+      minDurationSec: numOrNull(q.min_duration_seconds),
+      maxTenureDays: numOrNull(q.max_tenure_days),
+      order: q.order ? String(q.order) : 'recent',
+      limit: q.limit,
+      offset: q.offset,
+    };
+    try {
+      // Audit the cross-builder search BEFORE the query runs: a failed audit
+      // write means the corpus is never queried (true fail-closed — no read
+      // without a durable record).
+      await recordSessionRead(req, {
+        route: '/api/bongos/sessions/search',
+        targetBuilderId: null,
+        target: `search rank=${rank || '*'} order=${filters.order} offset=${db.clampSessionOffset(filters.offset)}`,
+      });
+      // Page + corpus-wide tally in parallel. `totals` reflects EVERY session
+      // matching the filter (not just this page), so the Ledger's stats stay
+      // stable as the viewer pages; `total` drives the pager's "page X of Y".
+      const [sessions, totals] = await Promise.all([
+        db.searchSessions(filters),
+        db.summarizeSessions(filters),
+      ]);
+      res.json({
+        sessions,
+        count: sessions.length,
+        total: totals.total,
+        totals,
+        limit: db.clampSessionLimit(filters.limit),
+        offset: db.clampSessionOffset(filters.offset),
+      });
+    } catch (err) {
+      console.error('[gds] GET /sessions/search', err);
+      res.fail('search_failed', 500);
+    }
+  });
+
+  // rank: any-builder — your OWN sessions (self-serve; no audit needed).
+  router.get('/sessions/mine', auth.requireBuilder, readRateLimit, async (req, res) => {
+    try {
+      const sessions = await db.listSessionsByBuilder(req.builder.id, req.query.limit);
+      res.json({ sessions, count: sessions.length });
+    } catch (err) {
+      console.error('[gds] GET /sessions/mine', err);
+      res.fail('list_failed', 500);
+    }
+  });
+
+  // rank: any-builder — own session full detail (deep-dive); cross-builder fetch
+  // requires Archon + a fail-closed audit row (BFG-principal posture until 6C.1).
+  router.get('/sessions/:id', auth.requireBuilder, readRateLimit, async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_session_id', positiveInt: true });
+    if (id === null) return;
+    try {
+      const session = await db.getSessionById(id);
+      if (!session) return res.fail('not_found', 404);
+      const isOwner = String(session.builder_id) === String(req.builder.id);
+      if (!isOwner) {
+        // Non-owner, non-Archon: return 404 (NOT 403) so the response can't be
+        // used as an existence oracle for sequential session ids.
+        if (req.builder.rank !== 'archon') return res.fail('not_found', 404);
+        await recordSessionRead(req, {
+          route: '/api/bongos/sessions/:id',
+          targetBuilderId: session.builder_id,
+          target: `session:${id}`,
+        });
+      }
+      res.json({ session });
+    } catch (err) {
+      console.error('[gds] GET /sessions/:id', err);
+      res.fail('fetch_failed', 500);
+    }
+  });
+
+  return router;
+};

package/modules/status-ui/CLAUDE.md

@@ -0,0 +1,47 @@
+# `status-ui` module — the public status dashboard ("The Watch")
+
+> A CORE-domain carve (BV1.R84, [ADR 0093](../../docs/adr/<redacted>.md) §1) — the **first WEB-SURFACE module** ([02-module-map §6](../../docs/design/modular-architecture/02-module-map.md): "a web surface is first-class"). `default: true` — a Cloud Bongos instance ships its status page like it ships its hall, so it mounts unconditionally unless an instance disables it.
+
+Owns the public build-status dashboard served at **`status.<apex>`** (`status.example.com`) — the live up/down banner, version-progress rollups, cost summary, recent ships, the leaderboard, and the kinds-of-work ecosystem fingerprint. A no-framework page (`status.js`) that polls the read-only `/api/gds/public/*` surface every 60s.
+
+## The shape: a static surface, not a backend domain
+
+Unlike every prior tranche-2 carve (economy/ideas/security/…), this module has **no `.js`, no `db.js` slice, no kernel port, and no routes**. It is purely:
+- `public/` — the static dashboard (HTML/CSS/JS/cursors/snapshots), moved verbatim from the old repo-root `public-status/`.
+- `module.json` — declares one **`contributes.webSurfaces`** entry `{ host: "status.", dir: "public" }`.
+
+## The serving seam (how a web surface reaches its host with no core edit)
+
+The loader exposes `moduleWebSurfaces({ isEnabled })` ([`src/module-loader/loader.js`](../../src/module-loader/loader.js)) — the Host-routed twin of `hallWidgetScripts`/`mountModuleRoutes`. It returns `[{ key, host, dir(abs) }]` for each enabled module that declares `webSurfaces` **and** ships the directory on disk. `src/bongos/serve-internal.js` iterates that set and serves each surface on its `Host:` prefix with the **same** machinery the status page always used:
+- the in-memory **content-hash-stamped** index (`buildStampedHtml`, #521 — defeats Cloudflare's 4h TTL),
+- the per-instance **branding/theme injection** (`injectBrandingInto`),
+- fall-through to `express.static` for assets.
+
+`serve-internal.js` names **no module key** (kernel stays module-agnostic, [ADR 0083](../../docs/adr/<redacted>.md) §Decision #4); it routes purely off the manifest-declared `host` prefix. The `isStatusHost` export stays the literal `status.` predicate the entrypoints (`server.js`/`src/platform-server.js`) use to keep their apex tail off the status host; **inside** `mountInternalSurfaces` the generic `isModuleSurfaceHost` (any enabled web-surface host) is used, so the next carved surface (hall-UI, R85) needs no new guard.
+
+## The boundary
+
+This module reaches **nothing** in core (no doorway require — it has no JS). Core, in turn, must never `require()` a file in here — `serve-internal.js` resolves the surface through `loader.moduleWebSurfaces`, never an import of `modules/status-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/public/*` read endpoints the dashboard polls (`/public/uptime`, `/public/progress`, `/public/cost-summary`, `/public/grades`, `/public/recent-shipped`, `/public/leaderboard`, `/public/analytics/ecosystem`, `/public/tasks|ideas|blockers/:id`, plus `/versions/:id/done-when`) **did not move** — they live in `src/bongos/routes/public.js` and are consumed by the hall and the **off-box GitHub-Pages mirror** too, not just this surface. A public read shared by multiple surfaces is correctly core/shared, not status-exclusive (the same call the economy/ideas carves made for `routes/public.js`'s inline reads). So the carve moves the *surface*, not the reads it happens to render.
+
+## Off-box mirror (operational)
+
+The LIVE page is served **off the droplet** for outage resilience ([ADR 0029](../../docs/adr/<redacted>.md)) — GitHub Pages from `example-owner/example-status`, fed by `scripts/status-mirror-sync.js`. That script (status-UI domain tooling that travels with its domain but stays a CLI under `scripts/`, the sessions/autonomy precedent) was re-pointed at `modules/status-ui/public/`. **Follow-up:** `.github/workflows/sync-status-mirror.yml` still triggers on `public-status/**` and must be re-pointed at `modules/status-ui/public/**` by an owner/Archon (the GitHub App can't push workflow files — learning 107).
+
+## Files & tooling
+
+| Path | What |
+|---|---|
+| `public/index.html` · `public/status.js` · `public/style.css` | the dashboard (no build step, no framework) |
+| `public/cursors/` · `public/snapshots/` | bronze cursors + the world-render snapshots the page shows |
+| `public/README.md` | the surface's own notes (off-box mirror, asset cache-busting) |
+| `module.json` | `contributes.webSurfaces: [{ host: "status.", dir: "public" }]`; no port, no routes |
+
+Generators that WRITE into this surface live under `scripts/` and were re-pointed: `scripts/art/gen-cursors.py` (cursors), `scripts/snapshots/render-*.mjs` (snapshots), `scripts/status-mirror-sync.js` (off-box publish).
+
+## Tests
+
+The loader seam is covered in `tests/module_loader.mjs` (`moduleWebSurfaces` — enabled lists, disabled vanishes, declared-but-not-shipped skipped, plus the live status-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`; and the carve proof in `scripts/gds/coreB-carve-proof.sh` (leg 4h).

package/modules/status-ui/module.json

@@ -0,0 +1,14 @@
+{
+  "key": "status-ui",
+  "title": "Status dashboard (\"The Watch\")",
+  "description": "The public build-status dashboard served at status.<apex> (status.amazonprimea.com) — the live up/down banner, version-progress rollups, cost summary, recent ships, leaderboard, and the ecosystem fingerprint, all polling the read-only /api/gds/public/* surface every 60s. A WEB-SURFACE core-domain module carved out of the GDS core in BV1.R84 (ADR 0093 §1; 02-module-map §6 — a web surface is first-class). default-on: a Cloud Bongos instance ships its status page like it ships its hall. Registers no port and contributes no routes — it declares a webSurface (host prefix + static dir) the loader hands serve-internal, which serves the module's public/ dir on the matching host exactly as it served public-status/ before. The public read endpoints it renders stay SHARED core in routes/public.js (the hall + the off-box mirror read them too).",
+  "coreVersion": "^1.11.0",
+  "default": true,
+  "contributes": {
+    "webSurfaces": [
+      { "host": "status.", "dir": "public" }
+    ]
+  },
+  "provides": [],
+  "consumes": []
+}

package/modules/status-ui/public/README.md

@@ -0,0 +1,29 @@
+# `modules/status-ui/public/` — the status dashboard ("The Watch")
+
+These files are the source of `status.example.com`. The surface moved here from `public-status/` in **BV1.R84** when the status dashboard became a first-class module ([ADR 0093](../../../docs/adr/<redacted>.md) §1); the loader's web-surface seam serves this `public/` dir on the `status.` host (see [`../CLAUDE.md`](../CLAUDE.md)). As of **#566 / [ADR 0029](../../../docs/adr/<redacted>.md)** they are **mirrored OFF-BOX** so the status page survives a droplet outage.
+
+## Why off-box
+
+On 2026-06-03 the droplet was powered off (a failed payment) and this page — served by the *same* Node process as the game — went dark with it. A status page must not share fate with the system it reports on.
+
+## Where it lives now
+
+- **Off-box mirror:** **[`example-owner/example-status`](https://github.com/example-owner/example-status)** → served by **GitHub Pages** (separate infrastructure from the DigitalOcean droplet). After the DNS cutover, `status.example.com` points there.
+- **This copy (droplet):** remains the origin/source of truth for the page markup and the fallback until the DNS cutover is confirmed. Once the off-box mirror is canonical it can be deprecated in a follow-up.
+
+## How the off-box page stays truthful during an outage
+
+The mirror is a port of these files with three changes:
+
+1. **Availability banner (always truthful):** a top strip reads the external prober's `status.json` from the off-box `status-data` branch (`raw.githubusercontent.com`) — so it shows the *real* up/down even when the droplet (and its API) are down.
+2. **Dev panels (degrade gracefully):** `status.js`'s `API` base points at the absolute droplet origin (`https://example.com`); `/api/bongos/public/*` now sends `<redacted>: *` (see `src/bongos/routes/public.js`) so the panels load cross-origin. Each fetch already `.catch(() => null)`, so when the droplet is down the panels show their empty state instead of breaking the page.
+3. **Assets are relative** so the page works at both the GitHub Pages URL and the custom domain.
+
+## Probing & alerting
+
+- **Alerting:** `.github/workflows/status-probe.yml` (this repo, #565) probes from outside every 5 min and **emails on a confirmed outage** — the "never surprised again" path.
+- **Page data:** the off-box repo runs its own **data-only** prober (no alert, to avoid double-alerting) that publishes `status.json` for the banner.
+
+## `uptime-poller.js` decision (ADR 0029)
+
+[`src/bongos/uptime-poller.js`](../../../src/bongos/uptime-poller.js) is **retained as an INTERNAL component-liveness signal** (can the Node process reach its own DB?). It is **no longer the public source of truth** for availability — a monitor inside the monitored process cannot witness its own death. The public truth is now the **external** prober (#565) + this off-box page. The in-process poller stays because the internal "is my DB reachable" datapoint is still useful and cheap; removing it is not warranted.