@bongos/core 1.18.0 → 1.18.18

package/scripts/gds/preflight.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// scripts/gds/preflight.js — the onboarding ENVIRONMENT PREFLIGHT (task 1002401,
+// onboarding-audit area 4).
+//
+// One shared, PURE check of the three things that used to bite a brand-new
+// builder one reactive crash at a time:
+//   1. Node >= 22        — the very first command (`bongos start`) shells to node;
+//                          on a bare machine it died with `node: command not found`.
+//   2. deps installed    — a missing node_modules is why a ship later blew up with
+//                          `Cannot find module 'pg'`.
+//   3. `claude` launchable — the grader spawns it per worker; without it every ship
+//                          failed grading with SUBAGENT_SPAWN_FAILED.
+// Each finding carries a copy-paste fix.
+//
+// Before this, those checks lived only inside `bongos doctor` (doctor.js) and were
+// never run at setup/start time — so newcomers hit the failures reactively, deep
+// in the session. This module is the front-loadable, testable source of truth:
+//   - `setup.js`  runs it at the top of `/builder-setup` (catch a bare machine up front)
+//   - `doctor.js` `checkToolchain()` delegates to it (one source, no drift)
+//   - `node scripts/gds/preflight.js` runs it standalone (a quick `bongos`-less check)
+//
+// Pure by construction: every OS touch (node version, fs, child_process) is an
+// injectable dep, so the unit test drives it with zero real I/O.
+
+'use strict';
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = nodePath.resolve(__dirname, '..', '..');
+const MIN_NODE_MAJOR = 22;
+
+// The node_modules-present check, factored out (task 1002403) so a HOT-PATH
+// caller — /builder-start runs on every session open — can reuse THIS exact
+// finding without paying for the `claude --version` spawn the full
+// preflightChecks() does. Pure: injectable fs + repoRoot.
+function depsFinding({ repoRoot = REPO_ROOT, fs = nodeFs } = {}) {
+  let hasDeps = false;
+  try { hasDeps = fs.existsSync(nodePath.join(repoRoot, 'node_modules')); } catch (_) { /* treat as missing */ }
+  if (hasDeps) {
+    return { level: 'ok', title: 'Dependencies', detail: 'node_modules present.' };
+  }
+  return {
+    level: 'warn',
+    title: 'Dependencies',
+    detail: 'node_modules is missing — scripts that need pg/express (a ship, the server) will fail until installed.',
+    fix: 'Run `npm ci` in the repo root.',
+  };
+}
+
+// preflightChecks(deps) → [{ level:'ok'|'warn'|'fail', title, detail, fix? }]
+// No printing, no process.exit — callers (setup, doctor, the test) format it.
+function preflightChecks({
+  repoRoot = REPO_ROOT,
+  nodeVersion = process.version,
+  env = process.env,
+  fs = nodeFs,
+  spawn = spawnSync,
+  platform = process.platform,
+} = {}) {
+  const out = [];
+
+  // 1. Node >= 22.
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]) || 0;
+  if (major >= MIN_NODE_MAJOR) {
+    out.push({ level: 'ok', title: 'Node', detail: `${nodeVersion} (>= ${MIN_NODE_MAJOR}).` });
+  } else {
+    out.push({
+      level: 'fail',
+      title: 'Node',
+      detail: `${nodeVersion} is below the required v${MIN_NODE_MAJOR}.`,
+      fix: 'Install Node >= 22 — e.g. `brew install node`, `nvm install 22`, or https://nodejs.org.',
+    });
+  }
+
+  // 2. Dependencies installed (node_modules present) — shared with the hot-path
+  //    /builder-start caller via depsFinding() (task 1002403).
+  out.push(depsFinding({ repoRoot, fs }));
+
+  // 3. `claude` CLI launchable — same resolution order the grader uses.
+  const bin = env.OTB_CLAUDE_BIN || env.CLAUDE_BIN || 'claude';
+  const via = env.OTB_CLAUDE_BIN ? ' (via OTB_CLAUDE_BIN)' : env.CLAUDE_BIN ? ' (via CLAUDE_BIN)' : '';
+  let r;
+  try {
+    r = spawn(bin, ['--version'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
+  } catch (err) { r = { error: err }; }
+  if (r && !r.error && r.status === 0) {
+    const ver = String(r.stdout || '').trim().split('\n')[0] || 'present';
+    out.push({ level: 'ok', title: 'claude CLI', detail: `launches${via}: ${ver} — the grader can spawn its workers.` });
+  } else {
+    const why = r && r.error ? (r.error.code || r.error.message) : `exited ${r ? r.status : '?'}`;
+    out.push({
+      level: 'fail',
+      title: 'claude CLI',
+      detail: `not launchable (${bin}: ${why}) — the grader spawns it per worker, so ships fail grading with SUBAGENT_SPAWN_FAILED.`,
+      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set OTB_CLAUDE_BIN to its full path.',
+    });
+  }
+
+  return out;
+}
+
+const GLYPH = { ok: '✓', warn: '!', fail: '✖' };
+const ANSI = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', dim: '\x1b[2m', reset: '\x1b[0m' };
+
+// formatPreflight(results, opts) → a printable multi-line string.
+function formatPreflight(results, { color = false, heading = false } = {}) {
+  const c = (k, s) => (color ? `${ANSI[k]}${s}${ANSI.reset}` : s);
+  const lines = [];
+  if (heading) lines.push('Checking your environment…');
+  for (const r of results) {
+    lines.push(`  ${c(r.level, GLYPH[r.level])} ${r.title}: ${r.detail}`);
+    if (r.fix) lines.push(`      ${c('dim', '→')} ${r.fix}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { preflightChecks, depsFinding, formatPreflight, REPO_ROOT, MIN_NODE_MAJOR };
+
+// Standalone: `node scripts/gds/preflight.js` — exit 1 if any hard fail.
+if (require.main === module) {
+  const results = preflightChecks();
+  console.log(formatPreflight(results, { color: process.stdout.isTTY, heading: true }));
+  process.exit(results.some((r) => r.level === 'fail') ? 1 : 0);
+}

package/scripts/gds/provision.js

@@ -47,6 +47,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const cp = require('node:child_process');
+const crypto = require('node:crypto');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
@@ -180,7 +181,23 @@ function loadDeps() {
   const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning'));
   // eslint-disable-next-line global-require
   const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
-  _deps = { pool, provisioning, DoApi };
+  // Cross-site identity (ADR 0141 §4, task #1002109). Resolve the hub-side module by a
+  // VARIABLE key, gated on isModuleEnabled — the module-loader's own dynamic-dispatch
+  // pattern (the run-unit-tests.js precedent), NOT a static 'modules/platform-identity/'
+  // literal that would couple this publishable core file to an instance-EXCLUDED module
+  // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
+  // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
+  // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
+  let platformIdentity = null, hubKeys = null;
+  const PI_KEY = 'platform-identity';
+  let piEnabled = false;
+  try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
+  if (piEnabled) {
+    const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
+    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
+    catch { platformIdentity = null; hubKeys = null; }
+  }
+  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
   return _deps;
 }
 
@@ -279,6 +296,14 @@ function standaloneMigrateCmd(inst, { privileged = false } = {}) {
     ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`
     : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`;
 }
+// Regenerate the instance's whole-file navigation docs (session-log index) from the pinned core,
+// AFTER the pull+install+migrate — the standalone analogue of the monorepo's deploy-prod.sh regen
+// block (ADR 0110 §2, task 1002314). Best-effort + LOUD (the script always exits 0 + prints
+// ::ERROR:: on a generator failure) so a stale/absent nav doc never fails a deploy. Run with
+// cwd = standaloneRoot so resolveInstanceRoot() writes into the instance repo. Without this a
+// standalone instance's docs never refresh on deploy — the gap the owner hit ("docs didn't
+// transfer from primea"): its bespoke pull-deploy regenerated nothing.
+function standaloneRegenDocsCmd() { return `node ${CORE_PKG_DIR}/scripts/gds/regen-instance-docs.js`; }
 
 // ── STANDALONE scaffold (ADR 0108 / 0125, task 2055) ──────────────────────────
 // The MISSING first leg of the greenfield "one guided flow": provision.js used to
@@ -325,7 +350,54 @@ function instanceInitSpec(inst, { ownerLogin } = {}) {
 // dist/ + secrets OUT of the commit, while the vendored core tarball (vendor/*.tgz)
 // and package-lock.json stay IN — `npm ci` on deploy resolves the pinned core from
 // the committed tarball (ADR 0108), so they MUST be tracked.
-const INSTANCE_GITIGNORE = ['node_modules/', 'dist/', '.env', '.env.local', '*.log', ''].join('\n');
+//
+// docs/session-log-index.md is a WHOLE-FILE generated navigation doc (ADR 0110): every byte is
+// machine-owned, regenerated at deploy by regen-instance-docs.js (task 1002314) into the served
+// tree. Untracked so `git reset --hard origin/main` never wipes it and no branch can diff it —
+// the same reasoning the core's own .gitignore applies to it. (docs/repo-map.md is listed for
+// parity/forward-compat; it is core-scoped today so a standalone instance doesn't generate its
+// own — see regenerateNavDocs() in upgrade.js — but ignoring it costs nothing and prevents a
+// stray future write from entering the tree.)
+const INSTANCE_GITIGNORE = [
+  'node_modules/', 'dist/', '.env', '.env.local', '*.log',
+  '# Whole-file generated navigation docs — regenerated at deploy (ADR 0110, task 1002314).',
+  'docs/session-log-index.md', 'docs/repo-map.md', '',
+].join('\n');
+
+// A PRE-BUILT @bongos/core tarball this control plane can vendor into a NEW instance
+// WITHOUT rebuilding from source — the consumer-control-plane fix (task 1002275).
+//
+// The scaffold's default core-install path rebuilds the tarball with package-core.js,
+// which enumerates GIT-TRACKED files (`git -C REPO_ROOT ls-tree`). That works from a core
+// SOURCE checkout, but NOT when this runner is ITSELF a consumer instance whose core is an
+// installed npm dependency: provision.js then runs out of node_modules/@bongos/core, so
+// REPO_ROOT points INSIDE gitignored node_modules, git sees ZERO tracked files there, and
+// package-core aborts ("the core set is EMPTY") — the scaffold never pushes and the freshly
+// created repo is left EMPTY (seen live: trial/test on cloudbongos.com).
+//
+// But the exact pinned tarball this instance installed FROM is on disk, named by its own
+// package.json ("@bongos/core": "file:vendor/bongos-core-<v>.tgz"). Reuse it: byte-identical,
+// already proven, and the child pins the SAME core the hub runs. Returns an absolute .tgz
+// path, or null on a source checkout (no `file:` core pin) — where package-core.js is the
+// right, unchanged path. `instanceRoot` defaults to $BONGOS_INSTANCE_ROOT (what
+// infra/core-node.sh resolves against) else process.cwd() (the runner's WorkingDirectory).
+// fs injectable for tests. PURE-ish (fs reads only, no mutation → dry-run safe).
+function installedCoreTarball({ instanceRoot, fsImpl = fs } = {}) {
+  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
+  catch { return null; }               // no/unreadable package.json → treat as a source checkout
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  // Both scope aliases the loader accepts (infra/core-node.sh checks the same two).
+  for (const name of ['@bongos/core', '@cloudbongos/core']) {
+    const m = /^file:(.+\.tgz)$/.exec(String(deps[name] || '').trim());
+    if (m) {
+      const abs = path.resolve(root, m[1]);
+      if (fsImpl.existsSync(abs)) return abs;   // a dangling pin (tarball pruned) → fall through to null
+    }
+  }
+  return null;
+}
 
 // Clone the (empty) target_ref → standaloneRoot → materialize config/ + .claude/ + a
 // file:-pinned @bongos/core + lockfile (via `bongos init --vendor-core`, task 2053)
@@ -366,11 +438,19 @@ async function scaffoldStandaloneRepo(inst, deps) {
     } catch { /* fall back to the repo owner */ }
   }
 
-  // 1. clone the (possibly empty) repo, then force the initial branch to `main` (an empty
-  //    clone leaves an unborn HEAD). A re-run after a partial clone reuses the existing dir.
+  // 1. Materialize the working tree + set the initial branch to `main`. A freshly-created
+  //    instance repo is EMPTY (github-repos.createUserRepo, auto_init:false), so there is
+  //    NOTHING to clone — and a git DEPLOY KEY is per-repo, so the shared PROVISION_GIT_SSH_ALIAS
+  //    key (e.g. `github-instances`, a deploy key scoped to ONE repo) can't even READ a
+  //    consumer's brand-new repo under their own account: `git clone` 500s with "Repository not
+  //    found." This is the clone-side twin of the task-1002317 push bug. So `git init` locally
+  //    instead of cloning, and set `origin` to the SSH remote for the no-token fallback push
+  //    below; the OAuth-preferred push (its token CREATED the repo, so it can write) handles the
+  //    upload for consumer repos. A re-run after a partial init reuses the existing dir.
   if (!fs.existsSync(path.join(root, '.git'))) {
-    exec(`mkdir -p ${path.posix.dirname(root)}`);
-    exec(`git clone ${remote} ${root}`);
+    exec(`mkdir -p ${root}`);
+    exec(`git -C ${root} init -q`);
+    exec(`git -C ${root} remote add origin ${remote}`);
   }
   exec(`git -C ${root} checkout -B main`);
 
@@ -400,9 +480,19 @@ async function scaffoldStandaloneRepo(inst, deps) {
     log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
     exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --registry-core`);
   } else {
-    log(`  [scaffold] core install: vendored tarball (offline default)`);
-    exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
-    const tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    // Vendored tarball. PREFER a pre-built pinned tarball this control plane already has
+    // (a consumer instance's own `file:` core pin) — rebuilding via package-core.js aborts
+    // with an EMPTY core set when this runner IS a consumer instance (REPO_ROOT is inside
+    // gitignored node_modules), which left new repos empty (task 1002275). Only rebuild
+    // from source when there is no such pin (a genuine core source checkout).
+    let tgz = installedCoreTarball({ instanceRoot: deps.instanceRoot });
+    if (tgz) {
+      log(`  [scaffold] core install: reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
+    } else {
+      log(`  [scaffold] core install: building a fresh vendored tarball from source (package-core.js)`);
+      exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
+      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    }
     exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --vendor-core ${tgz}`);
   }
 
@@ -412,8 +502,38 @@ async function scaffoldStandaloneRepo(inst, deps) {
   exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
   exec(`git -C ${root} add -A`);
   exec(`git -C ${root} commit -m "chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)"`, { allowFail: true });
-  exec(`git -C ${root} push -u origin main`);
-  log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main`);
+  // Push. A GitHub DEPLOY KEY is per-repo, so the box's shared key can't write to a NEW
+  // project repo — the second empty-repo cause (task 1002317). PREFER the instance owner's
+  // OAuth token (it CREATED the repo via github-repos.createUserRepo, so `public_repo`
+  // already grants write). The token rides a chmod-600 git credential-store file — never
+  // the logged command or makeExec's env (both are surfaced) — and is removed right after
+  // (finally, so a failed push can't leave it on disk). No token (org-owned repo, or
+  // secret-box off) → fall back to the SSH `origin` push (unchanged; e.g. an instance whose
+  // matching deploy key was cloned into origin). `deps.getGithubToken` is injectable for
+  // tests; production resolves it lazily against the core db slice with the runner's pool.
+  let ownerToken = null;
+  if (inst.owner_builder_id) {
+    try {
+      const fetchTok = deps.getGithubToken
+        || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db }));
+      const r = await fetchTok(inst.owner_builder_id);
+      ownerToken = r && r.token ? r.token : null;
+    } catch (e) { log(`  [scaffold] owner OAuth token lookup failed (${e && e.message}) — using the SSH remote`); }
+  }
+  if (ownerToken) {
+    const credFile = path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`);
+    writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+    const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+    try {
+      exec(`git -C ${root} -c credential.helper='store --file=${credFile}' push ${httpsUrl} HEAD:main`);
+      log(`  [scaffold] pushed to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
+    } finally {
+      exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+  } else {
+    exec(`git -C ${root} push -u origin main`);
+    log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main (SSH origin)`);
+  }
   return { ok: true, scaffolded: true };
 }
 
@@ -562,7 +682,7 @@ function provisionedEnvPrefix() {
 // the hall on this host + OAuth uses the real callback origin — without them the pack
 // stays at neutral localhost and the hall never loads (task 1972). No domain yet
 // (bring-your-own deferred, ADR 0111 §4) ⇒ origins stay neutral until one is set.
-function webEnvBody(inst, { clientId = '', clientSecret = '' } = {}) {
+function webEnvBody(inst, { clientId = '', clientSecret = '', federation = null } = {}) {
   const prefix = provisionedEnvPrefix();
   const origin = inst.domain ? `https://${inst.domain}` : '';
   const originLines = origin
@@ -583,7 +703,11 @@ ${prefix}_OAUTH_ORIGIN=${origin}
   // Manifest flow (placeManifestCreds fetches them control-plane-side + re-writes this
   // file with clientId/clientSecret set), or the manual oauth-secret.js placement. On
   // the first provision write they are blank placeholders the flow fills later.
-  const credComment = clientId || clientSecret
+  const credComment = federation
+    ? `# Provisioned by scripts/gds/provision.js (ADR 0111). This instance FEDERATES sign-in
+# through the Cloud Bongos hub (ADR 0141 §4) — it needs no GitHub app of its own, so the
+# GitHub client id/secret below stay blank; the ${prefix}_HUB_* block drives sign-in.`
+    : clientId || clientSecret
     ? `# Provisioned by scripts/gds/provision.js (ADR 0111). OAuth app creds placed via the
 # GitHub App Manifest flow (ADR 0133) — the owner clicked one link; no secret was pasted.`
     : `# Provisioned by scripts/gds/provision.js (ADR 0111). Fill the OAuth app creds via the
@@ -602,6 +726,20 @@ ${prefix}_OAUTH_ORIGIN=${origin}
   const firstAdminLine = ownerRepo && ownerRepo.owner
     ? `${prefix}_FIRST_ADMIN=${ownerRepo.owner}\n`
     : '';
+  // Cross-site identity federation block (ADR 0141 §4, task #1002109). Present only for
+  // a HOSTED (federated) instance: flips auth.idp ON via the env override branding.js
+  // reads (idpEnabled), and carries the hub origin, this instance's per-client secret
+  // (authenticates it TO the hub, server-to-server), and the hub's PUBLIC key (verifies
+  // the CLI's hub-signed assertion offline). All written straight to this chmod-600
+  // file — never through a browser or chat (the ADR 0133 secret-placement posture).
+  const fedLines = federation
+    ? `${prefix}_AUTH_IDP=true
+${prefix}_HUB_ORIGIN=${federation.hubOrigin}
+${prefix}_HUB_CLIENT_ID=${federation.clientId}
+${prefix}_HUB_CLIENT_SECRET=${federation.clientSecret}
+${prefix}_HUB_PUBLIC_KEY=${federation.hubPublicKey}
+`
+    : '';
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
@@ -609,12 +747,88 @@ ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
 ${originLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-`;
+${fedLines}`;
 }
 function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');
 }
 
+// ── Cross-site identity: federate a hosted instance's sign-in through the hub ───
+// (ADR 0141 §4, task #1002109). The control plane IS the hub (cloudbongos.com), so
+// registration is a direct in-process call against the hub pool — no HTTP hop.
+
+// The hub's own public origin, written into each federated instance as
+// <PREFIX>_HUB_ORIGIN (what auth.js loadIdpConfig reads). Explicit PROVISION_HUB_ORIGIN
+// wins; otherwise the control plane's OWN public origin (<PREFIX>_PUBLIC_ORIGIN, the
+// env the hub already runs under). Null → not hub-configured → shouldFederate is false.
+function federationHubOrigin() {
+  const explicit = process.env.PROVISION_HUB_ORIGIN;
+  if (explicit) return String(explicit).replace(/\/+$/, '');
+  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
+  return own ? String(own).replace(/\/+$/, '') : null;
+}
+
+// Whether provisioning should federate this instance's sign-in through the hub.
+// Dormant-by-default: true ONLY when the control plane is hub-configured (the
+// platform-identity module is present, a signing key is loadable, AND a hub origin
+// resolves), the instance is a CO-TENANT (the mothership-hosted shape whose web.env is
+// written locally — a `standalone` is owner-hosted and keeps its own GitHub app, the
+// self-hosted path; a `dedicated` droplet has no local web.env write yet, same gap the
+// ADR 0133 manifest flow leaves — see placeManifestCreds), and it has a public domain
+// (the origin the hub binds the CLI mint audience to — the #1002108 account-takeover
+// fix). Returns { federate, reason } so the caller can log WHY it skipped. PURE-ish
+// (reads env + the injected module handles; no DB, no I/O).
+function shouldFederate(inst, deps) {
+  const { platformIdentity, hubKeys } = deps;
+  if (!platformIdentity || !hubKeys) return { federate: false, reason: 'platform-identity module not present (control plane is not the hub)' };
+  if (!hubKeys.hubSigningConfigured()) return { federate: false, reason: 'hub signing key not configured (<PREFIX>_HUB_SIGNING_KEY unset)' };
+  if (!federationHubOrigin()) return { federate: false, reason: 'hub origin not resolvable (set PROVISION_HUB_ORIGIN or <PREFIX>_PUBLIC_ORIGIN)' };
+  if (inst.hosting_shape !== 'co-tenant') return { federate: false, reason: `${inst.hosting_shape} keeps its own GitHub app (not the co-tenant hosted path)` };
+  if (!inst.domain) return { federate: false, reason: 'no domain yet — federation needs the instance public origin' };
+  return { federate: true, reason: null };
+}
+
+// Register this hosted instance as an sso_clients row on the HUB (fresh per-client
+// secret) and return the federation block to bake into its web.env (ADR 0141 §4).
+// SECURITY: `origin` MUST be the instance's EXACT public origin — the hub binds the
+// CLI-federation mint audience to it (the #1002108 fix), so a mismatch would break
+// device sign-in (and a wrong origin would be a takeover vector). client_id is the
+// (unique, DNS-safe) slug, so a re-provision rotates the SAME row's secret via
+// registerClient's ON CONFLICT rather than orphaning a client. redirect_uri lists both
+// callback prefixes the core may emit (/api/gds is what auth.js builds today) so the
+// hub's exact-match allow-list accepts the browser leg. --apply gates the real hub
+// write; dry-run returns a placeholder block (so webEnvBody can still be composed) + logs.
+async function federateInstance(inst, deps) {
+  const { db, platformIdentity, hubKeys, log, apply } = deps;
+  const origin = `https://${inst.domain}`;
+  const clientId = inst.slug;
+  const hubOrigin = federationHubOrigin();
+  const hubPublicKey = hubKeys.hubPublicKeyB64();
+  if (!hubPublicKey) throw new Error('hub signing key is set but unreadable — cannot derive HUB_PUBLIC_KEY');
+  const redirectUris = [
+    `${origin}/api/gds/auth/web/callback`,
+    `${origin}/api/bongos/auth/web/callback`,
+  ];
+  if (!apply) {
+    log(`  [federate] would register client '${clientId}' on the hub (origin ${origin}) + write ${provisionedEnvPrefix()}_HUB_* + AUTH_IDP into web.env`);
+    return { hubOrigin, clientId, clientSecret: '0'.repeat(43), hubPublicKey };
+  }
+  const clientSecret = crypto.randomBytes(32).toString('base64url');
+  // Best-effort owner github_id — nice for the hub catalog's ownership link, but
+  // nullable in registerClient, so a lookup miss must never fail the provision.
+  let ownerGithubId = null;
+  try {
+    const { rows } = await db.query('SELECT github_id FROM builders WHERE id = $1', [inst.owner_builder_id]);
+    ownerGithubId = rows[0] ? rows[0].github_id : null;
+  } catch { /* non-fatal */ }
+  await platformIdentity.registerClient(
+    { clientId, secret: clientSecret, name: inst.slug, redirectUris, origin, ownerGithubId },
+    { pool: db },
+  );
+  log(`  [federate] registered client '${clientId}' on the hub (origin ${origin})`);
+  return { hubOrigin, clientId, clientSecret, hubPublicKey };
+}
+
 // The Cloudflare zone a hostname's A record lives in. Cloudflare zones are
 // registrable domains, which for the common case is the last two DNS labels
 // (mercury.example.com → example.com; apex example.com → example.com). Multi-part
@@ -925,6 +1139,28 @@ async function provisionInstance(inst, deps) {
   if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
   const patch = {};
 
+  // ── cross-site identity: register hub federation (ADR 0141 §4, task #1002109) ──
+  // Computed BEFORE the shape steps so the co-tenant web.env write (step 3) bakes it
+  // in — the instance comes up already federated, no post-hoc restart. Dormant unless
+  // the control plane is hub-configured AND the shape/domain qualify (shouldFederate);
+  // otherwise the instance owns its auth (direct GitHub), byte-identically to today.
+  let federation = null;
+  {
+    const fed = shouldFederate(inst, deps);
+    if (fed.federate) {
+      federation = await federateInstance(inst, deps);
+      log(`  [federate] ${inst.slug} → hub sign-in (auth.idp on) — no GitHub app of its own`);
+      if (apply) {
+        await provisioning.recordEvent(db, {
+          instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'federated',
+          detail: `sign-in federated to the hub (client ${inst.slug}, origin https://${inst.domain})`, actor: 'runner',
+        }).catch(() => {});
+      }
+    } else {
+      log(`  [federate] skipped (${fed.reason}) — instance owns its auth (direct GitHub)`);
+    }
+  }
+
   // ── step 1: server ───────────────────────────────────────────────────────
   // The A-record target for step 5's DNS UPSERT:
   //   • co-tenant  → PROVISION_PUBLIC_IP (the box it runs on — under remote-exec that
@@ -1018,11 +1254,19 @@ async function provisionInstance(inst, deps) {
     // here should surface. Dedicated bakes the same step into cloud-init (dedicatedUserData).
     log('  [seed] first version (only if versions is empty)');
     boxExec(seedFirstVersionCmd(inst, { privileged }));
+    // Regenerate the whole-file navigation docs from the pinned core so a fresh/redeployed
+    // standalone instance's docs/ stays live (ADR 0110 §2, task 1002314) — the deploy-regen the
+    // bespoke pull scripts were missing. Best-effort: regen-instance-docs.js exits 0 even on a
+    // generator hiccup (LOUD ::ERROR::), so a stale nav doc never fails a provision.
+    if (standalone) {
+      log('  [docs] regenerate whole-file navigation docs (session-log index)');
+      boxExec(standaloneRegenDocsCmd(), { cwd: standaloneRoot(inst), allowFail: true });
+    }
   } else { log('    (db create + migrate + first-version seed run via cloud-init on the droplet)'); }
 
   // ── step 3: config + per-instance secrets ─────────────────────────────────
   log('  [config] per-instance web.env');
-  if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst), { mode: 0o600, sudo: true });
+  if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst, { federation }), { mode: 0o600, sudo: true });
   else log('    (baked into cloud-init)');
 
   // ── step 4: systemd unit + enable ─────────────────────────────────────────
@@ -1476,8 +1720,8 @@ async function main() {
   const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
   if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
 
-  let pool, provisioning, DoApi;
-  try { ({ pool, provisioning, DoApi } = loadDeps()); }
+  let pool, provisioning, DoApi, platformIdentity, hubKeys;
+  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys } = loadDeps()); }
   catch (e) { console.error(`cannot load DB layer (run this on the control plane): ${e.message}`); process.exit(1); }
 
   // Box-target executor (remote over SSH when PROVISION_REMOTE_HOST is set, else
@@ -1492,6 +1736,9 @@ async function main() {
     writeFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec, remoteHost: CONFIG.remoteHost }),
     controlWriteFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec: controlExec }),
     doApi: DoApi ? new DoApi({ dryRun: !apply, token: CONFIG.doToken, log: (m) => console.log('    ' + m) }) : null,
