@bongos/core 1.17.0

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

@@ -0,0 +1,335 @@
+// public-builders/harbor.js — the Harbor (/builders/harbor).
+//
+// Archon-only dev-box management view (idea 257 / task 1163). Every builder's
+// dev box is rendered as a card on the dock; an Archon can close any box and
+// block a builder from opening new ones.
+//
+// Like the Watch page, this reads /api/bongos/me to learn the viewer's rank and
+// shows an Archons-only notice otherwise — DEFENCE IN DEPTH only. The data + mutation
+// endpoints (/boxes, /boxes/:id/close, /boxes/:id/block) are ALSO archon-gated
+// server-side (ADR 0016), and the page itself is gated by server.js
+// requireArchonPage. On a 401 it redirects into the web sign-in flow.
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  // Generated typed client (task 1996 / R09), served as window.BongosClient by
+  // /lib/bongos-client.js. baseUrl:'' passes the full `${API}${path}` URLs below
+  // through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const { escapeHtml, fmtInt } = window.OTB;
+  const rankLabel = (rank) => window.OTB.rankLabel(rank, { empty: '' });
+  const toast = (msg) => window.OTB.toast(msg);
+
+  // States that hold a droplet/snapshot worth reclaiming — mirrors the server's
+  // boxes.canTransition('deprovision', …). A box in one of these can be
+  // closed; the rest (none/destroyed/provisioning) have nothing to deprovision.
+  const CLOSEABLE = new Set(['active', 'parking', 'parked', 'waking', 'error']);
+
+  // ---- fetch helpers (mirror watch.js) -------------------------------------
+
+  async function fetchJson(path) {
+    const res = await api.request('GET', `${API}${path}`);
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw { kind: '401' }; }
+    if (res.status === 403) { throw { kind: '403' }; }
+    if (!res.ok) throw new Error(`${path} → ${res.status}`);
+    return res.data;
+  }
+
+  async function sendJson(method, path, body) {
+    const res = await api.request(method, `${API}${path}`, { body: body || {} });
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw { kind: '401' }; }
+    const data = res.data || {};
+    if (!res.ok) throw new Error(data.message || data.error || `${path} → ${res.status}`);
+    return data;
+  }
+
+  // ---- formatters ----------------------------------------------------------
+
+  // ISO → "3h 12m" / "2d 4h" / "8m" elapsed-since. "—" for empty/bad input.
+  function fmtAgo(iso) {
+    if (!iso) return '—';
+    const t = new Date(iso).getTime();
+    if (!Number.isFinite(t)) return '—';
+    let s = Math.max(0, Math.round((Date.now() - t) / 1000));
+    const d = Math.floor(s / 86400); s -= d * 86400;
+    const h = Math.floor(s / 3600); s -= h * 3600;
+    const m = Math.floor(s / 60);
+    if (d > 0) return `${d}d ${h}h`;
+    if (h > 0) return `${h}h ${m}m`;
+    return `${m}m`;
+  }
+
+  function fmtUsd(n) {
+    const v = Number(n);
+    if (!Number.isFinite(v)) return '$0.00';
+    return `$${v.toFixed(2)}`;
+  }
+
+  // Map a box state (+ block flag) to its card styling + pill label.
+  function stateStyle(state, blocked) {
+    if (blocked) return { mod: 'blocked', pill: 'blocked', pillMod: 'blocked' };
+    switch (state) {
+      case 'active': return { mod: 'active', pill: 'active', pillMod: 'active' };
+      case 'parked': return { mod: 'parked', pill: 'parked', pillMod: '' };
+      case 'provisioning':
+      case 'waking':
+      case 'parking': return { mod: 'pending', pill: state, pillMod: 'pending' };
+      case 'error': return { mod: 'error', pill: 'error', pillMod: '' };
+      default: return { mod: 'gone', pill: state || 'none', pillMod: '' };
+    }
+  }
+
+  // ---- modal ---------------------------------------------------------------
+
+  function closeModal() {
+    const root = document.getElementById('harbor-modal-root');
+    if (root) root.innerHTML = '';
+  }
+
+  // Build a modal. `fields` is optional extra HTML (inputs). onConfirm receives
+  // the modal element so the caller can read its inputs.
+  function openModal({ title, bodyHtml, confirmLabel, danger, onConfirm }) {
+    const root = document.getElementById('harbor-modal-root');
+    root.innerHTML = '';
+    const bg = document.createElement('div');
+    bg.className = 'harbor-modal-bg';
+    bg.innerHTML =
+      `<div class="harbor-modal" role="dialog" aria-modal="true">
+        <h2>${escapeHtml(title)}</h2>
+        ${bodyHtml}
+        <div class="harbor-modal__actions">
+          <button class="harbor-btn" data-act="cancel">Cancel</button>
+          <button class="harbor-btn ${danger ? 'harbor-btn--danger' : ''}" data-act="confirm">${escapeHtml(confirmLabel)}</button>
+        </div>
+      </div>`;
+    bg.addEventListener('click', (e) => { if (e.target === bg) closeModal(); });
+    bg.querySelector('[data-act=cancel]').addEventListener('click', closeModal);
+    bg.querySelector('[data-act=confirm]').addEventListener('click', () => onConfirm(bg));
+    root.appendChild(bg);
+  }
+
+  // ---- actions -------------------------------------------------------------
+
+  function confirmClose(box) {
+    const who = box.builder.github_login || `#${box.builder.id}`;
+    const verb = box.state === 'parked' ? 'destroy the snapshot of' : 'close';
+    openModal({
+      title: `Close ${who}'s box?`,
+      bodyHtml: `<p>This will ${verb} <strong>${escapeHtml(who)}</strong>'s dev box (state: ${escapeHtml(box.state)}). Any uncommitted work on that box is lost. The box is destroyed; the builder can open a fresh one unless they are also blocked.</p>
+         <p>A fresh box has a <strong>new SSH identity</strong>. If their Claude Desktop later says &ldquo;Host denied&rdquo; or asks for a password, tell them to fully restart Desktop (it re-pins) or press Repair — not to keep rebuilding, which only rotates the identity again.</p>`,
+      confirmLabel: 'Close box',
+      danger: true,
+      onConfirm: async () => {
+        try {
+          const r = await sendJson('POST', `/boxes/${box.builder.id}/close`, {});
+          toast(r.message || 'Close queued.');
+          closeModal();
+          load();
+        } catch (err) {
+          if (err && err.kind === '401') return;
+          toast(`Could not close: ${err.message || err}`);
+        }
+      },
+    });
+  }
+
+  function confirmBlock(box) {
+    const who = box.builder.github_login || `#${box.builder.id}`;
+    const hasLiveBox = CLOSEABLE.has(box.state);
+    openModal({
+      title: `Bar ${who} from opening boxes?`,
+      bodyHtml:
+        `<p>${escapeHtml(who)} will not be able to open or wake a dev box until you unblock them. A box they already have running is left alone unless you also close it below.</p>
+         <label for="harbor-block-reason">Reason (shown to the builder)</label>
+         <textarea id="harbor-block-reason" rows="2" placeholder="e.g. runaway cost — paused pending review"></textarea>
+         ${hasLiveBox ? `<label class="harbor-modal__check"><input type="checkbox" id="harbor-block-close"> Also close the box they have running now (state: ${escapeHtml(box.state)})</label>` : ''}`,
+      confirmLabel: 'Block builder',
+      danger: true,
+      onConfirm: async (modal) => {
+        const reason = (modal.querySelector('#harbor-block-reason') || {}).value || '';
+        const closeEl = modal.querySelector('#harbor-block-close');
+        try {
+          const r = await sendJson('PATCH', `/boxes/${box.builder.id}/block`, {
+            blocked: true,
+            reason: reason.trim() || undefined,
+            close_current: !!(closeEl && closeEl.checked),
+          });
+          toast(r.close_queued ? 'Builder blocked — running box will be closed.' : 'Builder blocked.');
+          closeModal();
+          load();
+        } catch (err) {
+          if (err && err.kind === '401') return;
+          toast(`Could not block: ${err.message || err}`);
+        }
+      },
+    });
+  }
+
+  function confirmUnblock(box) {
+    const who = box.builder.github_login || `#${box.builder.id}`;
+    openModal({
+      title: `Lift the block on ${who}?`,
+      bodyHtml: `<p>${escapeHtml(who)} will be able to open dev boxes again.</p>`,
+      confirmLabel: 'Unblock',
+      danger: false,
+      onConfirm: async () => {
+        try {
+          await sendJson('PATCH', `/boxes/${box.builder.id}/block`, { blocked: false });
+          toast('Block lifted.');
+          closeModal();
+          load();
+        } catch (err) {
+          if (err && err.kind === '401') return;
+          toast(`Could not unblock: ${err.message || err}`);
+        }
+      },
+    });
+  }
+
+  // ---- render --------------------------------------------------------------
+
+  function renderContainer(box, costByBuilder) {
+    const blocked = box.blocked && box.blocked.is;
+    const st = stateStyle(box.state, blocked);
+    const who = escapeHtml(box.builder.github_login || `#${box.builder.id}`);
+    const rank = rankLabel(box.builder.rank);
+    const cost = costByBuilder.get(String(box.builder.id));
+
+    const rows = [];
+    if (box.region || box.size_slug) {
+      rows.push(['Make', escapeHtml([box.region, box.size_slug].filter(Boolean).join(' · '))]);
+    }
+    if (box.ip && box.state === 'active') rows.push(['IP', escapeHtml(box.ip)]);
+    if (box.state === 'active') {
+      rows.push(['Up for', fmtAgo(box.provisioned_at)]);
+      rows.push(['Idle', `${fmtAgo(box.last_activity_at)}${box.claude_active ? ' · claude live' : ''}`]);
+    } else if (box.state === 'parked') {
+      rows.push(['Parked', fmtAgo(box.parked_at)]);
+    } else if (CLOSEABLE.has(box.state)) {
+      rows.push(['State since', fmtAgo(box.last_activity_at || box.provisioned_at)]);
+    }
+    rows.push(['Cost', cost != null ? fmtUsd(cost) : fmtUsd(box.compute_cost_usd)]);
+
+    const rowsHtml = rows.map(([k, v]) =>
+      `<li><span class="k">${escapeHtml(k)}</span><span class="v">${v}</span></li>`).join('');
+
+    const blockedNote = blocked
+      ? `<p class="harbor-blocked-note">Barred from opening boxes${box.blocked.reason ? `: ${escapeHtml(box.blocked.reason)}` : '.'}</p>`
+      : '';
+
+    const closeable = CLOSEABLE.has(box.state);
+    const closeLabel = box.state === 'parked' ? 'Destroy' : 'Close';
+    const actions = [];
+    if (closeable) actions.push(`<button class="harbor-btn harbor-btn--danger" data-act="close">${closeLabel}</button>`);
+    actions.push(blocked
+      ? `<button class="harbor-btn" data-act="unblock">Unblock</button>`
+      : `<button class="harbor-btn" data-act="block">Block</button>`);
+
+    const el = document.createElement('article');
+    el.className = `harbor-container harbor-container--${st.mod}`;
+    el.innerHTML =
+      `<div class="harbor-container__roof" aria-hidden="true"></div>
+       <div class="harbor-container__body">
+         <div class="harbor-container__head">
+           <span class="harbor-container__who">${who}<span class="harbor-container__rank">${escapeHtml(rank)}</span></span>
+           <span class="harbor-pill harbor-pill--${st.pillMod}">${escapeHtml(st.pill)}</span>
+         </div>
+         <ul class="harbor-rows">${rowsHtml}</ul>
+         ${blockedNote}
+         <div class="harbor-actions">${actions.join('')}</div>
+       </div>`;
+
+    const closeBtn = el.querySelector('[data-act=close]');
+    if (closeBtn) closeBtn.addEventListener('click', () => confirmClose(box));
+    const blockBtn = el.querySelector('[data-act=block]');
+    if (blockBtn) blockBtn.addEventListener('click', () => confirmBlock(box));
+    const unblockBtn = el.querySelector('[data-act=unblock]');
+    if (unblockBtn) unblockBtn.addEventListener('click', () => confirmUnblock(box));
+    return el;
+  }
+
+  function renderSummary(boxes, totalUsd) {
+    const afloat = boxes.filter((b) => CLOSEABLE.has(b.state)).length;
+    const active = boxes.filter((b) => b.state === 'active').length;
+    const blocked = boxes.filter((b) => b.blocked && b.blocked.is).length;
+    const stats = [
+      ['Boxes live', fmtInt(afloat)],
+      ['Active now', fmtInt(active)],
+      ['Blocked builders', fmtInt(blocked)],
+      ['Total cost', fmtUsd(totalUsd)],
+    ];
+    document.getElementById('harbor-summary').innerHTML = stats.map(([label, value]) =>
+      `<div class="harbor-stat"><div class="harbor-stat__label">${escapeHtml(label)}</div><div class="harbor-stat__value">${value}</div></div>`).join('');
+  }
+
+  // Sort: live boxes first, then parked, then everything else;
+  // within a group, most-recently-touched first (the API already orders by
+  // updated_at desc, so a stable sort by group preserves that).
+  function sortBoxes(boxes) {
+    const rank = (b) => (b.state === 'active' ? 0 : CLOSEABLE.has(b.state) ? 1 : (b.blocked && b.blocked.is) ? 2 : 3);
+    return boxes.map((b, i) => [b, i]).sort((a, z) => (rank(a[0]) - rank(z[0])) || (a[1] - z[1])).map((p) => p[0]);
+  }
+
+  async function load() {
+    const dock = document.getElementById('harbor-dock');
+    let boxesResp, ledger;
+    try {
+      [boxesResp, ledger] = await Promise.all([
+        fetchJson('/boxes'),
+        fetchJson('/boxes/cost-ledger').catch(() => ({ totals_by_builder: [] })),
+      ]);
+    } catch (err) {
+      if (err && err.kind === '401') return;
+      if (err && err.kind === '403') { showSealed(); return; }
+      dock.innerHTML = `<p class="harbor-empty">Could not load dev boxes just now.</p>`;
+      return;
+    }
+
+    const boxes = boxesResp.boxes || [];
+    const costByBuilder = new Map();
+    let totalUsd = 0;
+    for (const row of (ledger.totals_by_builder || [])) {
+      const usd = Number(row.total_usd) || 0;
+      costByBuilder.set(String(row.builder_id), usd);
+      totalUsd += usd;
+    }
+
+    renderSummary(boxes, totalUsd);
+
+    if (boxes.length === 0) {
+      dock.innerHTML = `<p class="harbor-empty">No dev boxes yet — no builder has opened one.</p>`;
+      return;
+    }
+    dock.innerHTML = '';
+    for (const box of sortBoxes(boxes)) dock.appendChild(renderContainer(box, costByBuilder));
+  }
+
+  function showSealed() {
+    document.getElementById('harbor-sealed').hidden = false;
+    document.getElementById('harbor-body').hidden = true;
+    document.getElementById('harbor-sub').textContent = 'Archons only.';
+  }
+
+  async function init() {
+    // Confirm rank=archon for a friendly Archons-only notice; the server gates
+    // the page + every endpoint regardless (this is cosmetic defence-in-depth).
+    let me;
+    try {
+      me = await fetchJson('/me');
+    } catch (err) {
+      if (err && err.kind === '401') return;        // redirected to sign-in
+      if (err && err.kind === '403') { showSealed(); return; }
+      me = null;
+    }
+    const rank = (me && (me.builder || me).rank || '').toLowerCase();
+    if (rank !== 'archon') { showSealed(); return; }
+
+    document.getElementById('harbor-sub').textContent = 'Each builder’s dev box at a glance.';
+    document.getElementById('harbor-body').hidden = false;
+    await load();
+  }
+
+  init();
+})();

