@bongos/core 1.18.3 → 1.18.19

package/tests/hall_signout.mjs

@@ -0,0 +1,124 @@
+// tests/hall_signout.mjs — the hall sign-out contract (task 1002245).
+//
+// Regression guard for an owner-reported bug: signing out on any hall page
+// OTHER than the index left the builder signed in, and never reached the hub.
+// Root cause — the real sign-out (POST /auth/logout: revoke session + clear
+// cookies + emit the federated single-logout, ADR 0144) was wired only in the
+// index script (builders.js); every other page rendered the sign-out link via
+// shell.js as a bare <a href="/api/bongos/auth/logout">, which is a GET to a
+// POST-only endpoint — a dead click that never revoked anything.
+//
+// The fix centralised the handler in shell.js (which draws the sign-out control
+// on EVERY page). This test EXECUTES the real shell.js in a minimal DOM stub and
+// drives a click, proving: a sign-out anchor fires exactly one POST /auth/logout,
+// expires gds_session (host-only + apex) and legacy pms_session, prevents the
+// default GET navigation, and bounces home — and that ordinary links are left
+// alone. Pure vm + file-read (no DB/network) — runs in the DB-free unit gate.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
+
+// Boot shell.js under a permissive DOM stub for a given non-index page, then
+// dispatch a single click carrying `href` through the delegated listener wire()
+// registered. Returns the recorded side effects.
+function driveClick({ page = 'settings', href } = {}) {
+  const calls = { requests: [], cookies: [], assign: [], prevented: 0 };
+  const docListeners = {};
+
+  const makeEl = () => ({
+    dataset: {}, style: {}, title: '', textContent: '', hidden: false,
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; }, removeAttribute() {},
+    addEventListener() {}, querySelectorAll() { return []; },
+    appendChild() {}, focus() {}, click() {},
+    set innerHTML(_v) {}, get innerHTML() { return ''; },
+  });
+
+  const location = {
+    hostname: 'builders.cloudbongos.com',
+    origin: 'https://builders.cloudbongos.com',
+    pathname: '/' + page,
+    assign(u) { calls.assign.push(u); },
+  };
+
+  const api = {
+    request(method, p) {
+      calls.requests.push([method, p]);
+      return Promise.resolve({ status: 200, ok: true, data: { builder: { rank: 'metic' }, onboarding: { stages: [] } } });
+    },
+  };
+
+  const documentObj = {
+    body: { dataset: { page } },
+    documentElement: { dataset: {}, style: {}, classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } } },
+    getElementById() { return makeEl(); },
+    querySelectorAll() { return []; },
+    createElement() { return makeEl(); },
+    addEventListener(type, fn) { (docListeners[type] || (docListeners[type] = [])).push(fn); },
+    get cookie() { return ''; },
+    set cookie(v) { calls.cookies.push(v); },
+  };
+
+  const windowObj = {
+    __BRANDING__: {}, __MODULES__: { enabled: {} },
+    BongosClient: { createClient: () => api },
+    matchMedia: () => ({ matches: false, addEventListener() {} }),
+    localStorage: { getItem() { return null; }, setItem() {} },
+    location,
+    addEventListener() {},
+  };
+
+  const sandbox = { window: windowObj, document: documentObj, location, console, setTimeout, clearTimeout };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(SRC, sandbox, { filename: 'shell.js' });
+
+  const clickListeners = docListeners.click || [];
+  assert.ok(clickListeners.length > 0, 'wire() must register a document click listener');
+
+  const anchor = { getAttribute(name) { return name === 'href' ? href : null; } };
+  const ev = { target: { closest(sel) { return sel === 'a' ? anchor : null; } }, preventDefault() { calls.prevented++; } };
+  for (const fn of clickListeners) fn(ev);
+  return calls;
+}
+
+// Let the .then(finish, finish) in doLogout settle.
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+test('non-index sign-out click fires the real POST /auth/logout (not a dead GET)', async () => {
+  const calls = driveClick({ page: 'settings', href: '/api/bongos/auth/logout' });
+  await flush();
+  assert.ok(calls.prevented >= 1, 'the default GET navigation is prevented');
+  const logoutPosts = calls.requests.filter(([m, p]) => m === 'POST' && /\/auth\/logout$/.test(p));
+  assert.equal(logoutPosts.length, 1, `exactly one POST /auth/logout — got ${JSON.stringify(calls.requests)}`);
+});
+
+test('sign-out clears both session cookies (host-only + apex) and bounces home', async () => {
+  const calls = driveClick({ page: 'settings', href: '/api/bongos/auth/logout' });
+  await flush();
+  assert.ok(calls.cookies.some((c) => /gds_session=;/.test(c) && /Max-Age=0/.test(c)), 'gds_session expired (host-only)');
+  assert.ok(calls.cookies.some((c) => /gds_session=;/.test(c) && /Domain=\.cloudbongos\.com/.test(c)), 'gds_session expired (apex-scoped)');
+  assert.ok(calls.cookies.some((c) => /pms_session=;/.test(c)), 'legacy pms_session expired');
+  assert.deepEqual(calls.assign, ['/'], 'redirected home after logout');
+});
+
+test('the footer sign-out link (no id, bare href) is intercepted too', async () => {
+  // Same delegated match — the footer anchor renders as href="/api/bongos/auth/logout".
+  const calls = driveClick({ page: 'ranks', href: '/api/bongos/auth/logout' });
+  await flush();
+  assert.equal(calls.requests.filter(([m, p]) => m === 'POST' && /\/auth\/logout$/.test(p)).length, 1, 'footer sign-out also POSTs');
+});
+
+test('ordinary hall links are left untouched (no logout, no redirect)', async () => {
+  const calls = driveClick({ page: 'settings', href: '/builders/ranks' });
+  await flush();
+  assert.equal(calls.prevented, 0, 'a normal link is not intercepted');
+  assert.equal(calls.requests.filter(([, p]) => /\/auth\/logout$/.test(p)).length, 0, 'no logout POST for a normal link');
+  assert.deepEqual(calls.assign, [], 'no redirect for a normal link');
+});

