@bongos/core 1.23.21 → 1.24.1

package/tests/unit_runner_serial.mjs

@@ -1,72 +1,295 @@
 // tests/unit_runner_serial.mjs
 //
-// The `unit` gate runs its tests SERIALLY, one child process each — pinned here
-// because that property is now load-bearing, not incidental (task 1001435).
+// The `unit` gate runs several test files at once, and keeps the files that share state
+// outside their own process in a SERIAL lane that runs alone (task 1004926). This file used
+// to pin the opposite — that the runner was strictly one-at-a-time (task 1001435) — by
+// reading the runner's source. It now drives the runner's own pieces instead:
 //
-// A flaky-`unit` report (idea #353) diagnosed "parallel execution racing on shared
-// global state" and asked, correctly, whether run-unit-tests fans tests out
-// concurrently in one process. It does not: runOne calls execFileSync, which
-// BLOCKS, from plain sequential for-loops. That rules an in-process race out by
-// construction, and scripts/bongos/run-unit-tests.js now records the audit that
-// followed from it — including that two of the three suites the report named
-// (fitness, session_index) mutate no global state at all.
-//
-// All of that reasoning is only true while execution stays serial. Make the runner
-// concurrent and every word of it silently becomes wrong, with no test to say so —
-// so this suite fails if that happens, and whoever does it has to revisit the note
-// rather than leave a stale explanation behind.
-//
-// Static source assertions on purpose: actually observing concurrency would mean
-// running the whole gate from inside the gate.
+//   - the pool size: UNIT_TESTS_SERIAL=1 forces one at a time, UNIT_TEST_JOBS=N sets it,
+//     the default is the CPU count;
+//   - which files go to the serial lane: a browser launch, a fixed listen port, a fixed
+//     temp path, or a name in SERIAL;
+//   - the scheduler: a serial-lane file never overlaps anything, the pool never exceeds
+//     its size, and output prints in entry order whatever order the files finish in;
+//   - the real child-process path: pass, fail, a stdin read, and a timeout, through the
+//     same runFile the gate uses.
 //
 // Run:  node tests/unit_runner_serial.mjs
 
 import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const RUNNER = path.join(ROOT, 'scripts', 'bongos', 'run-unit-tests.js');
-const src = fs.readFileSync(RUNNER, 'utf8');
+const require = createRequire(import.meta.url);
+const runner = require(path.join(ROOT, 'scripts', 'bongos', 'run-unit-tests.js'));
+const { resolveJobs, serialReason, runFile, runEntries, renderResult, SERIAL, UNIT_TESTS_SERIAL_ENV, UNIT_TEST_JOBS_ENV } = runner;
 
 let passed = 0;
 let failed = 0;
-function t(name, fn) {
-  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
   catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
 }
 