package/modules/hall-ui/public/index.html

@@ -0,0 +1,116 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <!-- BV1.R75 (ADR 0062 §4): the page chrome (title/description/h1) is the
+       no-JS fallback only — brand-apply.js rewrites it from window.__BRANDING__
+       (copy.hallName + identity.productName), and serve-internal.js injects the
+       branding global + the theme favicon <link> (later in <head>, so it wins
+       over the generic one below) on every served page. brand-apply gates all of
+       that on the #hall-h1 marker below, so the marker must stay index-only. -->
+  <title>Builders' Hall</title>
+  <meta name="description" content="The hall of the builders who shape this world. Standing, achievements, and work waiting to be claimed.">
+  <link rel="icon" href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><text x='16' y='24' font-size='24' text-anchor='middle' font-family='sans-serif'>⌂</text></svg>">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
+</head>
+<body data-page="home">
+
+<!-- The app shell: fixed sidebar + sticky top bar + normally-flowing content.
+     The window is the ONLY scroller (scroll-spy, scroll-margin and deep-link
+     scrollIntoView all assume window scrolling — keep it that way). shell.js
+     renders the sidebar/topbar innards synchronously at parse time (defer order
+     puts it before builders.js), so ids it renders (#logout-link, #welcome-line,
+     #topbar-title) exist before builders.js wires events. -->
+<div class="app">
+  <aside class="app-sidebar" id="app-sidebar" aria-label="Primary"></aside>
+  <div class="app-scrim" id="app-scrim" hidden></div>
+  <div class="app-body">
+    <header class="app-topbar" id="app-topbar"></header>
+    <div class="app-content">
+      <!-- brand-apply.js applyPageChrome gates on #hall-h1 existing (index only):
+           it sets document.title + this element's text from the branding pack.
+           The visible brand mark lives in the sidebar (shell.js reads the pack
+           directly); this stays as the invisible chrome hook + a11y page title. -->
+      <h1 id="hall-h1" class="sr-only">Builders' Hall</h1>
+
+      <!-- BV1.R75 (ADR 0062 §4): hall widgets are NOT hardcoded here. Every widget
+           — core (hall-widgets.js) and module-contributed (a module's own client
+           script) — registers into the hall-widget registry (window.OTB,
+           dom-utils.js), and builders.js stamps the registered <section>s into the
+           view containers below (falling back to <main> itself). The registry stays
+           the single source of truth for what the hall shows; a fitness check
+           (scripts/gds/fitness.js checkHallSectionRegistry) reds the build if a
+           <section class="scroll"> is hardcoded back inside this <main>. The
+           .view/.view-zone wrappers are shell layout only. -->
+      <main class="app-views">
+        <section class="view" id="view-home" data-view-title="Home">
+          <div class="view-zone" id="zone-home-banner">
+            <!-- Landing card for signed-out visitors (builders.js renderLanding)
+                 + the re-open affordance for a dismissed welcome banner. -->
+            <div id="landing-root" hidden></div>
+            <p id="welcome-reopen" hidden><a href="#home" class="pill-link">Show the setup guide again</a></p>
+          </div>
+          <div class="view-zone" id="zone-home-stats"></div>
+          <div class="view-zone view-zone--band" id="zone-home-band"></div>
+          <div class="view-zone" id="zone-home-main"></div>
+        </section>
+
+        <section class="view" id="view-standing" data-view-title="Standing" hidden>
+          <div class="standing-layout">
+            <nav class="section-rail" id="standing-rail" aria-label="Standing sections" hidden></nav>
+            <div class="view-zone standing-panels" id="zone-standing"></div>
+          </div>
+        </section>
+
+        <section class="view" id="view-achievements" data-view-title="Achievements" hidden>
+          <div class="view-zone" id="zone-achievements"></div>
+        </section>
+
+        <section class="view" id="view-leaderboard" data-view-title="Leaderboard" hidden>
+          <div class="view-zone" id="zone-leaderboard"></div>
+        </section>
+      </main>
+
+      <footer class="app-foot" id="app-foot"></footer>
+    </div>
+  </div>
+</div>
+
+<div id="toast" class="toast" role="status" aria-live="polite"></div>
+
+<!-- Live updates ride a Server-Sent Events stream (GET /api/bongos/live) since R55
+     / ADR 0069 — no client lib to load (EventSource is built into the browser). -->
+<!-- shared frontend toolkit (window.OTB) — loaded FIRST so every consuming
+     IIFE below can pull escapeHtml/$/fmtNum/... from one place. -->
+<script src="/builders/dom-utils.js?v=2026-06-14-domutils" defer></script>
+<script src="/builders/task-detail.js?v=2026-07-03-taskdetail" defer></script>
+<!-- R56 (task 1195): apply the instance currency label from window.__BRANDING__
+     to [data-currency-label]/[data-currency-tmpl] markup + expose OTBBranding.
+     Loaded BEFORE builders.js so the global is ready when the hall renders. -->
+<script src="/builders/brand-apply.js?v=2026-06-27-r75" defer></script>
+<!-- The app shell (sidebar + top bar + view router). Dependency-free; loaded
+     BEFORE builders.js so the chrome ids exist when events are wired. -->
+<script src="/builders/shell.js?v=2026-07-02-shell1" defer></script>
+<!-- #807: shared dev-box management panel — loaded BEFORE builders.js so the
+     OTBBoxPanel global is defined when the welcome panel mounts it. -->
+<script src="/builders/box-panel.js?v=2026-06-14-domutils" defer></script>
+<!-- BV1.R75: the CORE hall widgets register into window.OTB's hall-widget registry.
+     Loaded BEFORE builders.js so the registry is populated when builders.js stamps
+     the registered <section>s into the views. A module's own hall-widget client
+     script (served only when the module is enabled) is injected by the server
+     immediately before the builders.js tag below — that anchor is load-bearing
+     (serve-internal.js injectModuleHallWidgets). -->
+<script src="/builders/hall-widgets.js?v=2026-06-27-r75" defer></script>
+<!-- BV1.R78 (task 1694): the Goals widget registers into the same registry. -->
+<script src="/builders/goals.js?v=2026-07-01-goals" defer></script>
+<!-- BV1-prov-P6 (task 1947): the Instances widget — self-registers, gated on the provisioning module. -->
+<script src="/builders/new-project-wizard.js?v=2026-07-04-goal35" defer></script>
+<script src="/builders/instances-panel.js?v=2026-07-03-prov-p6" defer></script>
+<script src="/builders/builders.js?v=2026-06-27-r75" defer></script>
+<script src="/builders/copy-on-click.js?v=2026-06-01-copy-1" defer></script>
+</body>
+</html>

package/modules/hall-ui/public/instances-panel.js

@@ -0,0 +1,172 @@
+// instances-panel.js — the "Instances" hall widget (provisioning module, ADR 0111
+// §1, task 1947 / BV1-prov-P6).
+//
+// Surfaces provisioning_instances STATE + cost estimate: an owner sees their own
+// instance(s) + request status; an Archon additionally sees the fleet roster + the
+// cost ledger total. One cohesive panel — the caller's own instances always, the
+// fleet appended only when /me returns rank 'archon'.
+//
+// GATED on the provisioning module: registered with module:'provisioning', so
+// contributeHallWidget (dom-utils.js) drops it entirely on an instance that hasn't
+// enabled the module — the belt-and-suspenders to window.__MODULES__ (ADR 0062 §4).
+//
+// Reuses the dev-box hall pattern: a self-contained, self-fetching widget (the
+// goals.js precedent), living in the hall's own served dir so it serves on both the
+// apex and the builders subdomain. Reads the P1 routes only:
+//   GET /provisioning/instances                 (own)
+//   GET /provisioning/fleet                      (archon)
+//   GET /provisioning/fleet/cost-ledger          (archon)
+// READ/STATE only — no mutations. Creating a request is `bongos init` (P5) or the
+// provisioning API; request/teardown buttons here are a deliberate follow-up.
+(function () {
+  'use strict';
+  if (!window.OTB || typeof window.OTB.contributeHallWidget !== 'function') return;
+  const { escapeHtml } = window.OTB;
+  const API = '/api/bongos';
+  // Generated typed client (task 1996 / R09), served as window.BongosClient by
+  // /lib/bongos-client.js. baseUrl:'' passes the full same-origin paths this file
+  // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  async function getJSON(path, { softAuth = false } = {}) {
+    const res = await api.request('GET', path);
+    if (res.status === 401) {
+      if (softAuth) { const e = new Error('auth-needed'); e.code = 'auth-needed'; throw e; }
+      window.location.assign(`${API}/auth/web/start`);
+      throw new Error('redirecting to auth');
+    }
+    if (!res.ok) throw new Error(`${path} → ${res.status}`);
+    return res.data;
+  }
+
+  let host = null;
+
+  // Lifecycle status → a badge class from the shared goal-badge family (achieved =
+  // live/green, open = in-flight/neutral, archived = gone/muted). Mirrors the states
+  // in provisioning_001_tables.sql / provisioning.INSTANCE_STATES.
+  const STATUS_CLASS = {
+    active: 'goal-badge--achieved',
+    requested: 'goal-badge--open',
+    provisioning: 'goal-badge--open',
+    tearing_down: 'goal-badge--archived',
+    torn_down: 'goal-badge--archived',
+    error: 'goal-badge--archived',
+  };
+  function statusBadge(status) {
+    const cls = STATUS_CLASS[status] || 'goal-badge--open';
+    return `<span class="goal-badge ${cls}">${escapeHtml(status || 'unknown')}</span>`;
+  }
+  // Monthly cost — co-tenant is $0 (shares an existing box); a dedicated droplet
+  // carries its tier's estimate. VISIBILITY only (ADR 0111 §6), never a bill.
+  function usdMonthly(n) {
+    const v = Number(n) || 0;
+    return v > 0 ? `$${v.toFixed(2)}/mo` : '$0';
+  }
+  function openIntentNote(inst) {
+    if (!inst.open_intent) return '';
+    return ` <span class="ledger__note">(${escapeHtml(inst.open_intent.action)} ${escapeHtml(inst.open_intent.state)})</span>`;
+  }
+
+  function ownRow(inst) {
+    return `<tr>
+        <td>${escapeHtml(inst.slug || '—')}</td>
+        <td>${statusBadge(inst.status)}${openIntentNote(inst)}</td>
+        <td>${escapeHtml(inst.hosting_shape || '—')}</td>
+        <td>${inst.domain ? escapeHtml(inst.domain) : '—'}</td>
+        <td>${usdMonthly(inst.cost_estimate_usd)}</td>
+      </tr>`;
+  }
+
+  function fleetRow(inst) {
+    const owner = inst.owner || {};
+    return `<tr>
+        <td>${escapeHtml(inst.slug || '—')}</td>
+        <td>${escapeHtml(owner.github_login || owner.display_name || '—')}</td>
+        <td>${statusBadge(inst.status)}</td>
+        <td>${escapeHtml(inst.hosting_shape || '—')}</td>
+        <td>${inst.tier ? escapeHtml(inst.tier) : '—'}</td>
+        <td>${usdMonthly(inst.cost_estimate_usd)}</td>
+      </tr>`;
+  }
+
+  // Paint the caller's own instances into #instances-own-body.
+  function renderOwn(instances) {
+    const body = host.querySelector('#instances-own-body');
+    if (!body) return;
+    if (!instances.length) {
+      body.innerHTML = '<p class="goal-empty">No instances yet. Create one with <code>bongos init</code> or the provisioning API — it’ll show here with its status and cost.</p>';
+      return;
+    }
+    body.innerHTML =
+      '<table class="ledger"><thead><tr><th>Instance</th><th>Status</th><th>Shape</th><th>Domain</th><th>Cost</th></tr></thead>' +
+      `<tbody>${instances.map(ownRow).join('')}</tbody></table>`;
+  }
+
+  // Paint the fleet + cost-ledger total into #instances-fleet (Archon only). Reveals
+  // the section (hidden by default in the skeleton) once data is in hand.
+  function renderFleet(fleet, ledger) {
+    const wrap = host.querySelector('#instances-fleet');
+    const body = host.querySelector('#instances-fleet-body');
+    if (!wrap || !body) return;
+    wrap.hidden = false;
+    if (!fleet.length) {
+      body.innerHTML = '<p class="goal-empty">No provisioned instances across the fleet yet.</p>';
+      return;
+    }
+    const total = ledger && typeof ledger.total_monthly_usd === 'number' ? ledger.total_monthly_usd : null;
+    body.innerHTML =
+      '<table class="ledger"><thead><tr><th>Instance</th><th>Owner</th><th>Status</th><th>Shape</th><th>Tier</th><th>Cost</th></tr></thead>' +
+      `<tbody>${fleet.map(fleetRow).join('')}</tbody></table>` +
+      (total !== null ? `<p class="ledger__note">Fleet estimate: <strong>${usdMonthly(total)}</strong> across ${fleet.length} instance${fleet.length === 1 ? '' : 's'} (co-tenant instances are $0).</p>` : '');
+  }
+
+  async function load() {
+    if (!host) return;
+    try {
+      // Own instances (any authenticated builder).
+      const mine = await getJSON(`${API}/provisioning/instances`);
+      renderOwn(Array.isArray(mine.instances) ? mine.instances : []);
+    } catch (err) {
+      const body = host.querySelector('#instances-own-body');
+      if (body) body.innerHTML = '<p class="goal-empty">Your instances couldn’t be loaded just now. Refresh to try again.</p>';
+      console.error('[hall] instances load failed', err);
+    }
+
+    // Archon-only: the fleet roster + cost ledger. Read /me softly; a non-Archon (or
+    // an auth hiccup) simply never reveals the fleet section.
+    try {
+      const me = await getJSON(`${API}/me`, { softAuth: true }).catch(() => null);
+      const rank = me && me.builder ? me.builder.rank : null;
+      if (rank !== 'archon') return;
+      const [fleet, ledger] = await Promise.all([
+        getJSON(`${API}/provisioning/fleet`).catch(() => ({ instances: [] })),
+        getJSON(`${API}/provisioning/fleet/cost-ledger`).catch(() => null),
+      ]);
+      renderFleet(Array.isArray(fleet.instances) ? fleet.instances : [], ledger);
+    } catch (err) {
+      console.error('[hall] instances fleet load failed', err);
+    }
+  }
+
+  const SKELETON =
+    '<h2 id="instances-h" class="scroll__h">Instances</h2>' +
+    '<p class="scroll__lede">Hosting you’ve provisioned through Cloud Bongos — each instance’s status and estimated monthly cost. Provision one with <code>bongos init</code> or the provisioning API.</p>' +
+    '<div id="instances-own-body"><div class="profile__placeholder">Loading your instances…</div></div>' +
+    '<div id="instances-fleet" hidden>' +
+      '<h3 class="scroll__h" style="font-size:1rem;margin-top:1rem">Fleet</h3>' +
+      '<p class="scroll__lede">Every owner’s instances and the fleet cost estimate (Archon view).</p>' +
+      '<div id="instances-fleet-body"><div class="profile__placeholder">Loading the fleet…</div></div>' +
+    '</div>';
+
+  function mount(hostEl) {
+    host = hostEl;
+    host.innerHTML = SKELETON;
+    load();
+  }
+
+  window.OTB.contributeHallWidget({
+    id: 'instances-scroll', label: 'Instances', order: 34,
+    module: 'provisioning', view: 'home', zone: 'home-main',
+    labelledby: 'instances-h', mount,
+  });
+})();