+    // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
+    // dormant; shouldFederate() then skips and the instance owns its auth (as today).
+    platformIdentity, hubKeys,
   };
 
   let result;
@@ -1518,8 +1765,8 @@ module.exports = {
   dbName, dbCreateCmd, migrateCmd, seedFirstVersionCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
   backupUnitName, backupServicePath, backupTimerPath, backupScriptPath, backupService, backupTimer,
   standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
-  // standalone scaffold (ADR 0108 / 0125, task 2055)
-  parseTargetRef, instanceRepoRemote, instanceInitSpec, scaffoldStandaloneRepo, coreVersionSafe,
+  // standalone scaffold (ADR 0108 / 0125, task 2055; consumer-core fix task 1002275)
+  parseTargetRef, instanceRepoRemote, instanceInitSpec, installedCoreTarball, scaffoldStandaloneRepo, coreVersionSafe,
   zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,
   caddyBlock, caddySnippetPath, healthzCmd, dedicatedUserData, nextFreePort,
   // executors + orchestration (injectable deps for tests)
@@ -1527,4 +1774,6 @@ module.exports = {
   cmdRunIntents, cmdReconcile, cmdStatus,
   // GitHub App Manifest flow (task 2080, ADR 0133)
   convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
+  // cross-site identity federation (ADR 0141 §4, task #1002109)
+  federationHubOrigin, shouldFederate, federateInstance,
 };

package/scripts/gds/publish-manifest.js

@@ -61,17 +61,20 @@ const PUBLISH_ALLOWLIST = [
   'modules/sessions/',
   'modules/autonomy/',
   'modules/security/',
+  'modules/governance/',     // configurable roles & permissions (BV1 goal 1000030, ADR 0151) — the rank/permission machinery publishes AS the open-source methodology (ADR 0065 §4 / ADR 0098); it is in PROTECTED_GLOBS for write-protection, NOT publish-exclusion. default:true.
   'modules/hall-ui/',
   'modules/status-ui/',
   'modules/dev-box/',
   'modules/discord/',
   'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
+  'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
   'config/branding.neutral.json',
   'config/modules.neutral.json',
   'config/design-tokens.neutral.json',
   'config/design-tokens.schema.json',  // the design-token contract (generic schema, no instance values)
   'config/hierarchy.neutral.json',
+  'config/governance.neutral.json',     // the starting role templates a fresh instance inherits (BV1.R96)
   // --- the portable methodology core, governance, and sanitized docs ---
   'CLAUDE.md',
   'README.md',
@@ -86,7 +89,9 @@ const PUBLISH_ALLOWLIST = [
   'docs/architecture.md',
   // Served to the hall / advertised by /api/bongos — a standalone that omits these
   // renders broken onboarding + API-reference pages (task 2078). Redacted like the
-  // rest of this docs section; the diagrams' .png/.svg regenerate on the box.
+  // rest of this docs section. Only the diagram .mmd SOURCES ship: the .png/.svg are
+  // gitignored (ADR 0122) so the tarball cannot carry them, and `bongos upgrade`
+  // regenerates them on the box via healDocAssets() (upgrade.js, task 1002441).
   'docs/onboarding/',                // primer.md + drachmae-and-karma.md + diagram sources (/builders/primer · /drachmae · /diagrams)
   // API artifacts (classification settled, task 2141): CORE-shipped STARTERS so a fresh
   // hall/docs render before first regen — but per-instance GENERATED. init + `bongos
@@ -206,6 +211,7 @@ const INSTANCE_EXCLUDE = [
   'config/modules.json',
   'config/devbox-app.json',
   'config/hierarchy.json',
+  'config/governance.json',
   'CODEOWNERS',              // names the owner (a protected surface, excluded as identity)
   // instance SEED migrations — this host's scope-truth SQL (planning seeds, world data).
   // ADR 0105: a consumer's core must not carry them; migrate.sh reads instance seeds from
@@ -250,6 +256,21 @@ const INSTANCE_EXCLUDE = [
   'docs/design/container-exterior-tiles.md',
   'docs/design/container-interior.md',
   'docs/design/world-map-scroll.md',
+  // instance-HISTORY ADRs (task 1002219 / audit H5). These record THIS platform-family's own
+  // migration + identity history (the amazonprimea→cloudbongos lift, the standalone reprovision,
+  // the cloudbongos identity hub) — they are inherently full of the prior instance's name/owner and
+  // genericize to nothing (unlike a portable methodology ADR). docs/adr/ is allowlisted wholesale for
+  // the portable decision records; these three stay in this repo and never ship in the core, mirroring
+  // the instance-recipe / game-design carve-outs above. (The portable ADRs + the README index still publish.)
+  'docs/adr/0139-platform-history-migration-to-cloudbongos.md',
+  'docs/adr/0140-cloudbongos-standalone-reprovision.md',
+  'docs/adr/0141-cross-site-identity-federated-hub-idp.md',
+  // hall-preview FIXTURES (task 1002219 / audit H5) — the local hall-UI preview harness's sample
+  // data is a snapshot of THIS instance's builders/goals/tasks (owner login, world name, prior
+  // instance name), pure instance identity. The harness code stays portable; only the OTB data is
+  // carved out, so a consumer core never ships customer-zero's directory. (Fixtures remain in-repo
+  // for local dev — this only affects what package-core publishes.)
+  'scripts/hall-preview/fixtures/',
   'blockers/',
   'limitations/',
   'generative-ideas.md',

package/scripts/gds/reauth.js

@@ -39,6 +39,9 @@
 const { spawn } = require('node:child_process');
 const lib = require('./cli-lib');
 
+// lib.API_BASE is session-aware (task 1002427), so both URLs name the instance the
+// builder is actually signed into — not this checkout's branding default, which is
+// what sent a cloudbongos.com builder to a localhost:3000 click-path.
 const HALL_URL = `${lib.API_BASE}/builders`;
 // The "Re-issue CLI token" button lives on the Settings page (under "CLI
 // Access"), not the hall profile — open the builder right where the button is.
@@ -56,9 +59,10 @@ function openInBrowser(url) {
     case 'win32':
       // rundll32's FileProtocolHandler opens a URL without going through a
       // shell, so (unlike `cmd /c start`) shell metacharacters in the URL are
-      // never interpreted. Defense-in-depth: today the URL is a constant
-      // (GDS_API_BASE + '/builders'), but this keeps it safe if that ever
-      // becomes influenced by less-trusted input.
+      // never interpreted. This is now load-bearing, not hypothetical: since
+      // task 1002427 the URL derives from the session file's api_base (via the
+      // session-aware lib.API_BASE), not from a bare env/branding constant. That
+      // file is the builder's own 0600 config, but it IS file-derived input.
       cmd = 'rundll32';
       args = ['url.dll,FileProtocolHandler', url];
       break;