@bongos/core 1.17.0

package/scripts/gds/box-auth-check.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+// scripts/gds/box-auth-check.js — dev-box session-start auth gate (task 1712).
+//
+// THE FIRST THING a dev-box session should confirm: that its GDS CLI session is
+// a REAL, full-authority session — not the box-scoped bootstrap token, and not
+// an expired one. A box's baked session is `source:'box'` (ADR 0053 / #919): it
+// may call the on-box bootstrap endpoints but is 403'd (`box_scope`) on
+// claim / ship / publish. Nothing used to surface that until a ship hit the
+// publish-branch wall (the 2026-07-02 incident: a doc couldn't be pushed and the
+// session burned time on raw `git push`). This check makes the session say, up
+// front, "re-auth first" so no work starts on a token that can't finish it.
+//
+// Self-gating + fail-open, by design:
+//   * NOT a dev box (no /etc/otb/box.env) → silent no-op. Laptops handle auth at
+//     point-of-use and can't be box-scoped, so this stays out of their way.
+//   * a subagent (OTB_SUBAGENT) → silent (grader/worker context stays clean).
+//   * box-scoped or missing session → the directive comes from the LOCAL file
+//     alone (no network) — instant, and exactly the incident case.
+//   * a real token present → ONE bounded, fail-open GET /me to also catch an
+//     EXPIRED/revoked token; a quiet '✓ authed' on success; silent when the
+//     network is flaky (point-of-use still catches a genuine problem — never
+//     cry wolf and never delay session start).
+//
+// Printed to stdout so the SessionStart hook forwards it into session context.
+// Wired FIRST (right after the identity card) in .claude/hooks/session-start.js.
+
+const fs = require('node:fs');
+
+const BOX_ENV_PATH = '/etc/otb/box.env';
+const ME_TIMEOUT_MS = 3000;
+
+// Pure decision — given the auth facts, what should the card do? Exported +
+// unit-tested (tests/box_auth_check.mjs). Never does I/O.
+//   onBox:       provisioned dev box (/etc/otb/box.env present)
+//   hasToken:    a local session file with a token exists
+//   isBoxScoped: that session is the baked box token (source === 'box')
+//   meStatus:    HTTP status of a bounded GET /me, or null (not attempted / network failed)
+// → { action: 'skip' | 'setup' | 'reauth' | 'ok', reason }
+//
+// Ordering matters: isBoxScoped is decided from the local file BEFORE any
+// meStatus, so the incident case never needs (or waits on) the network.
+function decideBoxAuth({ onBox, hasToken, isBoxScoped, meStatus }) {
+  if (!onBox) return { action: 'skip', reason: 'not-a-box' };
+  if (!hasToken) return { action: 'setup', reason: 'no-session' };
+  if (isBoxScoped) return { action: 'reauth', reason: 'box-scoped' };
+  if (meStatus === 200) return { action: 'ok', reason: 'validated' };
+  if (meStatus === 401 || meStatus === 403) return { action: 'reauth', reason: 'expired-or-revoked' };
+  // Couldn't definitively verify (no network / fetch unavailable / timeout /
+  // 5xx). A locally valid-looking real token is trusted; stay silent rather
+  // than warn falsely — the point-of-use guard (cli-lib) still catches a real
+  // 401/403 the moment a command runs.
+  return { action: 'skip', reason: 'unverified' };
+}
+
+function onBox() {
+  try {
+    return fs.existsSync(BOX_ENV_PATH);
+  } catch (_) {
+    return false;
+  }
+}
+
+// Bounded, fail-open GET /me. Returns { status, login }; status is null and
+// login is null on ANY failure (no global fetch, network error, abort/timeout).
+// Never throws.
+async function probeMe(tokenInfo) {
+  if (!tokenInfo || !tokenInfo.token || typeof fetch !== 'function') {
+    return { status: null, login: null };
+  }
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), ME_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${tokenInfo.apiBase}/api/gds/me`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${tokenInfo.token}`, 'User-Agent': 'box-auth-check/1.0' },
+      signal: ctl.signal,
+    });
+    let login = null;
+    if (res.ok) {
+      try {
+        const j = await res.json();
+        login = (j && j.builder && j.builder.github_login) || null;
+      } catch (_) { /* body parse is cosmetic only */ }
+    }
+    return { status: res.status, login };
+  } catch (_) {
+    return { status: null, login: null };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function printReauth({ boxScoped }) {
+  const why = boxScoped
+    ? 'This box holds the BOX-SCOPED bootstrap token (source=box, ADR 0053) — it can bootstrap the box but is refused (403) on claim / ship / publish.'
+    : 'This session token is EXPIRED or revoked (CLI tokens carry a 24h idle TTL).';
+  console.log('[otb] ── dev box: RE-AUTH BEFORE YOU WORK ──');
+  console.log(`[otb] ${why}`);
+  console.log('[otb] ⚠ FIRST STEP this session: get the builder onto a real CLI session BEFORE claiming or shipping —');
+  console.log('[otb]   run /builder-reauth (UI-first: opens Settings → "Re-issue CLI token" → paste the one-liner back).');
+  console.log('[otb]   Work claimed on this token cannot be shipped/published — it will strand at the publish 403 wall.');
+}
+
+function printSetup() {
+  console.log('[otb] ── dev box: NO GDS SESSION — SIGN IN BEFORE YOU WORK ──');
+  console.log('[otb] ⚠ No CLI session was found on this box. FIRST STEP this session: sign in before claiming or');
+  console.log('[otb]   shipping any work — run /builder-reauth (UI-first), or /builder-setup for a brand-new machine.');
+}
+
+async function main() {
+  if (process.env.OTB_SUBAGENT) return;
+  if (!onBox()) return;
+
+  let lib;
+  let session = null;
+  let tokenInfo = null;
+  try {
+    lib = require('./cli-lib');
+    session = lib.loadSessionSync();
+    tokenInfo = lib.readSessionToken();
+  } catch (_) {
+    // cli-lib unreadable → treat as no-session (the setup path), which is the
+    // safe, actionable default rather than silence.
+  }
+
+  const hasToken = !!(session && session.token);
+  const isBoxScoped = !!(session && session.source === 'box');
+
+  // Only pay a network round-trip when a real (non-box) token is present — the
+  // box-scoped and no-session cases are already decided from the file alone.
+  let meStatus = null;
+  let login = null;
+  if (hasToken && !isBoxScoped) {
+    ({ status: meStatus, login } = await probeMe(tokenInfo));
+  }
+
+  const { action } = decideBoxAuth({ onBox: true, hasToken, isBoxScoped, meStatus });
+  if (action === 'reauth') {
+    printReauth({ boxScoped: isBoxScoped });
+  } else if (action === 'setup') {
+    printSetup();
+  } else if (action === 'ok') {
+    console.log(`[otb] ✓ dev box: GDS session is a real CLI session${login ? ` (signed in as ${login})` : ''} — clear to claim + ship.`);
+  }
+  // action === 'skip' → say nothing (off-box handled above; 'unverified' is silent).
+}
+
+// Direct run (the SessionStart hook spawns `node .../box-auth-check.js`) — run
+// the check and exit fast. A require() of this file (the unit test importing
+// decideBoxAuth) must NOT run main, so guard on require.main. The watchdog is
+// belt-and-suspenders: the SessionStart hook spawns this synchronously with no
+// timeout of its own, so guarantee a bounded exit even if something wedges (the
+// fetch already self-aborts at ME_TIMEOUT_MS).
+if (require.main === module) {
+  const watchdog = setTimeout(() => process.exit(0), ME_TIMEOUT_MS + 1500);
+  watchdog.unref();
+  main().then(() => process.exit(0)).catch(() => process.exit(0));
+}
+
+module.exports = { decideBoxAuth, onBox, printReauth, printSetup };

package/scripts/gds/box-connect-lib.js

@@ -0,0 +1,453 @@
+// scripts/gds/box-connect-lib.js — shared machinery for `bongos shell` / `bongos code`
+// (GDS-V4 · V4.R80 · task 1247; Phase 2 of the bongos toolkit, epic 1245).
+//
+// `bongos shell` opens a terminal on the builder's cloud dev box; `bongos code`
+// attaches VS Code over Remote-SSH at /workspace. Both reduce to the same four
+// steps, which live here so the two verbs stay thin and the string-building is
+// unit-testable without a network or a box:
+//
+//   1. Ensure the local ed25519 key exists (~/.ssh/otb_builder) and is registered
+//      with the GDS — so a FRESH laptop with no prior setup still connects.
+//   2. Wake/provision the box (POST /box/ensure) and poll (GET /box/me) until it
+//      is active and has a hostname (DNS is repointed on every wake/provision, so
+//      we always connect by hostname, never a cached IP).
+//   3. Pin the box's reported host keys into ~/.ssh/known_hosts (authoritative,
+//      survives a re-provision) and write a marker-delimited Host alias into
+//      ~/.ssh/config (User root + the box key) so the system OpenSSH client — the
+//      one VS Code Remote-SSH drives — resolves the box the same way every time.
+//   4. Hand off to `ssh` / `code`.
+//
+// No bash-isms: node is the one guaranteed runtime (#686). The pure helpers below
+// (buildSshAliasBlock, upsertSshConfigText, buildKnownHostsUpsert, rankAtLeast,
+// buildRemoteShellCommand, parseEnsure, remoteAuthority) take no I/O and are
+// covered by tests/bongos_box_connect.mjs.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const ic = require('../../src/instance-config');
+const { cliClient } = require('./cli-lib');
+
+// The box always runs as root and the repo is cloned to /workspace (the devcontainer
+// standardizes the same path). NOT ~/workspace — root's ~ is /root, which has no clone.
+const BOX_USER = 'root';
+const WORKSPACE = '/workspace';
+// VS Code extension id for Claude Code (mirrors .devcontainer/devcontainer.json).
+const CLAUDE_VSCODE_EXTENSION = 'anthropic.claude-code';
+
+// The rank ladder, entry→top. `--local` is a Metic+ convenience gate (a nudge to
+// keep newcomers on the standard cloud box, NOT a security boundary — real
+// authority is server-side and unaffected). thetes sits between xenos and metic
+// even though requires_rank only enumerates xenos/metic/archon.
+const RANK_ORDER = { xenos: 0, thetes: 1, metic: 2, archon: 3 };
+
+function rankAtLeast(rank, min) {
+  const r = RANK_ORDER[rank];
+  const m = RANK_ORDER[min];
+  if (r == null || m == null) return false;
+  return r >= m;
+}
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// -------------------------------------------------------------------------
+// Pure string builders (no I/O — unit tested)
+// -------------------------------------------------------------------------
+
+// A marker-delimited, idempotent Host block for ONE box. Markers carry the
+// hostname so re-running upserts THIS box's block without touching any other
+// (a builder may connect to more than one instance's box over time).
+function buildSshAliasBlock({ hostname, identityFile }) {
+  return [
+    `# >>> bongos-managed dev-box: ${hostname} >>>`,
+    `Host ${hostname}`,
+    `    HostName ${hostname}`,
+    `    User ${BOX_USER}`,
+    `    IdentityFile ${identityFile}`,
+    `    IdentitiesOnly yes`,
+    `    StrictHostKeyChecking accept-new`,
+    `# <<< bongos-managed dev-box: ${hostname} <<<`,
+  ].join('\n');
+}
+
+// Upsert the alias block into an existing ~/.ssh/config body. Replaces this
+// host's block in place if present, else appends it with a blank-line gap.
+function upsertSshConfigText(existing, { hostname, identityFile }) {
+  const block = buildSshAliasBlock({ hostname, identityFile });
+  const h = escapeRegExp(hostname);
+  const re = new RegExp(
+    `# >>> bongos-managed dev-box: ${h} >>>[\\s\\S]*?# <<< bongos-managed dev-box: ${h} <<<`,
+    'm'
+  );
+  const base = existing || '';
+  if (re.test(base)) return base.replace(re, block);
+  const gap = base ? (base.endsWith('\n') ? '\n' : '\n\n') : '';
+  return `${base}${gap}${block}\n`;
+}
+
+// Authoritative known_hosts upsert: drop any stale line for THIS host (exact
+// field-1 match), keep every other host, then append the box's reported keys.
+// hostKeysRaw is the newline-joined `<keytype> <base64>` string from /box/me.
+function buildKnownHostsUpsert(existing, hostname, hostKeysRaw) {
+  const keep = (existing || '')
+    .split('\n')
+    .filter((line) => line.trim() && line.split(/\s+/)[0] !== hostname);
+  const added = (hostKeysRaw || '')
+    .split('\n')
+    .map((k) => k.trim())
+    .filter(Boolean)
+    .map((k) => `${hostname} ${k}`);
+  const all = [...keep, ...added];
+  return all.length ? all.join('\n') + '\n' : '';
+}
+
+// The remote command `ssh -t root@host …` runs. Lands the builder in /workspace;
+// on the first connection to this box it runs an interactive `claude` first so the
+// Trusted-Devices /login enrollment (interactive-only by design — ADR 0038) is
+// completed once, then drops to a login shell. Silent on every later connect.
+function buildRemoteShellCommand({ firstRun = false, workdir = WORKSPACE } = {}) {
+  const cd = `cd ${workdir} 2>/dev/null || true`;
+  const login = firstRun
+    ? `echo '↪ First time on this box — complete /login in claude once (browser device flow), then exit to a shell.'; claude || true; `
+    : '';
+  return `${cd}; ${login}exec bash -l`;
+}
+
+// VS Code Remote-SSH authority for a host (VS Code resolves it via the ~/.ssh
+// Host alias we wrote, so User/IdentityFile/host-key policy all apply).
+function remoteAuthority(hostname) {
+  return `ssh-remote+${hostname}`;
+}
+
+// Normalize the POST /box/ensure body into { action, state, message }.
+function parseEnsure(data) {
+  const d = data || {};
+  return { action: d.action || null, state: d.state || null, message: d.message || null };
+}
+
+// -------------------------------------------------------------------------
+// Local toolchain + paths (thin I/O)
+// -------------------------------------------------------------------------
+
+function sshKeyPath() {
+  // OTB_SSH_KEY (via the instance env prefix) is the advanced/test override; the
+  // Dev Box app + connect.sh both pin the fixed ~/.ssh/otb_builder default.
+  return ic.resolveEnv('SSH_KEY') || path.join(os.homedir(), '.ssh', 'otb_builder');
+}
+
+function sshDir() {
+  return path.join(os.homedir(), '.ssh');
+}
+
+// Is a CLI launchable? (shell:true on win32 so a .cmd/.exe shim resolves — same
+// posture as doctor.js's claude/gh checks.)
+function binPresent(bin, versionArgs = ['--version']) {
+  try {
+    const r = spawnSync(bin, versionArgs, {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    return !!r && !r.error && (r.status === 0 || r.status === null);
+  } catch (_) {
+    return false;
+  }
+}
+
+// Local SHA256 fingerprint of a public key, or null if ssh-keygen can't read it.
+function localKeyFingerprint(pubPath) {
+  try {
+    const r = spawnSync('ssh-keygen', ['-lf', pubPath], {
+      encoding: 'utf8',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+      timeout: 15000,
+    });
+    if (!r || r.error || r.status !== 0) return null;
+    const m = (r.stdout || '').match(/SHA256:[A-Za-z0-9+/=]+/);
+    return m ? m[0] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// -------------------------------------------------------------------------
+// SSH key: ensure it exists locally + is registered with the GDS
+// -------------------------------------------------------------------------
+
+// Ensure ~/.ssh/otb_builder exists (generate an ed25519 pair if not) and return
+// { keyPath, pubKey, created }. Throws with actionable guidance if ssh-keygen is
+// missing or the key can't be read.
+function ensureSshKey({ log = console.log } = {}) {
+  const keyPath = sshKeyPath();
+  const pubPath = `${keyPath}.pub`;
+  let created = false;
+  if (!fs.existsSync(keyPath)) {
+    fs.mkdirSync(sshDir(), { recursive: true });
+    try {
+      fs.chmodSync(sshDir(), 0o700);
+    } catch (_) {
+      /* best-effort on non-POSIX */
+    }
+    log(`  Creating an SSH key at ${keyPath.replace(os.homedir(), '~')} (private half stays on this machine)…`);
+    const comment = `bongos ${os.hostname() || 'device'}`.slice(0, 80);
+    // No separate presence probe — ssh-keygen has no side-effect-free version
+    // flag, and a missing binary surfaces here as ENOENT with a clear message.
+    const r = spawnSync('ssh-keygen', ['-t', 'ed25519', '-N', '', '-C', comment, '-f', keyPath, '-q'], {
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      windowsHide: true,
+    });
+    if (r && r.error && r.error.code === 'ENOENT') {
+      throw new Error(
+        'ssh-keygen was not found. Install OpenSSH (macOS/Linux ship it; on Windows enable the "OpenSSH Client" optional feature) and re-run.'
+      );
+    }
+    if (!r || r.error || r.status !== 0) {
+      throw new Error(`ssh-keygen failed to create ${keyPath}${r && r.error ? `: ${r.error.message}` : ''}`);
+    }
+    created = true;
+  }
+  let pubKey = null;
+  try {
+    // Trim to "<type> <base64>" — matches what connect.sh/the server keep.
+    const parts = fs.readFileSync(pubPath, 'utf8').trim().split(/\s+/);
+    if (parts.length >= 2) pubKey = `${parts[0]} ${parts[1]}`;
+  } catch (_) {
+    /* handled below */
+  }
+  if (!pubKey) throw new Error(`could not read a valid public key from ${pubPath}`);
+  return { keyPath, pubKey, created };
+}
+
+// Register the public key with the GDS if it isn't already. Registers
+// unconditionally when we just generated it (fresh laptop); otherwise only when
+// the server's key list doesn't already carry this fingerprint — so re-runs don't
+// spam the 10-key-per-builder cap. Best-effort: a failure here is surfaced as a
+// warning, not fatal (SSH will report a genuine auth problem clearly).
+async function ensureKeyRegistered({ created, keyPath, pubKey, log = console.log } = {}) {
+  const api = await cliClient();
+  let needed = created;
+  if (!needed) {
+    const fp = localKeyFingerprint(`${keyPath}.pub`);
+    let listed = null;
+    try {
+      const res = await api.box.getBoxSshKey();
+      if (res.ok && res.data && Array.isArray(res.data.keys)) listed = res.data.keys;
+    } catch (_) {
+      /* tolerate — fall through to the heuristics below */
+    }
+    if (fp && Array.isArray(listed)) {
+      needed = !listed.some((k) => k && k.fingerprint === fp);
+    } else if (fp == null && Array.isArray(listed) && listed.length > 0) {
+      needed = false; // can't compare, but keys exist → assume registered
+    } else {
+      needed = false; // no info → don't spam; SSH will surface a real auth failure
+    }
+  }
+  if (!needed) return { registered: false };
+  try {
+    const label = `bongos ${process.platform}`.slice(0, 80);
+    const res = await api.box.postBoxSshKey({ body: { public_key: pubKey, label } });
+    if (res.ok) {
+      log('  ✓ Registered your public key with the dev system.');
+      return { registered: true };
+    }
+    log(`  ! Could not register your key (${res.data?.error || res.status}); if SSH is refused, add it via /builder-box.`);
+  } catch (err) {
+    log(`  ! Could not register your key (${err.message}); if SSH is refused, add it via /builder-box.`);
+  }
+  return { registered: false };
+}
+
+// -------------------------------------------------------------------------
+// Box lifecycle: ensure active + read connection details
+// -------------------------------------------------------------------------
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Wake/provision the box and poll until it is active with a hostname. Returns the
+// public box object from /box/me ({ state, hostname, ip, host_keys, … }).
+// Throws on a provision denial (rank/blocked) or a timeout.
+async function ensureBoxActive({ log = console.log, timeoutMs = 6 * 60 * 1000, intervalMs = 5000, sleepFn = sleep } = {}) {
+  const api = await cliClient();
+  const ensureRes = await api.box.postBoxEnsure();
+  if (ensureRes.status === 403) {
+    const msg = ensureRes.data?.message || ensureRes.data?.reason || 'dev-box access denied';
+    throw new Error(`Box could not be started: ${msg}`);
+  }
+  if (!ensureRes.ok) {
+    throw new Error(`POST /box/ensure failed (HTTP ${ensureRes.status}${ensureRes.data?.error ? `: ${ensureRes.data.error}` : ''})`);
+  }
+  const { action, message } = parseEnsure(ensureRes.data);
+  if (action === 'ready') {
+    log('  ✓ Box is already active.');
+  } else {
+    log(`  Box is being ${action === 'wake' ? 'woken' : action === 'provision' ? 'created' : 'prepared'} — ${message || 'this can take a minute or two'}.`);
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  let lastState = null;
+  let announced = 0;
+  for (;;) {
+    const me = await api.box.getBoxMe();
+    const box = me.ok && me.data ? me.data.box : null;
+    if (box && box.state === 'active' && box.hostname) {
+      log(`  ✓ Box active: ${box.hostname}`);
+      return box;
+    }
+    if (box && box.state !== lastState) {
+      lastState = box.state;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the box to become active (last state: ${box ? box.state : 'unknown'}). ` +
+          'It may still be provisioning — re-run in a minute, or check `bongos box` / the hall.'
+      );
+    }
+    // A quiet progress line every ~15s so the wait doesn't look hung.
+    if (Date.now() - announced >= 15000) {
+      log(`  …still ${box && box.state ? box.state : 'starting'} (waiting for the box to come up)`);
+      announced = Date.now();
+    }
+    await sleepFn(intervalMs);
+  }
+}
+
+// Fetch the caller's rank (GET /me). Returns the rank string, or null if it
+// can't be determined.
+async function fetchRank() {
+  try {
+    const api = await cliClient({ allowUnauthenticated: true });
+    const res = await api.me.getMe();
+    if (res.ok && res.data && res.data.builder) return res.data.builder.rank || null;
+  } catch (_) {
+    /* fall through */
+  }
+  return null;
+}
+
+// -------------------------------------------------------------------------
+// Write ~/.ssh/config alias + pin known_hosts (idempotent, best-effort)
+// -------------------------------------------------------------------------
+
+function writeSshAlias({ hostname, keyPath, log = console.log }) {
+  const cfgPath = path.join(sshDir(), 'config');
+  // IdentityFile keeps the ~ literal so it reads cleanly and works cross-machine.
+  const identityFile = keyPath.startsWith(os.homedir())
+    ? keyPath.replace(os.homedir(), '~')
+    : keyPath;
+  let existing = '';
+  try {
+    existing = fs.readFileSync(cfgPath, 'utf8');
+  } catch (_) {
+    /* no config yet */
+  }
+  const next = upsertSshConfigText(existing, { hostname, identityFile });
+  if (next !== existing) {
+    fs.mkdirSync(sshDir(), { recursive: true });
+    fs.writeFileSync(cfgPath, next, { mode: 0o600 });
+    try {
+      fs.chmodSync(cfgPath, 0o600);
+    } catch (_) {
+      /* best-effort */
+    }
+    log(`  ✓ Wrote SSH host alias for ${hostname} into ~/.ssh/config`);
+  }
+}
+
+function pinKnownHosts({ hostname, hostKeys, log = console.log }) {
+  if (!hostKeys) return; // box hasn't reported keys yet; accept-new covers first connect
+  const khPath = path.join(sshDir(), 'known_hosts');
+  let existing = '';
+  try {
+    existing = fs.readFileSync(khPath, 'utf8');
+  } catch (_) {
+    /* none yet */
+  }
+  const next = buildKnownHostsUpsert(existing, hostname, hostKeys);
+  if (next !== existing) {
+    fs.mkdirSync(sshDir(), { recursive: true });
+    fs.writeFileSync(khPath, next, { mode: 0o600 });
+    try {
+      fs.chmodSync(khPath, 0o600);
+    } catch (_) {
+      /* best-effort */
+    }
+    log(`  ✓ Pinned ${hostname}'s verified host key(s) into ~/.ssh/known_hosts`);
+  }
+}
+
+// The one-shot "get the box ready + local SSH set up" used by both verbs.
+// Returns { box, keyPath }.
+async function prepareConnection({ log = console.log } = {}) {
+  const { keyPath, pubKey, created } = ensureSshKey({ log });
+  await ensureKeyRegistered({ created, keyPath, pubKey, log });
+  const box = await ensureBoxActive({ log });
+  pinKnownHosts({ hostname: box.hostname, hostKeys: box.host_keys, log });
+  writeSshAlias({ hostname: box.hostname, keyPath, log });
+  return { box, keyPath };
+}
+
+// First-run marker (per box hostname). /login enrollment persists on the box, so
+// we only force the interactive claude handoff the first time we connect to a
+// given box from this laptop.
+function loginMarkerPath(hostname) {
+  const safe = String(hostname).replace(/[^A-Za-z0-9._-]/g, '_');
+  return ic.configPath(`box-login-${safe}.done`);
+}
+
+function isFirstLogin(hostname) {
+  return !fs.existsSync(loginMarkerPath(hostname));
+}
+
+function markLoginDone(hostname) {
+  const p = loginMarkerPath(hostname);
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${new Date().toISOString()}\n`);
+  } catch (_) {
+    /* best-effort — a missed marker just re-runs the harmless handoff */
+  }
+}
+
+module.exports = {
+  // constants
+  BOX_USER,
+  WORKSPACE,
+  CLAUDE_VSCODE_EXTENSION,
+  RANK_ORDER,
+  // pure helpers (tested)
+  rankAtLeast,
+  buildSshAliasBlock,
+  upsertSshConfigText,
+  buildKnownHostsUpsert,
+  buildRemoteShellCommand,
+  remoteAuthority,
+  parseEnsure,
+  // toolchain / paths
+  sshKeyPath,
+  binPresent,
+  localKeyFingerprint,
+  // key + box
+  ensureSshKey,
+  ensureKeyRegistered,
+  ensureBoxActive,
+  fetchRank,
+  // local ssh wiring
+  writeSshAlias,
+  pinKnownHosts,
+  prepareConnection,
+  // first-run login handoff
+  loginMarkerPath,
+  isFirstLogin,
+  markLoginDone,
+};