package/tests/hook_user_agents.mjs

@@ -36,6 +36,16 @@ const hookFiles = fs.existsSync(HOOKS_DIR)
   ? fs.readdirSync(HOOKS_DIR).filter((f) => f.endsWith('.js')).sort()
   : [];
 
+// The neutral core does NOT carry .claude/hooks/ — it's instance-materialized and
+// package-excluded (PROTECTED_TOPOLOGY_EXCLUDE in scripts/gds/publish-manifest.js),
+// so a clean core checkout has no hooks to scan. Skip cleanly rather than fail the
+// assertions below (task 1002234, same class as tests/stop_refcheck.mjs's absent-hook
+// crash); this UA invariant is enforced on an instance whose hooks are materialized.
+if (hookFiles.length === 0) {
+  console.log('hook_user_agents: SKIP — no .claude/hooks/*.js in this checkout (instance-materialized; not in the neutral core).');
+  process.exit(0);
+}
+
 t('.claude/hooks exists and has hook files to check', () => {
   assert.ok(hookFiles.length > 0, `no hook .js files found under ${HOOKS_DIR}`);
 });

package/tests/idea_triage.mjs

@@ -0,0 +1,162 @@
+// tests/idea_triage.mjs
+//
+// task 1002447 — the guards `updateIdea` puts in front of a MERGE verdict, and
+// the SQL a triage verdict actually writes.
+//
+// Merge is the verb that gained storage in migration core_195: before it,
+// `status='merged'` recorded that a merge happened but never what it merged
+// into (`promoted_to_task_id` could not stand in — it is REFERENCES tasks(id)).
+// These guards are what stop the new column from collecting nonsense: an idea
+// merged into itself, into an idea that does not exist, or into one that was
+// itself already merged (a chain that reads as "folded into X" while X points
+// somewhere else again).
+//
+// DB-free: `modules/ideas/inbox.js` destructures `pool` off the doorway at
+// require time, so patching `pool.query` on that same object — BEFORE requiring
+// inbox.js — intercepts every query. No live Postgres needed.
+//
+// Run:  node tests/idea_triage.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const api = require('../src/module-api.js');
+
+// The fake table every query below reads from, plus a log of what was written.
+let rows = new Map();
+let queries = [];
+
+api.pool.query = async (sql, params = []) => {
+  queries.push({ sql, params });
+  if (/^\s*SELECT/i.test(sql)) {
+    const row = rows.get(String(params[0]));
+    return { rows: row ? [row] : [] };
+  }
+  // UPDATE … RETURNING — apply nothing, just echo a plausible row back so the
+  // caller's return value is shaped right.
+  const row = rows.get(String(params[0]));
+  return { rows: row ? [{ ...row }] : [] };
+};
+
+const inbox = require('../modules/ideas/inbox.js');
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  queries = [];
+  rows = new Map([
+    ['1', { id: '1', title: 'the duplicate', status: 'open', merged_into_idea_id: null }],
+    ['2', { id: '2', title: 'the canonical one', status: 'open', merged_into_idea_id: null }],
+    ['3', { id: '3', title: 'already folded away', status: 'merged', merged_into_idea_id: '2' }],
+  ]);
+  try {
+    await fn();
+    passed += 1;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed += 1;
+    console.log(`  FAIL  ${name}\n      ${err.message}`);
+  }
+}
+
+async function rejectsWith(code, fn) {
+  try {
+    await fn();
+  } catch (err) {
+    assert.equal(err.code, code, `expected ${code}, got ${err.code || err.message}`);
+    return err;
+  }
+  throw new Error(`expected ${code}, but the call resolved`);
+}
+
+// -- merge guards ----------------------------------------------------------
+
+await test('merging an idea into itself is refused', () =>
+  rejectsWith('MERGE_SELF', () => inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: 1 })));
+
+await test('merging into an idea that does not exist is refused', () =>
+  rejectsWith('MERGE_TARGET_NOT_FOUND', () => inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: 99 })));
+
+await test('merging into an already-merged idea is refused (no chains)', async () => {
+  const err = await rejectsWith('MERGE_TARGET_MERGED', () =>
+    inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: 3 }));
+  // The error names where the chain actually ends, so the caller can retarget.
+  assert.equal(err.merged_into, '2');
+});
+
+await test('merging into a live idea writes both the status and the target', async () => {
+  await inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: 2, triage_note: 'same ask' });
+  const update = queries.find((q) => /^\s*UPDATE/i.test(q.sql));
+  assert.ok(update, 'no UPDATE ran');
+  assert.match(update.sql, /merged_into_idea_id = \$\d+/);
+  assert.match(update.sql, /triage_note = \$\d+/);
+  assert.match(update.sql, /status = \$\d+/);
+  assert.ok(update.params.includes(2), 'the merge target never reached the query');
+});
+
+// A null clears the link — the un-merge path — and must skip the guards rather
+// than trip MERGE_TARGET_NOT_FOUND on a lookup of `null`.
+await test('clearing the merge link with null skips the target guards', async () => {
+  await inbox.updateIdea('1', { status: 'open', merged_into_idea_id: null });
+  assert.equal(queries.filter((q) => /^\s*SELECT/i.test(q.sql)).length, 0, 'looked up a null target');
+  const update = queries.find((q) => /^\s*UPDATE/i.test(q.sql));
+  assert.ok(update.params.includes(null));
+});
+
+// -- the status/target invariant (a target exists IFF the idea is merged) ---
+//
+// Without it, two ordinary PATCHes build the chain the no-chains guard exists to
+// stop: point A at B while leaving A open, then merge C into A — whose status
+// still reads 'open'. The DB CHECK in core_195 is the backstop; these are the
+// clean 400s in front of it.
+
+await test('setting a merge target without status=merged is refused', () =>
+  rejectsWith('MERGE_STATUS_REQUIRED', () => inbox.updateIdea('1', { merged_into_idea_id: 2 })));
+
+await test('un-merging while still claiming merged status is refused', () =>
+  rejectsWith('MERGE_STATUS_REQUIRED', () => inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: null })));
+
+await test('the no-chains guard reads the target COLUMN, not the target status', async () => {
+  // idea 4: pointed at 2 but left 'open' — the exact row the old status-based
+  // guard waved through.
+  rows.set('4', { id: '4', title: 'mis-set row', status: 'open', merged_into_idea_id: '2' });
+  await rejectsWith('MERGE_TARGET_MERGED', () =>
+    inbox.updateIdea('1', { status: 'merged', merged_into_idea_id: 4 }));
+});
+
+// -- the discard reason ----------------------------------------------------
+
+await test('a discard reason is written as the triage note', async () => {
+  await inbox.updateIdea('1', { status: 'discarded', triage_note: 'superseded by the new gate' });
+  const update = queries.find((q) => /^\s*UPDATE/i.test(q.sql));
+  assert.ok(update.params.includes('superseded by the new gate'));
+});
+
+await test('an oversize triage note is refused before it reaches the DB', async () => {
+  await rejectsWith('TRIAGE_NOTE_TOO_LONG', () =>
+    inbox.updateIdea('1', { status: 'discarded', triage_note: 'x'.repeat(1001) }));
+  assert.equal(queries.length, 0, 'a rejected note still hit the database');
+});
+
+// -- the reads carry the new columns ---------------------------------------
+
+await test('getIdea selects the triage-provenance columns', async () => {
+  await inbox.getIdea('1');
+  const select = queries.find((q) => /^\s*SELECT/i.test(q.sql));
+  assert.match(select.sql, /merged_into_idea_id/);
+  assert.match(select.sql, /triage_note/);
+});
+
+await test('listOpenIdeas selects the triage-provenance columns', async () => {
+  api.pool.query = async (sql, params = []) => { queries.push({ sql, params }); return { rows: [] }; };
+  await inbox.listOpenIdeas({ limit: 5 });
+  const select = queries.find((q) => /^\s*SELECT/i.test(q.sql));
+  assert.match(select.sql, /merged_into_idea_id/);
+  assert.match(select.sql, /triage_note/);
+});
+
+console.log(`\nIdea triage tests: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/idp_device_exchange.mjs

@@ -101,5 +101,98 @@ t('generateHubKeypair yields distinct keypairs', () => {
   assert.notEqual(a.publicKeyB64, b.publicKeyB64);
 });
 
+// --- Federated single-logout token (ADR 0144, task 1002238) ----------------
+// The hub mints a back-channel LOGOUT token (hub-keys.js mintHubLogoutToken) and
+// the instance verifies it OFFLINE (auth.js verifyHubLogoutToken) before revoking
+// the builder's local sessions. Same Ed25519 envelope as the login assertion, so
+// it must survive the SAME adversarial battery — PLUS the two token types must be
+// mutually non-interchangeable (a login assertion can't trigger a logout, and a
+// logout token can't mint a session).
+
+function mintLogout(overrides = {}, opts = {}) {
+  return hubKeys.mintHubLogoutToken(
+    { clientId: 'client-x', githubId: 42, ...overrides },
+    { signingKey, ...opts },
+  );
+}
+
+console.log('\nhub logout token mint → instance verify (roundtrip):');
+
+t('a valid logout token verifies, carries the subject + purpose, NO identity/rank', () => {
+  const p = auth.verifyHubLogoutToken(mintLogout(), { publicKey, clientId: 'client-x' });
+  assert.equal(p.sub, '42');
+  assert.equal(p.purpose, 'backchannel-logout');
+  assert.equal(p.aud, 'client-x');
+  assert.equal(p.iss, 'cloudbongos-hub');
+  assert.equal(p.github_login, undefined, 'a logout token must carry no identity');
+  assert.equal(p.rank, undefined);
+});
+
+console.log('\nadversarial (logout) — every one of these MUST be rejected:');
+
+t('wrong audience (a logout for instance A cannot be replayed against instance B)', () => {
+  assert.throws(() => auth.verifyHubLogoutToken(mintLogout(), { publicKey, clientId: 'other-client' }), /audience/);
+});
+
+t('expired logout token (minted 10 min ago; TTL is ~120s)', () => {
+  const stale = mintLogout({}, { nowMs: Date.now() - 10 * 60 * 1000 });
+  assert.throws(() => auth.verifyHubLogoutToken(stale, { publicKey, clientId: 'client-x' }), /expired/);
+});
+
+t('tampered payload (swap sub to another github_id) fails the signature', () => {
+  const [h, p, s] = mintLogout().split('.');
+  const payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8'));
+  payload.sub = '999';
+  const forged = `${h}.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.${s}`;
+  assert.throws(() => auth.verifyHubLogoutToken(forged, { publicKey, clientId: 'client-x' }), /signature/);
+});
+
+t('a different signing key is rejected', () => {
+  const otherPub = crypto.generateKeyPairSync('ed25519').publicKey;
+  assert.throws(() => auth.verifyHubLogoutToken(mintLogout(), { publicKey: otherPub, clientId: 'client-x' }), /signature/);
+});
+
+t('algorithm-confusion (alg → "none") is rejected', () => {
+  const [h, p, s] = mintLogout().split('.');
+  const hdr = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'));
+  hdr.alg = 'none';
+  const forged = `${Buffer.from(JSON.stringify(hdr)).toString('base64url')}.${p}.${s}`;
+  assert.throws(() => auth.verifyHubLogoutToken(forged, { publicKey, clientId: 'client-x' }), /alg|signature/);
+});
+
+t('malformed + missing-pubkey logout tokens are rejected (fail closed)', () => {
+  assert.throws(() => auth.verifyHubLogoutToken('not-a-jwt', { publicKey, clientId: 'client-x' }), /malformed/);
+  assert.throws(() => auth.verifyHubLogoutToken(mintLogout(), { publicKey: null, clientId: 'client-x' }), /public key/);
+});
+
+t('mintHubLogoutToken refuses without a signing key', () => {
+  assert.throws(() => hubKeys.mintHubLogoutToken({ clientId: 'c', githubId: 1 }, {}), /signing key/);
+});
+
+console.log('\nlogin/logout tokens are mutually NON-interchangeable:');
+
+t('a LOGIN assertion is NOT accepted as a logout token (no purpose)', () => {
+  assert.throws(() => auth.verifyHubLogoutToken(mint(), { publicKey, clientId: 'client-x' }), /purpose|logout/);
+});
+
+t('a LOGOUT token is NOT accepted as a login assertion (no identity)', () => {
+  assert.throws(() => auth.verifyHubAssertion(mintLogout(), { publicKey, clientId: 'client-x' }), /identity/);
+});
+
+console.log('\nlogout-token anti-replay (jti honored once):');
+
+t('a logout jti is fresh on first use, seen on replay, and evicted after expiry', () => {
+  const now = 1_000_000;
+  const exp = Math.floor(now / 1000) + 120; // seconds, ~120s out
+  assert.equal(auth.logoutTokenJtiSeenAndRecord('jti-abc', exp, now), false, 'first use is fresh (→ revoke)');
+  assert.equal(auth.logoutTokenJtiSeenAndRecord('jti-abc', exp, now), true, 'replay within TTL is seen (→ no-op)');
+  // A different jti is independent.
+  assert.equal(auth.logoutTokenJtiSeenAndRecord('jti-xyz', exp, now), false, 'a distinct jti is fresh');
+  // After the TTL passes, the entry is swept and the jti is fresh again (bounded memory).
+  assert.equal(auth.logoutTokenJtiSeenAndRecord('jti-abc', exp, now + 200_000), false, 'expired jti is evicted → fresh');
+  // No jti → cannot dedupe (aud + TTL remain the guards), never reported as seen.
+  assert.equal(auth.logoutTokenJtiSeenAndRecord(undefined, exp, now), false, 'missing jti is never "seen"');
+});
+
 console.log(`\nidp_device_exchange: ${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);

package/tests/init.mjs

@@ -445,6 +445,57 @@ test('writeConfigs (greenfield, dry-run): writes nothing to disk', () => {
   }
 });
 
