@bongos/core 1.18.0 → 1.18.18

package/tests/platform_boot.mjs

@@ -10,9 +10,16 @@
 import assert from 'node:assert/strict';
 import { test, before, after } from 'node:test';
 import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import platformMod from '../src/platform-server.js';
+import loader from '../src/module-loader/loader.js';
 
-const { buildPlatformApp } = platformMod;
+const { buildPlatformApp, startBackgroundServices } = platformMod;
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 let server;
 let port;
@@ -168,3 +175,95 @@ test('R60: the served hall injects window.__MODULES__ (feature-module flags) syn
   assert.equal(typeof parsed.enabled['dev-box'], 'boolean');
   assert.equal(typeof parsed.enabled.discord, 'boolean');
 });
+
+// ---------------------------------------------------------------------------
+// task 1002419 — the platform entrypoint must actually START the module pollers.
+//
+// Regression fixture for a silent, high-blast-radius outage: startModulePollers
+// had ZERO callers after the game entrypoint (server.js) was retired, so on a
+// standalone instance EVERY module poller was dead — most visibly the lifecycle
+// publish-reconciler, which is what drives 'confirmed' tasks to 'shipped'. Eleven
+// tasks stranded at 'confirmed' (oldest 6.2 days) with nothing in any log to say
+// why: a poller that is never started is indistinguishable from one with nothing
+// to do. Both tests below are DB-free.
+// ---------------------------------------------------------------------------
+
+test('task 1002419: startBackgroundServices starts the enabled modules’ pollers', async () => {
+  // The wiring resolves a real, ENABLED module poller. lifecycle is default:true
+  // and declares contributes.pollers:["publish-reconciler"], so it must appear.
+  loader._reset();
+  let keys = [];
+  try {
+    const started = startBackgroundServices();
+    keys = started.map((p) => `${p.key}/${p.poller}`);
+    assert.ok(
+      keys.includes('lifecycle/publish-reconciler'),
+      `the lifecycle publish-reconciler poller must start (got: ${keys.join(', ') || 'none'})`
+    );
+  } finally {
+    // Clear the real (unref'd) timers this just started so the suite leaves none.
+    // The stopped count is also the loader's own record of what it started, so it
+    // must match what startBackgroundServices reported.
+    const stopped = await loader.stopModulePollers();
+    assert.equal(stopped, keys.length, 'stopModulePollers stops exactly what was started');
+    loader._reset();
+  }
+});
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const s = net.createServer();
+    s.on('error', reject);
+    s.listen(0, '127.0.0.1', () => {
+      const { port } = s.address();
+      s.close(() => resolve(port));
+    });
+  });
+}
+
+test('task 1002419: a real `node src/platform-server.js` boot announces the reconciler', async () => {
+  // The mutation-proof half. The test above would still pass if the entry block
+  // stopped calling startBackgroundServices(); this one spawns the entrypoint the
+  // way docker-entrypoint.sh does and asserts the poller announces itself in the
+  // boot log — so deleting the call site turns it red.
+  const port = await freePort();
+  const child = spawn(process.execPath, [path.join(REPO_ROOT, 'src', 'platform-server.js')], {
+    cwd: REPO_ROOT,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      HOST: '127.0.0.1',
+      // Push every first-fire far past the life of this test: we assert the
+      // START announcement, never a sweep, so no poller ever touches Postgres.
+      PUBLISH_RECONCILE_FIRST_MS: '3600000',
+      ROUTINE_PEER_VOTE_FIRST_MS: '3600000',
+    },
+  });
+
+  try {
+    const log = await new Promise((resolve, reject) => {
+      let out = '';
+      const timer = setTimeout(
+        () => reject(new Error(`platform-server did not announce the reconciler within 20s. Log:\n${out}`)),
+        20_000
+      );
+      const onData = (d) => {
+        out += d;
+        if (/\[publish-reconciler\] started/.test(out)) {
+          clearTimeout(timer);
+          resolve(out);
+        }
+      };
+      child.stdout.on('data', onData);
+      child.stderr.on('data', onData);
+      child.on('error', (e) => { clearTimeout(timer); reject(e); });
+      child.on('exit', (code) => {
+        clearTimeout(timer);
+        reject(new Error(`platform-server exited early (code ${code}). Log:\n${out}`));
+      });
+    });
+    assert.match(log, /\[publish-reconciler\] started — sweeping confirmed→shipped every \d+s/);
+  } finally {
+    child.kill('SIGKILL');
+  }
+});

package/tests/post_login_landing.mjs

