@bongos/core 1.19.902 → 1.19.903

package/tests/plain_cards.mjs

@@ -107,7 +107,7 @@ test('every card is complete, and short enough to be read', () => {
 
 test('the restrictions that must never be worked around are marked by_design', () => {
   for (const code of ['REBASE_REQUIRED', 'INSUFFICIENT_RANK', 'rank_too_low_for_task', 'session_already_has_active_claim',
-    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'box_scope', 'no_push_credential', 'grade_refused_authorization']) {
+    'main_checkout_claim', 'ship:protected_branch', 'ship:auth', 'no_push_credential', 'grade_refused_authorization']) {
     assert.equal(cardFor(code)?.by_design, true, code);
   }
   assert.match(cardFor('no_push_credential').next, /never ask/i);
@@ -164,7 +164,7 @@ test('a person at a terminal gets no card — it is written in the agent\'s voic
 
 test('the sign-in printers, the release refusals and the claim guard each print their card', () => {
   const wired = {
-    'scripts/gds/cli-lib.js': ['session_invalid', 'box_scope', 'no_session'],
+    'scripts/gds/cli-lib.js': ['session_invalid', 'no_session'],
     'scripts/gds/release.js': ['no_active_claim', 'CLAIM_SESSION_MISMATCH'],
     'scripts/gds/claim.js': ['main_checkout_claim'],
     'scripts/gds/ship-land.js': ['land_pending', 'reconcile_blocked'],

package/tests/rank_tier_single_source.mjs

@@ -12,7 +12,7 @@
 //      modules/discord/discord-channels.js): dependency-free substrate
 //      (permission-path-check runs in a bare git hook), source-parsed literals
 //      (src/bongos/db.js — gate-review.js + diagram-facts.js regex its text),
-//      standalone CLIs (sequence, box-connect-lib), the require-free dev-box
+//      standalone CLIs (sequence), the require-free dev-box
 //      module template (boxes.js), zero-dep catalog + its text-parsing auditor
 //      (route-rank-check), and the hall browser statics.
 //   3. NO NEW parallel map can land: a repo scan flags any rank→number map or
@@ -38,7 +38,6 @@ const lifecycleDb = require(path.join(ROOT, 'modules', 'lifecycle', 'db.js'));
 const ppc = require(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'));
 const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
 const sequence = require(path.join(ROOT, 'scripts', 'gds', 'sequence.js'));
-const boxConnect = require(path.join(ROOT, 'scripts', 'gds', 'box-connect-lib.js'));
 const boxes = require(path.join(ROOT, 'modules', 'dev-box', 'boxes.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
 
@@ -82,8 +81,8 @@ test('1-based local copies match: permission-path-check, sequence CLI', () => {
   assert.deepEqual(sequence.RANK_TIER, TIER, 'sequence.js CLI copy drifted');
 });
 
-test('0-based local copies match: box-connect-lib CLI, dev-box boxes.js', () => {
-  for (const [name, map] of [['box-connect-lib', boxConnect.RANK_ORDER], ['boxes', boxes.RANK_ORDER]]) {
+test('0-based local copies match: dev-box boxes.js', () => {
+  for (const [name, map] of [['boxes', boxes.RANK_ORDER]]) {
     assert.deepEqual(Object.keys(map).sort(), [...RANK_KEYS].sort(), `${name} keys drifted`);
     for (const r of RANK_KEYS) {
       assert.equal(map[r], TIER[r] - 1, `${name}.RANK_ORDER.${r} must be tier-1 (0-based)`);
@@ -193,7 +192,6 @@ const MAP_ALLOWLIST = new Set([
   'src/bongos/db.js',
   'src/bongos/permission-path-check.js',
   'scripts/gds/sequence.js',
-  'scripts/gds/box-connect-lib.js',
   'modules/dev-box/boxes.js',
   'modules/hall-ui/public/builders.js',
   // task 1003206 carved the hall page scripts up. builders.js KEPT its map (the

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

@@ -1,550 +0,0 @@
-// 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 crypto = require('node:crypto');
-const { spawnSync } = require('node:child_process');
-const ic = require('../../src/instance-config');
-const { cliClient, surfaceAction, assertDevBoxAvailable } = 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`;
-}
-
-// Does a known_hosts line name any of `names`? Field 1 is either a plain
-// `host` / `host,ip` LIST, or — with HashKnownHosts on (the Debian/Ubuntu default)
-// — the opaque `|1|<b64 salt>|<b64 hash>` form, hash = HMAC-SHA1(salt) of the name.
-//
-// (This duplicates ssh-setup.knownHostsLineMatchesHost on purpose: the Dev Box app
-// under modules/dev-box/app/ is a separately-packaged subproject with ZERO requires
-// into the repo — see modules/dev-box/CLAUDE.md — so the two cannot share a module.)
-function knownHostsLineNamesAny(line, names) {
-  const t = String(line || '').trim();
-  if (!t || t.startsWith('#')) return false;
-  const field = t.split(/\s+/)[0] || '';
-  const wanted = names.filter(Boolean).map(String);
-  if (!wanted.length) return false;
-  if (!field.startsWith('|1|')) {
-    const listed = field.split(',');
-    return wanted.some((n) => listed.includes(n));
-  }
-  const [, , salt, hash] = field.split('|');
-  if (!salt || !hash) return false;
-  try {
-    const key = Buffer.from(salt, 'base64');
-    return wanted.some((n) => crypto.createHmac('sha1', key).update(n).digest('base64') === hash);
-  } catch (_) {
-    return false; // unparseable salt → leave the line alone rather than guess
-  }
-}
-
-// Authoritative known_hosts upsert: drop EVERY stale line for this box, keep every
-// other host, then append the box's reported keys. hostKeysRaw is the newline-joined
-// `<keytype> <base64>` string from /box/me; `ip` is optional and drops an IP-keyed
-// line for the same box.
-//
-// It used to compare field 1 to the hostname with `!==`, which missed the two forms
-// OpenSSH actually writes — `host,192.0.2.4` (what `StrictHostKeyChecking=accept-new`
-// records) and the hashed `|1|salt|hash`. Those lines survived the "replace", so
-// every re-pin ACCUMULATED another entry and the client kept verifying against the
-// first, now-wrong one: "Host denied (verification failed)" on a box that had just
-// re-reported valid keys. Comments and blank lines are preserved.
-function buildKnownHostsUpsert(existing, hostname, hostKeysRaw, ip = null) {
-  const names = [hostname, ip];
-  const keep = (existing || '')
-    .split('\n')
-    .filter((line) => line.trim() && !knownHostsLineNamesAny(line, names));
-  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 on-box re-scope STEP (BV1.R101 / goal 1000051) — no `cd`, the caller
-// positions cwd. Re-runs the box source-fetch so /workspace holds exactly the
-// builder's ACTIVE-claim scope: "claim → open → the scoped folder." box-sync.js
-// re-runs infra/box-source-fetch.sh, which calls GET /box/source-access —
-// claim-driven since R94 — so a fresh claim (or a switch) re-scopes the ONE
-// working folder in place (the owner's one-folder decision). Best-effort (`|| true`):
-// a sync hiccup must never block the connection.
-const RESYNC_STEP = `echo '↪ Syncing your box to your active claim…'; node scripts/gds/box-sync.js || true`;
-
-// The remote command `ssh -t root@host …` runs. Lands the builder in /workspace;
-// with `sync` (BV1.R101) it re-scopes that folder to the active claim first, so a
-// builder who just claimed/switched arrives in a folder holding exactly that task's
-// code. On the first connection to this box it then runs an interactive `claude` 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, sync = false, workdir = WORKSPACE } = {}) {
-  const cd = `cd ${workdir} 2>/dev/null || true`;
-  const resync = sync ? `${RESYNC_STEP}; ` : '';
-  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}; ${resync}${login}exec bash -l`;
-}
-
-// The full one-shot remote command for `bongos code` (VS Code Remote-SSH opens the
-// folder directly rather than running a login shell, so the re-scope rides a
-// separate one-shot ssh before the window opens): cd + the re-scope step, no shell.
-function buildRemoteResyncCommand({ workdir = WORKSPACE } = {}) {
-  return `cd ${workdir} 2>/dev/null || true; ${RESYNC_STEP}`;
-}
-
-// 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 };
-}
-
-// PURE (unit tested): should we POST this key? The old inline version FAILED OPEN —
-// when the fingerprint couldn't be computed (ssh-keygen missing from a leaner PATH)
-// or the key list couldn't be fetched, it decided "don't register" and connected
-// anyway, so a builder whose key was never on the server got a bare "Permission
-// denied" with nothing to act on. Uncertainty now means REGISTER.
-//
-// A redundant POST costs nothing: POST /box/ssh-key upserts by fingerprint
-// (modules/dev-box/routes/box.js — an existing fingerprint is explicitly exempt from
-// MAX_SSH_KEYS_PER_BUILDER), so re-registering can neither add a row nor trip the
-// cap. Do not "optimize" the skip back in.
-function decideKeyRegistration({ created, fingerprint, listedKeys, listFailed } = {}) {
-  if (created) return { register: true, why: 'created' };
-  if (listFailed || !Array.isArray(listedKeys)) return { register: true, why: 'list_unavailable' };
-  if (!fingerprint) return { register: true, why: 'fingerprint_unknown' };
-  if (listedKeys.some((k) => k && k.fingerprint === fingerprint)) return { register: false, why: 'already_registered' };
-  return { register: true, why: 'not_listed' };
-}
-
-// Register the public key with the GDS unless the server already demonstrably has
-// it. 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 listedKeys = null;
-  let listFailed = false;
-  if (!created) {
-    try {
-      const res = await api.box.getBoxSshKey();
-      if (res.ok && res.data && Array.isArray(res.data.keys)) listedKeys = res.data.keys;
-      else listFailed = true;
-    } catch (_) {
-      listFailed = true;
-    }
-  }
-  const { register } = decideKeyRegistration({
-    created,
-    fingerprint: created ? null : localKeyFingerprint(`${keyPath}.pub`),
-    listedKeys,
-    listFailed,
-  });
-  if (!register) 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 ${surfaceAction('box')}.`);
-  } catch (err) {
-    log(`  ! Could not register your key (${err.message}); if SSH is refused, add it via ${surfaceAction('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 } = {}) {
-  await assertDevBoxAvailable();
-  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, ip = null, 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 */
-  }
-  // DNS is repointed on every wake, so an old line keyed by the PREVIOUS box's IP
-  // is stale too — pass it so the upsert drops it instead of leaving it to match.
-  const next = buildKnownHostsUpsert(existing, hostname, hostKeys, ip);
-  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 } = {}) {
-  // Before touching keys: key registration hits the box API too, so without this the reader gets
-  // a puzzling "Could not register your key (not_found)" line before the real explanation.
-  await assertDevBoxAvailable();
-  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, ip: box.ip, log });
-  writeSshAlias({ hostname: box.hostname, keyPath, log });
-  return { box, keyPath };
-}
-
-// Re-scope /workspace to the builder's active claim over a one-shot ssh, BEFORE
-// `bongos code` opens the VS Code window (BV1.R101). Best-effort: a failure just
-// means the folder holds its last-synced scope — the builder can /builder-sync
-// inside the VS Code terminal — so it never blocks the open. Returns true on a
-// clean run. Mirrors shell.js's ssh args (explicit key + host-key policy).
-function resyncBoxOverSsh({ host, keyPath, log = console.log }) {
-  const args = [
-    '-i', keyPath, '-o', 'IdentitiesOnly=yes', '-o', 'StrictHostKeyChecking=accept-new',
-    `${BOX_USER}@${host}`, buildRemoteResyncCommand(),
-  ];
-  log(`  Scoping ${WORKSPACE} to your active claim…`);
-  const r = spawnSync('ssh', args, { stdio: 'inherit' });
-  return !!r && !r.error && (r.status === 0 || r.status == null);
-}
-
-// 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,
-  knownHostsLineNamesAny,
-  decideKeyRegistration,
-  buildRemoteShellCommand,
-  buildRemoteResyncCommand, // BV1.R101 — one-shot re-scope for `bongos code`
-  RESYNC_STEP,
-  remoteAuthority,
-  parseEnsure,
-  // toolchain / paths
-  sshKeyPath,
-  binPresent,
-  localKeyFingerprint,
-  // key + box
-  ensureSshKey,
-  ensureKeyRegistered,
-  ensureBoxActive,
-  fetchRank,
-  // local ssh wiring
-  writeSshAlias,
-  pinKnownHosts,
-  prepareConnection,
-  resyncBoxOverSsh, // BV1.R101 — re-scope /workspace before `bongos code` opens
-  // first-run login handoff
-  loginMarkerPath,
-  isFirstLogin,
-  markLoginDone,
-};