@bongos/core 1.17.0

package/scripts/gds/setup.js

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+// Builder setup — runs the GitHub Device Flow and stores the session token.
+//
+// Usage:
+//   node scripts/gds/setup.js              run interactively, perform the auth
+//   node scripts/gds/setup.js --force      re-auth even if a valid session exists
+//   node scripts/gds/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/gds/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/gds-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, saveSession, SESSION_PATH, loadSession, printOnboardingNudge, API_BASE } = require('./cli-lib');
+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/gds-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('   https://amazonprimea.com/builders/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 https://status.amazonprimea.com.');
+    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();
+  }
+}
+
+(async () => {
+  const forceFlag = process.argv.includes('--force');
+
+  // --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/gds/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/gds/auth/device/start to get a user_code + verification_uri from GitHub.');
+    dryRunStep('Would print the verification_uri and user_code, then poll /api/gds/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/gds/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/gds/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/gds-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/gds-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);
+    }
+  }
+
+  console.log('Starting GitHub Device Flow...');
+  const start = await (await cliClient()).auth.postAuthDeviceStart();
+  if (!start.ok) {
+    console.error(`device/start failed (${start.status}):`, start.data);
+    if (start.data?.error === 'auth_not_configured') {
+      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('Off the Boats 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('    then re-run /builder-setup (or: node scripts/gds/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('');
+      console.log('');
+      console.log(`Authenticated as ${builder.github_login} (#${builder.id})`);
+      console.log(`Display name: ${builder.display_name}`);
+      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 pre-commit secrets guard AND the pre-push permission gate run. 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();
+        if (r.status === 'activated') console.log('Git hooks activated (pre-commit secrets guard + pre-push permission gate)');
+        else if (r.status === 'already-active') console.log('Git hooks already active (pre-commit + pre-push gates)');
+        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 https://amazonprimea.com/builders (creative / engineering)');
+          console.log('  2. Survey work:       /builder-start');
+          console.log('  3. Claim + ship:      /builder-claim N    →    /builder-ship');
+          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
+      }
+      process.exit(0);
+    }
+  }
+  console.error('\nTimed out waiting for approval.');
+  process.exit(1);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/gds/shell.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// scripts/gds/shell.js — `bongos shell` (GDS-V4 · V4.R80 · task 1247).
+//
+// Opens a terminal on the builder's cloud dev box. Wakes/provisions it first
+// (POST /box/ensure), ensures the local SSH key exists + is registered, pins the
+// box host key, then `ssh -t root@<host>` into /workspace. On the FIRST connect to
+// a given box it runs an interactive `claude` so the one-time /login (Trusted
+// Devices enrollment, interactive-only by design — ADR 0038) is completed; silent
+// after that.
+//
+//   bongos shell                 interactive shell on the cloud box
+//   bongos shell -- <cmd...>      run <cmd> on the box (non-interactive)
+//   bongos shell --login          force the first-run `claude` /login handoff
+//   bongos shell --local          open a shell on the LOCAL clone (Metic+ only)
+
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync, execFileSync } = require('node:child_process');
+const lib = require('./box-connect-lib');
+
+function repoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim();
+  } catch (_) {
+    return process.cwd();
+  }
+}
+
+async function runLocal({ remoteCmd, log }) {
+  const rank = await lib.fetchRank();
+  if (!lib.rankAtLeast(rank, 'metic')) {
+    console.error(
+      `✖ \`--local\` is a Metic+ convenience (your rank: ${rank || 'unknown'}). ` +
+        'The standard environment is the cloud box: run `bongos shell` without `--local`.'
+    );
+    process.exit(1);
+  }
+  const root = repoRoot();
+  log(`▸ Local clone: ${root.replace(os.homedir(), '~')}`);
+  const isDevcontainer = require('node:fs').existsSync(path.join(root, '.devcontainer', 'devcontainer.json'));
+  if (isDevcontainer) {
+    log('  (a .devcontainer is present — open it in VS Code with `bongos code --local`, then "Reopen in Container".)');
+  }
+  if (remoteCmd) {
+    const r = spawnSync(remoteCmd[0], remoteCmd.slice(1), { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' });
+    process.exit(r.status == null ? 1 : r.status);
+  }
+  const shell = process.env.SHELL || (process.platform === 'win32' ? process.env.COMSPEC || 'cmd.exe' : 'bash');
+  const r = spawnSync(shell, process.platform === 'win32' ? [] : ['-l'], { cwd: root, stdio: 'inherit' });
+  process.exit(r.status == null ? 1 : r.status);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const local = argv.includes('--local');
+  const forceLogin = argv.includes('--login');
+  let rest = argv.filter((a) => a !== '--local' && a !== '--login');
+  if (rest[0] === '--') rest = rest.slice(1);
+  const remoteCmd = rest.length ? rest : null;
+  const log = console.log;
+
+  if (local) return runLocal({ remoteCmd, log });
+
+  if (!lib.binPresent('ssh', ['-V'])) {
+    console.error('✖ The `ssh` client was not found. Install OpenSSH (macOS/Linux ship it; on Windows enable the "OpenSSH Client" optional feature) and re-run.');
+    process.exit(1);
+  }
+
+  console.log('▸ Connecting to your Amazonprimea dev box…');
+  const { box, keyPath } = await lib.prepareConnection({ log });
+  const host = box.hostname;
+
+  const sshArgs = ['-t', '-i', keyPath, '-o', 'IdentitiesOnly=yes', '-o', 'StrictHostKeyChecking=accept-new', `${lib.BOX_USER}@${host}`];
+  let firstRun = false;
+  if (remoteCmd) {
+    // Everything after the host IS the remote command (ssh option parsing stops
+    // at the destination), so pass the tokens directly — no `--` separator, which
+    // ssh would forward to the remote shell as a bogus first word.
+    sshArgs.push(...remoteCmd);
+  } else {
+    firstRun = forceLogin || lib.isFirstLogin(host);
+    sshArgs.push(lib.buildRemoteShellCommand({ firstRun }));
+    console.log(`▸ Opening a shell on ${host} (${lib.WORKSPACE})…`);
+  }
+
+  const r = spawnSync('ssh', sshArgs, { stdio: 'inherit' });
+  if (r.error) {
+    console.error(`✖ ssh failed to launch: ${r.error.message}`);
+    process.exit(1);
+  }
+  if (firstRun && r.status === 0) lib.markLoginDone(host);
+  process.exit(r.status == null ? 1 : r.status);
+}
+
+main().catch((err) => {
+  console.error(`✖ ${err.message}`);
+  process.exit(1);
+});