@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/setup.js

@@ -0,0 +1,646 @@
+#!/usr/bin/env node
+// Builder setup — runs the GitHub Device Flow and stores the session token.
+//
+// Usage:
+//   node scripts/bongos/setup.js              run interactively, perform the auth
+//   node scripts/bongos/setup.js --force      re-auth even if a valid session exists
+//   node scripts/bongos/setup.js --skip-keys  skip the per-builder Gemini-key prompt
+//                                          (for CI / batch onboarding / builders
+//                                          who don't need the art pipeline)
+//   node scripts/bongos/setup.js --dry-run    print every step that *would* run, without
+//                                          contacting the API, writing files, or
+//                                          prompting. Useful for newcomers who want
+//                                          a preview before running it for real.
+//
+// Prints the user_code and verification_uri, then polls until the user
+// completes auth (or expires/denies). On success, writes
+// ~/.config/otb/bongos-session.json (resolved from os.homedir(), so this works for
+// any user on any machine; no path is hardcoded to a particular developer's
+// home directory) and prints the builder profile.
+
+const readline = require('readline');
+const { cliClient, errCode, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE, hallBase, surfaceAction, isTerminalSurface } = require('./cli-lib');
+
+// The instance's status dashboard, from branding — never a hardcoded host, so a
+// non-OTB instance points its builders at ITS OWN dashboard (task 1002428).
+// Falls back to the resolved API base when branding is unreadable.
+function statusOrigin() {
+  try {
+    const d = require('../../src/branding').branding().domains || {};
+    if (d.statusOrigin) return d.statusOrigin;
+  } catch (_) { /* fall through */ }
+  return API_BASE;
+}
+const onboardingConfig = require('./onboarding-config');
+
+const DRY_RUN = process.argv.includes('--dry-run');
+// --skip-keys mirrors the same flag on scripts/setup-builder.sh — when set,
+// the Gemini-key prompt is skipped entirely. Used by CI / batch onboarding /
+// builders who don't intend to run the art pipeline.
+const SKIP_KEYS = process.argv.includes('--skip-keys');
+
+// Tiny helper so the dry-run output reads as a clear plan rather than a wall
+// of identical-looking log lines.
+function dryRunStep(msg) {
+  console.log(`[dry-run] ${msg}`);
+}
+
+// Ask the new builder for their own Google AI Studio key — used by the
+// pixel-art pipeline (gen_api.py). V3.R11 (#91): each builder pays their own
+// Gemini bill, so spend is attributable per-builder on the public dashboard.
+//
+// Stored as gemini_api_key in ~/.config/otb/bongos-session.json (mode 600, same
+// file as the GitHub session token). gen_api.py reads this location before
+// falling back to ~/.config/otb/env or .env.local.
+//
+// Behavior:
+//   - Non-TTY shells: skip silently. Builder can edit the session file later.
+//   - --skip-keys flag: skip silently. CI/batch onboarding.
+//   - Existing key on file: show last-4, ask "overwrite? [y/N]". Default no.
+//   - Empty input: leave whatever was there. Don't blank a working key by
+//     accident.
+async function promptGeminiKey() {
+  if (SKIP_KEYS) return;
+  if (!process.stdin.isTTY) return;
+
+  const fs = require('node:fs/promises');
+  let session;
+  try {
+    session = JSON.parse(await fs.readFile(SESSION_PATH, 'utf8'));
+  } catch (_) {
+    // saveSession just wrote it; if it's not readable something's badly wrong.
+    // Better to bail than to silently lose a key the builder is about to type.
+    return;
+  }
+
+  const existing = session.gemini_api_key;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  try {
+    console.log('');
+    console.log('Google AI Studio key for the pixel-art pipeline (per-builder, optional).');
+    console.log('  Get one at https://aistudio.google.com/app/apikey');
+    console.log('  (Or skip this and add it later with browser clicks: hall Settings →');
+    console.log(`   ${hallBase()}/settings#art-key — stored encrypted, ADR 0073.)`);
+    console.log('  Each builder pays their own Gemini bill so spend is attributed to them');
+    console.log(`  on ${statusOrigin()}.`);
+    let prompt;
+    if (existing && typeof existing === 'string' && existing.length >= 4) {
+      const last4 = existing.slice(-4);
+      const overwrite = (await ask(`  Key on file ending …${last4}. Overwrite? [y/N] `)).trim().toLowerCase();
+      if (!(overwrite === 'y' || overwrite === 'yes')) {
+        console.log('  Kept the existing key.');
+        return;
+      }
+      prompt = '  New GOOGLE_AI_STUDIO_KEY (press Enter to clear): ';
+    } else {
+      prompt = '  GOOGLE_AI_STUDIO_KEY (press Enter to skip): ';
+    }
+    const input = (await ask(prompt)).trim();
+    if (!input) {
+      if (existing) {
+        // The user asked to overwrite, then entered nothing → clear it.
+        delete session.gemini_api_key;
+        await fs.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+        console.log('  Cleared the key.');
+      } else {
+        console.log('  Skipped — set it later by re-running setup.js or editing the session file.');
+      }
+      return;
+    }
+    session.gemini_api_key = input;
+    await fs.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+    console.log(`  Saved Gemini key to ${SESSION_PATH} (mode 600).`);
+  } finally {
+    rl.close();
+  }
+}
+
+// V3.R10 (#235), criterion C3 — link the builder's Anthropic account.
+//
+// Claude Code is the trusted agent on the builder's machine: it writes its own
+// signed-in account to ~/.claude.json under `oauthAccount` (emailAddress +
+// accountUuid). We read that, ask the builder to confirm the email, and on a
+// match store the attested pair on their builder row via POST /me/anthropic-link.
+// The accountUuid is then written into the local session file as cosmetic
+// attribution. (The X-Anthropic-User identity pin was removed in task 1039 /
+// idea 258, so it is no longer sent or cross-checked.)
+//
+// "Setup refuses to proceed on email mismatch" (done-when): if the typed email
+// doesn't match what Claude Code reports, we REFUSE to link — nothing is stored
+// and the builder is told to fix it. (The GDS GitHub session itself is already
+// saved and stays valid; only the Anthropic attestation is withheld.)
+//
+// Skips gracefully (no error) when: not a TTY, no ~/.claude.json, or the file
+// has no oauthAccount/emailAddress (e.g. API-key auth, or a box without local
+// Claude creds). Attestation is best-effort onboarding polish, never a setup
+// blocker for builders whose environment can't produce it.
+function readLocalAnthropicAccount() {
+  const fs = require('node:fs');
+  const os = require('node:os');
+  const path = require('node:path');
+  try {
+    const p = path.join(os.homedir(), '.claude.json');
+    const oa = JSON.parse(fs.readFileSync(p, 'utf8'))?.oauthAccount;
+    if (oa && typeof oa.emailAddress === 'string' && typeof oa.accountUuid === 'string') {
+      return { email: oa.emailAddress, userId: oa.accountUuid };
+    }
+  } catch (_) { /* missing/unreadable/non-JSON → no local account */ }
+  return null;
+}
+
+async function promptAnthropicLink() {
+  if (!process.stdin.isTTY) return;
+  const local = readLocalAnthropicAccount();
+  if (!local) {
+    console.log('');
+    console.log('Anthropic account linking skipped — no local Claude Code account found');
+    console.log('  (~/.claude.json oauthAccount). Re-run setup from a machine signed into');
+    console.log('  Claude Code to attest your Anthropic identity for cost + authorship.');
+    return;
+  }
+
+  const fs = require('node:fs/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  try {
+    console.log('');
+    console.log('Link your Anthropic account (so cost + authorship are attributed to you).');
+    console.log('  Claude Code on this machine is signed in as: ' + local.email);
+    const typed = (await ask('  Confirm your Anthropic email [Enter = the address above]: ')).trim();
+    const confirmed = typed || local.email;
+    if (confirmed.toLowerCase() !== local.email.toLowerCase()) {
+      // done-when: refuse to proceed on mismatch. Store nothing.
+      console.error('  ❌ Email mismatch — "' + confirmed + '" does not match the Anthropic');
+      console.error('     account Claude Code is signed into (' + local.email + ').');
+      console.error('     Not linking. Re-run setup once the addresses agree, or sign Claude');
+      console.error('     Code into the correct account first.');
+      return;
+    }
+    const resp = await (await cliClient()).me.postMeAnthropicLink({
+      body: {
+        anthropic_email: confirmed,
+        anthropic_user_id: local.userId,
+      },
+    });
+    if (!resp.ok) {
+      console.error(`  Could not link Anthropic account (${resp.status}). You can re-run setup later.`);
+      return;
+    }
+    // Persist the attested id into the local session as cosmetic attribution.
+    // (No longer sent as X-Anthropic-User — the identity pin was removed,
+    // task 1039 / idea 258.)
+    try {
+      const session = JSON.parse(await fs.readFile(SESSION_PATH, 'utf8'));
+      session.anthropic_email = confirmed;
+      session.anthropic_user_id = local.userId;
+      await fs.writeFile(SESSION_PATH, JSON.stringify(session, null, 2), { mode: 0o600 });
+    } catch (_) { /* the server has the link; a session-file write hiccup is non-fatal */ }
+    console.log('  ✓ Anthropic account linked. Future calls attest this identity.');
+  } finally {
+    rl.close();
+  }
+}
+
+// Ask the new builder which disciplines they want the work queue tilted
+// toward, then persist via PATCH /me/disciplines (migration 024 / V3.R80).
+// Non-interactive shells (no TTY) skip the prompt and leave the default {}.
+async function promptDisciplines() {
+  if (!process.stdin.isTTY) return;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  try {
+    console.log('');
+    console.log('Which kind of work do you want surfaced first?');
+    console.log('  1) engineer  — code, gameplay mechanics, infra, the GDS itself, perf, bugs');
+    console.log('  2) artist    — pixel-art tiles, sprites, icons, avatars, the art pipeline');
+    console.log('  3) ideator   — idea capture, scoping, research, docs/briefs, narrative, lore');
+    console.log('  4) all of them');
+    console.log('  5) skip for now (you can set this later on /builders)');
+    const choice = (await ask('Choose [1-5]: ')).trim();
+    const map = {
+      1: ['engineer'], 2: ['artist'], 3: ['ideator'],
+      4: ['engineer', 'artist', 'ideator'], 5: null,
+    };
+    const disciplines = map[choice];
+    if (disciplines === undefined) {
+      console.log('Unrecognized choice — leaving disciplines unset. Edit later on /builders.');
+      return;
+    }
+    if (disciplines === null) return;
+    const resp = await (await cliClient()).me.patchMeDisciplines({ body: { preferred_disciplines: disciplines } });
+    if (resp.ok) {
+      console.log(`Preferred disciplines set: ${disciplines.join(', ')}`);
+    } else {
+      console.error(`Could not save disciplines (${resp.status}). Set them later on /builders.`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// Onboarding-friction consent (V3.R79 / #298, criterion C1 — feedback without
+// asking). Instead of interrogating new builders about what was confusing, we
+// offer to read their onboarding session transcripts and mine them for
+// friction automatically. This is opt-in and time-boxed: consent opens a short
+// onboarding window, after which the pipeline no-ops. Raw transcripts never
+// leave the machine — only a distilled friction signal is filed to the GDS.
+// Non-interactive shells skip the prompt and record no consent (safe default).
+async function promptOnboardingConsent() {
+  if (!process.stdin.isTTY) return;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  try {
+    console.log('');
+    console.log('To improve onboarding, we can read your onboarding session logs and');
+    console.log('automatically surface where the system tripped you up — no survey needed.');
+    console.log('Only a distilled friction summary is shared; your raw transcripts stay on');
+    console.log(`this machine. It runs for the first ${onboardingConfig.windowDays()} days, then stops on its own.`);
+    const answer = (await ask('May we read your onboarding session logs to improve the system? [Y/n] ')).trim().toLowerCase();
+    // Default (empty) is yes — the prompt advertises [Y/n].
+    const consent = answer === '' || answer === 'y' || answer === 'yes';
+    const record = onboardingConfig.writeConsent({ consent });
+    if (consent) {
+      console.log(`Thanks — onboarding-log analysis is on until ${new Date(onboardingConfig.windowExpiry(record)).toISOString().slice(0, 10)}.`);
+    } else {
+      console.log('No problem — onboarding-log analysis stays off.');
+    }
+  } catch (err) {
+    // Never let a consent-write hiccup block auth completion.
+    console.error(`(Could not record onboarding-log preference: ${err.message})`);
+  } finally {
+    rl.close();
+  }
+}
+
+// ── W1: the manifest-born App has Device Flow OFF (task 1003051) ─────────────
+// The detector + the guidance moved to ./device-flow-help (task 1003881) so
+// `bongos login` can use the same words without closing a require cycle back
+// through this file (setup requires login for runDeviceFlow). Re-exported here
+// because both are part of setup.js's tested public surface.
+const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');
+
+// Verify a hall-minted CLI token against /me and save the session (the
+// paste-token.js contract: nothing is written unless the token verifies).
+// Returns { ok:true, builder } or { ok:false, status }. Exported for tests.
+async function redeemCliToken(token) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/bongos/me`, { headers: { Authorization: `Bearer ${token}` } });
+  } catch (err) {
+    console.error(`Could not reach ${API_BASE}: ${err.message}`);
+    return { ok: false, status: 0 };
+  }
+  if (!res.ok) {
+    console.error(res.status === 401
+      ? `Token rejected by ${API_BASE} (HTTP 401) — copy the full token from the Settings page and try again.`
+      : `Verification call failed (HTTP ${res.status}).`);
+    return { ok: false, status: res.status };
+  }
+  const me = await res.json();
+  await saveSession({ token, builder: me.builder, api_base: API_BASE });
+  return { ok: true, builder: me.builder };
+}
+
+// Everything setup does AFTER a session is saved — shared verbatim by the
+// Device Flow success path and the W1 CLI-token fallback, so the fallback
+// completes the SAME onboarding end to end (task 1003051).
+async function finishSetup(builder) {
+  console.log('');
+  console.log(`Authenticated as ${builder.github_login} (#${builder.id})`);
+  if (builder.display_name != null) console.log(`Display name: ${builder.display_name}`);
+  if (builder.total_credits != null) console.log(`Total credits: ${builder.total_credits}`);
+  console.log(`Session saved to ${SESSION_PATH}`);
+  // SEC #863: activate the project git hooks (core.hooksPath → .husky) so
+  // the tracked hooks run — here that's the pre-push permission gate
+  // (task 1002608); an instance may track more. Best effort — an activation
+  // hiccup must never fail an otherwise-good setup; the post-push main
+  // audit is the fail-closed net regardless.
+  try {
+    const { activate } = require('./install-git-hooks');
+    const r = activate();
+    const live = (r.hooks && r.hooks.length) ? r.hooks.join(', ') : 'none tracked';
+    if (r.status === 'activated') console.log(`Git hooks activated (live hooks: ${live})`);
+    else if (r.status === 'already-active') console.log(`Git hooks already active (live hooks: ${live})`);
+    else console.log(`Note: ${r.message}`);
+  } catch (e) {
+    console.log(`Note: could not activate git hooks (${e.message}); run: git config core.hooksPath .husky`);
+  }
+  await promptGeminiKey();
+  // #1281: deliver the GDS shared art key to entitled newcomers right now, so
+  // a brand-new Xenos's first art task works without waiting for the next
+  // session start. Best-effort, bounded — never block setup. (Phase 2 will
+  // make the promptGeminiKey copy above rank-aware — "we cover your first art
+  // tasks; add your own key when you reach Thetes".)
+  try {
+    const { spawnSync } = require('node:child_process');
+    const path = require('node:path');
+    spawnSync(process.execPath, [path.join(__dirname, 'fetch-art-key.js')],
+      { stdio: 'ignore', timeout: 8000 });
+  } catch (_) { /* non-fatal — the session-start sync will deliver it later */ }
+  await promptAnthropicLink();
+  await promptDisciplines();
+  await promptOnboardingConsent();
+  // #766: explicit "what's next?" footer. The Xenos path is action-only —
+  // no primer to read first — so a newcomer goes straight from setup to
+  // surveying the works. Ship three and the city makes you a Thetes.
+  try {
+    const meRes = await (await cliClient()).me.getMe();
+    if (meRes.ok) {
+      console.log('');
+      printOnboardingNudge(meRes.data);
+      console.log('');
+      console.log('Newcomer path:');
+      console.log(`  1. Choose thy craft:  open ${hallBase()} (creative / engineering)`);
+      console.log(`  2. Survey work:       ${surfaceAction('start')}`);
+      console.log(`  3. Claim + ship:      ${surfaceAction('claim', 'N')}    →    ${surfaceAction('ship')}`);
+      // Claiming writes code, so it needs a checkout. In a terminal the public CLI answers
+      // `bongos claim` with where to get one; say so here rather than let step 3 look self-serve.
+      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `npx bongos claim` shows how to get one)');
+      console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
+    }
+  } catch (_) {
+    // never let a UX footer break a successful setup
+  }
+}
+
+async function main() {
+  const forceFlag = process.argv.includes('--force');
+
+  // Environment preflight (task 1002401, onboarding-audit area 4). Before auth,
+  // surface the three things that used to bite a new builder one reactive crash
+  // at a time — Node, installed deps, a launchable `claude` CLI — each with a
+  // copy-paste fix, instead of `node: command not found` / `Cannot find module
+  // 'pg'` / SUBAGENT_SPAWN_FAILED turning up deep in the session. Read-only and
+  // NON-blocking: a fail is actionable, not fatal to sign-in, so it also runs in
+  // --dry-run. Shares one source of truth with `bongos doctor` (preflight.js).
+  try {
+    const { preflightChecks, formatPreflight } = require('./preflight');
+    console.log(formatPreflight(preflightChecks(), { color: process.stdout.isTTY, heading: true }));
+    console.log('');
+  } catch (err) {
+    console.error(`(environment preflight skipped: ${err.message})`);
+  }
+
+  // --dry-run: describe every side effect the real flow would perform, without
+  // doing any of them. No API calls, no file writes, no TTY prompts. Suitable
+  // for a newcomer to read before running for real. Intentionally calls
+  // loadSession() — which is read-only — so the preview tells them whether the
+  // real run would short-circuit on a pre-existing session.
+  if (DRY_RUN) {
+    console.log('Dry run — no API calls will be made and no files will be written.');
+    console.log('');
+    const preExisting = await loadSession();
+    if (preExisting && preExisting.token && !forceFlag) {
+      dryRunStep(`Would verify existing session at ${SESSION_PATH} via GET /api/bongos/me.`);
+      dryRunStep('If the token is valid: on an interactive shell, would ASK whether to continue as that builder or set up as a different one ([1] continue / [2] sign in again, replacing the saved session). Non-interactive shells keep the existing session. (--force skips the question and re-auths directly.)');
+      dryRunStep('If the token is rejected (401), would fall through to the Device Flow.');
+    } else if (preExisting && forceFlag) {
+      dryRunStep(`Existing session found at ${SESSION_PATH}, but --force is set; would skip verification.`);
+    } else {
+      dryRunStep(`No existing session at ${SESSION_PATH}; would proceed straight to Device Flow.`);
+    }
+    dryRunStep('Would POST /api/bongos/auth/device/start to get a user_code + verification_uri from GitHub.');
+    dryRunStep('If GitHub refuses with device_flow_disabled (a one-click App whose checkbox is unticked, task 1003051): would print the web sign-in guidance (hall Settings → CLI Access) and prompt for a pasted CLI token instead of dead-ending.');
+    dryRunStep('Would print the verification_uri and user_code, then poll /api/bongos/auth/device/poll every few seconds until the user approves or the code expires.');
+    dryRunStep(`On approval, would write the bearer token + builder profile to ${SESSION_PATH} (chmod 600).`);
+    if (SKIP_KEYS) {
+      dryRunStep('Would skip the Gemini-key prompt (--skip-keys set).');
+    } else {
+      dryRunStep(`Would prompt for a per-builder GOOGLE_AI_STUDIO_KEY on TTY shells and store it as gemini_api_key in ${SESSION_PATH} (mode 600). Used by modules/art-pipeline/pipeline/gen_api.py for per-builder cost attribution.`);
+    }
+    dryRunStep('Would read ~/.claude.json oauthAccount and, on a TTY, prompt to confirm the Anthropic email; on a match would POST /api/bongos/me/anthropic-link and store anthropic_user_id in the session (kept as cosmetic attribution; the identity pin was removed — task 1039 / idea 258). On mismatch would REFUSE to link.');
+    dryRunStep('Would prompt for preferred disciplines (creative / engineering / both / skip) and PATCH /api/bongos/me/disciplines on TTY shells.');
+    dryRunStep(`Would prompt for onboarding-friction consent (Y/n) and record the decision to ${onboardingConfig.CONSENT_PATH} on TTY shells.`);
+    dryRunStep('Would print "Authenticated as <github_login>" and exit 0.');
+    process.exit(0);
+  }
+
+  const existing = await loadSession();
+
+  // PRE-FLIGHT: don't trust the local session file's existence alone — the
+  // token can be expired (mig 035 1h TTL), revoked, or belong to a different
+  // builder identity. Verify against the live API before declaring "already
+  // authenticated". Three branches:
+  //   200 (token works)            → keep current session unless --force
+  //   401 (token rejected)         → fall through to Device Flow automatically
+  //   network error / non-200/401  → require --force to proceed; otherwise abort
+  if (existing && existing.token && !forceFlag) {
+    let verify;
+    try {
+      // allowUnauthenticated: a 401 here is a legitimate "session is stale,
+      // fall through to re-auth" signal, not the global "exit 2" failure mode.
+      verify = await (await cliClient({ allowUnauthenticated: true })).me.getMe();
+    } catch (err) {
+      console.error(`(Could not reach the GDS to verify the session: ${err.message})`);
+      console.error('Pass --force if you want to re-authenticate without verification.');
+      process.exit(1);
+    }
+    if (verify.status === 200) {
+      const b = verify.data?.builder || {};
+      const who = `${b.github_login || '(unknown)'} (id #${b.id || '?'}, rank=${b.rank || '?'})`;
+
+      // A valid session already exists on this machine. Don't silently adopt
+      // it. The session file is a single global path
+      // (~/.config/otb/bongos-session.json), so a second person setting up on a
+      // shared device — or the same person onboarding a different account,
+      // e.g. for testing — would otherwise be invisibly bound to whoever set
+      // up first. On an interactive shell, confirm before continuing; the gate
+      // runs BEFORE we exit, so switching is always reachable without the
+      // builder needing to know about --force. (Fix A — multiple builders on
+      // one device, #533.)
+      if (!process.stdin.isTTY) {
+        // Non-interactive (CI / batch / piped input): can't ask. Keep the safe
+        // default — adopt the existing valid session rather than clobber it.
+        // A caller who needs a different identity passes --force.
+        console.log(`Already authenticated as ${who}. No setup needed.`);
+        // Intentionally do NOT advertise --force / account-switching here. The
+        // session is valid; surfacing "sign in as a different account" to every
+        // already-authenticated builder positions switching as an expected next
+        // step (and reads as "switch to a more privileged account"). --force
+        // still works for anyone who explicitly needs it; it just isn't pitched.
+        process.exit(0);
+      }
+
+      console.log('');
+      console.log(`This device already has a builder session for ${who}.`);
+      console.log('Make sure that is the account you mean to build under.');
+      console.log('  [1] Continue as this builder');
+      console.log('  [2] Set up as a DIFFERENT builder (sign in again — replaces the saved session)');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+      let choice;
+      try {
+        choice = (await ask('Choose [1/2] (default 1): ')).trim();
+      } finally {
+        rl.close();
+      }
+      if (choice === '2') {
+        console.log('');
+        console.log('Setting up as a different builder — the saved session will be replaced once you finish signing in...');
+        // Fall through to the Device Flow below, which calls saveSession() and
+        // overwrites ~/.config/otb/bongos-session.json with the new identity.
+      } else {
+        console.log(`Continuing as ${who}.`);
+        process.exit(0);
+      }
+    } else if (verify.status === 401) {
+      console.log(`Session file present at ${SESSION_PATH}, but the token is no longer valid.`);
+      console.log('Falling through to Device Flow to re-authenticate automatically...');
+      // Intentional: do NOT require --force here. The on-disk session is dead;
+      // re-auth is the only forward path and forcing the builder to re-run with
+      // a flag adds friction with zero value.
+    } else {
+      console.error(`Could not verify session (HTTP ${verify.status}). Pass --force to re-auth anyway.`);
+      process.exit(1);
+    }
+  }
+
+  // Federation (ADR 0141 §1, task #1002108): a HOSTED instance has no GitHub app of
+  // its own — it federates sign-in through the Cloud Bongos hub. If the instance
+  // manifest advertises auth.idp, run the hub device flow + assertion exchange via
+  // the shared login.js runDeviceFlow, then the SAME onboarding prompts. The direct
+  // GitHub device flow below (auth.idp unset) is untouched — the self-hosted default.
+  let idpCfg = null;
+  try {
+    const m = await fetch(`${API_BASE}/api/bongos/instance`);
+    const mj = m.ok ? await m.json() : null;
+    idpCfg = (mj && mj.auth && mj.auth.idp) || null;
+  } catch (_) { /* manifest unreachable → fall through to the direct flow */ }
+  if (idpCfg) {
+    console.log('Signing in via the Cloud Bongos platform (hub)...');
+    const { runDeviceFlow } = require('./login');
+    const flow = await runDeviceFlow(API_BASE, { log: console.log, idp: idpCfg });
+    if (flow.state === 'not_approved') {
+      console.error('');
+      console.error('This GitHub account has not been approved yet.');
+      console.error('An Archon must approve your access request before you can enroll.');
+      console.error(`  → Ask an Archon to invite you, then re-run ${surfaceAction('setup')}.`);
+      process.exit(1);
+    }
+    if (flow.state !== 'ok') {
+      console.error(`\nSign-in did not complete (${flow.state}). Re-run ${surfaceAction('setup')}.`);
+      process.exit(1);
+    }
+    const { token, builder } = flow;
+    await saveSession({ token, builder, api_base: API_BASE });
+    console.log('');
+    console.log(`Authenticated as ${builder.github_login} (#${builder.id}). Session saved to ${SESSION_PATH}.`);
+    try {
+      const { activate } = require('./install-git-hooks');
+      activate();
+    } catch (_) { /* hook activation is best-effort */ }
+    await promptGeminiKey();
+    await promptAnthropicLink();
+    await promptDisciplines();
+    await promptOnboardingConsent();
+    process.exit(0);
+  }
+
+  console.log('Starting GitHub Device Flow...');
+  const start = await (await cliClient()).auth.postAuthDeviceStart();
+  if (!start.ok) {
+    // W1 (task 1003051): a manifest-born App refuses Device Flow until its owner
+    // ticks the checkbox — fall back to the hall's CLI-token path instead of
+    // dead-ending the documented setup command.
+    if (isDeviceFlowDisabled(start)) {
+      for (const line of deviceFlowFallbackLines(API_BASE)) console.log(line);
+      console.log('');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      // Resolve '' on stdin EOF too, so a non-interactive run exits with the
+      // guidance instead of hanging on a question nobody can answer.
+      const token = (await new Promise((resolve) => {
+        rl.question('Paste the CLI token here (or press Enter to quit): ', resolve);
+        rl.once('close', () => resolve(''));
+      })).trim();
+      rl.close();
+      if (!token) {
+        console.error('No token pasted — run the Settings page one-liner, then re-run setup.');
+        process.exit(1);
+      }
+      const redeemed = await redeemCliToken(token);
+      if (!redeemed.ok) process.exit(1);
+      console.log('');
+      console.log('Signed in via the web token — terminal Device Flow stays broken until the owner ticks the checkbox.');
+      await finishSetup(redeemed.builder);
+      process.exit(0);
+    }
+    console.error(`device/start failed (${start.status}):`, start.data);
+    if (errCode(start.data) === 'auth_not_configured') {  // ADR 0116 nests the slug (task 1003658)
+      console.error('');
+      console.error('The server does not yet have GitHub OAuth credentials.');
+      console.error('An Archon needs to register the GitHub OAuth App and provision credentials on the server.');
+      console.error('See blockers/blockers.md#github-oauth-app for the operator-side checklist.');
+    }
+    process.exit(1);
+  }
+  const { device_code, user_code, verification_uri, expires_in, interval } = start.data;
+  console.log('');
+  console.log('  ┌──────────────────────────────────────────────┐');
+  console.log(`  │ 1. Open: ${verification_uri.padEnd(36)} │`);
+  console.log(`  │ 2. Enter code: ${user_code.padEnd(30)} │`);
+  console.log('  └──────────────────────────────────────────────┘');
+  console.log('');
+  console.log(`Polling every ${interval}s for up to ${Math.round(expires_in / 60)} minutes...`);
+
+  const deadline = Date.now() + expires_in * 1000;
+  let pollInterval = interval * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, pollInterval));
+    const poll = await (await cliClient()).auth.postAuthDevicePoll({ body: { device_code } });
+    // Admission gate (SR-19 / task #1000): a first-time GitHub account that an
+    // Archon hasn't approved is refused (HTTP 403, state:'not_approved'). Print a
+    // clear, friendly explanation rather than a raw "poll failed" dump — this is
+    // expected, not a server error. (Mirrors the web flow's NOT_APPROVED page.)
+    if (poll.data && poll.data.state === 'not_approved') {
+      console.error('');
+      console.error('This GitHub account has not been approved yet.');
+      console.error(`${require('./cli-lib').productName()} admits new builders by invitation: an Archon must`);
+      console.error('approve your access request before you can enroll.');
+      console.error('  → Ask an Archon to invite you / approve your access request,');
+      console.error(isTerminalSurface()
+        ? `    then re-run ${surfaceAction('setup')}.`
+        : '    then re-run /builder-setup (or: node scripts/bongos/setup.js).');
+      process.exit(1);
+    }
+    if (!poll.ok) {
+      console.error(`poll failed (${poll.status}):`, poll.data);
+      process.exit(1);
+    }
+    const state = poll.data.state;
+    if (state === 'pending') {
+      process.stdout.write('.');
+      continue;
+    }
+    if (state === 'slow_down') {
+      pollInterval = (poll.data.interval || interval) * 1000;
+      continue;
+    }
+    if (state === 'denied') {
+      console.error('\nAuthentication denied by GitHub.');
+      process.exit(1);
+    }
+    if (state === 'expired') {
+      console.error('\nDevice code expired before approval.');
+      process.exit(1);
+    }
+    if (state === 'ok') {
+      const { token, builder } = poll.data;
+      await saveSession({ token, builder, api_base: API_BASE });
+      console.log('');
+      await finishSetup(builder);
+      process.exit(0);
+    }
+  }
+  console.error('\nTimed out waiting for approval.');
+  process.exit(1);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = { isDeviceFlowDisabled, deviceFlowFallbackLines, redeemCliToken };