@@ -0,0 +1,42 @@
+// tests/post_login_landing.mjs — the configurable post-sign-in landing (task 1002240).
+//
+// postLoginLanding(brand) resolves the redirect target used after a successful
+// web sign-in when NO explicit ?return= / same-apex Referer was carried. It is
+// the ONE seam that lets a platform-home instance (cloudbongos.com) land a
+// visitor back on its orbs (/gate/) instead of the builders' hall, while every
+// other instance keeps the portable '/builders' default (the hall always
+// exists; a /gate/ orbs site does not). Pure over an injected brand pack, and
+// hardened through the SAME open-redirect allowlist as ?return= (safeReturnTo),
+// so a misconfigured landing can never become an open redirect.
+//
+// Pure function, no DB — requiring the route module does not open a pool.
+
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { postLoginLanding } = require('../src/bongos/routes/auth.js');
+
+let pass = 0, fail = 0;
+function ok(cond, msg) {
+  if (cond) { pass++; console.log(`  ok  ${msg}`); }
+  else { fail++; console.log(`  FAIL ${msg}`); }
+}
+
+console.log('\npostLoginLanding — portable default is the hall:');
+ok(postLoginLanding({}) === '/builders', 'no landing config → /builders');
+ok(postLoginLanding({ landing: {} }) === '/builders', 'empty landing block → /builders');
+// No-arg path reads the real committed neutral pack, which ships postLogin:'/builders'.
+ok(postLoginLanding() === '/builders', 'committed neutral pack → /builders');
+
+console.log('\npostLoginLanding — an instance lands visitors on its own front door:');
+ok(postLoginLanding({ landing: { postLogin: '/gate/' } }) === '/gate/', 'cloudbongos orbs → /gate/');
+ok(postLoginLanding({ landing: { postLogin: '/gate/?entered=1' } }) === '/gate/?entered=1', 'relative path with query preserved');
+
+console.log('\npostLoginLanding — a misconfigured landing can never become an open redirect:');
+ok(postLoginLanding({ landing: { postLogin: 'https://evil.com/' } }) === '/builders', 'foreign https origin → fallback');
+ok(postLoginLanding({ landing: { postLogin: '//evil.com' } }) === '/builders', 'protocol-relative → fallback');
+ok(postLoginLanding({ landing: { postLogin: 'javascript:alert(1)' } }) === '/builders', 'javascript: scheme → fallback');
+ok(postLoginLanding({ landing: { postLogin: '/a\\b' } }) === '/builders', 'backslash path → fallback');
+ok(postLoginLanding({ landing: { postLogin: 42 } }) === '/builders', 'non-string value → fallback');
+
+console.log(`\nPost-login-landing tests: ${pass} passed, ${fail} failed`);
+if (fail) process.exit(1);

package/tests/preflight_checks.mjs