+// ---- README START-HERE (task 1002404 / goal 1000052) ----
+test('buildReadme: names the first-run sequence in order (npm install → bongos dev → start)', () => {
+  const md = init.buildReadme(init.buildBrandingConfig(fullSpec()));
+  assert.ok(md.startsWith('# Cloud Bongos'), 'leads with the product-name heading');
+  const iNpm = md.indexOf('npm install');
+  const iDev = md.indexOf('bongos dev');
+  const iStart = md.indexOf('bongos start');
+  assert.ok(iNpm > 0 && iDev > iNpm && iStart > iDev, 'steps in order: npm install → bongos dev → bongos start');
+  assert.ok(/@bongos\/core/.test(md), 'explains WHY npm install is first (CLI ships inside @bongos/core)');
+});
+
+test('buildReadme: login step names the instance origin when known, else a placeholder', () => {
+  const withOrigin = init.buildReadme({ identity: { productName: 'X' }, domains: { publicOrigin: 'http://localhost:3007' } });
+  assert.ok(withOrigin.includes('bongos login http://localhost:3007'), 'uses the configured origin');
+  const noOrigin = init.buildReadme({ identity: { productName: 'X' } });
+  assert.ok(noOrigin.includes('bongos login <your-instance-url>'), 'placeholder when origin unknown');
+});
+
+test('buildReadme: no bare #N (linkify rule) and no unfilled holes', () => {
+  const md = init.buildReadme(init.buildBrandingConfig(fullSpec()));
+  assert.ok(!/#\d/.test(md), 'no bare #N that would mis-autolink to a GitHub issue');
+  assert.ok(!/undefined|\[object Object\]/.test(md), 'no undefined / stringified-object holes');
+});
+
+test('writeConfigs (greenfield): writes a root README START-HERE, never clobbering an existing one', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'greenfield-'));
+  try {
+    const res = init.writeConfigs(fullSpec(), { dir, force: false, dryRun: false, log: () => {} });
+    assert.ok(existsSync(res.readmePath), 'README.md written');
+    const md = readFileSync(res.readmePath, 'utf8');
+    assert.ok(/## Start here/.test(md) && md.includes('npm install'), 'is the START-HERE guide');
+
+    // A --force re-init must NOT clobber a README the owner has since edited.
+    writeFileSync(res.readmePath, '# my own readme\n');
+    init.writeConfigs(fullSpec(), { dir, force: true, dryRun: false, log: () => {} });
+    assert.equal(readFileSync(res.readmePath, 'utf8'), '# my own readme\n', 'existing README left untouched on --force');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('writeConfigs (greenfield, dry-run): mints no README', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'greenfield-'));
+  try {
+    init.writeConfigs(fullSpec(), { dir, force: false, dryRun: true, log: () => {} });
+    assert.equal(existsSync(join(dir, 'README.md')), false, 'dry-run writes no README');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 // ---- seedViaApi provisioning arm (live path, injected fake api) ----
 // A fake apiCall that records calls and returns a configured response per path
 // substring (default: 200 ok). Lets us exercise the live seedViaApi branching

package/tests/instance_config.mjs

@@ -74,3 +74,68 @@ test('resolveDocsRoot: the explicit instance root when set, else coreRoot (no-op
   assert.equal(resolveDocsRoot({ env: { CLOUDBONGOS_INSTANCE_ROOT: '/srv/consumer' } }), path.resolve('/srv/consumer'), 'consumer writes into its own repo');
   assert.equal(resolveDocsRoot({ env: {} }), resolveCoreRoot(), 'single checkout: coincides with coreRoot');
 });
+
+// ---------------------------------------------------------------------------
+// resolveApiBase — the ONE session-aware CLI base resolution (task 1002427).
+//
+// Regression fixture for a bug that locked a builder out of re-authenticating.
+// Three call sites resolved the API base three different ways and none reached
+// the instance the builder was actually signed into:
+//   * paste-token.js hardcoded 'https://amazonprimea.com' (a straggler the task
+//     1002201 sweep missed), so a token minted by cloudbongos.com was verified
+//     against the founder's host and rejected 401 — a VALID token, wrong host.
+//   * reauth.js used the module-level branding default, so it printed a
+//     localhost:3000 click-path to a builder signed into cloudbongos.com.
+//   * cliClient() alone had it right (env -> session.api_base -> default).
+// The session file knew the answer the whole time. This locks the order in.
+// ---------------------------------------------------------------------------
+
+const BRAND_B = { domains: { publicOrigin: 'https://instance-b.example' } };
+
+test('resolveApiBase: the persisted session beats the branding default', () => {
+  // THE regression. A builder authenticated against instance A must keep hitting
+  // A even when this checkout's own branding names B.
+  assert.equal(
+    ic.resolveApiBase({
+      session: { api_base: 'https://instance-a.example' },
+      env: {},
+      b: BRAND_B,
+    }),
+    'https://instance-a.example'
+  );
+});
+
+test('resolveApiBase: an explicit env override beats the session', () => {
+  assert.equal(
+    ic.resolveApiBase({
+      session: { api_base: 'https://instance-a.example' },
+      env: { CLOUDBONGOS_API_BASE: 'http://localhost:3000' },
+      b: BRAND_B,
+    }),
+    'http://localhost:3000'
+  );
+});
+
+test('resolveApiBase: falls back to the branding default with no env and no session', () => {
+  assert.equal(
+    ic.resolveApiBase({ session: null, env: {}, b: BRAND_B }),
+    'https://instance-b.example'
+  );
+});
+
+test('resolveApiBase: a session without a usable api_base falls back, never returns empty', () => {
+  for (const session of [{}, { api_base: '' }, { api_base: '   ' }, { api_base: 42 }]) {
+    assert.equal(
+      ic.resolveApiBase({ session, env: {}, b: BRAND_B }),
+      'https://instance-b.example',
+      `session ${JSON.stringify(session)} must fall back to the branding default`
+    );
+  }
+});
+
+test('resolveApiBase: session:null does not read the session file from disk', () => {
+  // Passing null explicitly means "no session" — the resolver must honour that
+  // rather than falling back to a disk read, so this test stays pure/hermetic
+  // and callers that already know there is no session get a deterministic answer.
+  assert.equal(ic.resolveApiBase({ session: null, env: {}, b: BRAND_B }), 'https://instance-b.example');
+});

package/tests/instance_mismatch_guard.mjs

@@ -27,6 +27,8 @@ function test(name, fn) {
 const DEMO = { domains: { publicOrigin: 'https://demo.cloudbongos.com' } };
 const OTB = { domains: { publicOrigin: 'https://amazonprimea.com' } };
 const noEnv = {}; // no <PREFIX>_API_BASE override in scope
+const branded = () => true;  // simulate a checkout that HAS config/branding.json (a declared instance)
+const neutral = () => false; // simulate a NEUTRAL checkout (portable core — no config/branding.json)
 
 test('instanceOriginHost: extracts host, tolerates trailing slash', () => {
   assert.equal(cli.instanceOriginHost('https://amazonprimea.com'), 'amazonprimea.com');
@@ -41,24 +43,24 @@ test('instanceOriginHost: unparseable input → null (edge)', () => {
 });
 
 test('match: same-host session + branding → no mismatch (the OTB/normal case)', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: OTB, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: OTB, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, false);
 });
 
 test('match: scheme/trailing-slash differences still match on host', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com/' }, brand: OTB, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com/' }, brand: OTB, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, false);
 });
 
 test('mismatch: demo repo + founder amazonprimea session → REFUSE (the reported failure)', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, true);
   assert.equal(r.expected, 'https://demo.cloudbongos.com');
   assert.equal(r.actual, 'https://amazonprimea.com');
 });
 
 test('mismatch: demo repo + cloudbongos.com session (sibling instance) → REFUSE', () => {
-  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: DEMO, env: noEnv });
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: DEMO, env: noEnv, hasInstanceConfig: branded });
   assert.equal(r.mismatch, true);
 });
 
