@bongos/core 1.18.3 → 1.18.19

package/scripts/gds/upgrade.js

@@ -194,6 +194,115 @@ function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsIm
   return { ok: true, ran };
 }
 
+// The instance's GITIGNORED WHOLE-FILE navigation docs (ADR 0110). On the monorepo these
+// regenerate at deploy (deploy-prod.sh) + box-fetch and are gitignored so no branch ever diffs
+// them. STANDALONE instances (ADR 0108) never got that step: their bespoke deploy regenerated
+// nothing and init/upgrade only did the API docs, so a fresh instance shipped with an empty docs/
+// and nothing kept the index live (task 1002314, the owner's "docs didn't transfer from primea").
+// This is the standalone sibling of deploy-prod.sh's regen: run the generator(s) against the
+// INSTANCE root, best-effort + LOUD — a broken generator must surface (::ERROR::) but must NEVER
+// fail the deploy/bump (a stale nav doc is tolerable; a failed deploy is not — ADR 0110 §2
+// "accepted staleness").
+//
+// SCOPE — deliberately just session-index (the one gitignored whole-file doc that is INSTANCE
+// content). Excluded on purpose:
+//   • repo-map.md — CORE-scoped: gen-repo-map writes to resolveCoreRoot() (the platform code map),
+//     not the instance. A pure standalone instance runs core from node_modules and has ~no code of
+//     its own to map, so an instance-level repo-map is empty/meaningless; the core ships its own.
+//     (An instance-scoped map for BROWNFIELD/adopted repos is a separate enhancement — task 1001655.)
+//   • file-map.md + API docs — TRACKED/committed (seeded at init, refreshed at ship/upgrade);
+//     regenerating them on the box would perpetually dirty the tree that deploy.sh `git reset
+//     --hard`es. file-map is also HYBRID (hand-written prose + generated sections, ADR 0110) so it
+//     cannot leave git; seeding it at standup is a follow-up (needs a scaffolded file-map.md).
+//   • diagrams + atlas.json — NOT instance content: they are CORE-scoped generated assets that
+//     live under resolveCoreRoot(). They are handled separately by healDocAssets() below, because
+//     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 ran = [];
+  const failed = [];
+  for (const gen of generators) {
+    const script = path.join(coreRoot, 'scripts', 'gds', gen);
+    if (!fsImpl.existsSync(script)) { failed.push({ gen, reason: `not found in core (${coreRoot})` }); continue; }
+    const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
+    if (!r || r.error || r.status !== 0) {
+      // LOUD per ADR 0110 §2 — journald greps ::ERROR:: so a broken generator alarms.
+      failed.push({ gen, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
+      continue;
+    }
+    ran.push(gen);
+  }
+  return { ok: failed.length === 0, ran, failed };
+}
+
+// The CORE-scoped generated doc assets that back two builders'-hall surfaces:
+//
+//   modules/hall-ui/public/atlas.json      → the Repo Atlas   (/builders/atlas)
+//   docs/onboarding/diagrams/<n>.svg+.png  → the system maps  (/builders/diagrams)
+//
+// Both are GITIGNORED (.gitignore: `modules/hall-ui/public/atlas.json`,
+// `docs/onboarding/diagrams/*.svg|*.png` — ADR 0122 / task 1002027) and both are generated INTO
+// the vendored core root. So an upgrade DESTROYS them: npmInstall replaces node_modules wholesale
+// and the new tarball carries only the .mmd sources. Nothing else puts them back —
+//   • packaging does not render (package-core.js has no render step, and the renders are
+//     gitignored so a git checkout has none to copy), and
+//   • a standalone instance's pull-deploy typically short-circuits on an unchanged git SHA, which
+//     an upgrade does not move — so its regen hooks never fire.
+// Result before this healer: /builders/atlas 404'd and the diagrams page showed broken images
+// after every `bongos upgrade`, until some unrelated commit happened to land (task 1002441).
+//
+// Both generators resolve their own output dir from __dirname, so running the CORE's copy always
+// writes into coreRoot regardless of cwd. Idempotent by design — each asset is regenerated only
+// when actually absent, so this is also safe to call from a deploy loop.
+//
+// Best-effort + LOUD, per ADR 0110 §2 "accepted staleness": a stale diagram is tolerable, a failed
+// upgrade is not. render-diagrams.sh additionally needs a system Chromium (ADR 0122); where none is
+// installed it fails and we say so via ::ERROR:: rather than aborting the bump.
+const DOC_ASSET_GENERATORS = {
+  atlas: { rel: path.join('scripts', 'gds', 'gen-atlas.js'), kind: 'node' },
+  diagrams: { rel: path.join('scripts', 'render-diagrams.sh'), kind: 'bash' },
+};
+
+// Which of the two asset groups are missing under coreRoot. Exported for testing.
+function missingDocAssets(coreRoot, fsImpl = fs) {
+  const missing = [];
+  if (!fsImpl.existsSync(path.join(coreRoot, 'modules', 'hall-ui', 'public', 'atlas.json'))) {
+    missing.push('atlas');
+  }
+  const diagramDir = path.join(coreRoot, 'docs', 'onboarding', 'diagrams');
+  let sources = [];
+  try {
+    sources = fsImpl.readdirSync(diagramDir).filter((f) => f.endsWith('.mmd'));
+  } catch { sources = []; }  // no diagram dir in this core → nothing to render
+  const unrendered = sources.some((src) => {
+    const base = path.join(diagramDir, src.replace(/\.mmd$/, ''));
+    return !fsImpl.existsSync(`${base}.svg`) || !fsImpl.existsSync(`${base}.png`);
+  });
+  if (unrendered) missing.push('diagrams');
+  return missing;
+}
+
+function healDocAssets({ coreRoot }, run = spawnSync, fsImpl = fs) {
+  const missing = missingDocAssets(coreRoot, fsImpl);
+  if (missing.length === 0) return { ok: true, ran: [], failed: [], missing: [] };
+  const ran = [];
+  const failed = [];
+  for (const group of missing) {
+    const gen = DOC_ASSET_GENERATORS[group];
+    const script = path.join(coreRoot, gen.rel);
+    if (!fsImpl.existsSync(script)) { failed.push({ group, reason: `not found in core (${gen.rel})` }); continue; }
+    const argv = gen.kind === 'bash' ? ['bash', [script]] : [process.execPath, [script]];
+    const r = run(argv[0], argv[1], { cwd: coreRoot, stdio: 'inherit' });
+    if (!r || r.error || r.status !== 0) {
+      failed.push({ group, reason: r && r.error ? r.error.message : `exited ${r && r.status}` });
+      continue;
+    }
+    ran.push(group);
+  }
+  return { ok: failed.length === 0, ran, failed, missing };
+}
+
 function restartService({ service, restartCmd }, run = spawnSync) {
   if (restartCmd) {
     const parts = restartCmd.split(/\s+/);
@@ -587,7 +696,20 @@ async function runUpgrade(opts, deps = {}) {
     const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
     if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
     else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
-  } else log('  • API-artifact regen skipped (--skip-regen-docs)');
+    // 5c. regenerate the whole-file navigation docs (repo-map + session-index) from the new
+    // core against the instance root (ADR 0110 / task 1002314). Best-effort + LOUD: a broken
+    // generator alarms via ::ERROR:: but never fails the bump.
+    const nav = (deps.regenerateNavDocs || regenerateNavDocs)({ instanceDir, coreRoot }, run);
+    if (nav.ok) log(`  ✓ regenerated navigation docs (${nav.ran.join(', ')}) from core ${targetVersion}`);
+    else err(`  ! ::ERROR:: navigation-doc regen incomplete — ran ${nav.ran.join(', ') || 'nothing'}; failed ${nav.failed.map((f) => `${f.gen} (${f.reason})`).join(', ')}. The next deploy retries.`);
+    // 5d. re-generate the CORE-scoped doc assets this very upgrade just wiped — the Repo Atlas
+    // data file + the onboarding diagram renders (task 1002441). See healDocAssets() for why
+    // nothing else puts them back. Best-effort + LOUD, same contract as 5c.
+    const heal = (deps.healDocAssets || healDocAssets)({ coreRoot }, run);
+    if (heal.missing.length === 0) log('  • doc assets intact (atlas + diagram renders present)');
+    else if (heal.ok) log(`  ✓ regenerated doc assets wiped by the core swap (${heal.ran.join(', ')})`);
+    else err(`  ! ::ERROR:: doc-asset regen incomplete — ran ${heal.ran.join(', ') || 'nothing'}; failed ${heal.failed.map((f) => `${f.group} (${f.reason})`).join(', ')}. /builders/atlas or /builders/diagrams may be broken until the next deploy retries (diagram renders need a system Chromium — ADR 0122).`);
+  } else log('  • doc regen skipped (--skip-regen-docs)');
 
   // 6. restart.
   const rs = restartService({ service: opts.service, restartCmd: opts.restartCmd }, run);
@@ -700,7 +822,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, preflightModules, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/scripts/migrate.sh

@@ -51,6 +51,15 @@ fi
 
 DB="${PGDATABASE:-amazonprimea}"
 
+# Test/ops seam (task 1002611): --print-migrations walks the REAL core-migration loop but reports
+# each path instead of applying it, and touches NO DB. tests/migrate_root_resolution.mjs uses it to
+# assert that a checkout whose path contains a space still yields whole, readable paths. Reporting
+# through the real loop (rather than a copy of it in the test) is the point: if the loop ever reverts
+# to an unquoted `for f in $MIGRATIONS`, this seam fragments the paths and the test fails. Also handy
+# in the field — `npm run migrate -- --print-migrations` shows exactly what migrate would apply.
+DRY_RUN=0
+if [ "${1:-}" = "--print-migrations" ]; then DRY_RUN=1; fi
+
 # --- Instance-seed policy (task 1704 / ADR 0105) --------------------------
 # OTB/product scope-truth (versions, goals, done_when_criteria) lives in seed
 # migrations under migrations/instance/ (plus a few guarded blocks embedded in the
@@ -81,22 +90,40 @@ echo "instance-seed policy: app.seed_instance_data=$SEED_INSTANCE (migrations/in
 
 # Make sure schema_migrations exists before we query it. (001 creates
 # it; other migrations rely on it.)
-psql -d "$DB" -v ON_ERROR_STOP=1 -tAc "
-  CREATE TABLE IF NOT EXISTS schema_migrations (
-    version text PRIMARY KEY,
-    applied_at timestamptz NOT NULL DEFAULT now()
-  );
-" >/dev/null
+if [ "$DRY_RUN" = 0 ]; then
+  psql -d "$DB" -v ON_ERROR_STOP=1 -tAc "
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      version text PRIMARY KEY,
+      applied_at timestamptz NOT NULL DEFAULT now()
+    );
+  " >/dev/null
 
-APPLIED=$(psql -d "$DB" -tA -c "SELECT version FROM schema_migrations ORDER BY version")
+  APPLIED=$(psql -d "$DB" -tA -c "SELECT version FROM schema_migrations ORDER BY version")
+else
+  APPLIED=""
+fi
 
 # Apply one migration file unless its filename stem is already recorded. Stem (not path) is the
 # key, so moving a file between migrations/ and migrations/game/ does NOT re-run it on prod.
+#
+# The two counters are what the no-op guard below reads: a run that LISTED core migrations but
+# neither applied nor recognized a single one is the space-in-path failure (task 1002611) and must
+# be fatal, not silent. Both loops that call this run in the CURRENT shell (herestring / plain glob,
+# never a `... | while` pipeline), so these increments are visible to the caller.
+MIGRATIONS_APPLIED=0
+MIGRATIONS_ALREADY=0
 apply_migration() {
   local f="$1" version
   version="$(basename "$f" .sql)"
+  if [ "$DRY_RUN" = 1 ]; then
+    # Counted as applied so the no-op guard below is exercised by the seam too.
+    printf 'would-apply\t%s\n' "$f"
+    MIGRATIONS_APPLIED=$((MIGRATIONS_APPLIED + 1))
+    return
+  fi
   if echo "$APPLIED" | grep -q "^${version}$"; then
     echo "skip   $version (already applied)"
+    MIGRATIONS_ALREADY=$((MIGRATIONS_ALREADY + 1))
     return
   fi
   echo "apply  $version"
@@ -108,6 +135,7 @@ apply_migration() {
   psql -d "$DB" -v ON_ERROR_STOP=1 -tAc \
     "INSERT INTO schema_migrations (version) VALUES ('${version}') ON CONFLICT DO NOTHING" \
     >/dev/null
+  MIGRATIONS_APPLIED=$((MIGRATIONS_APPLIED + 1))
 }
 
 # --- Forward-safety notice (task 1002223 / audit H10) ---------------------
@@ -116,7 +144,7 @@ apply_migration() {
 # UNACKNOWLEDGED forward-unsafe core migration so an operator knows a rollback past it would strand
 # old code on new schema. Fail-closed enforcement is the unit gate (tests/migrations_forward_safe.mjs);
 # here it is advisory (`|| true`) so a lint hiccup can NEVER break a deploy.
-if [ -f "$CORE_ROOT/scripts/gds/lint-migrations.js" ]; then
+if [ "$DRY_RUN" = 0 ] && [ -f "$CORE_ROOT/scripts/gds/lint-migrations.js" ]; then
   node "$CORE_ROOT/scripts/gds/lint-migrations.js" --warn --dir "$CORE_ROOT/migrations" || true
 fi
 
@@ -131,14 +159,66 @@ fi
 # are included only when SEED_INSTANCE=on; stem-keyed tracking means a file's directory never
 # affects whether it re-runs on OTB prod. Today CORE_ROOT == INSTANCE_ROOT (single checkout);
 # once the core installs from node_modules the two roots diverge and this still merges correctly.
+#
+# PATHS WITH SPACES (task 1002611): this list is NEWLINE-separated and must be read a line at a
+# time. The old `for f in $MIGRATIONS` word-split it on IFS — which includes space — so any checkout
+# whose absolute path contains a space ("/Users/.../Hermeslines Marketing/...") fragmented every
+# path, the `[ -e ]` guard below silently dropped all of them, and ZERO core migrations ran.
+# Reproduced on 1.18.18: 117 files listed, 234 loop iterations, 234 -e failures, schema_migrations
+# empty. The module loop further down is correctly quoted, so module migrations then ran against an
+# EMPTY schema and reported a bogus `relation "achievements" does not exist` from modules/economy —
+# `achievements` is created by CORE 006_pms_v2.sql, which never ran. Hence the guard after the loop.
+# `<<<` (bash — see the shebang) keeps the loop in the CURRENT shell, so the counters survive it; a
+# `... | while read` pipeline would both subshell the counters away and interact badly with
+# `set -euo pipefail`. `|| true` on each `ls` keeps an empty glob from tripping pipefail.
 MIGRATIONS=$( {
-  ls "$CORE_ROOT"/migrations/*.sql 2>/dev/null
-  if [ "$SEED_INSTANCE" = "on" ]; then ls "$INSTANCE_ROOT"/migrations/instance/*.sql 2>/dev/null; fi
+  ls "$CORE_ROOT"/migrations/*.sql 2>/dev/null || true
+  if [ "$SEED_INSTANCE" = "on" ]; then ls "$INSTANCE_ROOT"/migrations/instance/*.sql 2>/dev/null || true; fi
 } | awk -F/ '{ print $NF "\t" $0 }' | sort | cut -f2- )
-for f in $MIGRATIONS; do
-  [ -e "$f" ] || continue
+migrations_listed=0
+migrations_unreadable=0
+before_applied=$MIGRATIONS_APPLIED
+before_already=$MIGRATIONS_ALREADY
+while IFS= read -r f; do
+  # An empty $MIGRATIONS still yields one empty line through `<<<`, so skip blanks before -e.
+  [ -n "$f" ] || continue
+  migrations_listed=$((migrations_listed + 1))
+  if [ ! -e "$f" ]; then
+    migrations_unreadable=$((migrations_unreadable + 1))
+    echo "migrate.sh: listed migration is not a readable file, skipping: $f" >&2
+    continue
+  fi
   apply_migration "$f"
-done
+done <<< "$MIGRATIONS"
+
+# --- No-op guard (task 1002611) -------------------------------------------
+# Silence is what made the space-in-path bug expensive to diagnose: core migrations were skipped
+# without a word, and the first error the operator saw came from an unrelated MODULE migration
+# hitting the empty schema. If the glob LISTED core migrations but we neither applied nor recognized
+# a single one, the list itself is broken — stop here rather than let the module loop below produce a
+# misleading error about a table that a core migration was supposed to create.
+core_applied=$((MIGRATIONS_APPLIED - before_applied))
+core_already=$((MIGRATIONS_ALREADY - before_already))
+if [ "$migrations_listed" -gt 0 ] && [ "$core_applied" -eq 0 ] && [ "$core_already" -eq 0 ]; then
+  {
+    echo
+    echo "migrate.sh: FATAL — listed $migrations_listed core migration(s) but applied 0 and found 0 already applied."
+    echo "  $migrations_unreadable of the $migrations_listed listed path(s) were not readable files."
+    echo "  CORE_ROOT=$CORE_ROOT"
+    echo "  Refusing to continue to module migrations: they would run against an empty schema and"
+    echo "  fail with a misleading error (e.g. relation \"achievements\" does not exist) from a module,"
+    echo "  when the real cause is that no core migration ran."
+    echo "  Run 'npm run migrate -- --print-roots' to see the roots migrate resolved."
+  } >&2
+  exit 1
+fi
+
+# The --print-migrations seam stops here: the core list is what it verifies, and going further would
+# need a DB. The summary line is the machine-readable assertion target.
+if [ "$DRY_RUN" = 1 ]; then
+  printf 'listed=%d unreadable=%d\n' "$migrations_listed" "$migrations_unreadable"
+  exit 0
+fi
 [ "$SEED_INSTANCE" = "on" ] || echo "instance seeds skipped (migrations/instance/) — non-owning / vanilla instance"
 
 # Module-owned migrations (modules/<key>/migrations/*.sql) — applied only when the module is
@@ -208,7 +288,12 @@ if [ "${OTB_POST_DEPLOY_CHECK:-0}" = "1" ]; then
       BASELINE_FLAG="--baseline-only"
       echo "post-deploy: no prior score ledger — running in baseline-only mode"
     fi
-    if ! python3 modules/art-pipeline/pipeline/post_deploy_check.py $BASELINE_FLAG; then
+    # `${VAR:+"$VAR"}` expands to NOTHING when empty and to the quoted value otherwise. A bare
+    # $BASELINE_FLAG relied on word-splitting to vanish (the habit that caused task 1002611), and
+    # quoting it outright would instead pass an empty argv entry that argparse rejects. An array
+    # would need bash 4 — `set -u` + `"${arr[@]}"` on an empty array aborts under the bash 3.2 that
+    # macOS still ships, and this script's shebang takes whatever bash is on PATH.
+    if ! python3 modules/art-pipeline/pipeline/post_deploy_check.py ${BASELINE_FLAG:+"$BASELINE_FLAG"}; then
       echo "post-deploy: whole-world check FAILED — see output above" >&2
       exit 1
     fi

package/scripts/status-mirror-sync.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // scripts/status-mirror-sync.js — publish the status surface to the off-box status
-// mirror (lars589/amazonprimea-status → GitHub Pages → status.amazonprimea.com).
+// mirror (a separate repo → a static Pages host → the instance's status domain).
 //
 // SOURCE PATH (BV1.R84 / task 1635): the status dashboard moved from public-status/
 // to modules/status-ui/public/ when the status surface became a module (a web
@@ -14,19 +14,28 @@
 // (that's how #726's reorg + #731's theming never showed up). This makes the
 // publish deterministic and CI-driven.
 //
+// CONFIG (task 1002510 — no host identity is baked in here; ADR 0062 §3):
+//   domains.publicOrigin  — the origin the mirror calls cross-origin
+//                           (window.STATUS_API_BASE), and the site label the
+//                           availability banner names as up/down.
+//   domains.statusDataUrl — the off-box prober's status.json URL the availability
+//                           banner reads. EMPTY ⇒ this instance runs no off-box
+//                           mirror, and the publish REFUSES rather than shipping a
+//                           page whose banner points nowhere.
+//
 // DESIGN: status.js + style.css + cursors/ are byte-identical between the
 // droplet copy and the mirror (#737 parameterized the one differing constant via
 // window.STATUS_API_BASE), so they are PURE COPIES. Only index.html carries the
 // three off-box additions, injected here at stable anchors:
-//   1. <script>window.STATUS_API_BASE='https://amazonprimea.com'</script>  (head)
-//   2. <div id="offbox-status">…</div>                                     (after <body>)
-//   3. the availability-banner driver <script> (reads the status-data branch)  (before status.js)
+//   1. <script>window.STATUS_API_BASE = <domains.publicOrigin></script>   (head)
+//   2. <div id="offbox-status">…</div>                                    (after <body>)
+//   3. the availability-banner driver <script> (reads domains.statusDataUrl) (before status.js)
 // If any anchor is missing the script THROWS — a silent mis-sync is worse than
 // a failed run.
 //
 // USAGE:
 //   node scripts/status-mirror-sync.js --repo-dir <path-to-mirror-checkout> [--push]
-//     --repo-dir : a checkout of lars589/amazonprimea-status (its `main` branch).
+//     --repo-dir : a checkout of the status-mirror repo (its `main` branch).
 //     --push     : commit + push the result. Without it the files are written
 //                  and `git status` is printed for inspection (dry-ish run).
 //
@@ -42,52 +51,36 @@ const SRC = path.join(REPO_ROOT, 'modules', 'status-ui', 'public');
 const { branding, clientBranding } = require('../src/branding');
 
 // Stamp instance-identity tokens into the mirror HTML. The off-box mirror is
-// served by GitHub Pages, NOT the branding-injecting Node server — so this script
-// must reproduce serve-internal.applyBrandTokens (task 1705, ADR 0062 §3), else the
-// mirror would render literal {{worldName}}/{{currency}} placeholders. KEEP IN SYNC
-// with src/bongos/serve-internal.js applyBrandTokens.
-function brandTokens(html) {
-  const b = clientBranding();
-  const world = (b.identity && b.identity.worldName) || '';
-  const product = (b.identity && b.identity.productName) || '';
-  const cur = (b.currency && b.currency.label) || 'credits';
+// served by a static Pages host, NOT the branding-injecting Node server — so this
+// script must reproduce serve-internal.applyBrandTokens (task 1705, ADR 0062 §3), else
+// the mirror would render literal {{worldName}}/{{currency}} placeholders. KEEP IN SYNC
+// with src/bongos/serve-internal.js applyBrandTokens. `brand` is the client-safe pack
+// and `publicOrigin` the resolved origin — both injected, never read ambiently, so the
+// transform stays pure and testable.
+function brandTokens(html, brand = {}, publicOrigin = '') {
+  const world = (brand.identity && brand.identity.worldName) || '';
+  const product = (brand.identity && brand.identity.productName) || '';
+  const cur = (brand.currency && brand.currency.label) || 'credits';
   const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
-  let origin = '';
-  try { origin = branding().domains.publicOrigin || ''; } catch (_) { /* neutral */ }
   return html
     .split('{{worldName}}').join(world)
     .split('{{productName}}').join(product)
     .split('{{Currency}}').join(Cur)
     .split('{{currency}}').join(cur)
-    .split('{{publicOrigin}}').join(origin);
-}
-
-function arg(name) {
-  const i = process.argv.indexOf(name);
-  return i >= 0 ? process.argv[i + 1] : null;
-}
-const repoDir = arg('--repo-dir');
-const doPush = process.argv.includes('--push');
-if (!repoDir) {
-  console.error('usage: node scripts/status-mirror-sync.js --repo-dir <mirror-checkout> [--push]');
-  process.exit(2);
-}
-if (!fs.existsSync(path.join(repoDir, 'CNAME'))) {
-  console.error(`refusing: ${repoDir} does not look like the status mirror (no CNAME). Clone lars589/amazonprimea-status first.`);
-  process.exit(2);
+    .split('{{publicOrigin}}').join(publicOrigin || '');
 }
 
 // ---- the three off-box index.html injections -------------------------------
 
-const HEAD_INJECT =
+const headInject = (apiBase) =>
   `  <!-- #737: off-box mirror runs cross-origin against the droplet. -->\n` +
-  `  <script>window.STATUS_API_BASE = 'https://amazonprimea.com';</script>\n`;
+  `  <script>window.STATUS_API_BASE = ${JSON.stringify(apiBase)};</script>\n`;
 
 // The client-safe branding pack, so status.js reads the instance currency label
 // on the mirror exactly as it does on the droplet (serve-internal injects the same
 // global there). Without this, status.js would fall back to the neutral 'credits'.
-const BRANDING_INJECT =
-  `  <script>window.__BRANDING__ = ${JSON.stringify(clientBranding())};</script>\n`;
+const brandingInject = (brand) =>
+  `  <script>window.__BRANDING__ = ${JSON.stringify(brand)};</script>\n`;
 
 const BANNER_DIV =
   `\n<!-- Off-box availability banner (ADR 0029) — injected by scripts/status-mirror-sync.js.\n` +
@@ -95,11 +88,17 @@ const BANNER_DIV =
   `     prober's status.json from this repo's status-data branch, no droplet dependency. -->\n` +
   `<div id="offbox-status" role="status" aria-live="polite"></div>\n`;
 
-const BANNER_DRIVER = `<!-- Off-box availability banner driver (ADR 0029) — loaded before status.js so
+// The banner names the site it is reporting on. Derived from the configured origin
+// so no hostname is baked in; a non-URL origin falls back to the raw string.
+function siteLabel(origin) {
+  try { return new URL(origin).host; } catch { return String(origin || ''); }
+}
+
+const bannerDriver = (statusDataUrl, label) => `<!-- Off-box availability banner driver (ADR 0029) — loaded before status.js so
      it lights up even if the dashboard script or its cross-origin fetches fail. -->
 <script>
 (function () {
-  var OFFBOX_URL = 'https://raw.githubusercontent.com/lars589/amazonprimea-status/status-data/status.json';
+  var OFFBOX_URL = ${JSON.stringify(statusDataUrl)};
   var el = document.getElementById('offbox-status');
   if (!el) return;
   function fmtUtc(iso) {
@@ -113,8 +112,8 @@ const BANNER_DRIVER = `<!-- Off-box availability banner driver (ADR 0029) — lo
       .then(function (res) { if (!res.ok) throw new Error('HTTP ' + res.status); return res.json(); })
       .then(function (data) {
         var cur = data && data.current, status = cur && cur.status, when = fmtUtc(cur && cur.t);
-        if (status === 'up') setState('up', '\\uD83D\\uDFE2 amazonprimea.com is operational \\u2014 checked ' + when);
-        else if (status === 'down') setState('down', '\\uD83D\\uDD34 amazonprimea.com is DOWN \\u2014 checked ' + when);
+        if (status === 'up') setState('up', '\\uD83D\\uDFE2 ${label} is operational \\u2014 checked ' + when);
+        else if (status === 'down') setState('down', '\\uD83D\\uDD34 ${label} is DOWN \\u2014 checked ' + when);
         else setState('unknown', 'status data is momentarily unavailable');
       })
       .catch(function () { setState('unknown', 'status data is momentarily unavailable'); });
@@ -134,59 +133,90 @@ function injectOnce(haystack, anchor, insertion, where) {
   return haystack.slice(0, idx + anchor.length) + insertion + haystack.slice(idx + anchor.length);
 }
 
-function buildIndexHtml() {
-  let html = fs.readFileSync(path.join(SRC, 'index.html'), 'utf8');
+// Pure: droplet index.html + resolved config → the mirror's index.html. No disk, no
+// network, no ambient branding read — everything the output depends on is a parameter.
+function buildMirrorIndex({ srcHtml, apiBase, statusDataUrl, brand }) {
+  if (!statusDataUrl) {
+    throw new Error('domains.statusDataUrl is empty — the off-box availability banner would point nowhere. Set domains.statusDataUrl (the prober\'s status.json URL) in the branding config, or do not publish a mirror for this instance.');
+  }
+  let html = String(srcHtml == null ? '' : srcHtml);
   if (html.includes('offbox-status')) {
     throw new Error('modules/status-ui/public/index.html already contains offbox markup — the source should be the droplet (no-banner) copy. Aborting.');
   }
-  html = injectOnce(html, '</head>', HEAD_INJECT + BRANDING_INJECT, 'before');
+  html = injectOnce(html, '</head>', headInject(apiBase) + brandingInject(brand), 'before');
   html = injectOnce(html, '<body>', BANNER_DIV, 'after');
   // Insert the driver right before the main status.js script tag.
   const scriptAnchor = '<script src="/status.js';
-  html = injectOnce(html, scriptAnchor, BANNER_DRIVER + '', 'before');
-  // Stamp the instance branding tokens LAST — GitHub Pages won't run the server's
+  html = injectOnce(html, scriptAnchor, bannerDriver(statusDataUrl, siteLabel(apiBase)), 'before');
+  // Stamp the instance branding tokens LAST — the Pages host won't run the server's
   // injection, so the mirror must resolve {{worldName}}/{{currency}}/… itself.
-  html = brandTokens(html);
-  return html;
+  return brandTokens(html, brand, apiBase);
 }
 
-// ---- copy the verbatim assets + the transformed index ----------------------
+// ---- CLI -------------------------------------------------------------------
+
+if (require.main === module) {
+  const arg = (name) => {
+    const i = process.argv.indexOf(name);
+    return i >= 0 ? process.argv[i + 1] : null;
+  };
+  const repoDir = arg('--repo-dir');
+  const doPush = process.argv.includes('--push');
+  if (!repoDir) {
+    console.error('usage: node scripts/status-mirror-sync.js --repo-dir <mirror-checkout> [--push]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(path.join(repoDir, 'CNAME'))) {
+    console.error(`refusing: ${repoDir} does not look like the status mirror (no CNAME). Clone the status-mirror repo first.`);
+    process.exit(2);
+  }
 
-function copyFile(rel) {
-  fs.copyFileSync(path.join(SRC, rel), path.join(repoDir, rel));
-  console.error(`  copied ${rel}`);
-}
-function copyDir(rel) {
-  const from = path.join(SRC, rel), to = path.join(repoDir, rel);
-  if (!fs.existsSync(from)) return;
-  fs.rmSync(to, { recursive: true, force: true });
-  fs.cpSync(from, to, { recursive: true });
-  console.error(`  copied ${rel}/`);
+  const b = branding();
+
+  // ---- copy the verbatim assets + the transformed index ----------------------
+
+  const copyFile = (rel) => {
+    fs.copyFileSync(path.join(SRC, rel), path.join(repoDir, rel));
+    console.error(`  copied ${rel}`);
+  };
+  const copyDir = (rel) => {
+    const from = path.join(SRC, rel), to = path.join(repoDir, rel);
+    if (!fs.existsSync(from)) return;
+    fs.rmSync(to, { recursive: true, force: true });
+    fs.cpSync(from, to, { recursive: true });
+    console.error(`  copied ${rel}/`);
+  };
+
+  console.error('[status-mirror-sync] building mirror from modules/status-ui/public/ …');
+  const indexHtml = buildMirrorIndex({
+    srcHtml: fs.readFileSync(path.join(SRC, 'index.html'), 'utf8'),
+    apiBase: b.domains.publicOrigin,
+    statusDataUrl: b.domains.statusDataUrl,
+    brand: clientBranding(),
+  });
+  fs.writeFileSync(path.join(repoDir, 'index.html'), indexHtml);
+  console.error('  wrote index.html (with off-box injections)');
+  copyFile('status.js');
+  copyFile('style.css');
+  copyDir('cursors');
+
+  // ---- commit + (optionally) push -------------------------------------------
+
+  const git = (args) => execFileSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
+  git(['add', 'index.html', 'status.js', 'style.css', 'cursors']);
+  const status = git(['status', '--porcelain']);
+  if (!status.trim()) {
+    console.error('[status-mirror-sync] mirror already up to date — nothing to publish.');
+    process.exit(0);
+  }
+  console.error('[status-mirror-sync] changes staged:\n' + status);
+  if (!doPush) {
+    console.error('[status-mirror-sync] dry run (no --push). Review the checkout, then re-run with --push.');
+    process.exit(0);
+  }
+  git(['commit', '-m', 'chore(status): sync off-box mirror from modules/status-ui/public/ (#737)']);
+  git(['push', 'origin', 'HEAD:main']);
+  console.error(`[status-mirror-sync] published. The Pages host rebuilds ${b.domains.statusOrigin || 'the mirror'} in ~1 min.`);
 }
 
-console.error('[status-mirror-sync] building mirror from modules/status-ui/public/ …');
-fs.writeFileSync(path.join(repoDir, 'index.html'), buildIndexHtml());
-console.error('  wrote index.html (with off-box injections)');
-copyFile('status.js');
-copyFile('style.css');
-copyDir('cursors');
-
-// ---- commit + (optionally) push -------------------------------------------
-
-function git(args) {
-  return execFileSync('git', ['-C', repoDir, ...args], { encoding: 'utf8' });
-}
-git(['add', 'index.html', 'status.js', 'style.css', 'cursors']);
-const status = git(['status', '--porcelain']);
-if (!status.trim()) {
-  console.error('[status-mirror-sync] mirror already up to date — nothing to publish.');
-  process.exit(0);
-}
-console.error('[status-mirror-sync] changes staged:\n' + status);
-if (!doPush) {
-  console.error('[status-mirror-sync] dry run (no --push). Review the checkout, then re-run with --push.');
-  process.exit(0);
-}
-git(['commit', '-m', 'chore(status): sync off-box mirror from modules/status-ui/public/ (#737)']);
-git(['push', 'origin', 'HEAD:main']);
-console.error('[status-mirror-sync] published. GitHub Pages rebuilds status.amazonprimea.com in ~1 min.');
+module.exports = { buildMirrorIndex, injectOnce, brandTokens };

package/src/bongos/api-errors.js

@@ -66,6 +66,7 @@ const OVERRIDES = Object.freeze({
   // --- forbidden: 403 (rank/ownership, not "missing" or "bad input") ---
   forbidden: 'forbidden',
   rank_forbidden: 'forbidden',
+  permission_forbidden: 'forbidden',
   archon_approval_required: 'forbidden',
   archon_required_for_protected_scope: 'forbidden',
   metic_required_for_ownership: 'forbidden',