@bongos/core 1.18.0 → 1.18.18

package/scripts/gds/abandon.js

@@ -10,10 +10,12 @@
 // work another session already shipped — instead of leaving it in 'ready' as
 // claimable noise.
 //
-// Archon-only (the route is requireRank('archon')). Refuses on a shipped task
-// (immutable history) and on a task with an active claim (release it first);
-// idempotent on an already-abandoned task. The abandon + reason are recorded in
-// audit_log by the server's writing middleware, so the ledger stays complete.
+// Metic+ (the route is requireRank('metic', 'archon') as of ADR 0152; Archon-only
+// before that). Refuses on a shipped task (immutable history) and on a task with an
+// active claim (release it first); idempotent on an already-abandoned task. The
+// abandon + reason are recorded in audit_log by the server's writing middleware, so
+// the ledger stays complete. Retired the wrong task? POST /tasks/<id>/promote
+// restores it to backlog at the same rank (db.restoreTask) — no Archon SQL needed.
 
 const { cliClient, requireSession, arg } = require('./cli-lib');
 

package/scripts/gds/api.js

@@ -18,17 +18,21 @@
 // on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
 
 const fs = require('node:fs');
-const { cliClient, arg, isBoxScope, printBoxScopeGuidanceAndExit } = require('./cli-lib');
+const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit } = require('./cli-lib');
 
 
 (async () => {
   const method = (process.argv[2] || '').toUpperCase();
   const urlPath = process.argv[3];
   if (!method || !urlPath || !urlPath.startsWith('/')) {
-    console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->]");
+    console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->] [--quiet]");
     process.exit(2);
   }
 
+  // --quiet / GDS_QUIET: suppress the stderr status banner below. Default OFF —
+  // existing pipelines that scrape stderr for the status line are unaffected.
+  const quiet = resolveQuiet();
+
   // Resolve an optional JSON request body. `--body-file -` reads stdin (the
   // robust way to pass a body with awkward characters without shell quoting).
   let body = null;
