@bongos/core 1.18.3 → 1.18.19

package/src/bongos/routes/auth.js

@@ -80,6 +80,78 @@ function renderAuthErrorPage(heading, detail, opts = {}) {
 </body></html>`;
 }
 
+// renderAccessPendingPage — the calm "hang tight" page shown instead of the red
+// dead-end when admission is plausibly imminent (task 1002097): the configured
+// firstAdmin during the bootstrap window, or a login with a pending request.
+//
+// It polls GET /auth/web/admission-status and, the moment the answer flips to
+// admitted, sends the visitor back through /auth/web/start for a FRESH sign-in.
+// A fresh start is required, not optional: the OAuth code that brought them
+// here is already spent, so re-running the callback would fail on state
+// mismatch. The owner chose auto-walk-in, hence no button to click.
+//
+// Branding resolves defensively, exactly as renderAuthErrorPage does — a
+// branding hiccup must degrade to neutral copy, never crash the page.
+function renderAccessPendingPage(login) {
+  const worldName = (() => { try { return branding().identity?.worldName || 'The city'; } catch { return 'The city'; } })();
+  const epigraph = (() => { try { return branding().copy?.authError?.epigraph || '— access —'; } catch { return '— access —'; } })();
+  // The probe takes the login as a query param; everything interpolated into
+  // the page is escaped, and the JS reads it from a data- attribute rather than
+  // being built by string concatenation into a script body.
+  const safeLogin = escapeHtml(String(login || ''));
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(worldName)} — confirming access</title>
+<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=Cinzel:wght@500;700&family=EB+Garamond:ital,wght@0,400;0,500&display=swap" rel="stylesheet">
+<link rel="stylesheet" href="/builders/style.css">
+</head><body>
+<header class="hall">
+  <p class="hall__epigraph">${escapeHtml(epigraph)}</p>
+  <h1>Confirming your access</h1>
+  <p class="hall__sub">Hang tight — this usually takes a few seconds.</p>
+</header>
+<main>
+  <section class="scroll">
+    <div class="landing" id="pending" data-login="${safeLogin}">
+      <p>We're checking your access now. You'll be signed in automatically as soon as it clears — no need to refresh.</p>
+      <p class="landing__note" id="pending-note">Checking…</p>
+    </div>
+  </section>
+</main>
+<script>
+(function () {
+  var el = document.getElementById('pending');
+  var note = document.getElementById('pending-note');
+  var login = el ? el.getAttribute('data-login') : '';
+  var EVERY_MS = 3000;
+  var GIVE_UP_MS = 5 * 60 * 1000;
+  var started = Date.now();
+
+  function land() { window.location.href = '/api/gds/auth/web/start'; }
+
+  function tick() {
+    if (Date.now() - started > GIVE_UP_MS) {
+      note.textContent = 'Still waiting on approval. You can leave this page open, or try signing in again later.';
+      return;
+    }
+    fetch('/api/gds/auth/web/admission-status?login=' + encodeURIComponent(login), { credentials: 'omit' })
+      .then(function (r) { return r.ok ? r.json() : null; })
+      .then(function (j) {
+        if (j && j.admitted) { land(); return; }
+        setTimeout(tick, EVERY_MS);
+      })
+      .catch(function () { setTimeout(tick, EVERY_MS); });
+  }
+  setTimeout(tick, EVERY_MS);
+})();
+</script>
+</body></html>`;
+}
+
 // Cookie names. The web flow writes the new `gds_session` (+ `gds_oauth_state`)
 // names; both flows accept either the new or the legacy `pms_session` /
 // `pms_oauth_state` cookies on read so a builder mid-flow doesn't have to
@@ -189,6 +261,27 @@ function configuredOAuthOrigin() {
   }
 }
 