@@ -0,0 +1,72 @@
+// tests/preflight_checks.mjs
+//
+// Unit test for scripts/gds/preflight.js `preflightChecks()` (task 1002401,
+// onboarding-audit area 4) — the pure onboarding environment preflight shared by
+// /builder-setup and `bongos doctor`. DB-free and does zero real I/O: node
+// version, fs, and child_process are all injected, so we assert the real
+// decision logic (levels + fixes) without touching the machine.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { preflightChecks, formatPreflight } = require('../scripts/gds/preflight.js');
+
+const okSpawn = () => ({ status: 0, stdout: '1.2.3 (Claude Code)\n' });
+const badSpawn = () => ({ error: Object.assign(new Error('spawn claude ENOENT'), { code: 'ENOENT' }) });
+const fsWith = (present) => ({ existsSync: () => present });
+const find = (results, title) => results.find((r) => r.title === title);
+
+test('all green: node>=22, deps present, claude launches', () => {
+  const r = preflightChecks({ nodeVersion: 'v22.5.0', fs: fsWith(true), spawn: okSpawn, env: {} });
+  assert.equal(find(r, 'Node').level, 'ok');
+  assert.equal(find(r, 'Dependencies').level, 'ok');
+  assert.equal(find(r, 'claude CLI').level, 'ok');
+});
+
+test('node below v22 → fail with an upgrade fix', () => {
+  const r = preflightChecks({ nodeVersion: 'v18.19.0', fs: fsWith(true), spawn: okSpawn, env: {} });
+  const node = find(r, 'Node');
+  assert.equal(node.level, 'fail');
+  assert.match(node.fix, /22|nvm|nodejs/);
+});
+
+test('missing node_modules → warn (non-fatal) with `npm ci` fix', () => {
+  const r = preflightChecks({ nodeVersion: 'v22.0.0', fs: fsWith(false), spawn: okSpawn, env: {} });
+  const deps = find(r, 'Dependencies');
+  assert.equal(deps.level, 'warn');
+  assert.match(deps.fix, /npm ci/);
+});
+
+test('claude not launchable → fail naming SUBAGENT_SPAWN_FAILED + install fix', () => {
+  const r = preflightChecks({ nodeVersion: 'v22.0.0', fs: fsWith(true), spawn: badSpawn, env: {} });
+  const claude = find(r, 'claude CLI');
+  assert.equal(claude.level, 'fail');
+  assert.match(claude.detail, /SUBAGENT_SPAWN_FAILED/);
+  assert.match(claude.fix, /@anthropic-ai\/claude-code|OTB_CLAUDE_BIN/);
+});
+
+test('OTB_CLAUDE_BIN is used as the probe binary and labelled', () => {
+  let seenBin = null;
+  const spy = (bin) => { seenBin = bin; return { status: 0, stdout: 'x\n' }; };
+  const r = preflightChecks({ nodeVersion: 'v22.0.0', fs: fsWith(true), spawn: spy, env: { OTB_CLAUDE_BIN: '/opt/claude' } });
+  assert.equal(seenBin, '/opt/claude');
+  assert.match(find(r, 'claude CLI').detail, /via OTB_CLAUDE_BIN/);
+});
+
+test('a thrown existsSync is treated as deps-missing, never crashes', () => {
+  const fsThrows = { existsSync: () => { throw new Error('boom'); } };
+  const r = preflightChecks({ nodeVersion: 'v22.0.0', fs: fsThrows, spawn: okSpawn, env: {} });
+  assert.equal(find(r, 'Dependencies').level, 'warn');
+});
+
+test('formatPreflight renders glyphs + fixes and stays plain (no ANSI) by default', () => {
+  const r = preflightChecks({ nodeVersion: 'v18.0.0', fs: fsWith(false), spawn: badSpawn, env: {} });
+  const s = formatPreflight(r, { heading: true });
+  assert.match(s, /Checking your environment/);
+  assert.match(s, /✖ Node/);
+  assert.match(s, /! Dependencies/);
+  assert.match(s, /→ .*npm ci/);
+  assert.doesNotMatch(s, /\x1b\[/); // color:false ⇒ no ANSI escapes
+});

package/tests/provision.mjs

@@ -282,6 +282,10 @@ function recorder({ apply = false } = {}) {
     // Stub the DNS token-scope preflight (task 1980) so the composition stays hermetic
     // (no real CF call). Default: reachable; a test overrides it to exercise the block.
     checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+    // Owner OAuth token lookup for the scaffold push (task 1002317). Default: none →
+    // the scaffold takes the SSH `origin` fallback (so existing push assertions hold
+    // without touching the real db module). A test overrides it to exercise the token path.
+    getGithubToken: async () => null,
   };
   return { deps, cmds, writes, statuses };
 }