@@ -71,8 +73,23 @@ test('env-override: an explicit *_API_BASE override wins (dev/staging) → no mi
 });
 
 test('no-branding: repo declares no publicOrigin → cannot assert a mismatch → no mismatch', () => {
-  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: {}, env: noEnv }).mismatch, false);
-  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: { domains: {} }, env: noEnv }).mismatch, false);
+  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: {}, env: noEnv, hasInstanceConfig: branded }).mismatch, false);
+  assert.equal(cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: { domains: {} }, env: noEnv, hasInstanceConfig: branded }).mismatch, false);
+});
+
+test('NEUTRAL checkout (no config/branding.json) → trust the session, NO mismatch (task 1002399)', () => {
+  // A neutral core checkout signed into a real instance: even though the resolved
+  // brand host would differ from the session host, there is no declared instance to
+  // enforce, so the guard must NOT fire. This is exactly what lets a neutral checkout
+  // run /builder-* with no <PREFIX>_API_BASE prefix.
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://cloudbongos.com' }, brand: OTB, env: noEnv, hasInstanceConfig: neutral });
+  assert.equal(r.mismatch, false);
+});
+
+test('neutral guard is precedence-safe: env override still wins even when neutral', () => {
+  // env override short-circuits before the neutral check — order-independent.
+  const r = cli.detectInstanceMismatch({ session: { api_base: 'https://amazonprimea.com' }, brand: DEMO, env: { GDS_API_BASE: 'http://localhost:3000' }, hasInstanceConfig: neutral });
+  assert.equal(r.mismatch, false);
 });
 
 test('no-session: nothing to borrow → no mismatch (the no-session/401 path handles it)', () => {