+// The post-sign-in landing used when no explicit ?return= / same-apex Referer
+// was stashed for this sign-in. Configurable per instance via
+// branding.landing.postLogin (env override <PREFIX>_POST_LOGIN_LANDING) so a
+// platform-home instance can land visitors on its OWN front door —
+// cloudbongos.com sets it to /gate/ (the orbs) so a visitor who signs in from
+// the orbs returns to the orbs, never auto-redirected into the builders' hall
+// (task 1002240). Every other instance keeps the portable default '/builders':
+// the hall always exists, a /gate/ orbs site does not. The configured value is
+// run through the SAME open-redirect allowlist as ?return= (safeReturnTo), so a
+// misconfigured landing can never become an open redirect; anything unsafe or
+// absent falls back to '/builders'. Takes an optional resolved pack so the pure
+// path is unit-testable without disk I/O (mirrors clientBranding()).
+function postLoginLanding(brand) {
+  try {
+    const b = brand || branding();
+    return safeReturnTo(b.landing?.postLogin) || '/builders';
+  } catch {
+    return '/builders';
+  }
+}
+
 // The OAuth redirect_uri must be a FIXED, registered origin — never derived from
 // the request's x-forwarded-host (spoofable; F2 Hacker finding). Configured via
 // env, falling back to the configured canonical public origin, so an injected host
@@ -348,6 +441,49 @@ module.exports = function buildAuthRouter() {
       : auth.buildAuthorizeUrl(state, redirectUri, { repos: wantsRepos }));
   });
 