-t('each test runs in its OWN process, spawned synchronously', () => {
-  assert.match(src, /execFileSync\(\s*process\.execPath/,
-    'the runner must spawn each test with execFileSync (blocking, one process per test)');
+// ── pool size ────────────────────────────────────────────────────────────────────────
+
+await t('default pool size is the CPU count', () => {
+  assert.equal(resolveJobs({}, 8), 8);
+  assert.equal(resolveJobs({}, 0), 1, 'never below one');
+});
+
+await t('UNIT_TESTS_SERIAL=1 forces one at a time, whatever the machine', () => {
+  assert.equal(UNIT_TESTS_SERIAL_ENV, 'UNIT_TESTS_SERIAL');
+  for (const v of ['1', 'true', 'yes', 'on', 'TRUE']) assert.equal(resolveJobs({ UNIT_TESTS_SERIAL: v }, 16), 1, v);
+  assert.equal(resolveJobs({ UNIT_TESTS_SERIAL: '1', UNIT_TEST_JOBS: '8' }, 16), 1, 'serial wins over a jobs count');
+  assert.equal(resolveJobs({ UNIT_TESTS_SERIAL: '0' }, 16), 16, '0 does not force serial');
+});
+
+await t('UNIT_TEST_JOBS=N sets the pool size; junk is ignored', () => {
+  assert.equal(UNIT_TEST_JOBS_ENV, 'UNIT_TEST_JOBS');
+  assert.equal(resolveJobs({ UNIT_TEST_JOBS: '3' }, 16), 3);
+  assert.equal(resolveJobs({ UNIT_TEST_JOBS: '1' }, 16), 1);
+  for (const junk of ['0', '-2', 'many', '2.5']) assert.equal(resolveJobs({ UNIT_TEST_JOBS: junk }, 6), 6, junk);
+});
+
+// ── serial-lane classification ──────────────────────────────────────────────────────
+
+await t('a browser launch goes to the serial lane', () => {
+  assert.equal(serialReason('x', "import { chromium } from 'playwright';"), 'launches a browser');
+  assert.equal(serialReason('x', "const b = await puppeteer.launch({ headless: 'new' });"), 'launches a browser');
+});
+
+await t('a fixed listen port goes to the serial lane; listen(0) does not', () => {
+  assert.equal(serialReason('x', 'server.listen(3100, () => {});'), 'listens on a fixed port');
+  assert.equal(serialReason('x', 'server.listen(8080)'), 'listens on a fixed port');
+  assert.equal(serialReason('x', 'server.listen(0, () => {});'), null);
+  assert.equal(serialReason('x', "assert.match(out, /PORT=3003/);"), null, 'a port in an assertion is not a listen');
+});
+
+await t('a fixed temp path goes to the serial lane; a mkdtemp prefix does not', () => {
+  assert.equal(serialReason('x', "const p = path.join(os.tmpdir(), 'probe-home');"), 'uses a fixed temp path');
+  assert.equal(serialReason('x', "const d = fs.mkdtempSync(path.join(os.tmpdir(), 'probe-'));"), null);
+  assert.equal(serialReason('x', "const d = mkdtempSync(join(os.tmpdir(), 'probe-'));"), null);
+  assert.equal(serialReason('x', 'const p = path.join(os.tmpdir(), `probe-${process.pid}`);'), null, 'a per-process name is not shared');
+  // A file with one mkdtemp and one fixed path is still serial — the fixed one decides.
+  assert.equal(serialReason('x', "fs.mkdtempSync(path.join(os.tmpdir(), 'a-'));\nconst p = path.join(os.tmpdir(), 'fixed');"), 'uses a fixed temp path');
+});
+
+await t('a name in SERIAL is serial whatever its source says', () => {
+  SERIAL.add('__probe_listed__');
+  try {
+    assert.equal(serialReason('__probe_listed__', ''), 'listed in SERIAL');
+  } finally { SERIAL.delete('__probe_listed__'); }
+  assert.equal(serialReason('plain', 'assert.equal(1, 1);'), null);
+});
+
+await t('the real suite: every browser-launching test file lands in the serial lane', () => {
+  // The scan has to keep seeing the files it exists for. A pattern that silently stopped
+  // matching would put Chrome back in the pool, and green would look the same.
+  for (const name of ['page_reader', 'ui_design_skills']) {
+    const src = fs.readFileSync(path.join(ROOT, 'tests', `${name}.mjs`), 'utf8');
+    assert.equal(serialReason(name, src), 'launches a browser', name);
+  }
+  // and not everything: the pool has to have something in it
+  const sample = fs.readdirSync(path.join(ROOT, 'tests')).filter((f) => f.endsWith('.mjs')).slice(0, 200);
+  const serial = sample.filter((f) => serialReason(f, fs.readFileSync(path.join(ROOT, 'tests', f), 'utf8')));
+  assert.ok(serial.length < sample.length / 2, `most files run in the pool (${serial.length}/${sample.length} serial)`);
+});
+
+// ── scheduler ────────────────────────────────────────────────────────────────────────
+
+// A fake `run` that finishes each file after a set delay and records what overlapped.
+function fakeRun(delays) {
+  const log = { inFlight: new Set(), maxInFlight: 0, overlapsWithSerial: [], started: [] };
+  const run = async (file) => {
+    log.inFlight.add(file);
+    log.started.push(file);
+    log.maxInFlight = Math.max(log.maxInFlight, log.inFlight.size);
+    if (file.startsWith('S') && log.inFlight.size > 1) log.overlapsWithSerial.push([...log.inFlight]);
+    for (const other of log.inFlight) if (other !== file && other.startsWith('S')) log.overlapsWithSerial.push([...log.inFlight]);
+    await new Promise((r) => setTimeout(r, delays[file] ?? 5));
+    log.inFlight.delete(file);
+    return { ok: !file.endsWith('!'), status: file.endsWith('!') ? 1 : 0, signal: null, killed: false, stdout: file.endsWith('!') ? '  FAIL  case\n0 passed, 1 failed' : '1 passed, 0 failed', stderr: '' };
+  };
+  return { run, log };
+}
+
+const entry = (file) => ({ displayName: file, file, serial: file.startsWith('S') ? 'listed in SERIAL' : null });
+
+await t('output prints in entry order even when later files finish first', async () => {
+  const files = ['a', 'b', 'c', 'd', 'e', 'f'];
+  // a is slowest, so every other file finishes before it
+  const { run } = fakeRun({ a: 60, b: 5, c: 10, d: 1, e: 20, f: 2 });
+  const printed = [];
+  const results = await runEntries(files.map(entry), { jobs: 4, perTestTimeout: 1000, run, print: (l) => printed.push(l) });
+  assert.deepEqual(printed, files.map((f) => `  ok    ${f}`));
+  assert.deepEqual(results.map((r) => r.outcome), files.map(() => 'ok'));
 });
 
-t('the run loops are sequential — no concurrency primitive in the runner', () => {
-  // Promise.all / allSettled over the file list, a worker pool, or the async
-  // execFile would each make the suites overlap and reintroduce the shared-state
-  // class the recorded audit rules out.
-  assert.doesNotMatch(src, /Promise\.(all|allSettled|race)\s*\(/,
-    'a Promise.all over the test list would run suites concurrently');
-  assert.doesNotMatch(src, /require\(['"]node:worker_threads['"]\)|from ['"]node:worker_threads['"]/,
-    'a worker pool would run suites concurrently');
-  assert.doesNotMatch(src, /\bexecFile\s*\(/,
-    'the ASYNC execFile would overlap suites; the runner uses execFileSync');
+await t('the pool runs files concurrently but never more than its size', async () => {
+  const files = Array.from({ length: 12 }, (_, i) => `p${String(i).padStart(2, '0')}`);
+  const { run, log } = fakeRun(Object.fromEntries(files.map((f) => [f, 15])));
+  await runEntries(files.map(entry), { jobs: 3, perTestTimeout: 1000, run, print: () => {} });
+  assert.equal(log.maxInFlight, 3);
 });
 
-t('the loop over the discovered test files is a plain for-of', () => {
-  assert.match(src, /for \(const name of files\) runOne\(/,
-    'sequential iteration is the mechanism — not a map() returning promises');
+await t('a serial-lane file never runs beside anything else', async () => {
+  const files = ['S1', 'a', 'b', 'S2', 'c', 'd', 'e', 'S3'];
+  const { run, log } = fakeRun(Object.fromEntries(files.map((f) => [f, 10])));
+  const printed = [];
+  await runEntries(files.map(entry), { jobs: 4, perTestTimeout: 1000, run, print: (l) => printed.push(l) });
+  assert.deepEqual(log.overlapsWithSerial, [], 'no serial file overlapped another run');
+  assert.ok(log.maxInFlight > 1, 'the pool part still ran in parallel');
+  assert.deepEqual(printed, files.map((f) => `  ok    ${f}`), 'still printed in entry order');
 });
 
-t('the serial guarantee is EXPLAINED where it is relied on, not just true by accident', () => {
-  // The audit recorded beside the loop is what a future flake investigation reads
-  // instead of re-deriving it. If the loop is rewritten the note must be revisited,
-  // which is the whole point of pinning it next to the mechanism.
-  assert.match(src, /EXECUTION IS SERIAL, ONE PROCESS PER TEST/,
-    'run-unit-tests.js must carry the note explaining why serialism is relied upon');
+await t('jobs=1 runs everything one at a time, in entry order', async () => {
+  const files = ['S1', 'a', 'b', 'c'];
+  const { run, log } = fakeRun({ a: 15, b: 1, c: 5 });
+  await runEntries(files.map(entry), { jobs: 1, perTestTimeout: 1000, run, print: () => {} });
+  assert.equal(log.maxInFlight, 1);
+  assert.deepEqual(log.started, files);
 });
 
+await t('a failure keeps its verdict and detail lines, in its place', async () => {
+  const files = ['a', 'b!', 'c'];
+  const { run } = fakeRun({ a: 20, 'b!': 1, c: 1 });
+  const printed = [];
+  const results = await runEntries(files.map(entry), { jobs: 3, perTestTimeout: 1000, run, print: (l) => printed.push(l) });
+  assert.deepEqual(results.map((r) => r.outcome), ['ok', 'fail', 'ok']);
+  assert.equal(printed[0], '  ok    a');
+  assert.equal(printed[1], '  FAIL  b! (exit 1)');
+  assert.ok(printed.includes('      FAIL  case'), 'the file\'s own FAIL line is shown');
+  assert.equal(printed[printed.length - 1], '  ok    c');
+});
+
+await t('a pooled TIMEOUT is re-run alone, and the alone run is the verdict', async () => {
+  const calls = [];
+  let inFlight = 0;
+  const run = async (file) => {
+    inFlight++;
+    const alone = inFlight === 1;
+    calls.push({ file, alone });
+    await new Promise((r) => setTimeout(r, 5));
+    inFlight--;
+    // 'slow' only finishes when nothing else is running; 'hang' never finishes
+    const killed = file === 'hang' || (file === 'slow' && !calls.filter((c) => c.file === 'slow').at(-1).alone);
+    return { ok: !killed, status: killed ? null : 0, signal: killed ? 'SIGTERM' : null, killed, stdout: killed ? '' : '1 passed, 0 failed', stderr: '' };
+  };
+  const files = ['a', 'hang', 'slow', 'z'];
+  const printed = [];
+  const results = await runEntries(files.map(entry), { jobs: 4, perTestTimeout: 1000, run, print: (l) => printed.push(l) });
+  assert.deepEqual(results.map((r) => r.outcome), ['ok', 'fail', 'ok', 'ok'], 'starved-only passes; a real hang still fails');
+  assert.equal(calls.filter((c) => c.file === 'slow').length, 2);
+  assert.equal(calls.filter((c) => c.file === 'slow').at(-1).alone, true, 'the re-run had nothing beside it');
+  assert.equal(calls.filter((c) => c.file === 'a').length, 1, 'a file that passed is not re-run');
+  assert.equal(printed[0], '  ok    a');
+  assert.equal(printed[1], '  FAIL  hang (TIMEOUT after 1s, SIGTERM)');
+  assert.match(printed[2], /re-run alone/);
+  assert.equal(printed.at(-1), '  ok    z', 'still in entry order');
+});
+
+await t('an assertion failure in the pool is NOT re-run', async () => {
+  const { run, log } = fakeRun({});
+  await runEntries(['a', 'b!'].map(entry), { jobs: 2, perTestTimeout: 1000, run, print: () => {} });
+  assert.deepEqual(log.started.filter((f) => f === 'b!'), ['b!']);
+});
+
+await t('a write inside the repo goes to the serial lane; a write into a temp dir does not', () => {
+  const why = 'writes inside the repo';
+  assert.equal(serialReason('x', "const probe = path.join(ROOT, 'modules', 'p');\nmkdirSync(probe);"), why);
+  assert.equal(serialReason('x', "fs.writeFileSync(path.join(REPO_ROOT, 'config', 'x.json'), '{}');"), why);
+  assert.equal(serialReason('x', "const target = new URL('../src/a.js', import.meta.url);\nfs.writeFileSync(target, s);"), why);
+  assert.equal(serialReason('x', "const tmp = fs.mkdtempSync(path.join(ROOT, '.tmp-'));"), why);
+  assert.equal(serialReason('x', "const src = path.join(ROOT, 'config', 'a.json');\nfs.readFileSync(src, 'utf8');"), null, 'reading the repo is fine');
+  assert.equal(serialReason('x', "const d = fs.mkdtempSync(path.join(os.tmpdir(), 'w-'));\nfs.writeFileSync(path.join(d, 'f'), 'x');"), null);
+});
+
+await t('the real suite: every repo-writer found by watching a pooled run is in the serial lane', () => {
+  // Each of these changed a file another test reads while the pool ran (task 1004926).
+  for (const name of ['prelaunch_gate', 'file_map', 'figma_adapter', 'repo_map', 'government_vocabulary', 'cloud_bongos_pack', 'search_ingest_nul']) {
+    const src = fs.readFileSync(path.join(ROOT, 'tests', `${name}.mjs`), 'utf8');
+    assert.equal(serialReason(name, src), 'writes inside the repo', name);
+  }
+  // agents_event_router times a handler at 50 ms of wall clock — a busy pool makes that a coin toss
+  assert.equal(serialReason('agents_event_router', ''), 'listed in SERIAL');
+});
+
+// ── verdict rendering (unchanged rules)─────────────────────────────────────────────
+
+await t('renderResult: timeout, skips and the libuv teardown abort read as before', () => {
+  const timeout = renderResult('slow', { ok: false, status: null, signal: 'SIGTERM', killed: true, stdout: '', stderr: '' }, 90_000);
+  assert.equal(timeout.outcome, 'fail');
+  assert.equal(timeout.lines[0], '  FAIL  slow (TIMEOUT after 90s, SIGTERM)');
+  assert.match(timeout.lines[1], /no output at all/);
+
+  const skips = renderResult('sk', { ok: true, status: 0, signal: null, killed: false, stdout: '  SKIP one — no db\n1 passed, 0 failed, 1 skipped', stderr: '' }, 90_000);
+  assert.deepEqual(skips, { lines: ['  ok    sk (1 SKIPPED — not run here)'], outcome: 'ok', skips: 1 });
+
+  const abort = renderResult('ab', { ok: false, status: 127, signal: null, killed: false, stdout: '3 passed, 0 failed', stderr: 'Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)' }, 90_000);
+  assert.equal(abort.outcome, 'teardown');
+  assert.equal(abort.lines[0], '  ok    ab (clean verdict, then libuv teardown abort, exit 127)');
+});
+
+// ── the real child-process path ─────────────────────────────────────────────────────
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'unit-runner-pool-'));
+try {
+  const write = (name, body) => { const p = path.join(dir, name); fs.writeFileSync(p, body); return p; };
+  const pass = write('pass.mjs', "console.log('  PASS  one'); console.log('1 passed, 0 failed');\n");
+  const fail = write('fail.mjs', "console.log('  FAIL  one'); console.log('0 passed, 1 failed'); console.error('boom'); process.exit(3);\n");
+  const stdin = write('stdin.mjs', "process.stdin.resume(); process.stdin.on('end', () => { console.log('1 passed, 0 failed'); });\n");
+  const hang = write('hang.mjs', 'setInterval(() => {}, 1000);\n');
+
+  await t('runFile: a passing file resolves ok with its stdout', async () => {
+    const r = await runFile(pass, 20_000);
+    assert.equal(r.ok, true);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /1 passed, 0 failed/);
+  });
+
+  await t('runFile: a failing file resolves with its exit code, stdout and stderr', async () => {
+    const r = await runFile(fail, 20_000);
+    assert.equal(r.ok, false);
+    assert.equal(r.status, 3);
+    assert.equal(r.killed, false);
+    assert.match(r.stdout, /FAIL {2}one/);
+    assert.match(r.stderr, /boom/);
+    assert.equal(renderResult('fail', r, 20_000).lines[0], '  FAIL  fail (exit 3)');
+  });
+
+  await t('runFile: stdin reads see end-of-input at once, as under the old ignored stdin', async () => {
+    const r = await runFile(stdin, 20_000);
+    assert.equal(r.ok, true, 'a suite that reads stdin must not wait for the whole budget');
+  });
+
+  await t('runFile: a hung file is killed at the budget and reads as a TIMEOUT', async () => {
+    const r = await runFile(hang, 1_500);
+    assert.equal(r.ok, false);
+    assert.equal(r.killed, true);
+    assert.match(renderResult('hang', r, 1_500).lines[0], /^ {2}FAIL {2}hang \(TIMEOUT after 1\.5s/);
+  });
+
+  await t('runEntries end to end: real files, a pool of 3, sorted output and outcomes', async () => {
+    const entries = [
+      { displayName: 'fail', file: fail, serial: null },
+      { displayName: 'pass', file: pass, serial: 'listed in SERIAL' },
+      { displayName: 'stdin', file: stdin, serial: null },
+    ];
+    const printed = [];
+    const results = await runEntries(entries, { jobs: 3, perTestTimeout: 20_000, print: (l) => printed.push(l) });
+    assert.deepEqual(results.map((r) => r.outcome), ['fail', 'ok', 'ok']);
+    assert.equal(printed[0], '  FAIL  fail (exit 3)');
+    assert.deepEqual(printed.slice(-2), ['  ok    pass', '  ok    stdin']);
+  });
+} finally {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
 console.log('');
 console.log(`unit_runner_serial: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/version_close_route.mjs

@@ -166,7 +166,7 @@ function closePool({ status = 'building', goalStatus = 'open', remaining = 0, st
   return txPool((sql) => {
     const q = String(sql).replace(/\s+/g, ' ');
     if (/FROM versions WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 'V1', status }] };
-    if (/FROM goals WHERE id = \$1 AND version_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 'g', status: goalStatus }] };
+    if (/FROM goals WHERE id = ANY\(\$1::bigint\[\]\) AND version_id = \$2 ORDER BY id FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 'g', status: goalStatus }] };
     if (/UPDATE tasks SET status = 'abandoned'/.test(q)) return { rows: [{ id: 11 }, { id: 12 }] };
     // R17 (task 1003604) — the roll_forward writes: the successor INSERT, the
     // membership copy, and the task re-point.

package/tests/version_literals.mjs

@@ -75,7 +75,7 @@ test('an unknown future prefix is caught too', () => {
 
 // ---- what the guard must NOT catch ---------------------------------------
 test('a COMMENT naming an old version is not a violation', () => {
-  // smoke-claim-consistency.sh legitimately says "PMS-V2 P6 not live yet".
+  // A script may legitimately say "PMS-V2 P6 not live yet" in a comment.
   const r = scan({
     'scripts/bongos/d.sh': '# TODO: once PMS-V2 P6 ships, drop this',
     'scripts/bongos/e.js': "// version_id: 'GDS-V3' used to live here",
@@ -133,12 +133,10 @@ test('smoke-write.sh resolves its version instead of naming one', () => {
   assert.match(sh, /exit 1/, 'and stops if it cannot');
 });
 
-test('all four bash smokes resolve, and none names a version', () => {
-  for (const f of ['smoke-write.sh', 'smoke-claim-consistency.sh', 'smoke-batch-release.sh', 'smoke-batch-claim.sh']) {
-    const sh = read('scripts', 'bongos', f);
-    assert.match(sh, /version-select\.js/, `${f} resolves`);
-    assert.match(sh, /'version_id': '\$\{VERSION_ID\}'/, `${f} uses the resolved id`);
-  }
+test('the bash smoke writes the resolved id, not a named version', () => {
+  // smoke-write.sh is the one bash smoke left (task 1005002 deleted the other three).
+  const sh = read('scripts', 'bongos', 'smoke-write.sh');
+  assert.match(sh, /'version_id': '\$\{VERSION_ID\}'/, 'smoke-write.sh uses the resolved id');
 });
 
 test('capture.js no longer keeps its own copy of the rule', () => {

package/tests/welcome_boot.mjs

@@ -75,12 +75,23 @@ test('every light sits inside the painting, and every pulse climbs inside its to
   assert.deepEqual(W.pulseRuns(W.TOWERS, 3, 7), runs, 'seeded: every visit draws the same picture');
 });
 
-test('the banner names the project from the branding pack, never a hardcoded word', () => {
-  assert.equal(W.bannerText({ identity: { worldName: 'Harbor', productName: 'Cloud Bongos' } }), 'Working on the core of Harbor');
-  assert.equal(W.bannerText({ identity: { productName: 'Cloud Bongos' } }), 'Working on the core of Cloud Bongos');
-  assert.equal(W.bannerText(undefined), 'Working on the core of this project', 'no branding: still a sentence');
+test('the banner is the logo, named from the branding pack, never a hardcoded word (task 1004953)', () => {
+  assert.equal(W.bannerText, undefined, 'the "Working on the core of" banner is gone');
+  const harbor = W.logoHtml({ identity: { worldName: 'Harbor', productName: 'Cloud Bongos' } });
+  assert.match(harbor, /<svg class="wb__mark"/, 'no project logo: the Bongos mark');
+  assert.match(harbor, /class="wb__ring"[^>]*pathLength="100"/, 'the ring can draw in');
+  assert.match(harbor, /class="wb__moonlet"[^>]*fill="#fb9569"/, 'the salmon moon');
+  assert.match(harbor, /<span class="wb__name">Harbor<\/span>/);
+  assert.match(W.logoHtml(undefined), /<span class="wb__name">this project<\/span>/, 'no branding: still a name');
+  const own = W.logoHtml({ identity: { worldName: 'Harbor' }, theme: { logo: '/logo.png?a="b"' } });
+  assert.match(own, /<img class="wb__logo" src="\/logo\.png\?a=&quot;b&quot;"/, 'a project logo takes the mark\'s place, escaped');
+  assert.doesNotMatch(own, /wb__mark/);
   const branding = JSON.parse(fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8'));
-  assert.equal(W.bannerText(branding), 'Working on the core of ' + branding.identity.worldName);
+  assert.match(W.logoHtml(branding), new RegExp('>' + branding.identity.worldName + '<'));
+});
+
+test('the credit links to cloudbongos.com (task 1004953)', () => {
+  assert.deepEqual(W.BUILT_ON, { href: 'https://cloudbongos.com', label: 'cloudbongos.com' });
 });
 
 test('the owner\'s role mapping: destination and craft mode', () => {

package/tests/welcome_boot_browser.mjs

@@ -297,17 +297,49 @@ test('the way out sinks and fades into the hall, which is usable at once', { ski
   await ctx.close();
 });
 
-test('the banner names the project, the motion is laid on, and the drawn tower and city are gone', { skip }, async () => {
+test('the banner is the animated logo, the motion is laid on, and the drawn tower and city are gone', { skip }, async () => {
   const ctx = await hall();
   const { page } = await open(ctx);
   await signIn(page);
-  await page.waitForSelector('#welcome-boot .wb-motion');
+  await page.waitForSelector('#welcome-boot.wb--lit .wb-motion');
   const s = await page.evaluate(() => ({
-    banner: document.querySelector('.wb__banner .wb__eyebrow').textContent,
+    banner: document.querySelector('.wb__banner').textContent,
+    name: document.querySelector('.wb__banner .wb__name').textContent,
+    mark: !!document.querySelector('.wb__banner svg.wb__mark .wb__moonlet'),
+    ringAnim: getComputedStyle(document.querySelector('.wb__ring')).animationName,
     pulses: document.querySelectorAll('#wb-fx .wb-pulse').length,
     cars: document.querySelectorAll('#wb-fx .wb-car').length,
     old: document.querySelectorAll('.wb-floor, .wb-bldg, .wb-person, #wb-scene, #wb-beam, #wb-city').length,
   }));
-  assert.deepEqual(s, { banner: 'Working on the core of Harbor', pulses: 21, cars: 3, old: 0 });
+  assert.doesNotMatch(s.banner, /Working on the core of/, 'task 1004953: the banner text is gone');
+  assert.deepEqual({ name: s.name, mark: s.mark, ringAnim: s.ringAnim, pulses: s.pulses, cars: s.cars, old: s.old },
+    { name: 'Harbor', mark: true, ringAnim: 'wb-ring', pulses: 21, cars: 3, old: 0 });
   await ctx.close();
 });
+
+test('the "Built on cloudbongos.com" credit sits bottom right, clear of the choices, at desktop and phone width', { skip }, async () => {
+  for (const viewport of [{ width: 1280, height: 800 }, { width: 390, height: 760 }]) {
+    const ctx = await hall();
+    const { page } = await open(ctx);
+    await page.setViewportSize(viewport);
+    await page.evaluate(() => window.OTBShell.applyAccess({ authed: false }));
+    await page.waitForSelector('#welcome-boot .wb__built');
+    await page.click('[data-wb-skip]');
+    const s = await page.evaluate(() => {
+      const a = document.querySelector('.wb__built').getBoundingClientRect();
+      const c = document.querySelector('.wb__choices').getBoundingClientRect();
+      const el = document.querySelector('.wb__built');
+      return {
+        text: el.textContent, href: el.getAttribute('href'),
+        right: Math.round(innerWidth - a.right), bottom: Math.round(innerHeight - a.bottom),
+        clear: a.top >= c.bottom || a.right <= c.left || a.left >= c.right, tall: a.height >= 24,
+      };
+    });
+    assert.equal(s.text, 'Built on cloudbongos.com');
+    assert.equal(s.href, 'https://cloudbongos.com');
+    assert.ok(s.right <= 24 && s.bottom <= 24, 'bottom-right corner at ' + viewport.width + 'w');
+    assert.ok(s.clear, 'does not cover the choices at ' + viewport.width + 'w');
+    assert.ok(s.tall, 'a 24px target');
+    await ctx.close();
+  }
+});

package/docs/recipes/bongos-cli-release.md

@@ -1,66 +0,0 @@
-# Releasing the standalone `bongos` CLI
-
-How the compiled `bongos` binaries get built, published, and installed — the
-"no Node, no repo" on-ramp (task [#1248](https://example.com/builders#/task/1248), V4.R81).
-The release flow: **CI builds, the operator publishes to a public releases repo, the server serves
-branded redirects.** There is no cross-repo write token in CI — publishing is a
-deliberate operator step.
-
-## The moving parts
-
-| Piece | Where | Role |
-|---|---|---|
-| Build wrapper | [`scripts/bongos/build-bongos.js`](../../scripts/bongos/build-bongos.js) | `bun build --compile` → per-platform binaries in `dist/` |
-| CI | `.github/workflows/build-bongos-cli.yml` (instance-side) | runs the wrapper, uploads `bongos-cli-binaries` artifacts (no publish) |
-| Release pointer | `config/bongos-cli.json` (instance-side) | `releases_repo` + `version` + per-target asset filenames |
-| Redirects | [`src/bongos-downloads.js`](../../src/bongos-downloads.js) → `/downloads/bongos/*` in [`serve-internal.js`](../../src/bongos/serve-internal.js) | `/downloads/bongos/<target>` 302s to the release asset; `/version` + `/latest.json` for update-checks |
-| Installer | `infra/bongos-install.sh` + `.ps1` (instance-side) | served (origin-pinned) at `/downloads/bongos/install.sh` / `.ps1` |
-| Package managers | `packaging/homebrew/bongos.rb`, `packaging/scoop/bongos.json` (instance-side) | brew/scoop templates (fill sha256 at release) |
-
-## What the user runs
-
-```sh
-# macOS / Linux — no Node required:
-curl -fsSL https://example.com/downloads/bongos/install.sh | sh
-# Windows (PowerShell):
-irm https://example.com/downloads/bongos/install.ps1 | iex
-# or, once the tap/bucket is published:
-brew install example-owner/bongos/bongos          # macOS/Linux
-scoop bucket add bongos https://github.com/example-owner/scoop-bongos; scoop install bongos
-```
-
-Then: `bongos login <instance-url>` → `bongos start`. Writing code needs a checkout of the
-project repo, where the full CLI is installed.
-
-## One-time owner setup (tracked as the open blocker on [#1248](https://example.com/builders#/task/1248))
-
-1. **Create a PUBLIC releases repo** — `example-owner/example-bongos` (matches `config/bongos-cli.json`'s `releases_repo`). Public so GitHub's release CDN serves the downloads at $0; it holds ONLY the binaries, never source.
-2. *(optional, for brew/scoop)* create the tap repo `example-owner/homebrew-bongos` and/or the bucket `lars689/scoop-bongos`.
-3. *(optional)* point `get.bongos.dev` at the instance with a DNS CNAME → `example.com`, so the branded `curl -fsSL https://get.bongos.dev | sh` works (it just proxies `/downloads/bongos/install.sh`).
-
-## Cutting a release
-
-1. **Bump** `config/bongos-cli.json`: `version` + every `assets.*` filename to the new version. (Claim a task; this rides the normal ship flow.)
-2. **Push** → `build-bongos-cli.yml` runs and produces the `bongos-cli-binaries` artifact. Wait for green.
-3. **Download** the artifacts:
-   ```sh
-   gh run download -R example-owner/example --name bongos-cli-binaries --dir dist
-   ```
-4. **Publish** them as a `v<version>` release on the public repo:
-   ```sh
-   gh release create v0.1.0 -R example-owner/example-bongos --title "bongos v0.1.0" --notes "Standalone bongos CLI" dist/bongos-*
-   ```
-   The tag and asset filenames MUST match `config/bongos-cli.json` exactly — the redirect is `releases/download/v<version>/<asset>`; a renamed asset 404s.
-5. *(package managers)* compute `shasum -a 256 dist/bongos-*`, fill the `sha256`/`hash` fields in `packaging/homebrew/bongos.rb` + `packaging/scoop/bongos.json`, and copy them to the tap/bucket repos.
-6. **Ship** the `config/bongos-cli.json` bump. The `/downloads/bongos/*` redirects follow within a minute of deploy.
-
-Verify: `curl -fsSL https://example.com/downloads/bongos/version` shows the new version, and `curl -fsSL .../install.sh | sh` installs a working binary.
-
-## The binary architecture (why some verbs aren't in it)
-
-`bin/bongos.js` is one dispatcher with two runtimes ([task 1248](https://example.com/builders#/task/1248)):
-
-- **repo / `npm i -g`** → runs under `node`; spawns each sibling `scripts/bongos/*.js` (unchanged).
-- **compiled binary** → `process.execPath` is the `bongos` binary (no `node`, no scripts on disk), so it dispatches the **bundled on-ramp verbs in-process**: `login`/`setup`, `reauth`, `paste-token`, `api`, `init`, `onboard`. The heavy work verbs (`ship`/`claim`/`start`/`status`/`recall`/`cost`/`release`/`module`/`package-core`) and `doctor` are **not** bundled — they need a full repo + git to run, and pulling their dependency trees in would bloat the binary. Run those in a clone, where `npm i -g` gives the full CLI. A bare-binary user who invokes one gets a clear "get onto a real environment first" message.
-
-Follow-ups (not blocking the first release): SHA-pin `oven-sh/setup-bun`, code-sign the mac/win binaries, and expand the bundled verb set if a self-host workflow needs more offline.