@bongos/core 1.17.0

package/tests/auth_admission_gate.mjs

@@ -0,0 +1,164 @@
+// tests/auth_admission_gate.mjs
+//
+// Admission gate (SR-19 / task #1000): the CLI device flow (pollDeviceFlow) and
+// the web hall sign-in (completeWebFlow) must admit a FIRST-TIME GitHub account
+// only when an Archon has invited them — unless open enrollment is explicitly
+// turned on. Both paths share the pure decision helper firstTimeAdmissionBlocked
+// (+ openEnrollmentEnabled) precisely so they can't drift, so testing the helper
+// directly exercises the exact decision both flows make. DB-free + network-free,
+// so this runs in the unit gate (run-unit-tests.js).
+//
+// Run:  node tests/auth_admission_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const auth = require('../src/bongos/auth.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  PASS  ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`);
+  }
+}
+
+// Run `fn` with OTB_OPEN_XENOS_ENROLLMENT set to `val` (or deleted if undefined),
+// restoring the prior value afterward.
+function withOpenEnrollmentEnv(val, fn) {
+  const prev = process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  if (val === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  else process.env.OTB_OPEN_XENOS_ENROLLMENT = val;
+  try {
+    fn();
+  } finally {
+    if (prev === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+    else process.env.OTB_OPEN_XENOS_ENROLLMENT = prev;
+  }
+}
+
+console.log('admission gate — exports:');
+
+t('openEnrollmentEnabled + firstTimeAdmissionBlocked are exported', () => {
+  assert.equal(typeof auth.openEnrollmentEnabled, 'function');
+  assert.equal(typeof auth.firstTimeAdmissionBlocked, 'function');
+});
+
+console.log('\nopenEnrollmentEnabled — only "1"/"true" are truthy:');
+
+t("'1' enables open enrollment", () => {
+  withOpenEnrollmentEnv('1', () => assert.equal(auth.openEnrollmentEnabled(), true));
+});
+
+t("'true' enables open enrollment", () => {
+  withOpenEnrollmentEnv('true', () => assert.equal(auth.openEnrollmentEnabled(), true));
+});
+
+t('unset → invite required (default secure)', () => {
+  withOpenEnrollmentEnv(undefined, () => assert.equal(auth.openEnrollmentEnabled(), false));
+});
+
+t("'0' / '' / 'yes' do NOT enable open enrollment", () => {
+  for (const v of ['0', '', 'yes', 'on', 'TRUE', 'False']) {
+    withOpenEnrollmentEnv(v, () => assert.equal(auth.openEnrollmentEnabled(), false, `value ${JSON.stringify(v)} should be falsy`));
+  }
+});
+
+console.log('\nfirstTimeAdmissionBlocked — the shared decision both flows make:');
+
+t('first-timer WITHOUT invite, open enrollment OFF → BLOCKED', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false }), true);
+  });
+});
+
+t('first-timer WITH invite, open enrollment OFF → allowed', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: true }), false);
+  });
+});
+
+t('EXISTING builder ALWAYS passes (no invite, open enrollment OFF) — never locked out', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: { id: 42 }, approved: false }), false);
+  });
+});
+
+t('open enrollment ON → first-timer without invite is allowed (escape-hatch)', () => {
+  withOpenEnrollmentEnv('1', () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false }), false);
+  });
+});
+
+t('open enrollment ON → existing builder still allowed', () => {
+  withOpenEnrollmentEnv('true', () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: { id: 7 }, approved: false }), false);
+  });
+});
+
+console.log('\nfirstTimeAdmissionBlocked — first-admin bootstrap bypass (R62 / task 1397):');
+
+t('configured firstAdmin WITHOUT invite, enrollment OFF → ALLOWED (so the owner can be seated)', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    const fa = auth.firstAdminLogin();
+    assert.ok(fa, 'the test branding pack configures a firstAdmin');
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false, login: fa }), false);
+    // case-insensitive match (GitHub logins compare case-insensitively)
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false, login: fa.toUpperCase() }), false);
+  });
+});
+
+t('a NON-firstAdmin first-timer WITHOUT invite, enrollment OFF → still BLOCKED', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false, login: 'some-random-newcomer' }), true);
+  });
+});
+
+t('no login passed (legacy callers) behaves exactly as before — BLOCKED', () => {
+  withOpenEnrollmentEnv(undefined, () => {
+    assert.equal(auth.firstTimeAdmissionBlocked({ existing: null, approved: false }), true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Call-site non-drift (task 1970). The helper above accepts `login` and does the
+// right thing — but the WEB flow (completeWebFlow) once called it WITHOUT `login`,
+// so the configured-firstAdmin bypass never fired and the founding owner was gated
+// out of their own fresh instance. Testing the pure helper can't catch a caller
+// that forgets an argument, so we assert it structurally: EVERY invocation of
+// firstTimeAdmissionBlocked in auth.js must pass `login`. This is the "the two
+// flows can't drift" promise, enforced instead of merely commented.
+console.log('\nfirstTimeAdmissionBlocked — every call-site passes `login` (SR-19 non-drift, #1970):');
+
+t('completeWebFlow + pollDeviceFlow both pass `login` to the gate', () => {
+  const src = readFileSync(new URL('../src/bongos/auth.js', import.meta.url), 'utf8');
+  const re = /firstTimeAdmissionBlocked\s*\(\s*\{[^}]*\}/g;
+  const callSites = [];
+  for (let m = re.exec(src); m; m = re.exec(src)) {
+    // Skip the function DECLARATION (`function firstTimeAdmissionBlocked({…})`) —
+    // only the CALL-sites must carry `login`.
+    if (src.slice(Math.max(0, m.index - 'function '.length), m.index) === 'function ') continue;
+    callSites.push(m[0]);
+  }
+  assert.ok(callSites.length >= 2, `expected ≥2 call-sites (web + device flow), found ${callSites.length}`);
+  for (const call of callSites) {
+    assert.match(call, /\blogin\b/, `a firstTimeAdmissionBlocked call omits \`login\` — the founding-owner bypass will silently fail:\n        ${call}`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+console.log('');
+if (failed === 0) {
+  console.log(`all ${passed} checks passed.`);
+  process.exit(0);
+} else {
+  console.log(`${failed} failed, ${passed} passed.`);
+  process.exit(1);
+}

package/tests/auth_anthropic_identity.mjs

@@ -0,0 +1,95 @@
+// tests/auth_anthropic_identity.mjs
+//
+// Anthropic-identity pin REMOVED (task 1039, idea 258).
+//
+// requireBuilder used to 403 `identity_mismatch` when a linked builder's CLI
+// echoed an X-Anthropic-User header that differed from the stored
+// anthropic_user_id (V3.R10 #235, C3). That pin is gone: the drachmae reward
+// values work at a uniform server-side list price (ADR 0054), not against each
+// builder's own Anthropic account, so there is no reason to bind a session to
+// one Anthropic identity — attribution is the GDS session-token holder. The pin
+// also locked a linked builder out of their own session the moment they used a
+// second Claude account.
+//
+// The contract is now simple: the X-Anthropic-User header is NEVER read, for
+// ANY builder (linked or not), with ANY header value. requireBuilder must:
+//   - pass a linked builder whose header DIFFERS from the stored id (this is the
+//     regression guard for the bug — multi-account must work);
+//   - pass a linked builder whose header matches / is absent;
+//   - pass an unlinked builder regardless of any header value.
+// anthropic_user_id is still stored as cosmetic attribution; it is no longer an
+// auth boundary.
+//
+// lookupSession is stubbed on the db module BEFORE auth.js is required, because
+// auth.js destructures it at load time. No server/DB/network.
+//
+// Run:  node tests/auth_anthropic_identity.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const db = require('../src/bongos/db-kernel.js'); // lookupSession lives in db-kernel now (ADR 0102)
+let nextSession = null;
+db.lookupSession = async () => nextSession;
+const auth = require('../src/bongos/auth.js');
+
+function fakeRes() {
+  return {
+    _status: null, _json: null,
+    status(c) { this._status = c; return this; },
+    json(b) { this._json = b; return this; },
+  };
+}
+
+let pass = 0, fail = 0;
+const t = async (name, fn) => {
+  try { await fn(); pass++; console.log(`PASS  ${name}`); }
+  catch (e) { fail++; console.log(`FAIL  ${name}\n      ${e.stack || e.message}`); }
+};
+
+const LINKED = { builder_id: 1, github_login: 'lars589', rank: 'archon', status: 'active', anthropic_user_id: 'uuid-real' };
+
+await t('linked builder + DIFFERENT header (2nd Claude account) → next() called, NOT 403 (pin removed)', async () => {
+  nextSession = LINKED;
+  const req = { headers: { authorization: 'Bearer t', 'x-anthropic-user': 'uuid-from-second-account' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requireBuilder(req, res, () => { nexted = true; });
+  assert.equal(nexted, true, 'a linked builder on a second Claude account must NOT be locked out');
+  assert.equal(res._status, null, 'no 403 — the identity pin is gone');
+});
+
+await t('linked builder + MATCHING header → next() called', async () => {
+  nextSession = LINKED;
+  const req = { headers: { authorization: 'Bearer t', 'x-anthropic-user': 'uuid-real' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requireBuilder(req, res, () => { nexted = true; });
+  assert.equal(nexted, true, 'a matching attestation must pass');
+  assert.equal(res._status, null);
+});
+
+await t('linked builder + ABSENT header → next() called (web/curl/pre-link)', async () => {
+  nextSession = LINKED;
+  const req = { headers: { authorization: 'Bearer t' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requireBuilder(req, res, () => { nexted = true; });
+  assert.equal(nexted, true, 'absence is fine — the header is never required');
+  assert.equal(res._status, null);
+});
+
+await t('UNLINKED builder (no anthropic_user_id) + any header → next() called', async () => {
+  nextSession = { builder_id: 2, github_login: 'metic1', rank: 'metic', status: 'active' };
+  const req = { headers: { authorization: 'Bearer t', 'x-anthropic-user': 'anything' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requireBuilder(req, res, () => { nexted = true; });
+  assert.equal(nexted, true, 'an unlinked builder is never checked');
+  assert.equal(res._status, null);
+});
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/auth_duplicate_cookie.mjs

@@ -0,0 +1,56 @@
+// tests/auth_duplicate_cookie.mjs — regression for the duplicate gds_session
+// cookie 401 (#851). A browser can carry TWO gds_session cookies: a stale
+// host-only one (set on amazonprimea.com before the #726/#734 apex-scoping
+// rollout) AND the current apex-scoped one. The old extractToken() returned the
+// FIRST value only, so a stale duplicate could shadow the live session and 401
+// the builder (hit on the Discord link callback for builder 25). extractTokens()
+// must surface EVERY candidate, in priority order, deduped — so resolveSession()
+// can try them all and a valid token always wins.
+import assert from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const auth = require('../src/bongos/auth.js');
+
+let pass = 0, fail = 0;
+const ok = (cond, msg) => { if (cond) { pass++; console.log('  ok ', msg); } else { fail++; console.log('  FAIL', msg); } };
+const req = (cookie, authz) => ({ headers: { cookie, ...(authz ? { authorization: authz } : {}) } });
+
+console.log('extractTokens — duplicate gds_session cookies:');
+// The exact bug: two gds_session cookies, stale one first. Both must surface.
+ok(
+  JSON.stringify(auth.extractTokens(req('gds_session=STALE; gds_session=LIVE; gds_discord_state=x')))
+    === JSON.stringify(['STALE', 'LIVE']),
+  'both gds_session values returned, in header order',
+);
+
+console.log('\nextractTokens — priority order + dedup:');
+ok(
+  JSON.stringify(auth.extractTokens(req('gds_session=COOKIE; pms_session=LEGACY', 'Bearer ABC123')))
+    === JSON.stringify(['ABC123', 'COOKIE', 'LEGACY']),
+  'Bearer first, then gds_session, then legacy pms_session',
+);
+ok(
+  JSON.stringify(auth.extractTokens(req('gds_session=DUP; gds_session=DUP'))) === JSON.stringify(['DUP']),
+  'identical duplicates deduped',
+);
+ok(JSON.stringify(auth.extractTokens(req(''))) === JSON.stringify([]), 'no cookies → empty list');
+ok(
+  JSON.stringify(auth.extractTokens(req('gds_session=; gds_session=REAL'))) === JSON.stringify(['REAL']),
+  'empty-valued cookie skipped, real one kept',
+);
+// A token value is hex/base64-ish and never contains '=', but guard the parser
+// anyway: split on the FIRST '=' so a value is never truncated.
+ok(
+  JSON.stringify(auth.extractTokens(req('gds_session=a=b=c'))) === JSON.stringify(['a=b=c']),
+  "value with '=' kept intact (split on first '=' only)",
+);
+
+console.log('\nresolveSession — tries every candidate until one resolves:');
+// resolveSession calls the module's lookupSession (DB-backed). We can't hit a DB
+// here, but we CAN prove the ordering contract via extractTokens above, which is
+// exactly what resolveSession iterates. Assert resolveSession is wired + async.
+ok(typeof auth.resolveSession === 'function', 'resolveSession exported');
+ok(auth.resolveSession.constructor.name === 'AsyncFunction', 'resolveSession is async');
+
+console.log(`\nDuplicate-cookie auth tests: ${pass} passed, ${fail} failed`);
+if (fail) process.exit(1);

package/tests/auth_error_brand.mjs

@@ -0,0 +1,77 @@
+// tests/auth_error_brand.mjs — the auth error page is brand-aware (task 1439 /
+// idea #351, ADR 0062 §3). renderAuthErrorPage used to bake OTB lore ("The Gate
+// is Closed", "seek the Archon", "chronicles of the city") straight into the
+// template, so it leaked onto cloudbongos.com and every other instance. Now every
+// fixed string is owned by the branding pack's `copy.authError` block. Two layers,
+// both DB-free:
+//   1. Both packs carry a COMPLETE authError block, and the neutral pack (what a
+//      vanilla / cloudbongos.com instance renders) is free of OTB lore.
+//   2. renderAuthErrorPage interpolates the pack's authError values rather than
+//      hardcoding them — proven against the ambient OTB pack, where the pack
+//      values must win over the neutral code fallback.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import brandingMod from '../src/branding.js';
+import authMod from '../src/bongos/routes/auth.js';
+
+const { loadBranding } = brandingMod;
+const { renderAuthErrorPage } = authMod;
+
+const KEYS = ['titleSuffix', 'epigraph', 'heading', 'subtitle', 'ctaLabel'];
+// Instance-specific terms that must never appear in the NEUTRAL/vanilla copy —
+// exactly what was leaking onto cloudbongos.com before this fix.
+const OTB_LORE = [/archon/i, /\bgate\b/i, /chronicles/i, /amazonprimea/i, /\bboats\b/i, /drachma/i];
+
+// A vanilla boot has no instance config → the neutral starter alone (the
+// fail-to-vanilla path), exactly as a fresh `node src/platform-server.js` would.
+const vanilla = () => loadBranding({ instancePath: '/no/such/instance/branding.json', env: {} });
+
+test('authError: both packs carry a complete block, and the neutral pack is lore-free', () => {
+  const otb = loadBranding({ env: {} }).copy?.authError; // default env → config/branding.json (OTB)
+  const neutral = vanilla().copy?.authError;
+
+  for (const [name, pack] of [['OTB', otb], ['neutral', neutral]]) {
+    assert.ok(pack, `${name} pack has a copy.authError block`);
+    for (const k of KEYS) {
+      assert.equal(typeof pack[k], 'string', `${name}.authError.${k} is a string`);
+      assert.ok(pack[k].trim().length > 0, `${name}.authError.${k} is non-empty`);
+    }
+  }
+
+  // OTB keeps its own flavor (regression lock — a future edit must not neutralize
+  // OTB's OWN page while making the platform brand-aware).
+  assert.equal(otb.heading, 'The Gate is Closed');
+  assert.equal(otb.titleSuffix, 'the gate is closed');
+  assert.match(otb.subtitle, /seek the Archon/);
+  assert.match(otb.epigraph, /chronicles of the city/);
+  assert.equal(otb.ctaLabel, 'Try the gate again');
+
+  // The neutral pack — what cloudbongos.com actually renders — carries NO OTB lore.
+  for (const k of KEYS) {
+    for (const lore of OTB_LORE) {
+      assert.doesNotMatch(neutral[k], lore, `neutral.authError.${k} must not contain ${lore}`);
+    }
+  }
+});
+
+test('renderAuthErrorPage interpolates the branding pack, not hardcoded lore', () => {
+  // Ambient branding in this checkout is the OTB pack, so the rendered page must
+  // carry the OTB authError values AND the branded worldName.
+  const otb = loadBranding({ env: {} });
+  const a = otb.copy.authError;
+  const html = renderAuthErrorPage('State mismatch', 'the detail line');
+
+  assert.match(html, new RegExp(otb.identity.worldName)); // Amazonprimea, from the pack
+  assert.ok(html.includes(a.heading), 'page heading comes from the pack');
+  assert.ok(html.includes(a.epigraph), 'epigraph comes from the pack');
+  assert.ok(html.includes(a.subtitle), 'sub-line comes from the pack');
+  assert.ok(html.includes(a.ctaLabel), 'retry button label comes from the pack');
+  assert.ok(html.includes(`${otb.identity.worldName} — ${a.titleSuffix}`), 'tab title = worldName + pack suffix');
+  // The per-branch args still render (they are passed in, not pack-owned).
+  assert.ok(html.includes('State mismatch') && html.includes('the detail line'));
+
+  // The pack must have WON over the neutral code fallback — otherwise the render
+  // wasn't actually pack-driven.
+  assert.ok(!html.includes('— access —'), 'neutral fallback epigraph must not appear under the OTB pack');
+  assert.ok(!html.includes('Try signing in again'), 'neutral fallback cta must not appear under the OTB pack');
+});

package/tests/auth_flow_slice1.mjs

@@ -0,0 +1,223 @@
+// tests/auth_flow_slice1.mjs
+//
+// Auth-flow slice 1 (task #369): apiCall must short-circuit on HTTP 401 with
+// clear guidance, unless the caller opts out via { allowUnauthenticated: true }.
+// Also exercises that doctor.js is structurally sane (loads, executes, prints
+// the expected section headers).
+//
+// Pure-JS where possible. The fetch path is monkey-patched on globalThis;
+// process.exit is monkey-patched to throw a tagged Error so we can assert
+// without actually exiting the test process.
+//
+// Run:  node tests/auth_flow_slice1.mjs
+
+import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, '..');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try {
+    const r = fn();
+    if (r && typeof r.then === 'function') {
+      return r.then(
+        () => { passed++; console.log(`  PASS  ${name}`); },
+        (e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); },
+      );
+    }
+    passed++;
+    console.log(`  PASS  ${name}`);
+  } catch (e) {
+    failed++;
+    console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test harness: stub globalThis.fetch + process.exit before requiring cli-lib.
+// cli-lib reads its session file lazily on each apiCall, so we can also
+// monkey-patch fs.readFile to provide a synthetic session without touching
+// the real ~/.config/otb/gds-session.json.
+// ---------------------------------------------------------------------------
+
+const fsp = require('node:fs/promises');
+const origReadFile = fsp.readFile;
+
+function withFakeSession(token, fn) {
+  fsp.readFile = async (p, enc) => {
+    if (String(p).endsWith('gds-session.json') || String(p).endsWith('pms-session.json')) {
+      // Stub builder identity — placeholder values, not tied to any real
+      // builder. The test only asserts on token plumbing, not identity content.
+      return JSON.stringify({ token, builder: { id: 1, github_login: 'test-builder', rank: 'archon' } });
+    }
+    return origReadFile(p, enc);
+  };
+  return Promise.resolve(fn()).finally(() => { fsp.readFile = origReadFile; });
+}
+
+function withFakeFetch(handler, fn) {
+  const orig = globalThis.fetch;
+  globalThis.fetch = handler;
+  return Promise.resolve(fn()).finally(() => { globalThis.fetch = orig; });
+}
+
+function exitTrap() {
+  const orig = process.exit;
+  const calls = [];
+  process.exit = (code) => { calls.push(code); throw new Error(`__EXIT_TRAP__:${code}`); };
+  return {
+    calls,
+    restore: () => { process.exit = orig; },
+  };
+}
+
+// Capture stderr writes (the guidance message goes there).
+function stderrCapture() {
+  const orig = process.stderr.write.bind(process.stderr);
+  let buf = '';
+  process.stderr.write = (chunk, enc, cb) => {
+    buf += chunk.toString();
+    if (typeof enc === 'function') enc();
+    else if (typeof cb === 'function') cb();
+    return true;
+  };
+  return {
+    get text() { return buf; },
+    restore: () => { process.stderr.write = orig; },
+  };
+}
+
+// Also need to suppress console.error during the trap (it writes to stderr too,
+// but goes through a different path on some node versions). Our capture above
+// covers both because console.error pipes through process.stderr.write.
+
+// ---------------------------------------------------------------------------
+// 1. cli-lib apiCall — 401 short-circuit + opt-out
+// ---------------------------------------------------------------------------
+
+// Require cli-lib FRESH so the _unauthExitInFlight module-state is clean.
+// We use the require cache hack: delete it from cache before each scenario.
+function freshCliLib() {
+  const path = require.resolve('../scripts/gds/cli-lib.js');
+  delete require.cache[path];
+  return require('../scripts/gds/cli-lib.js');
+}
+
+console.log('cli-lib apiCall behavior:');
+
+await t('200 OK: apiCall returns { status: 200, ok: true, data }', async () => {
+  await withFakeSession('faketoken', () => withFakeFetch(
+    async () => ({ status: 200, ok: true, text: async () => JSON.stringify({ hello: 'world' }) }),
+    async () => {
+      const { apiCall } = freshCliLib();
+      const r = await apiCall('GET', '/api/gds/me');
+      assert.equal(r.status, 200);
+      assert.equal(r.ok, true);
+      assert.deepEqual(r.data, { hello: 'world' });
+    },
+  ));
+});
+
+await t('401: apiCall (default opts) prints guidance + calls process.exit(2)', async () => {
+  await withFakeSession('staletoken', () => withFakeFetch(
+    async () => ({ status: 401, ok: false, text: async () => JSON.stringify({ error: 'unauthenticated' }) }),
+    async () => {
+      const exit = exitTrap();
+      const errs = stderrCapture();
+      try {
+        const { apiCall } = freshCliLib();
+        await assert.rejects(
+          () => apiCall('GET', '/api/gds/me'),
+          /__EXIT_TRAP__:2/,
+        );
+        assert.deepEqual(exit.calls, [2]);
+        assert.match(errs.text, /no longer valid/i);
+        assert.match(errs.text, /setup\.js --force/);
+      } finally {
+        exit.restore();
+        errs.restore();
+      }
+    },
+  ));
+});
+
+await t('401: apiCall with { allowUnauthenticated: true } returns the 401 instead of exiting', async () => {
+  await withFakeSession('staletoken', () => withFakeFetch(
+    async () => ({ status: 401, ok: false, text: async () => JSON.stringify({ error: 'unauthenticated' }) }),
+    async () => {
+      const exit = exitTrap();
+      try {
+        const { apiCall } = freshCliLib();
+        const r = await apiCall('GET', '/api/gds/me', null, { allowUnauthenticated: true });
+        assert.equal(r.status, 401);
+        assert.equal(r.ok, false);
+        assert.deepEqual(r.data, { error: 'unauthenticated' });
+        // process.exit must NOT have been called.
+        assert.deepEqual(exit.calls, []);
+      } finally {
+        exit.restore();
+      }
+    },
+  ));
+});
+
+await t('500: apiCall does NOT short-circuit on non-401 errors (returns the response)', async () => {
+  await withFakeSession('faketoken', () => withFakeFetch(
+    async () => ({ status: 500, ok: false, text: async () => JSON.stringify({ error: 'boom' }) }),
+    async () => {
+      const exit = exitTrap();
+      try {
+        const { apiCall } = freshCliLib();
+        const r = await apiCall('GET', '/api/gds/tasks');
+        assert.equal(r.status, 500);
+        assert.equal(r.ok, false);
+        assert.deepEqual(exit.calls, []);
+      } finally {
+        exit.restore();
+      }
+    },
+  ));
+});
+
+await t('exports include printUnauthGuidanceAndExit so other scripts can reuse', () => {
+  const lib = freshCliLib();
+  assert.equal(typeof lib.printUnauthGuidanceAndExit, 'function');
+});
+
+// ---------------------------------------------------------------------------
+// 2. doctor.js — structural sanity. The doctor relies on the live API + git
+// state to render its rows, so we cannot stub everything from inside the
+// test process. Spawn it as a child and assert it runs, prints the expected
+// section headers, and exits with an exit code we can interpret.
+// ---------------------------------------------------------------------------
+
+console.log('\ndoctor.js structural smoke:');
+
+await t('doctor.js executes and prints all four section headers', () => {
+  const r = spawnSync('node', ['scripts/gds/doctor.js'], { cwd: REPO, encoding: 'utf8', timeout: 30_000 });
+  // The doctor is allowed to exit 0 or 1 — 1 means there's a red row, which
+  // is a legitimate environment state. We're checking structure, not result.
+  assert.ok([0, 1].includes(r.status), `unexpected exit code ${r.status}: ${r.stderr}`);
+  for (const header of ['Session', 'Git plumbing', 'Repo state', 'Environment']) {
+    assert.match(r.stdout, new RegExp(`(?:^|\\n)${header}\\b`), `missing section: ${header}\nstdout was:\n${r.stdout}`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+console.log('');
+if (failed === 0) {
+  console.log(`all ${passed} checks passed.`);
+  process.exit(0);
+} else {
+  console.log(`${failed} failed, ${passed} passed.`);
+  process.exit(1);
+}