+  // GET /auth/web/admission-status?login=X — the probe renderAccessPendingPage
+  // polls (task 1002097). Answers ONE question: would this login be admitted
+  // right now? It mirrors the real gate via auth.webAdmissionStatus so the page
+  // can never invite someone in the gate would refuse.
+  //
+  // rank: public — it must be reachable by a visitor with no session (that is
+  //   the entire situation it exists for). It grants nothing: admission still
+  //   runs through the normal sign-in, and this only reads state.
+  //
+  // WHAT IT LEAKS, stated plainly (task 1002430 — an earlier version of this
+  // comment claimed the opposite and was wrong). Returning only a boolean does
+  // NOT make it non-enumerable: with open enrollment off, and for any login
+  // that is not the configured firstAdmin, `admitted:true` means that login is
+  // a member or has been invited. That reveals account existence to an
+  // unauthenticated caller. It is also NOT throttled — rateLimitMiddleware
+  // returns early for non-write methods, so GETs bypass it entirely; the page's
+  // 3s poll bounds the honest client, not an attacker.
+  //
+  // Why it is nonetheless not a new exposure: the onboarding module's
+  // GET /access-requests/status?github_login=X is ALREADY public and returns
+  // the strictly richer member|invited|pending|dismissed|none plus its own
+  // `admitted`. Anything derivable here is already derivable there, so this
+  // adds no net-new surface — and hardening only this route would accomplish
+  // nothing while that one stays open. Whether unauthenticated login-existence
+  // probing is acceptable at all is a real question, but it belongs to both
+  // routes together, not to a comment here.
+  //
+  // That endpoint is also why this one exists: it models neither the firstAdmin
+  // bypass nor open enrollment, so it reports the OWNER as 'none' forever —
+  // the exact case this page has to resolve.
+  router.get('/auth/web/admission-status', async (req, res) => {
+    const login = typeof req.query.login === 'string' ? req.query.login.slice(0, 100) : '';
+    if (!login) return res.json({ admitted: false });
+    try {
+      const { admitted } = await auth.webAdmissionStatus(login);
+      return res.json({ admitted: !!admitted });
+    } catch (err) {
+      // Fail closed and quietly — the page just keeps polling.
+      console.error('[gds] auth/web/admission-status', err);
+      return res.json({ admitted: false });
+    }
+  });
+
   // rank: public — OAuth callback; the state cookie + code are the bearer.
   router.get('/auth/web/callback', async (req, res) => {
     if (!auth.authConfigured() && !auth.idpConfigured()) {
@@ -415,15 +551,37 @@ module.exports = function buildAuthRouter() {
         res.clearCookie(REPOS_COOKIE, domainOpts);
       }
       // Land back where sign-in began if a validated return target was stashed
-      // (e.g. the builders subdomain bounced through here); else the hall.
+      // (e.g. the builders subdomain bounced through here); else the instance's
+      // configured post-login landing (default '/builders'; cloudbongos.com →
+      // /gate/, the orbs — task 1002240).
       const returnTo = safeReturnTo(parseCookie(req, RETURN_COOKIE));
       res.clearCookie(RETURN_COOKIE, domainOpts);
-      res.redirect(returnTo || '/builders');
+      res.redirect(returnTo || postLoginLanding());
     } catch (err) {
       // Approval gate (2026-05-30): a first-time GitHub account that hasn't been
       // approved by an Archon can't enter. Send them to the hall to request
       // access rather than dead-ending on a generic error.
       if (err && err.code === 'NOT_APPROVED') {
+        // task 1002097: a blocked sign-in is not always a rejection. On a fresh
+        // or just-restarted instance the configured firstAdmin lands here for a
+        // few seconds — before FIRST_ADMIN is loaded / the bootstrap finishes —
+        // and so does anyone whose access_request an Archon is about to mark
+        // invited. The red dead-end looked broken, and could not be retried:
+        // the OAuth code is single-use, so a reload throws "State mismatch"
+        // instead. For those two, show a calm waiting page that polls and walks
+        // them in by itself. Genuine strangers still get the request-access
+        // page below.
+        let expectedSoon = false;
+        try {
+          ({ expectedSoon } = await auth.webAdmissionStatus(err.login));
+        } catch (probeErr) {
+          // Never let the classifier turn a clean 403 into a 500 — fall through
+          // to the existing page, which is the safe answer for a stranger.
+          console.error('[gds] web/callback admission classify', probeErr);
+        }
+        if (expectedSoon) {
+          return res.status(202).type('text/html').send(renderAccessPendingPage(err.login));
+        }
         return res.status(403).type('text/html').send(renderAuthErrorPage(
           'This account is not approved yet',
           'Signing in with GitHub is only for builders an Archon has already approved. If you are new, request access at the builders’ hall — an Archon will approve you, then this sign-in will let you in. If you were just approved, the Archon may still need to mark you invited; give it a moment and try again.',
@@ -617,9 +775,67 @@ module.exports = function buildAuthRouter() {
       res.clearCookie(SESSION_COOKIE, domainOpts);
       res.clearCookie(SESSION_COOKIE_LEGACY, domainOpts);
     }
+    // Federated single-logout (ADR 0144, task 1002238): announce the logout so the
+    // hub (platform-identity, enabled only on cloudbongos.com) can fan a signed
+    // back-channel logout out to every federated project this builder entered. A
+    // fire-and-forget seam EMIT — zero listeners on a non-hub instance, so it's a
+    // no-op there; the fan-out is best-effort server-side and never blocks or fails
+    // this logout (the hub session is already revoked above).
+    seams.emit('builder.logout', {
+      builderId: req.builder.id,
+      githubId: req.builder.github_id,
+      githubLogin: req.builder.github_login,
+    });
     res.json({ ok: true });
   });
 
+  // POST /auth/backchannel-logout — the INSTANCE side of federated single-logout
+  // (ADR 0144, task 1002238). The hub POSTs a hub-signed logout token here when a
+  // builder signs out of the hub; we verify it and revoke ALL of that builder's
+  // local sessions, so one hub logout ends the session on every federated project.
+  //
+  // rank: public — the hub-signed EdDSA logout token IS the credential (like the
+  //   OAuth callback), NOT a builder session. Inert (404) on an instance that does
+  //   not federate through a hub (idp unset), so a self-hosted instance exposes no
+  //   new surface. Idempotent: an unknown/replayed subject just revokes nothing.
+  router.post('/auth/backchannel-logout', async (req, res) => {
+    const idp = auth.loadIdpConfig();
+    if (!idp) {
+      // Not a federated instance — indistinguishable from "no such route".
+      return res.status(404).type('text/plain').send('not found');
+    }
+    if (validateOrRespond(req, res, {
+      logout_token: { required: true, type: 'string', maxLength: 4096 },
+    })) return;
+    const publicKey = auth.loadHubPublicKey();
+    if (!publicKey) return res.fail('idp_unconfigured', { status: 503, message: 'hub public key not configured' });
+    let payload;
+    try {
+      payload = auth.verifyHubLogoutToken(req.body.logout_token, { publicKey, clientId: idp.clientId });
+    } catch (err) {
+      // A bad / expired / forged / wrong-audience token is an auth failure (401),
+      // never a server error — and never revokes anything.
+      return res.fail('invalid_logout_token', { status: 401, message: String(err.message || 'invalid logout token').slice(0, 160) });
+    }
+    // Anti-replay (defense-in-depth, symmetric with the CLI assertion path): honor
+    // a logout token's jti ONCE. A replay within the ~120s TTL is an idempotent
+    // no-op, so a captured token can't keep killing sessions the builder creates
+    // AFTER it was minted.
+    if (auth.logoutTokenJtiSeenAndRecord(payload.jti, payload.exp)) {
+      return res.json({ ok: true });
+    }
+    try {
+      const builder = await db.getBuilderByGithubId(payload.sub);
+      // Revoke ALL of this builder's local sessions (web + CLI) — the hub said sign
+      // them out. No-op + 200 if we don't know this builder (never leak existence).
+      if (builder) await db.revokeAllSessionsForBuilder(builder.id);
+      res.json({ ok: true });
+    } catch (err) {
+      console.error('[gds] /auth/backchannel-logout revoke', err);
+      res.fail('server_error', { status: 500, message: 'logout failed' });
+    }
+  });
+
   // POST /auth/cli-token/issue — V3.R91 / #401. Issue a fresh CLI bearer for
   // the requesting builder, gated on a WEB COOKIE session (not a bearer). The
   // browser already proves identity via the gds_session cookie; this endpoint
@@ -835,6 +1051,7 @@ module.exports = function buildAuthRouter() {
 // open-redirect guard on the post-sign-in return target and the cross-subdomain
 // cookie-domain decision — worth locking down independently of a running server.
 module.exports.safeReturnTo = safeReturnTo;
+module.exports.postLoginLanding = postLoginLanding;
 module.exports.sessionCookieDomainOpts = sessionCookieDomainOpts;
 module.exports.reqHost = reqHost;
 // The auth-error page renderer (task 1439): pure over the branding pack, so a

package/src/bongos/routes/backup.js

@@ -37,7 +37,39 @@ const BACKUP_SCRIPT = process.env.GDS_BACKUP_SCRIPT
 // In-memory guard: true while a trigger-initiated dump is running.
 let triggerRunning = false;
 
-function latestDump() {
+// A dump older than this counts as STALE. The nightly timer fires daily, so 36h
+// allows one missed run plus slack before we call it broken.
+const STALE_AFTER_HOURS = Number(process.env.GDS_BACKUP_STALE_HOURS) || 36;
+
+// parseDumpTimestamp — the dump filename stamp `YYYY-MM-DDTHHMMSSZ` is ALMOST
+// ISO-8601 but omits the time separators, so Date.parse rejects it. Re-insert
+// the colons and parse. Returns epoch ms, or null if it doesn't match.
+// Pure + exported so tests can pin it without touching the filesystem.
+function parseDumpTimestamp(stamp) {
+  const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(String(stamp || ''));
+  if (!m) return null;
+  const ms = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}Z`);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+// dumpAgeHours — hours between a dump stamp and now. null when unparseable, so
+// callers can tell "cannot tell" apart from "fresh". Pure (now is injectable).
+function dumpAgeHours(stamp, nowMs = Date.now()) {
+  const ms = parseDumpTimestamp(stamp);
+  if (ms === null) return null;
+  return Math.max(0, (nowMs - ms) / 3_600_000);
+}
+
+// isStaleDump — fail LOUD on an unreadable/absent stamp. A dump we cannot date
+// must not read as healthy: that silence is exactly how the cloudbongos nightly
+// sat failed for 13 days (2026-07-15 → 07-28) with nothing noticing (1002479).
+function isStaleDump(stamp, nowMs = Date.now(), staleAfterHours = STALE_AFTER_HOURS) {
+  const age = dumpAgeHours(stamp, nowMs);
+  if (age === null) return true;
+  return age > staleAfterHours;
+}
+
+function latestDump(nowMs = Date.now()) {
   let files;
   try {
     files = fs.readdirSync(BACKUP_DIR);
@@ -54,7 +86,18 @@ function latestDump() {
   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 };
+  const age = dumpAgeHours(ts, nowMs);
+  return {
+    filename: name,
+    timestamp: ts,
+    size_bytes,
+    count: dumps.length,
+    // Staleness is reported, not just implied by the timestamp, so a consumer
+    // (CLI, dashboard, alert) can act on one boolean instead of re-deriving it.
+    age_hours: age === null ? null : Math.round(age * 10) / 10,
+    stale: isStaleDump(ts, nowMs),
+    stale_after_hours: STALE_AFTER_HOURS,
+  };
 }
 
 module.exports = function buildBackupRouter() {
@@ -68,6 +111,11 @@ module.exports = function buildBackupRouter() {
         backup_dir: BACKUP_DIR,
         db_name: DB_NAME,
         latest_dump: dump,
+        // Top-level too, so a consumer gets a health signal WITHOUT having to
+        // special-case latest_dump===null. No dump at all is the worst state,
+        // not a neutral one, so it reports stale.
+        stale: dump ? dump.stale : true,
+        age_hours: dump ? dump.age_hours : null,
         trigger_running: triggerRunning,
       });
     }));
@@ -102,3 +150,11 @@ module.exports = function buildBackupRouter() {
 
   return router;
 };
+
+// Pure helpers exported for tests (tests/backup_cli.mjs) — importing the real
+// implementations beats re-implementing them in the test, which is how a test
+// can pass while the shipped code is wrong.
+module.exports.parseDumpTimestamp = parseDumpTimestamp;
+module.exports.dumpAgeHours = dumpAgeHours;
+module.exports.isStaleDump = isStaleDump;
+module.exports.STALE_AFTER_HOURS = STALE_AFTER_HOURS;

package/src/bongos/routes/me.js

@@ -83,7 +83,7 @@ module.exports = function buildMeRouter() {
     const [
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
-      behaviorPrefs, geminiKeyRow,
+      behaviorPrefs, geminiKeyRow, needsRebaseTasks,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -136,6 +136,14 @@ module.exports = function buildMeRouter() {
       // Own Gemini-key status via the art-pipeline port (ADR 0102) — the storage
       // is art-pipeline domain now; degrades to a no-key shape on a vanilla instance.
       seams.resolveOptional('art.getBuilderGeminiKeyRow', async () => ({ enc: null, last4: null, set_at: null }))(req.builder.id),
+      // ADR 0120 part 5: the confirmed tasks this builder owes a rebase on —
+      // un-landed confirmed work the publish-reconciler flagged needs_rebase
+      // (part 2). It GATES new claims (part 3: claimTask refuses REBASE_REQUIRED)
+      // and its per-task reward now lands only on ship (part 1), so the CLI
+      // (/builder-start) + the hall surface an owed-rebase warning from this
+      // without a follow-up call. Through the `lifecycle` port; [] on a
+      // lifecycle-less instance (guarded — the port is resolveOptional).
+      lc() ? lc().needsRebaseTasksForBuilder(req.builder.id) : [],
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -148,6 +156,18 @@ module.exports = function buildMeRouter() {
     } catch (err) {
       console.error('[gds] GET /me cost status', err);
     }
+    // Best-effort read of the resolved reward policy (see the payload note).
+    // Never break the profile over a display concern — null degrades the CLI to
+    // its own paying default rather than a wrong "not paid" claim.
+    const rewardPolicySafe = () => {
+      try {
+        const p = typeof reward.rewardConfig === 'function' ? reward.rewardConfig() : null;
+        return p && typeof p.mode === 'string' ? { mode: p.mode, perTaskCredit: p.perTaskCredit !== false } : null;
+      } catch (err) {
+        console.error('[gds] GET /me reward policy', err);
+        return null;
+      }
+    };
     // For each active claim, compute the streak preview (cheap; pool query).
     // Lets the CLI render "shipping this would extend streak to N days" hints.
     const activeClaimsWithPreview = await Promise.all(
@@ -161,6 +181,20 @@ module.exports = function buildMeRouter() {
       active_claims: activeClaimsWithPreview,
       // Legacy field — first claim only. Prefer active_claims (plural).
       active_claim: activeClaimsWithPreview[0] ?? null,
+      // ADR 0120 part 5: un-landed confirmed tasks this builder owes a rebase on.
+      // Each row: { id, title, needs_rebase_reason, needs_rebase_at }, oldest
+      // first. Empty when none owed (or on a lifecycle-less instance). These GATE
+      // new claims (part 3) and their reward is pending until they land on ship
+      // (part 1); the CLI + hall render a warning off this array.
+      needs_rebase_tasks: needsRebaseTasks,
+      // ADR 0146 / task 1002469: the instance's RESOLVED reward policy, so the
+      // CLI can label a task's advertised `credits_reward` honestly. On a
+      // `cost-plus-only` instance that estimate is never paid, and a builder who
+      // isn't told reads a correct `+0` at ship as a broken payout. It must come
+      // from the SERVER — the instance's branding.json is not in the builder's
+      // checkout, so a laptop reading local config always sees the default.
+      // Resolved by economy (never re-derived); null if economy is disabled.
+      reward: rewardPolicySafe(),
       est_vs_actual: estVsActual,
       unlocked,
       locked_with_progress: lockedWithProgress,

package/src/bongos/serve-internal.js

@@ -47,7 +47,7 @@ const { buildBongosDownloads } = require('../bongos-downloads');
 const { clientBranding, branding } = require('../branding');
 const { clientModules, isModuleEnabled } = require('../modules');
 const { hallWidgetScripts, moduleWebSurfaces } = require('../module-loader/loader');
-const { resolveCoreRoot } = require('../instance-config');
+const { resolveCoreRoot, resolveDocsRoot, resolveInstanceRoot } = require('../instance-config');
 const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_API_PREFIXES } = require('./api-prefix');
 
 // ADR 0108 §1: every use of ROOT below (infra/ installers, modules/, docs/) is
@@ -56,15 +56,28 @@ const { API_PREFIX, LEGACY_API_PREFIXES, API_VERSION, VERSIONED_API_PREFIX, ALL_
 const ROOT = resolveCoreRoot();
 
 // Instance-only RELEASE config (config/devbox-app.json, config/bongos-cli.json) is
-// boundary-excluded from the portable core (publish-manifest INSTANCE_EXCLUDE), so a
-// vanilla self-host boot ships without it. Requiring it hard used to CRASH the boot
-// (task 1824). Guard the require so an absent config makes its download surface simply
-// not mount (fail-to-vanilla, like branding/modules) rather than take the server down.
-// A malformed config (JSON parse error, etc.) still throws — only a MISSING file is
-// tolerated. A branded instance that ships the config gets the routes exactly as before.
-function tryRequireConfig(relPath) {
-  try { return require(relPath); }
-  catch (e) { if (e && e.code === 'MODULE_NOT_FOUND') return null; throw e; }
+// boundary-excluded from the portable core (publish-manifest INSTANCE_EXCLUDE), so it is
+// HOST content: it lives at the INSTANCE root, which on a vendored instance is NOT the
+// package dir this file sits under. A core-relative require therefore looked in
+// node_modules/@bongos/core/config/ and never found it, so /downloads/* silently failed
+// to mount (task 1002371 — same class as ADR 0144's vendored infra/ path bug; ADR 0145's
+// copy-the-config-into-node_modules workaround is lost on the next `npm ci`). So resolve
+// the instance root FIRST — the branding/modules resolution (src/branding.js INSTANCE_PATH)
+// — then the core package dir, which keeps a single checkout (and that copied-in
+// workaround) byte-identical.
+//
+// Fail-soft is preserved verbatim: an ABSENT config makes its download surface simply not
+// mount (fail-to-vanilla, like branding/modules) rather than crash the boot as the original
+// hard require did (task 1824); a MALFORMED config still throws — only a MISSING file is
+// tolerated. `roots` is injected so the ladder is unit-testable with zero ambient state.
+function tryLoadInstanceConfig(name, roots = [resolveInstanceRoot(), ROOT]) {
+  for (const root of new Set(roots)) {
+    let raw;
+    try { raw = fs.readFileSync(path.join(root, 'config', name), 'utf8'); }
+    catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+    return JSON.parse(raw);
+  }
+  return null;
 }
 
 // Map the pack's camelCase theme color keys → the kebab-case CSS custom
@@ -193,6 +206,60 @@ function docsIndexHtml() {
   return _docsHtml;
 }
 
+// The OpenAPI 3.1 spec served at /docs/openapi.json — SELF-HEALING (task 1002200).
+// The Redoc page (public-docs/) ships as static assets, but the SPEC is a generated
+// artifact whose on-disk copy is NOT guaranteed at every deploy topology, so a bare
+// res.sendFile(one fixed path) 404s exactly when the file is missing:
+//   • Standalone instance (ADR 0108/0140): the route resolves from the CORE package
+//     (resolveCoreRoot → node_modules/@bongos/core) while the generator writes the
+//     INSTANCE's own spec to resolveDocsRoot (the instance repo) — a path mismatch.
+//   • A pinned @bongos/core that predates the spec's packaging ships NO copy at all
+//     (the observed cloudbongos.com 404: public-docs/ shipped, docs/api/ didn't).
+//   • A fresh instance, before its first generate, has neither.
+// So resolve the spec in tiers: (1) the committed spec at resolveDocsRoot() (the
+// instance's own — carries its module routes), then (2) at resolveCoreRoot() (the
+// core-package copy), then (3) GENERATE it in-process from the live route source.
+// gen-api-docs.build() reads routes from resolveCoreRoot() (always present — it IS
+// the running code), is DB-free + express-free (a pure line+regex extractor that
+// never executes a route or opens a connection), and yields the identical spec.
+// resolveOpenapiJson is the pure, injectable core so the fallback ladder is unit-
+// testable (tests/docs_openapi_route.mjs).
+function resolveOpenapiJson({ candidates = [], generate } = {}) {
+  for (const p of candidates) {
+    let raw;
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; } // absent → next tier
+    try { JSON.parse(raw); } catch { continue; }                  // corrupt → next tier
+    return raw;
+  }
+  if (typeof generate === 'function') {
+    try {
+      const out = generate();
+      if (out) return out;
+    } catch (e) {
+      console.error('[docs] in-process OpenAPI generation failed:', e && e.message);
+    }
+  }
+  return '';
+}
+
+// Memoized like docsIndexHtml: one resolve per process; a redeploy restarts and
+// re-resolves. '' (→ the route falls through to 404) only if every tier fails.
+let _openapiJson;
+function openapiJson() {
+  if (_openapiJson !== undefined) return _openapiJson;
+  const roots = [...new Set([resolveDocsRoot(), ROOT])]; // instance repo first, then core pkg
+  _openapiJson = resolveOpenapiJson({
+    candidates: roots.map((r) => path.join(r, 'docs/api/openapi.json')),
+    generate() {
+      // Lazy require: boot never pays for it, and a generator hiccup is contained
+      // to this one endpoint rather than taking down server start.
+      const gen = require('../../scripts/gds/gen-api-docs.js');
+      return JSON.stringify(gen.build().spec, null, 2) + '\n';
+    },
+  });
+  return _openapiJson;
+}
+
 // The browser-global build of the generated typed client (task 1996 / R09),
 // served at /lib/bongos-client.js so classic <script> web pages can consume the
 // same generated client the CLI uses (window.BongosClient). Read once at boot
@@ -408,7 +475,7 @@ function mountInternalSurfaces(app) {
   // builders.<apex> (the builders rewrite shim below only prefixes non-/api
   // paths, so without this placement /downloads/* would be rewritten to
   // /builders/downloads/* and 404).
-  const devboxCfg = tryRequireConfig('../../config/devbox-app.json');
+  const devboxCfg = tryLoadInstanceConfig('devbox-app.json');
   if (devboxCfg) {
     const devboxDownloads = buildDevboxDownloads(devboxCfg);
     app.get('/downloads/devbox/latest.json', (_req, res) => {
@@ -439,7 +506,7 @@ function mountInternalSurfaces(app) {
   // every user-facing URL on the apex. The installer scripts are served with the
   // server's PINNED origin substituted for __GDS_API_BASE__ — never a request
   // header, so a spoofed Host can't redirect a `curl | sh` (the box-connect.sh rule).
-  const bongosCfg = tryRequireConfig('../../config/bongos-cli.json');
+  const bongosCfg = tryLoadInstanceConfig('bongos-cli.json');
   if (bongosCfg) {
     const bongosDownloads = buildBongosDownloads(bongosCfg);
     // Pinned public origin for the served installer scripts (never a request header —
@@ -847,7 +914,7 @@ function mountInternalSurfaces(app) {
   // external fetch (matches the /vendor/* self-hosting convention; CSP-safe).
   //   GET /docs                    → the Redoc host page (branding-injected)
   //   GET /docs/redoc.standalone.js → the vendored renderer (long-cached)
-  //   GET /docs/openapi.json        → the generated spec (CORS-open so Postman/Swagger/AI can fetch it)
+  //   GET /docs/openapi.json        → the spec, SELF-HEALING (committed → generated), CORS-open so Postman/Swagger/AI can fetch it; see openapiJson()
   app.get('/docs', (req, res, next) => {
     if (isModuleSurfaceHost(req)) return next();
     const html = docsIndexHtml();
@@ -864,10 +931,12 @@ function mountInternalSurfaces(app) {
   });
   app.get('/docs/openapi.json', (req, res, next) => {
     if (isModuleSurfaceHost(req)) return next();
+    const json = openapiJson();
+    if (!json) return next(); // no committed spec + generation failed → fall through to 404
     res.set('Access-Control-Allow-Origin', '*'); // read-only spec — tools fetch it cross-origin
     res.set('Cache-Control', 'public, max-age=60');
     res.type('application/json');
-    res.sendFile(path.join(ROOT, 'docs/api/openapi.json'));
+    res.send(json);
   });
 
   app.use((req, res, next) => {
@@ -895,4 +964,4 @@ function mountInternalSurfaces(app) {
   return app;
 }
 
-module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens };
+module.exports = { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal, injectBrandingInto, injectModuleHallWidgets, themeMarkup, applyBrandTokens, resolveOpenapiJson, openapiJson, tryLoadInstanceConfig };

package/src/branding.js

@@ -49,6 +49,11 @@ const ENV_OVERRIDES = [
   // idp:false), so a co-tenant instance sharing the neutral pack still federates
   // individually. 'bool'-coerced below — auth.js idpEnabled() reads it as strict === true.
   ['AUTH_IDP', ['auth', 'idp'], 'bool'],
+  // Post-sign-in landing when no ?return=/Referer was carried (auth.js
+  // postLoginLanding). Env-overridable so a platform-home instance can flip its
+  // front door with one env var and no instance branding.json — cloudbongos.com
+  // sets <PREFIX>_POST_LOGIN_LANDING=/gate/ (the orbs). Task 1002240.
+  ['POST_LOGIN_LANDING', ['landing', 'postLogin']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -192,7 +197,34 @@ function clientBranding(b = branding()) {
       notFound: b.copy?.notFound || 'Page not found.',
     },
     rankLabels: b.rankLabels || {},
+    reward: clientReward(),
   };
 }
 
+// The RESOLVED reward policy, projected client-safe (ADR 0146 follow-up, task
+// 1002469). Display surfaces need to know which streams this instance actually
+// pays — on a `cost-plus-only` instance the per-task "Est." is a guide, never a
+// payout, and a builder who is not told that reads a correct `+0` as a bug.
+//
+// Resolved through the economy module's `reward` port, NOT re-derived here: the
+// mode→perTaskCredit mapping is economy's to own (ADR 0146 put the knob inside
+// the module deliberately). `module-seams` is a dependency-free leaf, so this
+// adds no boot-order coupling to the config layer.
+//
+// Fail-safe: an instance with economy disabled, or a resolve that throws, falls
+// back to the ADR 0146 DEFAULT (pay both streams) — the same direction the pure
+// resolver takes an unknown mode, so a hiccup can never silently tell builders
+// their per-task reward is withheld.
+function clientReward() {
+  const fallback = { mode: 'cost-plus-and-estimate', perTaskCredit: true };
+  try {
+    const reward = require('./module-seams').resolveOptional('reward');
+    const p = reward && typeof reward.rewardConfig === 'function' ? reward.rewardConfig() : null;
+    if (!p || typeof p.mode !== 'string') return fallback;
+    return { mode: p.mode, perTaskCredit: p.perTaskCredit !== false };
+  } catch (_) {
+    return fallback;
+  }
+}
+
 module.exports = { resolveBranding, loadBranding, deepMerge, branding, clientBranding, userAgent, NEUTRAL_PATH, INSTANCE_PATH };