@bongos/core 1.19.654 → 1.19.656

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

@@ -96,7 +96,19 @@
       throw { kind: '401' };
     }
     if (res.status === 403) {
-      throw { kind: '403' };
+      // Carry the FLOOR the server actually enforced. requirePermission puts
+      // `details.floors` (permission key → catalog floor rank) on every denial
+      // for exactly this purpose — see its comment in src/bongos/auth.js, which
+      // names hardcoded prose as the failure shape ADR 0157 left behind. This
+      // page WAS that shape: every panel said "Archons only" while its route had
+      // long since moved to a metic-floored atom.
+      //
+      // One distinct floor is the panel's floor. A multi-atom gate that denies on
+      // keys with DIFFERENT floors has no single honest answer, so the panel names
+      // none rather than picking one — the same fail-quiet the old copy did not do.
+      const details = res.data && res.data.error && res.data.error.details;
+      const ranks = details && details.floors ? [...new Set(Object.values(details.floors))] : [];
+      throw { kind: '403', floor: ranks.length === 1 ? ranks[0] : null };
     }
     if (!res.ok) throw new Error(`${path} → ${res.status}`);
     return res.data;
@@ -152,13 +164,25 @@
   // `sealedMsg`; any other failure logs `[watch] <name> failed` and shows `errMsg`.
   // NOTE: loadMarks is the deliberate outlier — its failure state is a plain
   // "empty" message, not "unavailable", so it keeps its own try/catch.
