@bongos/core 1.17.0

package/tests/bfg_write.mjs

@@ -0,0 +1,423 @@
+// tests/bfg_write.mjs
+//
+// Unit + in-process HTTP for the BFG cross-builder memory WRITE path
+// (6C.1 / ADR 0026 §6C) — the first cross-builder write capability and the
+// deliberate, bounded exception to the ADR 0016 trust boundary.
+//
+// The load-bearing invariants under test:
+//   1. IDENTITY GATE, NOT RANK: only the BFG service principal (system_role=
+//      'bfg') reaches the write endpoint. An Archon token — the highest human
+//      rank — is REJECTED (403). This is the exact test ADR 0026 §6C demands.
+//   2. KILL-SWITCH: with BFG_WRITE_ENABLED unset, the path is closed (503),
+//      even for the principal.
+//   3. NAMESPACED + ATTRIBUTED: writes land under bfg/ with mandatory
+//      author: BFG frontmatter (a BFG note can't masquerade as the builder's).
+//   4. RESERVED NAMESPACE: a builder cannot SYNC into bfg/ (no overwrite race).
+//   5. FAIL-CLOSED AUDIT: the write + its audit row share ONE transaction
+//      (asserted structurally — no DB in this test).
+//
+// Run:  node tests/bfg_write.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+
+const require = createRequire(import.meta.url);
+const auth = require('../src/module-api'); // doorway: memory-module routes capture api.requireBuilder, so the stub must patch the doorway (BV1.R72 / ADR 0091)
+const memory = require('../modules/memory/memory.js');
+const db = require('../src/bongos/db.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+// ===========================================================================
+// Layer 1 — pure helpers
+// ===========================================================================
+
+console.log('requireBfgPrincipal (the identity gate — NOT a rank gate):');
+
+function runGate(builder) {
+  const req = { builder };
+  let code = null;
+  let body = null;
+  let nexted = false;
+  const res = {
+    status(c) { code = c; return this; },
+    json(b) { body = b; return this; },
+  };
+  auth.requireBfgPrincipal(req, res, () => { nexted = true; });
+  return { nexted, code, body };
+}
+
+await t('the BFG principal (system_role="bfg") passes', () => {
+  const r = runGate({ id: 9, system_role: 'bfg', rank: 'xenos' });
+  assert.equal(r.nexted, true);
+  assert.equal(r.code, null);
+});
+
+await t('an ARCHON token is REJECTED (403 not_bfg_principal) — the ADR 0026 §6C requirement', () => {
+  const r = runGate({ id: 1, rank: 'archon', system_role: null });
+  assert.equal(r.nexted, false, 'an archon must NOT reach the write path');
+  assert.equal(r.code, 403);
+  assert.equal(r.body.error, 'not_bfg_principal');
+});
+
+await t('a metic and a xenos are both rejected', () => {
+  for (const rank of ['metic', 'xenos']) {
+    const r = runGate({ id: 2, rank, system_role: null });
+    assert.equal(r.nexted, false);
+    assert.equal(r.code, 403);
+  }
+});
+
+await t('a rank-escalated token (rank=archon but no system_role) is still rejected — the gate ignores rank', () => {
+  const r = runGate({ id: 3, rank: 'archon', system_role: undefined });
+  assert.equal(r.code, 403);
+});
+
+await t('no builder on the request → rejected (fail closed)', () => {
+  const r = runGate(undefined);
+  assert.equal(r.code, 403);
+});
+
+console.log('\nbuildBfgMemoryFile (attribution is structural, not optional):');
+
+await t('a valid dream → bfg/dream-<slug>.md with author:BFG + type:bfg-dream frontmatter', () => {
+  const { path: p, content } = memory.buildBfgMemoryFile({
+    kind: 'dream', slug: 'commit-before-ship', title: 'Commit before /builder-ship',
+    body_md: 'Commit your work first so the grader sees a real diff.',
+    rationale: 'Top performers always commit before shipping.',
+    sourceBuilder: 'bfg-system', targetBuilderId: 42, now: new Date('2026-06-03T00:00:00Z'),
+  });
+  assert.equal(p, 'bfg/dream-commit-before-ship.md');
+  assert.match(content, /^---\n/);
+  assert.match(content, /\nauthor: BFG\n/);
+  assert.match(content, /\ntype: bfg-dream\n/);
+  assert.match(content, /\ntarget_builder: 42\n/);
+  assert.match(content, /written by the BFG \(system\), not by you/);
+  assert.match(content, /Commit your work first/);
+});
+
+await t('a valid correction → bfg/correction-<slug>.md with type:bfg-correction', () => {
+  const { path: p, content } = memory.buildBfgMemoryFile({
+    kind: 'correction', slug: 'claim-before-edit',
+    body_md: 'You edited files without an active claim.', rationale: 'Methodology rule.',
+    targetBuilderId: 7,
+  });
+  assert.equal(p, 'bfg/correction-claim-before-edit.md');
+  assert.match(content, /\ntype: bfg-correction\n/);
+  assert.match(content, /BFG correction note/);
+});
+
+await t('a multi-line rationale is collapsed so the frontmatter stays valid', () => {
+  const { content } = memory.buildBfgMemoryFile({
+    kind: 'dream', slug: 'x', body_md: 'b', rationale: 'line one\nline two\n  line three', targetBuilderId: 1,
+  });
+  const fm = content.split('---')[1];
+  assert.ok(!/line one\nline two/.test(fm), 'rationale must be single-line in frontmatter');
+  assert.match(fm, /rationale: "line one line two line three"/);
+});
+
+await t('bad kind / slug / body / rationale each throw a specific code', () => {
+  const base = { kind: 'dream', slug: 'ok', body_md: 'b', rationale: 'r', targetBuilderId: 1 };
+  assert.throws(() => memory.buildBfgMemoryFile({ ...base, kind: 'nightmare' }), (e) => e.code === 'BAD_BFG_KIND');
+  assert.throws(() => memory.buildBfgMemoryFile({ ...base, slug: 'Bad Slug!' }), (e) => e.code === 'BAD_BFG_SLUG');
+  assert.throws(() => memory.buildBfgMemoryFile({ ...base, body_md: '   ' }), (e) => e.code === 'BAD_BFG_BODY');
+  assert.throws(() => memory.buildBfgMemoryFile({ ...base, rationale: '' }), (e) => e.code === 'BAD_BFG_RATIONALE');
+});
+
+console.log('\nnamespace guards:');
+
+await t('assertBfgPath accepts bfg/ paths and rejects others', () => {
+  memory.assertBfgPath('bfg/dream-x.md'); // no throw
+  assert.throws(() => memory.assertBfgPath('notes.md'), (e) => e.code === 'NOT_BFG_NAMESPACE');
+  assert.throws(() => memory.assertBfgPath('bfg/../escape.md'), (e) => e.code === 'BAD_PATH');
+});
+
+await t('isReservedNamespacePath flags exactly the bfg/ prefix', () => {
+  assert.equal(memory.isReservedNamespacePath('bfg/x.md'), true);
+  assert.equal(memory.isReservedNamespacePath('notes.md'), false);
+  assert.equal(memory.isReservedNamespacePath('mybfg/x'), false);
+});
+
+console.log('\nkill-switch (bfgWriteEnabled):');
+
+const buildMemoryRouter = require('../modules/memory/routes/memory.js');
+const { bfgWriteEnabled } = buildMemoryRouter._internals;
+
+await t('disabled by default; enabled only by the exact string "true"', () => {
+  const saved = process.env.BFG_WRITE_ENABLED;
+  delete process.env.BFG_WRITE_ENABLED;
+  assert.equal(bfgWriteEnabled(), false);
+  process.env.BFG_WRITE_ENABLED = '1';
+  assert.equal(bfgWriteEnabled(), false, 'only "true" enables it (fail-safe)');
+  process.env.BFG_WRITE_ENABLED = 'true';
+  assert.equal(bfgWriteEnabled(), true);
+  if (saved === undefined) delete process.env.BFG_WRITE_ENABLED; else process.env.BFG_WRITE_ENABLED = saved;
+});
+
+// ===========================================================================
+// Layer 1b — source-structural checks (the invariants are encoded, not promised)
+// ===========================================================================
+
+console.log('\nsource-structural checks:');
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const routeSrc = fs.readFileSync(path.join(here, '..', 'modules', 'memory', 'routes', 'memory.js'), 'utf8');
+const memSrc = fs.readFileSync(path.join(here, '..', 'modules', 'memory', 'memory.js'), 'utf8');
+
+await t('the bfg-write endpoint is gated by requireBfgPrincipal (identity), and the kill-switch is checked', () => {
+  const idx = routeSrc.indexOf("'/memory/builders/:builderId/bfg-write'");
+  assert.ok(idx >= 0, 'bfg-write route must be declared');
+  const window = routeSrc.slice(idx, idx + 700);
+  assert.ok(/requireBfgPrincipal/.test(window), 'must be gated by requireBfgPrincipal');
+  assert.ok(!/requireRank/.test(window), 'must NOT use a rank gate (identity, not rank)');
+  assert.ok(/bfgWriteEnabled\(\)/.test(window), 'must check the kill-switch');
+});
+
+await t('bfgWriteMemoryFile writes the file AND the audit row in ONE transaction (fail-closed)', () => {
+  const fn = memSrc.slice(memSrc.indexOf('async function bfgWriteMemoryFile'));
+  const body = fn.slice(0, fn.indexOf('\n}\n'));
+  assert.ok(/BEGIN/.test(body), 'opens a transaction');
+  assert.ok(/INSERT INTO builder_memory/.test(body), 'inserts the memory row');
+  assert.ok(/INSERT INTO audit_log/.test(body), 'inserts the audit row');
+  assert.ok(/COMMIT/.test(body) && /ROLLBACK/.test(body), 'commits both / rolls back on error');
+  // the audit INSERT must be BEFORE the single COMMIT (same tx as the write)
+  assert.ok(body.indexOf('INSERT INTO audit_log') < body.indexOf("COMMIT"), 'audit insert is inside the write transaction');
+});
+
+await t('production code names no grader system (project convention — mirrors memory_isolation Fix #3)', () => {
+  // Shipped code must not reference the grader/its workers (the same check the
+  // memory_isolation suite enforces); kept here so a future edit to THIS route
+  // file can't reintroduce a grader reference unnoticed.
+  assert.ok(!/grader/i.test(routeSrc), 'route source must not mention the grader');
+});
+
+// ===========================================================================
+// Layer 2 — REAL in-process HTTP through the actual router
+// ===========================================================================
+
+console.log('\nHTTP-level (real router, fake auth, stubbed store + builder lookup):');
+
+const orig = {
+  requireBuilder: auth.requireBuilder,
+  requireBfgPrincipal: auth.requireBfgPrincipal,
+  bfgWriteMemoryFile: memory.bfgWriteMemoryFile,
+  storeMemoryFilesBatch: memory.storeMemoryFilesBatch,
+  deleteMemoryFile: memory.deleteMemoryFile,
+  getBuilderById: db.getBuilderById,
+  BFG_WRITE_ENABLED: process.env.BFG_WRITE_ENABLED,
+};
+
+const fixture = {
+  session: { id: 9, github_login: 'bfg-system', system_role: 'bfg', rank: 'xenos' },
+  target: { id: 42, github_login: 'alice', system_role: null },
+  writeCalls: [],
+  syncBatchCalls: [],
+  deleteCalls: [],
+};
+
+auth.requireBuilder = function fakeRequireBuilder(req, _res, next) {
+  req.builder = { ...fixture.session };
+  next();
+};
+// Real-shaped identity gate so the 403 we assert IS the gate behavior.
+auth.requireBfgPrincipal = function fakeBfgGate(req, res, next) {
+  if (!req.builder || req.builder.system_role !== 'bfg') {
+    return res.status(403).json({ error: 'not_bfg_principal' });
+  }
+  next();
+};
+memory.bfgWriteMemoryFile = async function stubWrite(args) {
+  fixture.writeCalls.push(args);
+  return {
+    row: { builder_id: args.targetBuilderId, path: args.path, sha256: 'deadbeef', byte_len: args.content.length, updated_at: '2026-06-03T00:00:00Z' },
+    audit_id: 123,
+  };
+};
+memory.storeMemoryFilesBatch = async function stubBatch(_builderId, files) {
+  fixture.syncBatchCalls.push(files);
+  return files.map((f) => ({ ok: true, row: { path: f.path, sha256: 'x', byte_len: 1, updated_at: 'now', created_at: 'now' } }));
+};
+memory.deleteMemoryFile = async function stubDelete(builderId, p) {
+  fixture.deleteCalls.push({ builderId, path: p });
+  return p === 'bfg/gone.md' ? 0 : 1; // 0 = nothing to delete
+};
+db.getBuilderById = async function stubGet(id) {
+  if (Number(id) === fixture.target.id) return fixture.target;
+  if (Number(id) === 999) return null;
+  if (Number(id) === 500) return { id: 500, system_role: 'bfg' }; // another system principal
+  return { id: Number(id), system_role: null, github_login: 'someone' };
+};
+
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.use('/api/gds', buildMemoryRouter());
+const server = http.createServer(app);
+await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+const base = `http://127.0.0.1:${server.address().port}/api/gds`;
+
+function reset() { fixture.writeCalls = []; fixture.syncBatchCalls = []; fixture.deleteCalls = []; }
+async function post(p, body, sessionOverride) {
+  if (sessionOverride) fixture.session = sessionOverride;
+  return fetch(`${base}${p}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+}
+const VALID = { kind: 'dream', slug: 'commit-first', title: 'Commit first', body_md: 'Commit before ship.', rationale: 'It avoids the empty-diff footgun.' };
+
+try {
+  await t('(1) principal + enabled + valid → 201, write helper called with the target id + bfg/ path', async () => {
+    reset();
+    process.env.BFG_WRITE_ENABLED = 'true';
+    fixture.session = { id: 9, github_login: 'bfg-system', system_role: 'bfg', rank: 'xenos' };
+    const res = await post('/memory/builders/42/bfg-write', VALID);
+    assert.equal(res.status, 201);
+    const body = await res.json();
+    assert.equal(body.ok, true);
+    assert.equal(body.author, 'BFG');
+    assert.equal(body.builder_id, 42);
+    assert.equal(body.path, 'bfg/dream-commit-first.md');
+    assert.equal(fixture.writeCalls.length, 1);
+    assert.equal(fixture.writeCalls[0].targetBuilderId, 42);
+    assert.ok(fixture.writeCalls[0].path.startsWith('bfg/'));
+    assert.equal(fixture.writeCalls[0].audit.action, 'bfg_dream_write');
+  });
+
+  await t('(2) an ARCHON token → 403 and the write helper is NEVER called (ADR 0026 §6C)', async () => {
+    reset();
+    process.env.BFG_WRITE_ENABLED = 'true';
+    const res = await post('/memory/builders/42/bfg-write', VALID, { id: 1, github_login: 'an-archon', rank: 'archon', system_role: null });
+    assert.equal(res.status, 403);
+    assert.equal((await res.json()).error, 'not_bfg_principal');
+    assert.equal(fixture.writeCalls.length, 0, 'no cross-builder write may happen for a non-principal');
+  });
+
+  await t('(3) kill-switch OFF → 503, write helper NOT called (even for the principal)', async () => {
+    reset();
+    delete process.env.BFG_WRITE_ENABLED;
+    fixture.session = { id: 9, github_login: 'bfg-system', system_role: 'bfg', rank: 'xenos' };
+    const res = await post('/memory/builders/42/bfg-write', VALID);
+    assert.equal(res.status, 503);
+    assert.equal((await res.json()).error, 'bfg_write_disabled');
+    assert.equal(fixture.writeCalls.length, 0);
+    process.env.BFG_WRITE_ENABLED = 'true';
+  });
+
+  await t('(4) writing to SELF → 400 bfg_cannot_write_self', async () => {
+    reset();
+    fixture.session = { id: 9, github_login: 'bfg-system', system_role: 'bfg', rank: 'xenos' };
+    const res = await post('/memory/builders/9/bfg-write', VALID);
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error, 'bfg_cannot_write_self');
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(5) target that is a SYSTEM principal → 400 target_is_system_principal', async () => {
+    reset();
+    const res = await post('/memory/builders/500/bfg-write', VALID);
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error, 'target_is_system_principal');
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(6) target not found → 404', async () => {
+    reset();
+    const res = await post('/memory/builders/999/bfg-write', VALID);
+    assert.equal(res.status, 404);
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(7) bad input (bad kind) → 400 bad_bfg_input, write helper not called', async () => {
+    reset();
+    const res = await post('/memory/builders/42/bfg-write', { ...VALID, kind: 'nightmare' });
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error, 'bad_bfg_input');
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(8) a builder CANNOT sync into the reserved bfg/ namespace; other files still store', async () => {
+    reset();
+    fixture.session = { id: 42, github_login: 'alice', system_role: null, rank: 'xenos' };
+    const res = await post('/memory/sync', { files: [
+      { path: 'bfg/dream-sneaky.md', content: 'trying to spoof a BFG note' },
+      { path: 'notes.md', content: 'my own note' },
+    ] });
+    const body = await res.json();
+    const reserved = body.results.find((r) => r.path === 'bfg/dream-sneaky.md');
+    assert.ok(reserved && reserved.error && reserved.error.code === 'RESERVED_NAMESPACE', 'bfg/ sync must be refused');
+    // the batch helper must have been handed ONLY the non-reserved file
+    assert.equal(fixture.syncBatchCalls.length, 1);
+    assert.deepEqual(fixture.syncBatchCalls[0].map((f) => f.path), ['notes.md']);
+  });
+
+  // ---- 6C.2: correction karma + delete affordance ----
+
+  await t('(9) a correction with a negative karma_delta passes karma to the write helper', async () => {
+    reset();
+    process.env.BFG_WRITE_ENABLED = 'true';
+    fixture.session = { id: 9, github_login: 'bfg-system', system_role: 'bfg', rank: 'xenos' };
+    const res = await post('/memory/builders/42/bfg-write', { kind: 'correction', slug: 'claim-first', title: 'Correction', body_md: 'You edited without a claim.', rationale: 'methodology', karma_delta: -3 });
+    assert.equal(res.status, 201);
+    assert.equal(fixture.writeCalls.length, 1);
+    assert.ok(fixture.writeCalls[0].karma, 'karma must be passed through');
+    assert.equal(fixture.writeCalls[0].karma.delta, -3);
+    assert.equal(fixture.writeCalls[0].karma.reason, 'bfg_correction');
+    assert.equal(fixture.writeCalls[0].karma.grantedBy, 9, 'granted_by = the principal');
+  });
+
+  await t('(10) a POSITIVE karma_delta is rejected (corrections dock, never reward)', async () => {
+    reset();
+    const res = await post('/memory/builders/42/bfg-write', { kind: 'correction', slug: 'x', body_md: 'b', rationale: 'r', karma_delta: 5 });
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error, 'bad_karma_delta');
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(11) karma_delta on a DREAM is rejected', async () => {
+    reset();
+    const res = await post('/memory/builders/42/bfg-write', { ...VALID, karma_delta: -1 });
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error, 'karma_delta_not_allowed');
+    assert.equal(fixture.writeCalls.length, 0);
+  });
+
+  await t('(12) a builder DELETEs their own (BFG-written) file → 200, scoped to the session id', async () => {
+    reset();
+    fixture.session = { id: 42, github_login: 'alice', system_role: null, rank: 'xenos' };
+    const res = await fetch(`${base}/memory/file?path=bfg/dream-x.md`, { method: 'DELETE' });
+    assert.equal(res.status, 200);
+    assert.equal((await res.json()).deleted, true);
+    assert.equal(fixture.deleteCalls.length, 1);
+    assert.equal(fixture.deleteCalls[0].builderId, 42, 'delete is scoped to the authenticated session, never a path-supplied owner');
+    assert.equal(fixture.deleteCalls[0].path, 'bfg/dream-x.md');
+  });
+
+  await t('(13) DELETE of an absent file → 404', async () => {
+    reset();
+    fixture.session = { id: 42, github_login: 'alice', system_role: null, rank: 'xenos' };
+    const res = await fetch(`${base}/memory/file?path=bfg/gone.md`, { method: 'DELETE' });
+    assert.equal(res.status, 404);
+  });
+} finally {
+  await new Promise((resolve) => server.close(resolve));
+  auth.requireBuilder = orig.requireBuilder;
+  auth.requireBfgPrincipal = orig.requireBfgPrincipal;
+  memory.bfgWriteMemoryFile = orig.bfgWriteMemoryFile;
+  memory.storeMemoryFilesBatch = orig.storeMemoryFilesBatch;
+  memory.deleteMemoryFile = orig.deleteMemoryFile;
+  db.getBuilderById = orig.getBuilderById;
+  if (orig.BFG_WRITE_ENABLED === undefined) delete process.env.BFG_WRITE_ENABLED;
+  else process.env.BFG_WRITE_ENABLED = orig.BFG_WRITE_ENABLED;
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/bongos_box_connect.mjs

@@ -0,0 +1,89 @@
+// tests/bongos_box_connect.mjs — pure helpers behind `bongos shell` / `bongos code`
+// (V4.R80 / task 1247). DB-free + network-free: only the pure string/decision
+// helpers are exercised. Picked up by scripts/gds/run-unit-tests.js (the `unit` gate).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import lib from '../scripts/gds/box-connect-lib.js';
+
+const HOST = 'box-alice.dev.amazonprimea.com';
+
+test('rankAtLeast gates --local at Metic+', () => {
+  assert.equal(lib.rankAtLeast('metic', 'metic'), true);
+  assert.equal(lib.rankAtLeast('archon', 'metic'), true);
+  assert.equal(lib.rankAtLeast('thetes', 'metic'), false);
+  assert.equal(lib.rankAtLeast('xenos', 'metic'), false);
+  assert.equal(lib.rankAtLeast(null, 'metic'), false);
+  assert.equal(lib.rankAtLeast('nonsense', 'metic'), false);
+});
+
+test('buildSshAliasBlock carries the box user, key, and host-key policy', () => {
+  const b = lib.buildSshAliasBlock({ hostname: HOST, identityFile: '~/.ssh/otb_builder' });
+  assert.match(b, new RegExp(`^Host ${HOST}$`, 'm'));
+  assert.match(b, /User root/);
+  assert.match(b, /IdentityFile ~\/\.ssh\/otb_builder/);
+  assert.match(b, /StrictHostKeyChecking accept-new/);
+  assert.match(b, /IdentitiesOnly yes/);
+});
+
+test('upsertSshConfigText appends when absent and preserves other content', () => {
+  const existing = 'Host example\n    HostName example.com\n';
+  const next = lib.upsertSshConfigText(existing, { hostname: HOST, identityFile: '~/.ssh/otb_builder' });
+  assert.ok(next.includes('Host example'), 'keeps the pre-existing block');
+  assert.ok(next.includes(`Host ${HOST}`), 'adds the box block');
+});
+
+test('upsertSshConfigText is idempotent (re-run yields the same body)', () => {
+  const once = lib.upsertSshConfigText('', { hostname: HOST, identityFile: '~/.ssh/otb_builder' });
+  const twice = lib.upsertSshConfigText(once, { hostname: HOST, identityFile: '~/.ssh/otb_builder' });
+  assert.equal(twice, once);
+  // Exactly one block for this host.
+  const matches = twice.match(new RegExp(`Host ${HOST.replace(/\./g, '\\.')}\\b`, 'g')) || [];
+  assert.equal(matches.length, 1);
+});
+
+test('upsertSshConfigText replaces a changed block in place, not duplicating', () => {
+  const first = lib.upsertSshConfigText('', { hostname: HOST, identityFile: '~/.ssh/otb_builder' });
+  const changed = lib.upsertSshConfigText(first, { hostname: HOST, identityFile: '~/.ssh/other_key' });
+  assert.ok(changed.includes('IdentityFile ~/.ssh/other_key'));
+  assert.ok(!changed.includes('IdentityFile ~/.ssh/otb_builder'));
+  const begins = changed.match(/# >>> bongos-managed/g) || [];
+  assert.equal(begins.length, 1);
+});
+
+test('buildKnownHostsUpsert drops the stale line for the host, keeps others, appends keys', () => {
+  const existing = [
+    'other.example.com ssh-ed25519 AAAAOTHER',
+    `${HOST} ssh-ed25519 AAAASTALE`,
+  ].join('\n') + '\n';
+  const hostKeys = 'ssh-ed25519 AAAANEW\nssh-rsa AAAARSANEW';
+  const next = lib.buildKnownHostsUpsert(existing, HOST, hostKeys);
+  assert.ok(next.includes('other.example.com ssh-ed25519 AAAAOTHER'), 'keeps unrelated hosts');
+  assert.ok(!next.includes('AAAASTALE'), 'drops the stale key for this host');
+  assert.ok(next.includes(`${HOST} ssh-ed25519 AAAANEW`), 'appends the reported key');
+  assert.ok(next.includes(`${HOST} ssh-rsa AAAARSANEW`), 'appends every reported key');
+});
+
+test('buildRemoteShellCommand forces claude only on first run and always lands in /workspace', () => {
+  const first = lib.buildRemoteShellCommand({ firstRun: true });
+  const later = lib.buildRemoteShellCommand({ firstRun: false });
+  assert.match(first, /cd \/workspace/);
+  assert.match(first, /claude \|\| true/);
+  assert.match(first, /exec bash -l/);
+  assert.match(later, /cd \/workspace/);
+  assert.ok(!/claude/.test(later), 'no forced claude on a normal connect');
+  assert.match(later, /exec bash -l/);
+});
+
+test('remoteAuthority builds a VS Code Remote-SSH authority', () => {
+  assert.equal(lib.remoteAuthority(HOST), `ssh-remote+${HOST}`);
+});
+
+test('parseEnsure normalizes the /box/ensure body', () => {
+  assert.deepEqual(lib.parseEnsure({ action: 'ready', state: 'active', queued: false }), {
+    action: 'ready',
+    state: 'active',
+    message: null,
+  });
+  assert.deepEqual(lib.parseEnsure({}), { action: null, state: null, message: null });
+  assert.deepEqual(lib.parseEnsure(null), { action: null, state: null, message: null });
+});

package/tests/bongos_dispatch.mjs

@@ -0,0 +1,74 @@
+// tests/bongos_dispatch.mjs — the `bongos` CLI dispatch table (V4.R79 / task 1246).
+//
+// DB-free unit test: it only inspects the static verb table and spawns the
+// help/unknown/bare paths (which return before touching the network). Picked up
+// automatically by scripts/gds/run-unit-tests.js (the `unit` gate).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import bongos from '../bin/bongos.js';
+
+const { VERBS, GDS_DIR, helpText } = bongos;
+const BIN = fileURLToPath(new URL('../bin/bongos.js', import.meta.url));
+
+// The 7 verbs the task's "done when" explicitly requires to dispatch.
+const REQUIRED = ['start', 'claim', 'ship', 'box', 'cost', 'status', 'recall'];
+
+test('every required verb is registered', () => {
+  for (const v of REQUIRED) assert.ok(VERBS[v], `missing required verb: ${v}`);
+});
+
+test('every mapped script exists on disk (a typo cannot ship a dead verb)', () => {
+  for (const [verb, def] of Object.entries(VERBS)) {
+    if (!def.script) continue; // special verbs (exec) dispatch without a backing scripts/gds/ file
+    const p = path.join(GDS_DIR, def.script);
+    assert.ok(existsSync(p), `verb "${verb}" -> missing script scripts/gds/${def.script}`);
+  }
+});
+
+test('`bongos exec` runs a package script and refuses a path escape (ADR 0108 §3 / W3)', () => {
+  const { resolveExecTarget } = bongos;
+  assert.ok(resolveExecTarget('scripts/gds/next-number.js'), 'a package-relative script resolves');
+  assert.equal(resolveExecTarget('/etc/passwd'), null, 'an absolute path is refused');
+  assert.equal(resolveExecTarget('../../../etc/passwd'), null, 'a `..` escape is refused');
+  // end-to-end: exec a harmless core script (next-number prints + exits 0)
+  const r = spawnSync(process.execPath, [BIN, 'exec', 'scripts/gds/next-number.js', '--json'], { encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /"migration"/, 'exec forwarded to the core script and returned its output');
+  // refusal path exits 2 with guidance
+  const bad = spawnSync(process.execPath, [BIN, 'exec', '/etc/passwd'], { encoding: 'utf8' });
+  assert.equal(bad.status, 2);
+});
+
+test('help lists every verb', () => {
+  const h = helpText();
+  for (const verb of Object.keys(VERBS)) {
+    assert.ok(h.includes(verb), `help text omits "${verb}"`);
+  }
+});
+
+test('`bongos help` exits 0 and prints the banner', () => {
+  const r = spawnSync(process.execPath, [BIN, 'help'], { encoding: 'utf8' });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /bongos — the Cloud Bongos CLI/);
+});
+
+test('an unknown command exits 2 and shows help on stderr', () => {
+  const r = spawnSync(process.execPath, [BIN, 'definitely-not-a-verb'], { encoding: 'utf8' });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /unknown command/);
+});
+
+test('bare `bongos` prints help and exits 0', () => {
+  const r = spawnSync(process.execPath, [BIN], { encoding: 'utf8' });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /Usage:  bongos/);
+});
+
+test('a prefix-args verb (box) targets the generic api.js caller', () => {
+  assert.equal(VERBS.box.script, 'api.js');
+  assert.deepEqual(VERBS.box.prefixArgs, ['POST', '/api/gds/box/ensure']);
+});