@bongos/core 1.21.146 → 1.21.148

package/tests/core_move_notice.mjs

@@ -0,0 +1,356 @@
+// tests/core_move_notice.mjs — after the project's core moves, its own hall says so once,
+// with what changed, and Settings → Software update keeps a short history (task 1004731).
+//
+// The move writes one row to THIS project's own core_upgrades ledger (scripts/gds/upgrade.js);
+// the running core carries the release notes for every version up to itself
+// (release-notes.json). src/bongos/core-moves.js reads both back: GET /core-update carries
+// the one-time notice (`moved`) for the banner, GET /software-update the history. The
+// builder's "seen" is server-side, in the builder-settings module's behavior_prefs.
+//
+// Run:  node tests/core_move_notice.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { moveNotice, moveHistory, readInstalledReleaseNotes } = require('../src/bongos/core-moves.js');
+const seen = require('../modules/builder-settings/core-move-seen.js');
+
+let passed = 0;
+let failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+const NOW = Date.parse('2026-10-16T12:00:00.000Z');
+const NOTES = {
+  '1.21.20': [{ id: '1', text: 'Old work, already on the project.' }],
+  '1.21.21': [{ id: '1004700', text: 'The board shows who is reviewing.' }],
+  '1.21.22': [],
+  '1.21.23': [{ text: 'Settings remembers your filters.' }, { id: '1004702', text: 'Faster task pages.' }],
+  '1.21.24': [{ id: '9', text: 'Beyond this move.' }],
+};
+// The rows upgrade.js writes: a landed move, an automatic one, a door one, a rollback.
+const moved = (over = {}) => ({ id: '41', from_version: '1.21.20', to_version: '1.21.23', note: null, source: null,
+  applied_at: '2026-10-15T09:00:00.000Z', ...over });
+const rollback = { id: '40', from_version: '1.21.20', to_version: '1.21.22', source: null, applied_at: '2026-10-14T09:00:00.000Z',
+  note: 'rolled_back: migrate failed (attempted 1.21.20 → 1.21.22, restored 1.21.20)' };
+
+console.log('the notice after a core move, and the history of moves (task 1004731)');
+
+await t('a recorded move renders as a notice: version, date, and the release-note entries between old and new', () => {
+  const n = moveNotice({ rows: [moved()], running: '1.21.23', notes: NOTES, now: NOW });
+  assert.equal(n.id, '41');
+  assert.equal(n.version, '1.21.23');
+  assert.equal(n.from, '1.21.20');
+  assert.equal(n.message, 'Upgraded to core 1.21.23 on 15 October 2026.');
+  assert.deepEqual(n.entries.map((e) => e.text),
+    ['Settings remembers your filters.', 'Faster task pages.', 'The board shows who is reviewing.'],
+    'newest first, only the versions after the old one and up to the new one');
+  assert.equal(n.more, 0);
+});
+
+await t('an automatic move says so; a move by hand reads the same, without the word', () => {
+  assert.equal(moveNotice({ rows: [moved({ note: 'auto-subscription' })], running: '1.21.23', notes: NOTES, now: NOW }).message,
+    'Upgraded automatically to core 1.21.23 on 15 October 2026.');
+  const door = moveNotice({ rows: [moved({ source: 'owner-control' })], running: '1.21.23', notes: NOTES, now: NOW });
+  assert.equal(door.how, 'by_hand');
+  assert.equal(door.message, 'Upgraded to core 1.21.23 on 15 October 2026.');
+});
+
+await t('the notice clears once this builder has seen that move, and the next move is news again', () => {
+  assert.equal(moveNotice({ rows: [moved()], running: '1.21.23', notes: NOTES, seenId: '41', now: NOW }), null);
+  assert.ok(moveNotice({ rows: [moved({ id: '42' })], running: '1.21.23', notes: NOTES, seenId: '41', now: NOW }));
+});
+
+await t('no notice for a rollback, a version this server does not run, or a move months old', () => {
+  assert.equal(moveNotice({ rows: [rollback, moved()], running: '1.21.20', notes: NOTES, now: NOW }), null);
+  assert.equal(moveNotice({ rows: [moved()], running: '1.21.20', notes: NOTES, now: NOW }), null);
+  assert.equal(moveNotice({ rows: [moved()], running: '1.21.23', notes: NOTES, now: NOW + 40 * 86400000 }), null);
+  assert.equal(moveNotice({ rows: [], running: '1.21.23', notes: NOTES, now: NOW }), null);
+});
+
+await t('notes that cannot be read, or do not cover the move, still give the notice, with no entries', () => {
+  const none = moveNotice({ rows: [moved()], running: '1.21.23', notes: null, now: NOW });
+  assert.equal(none.entries, null);
+  assert.match(none.message, /1\.21\.23/);
+  assert.equal(moveNotice({ rows: [moved()], running: '1.21.23', notes: { '1.21.22': [] }, now: NOW }).entries, null);
+});
+
+await t('a long range shows a few entries and counts the rest', () => {
+  const many = { '1.21.20': [] };
+  for (let i = 21; i <= 30; i++) many[`1.21.${i}`] = [{ text: `Change ${i}.` }];
+  const n = moveNotice({ rows: [moved({ to_version: '1.21.30' })], running: '1.21.30', notes: many, now: NOW });
+  assert.equal(n.entries.length, 6);
+  assert.equal(n.more, 4);
+});
+
+await t('the history lists every move, newest first, failed ones included, with how and outcome', () => {
+  const h = moveHistory([moved({ note: 'auto-subscription' }), rollback,
+    { id: '39', from_version: '1.21.19', to_version: '1.21.20', source: 'owner-control', note: null, applied_at: '2026-10-10T09:00:00.000Z' },
+    { id: '38', from_version: '1.21.20', to_version: '1.21.19', source: null, note: 'downgrade (--allow-downgrade)', applied_at: '2026-10-09T09:00:00.000Z' }]);
+  assert.deepEqual(h.map((m) => [m.version, m.how, m.outcome]), [
+    ['1.21.23', 'automatic', 'upgraded'],
+    ['1.21.22', 'on_server', 'rolled_back'],
+    ['1.21.20', 'by_hand', 'upgraded'],
+    ['1.21.19', 'on_server', 'moved_back'],
+  ]);
+  assert.equal(h[0].at, '2026-10-15T09:00:00.000Z');
+  assert.equal(moveHistory(Array.from({ length: 20 }, (_, i) => moved({ id: String(i) }))).length, 8, 'a short history');
+});
+
+await t('the running core\'s own release notes are read from its package root; none is null, never a throw', () => {
+  const fake = { readFileSync: () => JSON.stringify(NOTES) };
+  assert.deepEqual(readInstalledReleaseNotes({ fsImpl: fake, root: '/x' }), NOTES);
+  assert.equal(readInstalledReleaseNotes({ fsImpl: { readFileSync: () => { throw new Error('ENOENT'); } }, root: '/x' }), null);
+});
+
+// ---- the per-builder seen state (builder-settings module) -------------------------------
+
+await t('seen is one ledger id per builder, kept beside the other prefs', () => {
+  assert.equal(seen.seenId({}), null);
+  assert.equal(seen.seenId(seen.applySeen({ wandering: 'low' }, '41')), '41');
+  assert.equal(seen.applySeen({ wandering: 'low' }, '41').wandering, 'low');
+  assert.equal(seen.validatePatch({ id: '41' }).id, '41');
+  assert.equal(seen.validatePatch({ id: 'x' }).ok, false);
+  assert.equal(seen.validatePatch({ id: '41', other: 1 }).ok, false);
+});
+
+await t('PATCH /me/core-move-seen stores it for the signed-in builder only, and the port reads it back', async () => {
+  const rows = new Map([[1, { wandering: 'low' }]]);
+  const db = require('../modules/builder-settings/db.js');
+  db.getBuilderBehaviorPrefs = async (id) => rows.get(id) || {};
+  db.setBuilderBehaviorPrefs = async (id, prefs) => { rows.set(id, prefs); return prefs; };
+  const router = require('../modules/builder-settings/routes/settings.js')();
+  const layer = router.stack.find((l) => l.route && l.route.path === '/me/core-move-seen' && l.route.methods.patch);
+  assert.ok(layer, 'PATCH /me/core-move-seen is registered');
+  const out = { status: 200, body: null };
+  const res = { status(s) { out.status = s; return this; }, json(b) { out.body = b; return this; },
+    fail(code, a, b) { out.status = typeof a === 'number' ? a : (a && a.status) || 400; out.body = { error: code, ...(b || {}) }; return this; } };
+  await layer.route.stack[layer.route.stack.length - 1].handle({ builder: { id: 1 }, body: { id: '41' } }, res);
+  assert.equal(out.status, 200);
+  assert.deepEqual(out.body, { ok: true, seen: '41' });
+  assert.equal(rows.get(1).wandering, 'low', 'sibling prefs survive');
+  assert.equal(rows.has(2), false);
+  const port = require('../modules/builder-settings/settings.js');
+  assert.equal(port.coreMoveSeen(rows.get(1)), '41');
+});
+
+// ---- the two reads the hall makes ------------------------------------------------------
+
+const { CORE_VERSION } = require('../src/module-api.js');
+const nowMove = (over = {}) => moved({ to_version: CORE_VERSION, from_version: '0.0.1', applied_at: new Date().toISOString(), ...over });
+
+async function drive(p, deps) {
+  const auth = require('../src/bongos/auth.js');
+  const saved = { b: auth.requireBuilder, p: auth.requirePermission };
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: '7' }; next(); };
+  auth.requirePermission = () => (_req, _res, next) => next();
+  const build = require('../src/bongos/routes/core-update.js');
+  const express = require('express');
+  const app = express();
+  try {
+    app.use(build({ askDeps: () => ({ hub: null, getSetting: async () => null }), canUpdate: async () => true,
+      doorInputs: () => ({ provisioning: false, idp: null, hubUpgradeUrl: null }), upgradeHold: async () => null,
+      releaseNotes: () => ({ '0.0.1': [], [CORE_VERSION]: [{ text: 'Shown after the move.' }] }), ...deps }));
+  } finally { auth.requireBuilder = saved.b; auth.requirePermission = saved.p; }
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}${p}`);
+    return { status: res.status, body: await res.json() };
+  } finally { server.close(); }
+}
+
+await t('GET /core-update carries the notice for this builder, and none once they have seen it', async () => {
+  const r = await drive('/core-update', {
+    coreUpdate: async () => ({ reading: 'ok', behind: false }), selfChannel: async () => null,
+    upgrades: async () => [nowMove()], seenMove: async () => ({ remember: 'server', seen: null }),
+  });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.moved.version, CORE_VERSION);
+  assert.equal(r.body.moved.remember, 'server');
+  assert.deepEqual(r.body.moved.entries.map((e) => e.text), ['Shown after the move.']);
+  const after = await drive('/core-update', {
+    coreUpdate: async () => ({ reading: 'ok', behind: false }), selfChannel: async () => null,
+    upgrades: async () => [nowMove()], seenMove: async () => ({ remember: 'server', seen: '41' }),
+  });
+  assert.equal(after.body.moved, null);
+});
+
+await t('a ledger that cannot be read is no notice, never a failed banner read', async () => {
+  const r = await drive('/core-update', { coreUpdate: async () => ({ reading: 'ok', behind: false }), selfChannel: async () => null,
+    upgrades: async () => { throw new Error('no table'); }, seenMove: async () => ({ remember: 'server', seen: null }) });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.moved, null);
+});
+
+await t('GET /software-update carries the history for those who may update, and not for anyone else', async () => {
+  const deps = { softwareUpdate: async ({ running }) => ({ reading: 'ok', running, offered: null }),
+    upgrades: async () => [nowMove({ note: 'auto-subscription' }), rollback] };
+  const r = await drive('/software-update', deps);
+  assert.deepEqual(r.body.history.map((m) => [m.how, m.outcome]), [['automatic', 'upgraded'], ['on_server', 'rolled_back']]);
+  const other = await drive('/software-update', { ...deps, canUpdate: async () => false });
+  assert.equal(other.body.history, null, 'when and to what the core moved is a vulnerability-window fact (ADR 0043)');
+});
+
+// ---- the hall draws the notice, and it clears after it is seen --------------------------
+
+const SHELL = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
+// shell.js loads the notice's own file only when there is a notice; the fake <head> runs it.
+const NOTICE = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/core-move-notice.js'), 'utf8');
+
+function boot({ data, permissions = { 'core.pin.move': true }, stored = {} } = {}) {
+  const inserted = [];
+  const requested = [];
+  const loaded = [];
+  const els = new Map();
+  let sandbox = null;
+  const makeEl = () => ({
+    dataset: {}, style: {}, textContent: '', hidden: false, _html: '', _on: {},
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; }, removeAttribute() {},
+    addEventListener(ev, fn) { this._on[ev] = fn; },
+    querySelector(sel) { const self = this; return { addEventListener: (e, f) => { (self._q ||= {})[sel] = f; } }; },
+    querySelectorAll() { return []; },
+    appendChild() {}, focus() {}, click() {}, scrollIntoView() {}, remove() { this._removed = true; },
+    insertAdjacentElement(_pos, el) { inserted.push(el); },
+    set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; },
+  });
+  const documentObj = {
+    body: { dataset: { page: 'index' } },
+    documentElement: { dataset: {}, style: {}, classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } } },
+    getElementById(id) { if (!els.has(id)) els.set(id, makeEl()); return els.get(id); },
+    querySelectorAll() { return []; }, createElement() { return makeEl(); },
+    addEventListener() {}, dispatchEvent() {}, get cookie() { return ''; }, set cookie(_v) {},
+    head: { appendChild(tag) { loaded.push(tag.src); vm.runInContext(NOTICE, sandbox, { filename: 'core-move-notice.js' }); tag.onload(); } },
+  };
+  const location = { hostname: 'h', origin: 'https://h', pathname: '/', hash: '', assign() {}, replace() {} };
+  const windowObj = {
+    __BRANDING__: {}, __MODULES__: { enabled: { provisioning: false } },
+    BongosClient: { createClient: () => ({ request: (method, p, opts) => {
+      requested.push({ method, p, body: opts && opts.body });
+      if (p === '/api/bongos/core-update') return Promise.resolve({ status: 200, data });
+      if (p === '/api/bongos/me/core-move-seen') return Promise.resolve({ status: 200, ok: true, data: { ok: true } });
+      return new Promise(() => {});
+    } }) },
+    matchMedia: () => ({ matches: false, addEventListener() {} }),
+    localStorage: { getItem: (k) => (k in stored ? stored[k] : null), setItem: (k, v) => { stored[k] = v; } },
+    requestAnimationFrame() {}, scrollTo() {}, location, addEventListener() {},
+  };
+  sandbox = { window: windowObj, document: documentObj, location, console, setTimeout, clearTimeout, queueMicrotask,
+    CustomEvent: class { constructor(tp, i) { this.type = tp; Object.assign(this, i); } } };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(SHELL, sandbox, { filename: 'shell.js' });
+  windowObj.OTBShell.applyAccess({ authed: true, rank: 'archon', permissions });
+  return { inserted, requested, stored, loaded, notice: () => inserted.find((e) => String(e._html).includes('core-move-notice__list') || String(e._html).includes('Upgraded')) };
+}
+const settle = async () => { for (let i = 0; i < 5; i++) await new Promise((r) => setTimeout(r, 0)); };
+
+const recorded = moveNotice({ rows: [moved({ note: 'auto-subscription' })], running: '1.21.23', notes: NOTES, now: NOW });
+
+await t('the hall renders the notice from a recorded move, with its release-note entries', async () => {
+  const b = boot({ data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: { ...recorded, remember: 'server' } } });
+  await settle();
+  const el = b.notice();
+  assert.ok(el, 'the notice is drawn');
+  assert.match(el.innerHTML, /Upgraded automatically to core 1\.21\.23 on 15 October 2026\./);
+  assert.match(el.innerHTML, /Settings remembers your filters\./);
+  assert.match(el.innerHTML, /Faster task pages\./);
+  assert.match(el.innerHTML, /href="\/settings#software-update"/);
+  assert.equal(b.loaded.length, 1, 'its file is loaded once, only because there is a notice');
+  assert.match(b.loaded[0], /^\/builders\/core-move-notice\.js/);
+});
+
+await t('no notice, no extra file: a page with nothing to say loads nothing', async () => {
+  const b = boot({ data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: null } });
+  await settle();
+  assert.equal(b.loaded.length, 0);
+  assert.equal(b.notice(), undefined);
+});
+
+await t('the notice clears once seen: closing it tells the server, for this move, and removes it', async () => {
+  const b = boot({ data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: { ...recorded, remember: 'server' } } });
+  await settle();
+  const el = b.notice();
+  el._q['.core-move-notice__close']();
+  await settle();
+  assert.equal(el._removed, true);
+  const patch = b.requested.find((r) => r.method === 'PATCH');
+  assert.equal(patch && patch.p, '/api/bongos/me/core-move-seen');
+  assert.equal(JSON.stringify(patch.body), JSON.stringify({ id: '41' }));
+  // The next page load: the server answers moved:null for this builder.
+  const next = boot({ data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: null } });
+  await settle();
+  assert.equal(next.notice(), undefined);
+});
+
+await t('without the server-side store the browser remembers it instead', async () => {
+  const stored = {};
+  const b = boot({ stored, data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: { ...recorded, remember: 'browser' } } });
+  await settle();
+  b.notice()._q['.core-move-notice__close']();
+  await settle();
+  assert.equal(stored['bongos.coreMove.seen'], '41');
+  assert.ok(!b.requested.some((r) => r.method === 'PATCH'));
+  const again = boot({ stored, data: { ok: true, update: { reading: 'ok', behind: false }, held: null, moved: { ...recorded, remember: 'browser' } } });
+  await settle();
+  assert.equal(again.notice(), undefined);
+});
+
+// ---- Settings → Software update draws the history ---------------------------------------
+
+const PANEL_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-software-update.js'), 'utf8');
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+async function panel(data) {
+  const el = () => ({ hidden: true, textContent: '', _html: '', dataset: {}, set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; }, querySelectorAll: () => [] });
+  const els = new Map([['software-update-scroll', el()], ['su-body', el()], ['su-note', el()], ['settings-groups', el()]]);
+  els.get('settings-groups').dataset.active = 'update';
+  const windowObj = { BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) }, OTB: { escapeHtml }, location: { assign() {} } };
+  const sandbox = { window: windowObj, document: { getElementById: (id) => els.get(id) || null, addEventListener() {} }, console, setTimeout, Date, Math, URL, Promise, String, Number };
+  vm.createContext(sandbox);
+  vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });
+  for (let i = 0; i < 10; i++) await new Promise((r) => setTimeout(r, 0));
+  return els.get('su-body').innerHTML;
+}
+
+await t('Settings → Software update lists the moves: version, date, automatic or by hand, outcome', async () => {
+  const history = moveHistory([moved({ note: 'auto-subscription' }), rollback,
+    { id: '39', from_version: '1.21.19', to_version: '1.21.20', source: 'owner-control', note: null, applied_at: '2026-10-10T09:00:00.000Z' }]);
+  const html = await panel({ ok: true, update: { reading: 'ok', running: '1.21.23', offered: null }, door: { kind: 'cli' }, can_update: true, ask: {}, held: null, history });
+  assert.match(html, /Recent updates/);
+  assert.match(html, /1\.21\.23/);
+  assert.match(html, /15 October 2026/);
+  assert.match(html, /Automatic/);
+  assert.match(html, /By hand/);
+  assert.match(html, /Rolled back/);
+  assert.match(html, /Installed/);
+  assert.doesNotMatch(html.slice(html.indexOf('Recent updates')), /[—–]/, 'voice rule: no dashes in new copy');
+});
+
+await t('no history, no change: the panel draws exactly what it did before', async () => {
+  const data = { ok: true, update: { reading: 'ok', running: '1.21.20', offered: '1.21.116', whats_new: null }, door: { kind: 'cli', url: null }, can_update: true, ask: {}, held: null };
+  assert.equal(await panel({ ...data, history: null }), await panel(data));
+  assert.equal(await panel({ ...data, history: [] }), await panel(data));
+});
+
+// ---- the hub's automatic move marks itself in the project's ledger -------------------------
+
+await t('the hub\'s automatic move passes the auto-subscription note; a door move and a preview do not', () => {
+  const R = require('../scripts/gds/provision-core-upgrade.js');
+  const box = { slug: 'toast', port: 4100, hosting_shape: 'cloud-host' };
+  const as = { runAs: 'bongos', migrateAs: 'bongos' };
+  assert.match(R.upgradeInvocation(box, '1.21.23', { ...as, automatic: true }).cmd, / --note auto-subscription(\s|$)/);
+  assert.doesNotMatch(R.upgradeInvocation(box, '1.21.23', { ...as, requestedBy: '42' }).cmd, /--note/);
+  assert.doesNotMatch(R.upgradeInvocation(box, '1.21.23', { ...as, automatic: true, dryRun: true }).cmd, /--note/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/core_origin_follow.mjs

@@ -0,0 +1,287 @@
+// tests/core_origin_follow.mjs — the laptop picks up a core move the hub made (task 1004732)
+//
+// The bug: when the hub moves a hosted project's core it commits the new pin on the box
+// and pushes it to the project's GitHub repo. The owner's laptop checkout never heard of
+// it, so the next session and the next ship ran — and merged against — the old pin.
+//
+// Each case is a REAL temp git setup: a bare "GitHub" origin, a "box" clone that makes
+// the hub's pin commit and pushes it, and a "laptop" clone that is the checkout under
+// test. npm is stubbed (it lays down a fake installed core); git is real.
+//
+// Run:  node tests/core_origin_follow.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const follow = require('../scripts/gds/core-origin-follow.js');
+const pinSync = require('../scripts/gds/core-pin-sync.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+function git(cwd, ...args) {
+  const r = spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...args], { cwd, encoding: 'utf8' });
+  assert.equal(r.status, 0, `git ${args.join(' ')}: ${r.stderr}`);
+  return r.stdout;
+}
+
+const OLD = '1.21.20';
+const NEW = '1.21.115';
+
+function writePin(dir, spec, version) {
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'toast', private: true, dependencies: { '@bongos/core': spec } }, null, 2) + '\n');
+  fs.writeFileSync(path.join(dir, 'package-lock.json'), JSON.stringify({
+    name: 'toast', lockfileVersion: 3,
+    packages: { 'node_modules/@bongos/core': { version, resolved: spec.startsWith('file:') ? spec : `https://registry.npmjs.org/@bongos/core/-/core-${version}.tgz` } },
+  }, null, 2) + '\n');
+}
+
+// A fake installed core in `root`: what npm would leave behind.
+function installCore(root, version) {
+  const core = path.join(root, 'node_modules', '@bongos', 'core');
+  fs.rmSync(path.join(root, 'node_modules'), { recursive: true, force: true });
+  fs.mkdirSync(path.join(core, 'bin'), { recursive: true });
+  fs.mkdirSync(path.join(core, 'scripts', 'gds'), { recursive: true });
+  fs.writeFileSync(path.join(core, 'package.json'), JSON.stringify({ name: '@bongos/core', version }));
+  fs.writeFileSync(path.join(core, 'bin', 'bongos.js'), '');
+  fs.writeFileSync(path.join(core, 'scripts', 'gds', 'fitness.js'), '');
+  return core;
+}
+
+// origin (bare) ← box pushes the hub's move; laptop is a clone made BEFORE the move.
+// `move` makes the hub's commit: vendored tgz pin → exact registry pin, tgz removed.
+function setup({ move = true, alsoOnBox = null } = {}) {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'core-origin-follow-'));
+  const origin = path.join(base, 'origin.git');
+  const box = path.join(base, 'box');
+  const laptop = path.join(base, 'laptop');
+  git(base, 'init', '-q', '--bare', '-b', 'main', origin);
+  fs.mkdirSync(box);
+  git(box, 'init', '-q', '-b', 'main');
+  writePin(box, `file:vendor/bongos-core-${OLD}.tgz`, OLD);
+  fs.mkdirSync(path.join(box, 'vendor'));
+  fs.writeFileSync(path.join(box, 'vendor', `bongos-core-${OLD}.tgz`), 'old-tarball');
+  fs.writeFileSync(path.join(box, '.gitignore'), 'node_modules/\n');
+  git(box, 'add', '-A');
+  git(box, 'commit', '-qm', 'init: vendored core');
+  git(box, 'remote', 'add', 'origin', origin);
+  git(box, 'push', '-q', 'origin', 'main');
+  git(base, 'clone', '-q', origin, laptop);
+  // The laptop has the old core installed and the untracked, excluded scripts link.
+  installCore(laptop, OLD);
+  fs.symlinkSync(path.join(laptop, 'node_modules', '@bongos', 'core', 'scripts'), path.join(laptop, 'scripts'), 'junction');
+  fs.appendFileSync(path.join(laptop, '.git', 'info', 'exclude'), 'scripts\n');
+  if (move) {
+    writePin(box, NEW, NEW);
+    git(box, 'rm', '-q', `vendor/bongos-core-${OLD}.tgz`);
+    if (alsoOnBox) alsoOnBox(box);
+    git(box, 'add', '-A');
+    git(box, 'commit', '-qm', `core: upgrade @bongos/core to ${NEW}`);
+    git(box, 'push', '-q', 'origin', 'main');
+  }
+  // The core the laptop runs (node_modules/@bongos/core) — the dispatcher's REPO_ROOT.
+  const coreRoot = path.join(laptop, 'node_modules', '@bongos', 'core');
+  return { base, origin, box, laptop, coreRoot };
+}
+
+// git → real; npm → lay down the pinned core; the re-run of bongos → recorded.
+function stubRun(root) {
+  const calls = { installs: [], reruns: [], git: 0 };
+  const run = (cmd, args, opts) => {
+    if (cmd === 'git') { calls.git++; return spawnSync(cmd, args, opts); }
+    if (cmd === 'npm' || String(args[0] || '').endsWith('npm-cli.js')) {
+      calls.installs.push(cmd === 'npm' ? args : args.slice(1));
+      const lock = JSON.parse(fs.readFileSync(path.join(root, 'package-lock.json'), 'utf8'));
+      installCore(root, lock.packages['node_modules/@bongos/core'].version);
+      return { status: 0 };
+    }
+    if (String(args[0] || '').endsWith('bongos.js')) { calls.reruns.push(args.slice(1)); return { status: 0 }; }
+    return { status: 1 };
+  };
+  return { run, calls };
+}
+
+const pinOf = (dir) => JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'];
+const head = (dir) => git(dir, 'rev-parse', 'HEAD').trim();
+
+test('clean main: says the project moved, fast-forwards, reinstalls, re-runs, scripts link resolves', () => {
+  const { laptop, coreRoot } = setup();
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  const code = follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s), npmCli: null });
+  assert.equal(code, 0, 'the re-run exit code: ' + logs.join('\n'));
+  assert.ok(logs.some((l) => l.includes(`upgraded to core ${NEW} on GitHub`) && l.includes(OLD)), logs.join('\n'));
+  assert.equal(pinOf(laptop), NEW, 'fast-forwarded onto the hub commit');
+  assert.equal(calls.installs.length, 1, 'npm ran once');
+  assert.equal(calls.installs[0][0], 'ci');
+  assert.deepEqual(calls.reruns, [['start']], 'start re-ran under the new core');
+  assert.ok(fs.existsSync(path.join(laptop, 'scripts', 'gds', 'fitness.js')), 'the scripts link still resolves');
+  const installed = JSON.parse(fs.readFileSync(path.join(laptop, 'node_modules', '@bongos', 'core', 'package.json'), 'utf8'));
+  assert.equal(installed.version, NEW);
+});
+
+test('vendored → registry pin: no tgz left referenced after the follow', () => {
+  const { laptop, coreRoot } = setup();
+  const { run } = stubRun(laptop);
+  follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'ship', '7'], verb: 'ship', cwd: laptop, env: {}, run, log: () => {}, npmCli: null });
+  assert.equal(pinOf(laptop), NEW);
+  for (const f of ['package.json', 'package-lock.json']) {
+    assert.ok(!/bongos-core-[\d.]+\.tgz/.test(fs.readFileSync(path.join(laptop, f), 'utf8')), `${f} still names a tarball`);
+  }
+  assert.ok(!fs.existsSync(path.join(laptop, 'vendor', `bongos-core-${OLD}.tgz`)), 'the hub removed the old tarball; the follow carried that');
+});
+
+test('dirty tree: reports the move only — no fast-forward, no install', () => {
+  const { laptop, coreRoot } = setup();
+  fs.writeFileSync(path.join(laptop, '.gitignore'), 'node_modules/\nlocal-edit\n');
+  const before = head(laptop);
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  const code = follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s), npmCli: null });
+  assert.equal(code, null, 'carry on with the command');
+  assert.ok(logs.some((l) => l.includes(`upgraded to core ${NEW} on GitHub`)), logs.join('\n'));
+  assert.ok(logs.some((l) => /uncommitted/.test(l)), 'says why it was not applied: ' + logs.join('\n'));
+  assert.equal(head(laptop), before);
+  assert.equal(pinOf(laptop), `file:vendor/bongos-core-${OLD}.tgz`);
+  assert.equal(calls.installs.length, 0);
+  assert.match(fs.readFileSync(path.join(laptop, '.gitignore'), 'utf8'), /local-edit/, 'the edit is untouched');
+});
+
+test('feature branch: reports only, never moves the branch', () => {
+  const { laptop, coreRoot } = setup();
+  git(laptop, 'checkout', '-qb', 'task-49');
+  const before = head(laptop);
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  const r = follow.followOriginPin({ coreRoot, cwd: laptop, env: {}, run, log: (s) => logs.push(s) });
+  assert.equal(r.action, 'reported');
+  assert.ok(logs.some((l) => l.includes('task-49')), logs.join('\n'));
+  assert.equal(head(laptop), before);
+  assert.equal(calls.installs.length, 0);
+});
+
+// The fast-forward installs and RUNS what it brings in, so only the hub's pin-only commit
+// shape onto a published release is applied unattended; anything wider is reported.
+function expectReportedOnly(alsoOnBox, why) {
+  const { laptop, coreRoot } = setup({ alsoOnBox });
+  const before = head(laptop);
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  const code = follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s), npmCli: null });
+  assert.equal(code, null);
+  assert.ok(logs.some((l) => l.includes('upgraded to core') ), logs.join('\n'));
+  assert.ok(logs.some((l) => why.test(l)), `names why (${why}): ` + logs.join('\n'));
+  assert.equal(head(laptop), before, 'not fast-forwarded');
+  assert.equal(calls.installs.length, 0, 'nothing installed');
+}
+
+test('a move that carries other code too is reported, never applied', () => {
+  expectReportedOnly((box) => fs.writeFileSync(path.join(box, 'postinstall.js'), 'evil()'), /other changes besides the core move/);
+});
+
+test('a move whose package.json changes more than the core pin is reported, never applied', () => {
+  expectReportedOnly((box) => {
+    const p = JSON.parse(fs.readFileSync(path.join(box, 'package.json'), 'utf8'));
+    p.scripts = { prestart: 'evil' };
+    fs.writeFileSync(path.join(box, 'package.json'), JSON.stringify(p, null, 2) + '\n');
+  }, /package\.json changed beyond the core pin/);
+});
+
+test('a move onto a tarball from GitHub (not a published release) is reported, never applied', () => {
+  // the pin alone names a tarball (the spec gate) …
+  expectReportedOnly((box) => writePin(box, `file:vendor/bongos-core-${NEW}.tgz`, NEW), /not a published release/);
+  // … and a tarball file brought in with it is caught by the file gate first
+  expectReportedOnly((box) => {
+    writePin(box, `file:vendor/bongos-core-${NEW}.tgz`, NEW);
+    fs.mkdirSync(path.join(box, 'vendor'), { recursive: true });
+    fs.writeFileSync(path.join(box, 'vendor', `bongos-core-${NEW}.tgz`), 'unreleased');
+  }, /other changes besides the core move/);
+});
+
+test('a lockfile that resolves from outside the public registry is reported, never applied', () => {
+  expectReportedOnly((box) => {
+    const lock = JSON.parse(fs.readFileSync(path.join(box, 'package-lock.json'), 'utf8'));
+    lock.packages['node_modules/left-pad'] = { version: '1.0.0', resolved: 'https://evil.example/left-pad.tgz' };
+    fs.writeFileSync(path.join(box, 'package-lock.json'), JSON.stringify(lock, null, 2) + '\n');
+  }, /source outside the public registry/);
+});
+
+test('the core repo itself: a no-op, without a single git spawn', () => {
+  const { laptop } = setup();
+  const coreRepo = fs.mkdtempSync(path.join(os.tmpdir(), 'core-origin-follow-core-'));
+  fs.writeFileSync(path.join(coreRepo, 'package.json'), JSON.stringify({ name: 'cloud-bongos', version: '0.0.2' }));
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  assert.equal(follow.ensureCurrentCore({ coreRoot: coreRepo, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s) }), null);
+  assert.equal(calls.git, 0);
+  assert.deepEqual(logs, []);
+});
+
+test('origin unreadable: silent no-op', () => {
+  const { laptop, coreRoot, origin } = setup();
+  // Drop the remote-tracking ref and point origin at nothing: the fetch fails and there is no origin/main.
+  git(laptop, 'update-ref', '-d', 'refs/remotes/origin/main');
+  git(laptop, 'remote', 'set-url', 'origin', origin + '-gone');
+  const before = head(laptop);
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  assert.equal(follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s) }), null);
+  assert.deepEqual(logs, [], 'nothing said');
+  assert.equal(head(laptop), before);
+  assert.equal(calls.installs.length, 0);
+});
+
+test('no move on origin: silent, and start pays no install', () => {
+  const { laptop, coreRoot } = setup({ move: false });
+  const { run, calls } = stubRun(laptop);
+  const logs = [];
+  assert.equal(follow.ensureCurrentCore({ coreRoot, argv: ['node', 'bongos', 'start'], verb: 'start', cwd: laptop, env: {}, run, log: (s) => logs.push(s) }), null);
+  assert.deepEqual(logs, []);
+  assert.equal(calls.installs.length, 0);
+});
+
+test('a pin the LAPTOP moved (not pushed yet) is not reported as a hub move', () => {
+  const { laptop, coreRoot } = setup({ move: false });
+  writePin(laptop, '1.21.99', '1.21.99');
+  git(laptop, 'commit', '-qam', 'local pin bump');
+  const { run } = stubRun(laptop);
+  const logs = [];
+  const r = follow.followOriginPin({ coreRoot, cwd: laptop, env: {}, run, log: (s) => logs.push(s) });
+  assert.equal(r.action, 'none');
+  assert.deepEqual(logs, []);
+});
+
+test('a scripts link left dangling after the install is re-pointed at the installed core', () => {
+  const { laptop } = setup({ move: false });
+  const link = path.join(laptop, 'scripts');
+  fs.rmSync(link, { force: true, recursive: false });
+  const gone = path.join(laptop, 'old-core-scripts');
+  fs.mkdirSync(gone);
+  fs.symlinkSync(gone, link, 'junction');
+  fs.rmSync(gone, { recursive: true });
+  const logs = [];
+  assert.equal(pinSync.healScriptsLink(laptop, { log: (s) => logs.push(s) }), 'repointed');
+  assert.ok(fs.existsSync(path.join(link, 'gds', 'fitness.js')));
+  // a real scripts/ directory (the core repo shape) is never touched
+  const real = fs.mkdtempSync(path.join(os.tmpdir(), 'core-origin-follow-real-'));
+  fs.mkdirSync(path.join(real, 'scripts'));
+  assert.equal(pinSync.healScriptsLink(real, { log: () => {} }), 'not-a-link');
+});
+
+test('the dispatcher runs the follow before ship and start', () => {
+  const src = fs.readFileSync(new URL('../bin/bongos.js', import.meta.url), 'utf8');
+  assert.match(src, /verb === 'ship' \|\| verb === 'start'/);
+  assert.match(src, /require\('\.\.\/scripts\/gds\/core-origin-follow\.js'\)\.ensureCurrentCore/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);