@@ -36,8 +40,9 @@ const { cliClient, arg, isBoxScope, printBoxScopeGuidanceAndExit } = require('./
   const bodyInline = arg('--body');
   try {
     let raw = null;
-    if (bodyFile != null) raw = bodyFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(bodyFile, 'utf8');
-    else if (bodyInline != null) raw = bodyInline;
+    if (bodyFile != null) {
+      raw = stripBom(bodyFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(bodyFile, 'utf8'));
+    } else if (bodyInline != null) raw = bodyInline;
     if (raw != null && raw.trim()) body = JSON.parse(raw);
   } catch (e) {
     console.error(`api: could not read/parse JSON body: ${e.message}`);
@@ -59,7 +64,7 @@ const { cliClient, arg, isBoxScope, printBoxScopeGuidanceAndExit } = require('./
     console.error(`api: request failed: ${e.message}`);
     process.exit(1);
   }
-  console.error(`${method} ${urlPath} → ${res.status}`);
+  if (!quiet) console.error(`${method} ${urlPath} → ${res.status}`);
   // task 1501: on a dev box the baked session is box-scoped (ADR 0053) and every
   // non-bootstrap call (e.g. /me, /inbox) returns 403 box_scope. We pass
   // allowUnauthenticated above (so a 401 stays a plain error, not the setup

package/scripts/gds/api.ps1

@@ -0,0 +1,26 @@
+# scripts/gds/api.ps1 — PowerShell 5.1-safe wrapper around api.js.
+#
+# PS 5.1 wraps a native command's stderr into NativeCommandError records and sets
+# $? false even on a clean exit (api.js always prints its status banner to
+# stderr), so a plain `node scripts/gds/api.js ... 2>&1` looks like a failure when
+# it isn't. This wrapper discards stderr, strips a leading UTF-8 BOM, and writes
+# only the raw JSON to stdout so callers can `| ConvertFrom-Json` it directly.
+#
+# Usage: scripts/gds/api.ps1 <METHOD> <path> [--body '<json>' | --body-file <file>]
+
+$apiJs = Join-Path $PSScriptRoot 'api.js'
+$out = & node $apiJs @args 2>$null
+$exitCode = $LASTEXITCODE
+
+$text = $out -join "`n"
+if ($text.Length -gt 0 -and $text[0] -eq [char]0xFEFF) {
+    $text = $text.Substring(1)
+}
+
+if ($exitCode -ne 0) {
+    Write-Output "GDS-ERROR: scripts/gds/api.ps1 exited $exitCode"
+    exit $exitCode
+}
+
+Write-Output $text
+exit $exitCode

package/scripts/gds/api.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# scripts/gds/api.sh — Git Bash/Linux passthrough wrapper around api.js.
+# MSYS_NO_PATHCONV avoids Git Bash mangling API paths (e.g. /api/gds/inbox) into
+# Windows paths before node ever sees them.
+export MSYS_NO_PATHCONV=1
+exec node "$(dirname "$0")/api.js" "$@"

package/scripts/gds/audit-ships.js

@@ -102,8 +102,14 @@ function downstreamImpact(sha, files) {
 }
 
 async function fetchShipped(days) {
+  // Derive the public read host from branding (statusOrigin → publicOrigin), never a
+  // hardcoded founder host (was https://status.amazonprimea.com — task 1002234). The
+  // recent-shipped feed is a public endpoint served on the status dashboard host.
+  const b = (() => { try { return require('../../src/branding').branding(); } catch (_) { return {}; } })();
+  const d = b.domains || {};
+  const statusBase = String(d.statusOrigin || d.publicOrigin || '').replace(/\/+$/, '');
   const r = await fetch(
-    `https://status.amazonprimea.com/api/gds/public/recent-shipped?days=${days}&limit=500`
+    `${statusBase}/api/gds/public/recent-shipped?days=${days}&limit=500`
   );
   const data = await r.json();
   return data.tasks || [];

package/scripts/gds/backfill-sessions.js

@@ -44,7 +44,8 @@ const path = require('path');
 const os = require('os');
 
 const { cliClient, loadSession } = require('./cli-lib');
-const { buildSessionDigest } = require('./ship');
+const { buildSessionDigest, encodeProjectPath } = require('./ship');
+const { looksLikeGraderTranscript } = require('./session-cost');
 
 // ---- args ----------------------------------------------------------------
 const ARGV = process.argv.slice(2);
@@ -68,7 +69,17 @@ const PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 // Project-path families this project has lived under (the cwd is encoded into
 // the dir name by Claude Code; the project was renamed over its life). A dir is
 // in-scope if its name contains any of these tokens.
+//
+// The first token is DERIVED from this checkout, not hardcoded: the legacy names
+// below are the owner's old machine, so on every other clone inScope() matched
+// nothing and the script reported "0 transcripts" while exiting 0 — the failure
+// looked like success. encodeProjectPath is the same encoder Claude Code (and
+// resolveTranscriptPath) uses, so the derived token IS the real dir name, and a
+// per-task worktree dir (<encoded-root>--claude-worktrees-task-N) still matches
+// on the prefix. The legacy tokens stay so the owner's older corpus keeps working.
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const PROJECT_TOKENS = [
+  encodeProjectPath(REPO_ROOT),
   'Offtheboats',
   'Claude-OTB',
   'LarsCode-Amazonprimea',
@@ -80,11 +91,13 @@ const PROJECT_TOKENS = [
 // invocation, a claim/release slash command, or the builder-claim skill's
 // "Claimed #N" confirmation. NOT markdown "#N" links, NOT API list responses
 // (those carry many incidental task_id fields), NOT "/tasks/N/..." paths.
+// Ids are 7 digits on a live instance (1002471); the original {1,4} matched none
+// of them, so every modern session extracted zero task_ids and could never pay.
 const TASK_MARKERS = [
-  /\bship\.js\s+(\d{1,4})\b/g, // node scripts/gds/ship.js 681 [--flags]
-  /\bbuilder-claim\s+(\d{1,4})\b/g, // /builder-claim 681
-  /\bbuilder-release\s+(\d{1,4})\b/g, // /builder-release 681
-  /\bClaimed\s+(?:task\s+)?#(\d{1,4})\b/g, // "Claimed #681" / "Claimed task #681"
+  /\bship\.js\s+(\d{1,7})\b/g, // node scripts/gds/ship.js 1002471 [--flags]
+  /\bbuilder-claim\s+(\d{1,7})\b/g, // /builder-claim 1002471
+  /\bbuilder-release\s+(\d{1,7})\b/g, // /builder-release 1002471
+  /\bClaimed\s+(?:task\s+)?#(\d{1,7})\b/g, // "Claimed #1002471" / "Claimed task #1002471"
 ];
 
 // Decode the human-and-tool text of one transcript entry: assistant text +
@@ -119,13 +132,53 @@ function extractTaskIds(entries) {
       let m;
       while ((m = re.exec(t)) !== null) {
         const n = parseInt(m[1], 10);
-        if (n > 0 && n < 10000) found.add(n);
+        // No upper clamp: the old `n < 10000` dropped every 7-digit id a SECOND
+        // time, so widening TASK_MARKERS alone would still have extracted nothing.
+        //
+        // Over-capture cannot pay for work you did not do. The id set here is a
+        // REQUEST; the server intersects it with the caller's own claims before
+        // storing — modules/sessions/routes/sessions.js calls
+        // db.filterTaskIdsClaimedBy(req.builder.id, requestedTaskIds), which is
+        // `SELECT DISTINCT task_id FROM claims WHERE builder_id = $1 AND task_id =
+        // ANY($2)` (modules/sessions/db.js). builder_id comes from the authenticated
+        // caller, never the body, so a forged transcript naming an unclaimed task
+        // yields an EMPTY task_ids — and the cost-plus reward is gated on a stored
+        // id reaching status='shipped' (ADR 0120), so it can never book.
+        // Confirmed empirically on the 2026-07-28 recovery: ids 2, 5, 600, 2615 and
+        // 999999 were extracted from quoted docs and every one was dropped server-side.
+        if (n > 0) found.add(n);
       }
     }
   }
   return [...found].sort((a, b) => a - b);
 }
 
+// buildUploadPayload — the POST /sessions body for one planned session. Pure +
+// exported so the field set is unit-tested; the money rides on `model_usage`.
+//
+// model_usage MUST be top-level. The route promotes it to its own column and
+// deletes it from the metrics jsonb (modules/sessions/routes/sessions.js), so it
+// reads body.model_usage and never looks inside metrics. Omitting it left every
+// backfilled reward on the task-1676 fallback, which prices the whole token total
+// at the opus cache_read rate — deliberately conservative, i.e. an under-payment.
+// Sent exactly as ship.js sends it so a backfilled row prices identically to one
+// written at ship time.
+function buildUploadPayload(p) {
+  const digest = (p && p.digest) || {};
+  const metrics = digest.metrics || {};
+  return {
+    session_id: p.sessionId,
+    task_ids: p.taskIds,
+    total_tokens: digest.totalTokens,
+    duration_seconds: digest.durationSeconds,
+    started_at: digest.startedAt,
+    ended_at: digest.endedAt,
+    detail: digest.detail,
+    metrics,
+    model_usage: metrics.model_usage || {},
+  };
+}
+
 // ---- transcript discovery + parse ----------------------------------------
 function inScope(dirName) {
   return PROJECT_TOKENS.some((tok) => dirName.includes(tok));
@@ -218,6 +271,7 @@ async function main() {
   let skippedPresent = 0;
   let skippedEmpty = 0;
   let skippedActive = 0;
+  let skippedGrader = 0;
   for (const file of files) {
     const sessionId = path.basename(file, '.jsonl');
     if (!/^[A-Za-z0-9_-]+$/.test(sessionId)) continue; // server format guard
@@ -229,6 +283,18 @@ async function main() {
       skippedPresent++;
       continue;
     }
+    // The ship-time subagent grader panel persists each worker as its OWN
+    // top-level transcript in this same project dir (they are the MAJORITY of
+    // files here — 36 of 52 in one real main dir, 146 of 151 across worktrees).
+    // A worker reads the diff, so it quotes the very ship markers above and would
+    // be uploaded as a session that shipped a real task — earning a cost-plus
+    // reward the live ship path never pays, for spend already captured by the
+    // worker cost envelope. Same exclusion, same reason as session-cost.js's
+    // ADR 0028 non-double-count invariant; reuse its detector.
+    if (looksLikeGraderTranscript(file)) {
+      skippedGrader++;
+      continue;
+    }
     const entries = parseEntries(file);
     const digest = buildSessionDigest(entries, { extraSecrets });
     // Skip sessions with no real LLM work. A 0-token digest is either an aborted
@@ -252,7 +318,8 @@ async function main() {
   const totalTasks = plan.reduce((n, p) => n + p.taskIds.length, 0);
   console.log(
     `\nPlan: ${plan.length} new sessions to upload ` +
-      `(${skippedPresent} already present, ${skippedEmpty} empty/no-turns skipped` +
+      `(${skippedPresent} already present, ${skippedEmpty} empty/no-turns skipped, ` +
+      `${skippedGrader} grader-worker transcripts skipped` +
       `${skippedActive ? `, ${skippedActive} current-session skipped` : ''}).`
   );
   console.log(`Task-id associations extracted: ${totalTasks} across ${plan.filter((p) => p.taskIds.length).length} sessions.\n`);
@@ -283,16 +350,7 @@ async function main() {
   const api = await cliClient();
   for (let i = 0; i < capped; i++) {
     const p = plan[i];
-    const payload = {
-      session_id: p.sessionId,
-      task_ids: p.taskIds,
-      total_tokens: p.digest.totalTokens,
-      duration_seconds: p.digest.durationSeconds,
-      started_at: p.digest.startedAt,
-      ended_at: p.digest.endedAt,
-      detail: p.digest.detail,
-      metrics: p.digest.metrics,
-    };
+    const payload = buildUploadPayload(p);
     let attempts = 0;
     for (;;) {
       attempts++;
@@ -341,7 +399,9 @@ function finish(ok, failed, failures) {
 
 // Pure helpers are exported for unit testing (matches the ship.js / session-eval
 // convention). The script only executes when run directly, not when required.
-module.exports = { entryText, extractTaskIds, inScope, TASK_MARKERS, PROJECT_TOKENS };
+module.exports = {
+  entryText, extractTaskIds, inScope, buildUploadPayload, TASK_MARKERS, PROJECT_TOKENS,
+};
 
 if (require.main === module) {
   main().catch((e) => {

package/scripts/gds/backup.js

@@ -26,19 +26,41 @@ async function fetchStatus() {
   return r.data;
 }
 
+function fmtAge(hours) {
+  if (hours == null) return '(unknown age)';
+  if (hours < 48) return `${hours.toFixed(1)}h old`;
+  return `${Math.floor(hours / 24)} days old`;
+}
+
 function printStatus(data) {
   const d = data.latest_dump;
   if (!d) {
     console.log(`Backup dir: ${data.backup_dir}`);
     console.log('No dumps found yet.');
+    console.log('');
+    console.log('  ⚠️  NO BACKUP EXISTS. There is no restore point for this database.');
     return;
   }
   console.log(`Backup dir:  ${data.backup_dir}`);
   console.log(`Latest dump: ${d.filename}`);
-  console.log(`  Timestamp: ${d.timestamp}`);
+  console.log(`  Timestamp: ${d.timestamp}  (${fmtAge(d.age_hours)})`);
   console.log(`  Size:      ${fmtBytes(d.size_bytes)}`);
   console.log(`  Retained:  ${d.count} dump(s)`);
   if (data.trigger_running) console.log('  ⏳ A backup is currently running.');
+  // Loud on purpose. A stale backup previously showed as an ordinary timestamp
+  // the reader had to date themselves — which is how 13 days of failure went
+  // unnoticed on cloudbongos (task 1002479).
+  if (d.stale) {
+    console.log('');
+    console.log(`  ⚠️  STALE — the newest dump is ${fmtAge(d.age_hours)}, past the ${d.stale_after_hours}h threshold.`);
+    console.log('      The nightly backup is probably failing. Check the unit:');
+    console.log('        systemctl status gds-db-backup.service');
+    console.log('        journalctl -u gds-db-backup.service -n 50 --no-pager');
+    console.log('      A 203/EXEC there means the script lost its exec bit — the unit');
+    console.log('      should invoke it via `/usr/bin/env bash <script>`.');
+  } else {
+    console.log(`  ✅ Fresh (threshold ${d.stale_after_hours}h).`);
+  }
 }
 
 async function trigger() {

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

@@ -27,6 +27,7 @@
 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 } = require('./cli-lib');
@@ -90,13 +91,49 @@ function upsertSshConfigText(existing, { hostname, identityFile }) {
   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) {
+// 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,1.2.3.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() && line.split(/\s+/)[0] !== hostname);
+    .filter((line) => line.trim() && !knownHostsLineNamesAny(line, names));
   const added = (hostKeysRaw || '')
     .split('\n')
     .map((k) => k.trim())
@@ -106,16 +143,35 @@ function buildKnownHostsUpsert(existing, hostname, hostKeysRaw) {
   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;
-// 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
+// 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, workdir = WORKSPACE } = {}) {
+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}; ${login}exec bash -l`;
+  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
@@ -226,32 +282,47 @@ function ensureSshKey({ log = console.log } = {}) {
   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).
+// 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 needed = created;
-  if (!needed) {
-    const fp = localKeyFingerprint(`${keyPath}.pub`);
-    let listed = null;
+  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)) listed = res.data.keys;
+      if (res.ok && res.data && Array.isArray(res.data.keys)) listedKeys = res.data.keys;
+      else listFailed = true;
     } 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
+      listFailed = true;
     }
   }
-  if (!needed) return { registered: false };
+  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 } });
@@ -364,7 +435,7 @@ function writeSshAlias({ hostname, keyPath, log = console.log }) {
   }
 }
 
-function pinKnownHosts({ hostname, hostKeys, log = console.log }) {
+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 = '';
@@ -373,7 +444,9 @@ function pinKnownHosts({ hostname, hostKeys, log = console.log }) {
   } catch (_) {
     /* none yet */
   }
-  const next = buildKnownHostsUpsert(existing, hostname, hostKeys);
+  // 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 });
@@ -392,11 +465,26 @@ 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 });
+  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.
@@ -430,7 +518,11 @@ module.exports = {
   buildSshAliasBlock,
   upsertSshConfigText,
   buildKnownHostsUpsert,
+  knownHostsLineNamesAny,
+  decideKeyRegistration,
   buildRemoteShellCommand,
+  buildRemoteResyncCommand, // BV1.R101 — one-shot re-scope for `bongos code`
+  RESYNC_STEP,
   remoteAuthority,
   parseEnsure,
   // toolchain / paths
@@ -446,6 +538,7 @@ module.exports = {
   writeSshAlias,
   pinKnownHosts,
   prepareConnection,
+  resyncBoxOverSsh, // BV1.R101 — re-scope /workspace before `bongos code` opens
   // first-run login handoff
   loginMarkerPath,
   isFirstLogin,