@bongos/core 1.18.0 → 1.18.18

package/modules/dev-box/app/test/unit.mjs

@@ -0,0 +1,526 @@
+// devbox-app/test/unit.mjs — hermetic unit tests for the app's pure logic
+// (no Electron, no network, no fs side effects beyond a temp dir).
+//
+// Run: npm test (inside devbox-app/), or node devbox-app/test/unit.mjs.
+// NOTE: lives under devbox-app/ (not the root tests/) on purpose — the root
+// run-unit-tests gate runs from the droplet-bound dependency set; this
+// subproject's tests ride its own CI job (.github/workflows/build-devbox-app.yml).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { deriveStatus, pollDelayMs, transitionNotification, terminalAuthUrl, TERMINAL_USER, shouldHeartbeat } = require('../src/box-controller.js');
+const { mergeKnownHosts, settingsUpToDate, scanComplete, hostKeyLinesFor, knownHostsHasKey, verifyKnownHosts } = require('../src/ssh-setup.js');
+const { createPairing } = require('../src/pairing.js');
+const { apiBase } = require('../src/config.js');
+const brand = require('../src/brand.js');
+const { compareVersions, isUpdateAvailable, resolveTarget, updateBannerText } = require('../src/updater.js');
+const { createClient: createGdsClient, GdsError } = require('../src/gds-client.js');
+const { shapeClaimableTasks, boxScopeMessage, claimErrorMessage } = require('../src/task-picker.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log('deriveStatus:');
+
+t('no box → none; active box → active', () => {
+  assert.equal(deriveStatus(null), 'none');
+  assert.equal(deriveStatus({ box: { state: 'none' }, open_intent: null }), 'none');
+  assert.equal(deriveStatus({ box: { state: 'active' }, open_intent: null }), 'active');
+});
+
+t('open intents win over raw state', () => {
+  assert.equal(deriveStatus({ box: { state: 'none' }, open_intent: { action: 'provision', state: 'pending' } }), 'provisioning');
+  assert.equal(deriveStatus({ box: { state: 'active' }, open_intent: { action: 'deprovision', state: 'pending' } }), 'closing');
+  assert.equal(deriveStatus({ box: { state: 'parked' }, open_intent: { action: 'wake', state: 'running' } }), 'provisioning');
+});
+
+t('parked reads as off (the switch wakes it); error surfaces', () => {
+  assert.equal(deriveStatus({ box: { state: 'parked' }, open_intent: null }), 'none');
+  assert.equal(deriveStatus({ box: { state: 'error' }, open_intent: null }), 'error');
+  assert.equal(deriveStatus({ box: { state: 'waking' }, open_intent: null }), 'provisioning');
+  assert.equal(deriveStatus({ box: { state: 'parking' }, open_intent: null }), 'closing');
+});
+
+console.log('pollDelayMs:');
+
+t('transitions poll fast, settled states slow', () => {
+  assert.ok(pollDelayMs('provisioning') <= 5000);
+  assert.ok(pollDelayMs('closing') <= 5000);
+  assert.ok(pollDelayMs('active') >= 30000);
+  assert.ok(pollDelayMs('none') >= 60000);
+});
+
+console.log('shouldHeartbeat (leg 3 — connect-window keep-alive):');
+
+t('only an ACTIVE box ever heartbeats', () => {
+  const now = 1_000_000;
+  for (const status of ['none', 'provisioning', 'closing', 'error', 'signed_out']) {
+    assert.equal(shouldHeartbeat({ status, panelVisible: true, lastConnectActionAt: now, now }), false, status);
+  }
+});
+
+t('active + panel visible → heartbeat (the mid-connect lockout window)', () => {
+  const now = 1_000_000;
+  assert.equal(shouldHeartbeat({ status: 'active', panelVisible: true, lastConnectActionAt: 0, now }), true);
+});
+
+t('active + panel hidden but within the connect window → heartbeat', () => {
+  const now = 1_000_000;
+  assert.equal(shouldHeartbeat({ status: 'active', panelVisible: false, lastConnectActionAt: now - 60_000, now }), true);
+});
+
+t('active + panel hidden + connect window expired → NO heartbeat (idle box still reaps)', () => {
+  const now = 1_000_000;
+  // 11 min > the 10-min window
+  assert.equal(shouldHeartbeat({ status: 'active', panelVisible: false, lastConnectActionAt: now - 11 * 60_000, now }), false);
+  // never connected, panel hidden → also no beat
+  assert.equal(shouldHeartbeat({ status: 'active', panelVisible: false, lastConnectActionAt: 0, now }), false);
+});
+
+console.log('terminalAuthUrl:');
+
+t('embeds otb:<credential> userinfo in the terminal URL', () => {
+  assert.equal(
+    terminalAuthUrl({ url: 'https://term-lars589.amazonprimea.com', credential: 'abc123' }),
+    `https://${TERMINAL_USER}:abc123@term-lars589.amazonprimea.com/`
+  );
+});
+
+t('no terminal / no url → null; no credential → bare url; bad url → bare url', () => {
+  assert.equal(terminalAuthUrl(null), null);
+  assert.equal(terminalAuthUrl({ credential: 'x' }), null);
+  assert.equal(terminalAuthUrl({ url: 'https://t.example.com' }), 'https://t.example.com');
+  assert.equal(terminalAuthUrl({ url: 'not a url', credential: 'x' }), 'not a url');
+});
+
+t('percent-encodes credentials that need it', () => {
+  const out = terminalAuthUrl({ url: 'https://t.example.com', credential: 'p@ss/wor:d' });
+  assert.ok(out.startsWith(`https://${TERMINAL_USER}:p%40ss%2Fwor%3Ad@t.example.com`));
+});
+
+console.log('transitionNotification:');
+
+t('ready / idle-close notify; no-change does not', () => {
+  assert.equal(transitionNotification('active', 'active'), null);
+  assert.ok(transitionNotification('provisioning', 'active', { envName: 'X' }).title.includes('ready'));
+  assert.ok(transitionNotification('active', 'none').title.includes('closed'));
+  assert.equal(transitionNotification('none', 'provisioning'), null);
+});
+
+t('ready notification names the Desktop environment when settings installed', () => {
+  const n = transitionNotification('provisioning', 'active', { envName: 'Env Name', settingsInstalled: true });
+  assert.ok(n.body.includes('Env Name'));
+});
+
+console.log('mergeKnownHosts:');
+
+t('replaces stale lines for the hostname, keeps everything else', () => {
+  const existing = [
+    'github.com ssh-ed25519 AAAA1',
+    'box-lars.dev.example.com ssh-ed25519 OLDKEY',
+    'box-lars.dev.example.com,1.2.3.4 ecdsa-sha2 OLDKEY2',
+    '# a comment',
+    'other.host ssh-rsa BBBB',
+  ].join('\n');
+  const out = mergeKnownHosts(existing, 'box-lars.dev.example.com', [
+    'box-lars.dev.example.com ssh-ed25519 NEWKEY',
+  ]);
+  assert.ok(!out.includes('OLDKEY'), 'old keys dropped');
+  assert.ok(out.includes('NEWKEY'), 'new key added');
+  assert.ok(out.includes('github.com ssh-ed25519 AAAA1'), 'unrelated host kept');
+  assert.ok(out.includes('# a comment'), 'comments kept');
+  assert.ok(out.endsWith('\n'), 'trailing newline');
+});
+
+t('works against an empty/missing known_hosts', () => {
+  const out = mergeKnownHosts('', 'h.example.com', ['h.example.com ssh-ed25519 K']);
+  assert.equal(out, 'h.example.com ssh-ed25519 K\n');
+});
+
+console.log('scanComplete:');
+
+t('a scan with an ed25519 line is complete', () => {
+  assert.equal(scanComplete([
+    'h.example.com ssh-rsa AAAA',
+    'h.example.com ssh-ed25519 BBBB',
+  ]), true);
+});
+
+t('an rsa-only scan is NOT complete (#925 — Desktop ssh2 negotiates ed25519)', () => {
+  assert.equal(scanComplete(['h.example.com ssh-rsa AAAA']), false);
+  assert.equal(scanComplete(['h.example.com ecdsa-sha2-nistp256 CCCC']), false);
+  assert.equal(scanComplete([]), false);
+});
+
+console.log('hostKeyLinesFor (task 1187 / idea 235 — authoritative host keys):');
+
+t('builds <host> <type> <base64> lines from the reported keys, ed25519 present', () => {
+  const r = hostKeyLinesFor('box-x.dev.amazonprimea.com', 'ssh-ed25519 AAAA\necdsa-sha2-nistp256 BBBB');
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.lines, [
+    'box-x.dev.amazonprimea.com ssh-ed25519 AAAA',
+    'box-x.dev.amazonprimea.com ecdsa-sha2-nistp256 BBBB',
+  ]);
+});
+
+t('these lines feed mergeKnownHosts as a clean replace-by-host', () => {
+  const r = hostKeyLinesFor('h.example.com', 'ssh-ed25519 NEW');
+  const merged = mergeKnownHosts('h.example.com ssh-ed25519 OLD\nother ssh-rsa K', 'h.example.com', r.lines);
+  assert.ok(merged.includes('other ssh-rsa K'), 'other host preserved');
+  assert.ok(merged.includes('h.example.com ssh-ed25519 NEW'), 'fresh key written');
+  assert.ok(!merged.includes('OLD'), 'stale key for our host removed');
+});
+
+t('an rsa-only report is rejected (no ed25519 — the #925 Desktop failure)', () => {
+  const r = hostKeyLinesFor('h', 'ssh-rsa AAAA');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_ed25519');
+});
+
+t('empty report / missing hostname are rejected', () => {
+  assert.equal(hostKeyLinesFor('h', '').ok, false);
+  assert.equal(hostKeyLinesFor('h', '   \n  ').reason, 'no_reported_keys');
+  assert.equal(hostKeyLinesFor('', 'ssh-ed25519 AAAA').reason, 'no_hostname');
+});
+
+console.log('knownHostsHasKey + verifyKnownHosts (idea 264 — self-verify the on-disk pin):');
+
+const HKEY = 'AAAAC3NzaC1lZDI1NTE5AAAAIBh0r5JKa722SY0UXjqHv2'; // sample ed25519 blob
+const EXPECTED = hostKeyLinesFor('box-x.dev.amazonprimea.com', `ssh-ed25519 ${HKEY}\necdsa-sha2-nistp256 BBBB`).lines;
+
+t('authoritative key present in file → true', () => {
+  const file = `box-x.dev.amazonprimea.com ssh-ed25519 ${HKEY}\nother.example.com ssh-rsa K`;
+  assert.equal(knownHostsHasKey(file, 'box-x.dev.amazonprimea.com', EXPECTED), true);
+});
+
+t('STALE ed25519 (rebuild minted a new key) → false, even though a host line exists', () => {
+  const file = 'box-x.dev.amazonprimea.com ssh-ed25519 OLDOLDOLD';
+  assert.equal(knownHostsHasKey(file, 'box-x.dev.amazonprimea.com', EXPECTED), false);
+});
+
+t('MISSING (ssh-keygen -R removed it / empty file) → false', () => {
+  assert.equal(knownHostsHasKey('unrelated.example.com ssh-ed25519 ZZZZ', 'box-x.dev.amazonprimea.com', EXPECTED), false);
+  assert.equal(knownHostsHasKey('', 'box-x.dev.amazonprimea.com', EXPECTED), false);
+});
+
+t('no authoritative key → any ed25519 line for the host counts (keyscan fallback)', () => {
+  assert.equal(knownHostsHasKey('box-x.dev.amazonprimea.com ssh-ed25519 WHATEVER', 'box-x.dev.amazonprimea.com', []), true);
+  // ...but an rsa-only pin (no ed25519, the algo Desktop verifies) is NOT enough.
+  assert.equal(knownHostsHasKey('box-x.dev.amazonprimea.com ssh-rsa RRRR', 'box-x.dev.amazonprimea.com', []), false);
+});
+
+t('host,ip combined first field + comments/blanks are handled', () => {
+  const file = `# a comment\n\nbox-x.dev.amazonprimea.com,1.2.3.4 ssh-ed25519 ${HKEY}`;
+  assert.equal(knownHostsHasKey(file, 'box-x.dev.amazonprimea.com', EXPECTED), true);
+});
+
+t('no hostname → false (fail-closed)', () => {
+  assert.equal(knownHostsHasKey(`box-x ssh-ed25519 ${HKEY}`, '', EXPECTED), false);
+});
+
+t('verifyKnownHosts: missing hostname is a clean not-ok with no file IO', () => {
+  const r = verifyKnownHosts('', 'ssh-ed25519 AAAA');
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'no_hostname');
+});
+
+console.log('settingsUpToDate:');
+
+t('content equality is structural, missing file is false', () => {
+  assert.equal(settingsUpToDate('/nonexistent/path.json', '{"a":1}'), false);
+});
+
+console.log('pairing:');
+
+await ta('pairing run: opens browser, polls to approval, returns the grant', async () => {
+  const calls = [];
+  let polls = 0;
+  const client = {
+    pairStart: async () => ({ pair_code: 'ABCD-EFGH', poll_token: 'pt', verify_url: 'https://x/pair?code=ABCD-EFGH', expires_in: 600, interval: 0.01 }),
+    pairPoll: async () => (++polls < 3 ? { status: 'pending' } : { status: 'approved', token: 'tok', builder: { github_login: 'l' }, expires_at: 'soon' }),
+  };
+  const pairing = createPairing({ client, openExternal: async (u) => calls.push(u), sleep: () => Promise.resolve() });
+  const updates = [];
+  const grant = await pairing.run((u) => updates.push(u));
+  assert.deepEqual(calls, ['https://x/pair?code=ABCD-EFGH']);
+  assert.equal(updates[0].phase, 'waiting');
+  assert.equal(grant.token, 'tok');
+});
+
+await ta('pairing run: expired poll throws', async () => {
+  const client = {
+    pairStart: async () => ({ pair_code: 'A', poll_token: 'pt', verify_url: 'https://x', expires_in: 600, interval: 0.01 }),
+    pairPoll: async () => ({ status: 'expired' }),
+  };
+  const pairing = createPairing({ client, openExternal: async () => {}, sleep: () => Promise.resolve() });
+  await assert.rejects(() => pairing.run(), /expired/);
+});
+
+await ta('pairing run: cancel stops the loop', async () => {
+  const client = {
+    pairStart: async () => ({ pair_code: 'A', poll_token: 'pt', verify_url: 'https://x', expires_in: 600, interval: 0.01 }),
+    pairPoll: async () => ({ status: 'pending' }),
+  };
+  const pairing = createPairing({ client, openExternal: async () => {}, sleep: () => Promise.resolve() });
+  const p = pairing.run();
+  pairing.cancel();
+  await assert.rejects(() => p, /cancelled/);
+});
+
+console.log('mergeUserSshConfigs (#910 — the picker reads ~/.claude/settings.json):');
+
+t('merges our entry into empty/missing settings', () => {
+  const { mergeUserSshConfigs } = require('../src/ssh-setup.js');
+  const out = mergeUserSshConfigs('', [{ id: 'otb-x', name: 'Box', sshHost: 'root@h' }]);
+  assert.deepEqual(out.sshConfigs, [{ id: 'otb-x', name: 'Box', sshHost: 'root@h' }]);
+});
+
+t('replaces our id, preserves other entries and unrelated settings', () => {
+  const { mergeUserSshConfigs } = require('../src/ssh-setup.js');
+  const existing = JSON.stringify({
+    theme: 'dark',
+    sshConfigs: [
+      { id: 'personal', name: 'My server', sshHost: 'me@mine' },
+      { id: 'otb-x', name: 'Old Box', sshHost: 'root@old' },
+    ],
+  });
+  const out = mergeUserSshConfigs(existing, [{ id: 'otb-x', name: 'New Box', sshHost: 'root@new' }]);
+  assert.equal(out.theme, 'dark', 'unrelated settings preserved');
+  assert.deepEqual(out.sshConfigs.map((c) => c.id), ['personal', 'otb-x']);
+  assert.equal(out.sshConfigs[1].sshHost, 'root@new');
+});
+
+t('corrupt settings file never throws — starts clean', () => {
+  const { mergeUserSshConfigs } = require('../src/ssh-setup.js');
+  const out = mergeUserSshConfigs('{not json', [{ id: 'a', name: 'A', sshHost: 'h' }]);
+  assert.equal(out.sshConfigs.length, 1);
+});
+
+console.log('resolveSshTool (#909):');
+
+t('returns the bare name on POSIX (PATH resolution)', () => {
+  const { resolveSshTool } = require('../src/ssh-setup.js');
+  if (process.platform !== 'win32') {
+    assert.equal(resolveSshTool('ssh-keyscan'), 'ssh-keyscan');
+  } else {
+    // On Windows it must come back absolute (or fall through to PATH).
+    const out = resolveSshTool('ssh-keyscan');
+    assert.ok(out === 'ssh-keyscan' || out.endsWith('ssh-keyscan.exe'));
+  }
+});
+
+console.log('hostKeys snapshot wiring (#909):');
+
+t('setHostKeys lands in the snapshot and clears when the box leaves active', async () => {
+  const { createBoxController } = require('../src/box-controller.js');
+  let payload = { box: { state: 'active', hostname: 'h' }, open_intent: null };
+  const client = {
+    boxMe: async () => payload,
+    boxTerminal: async () => ({ url: null }),
+  };
+  const c = createBoxController({ client, signedIn: () => true, onChange: () => {}, onNotify: () => {}, envName: 'E' });
+  await c.refresh();
+  c.setHostKeys({ ok: false, reason: 'no_keys', attempt: 2 });
+  assert.deepEqual(c.snapshot().hostKeys, { ok: false, reason: 'no_keys', attempt: 2 });
+  payload = { box: { state: 'none' }, open_intent: null };
+  await c.refresh();
+  assert.equal(c.snapshot().hostKeys, null, 'cleared when not active');
+  c.stop(); // halt the (unref'd) poll timer
+});
+
+console.log('keyRegistered snapshot wiring (task 1002509):');
+
+await ta('setKeyRegistered surfaces registration state and SURVIVES the box going away', async () => {
+  const { createBoxController } = require('../src/box-controller.js');
+  let payload = {
+    box: {
+      state: 'active', hostname: 'h',
+      host_keys: 'ssh-ed25519 K', host_keys_at: '2026-07-01T10:00:00Z', active_since: '2026-07-01T09:00:00Z',
+    },
+    open_intent: null,
+  };
+  const client = { boxMe: async () => payload, boxTerminal: async () => ({ url: null }) };
+  const c = createBoxController({ client, signedIn: () => true, onChange: () => {}, onNotify: () => {}, envName: 'E' });
+  await c.refresh();
+  assert.equal(c.snapshot().keyRegistered, null, 'nothing reported yet');
+  assert.equal(c.snapshot().box.hostKeysAt, '2026-07-01T10:00:00Z');
+  assert.equal(c.snapshot().box.activeSince, '2026-07-01T09:00:00Z');
+  c.setKeyRegistered({ ok: false, reason: 'verify_failed', fingerprint: 'SHA256:x', attempts: 3 });
+  assert.deepEqual(c.snapshot().keyRegistered, { ok: false, reason: 'verify_failed', fingerprint: 'SHA256:x', attempts: 3 });
+  payload = { box: { state: 'none' }, open_intent: null };
+  await c.refresh();
+  assert.deepEqual(
+    c.snapshot().keyRegistered,
+    { ok: false, reason: 'verify_failed', fingerprint: 'SHA256:x', attempts: 3 },
+    'the key lives on the ACCOUNT, not the box — a failure must stay visible after the box closes'
+  );
+  c.stop();
+});
+
+t('ready notification tells the user to RESTART Claude Desktop (#909 picker finding)', () => {
+  const n = transitionNotification('provisioning', 'active', { envName: 'X', settingsInstalled: true });
+  assert.ok(/restart claude desktop/i.test(n.body), n.body);
+});
+
+console.log('config:');
+
+t('apiBase: env override > session base > production default; slashes stripped', () => {
+  delete process.env.OTB_DEVBOX_API_BASE;
+  assert.equal(apiBase(null), brand.PUBLIC_ORIGIN);
+  assert.equal(apiBase('https://staging.example.com/'), 'https://staging.example.com');
+  process.env.OTB_DEVBOX_API_BASE = 'http://127.0.0.1:3000/';
+  assert.equal(apiBase('https://staging.example.com'), 'http://127.0.0.1:3000');
+  delete process.env.OTB_DEVBOX_API_BASE;
+});
+
+console.log('updater (#924 — in-app update check):');
+
+t('compareVersions orders X.Y.Z numerically (not lexically)', () => {
+  assert.equal(compareVersions('1.0.5', '1.0.6'), -1);
+  assert.equal(compareVersions('1.0.6', '1.0.5'), 1);
+  assert.equal(compareVersions('1.0.10', '1.0.9'), 1, '10 > 9 numerically, not "10" < "9" lexically');
+  assert.equal(compareVersions('1.2.0', '1.10.0'), -1);
+  assert.equal(compareVersions('2.0.0', '1.9.9'), 1);
+  assert.equal(compareVersions('1.0.0', '1.0.0'), 0);
+});
+
+t('isUpdateAvailable is true ONLY for a strictly-newer published release', () => {
+  assert.equal(isUpdateAvailable('1.0.5', '1.0.6'), true);
+  // The live-state bug this fixes: app AHEAD of the published config is NOT an update.
+  assert.equal(isUpdateAvailable('1.0.6', '1.0.5'), false);
+  assert.equal(isUpdateAvailable('1.0.6', '1.0.6'), false);
+});
+
+t('isUpdateAvailable never false-positives on a malformed version', () => {
+  assert.equal(isUpdateAvailable('1.0.6', ''), false);
+  assert.equal(isUpdateAvailable('1.0.6', null), false);
+  assert.equal(isUpdateAvailable('1.0.6', 'v1.0.7'), false);
+  assert.equal(isUpdateAvailable('1.0.6', 'latest'), false);
+  assert.equal(isUpdateAvailable('garbage', '1.0.7'), false);
+});
+
+t('resolveTarget maps platform/arch to a config asset key (matching devbox-app.json)', () => {
+  assert.equal(resolveTarget('darwin', 'arm64'), 'mac-arm64');
+  assert.equal(resolveTarget('darwin', 'x64'), 'mac-x64');
+  assert.equal(resolveTarget('win32', 'arm64'), 'win-arm64');
+  assert.equal(resolveTarget('win32', 'x64'), 'win-x64');
+  assert.equal(resolveTarget('linux', 'x64'), null, 'no installer target → no in-app offer');
+});
+
+t('updateBannerText is the exact copy the task specifies', () => {
+  assert.equal(updateBannerText('1.0.6'), 'Update available — v1.0.6');
+});
+
+console.log('\ngds-client (backed by the vendored generated client, task 1996 / R09):');
+
+// A fake fetch that records the last request and returns a fixed response, so we
+// assert the generated named methods produce the exact GDS endpoints/verbs/bodies
+// the app has always used — and that the GdsError contract (status + raw body) holds.
+function recordingClient(response = { ok: true, status: 200, text: async () => '{"ok":true}' }) {
+  const rec = {};
+  const fetchImpl = async (url, init) => { rec.url = url; rec.init = init; return response; };
+  const client = createGdsClient({ getToken: () => 'tok', getApiBase: () => 'https://x.test', fetchImpl });
+  return { client, rec };
+}
+
+const ENDPOINTS = [
+  ['logout', [], 'POST', '/api/gds/auth/logout', undefined],
+  ['pairStart', ['Lars-Mac', 'darwin'], 'POST', '/api/gds/auth/app-pair/start', { device_name: 'Lars-Mac', platform: 'darwin' }],
+  ['pairPoll', ['pt'], 'POST', '/api/gds/auth/app-pair/poll', { poll_token: 'pt' }],
+  ['boxMe', [], 'GET', '/api/gds/box/me', undefined],
+  ['boxEnsure', [], 'POST', '/api/gds/box/ensure', undefined],
+  ['boxClose', [], 'POST', '/api/gds/box/close', undefined],
+  ['boxHeartbeat', [], 'POST', '/api/gds/box/heartbeat', undefined],
+  ['boxTerminal', [], 'GET', '/api/gds/box/terminal', undefined],
+  ['registerSshKey', ['ssh-ed25519 AAA', 'lars'], 'POST', '/api/gds/box/ssh-key', { public_key: 'ssh-ed25519 AAA', label: 'lars' }],
+  ['managedSettings', [], 'GET', '/api/gds/box/managed-settings', undefined],
+  ['claimableTasks', [], 'GET', '/api/gds/tasks/claimable', undefined],
+  ['claimTask', ['1002388'], 'POST', '/api/gds/claims', { task_id: '1002388' }],
+  ['boxScope', [], 'GET', '/api/gds/box/scope', undefined],
+  ['latestRelease', [], 'GET', '/downloads/devbox/latest.json', undefined],
+];
+
+for (const [name, args, method, urlPath, body] of ENDPOINTS) {
+  await ta(`${name} → ${method} ${urlPath} (Bearer + exact body)`, async () => {
+    const { client, rec } = recordingClient();
+    await client[name](...args);
+    assert.equal(rec.init.method, method);
+    assert.equal(rec.url, `https://x.test${urlPath}`);
+    assert.equal(rec.init.headers.Authorization, 'Bearer tok');
+    const sentBody = rec.init.body === undefined ? undefined : JSON.parse(rec.init.body);
+    assert.deepEqual(sentBody, body);
+  });
+}
+
+await ta('a non-2xx rejects with GdsError carrying status + the raw (flat) body', async () => {
+  const { client } = recordingClient({ ok: false, status: 403, text: async () => '{"error":"BOX_PROVISION_DENIED","reason":"quota"}' });
+  await assert.rejects(client.boxEnsure(), (e) => {
+    assert.ok(e instanceof GdsError);
+    assert.equal(e.status, 403);
+    assert.equal(e.body.error, 'BOX_PROVISION_DENIED');
+    assert.equal(e.body.reason, 'quota');
+    return true;
+  });
+});
+
+console.log('\ntask-picker (BV1.R100 — "What are you working on?" pick + confirm):');
+
+t('shapeClaimableTasks normalizes rows, caps to the limit, tolerates junk', () => {
+  const payload = { claimable: [
+    { id: 1002388, title: 'R100', kind: 'feature', est_minutes: 45 },
+    { id: 7, kind: 'bug' },
+    ...Array.from({ length: 10 }, (_v, i) => ({ id: 100 + i, title: `t${i}` })),
+  ] };
+  const rows = shapeClaimableTasks(payload, { limit: 6 });
+  assert.equal(rows.length, 6, 'capped to limit');
+  assert.deepEqual(rows[0], { id: '1002388', title: 'R100', kind: 'feature', estMinutes: 45 });
+  assert.equal(rows[1].title, 'Task 7', 'missing title → fallback');
+  assert.equal(rows[1].kind, 'bug');
+  assert.equal(rows[1].estMinutes, null, 'missing est_minutes → null');
+  assert.deepEqual(shapeClaimableTasks(null), [], 'no payload → empty');
+  assert.deepEqual(shapeClaimableTasks({}), [], 'no claimable key → empty');
+});
+
+t('boxScopeMessage names EXACTLY the modules the box will hold (task scope) + directs to /builder-sync', () => {
+  const m = boxScopeMessage({ task: { id: '1002388' }, scope: { scope: 'task', modules: ['dev-box', 'onboarding'], task_scope: true } });
+  assert.ok(m.includes('task 1002388'), m);
+  assert.ok(m.includes('dev-box, onboarding'), m);
+  assert.ok(m.includes('nothing else'), 'the minimality is the point');
+  assert.ok(/builder-sync/.test(m), 'directs to /builder-sync (R96)');
+});
+
+t('boxScopeMessage: base-only (empty modules) → nothing extra to pull', () => {
+  const m = boxScopeMessage({ task: { id: '5' }, scope: { scope: 'base', modules: [], task_scope: true } });
+  assert.ok(/base instance/.test(m) && /nothing extra to pull/.test(m), m);
+});
+
+t('boxScopeMessage: rank fallback (modules null) → generic scope + sync hint', () => {
+  const m = boxScopeMessage({ task: { id: '9' }, scope: { scope: 'full', modules: null, task_scope: false } });
+  assert.ok(/full scope/.test(m) && /builder-sync/.test(m), m);
+});
+
+t('boxScopeMessage: scope read failed (null) → claim still confirmed, still sync', () => {
+  const m = boxScopeMessage({ task: { id: '9' }, scope: null });
+  assert.ok(/Claimed task 9/.test(m) && /builder-sync/.test(m), m);
+});
+
+t('claimErrorMessage maps known refusals; falls back to server text/code', () => {
+  assert.ok(/waiting on other work/.test(claimErrorMessage({ body: { error: 'DEPS_NOT_SHIPPED' } })));
+  assert.ok(/in flight/.test(claimErrorMessage({ body: { error: 'session_already_has_active_claim' } })));
+  assert.ok(/same files/.test(claimErrorMessage({ body: { error: 'touches_conflict' } })));
+  assert.equal(claimErrorMessage({ body: { message: 'boom' } }), 'boom', 'server message wins the fallback');
+  assert.ok(/mystery/.test(claimErrorMessage({ body: { error: 'mystery' } })), 'unknown code surfaces');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);