@@ -337,8 +341,9 @@ await ta('provisionInstance(standalone) SCAFFOLDS its repo, then syncs (pull + n
   const r = await P.provisionInstance({ ...coTenant, hosting_shape: 'standalone', target_ref: 'lars589/mercury' }, deps);
   assert.equal(r.ok, true);
   const joined = cmds.join('\n');
-  // scaffold leg (task 2055): clone → package-core → init --vendor-core → push
-  assert.match(joined, /git clone git@github-deploy:lars589\/mercury\.git/, 'clones the instance repo');
+  // scaffold leg (task 2055): git init → package-core → init --vendor-core → push
+  assert.match(joined, /git -C \S+ init -q/, 'inits the instance working tree (empty repo — nothing to clone)');
+  assert.match(joined, /git -C \S+ remote add origin git@github-deploy:lars589\/mercury\.git/, 'sets the instance repo as origin');
   assert.match(joined, /node scripts\/gds\/package-core\.js/, 'builds the core tarball');
   assert.match(joined, /init\.js --from .* --dir .* --no-seed --force --vendor-core /, 'materializes + file:-pins the core');
   assert.match(joined, /git -C .* push -u origin main/, 'pushes the scaffold');
@@ -349,9 +354,9 @@ await ta('provisionInstance(standalone) SCAFFOLDS its repo, then syncs (pull + n
   assert.match(joined, /node_modules\/@bongos\/core\/scripts\/migrate\.sh/, 'migrates from the INSTANCE root\'s core');
   assert.ok(!cmds.some((c) => /\.\/scripts\/migrate\.sh/.test(c)), 'standalone does NOT use the control-plane checkout migrate');
   assert.match(joined, /INSERT INTO versions/, 'standalone seeds its first version too (task 2119)');
-  // ordering: clone → package-core → init → push → pull → npm ci → migrate → service
+  // ordering: git init → package-core → init → push → pull → npm ci → migrate → service
   const idx = (re) => cmds.findIndex((c) => re.test(c));
-  assert.ok(idx(/git clone/) < idx(/package-core/), 'clone before tarball build');
+  assert.ok(idx(/git -C \S+ init -q/) < idx(/package-core/), 'git init before tarball build');
   assert.ok(idx(/package-core/) < idx(/init\.js/), 'tarball before init');
   assert.ok(idx(/init\.js/) < idx(/push -u origin main/), 'init before push');
   assert.ok(idx(/push -u origin main/) < idx(/git pull/), 'scaffold push before the deploy pull');
@@ -415,7 +420,7 @@ await ta('scaffoldStandaloneRepo: idempotent — a repo that already carries pac
     const { deps, cmds } = recorder({ apply: true });
     const res = await P.scaffoldStandaloneRepo({ slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo' }, deps);
     assert.equal(res.already, true);
-    assert.equal(cmds.length, 0, 'no clone/build/push when already scaffolded');
+    assert.equal(cmds.length, 0, 'no init/build/push when already scaffolded');
   } finally {
     P.CONFIG.standaloneBase = origBase;
     rmSync(tmp, { recursive: true, force: true });
@@ -431,9 +436,13 @@ async function scaffoldWithEnv(env) {
   P.CONFIG.standaloneBase = tmp;
   try {
     const { deps, cmds } = recorder({ apply: true });
+    // instanceRoot = the fresh base (no package.json → no `file:` core pin), so these
+    // vendored-path assertions stay deterministic: installedCoreTarball returns null and
+    // the scaffold rebuilds via package-core.js (task 1002275). A consumer-instance root
+    // (a real pin) takes the reuse path — covered by its own test below.
     await P.scaffoldStandaloneRepo(
       { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo' },
-      { ...deps, env },
+      { ...deps, env, instanceRoot: tmp },
     );
     return cmds.join('\n');
   } finally {
@@ -463,6 +472,122 @@ await ta('scaffoldStandaloneRepo: default (no registry env) stays on the vendore
   assert.ok(!/--registry-core/.test(joined));
 });
 
+// ── consumer control-plane core reuse (the empty-repo fix, task 1002275) ──────────
+// When the runner is ITSELF a consumer instance (its @bongos/core is a vendored npm dep,
+// not a source checkout), package-core.js can't rebuild the core from git (REPO_ROOT is
+// inside gitignored node_modules → an EMPTY core set → abort → no push → EMPTY repo, seen
+// live on cloudbongos.com for trial/test). Reuse the pinned tarball the instance runs.
+t('installedCoreTarball: reuses a consumer instance file: core pin; null on a source checkout', () => {
+  // consumer instance: package.json file:-pins the core AND the tarball is on disk → reuse it
+  const inst = mkdtempSync(join(tmpdir(), 'cptgz-consumer-'));
+  mkdirSync(join(inst, 'vendor'));
+  writeFileSync(join(inst, 'vendor', 'bongos-core-1.17.4.tgz'), 'x');
+  writeFileSync(join(inst, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': 'file:vendor/bongos-core-1.17.4.tgz' } }));
+  assert.equal(P.installedCoreTarball({ instanceRoot: inst }), join(inst, 'vendor', 'bongos-core-1.17.4.tgz'), 'reuses the pinned tarball');
+
+  // dangling pin (tarball pruned) → null, so the caller never points init at a missing file
+  rmSync(join(inst, 'vendor', 'bongos-core-1.17.4.tgz'));
+  assert.equal(P.installedCoreTarball({ instanceRoot: inst }), null, 'a dangling file: pin resolves to null');
+
+  // source checkout: a caret range (no file: pin) → null → the caller rebuilds via package-core.js
+  const src = mkdtempSync(join(tmpdir(), 'cptgz-source-'));
+  writeFileSync(join(src, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': '^1.17.4' } }));
+  assert.equal(P.installedCoreTarball({ instanceRoot: src }), null, 'a source checkout has no file: pin');
+
+  // no package.json at all → null
+  const bare = mkdtempSync(join(tmpdir(), 'cptgz-bare-'));
+  assert.equal(P.installedCoreTarball({ instanceRoot: bare }), null, 'no package.json → null');
+
+  // the @cloudbongos/core scope alias is honored too (infra/core-node.sh accepts both)
+  const alt = mkdtempSync(join(tmpdir(), 'cptgz-alt-'));
+  mkdirSync(join(alt, 'vendor'));
+  writeFileSync(join(alt, 'vendor', 'bongos-core-2.0.0.tgz'), 'x');
+  writeFileSync(join(alt, 'package.json'), JSON.stringify({ dependencies: { '@cloudbongos/core': 'file:vendor/bongos-core-2.0.0.tgz' } }));
+  assert.equal(P.installedCoreTarball({ instanceRoot: alt }), join(alt, 'vendor', 'bongos-core-2.0.0.tgz'), 'honors the @cloudbongos/core scope alias');
+
+  [inst, src, bare, alt].forEach((d) => rmSync(d, { recursive: true, force: true }));
+});
+
+await ta('scaffoldStandaloneRepo: on a consumer control plane it REUSES the pinned tarball — no package-core rebuild (task 1002275)', async () => {
+  // the control plane is itself a consumer instance: its package.json file:-pins the core
+  const cp = mkdtempSync(join(tmpdir(), 'cptgz-cp-'));
+  mkdirSync(join(cp, 'vendor'));
+  const pinned = join(cp, 'vendor', 'bongos-core-1.17.4.tgz');
+  writeFileSync(pinned, 'x');
+  writeFileSync(join(cp, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': 'file:vendor/bongos-core-1.17.4.tgz' } }));
+  const base = mkdtempSync(join(tmpdir(), 'cptgz-standalone-'));   // FRESH base → the scaffold proceeds
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    const { deps, cmds } = recorder({ apply: true });
+    await P.scaffoldStandaloneRepo(
+      { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo' },
+      { ...deps, instanceRoot: cp },
+    );
+    const joined = cmds.join('\n');
+    assert.ok(!/package-core\.js/.test(joined), 'does NOT rebuild the core from source (the empty-set abort path)');
+    assert.match(joined, new RegExp('init\\.js --from .* --no-seed --force --vendor-core ' + reEsc(pinned)), 'feeds the PINNED tarball to init --vendor-core');
+    assert.match(joined, /git -C \S+ remote add origin git@github-deploy:lars589\/demo\.git/, 'still targets the repo as origin');
+    assert.match(joined, /push /, 'still pushes the scaffold');
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    [cp, base].forEach((d) => rmSync(d, { recursive: true, force: true }));
+  }
+});
+
+// ── scaffold push via the owner OAuth token (task 1002317) ────────────────────────
+// Deploy keys are per-repo; a shared key can't write to a NEW project repo. Push with the
+// owner's token (which created the repo) instead — WITHOUT leaking it into a logged command.
+await ta('scaffoldStandaloneRepo: pushes via the owner OAuth token (not SSH), token never in a logged command (task 1002317)', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'push-tok-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    const { deps, cmds } = recorder({ apply: true });
+    const writes = [];
+    deps.writeFile = (p, body, opts) => { writes.push({ p, body, opts }); return { ok: true }; };
+    deps.getGithubToken = async () => ({ token: 'gho_SECRET_TOKEN_XYZ', scope: 'public_repo' });
+    await P.scaffoldStandaloneRepo(
+      { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo', owner_builder_id: 7 },
+      { ...deps, instanceRoot: base },
+    );
+    const joined = cmds.join('\n');
+    // SECURITY: the token must NEVER appear in a command string (makeExec logs commands)
+    assert.ok(!joined.includes('gho_SECRET_TOKEN_XYZ'), 'token never appears in any command string');
+    // pushes over HTTPS via the credential-store helper to HEAD:main, NOT the SSH origin
+    assert.match(joined, /credential\.helper='store --file=[^']*bongos-gitcred-demo[^']*' push https:\/\/x-access-token@github\.com\/lars589\/demo\.git HEAD:main/, 'pushes via the token credential-store helper');
+    assert.ok(!/push -u origin main/.test(joined), 'does NOT use the SSH origin push when a token is available');
+    // the credential file is written chmod 600, carries the token (content, NOT logged), then removed
+    const cred = writes.find((w) => /bongos-gitcred-demo/.test(w.p));
+    assert.ok(cred, 'wrote a credential-store file');
+    assert.equal(cred.opts && cred.opts.mode, 0o600, 'credential file is chmod 600');
+    assert.ok(String(cred.body).includes('gho_SECRET_TOKEN_XYZ'), 'credential file carries the token in its CONTENT (makeWriteFile logs only the path + byte count)');
+    assert.match(joined, /rm -f [^\n]*bongos-gitcred-demo/, 'removes the credential file after the push');
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+await ta('scaffoldStandaloneRepo: no owner token → falls back to the SSH origin push (unchanged; task 1002317)', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'push-ssh-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = base;
+  try {
+    const { deps, cmds } = recorder({ apply: true });   // default getGithubToken → null
+    await P.scaffoldStandaloneRepo(
+      { slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo', owner_builder_id: 7 },
+      { ...deps, instanceRoot: base },
+    );
+    const joined = cmds.join('\n');
+    assert.match(joined, /git -C [^\n]* push -u origin main/, 'falls back to the SSH origin push');
+    assert.ok(!/credential\.helper=/.test(joined), 'no token credential helper when there is no token');
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 await ta('provisionInstance is idempotent: an already-active instance is a no-op', async () => {
   const { deps, cmds } = recorder();
   const r = await P.provisionInstance({ ...coTenant, status: 'active' }, deps);
@@ -914,7 +1039,7 @@ await ta('provisionInstance(standalone, remote): EVERY box step runs control-pla
       assert.ok(!box.some((c) => re.test(c)), `${re} does NOT cross to the co-hosting box`);
     }
     // The scaffold leg was already control-local; confirm it stayed there.
-    assert.ok(control.some((c) => /git clone /.test(c)) && control.some((c) => /push -u origin main/.test(c)), 'scaffold clone+push stay control-local');
+    assert.ok(control.some((c) => /git -C \S+ init -q/.test(c)) && control.some((c) => /push -u origin main/.test(c)), 'scaffold init+push stay control-local');
     // NOTHING crosses to the remote box for a standalone — the whole point of the fix.
     assert.equal(box.length, 0, 'zero remote (co-hosting box) commands for a standalone');
     assert.equal(boxWrites.length, 0, 'zero remote writes for a standalone');
@@ -969,5 +1094,162 @@ await ta('teardownInstance(standalone, remote): tears down on the CONTROL PLANE
   assert.equal(box.length, 0, 'nothing crosses to the co-hosting box for a standalone teardown');
 });
 
+console.log('\ncross-site identity federation (ADR 0141 §4, task #1002109):');
+
+// Fakes for the hub-side module handles provisioning is injected. hubKeysOn = a
+// hub-configured control plane; hubKeysOff = signing key unset. fakePI records every
+// registerClient call so we can assert the (security-critical) origin binding.
+const hubKeysOn = { hubSigningConfigured: () => true, hubPublicKeyB64: () => 'HUBPUBKEYB64==' };
+const hubKeysOff = { hubSigningConfigured: () => false, hubPublicKeyB64: () => null };
+function fakePI() { const calls = []; return { calls, registerClient: async (a) => { calls.push(a); return { client_id: a.clientId }; } }; }
+function withEnv(vars, fn) {
+  const saved = {};
+  for (const k of Object.keys(vars)) { saved[k] = process.env[k]; if (vars[k] === undefined) delete process.env[k]; else process.env[k] = vars[k]; }
+  const restore = () => { for (const k of Object.keys(saved)) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; } };
+  // Promise-aware: for an async fn, restore only AFTER it settles (a plain try/finally
+  // would restore synchronously, before the awaited body ever reads the env).
+  let result;
+  try { result = fn(); } catch (e) { restore(); throw e; }
+  if (result && typeof result.then === 'function') return result.then((v) => { restore(); return v; }, (e) => { restore(); throw e; });
+  restore();
+  return result;
+}
+const HUB_ENV = { PROVISION_HUB_ORIGIN: 'https://cloudbongos.com', [`${NEUTRAL_PREFIX}_PUBLIC_ORIGIN`]: undefined };
+const coTenantWithDomain = { ...coTenant, domain: 'mercury.example.com' };
+
+t('federationHubOrigin: explicit PROVISION_HUB_ORIGIN wins; falls back to <PREFIX>_PUBLIC_ORIGIN; strips trailing slash; null when neither', () => {
+  withEnv({ PROVISION_HUB_ORIGIN: 'https://hub.example/', [`${NEUTRAL_PREFIX}_PUBLIC_ORIGIN`]: 'https://own.example' }, () => {
+    assert.equal(P.federationHubOrigin(), 'https://hub.example', 'explicit wins + trailing slash stripped');
+  });
+  withEnv({ PROVISION_HUB_ORIGIN: undefined, [`${NEUTRAL_PREFIX}_PUBLIC_ORIGIN`]: 'https://own.example/' }, () => {
+    assert.equal(P.federationHubOrigin(), 'https://own.example', 'falls back to the control plane\'s own public origin');
+  });
+  withEnv({ PROVISION_HUB_ORIGIN: undefined, [`${NEUTRAL_PREFIX}_PUBLIC_ORIGIN`]: undefined }, () => {
+    assert.equal(P.federationHubOrigin(), null, 'null when nothing is configured (→ not hub-configured)');
+  });
+});
+
+t('shouldFederate: dormant unless hub-configured AND co-tenant AND a domain is set', () => {
+  withEnv(HUB_ENV, () => {
+    // the happy path
+    assert.equal(P.shouldFederate(coTenantWithDomain, { platformIdentity: fakePI(), hubKeys: hubKeysOn }).federate, true, 'co-tenant + hub-configured + domain → federate');
+    // each guard, in turn
+    assert.equal(P.shouldFederate(coTenantWithDomain, { platformIdentity: null, hubKeys: hubKeysOn }).federate, false, 'module absent (not the hub) → skip');
+    assert.equal(P.shouldFederate(coTenantWithDomain, { platformIdentity: fakePI(), hubKeys: hubKeysOff }).federate, false, 'no signing key → skip');
+    assert.equal(P.shouldFederate({ ...coTenantWithDomain, domain: null }, { platformIdentity: fakePI(), hubKeys: hubKeysOn }).federate, false, 'no domain → skip');
+    // a standalone (owner-hosted) keeps its own GitHub app; a dedicated droplet has no local web.env bake yet
+    assert.equal(P.shouldFederate({ ...coTenantWithDomain, hosting_shape: 'standalone' }, { platformIdentity: fakePI(), hubKeys: hubKeysOn }).federate, false, 'standalone = self-hosted → skip');
+    assert.equal(P.shouldFederate({ ...coTenantWithDomain, hosting_shape: 'dedicated' }, { platformIdentity: fakePI(), hubKeys: hubKeysOn }).federate, false, 'dedicated → skip (no local web.env yet)');
+  });
+  // no hub origin resolvable (even with a signing key) → skip
+  withEnv({ PROVISION_HUB_ORIGIN: undefined, [`${NEUTRAL_PREFIX}_PUBLIC_ORIGIN`]: undefined }, () => {
+    assert.equal(P.shouldFederate(coTenantWithDomain, { platformIdentity: fakePI(), hubKeys: hubKeysOn }).federate, false, 'no hub origin → skip');
+  });
+});
+
+t('webEnvBody(federation): flips <PREFIX>_AUTH_IDP + writes the HUB_* block; GitHub creds stay blank; NO block without federation', () => {
+  const federation = { hubOrigin: 'https://cloudbongos.com', clientId: 'mercury', clientSecret: 'S'.repeat(43), hubPublicKey: 'PUB==' };
+  const b = P.webEnvBody(coTenantWithDomain, { federation });
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_AUTH_IDP=true`), 'flips the federation switch auth.js idpEnabled() reads');
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_HUB_ORIGIN=https://cloudbongos\\.com`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_HUB_CLIENT_ID=mercury`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_HUB_CLIENT_SECRET=S{43}`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_HUB_PUBLIC_KEY=PUB==`));
+  // a federated instance needs no GitHub app of its own → those creds stay blank
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=\\n`), 'GitHub id blank (federated)');
+  // regression: a non-federated write carries NO hub block + NO AUTH_IDP flip
+  const plain = P.webEnvBody(coTenantWithDomain);
+  assert.doesNotMatch(plain, /_AUTH_IDP=/, 'default (unset) never flips federation on');
+  assert.doesNotMatch(plain, /_HUB_ORIGIN=/, 'default write carries no hub block');
+});
+
+t('branding: <PREFIX>_AUTH_IDP env override flips auth.idp to a real boolean (idpEnabled reads === true)', () => {
+  const requireB = createRequire(import.meta.url);
+  const branding = requireB('../src/branding.js');
+  const neutral = { envPrefix: NEUTRAL_PREFIX, llmProjectName: 'x', identity: { productName: 'x', worldName: 'w' }, domains: { publicOrigin: 'https://x', buildersOrigin: 'https://x', statusOrigin: 'https://x', oauthOrigin: 'https://x' }, auth: { idp: false } };
+  const off = branding.resolveBranding({ neutral, instance: {}, env: {} });
+  assert.equal(off.auth.idp, false, 'unset → stays false (dormant default)');
+  const on = branding.resolveBranding({ neutral, instance: {}, env: { [`${NEUTRAL_PREFIX}_AUTH_IDP`]: 'true' } });
+  assert.equal(on.auth.idp, true, 'the string "true" coerces to boolean true (not the string, which would fail === true)');
+  assert.strictEqual(typeof on.auth.idp, 'boolean', 'coerced to a real boolean');
+});
+
+await ta('federateInstance(--apply): registers the client on the hub bound to the EXACT origin (the #1002108 takeover fix), returns the env block', async () => {
+  await withEnv(HUB_ENV, async () => {
+    const pi = fakePI();
+    const deps = { apply: true, log: () => {}, platformIdentity: pi, hubKeys: hubKeysOn, db: { query: async () => ({ rows: [{ github_id: 'gh-owner-1' }] }) } };
+    const block = await P.federateInstance(coTenantWithDomain, deps);
+    assert.equal(pi.calls.length, 1, 'registered exactly once');
+    const reg = pi.calls[0];
+    assert.equal(reg.origin, 'https://mercury.example.com', 'origin is the instance EXACT public origin (hub binds the mint audience to it)');
+    assert.equal(reg.clientId, 'mercury', 'client_id is the stable slug (re-provision rotates the same row)');
+    assert.ok(reg.redirectUris.includes('https://mercury.example.com/api/gds/auth/web/callback'), 'registers the exact browser callback the instance sends');
+    assert.equal(reg.ownerGithubId, 'gh-owner-1', 'threads the owner github_id for the catalog');
+    assert.ok(typeof reg.secret === 'string' && reg.secret.length >= 32, 'a strong per-client secret was generated');
+    // the block webEnvBody bakes in
+    assert.equal(block.hubOrigin, 'https://cloudbongos.com');
+    assert.equal(block.clientId, 'mercury');
+    assert.equal(block.clientSecret, reg.secret, 'the secret written to the instance is the one registered on the hub');
+    assert.equal(block.hubPublicKey, 'HUBPUBKEYB64==', 'the hub PUBLIC key (for offline assertion verify) rides along');
+  });
+});
+
+await ta('federateInstance(dry-run): registers NOTHING, returns a placeholder block (so webEnvBody can still compose)', async () => {
+  await withEnv(HUB_ENV, async () => {
+    const pi = fakePI();
+    const block = await P.federateInstance(coTenantWithDomain, { apply: false, log: () => {}, platformIdentity: pi, hubKeys: hubKeysOn, db: { query: async () => ({ rows: [] }) } });
+    assert.equal(pi.calls.length, 0, 'dry-run performs no hub write');
+    assert.equal(block.clientId, 'mercury');
+    assert.equal(block.hubPublicKey, 'HUBPUBKEYB64==');
+  });
+});
+
+await ta('provisionInstance(co-tenant, hub-configured): bakes the HUB block into web.env, records a "federated" event, registers the client', async () => {
+  await withEnv(HUB_ENV, async () => {
+    const { deps } = recorder({ apply: true });
+    const bodies = {}; const events = []; const pi = fakePI();
+    deps.writeFile = (p, body) => { bodies[p] = body; return { ok: true }; };
+    deps.provisioning.recordEvent = async (_db, e) => { events.push(e.event); };
+    deps.platformIdentity = pi; deps.hubKeys = hubKeysOn;
+    await P.provisionInstance(coTenantWithDomain, deps);
+    const env = bodies[P.webEnvPath(coTenantWithDomain)];
+    assert.ok(env, 'wrote the per-instance web.env');
+    assert.match(env, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_AUTH_IDP=true`), 'the co-tenant comes up already federated');
+    assert.match(env, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_HUB_CLIENT_SECRET=`), 'hub creds baked into web.env');
+    assert.ok(events.includes('federated'), 'records the federation event for the audit trail');
+    assert.equal(pi.calls.length, 1, 'registered the client on the hub');
+    assert.equal(pi.calls[0].origin, 'https://mercury.example.com');
+  });
+});
+
+await ta('provisionInstance: a NON-hub control plane (no module/key) does NOT federate — the instance owns its auth (unchanged)', async () => {
+  await withEnv(HUB_ENV, async () => {
+    const { deps } = recorder({ apply: true });
+    const bodies = {};
+    deps.writeFile = (p, body) => { bodies[p] = body; return { ok: true }; };
+    // default recorder has no platformIdentity/hubKeys → shouldFederate skips
+    await P.provisionInstance(coTenantWithDomain, deps);
+    const env = bodies[P.webEnvPath(coTenantWithDomain)];
+    assert.ok(env, 'wrote web.env');
+    assert.doesNotMatch(env, /_AUTH_IDP=/, 'no federation flip on a non-hub control plane');
+    assert.doesNotMatch(env, /_HUB_ORIGIN=/, 'no hub block — the direct-GitHub path, byte-identical to today');
+  });
+});
+
+await ta('provisionInstance(standalone, hub-configured): still NOT federated — owner-hosted keeps its own GitHub app', async () => {
+  await withEnv(HUB_ENV, async () => {
+    const { deps } = recorder({ apply: true });
+    const bodies = {}; const pi = fakePI();
+    deps.controlWriteFile = (p, body) => { bodies[p] = body; return { ok: true }; };
+    deps.writeFile = (p, body) => { bodies[p] = body; return { ok: true }; };
+    deps.platformIdentity = pi; deps.hubKeys = hubKeysOn;
+    await P.provisionInstance({ ...coTenantWithDomain, hosting_shape: 'standalone', target_ref: 'lars589/mercury' }, deps);
+    const env = bodies[P.webEnvPath({ ...coTenantWithDomain, hosting_shape: 'standalone' })];
+    assert.ok(env, 'wrote web.env');
+    assert.doesNotMatch(env, /_AUTH_IDP=/, 'standalone is the self-hosted path — no federation');
+    assert.equal(pi.calls.length, 0, 'no hub registration for a standalone');
+  });
+});
+
 console.log(`\nprovision: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);