+  // sealedText — name the floor the DENIAL reported, never one written here.
+  // Each `sealedMsg` below is the SUBJECT clause only ("The roster is not visible
+  // at your rank."); the rank sentence in front of it is composed from the 403.
+  // That is what keeps this page from telling a builder a permission model the
+  // server stopped implementing, which is the whole of task 1003449 — and why the
+  // floor is not merely corrected to 'metic' here: a hardcoded 'metic' is the same
+  // defect one ADR later. Label via rankLabel so an instance that renames its
+  // ranks reads its own words (ADR 0157).
+  function sealedText(floor, subject) {
+    return floor ? `${rankLabel(floor)} and up. ${subject}` : subject;
+  }
+
   async function section(target, fetcher, render, { sealedMsg, errMsg, name }) {
     if (!target) return;
     try {
       render(await fetcher(), target);
     } catch (err) {
       if (err && err.kind === '401') return;
-      if (err && err.kind === '403') { renderUnavailable(target, sealedMsg); return; }
+      if (err && err.kind === '403') { renderUnavailable(target, sealedText(err.floor, sealedMsg)); return; }
       console.error(`[watch] ${name} failed`, err);
       renderUnavailable(target, errMsg);
     }
@@ -499,7 +523,7 @@
 
   function loadGate() {
     return section($('#gate-body'), () => fetchJson(`/access-requests?status=${encodeURIComponent(gateView)}`), renderGate, {
-      sealedMsg: 'Archons only. Access requests are not visible at your rank.',
+      sealedMsg: 'Access requests are not visible at your rank.',
       errMsg: 'Could not load access requests.',
       name: 'gate',
     });
@@ -554,7 +578,7 @@
 
   function loadReports() {
     return section($('#reports-body'), () => fetchJson('/security/reports'), renderReports, {
-      sealedMsg: 'Archons only. Security reports are not visible at your rank.',
+      sealedMsg: 'Security reports are not visible at your rank.',
       errMsg: 'Could not load the security reports.',
       name: 'reports',
     });
@@ -621,7 +645,7 @@
 
   function loadEngagementDocs() {
     return section($('#engagement-docs-body'), () => fetchJson('/security/docs'), renderEngagementDocs, {
-      sealedMsg: 'Archons only. Engagement reports are not visible at your rank.',
+      sealedMsg: 'Engagement reports are not visible at your rank.',
       errMsg: 'Could not load the engagement reports.',
       name: 'engagement docs',
     });
@@ -667,7 +691,7 @@
 
   function loadOverrides() {
     return section($('#overrides-body'), () => fetchJson('/override-requests?status=open'), renderOverrides, {
-      sealedMsg: 'Archons only. The override queue is not visible at your rank.',
+      sealedMsg: 'The override queue is not visible at your rank.',
       errMsg: 'Could not load the override queue.',
       name: 'overrides',
     });
@@ -706,7 +730,7 @@
 
   function loadAudit() {
     return section($('#audit-body'), () => fetchJson('/audit-log?limit=50'), renderAudit, {
-      sealedMsg: 'Archons only. The audit log is not visible at your rank.',
+      sealedMsg: 'The audit log is not visible at your rank.',
       errMsg: 'Could not load the audit log.',
       name: 'audit',
     });
@@ -826,7 +850,7 @@
 
   function loadRoster() {
     return section($('#roster-body'), () => fetchJson('/builders/roster'), renderRoster, {
-      sealedMsg: 'Archons only. The roster is not visible at your rank.',
+      sealedMsg: 'The roster is not visible at your rank.',
       errMsg: 'Could not load the roster.',
       name: 'roster',
     });
@@ -861,7 +885,7 @@
 
   function loadBoxCosts() {
     return section($('#box-costs-body'), () => fetchJson('/boxes/cost-ledger?limit=100'), renderBoxCosts, {
-      sealedMsg: 'Archons only. The cost ledger is not visible at your rank.',
+      sealedMsg: 'The cost ledger is not visible at your rank.',
       errMsg: 'Could not load the dev-box cost ledger.',
       name: 'box costs',
     });
@@ -908,7 +932,7 @@
       if (data.window_days) target.insertAdjacentHTML('beforeend', foot(`Window: last ${escapeHtml(data.window_days)} days.`));
     } catch (err) {
       if (err && err.kind === '401') return;
-      if (err && err.kind === '403') { renderUnavailable(target, 'Archons only. Review data is not visible at your rank.'); return; }
+      if (err && err.kind === '403') { renderUnavailable(target, sealedText(err.floor, 'Review data is not visible at your rank.')); return; }
       // 404 / not-yet-built / any other failure → graceful empty state.
       console.error('[watch] marks-by-builder failed', err);
       target.innerHTML = emptyStateHtml('No reviews recorded in this window.');
@@ -964,7 +988,7 @@
 
   function loadMasonMarks() {
     return section($('#mason-marks-stats'), () => fetchJson('/public/grades?days=7'), renderMasonMarks, {
-      sealedMsg: 'Archons only. Review quality data is not visible at your rank.',
+      sealedMsg: 'Review quality data is not visible at your rank.',
       errMsg: 'Could not load review quality data.',
       name: 'public grades',
     });
@@ -999,7 +1023,7 @@
 
   function loadSurveyor() {
     return section($('#surveyor-stats'), () => fetchJson('/public/estimation-drift'), renderSurveyor, {
-      sealedMsg: 'Archons only. Estimation data is not visible at your rank.',
+      sealedMsg: 'Estimation data is not visible at your rank.',
       errMsg: 'Could not load estimation data.',
       name: 'estimation drift',
     });
@@ -1177,7 +1201,7 @@
 
   function loadLedger() {
     return section($('#ledger-stats'), () => fetchJson('/public/repo-health?days=30'), renderLedger, {
-      sealedMsg: 'Archons only. Repo health data is not visible at your rank.',
+      sealedMsg: 'Repo health data is not visible at your rank.',
       errMsg: 'Could not load repo health data.',
       name: 'repo health',
     });
@@ -1227,7 +1251,7 @@
 
   function loadSessions() {
     return section($('#sessions-stats'), () => fetchJson('/sessions/search?order=recent&limit=5'), renderSessions, {
-      sealedMsg: 'Archons only. Session data is not visible at your rank.',
+      sealedMsg: 'Session data is not visible at your rank.',
       errMsg: 'Could not load the session tally.',
       name: 'sessions tally',
     });

package/modules/lifecycle/db-rank-authz.js

@@ -80,15 +80,33 @@ function xenosClaimAllowed(rank, newcomerFriendly) {
 
 // claimPermissionsFor — the builder's effective permission set for the claim
 // decision, read through the `governance` kernel PORT (never by importing the
-// module — the one-way rule, ADR 0083). Returns a Set, or NULL when authority
-// cannot be ESTABLISHED, which claimEligibilityAllows reads as "fall back to the
-// incumbent rank rule":
-//   • the governance module is not mounted (no port), or the resolver throws;
-//   • the builder resolves to ZERO permissions — i.e. they hold no role row.
-//     governance_002's backfill is run-once and nothing yet re-assigns a rank-role
-//     when a builder is created or re-ranked, so this is a live gap, not a theory.
-// Every seeded rank-role grants at least twelve permissions, so an empty set never
-// means "a real role that grants nothing" today.
+// module — the one-way rule, ADR 0083).
+//
+// NULL means authority could not be ESTABLISHED, which claimEligibilityAllows
+// reads as "fall back to the incumbent rank rule". Exactly two things mean that:
+//   • the governance module is not mounted (no port), so there is no authority
+//     system to ask;
+//   • the resolver threw, so the answer is unknown rather than empty.
+//
+// AN EMPTY SET IS AN ANSWER, NOT A FAILURE (task 1003816). It used to be folded
+// into the null above, on the stated grounds that governance_002's backfill was
+// run-once and nothing re-assigned a rank-role afterwards — so a builder holding
+// no role row was a live gap rather than a real verdict. That is no longer true,
+// and the three writes that closed it are all shipped:
+//   • BV1.R95b rotates the role inside the rank-change transaction, and syncs it
+//     on every sign-in (src/bongos/auth-admission.js safeSyncRankRole);
+//   • task 1003193 rotates it in-tx on offboard AND reactivation;
+//   • governance_005 repaired the rows already written.
+// governance_005 states the intended reading in as many words — a builder with no
+// role row "resolves to the empty set (denied everywhere)" — and
+// syncGovernanceRankRole calls that same outcome "the fail-closed answer". Folding
+// it back into the rank rule is what stopped those three from being true at the
+// claim gate, so the empty set now flows through as a real deny.
+//
+// The residual way to hold no role row is the sign-in sync failing transiently
+// (it is deliberately best-effort so a governance hiccup cannot block a sign-in).
+// Denying the claim is the correct read of that state, and it self-repairs on the
+// next successful sign-in.
 //
 // Called BEFORE the claim transaction opens: authority is a per-request read (ADR
 // 0016 — resolved server-side, uncached), and taking a second pool connection while
@@ -98,7 +116,9 @@ async function claimPermissionsFor(builderId) {
   if (!governance || typeof governance.resolveBuilderPermissions !== 'function') return null;
   try {
     const keys = await governance.resolveBuilderPermissions(builderId);
-    if (!keys || keys.length === 0) return null;
+    // A non-array is a broken port contract, not a verdict — resolveBuilderPermissions
+    // always returns an array. Treat it as "could not establish", never as "denied".
+    if (!Array.isArray(keys)) return null;
     return new Set(keys);
   } catch (err) {
     console.error('[gds] claim eligibility: permission resolve failed, falling back to the rank rule', err);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.654",
+  "version": "1.19.656",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.654",
+      "version": "1.19.656",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.654",
+  "version": "1.19.656",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/box.js

@@ -312,7 +312,7 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
   // session-file fallback (box-source-fetch.sh, out-of-repo on the control-plane
   // — see the cross-repo blocker filed alongside this fix). Baking it explicitly
   // closes that gap for every future box regardless of which script forgets it.
-  const apiOrigin = process.env.GDS_PUBLIC_ORIGIN || instanceConfig.defaultApiBase();
+  const apiOrigin = instanceConfig.resolveEnv('PUBLIC_ORIGIN') || instanceConfig.defaultApiBase();
   let boxEnv = buildBoxEnv({ apiOrigin });
   let terminalHostname = null;
   let terminalCredential = null;
@@ -380,7 +380,7 @@ async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
     // operator's own CLI session happens to be signed into right now — the two can
     // differ (an operator provisioning boxes across instances) and the box must
     // still call home to itself, not to the operator's other login.
-    api_base: process.env.GDS_PUBLIC_ORIGIN || instanceConfig.defaultApiBase(),
+    api_base: instanceConfig.resolveEnv('PUBLIC_ORIGIN') || instanceConfig.defaultApiBase(),
   }, null, 2);
 
   const doApi = makeDo(apply);
@@ -1204,7 +1204,7 @@ async function cmdStatus(pool, boxes) {
 
 let APPLY = false;
 function actorTag() {
-  const who = process.env.GDS_ACTOR || process.env.USER || 'cli';
+  const who = instanceConfig.resolveEnv('ACTOR') || process.env.USER || 'cli';
   return `cli:${who}`;
 }
 function fail(msg) { console.error(`✖ ${msg}`); return { ok: false, error: msg }; }

package/scripts/gds/claude-materialize.js

@@ -121,7 +121,7 @@ function buildRebrandRules(from = {}, to = {}) {
   add(`.config/${fc}`, `.config/${tc}`);
   add(`/etc/${fc}`, `/etc/${tc}`);
   add(`[${fc}]`, `[${tc}]`);
-  // The instance env-var prefix (e.g. OTB_ → CLOUDBONGOS_), bounded by its underscore.
+  // The instance env-var prefix (e.g. OTB_ → BONGOS_), bounded by its underscore.
   add(`${effEnvPrefix(from)}_`, `${effEnvPrefix(to)}_`);
   // task 1002672: the bare User-Agent brand token (e.g. `amazonprimea-gds-cli/1.0`
   // in a hook's outbound fetch). It carries no TLD, so none of the HOST rules above

package/scripts/gds/init.js

@@ -73,7 +73,7 @@ const path = require('node:path');
 const readline = require('node:readline');
 const { apiCall, arg, hasFlag } = require('./cli-lib');
 const { DEFAULT_HIERARCHY } = require('../../src/bongos/hierarchy-config');
-const { resolveCoreRoot } = require('../../src/instance-config'); // ADR 0108 §1: where the core package lives
+const { resolveCoreRoot, FALLBACK_ENV_PREFIX } = require('../../src/instance-config'); // ADR 0108 §1: where the core package lives
 const { materializeClaude } = require('./claude-materialize'); // ADR 0108 §3 (W3): copy .claude/ into the instance
 const { detectStack, formatStackSummary } = require('./adopt-detect'); // ADR 0121 §Decision 4 (task 2043): inspect an existing repo before layering
 const { resolveBacklogTasks, DEFAULT_MAX: BACKLOG_MAX } = require('./adopt-import'); // ADR 0121 §Decision 3 (task 2044): import an existing backlog
@@ -250,7 +250,7 @@ function buildBrandingConfig(spec) {
     repo: { owner: spec.repo.owner, name: spec.repo.name },
     firstAdmin: spec.firstAdmin,
     currency: { label: (spec.currency && spec.currency.label) || 'credits', symbol: (spec.currency && spec.currency.symbol) || '' },
-    envPrefix: spec.envPrefix || 'CLOUDBONGOS',
+    envPrefix: spec.envPrefix || FALLBACK_ENV_PREFIX,
     // Every instance gets its OWN session/config dir (task 1002626). Without
     // this, instance-config.js falls back to the shared 'cloudbongos' dir, so
     // every un-branded instance on a machine reads/writes the SAME

package/scripts/gds/module.js

@@ -93,8 +93,9 @@ function readJson(p) {
 }
 
 function envPrefix() {
-  try { return require('../../src/branding').branding().envPrefix || 'CLOUDBONGOS'; }
-  catch { return 'CLOUDBONGOS'; }
+  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
+  try { return require('../../src/branding').branding().envPrefix || FALLBACK_ENV_PREFIX; }
+  catch { return FALLBACK_ENV_PREFIX; }
 }
 
 // ---------------------------------------------------------------------------

package/scripts/gds/oauth-secret.js

@@ -59,12 +59,15 @@ function validateClientId(id) {
 
 // The env-var prefix the provisioned instance resolves (the neutral pack's envPrefix,
 // mirroring provision.js provisionedEnvPrefix — the creds MUST be written under this
-// prefix or src/branding + auth never read them, task 1972). Fail-soft to CLOUDBONGOS.
+// prefix or src/branding + auth never read them, task 1972). Fail-soft to the
+// core's own FALLBACK_ENV_PREFIX so this cannot drift from the pack again — it
+// was a hardcoded 'CLOUDBONGOS' until task 1003703 made BONGOS canonical.
 function provisionedEnvPrefix() {
+  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
   try {
     const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
-    return pack.envPrefix || 'CLOUDBONGOS';
-  } catch { return 'CLOUDBONGOS'; }
+    return pack.envPrefix || FALLBACK_ENV_PREFIX;
+  } catch { return FALLBACK_ENV_PREFIX; }
 }
 
 function webEnvPath(slug, { etcBase = ETC_BASE } = {}) {

package/scripts/gds/provision-units.js

@@ -152,10 +152,11 @@ const ENV_PREFIX_PACK = 'config/branding.neutral.json';
 // was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
 // the OAuth creds were silently unreadable — task 1972.)
 function provisionedEnvPrefix() {
+  const { FALLBACK_ENV_PREFIX } = require('../../src/instance-config');
   try {
     const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, ENV_PREFIX_PACK), 'utf8'));
-    return pack.envPrefix || 'CLOUDBONGOS';
-  } catch { return 'CLOUDBONGOS'; }
+    return pack.envPrefix || FALLBACK_ENV_PREFIX;
+  } catch { return FALLBACK_ENV_PREFIX; }
 }
 
 // The per-instance secrets file body (the standup runbook's /etc/<inst>/web.env).

package/scripts/gds/seed-bongos-coreB-tranche1-tasks.js

@@ -7,7 +7,7 @@
 // Run: node scripts/gds/seed-bongos-coreB-tranche1-tasks.js
 const os = require('os');
 const TOKEN = require(os.homedir() + '/.config/otb/gds-session.json').token;
-const BASE = process.env.GDS_BASE || 'https://amazonprimea.com';
+const BASE = require('../../src/instance-config').resolveEnv('BASE') || 'https://amazonprimea.com';
 const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
 
 // ref → task spec. depends_on_refs are local R## refs resolved after create.

package/scripts/gds/seed-bongos-coreB-tranche2-tasks.js

@@ -9,7 +9,7 @@
 // Run: node scripts/gds/seed-bongos-coreB-tranche2-tasks.js
 const os = require('os');
 const TOKEN = require(os.homedir() + '/.config/otb/gds-session.json').token;
-const BASE = process.env.GDS_BASE || 'https://amazonprimea.com';
+const BASE = require('../../src/instance-config').resolveEnv('BASE') || 'https://amazonprimea.com';
 const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
 
 // ref → task spec. deps are local R## refs resolved after create. Clean-slicing

package/scripts/gds/seed-provisioning-tasks.js

@@ -7,7 +7,7 @@
 // Run: node scripts/gds/seed-provisioning-tasks.js
 const os = require('os');
 const TOKEN = require(os.homedir() + '/.config/otb/gds-session.json').token;
-const BASE = process.env.GDS_BASE || 'https://amazonprimea.com';
+const BASE = require('../../src/instance-config').resolveEnv('BASE') || 'https://amazonprimea.com';
 const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
 const GOAL = 26; // Cloud Bongos productization and self-host
 

package/scripts/gds/status.js

@@ -20,12 +20,13 @@
 // Exit codes: 0 ok · 1 network/api error · 2 bad invocation · 3 not found.
 
 const { API_BASE, cliClient, assertInstanceMatch } = require('./cli-lib');
+const { resolveEnv } = require('../../src/instance-config');
 
-// The active internal version; override with GDS_STATUS_DEFAULT_VERSION (or pass
+// The active internal version; override with <PREFIX>_STATUS_DEFAULT_VERSION (or pass
 // --version). Bumped GDS-V4 → BONGOS-V1 (task 1709, ADR 0103): GDS-V4 was
 // consolidated into BONGOS-V1 (the Cloud Bongos platform version) and frozen, so
 // the bare `/status` card should default to the live version, not a sealed one.
-const DEFAULT_VERSION = process.env.GDS_STATUS_DEFAULT_VERSION || 'BONGOS-V1';
+const DEFAULT_VERSION = resolveEnv('STATUS_DEFAULT_VERSION') || 'BONGOS-V1';
 
 // Compact, status-first ordering for the "remaining: …" summaries.
 const STATUS_ORDER = ['shipped', 'confirmed', 'completed', 'claimed', 'ready', 'blocked', 'backlog'];

package/scripts/gds/upgrade.js

@@ -358,7 +358,7 @@ function resolveInstanceDb({ instanceDir }, run = spawnSync) {
   const r = run(process.execPath, ['-e', "process.stdout.write(require(process.argv[1]).instanceDbName() || '')", poolPath], {
     cwd: instanceDir,
     encoding: 'utf8',
-    env: { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir },
+    env: { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir },
   });
   if (!r || r.error || r.status !== 0 || typeof r.stdout !== 'string') return { db: null, ran: false };
   return { db: String(r.stdout).trim() || null, ran: true };
@@ -377,7 +377,7 @@ function resolveInstanceDb({ instanceDir }, run = spawnSync) {
 // (fitness `gen-api-docs --check` + the api_client test backstop it on the next ship).
 // Runs AFTER npm install so the generators come from the NEW core.
 function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs) {
-  const env = { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir };
+  const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
   const ran = [];
   for (const gen of ['gen-api-docs.js', 'gen-api-client.js']) {
     const script = path.join(coreRoot, 'scripts', 'gds', gen);
@@ -416,7 +416,7 @@ function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsIm
 //     an upgrade is precisely what destroys them (task 1002441).
 const NAV_WHOLE_FILE_GENERATORS = ['gen-session-index.js'];
 function regenerateNavDocs({ instanceDir, coreRoot, generators = NAV_WHOLE_FILE_GENERATORS }, run = spawnSync, fsImpl = fs) {
-  const env = { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir };
+  const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
   const ran = [];
   const failed = [];
   for (const gen of generators) {

package/scripts/hall-preview/server.js

@@ -66,7 +66,7 @@ const MODULES_ON = String(arg('--modules-on') || '').split(',').map((s) => s.tri
 // and it is the explicit way to preview the signed-out fallback (task 1003315).
 const FIXTURE_ME = process.argv.includes('--fixture-me');
 const BRAND_FILE = arg('--brand') || 'config/branding.neutral.json';
-process.env.GDS_BRANDING_FILE = path.resolve(ROOT, BRAND_FILE);
+process.env.BONGOS_BRANDING_FILE = path.resolve(ROOT, BRAND_FILE);
 
 /* eslint-disable import/no-dynamic-require */
 // express comes from this tree's node_modules when installed, else node's

package/src/bongos/routes/auth.js

@@ -40,6 +40,7 @@ const { pairStore } = require('../app-pair');
 const { publicOrigin, parseCookie, validateOrRespond } = require('./_helpers');
 const { accountExistenceReadRateLimit } = require('../middleware/rate-limit');
 const { branding } = require('../../branding');
+const { resolveEnv } = require('../../instance-config');
 const seams = require('../../module-seams');
 // task 1003208: structured logging — was console.*. A core file logs through
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
@@ -373,14 +374,14 @@ function postLoginLanding(brand) {
 // 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
 // cannot rewrite the redirect and Discord's URI registration is not the SOLE backstop.
-const DISCORD_REDIRECT_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || configuredOAuthOrigin();
+const DISCORD_REDIRECT_ORIGIN = resolveEnv('PUBLIC_ORIGIN') || configuredOAuthOrigin();
 const DISCORD_REDIRECT_URI = `${DISCORD_REDIRECT_ORIGIN}/api/gds/auth/discord/callback`;
 
 // The GitHub web-OAuth redirect_uri origin (#734). PINNED to the canonical
 // public origin (same env knob as Discord), never the request host — GitHub
 // matches redirect_uri against the app's single registered callback host, so a
 // sign-in started on a builders.* subdomain must still use the apex.
-const WEB_REDIRECT_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || configuredOAuthOrigin();
+const WEB_REDIRECT_ORIGIN = resolveEnv('PUBLIC_ORIGIN') || configuredOAuthOrigin();
 
 // The ship-time hub push (task 1002803, ADR 0171 amendment R01) lives here
 // because this file already owns the OTHER trigger: the federated sign-in flows

package/src/bongos/routes/backup.js

@@ -22,19 +22,23 @@ const path = require('node:path');
 const { execFile } = require('node:child_process');
 const auth = require('../auth');
 const { branding } = require('../../branding');
+const { resolveEnv } = require('../../instance-config');
 const { asyncHandler } = require('./_helpers');
 // task 1003208: structured logging — was console.*. A core file logs through
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
 const log = require('../logger').logger.child({ src: 'backup' });
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
-const BACKUP_DIR = process.env.GDS_BACKUP_DIR || '/var/backups/gds';
+// These four knobs are set in the droplet's systemd unit, so they resolve through
+// resolveEnv() — <PREFIX>_BACKUP_* first, then the legacy spellings including the
+// GDS_BACKUP_* the deployed unit still exports (task 1003703).
+const BACKUP_DIR = resolveEnv('BACKUP_DIR') || '/var/backups/gds';
 // The DB name comes from the branding pack (branding.db.database), never a
 // hardcoded host brand (ADR 0062 §3) — a non-OTB instance dumps its own DB.
-const DB_NAME = process.env.GDS_BACKUP_DB
+const DB_NAME = resolveEnv('BACKUP_DB')
   || (() => { try { return branding().db && branding().db.database; } catch { return null; } })()
   || 'gds';
-const BACKUP_SCRIPT = process.env.GDS_BACKUP_SCRIPT
+const BACKUP_SCRIPT = resolveEnv('BACKUP_SCRIPT')
   || path.join(REPO_ROOT, 'scripts', 'gds', 'db-backup-nightly.sh');
 
 // In-memory guard: true while a trigger-initiated dump is running.
@@ -42,7 +46,7 @@ let triggerRunning = false;
 
 // 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;
+const STALE_AFTER_HOURS = Number(resolveEnv('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

package/src/bongos/routes/security.js

@@ -21,6 +21,7 @@ const fs = require('node:fs/promises');
 const auth = require('../auth');
 const db = require('../db');
 const { validateOrRespond } = require('./_helpers');
+const { resolveEnv } = require('../../instance-config');
 
 // Slug shape for security_docs (task 991): lowercase kebab, 1–128 chars. Used to
 // validate POST /security/docs and to safely interpolate :slug into the GET.
@@ -36,7 +37,7 @@ const SECURITY_DOC_CONTENT_MAX = 2_000_000;
 // staging can point at a different file; the recommended prod path is
 // /etc/amazonprimea/security-adr.md (chmod 600, owned by the deploy user).
 function adrPath() {
-  return (process.env.GDS_SECURITY_ADR_PATH || '').trim() || null;
+  return (resolveEnv('SECURITY_ADR_PATH') || '').trim() || null;
 }
 
 // Read the full ADR off disk. Returns { adr_md, source, fetched_at } on

package/src/bongos/serve-internal.js

@@ -51,7 +51,7 @@ const { stealthGate } = require('./stealth-gate');
 const { platformVisibilityGate } = require('./platform-visibility-gate');
 const { clientModules, isModuleEnabled } = require('../modules');
 const { hallWidgetScripts, moduleWebSurfaces } = require('../module-loader/loader');
-const { resolveCoreRoot, resolveDocsRoot, resolveInstanceRoot } = require('../instance-config');
+const { resolveCoreRoot, resolveDocsRoot, resolveInstanceRoot, resolveEnv } = 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
@@ -640,7 +640,7 @@ function mountInternalSurfaces(app) {
     // Pinned public origin for the served installer scripts (never a request header —
     // a spoofed Host can't redirect a `curl | sh`). The fallback comes from the
     // branding pack, not a hardcoded host brand (ADR 0062 §3).
-    const BONGOS_PUBLIC_ORIGIN = process.env.GDS_PUBLIC_ORIGIN || branding().domains.publicOrigin;
+    const BONGOS_PUBLIC_ORIGIN = resolveEnv('PUBLIC_ORIGIN') || branding().domains.publicOrigin;
     const readBongosInstallScript = (name) => {
       try {
         return fs.readFileSync(path.join(ROOT, 'infra', name), 'utf8').split('__GDS_API_BASE__').join(BONGOS_PUBLIC_ORIGIN);

package/src/branding.js

@@ -18,7 +18,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { resolveCoreRoot, resolveInstanceRoot } = require('./instance-config');
+const { resolveCoreRoot, resolveInstanceRoot, resolveEnv, FALLBACK_ENV_PREFIX } = require('./instance-config');
 
 // ADR 0108 §1: the neutral starter ships WITH the core package; the instance
 // pack is host content. Both resolvers return the repo root today, so this is
@@ -106,9 +106,15 @@ function resolveBranding({ neutral = {}, instance = {}, env = {} } = {}) {
   // neutral/instance inputs — otherwise the deepFreeze below would also freeze
   // the caller's input objects (deepMerge shallow-copies only the top level).
   const resolved = structuredClone(deepMerge(neutral, instance));
-  const prefix = resolved.envPrefix || 'CLOUDBONGOS';
+  const prefix = resolved.envPrefix || FALLBACK_ENV_PREFIX;
   for (const [suffix, p, coerce] of ENV_OVERRIDES) {
-    const v = env[`${prefix}_${suffix}`];
+    // resolveEnv, not a bare env[] read: these overrides are set OUTSIDE the repo
+    // (/etc/cloudbongos/web.env, systemd units, the provisioning runner), so when
+    // task 1003703 moved the canonical prefix from CLOUDBONGOS_ to BONGOS_ a
+    // direct read would have silently stopped honoring every already-deployed
+    // CLOUDBONGOS_PUBLIC_ORIGIN — an origin regression with no error, found only
+    // by a broken OAuth callback. The legacy spellings warn once each instead.
+    const v = resolveEnv(suffix, { env, prefix });
     if (v === undefined || v === '') continue;
     // Most overrides are string-valued (origins, cookie domain) and set verbatim. A
     // 'bool'-tagged override (auth.idp) coerces the env string to a real boolean —
@@ -139,15 +145,26 @@ function readJson(p) {
 // OTB on the apex (server.js, the committed config/branding.json) and a vanilla
 // Cloud Bongos process pointed at its own pack (config/branding.cloudbongos.json)
 // — differentiated only by env, with no divergent clone to maintain. The loader
-// runs before the resolved envPrefix is known, so this is a FIXED env name (like
-// auth.js's GDS_PUBLIC_ORIGIN), not a <PREFIX>_ one. A relative path resolves
-// against the repo root.
+// runs before the resolved envPrefix is known, so this is a FIXED env name, not
+// a <PREFIX>_ one — which is exactly why it cannot go through resolveEnv() and
+// needs the two spellings listed by hand here. A relative path resolves against
+// the repo root.
+//
+// BONGOS_BRANDING_FILE is canonical since task 1003703; GDS_BRANDING_FILE is
+// still read (one deprecation warning per process) because it is set outside the
+// repo — the hall-preview server, CI jobs and side-by-side dev processes all
+// export it. Task 1003706 retires the old spelling.
 function loadBranding({ neutralPath = NEUTRAL_PATH, instancePath, env = process.env } = {}) {
   const neutral = readJson(neutralPath);
   if (!neutral) throw new Error(`branding: neutral starter not found at ${neutralPath}`);
   let ip = instancePath;
   if (ip === undefined) {
-    const override = env.GDS_BRANDING_FILE;
+    // prefix pinned to FALLBACK_ENV_PREFIX, not envPrefix(): this read happens
+    // BEFORE the pack that would name the prefix can be loaded, so the canonical
+    // spelling has to be a fixed one. Same pin, same reason, as
+    // resolveInstanceRootExplicit(). The legacy prefixes still resolve, which is
+    // what keeps every already-deployed GDS_BRANDING_FILE working.
+    const override = resolveEnv('BRANDING_FILE', { env, prefix: FALLBACK_ENV_PREFIX });
     ip = override ? path.resolve(resolveInstanceRoot(), override) : INSTANCE_PATH;
   }
   const instance = readJson(ip) || {};