@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/core-origin-follow.js

@@ -0,0 +1,185 @@
+// scripts/bongos/core-origin-follow.js — the laptop follows a core move the hub made (task 1004732)
+//
+// WHY. When the hub moves a hosted project's core (provision-core-upgrade.js), it commits
+// the new pin — package.json + lockfile, usually a vendored `file:vendor/bongos-core-X.tgz`
+// rewritten to an exact registry version — on the box and pushes it to the project's
+// GitHub repo. The owner's laptop checkout never hears of it: the next session runs the
+// old core, and the next ship merges against the old pin. Seen on toast (1.21.20 on the
+// laptop while fixes sat in newer releases).
+//
+// THE FIX. Before `bongos start` (an instance's session start: its CLAUDE.md opens every
+// session with it, and a package-installed instance carries no SessionStart hooks) and
+// before `bongos ship`, the dispatcher calls ensureCurrentCore(). It fetches origin/main
+// (bounded; allowed to fail) and compares the checkout's @bongos/core pin with
+// origin/main's. When ORIGIN moved it, the builder gets one plain line saying so. On a
+// clean `main` with no local commits, the checkout is fast-forwarded and the pinned core
+// is installed through core-pin-sync.js (task 1004632) — whose gates (the pin's shape,
+// and the pin having landed on main) still decide what may be installed — then the
+// command re-runs under the new core. A dirty tree, a feature branch or local commits get
+// the line and the command to run, never a forced change. So does a move that is not
+// pin-only (notPinOnly): the fast-forward installs and runs what it brings in, so it is
+// taken only for the hub's commit shape — the pin, the lockfile, a removed tarball — onto
+// a published registry release; anything wider waits for the owner to look.
+//
+// Silent and fail-open: in the core repo itself (the running package is not
+// @bongos/core) it returns before any git spawn; outside git, with no pin, when origin
+// cannot be read, or when the pins already agree it says nothing. A pin the LOCAL side
+// moved (origin's pin is still the one this branch forked from) is not a hub move.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const pinSync = require('./core-pin-sync.js');
+
+const FETCH_TIMEOUT_MS = 5000;
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(String(fsImpl.readFileSync(file, 'utf8')).replace(/^/, '')); } catch { return null; }
+}
+
+function gitOut(args, cwd, run, extra = {}) {
+  try {
+    const r = run('git', args, { cwd, encoding: 'utf8', ...extra });
+    return r && r.status === 0 ? String(r.stdout || '').trim() : null;
+  } catch { return null; }
+}
+
+function specOf(pkg) {
+  if (!pkg) return null;
+  return (pkg.dependencies || {})[pinSync.CORE_PKG] || (pkg.devDependencies || {})[pinSync.CORE_PKG] || null;
+}
+
+// The core pin package.json carries at `rev`, or null when that file cannot be read there.
+function specAt(root, rev, run) {
+  const body = gitOut(['show', `${rev}:package.json`], root, run, { maxBuffer: 8 * 1024 * 1024 });
+  if (body == null) return null;
+  try { return specOf(JSON.parse(body.replace(/^/, ''))); } catch { return null; }
+}
+
+const shown = (spec) => pinSync.versionFromSpec(spec) || spec;
+
+// Why the move cannot be applied to this checkout automatically, or null when it can.
+function blockedReason({ branch, dirty, ahead }) {
+  if (!branch) return 'this checkout is not on a branch';
+  if (branch !== 'main') return `you are on branch ${branch}, which picks the move up when it merges main`;
+  if (dirty == null || dirty !== '') return 'this checkout has uncommitted changes';
+  if (!Number.isFinite(ahead) || ahead !== 0) return 'main has local commits GitHub does not have';
+  return null;
+}
+
+const REMEDY = 'On a clean main: `git pull --ff-only origin main`, then `npm ci`.';
+const REVIEW_REMEDY = 'Review what GitHub has (`git log HEAD..origin/main`), then `git pull --ff-only origin main` and `npm ci`.';
+const REGISTRY = 'https://registry.npmjs.org/';
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$/;
+
+function jsonAt(root, rev, file, run) {
+  const body = gitOut(['show', `${rev}:${file}`], root, run, { maxBuffer: 64 * 1024 * 1024 });
+  if (body == null) return null;
+  try { return JSON.parse(body.replace(/^/, '')); } catch { return null; }
+}
+
+// The fast-forward installs and then RUNS what it brings in, unattended — so it is taken
+// only when what GitHub has is the hub's pin move and nothing else (the shape
+// provision-core-upgrade.js pushes). Anything wider is reported, never applied. Returns
+// null when the move is pin-only, else the reason it is not.
+//   - the only files that differ are package.json, package-lock.json and a removed
+//     vendored tarball;
+//   - package.json differs ONLY in the @bongos/core spec;
+//   - the new spec is an exact version, i.e. a published release (a tarball brought in
+//     from GitHub is code nobody released);
+//   - the lockfile pins that version from the public registry, and every lockfile
+//     source it adds is the public registry too.
+function notPinOnly(root, run) {
+  const diff = gitOut(['diff', '--name-status', '--no-renames', 'HEAD', 'origin/main'], root, run, { maxBuffer: 16 * 1024 * 1024 });
+  if (diff == null) return 'the change on GitHub could not be read';
+  for (const line of diff.split('\n').filter(Boolean)) {
+    const [status, file] = line.split('\t');
+    const ok = file === 'package.json' || file === 'package-lock.json' ||
+      (status === 'D' && /^vendor\/bongos-core-[^/]+\.tgz$/.test(file));
+    if (!ok) return 'GitHub has other changes besides the core move';
+  }
+  const before = jsonAt(root, 'HEAD', 'package.json', run);
+  const after = jsonAt(root, 'origin/main', 'package.json', run);
+  if (!before || !after) return 'package.json could not be read';
+  const spec = specOf(after);
+  const strip = (pkg) => {
+    const c = JSON.parse(JSON.stringify(pkg));
+    for (const k of ['dependencies', 'devDependencies']) if (c[k]) delete c[k][pinSync.CORE_PKG];
+    return JSON.stringify(c);
+  };
+  if (strip(before) !== strip(after)) return 'package.json changed beyond the core pin';
+  if (!EXACT_SEMVER.test(String(spec || ''))) return 'the new pin is not a published release';
+  const lock = jsonAt(root, 'origin/main', 'package-lock.json', run);
+  const entry = lock && lock.packages && lock.packages[`node_modules/${pinSync.CORE_PKG}`];
+  if (!entry || entry.version !== spec || !String(entry.resolved || '').startsWith(`${REGISTRY}${pinSync.CORE_PKG}/-/`)) {
+    return 'the lockfile does not pin that release from the public registry';
+  }
+  const prior = new Set(Object.values(((jsonAt(root, 'HEAD', 'package-lock.json', run) || {}).packages) || {}).map((p) => p && p.resolved));
+  for (const p of Object.values(lock.packages)) {
+    const r = p && p.resolved;
+    if (r && !prior.has(r) && !String(r).startsWith(REGISTRY)) return 'the lockfile adds a source outside the public registry';
+  }
+  return null;
+}
+
+// Returns { action: 'none' | 'reported' | 'fast-forwarded', reason, from?, to? }.
+function followOriginPin({ coreRoot, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, fetchTimeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const none = (reason) => ({ action: 'none', reason });
+  if (env && (env.BONGOS_SKIP_CORE_SYNC || env[pinSync.SYNCED_ENV])) return none('skipped');
+  const running = readJson(path.join(coreRoot, 'package.json'), fsImpl);
+  if (!running || running.name !== pinSync.CORE_PKG) return none('core-repo'); // no git spawn
+  const top = gitOut(['rev-parse', '--show-toplevel'], cwd, run);
+  if (!top) return none('no-git');
+  const root = path.resolve(top);
+  const local = specOf(readJson(path.join(root, 'package.json'), fsImpl));
+  if (!local) return none('no-pin');
+
+  // Bounded, quiet, never prompts; a failure is fine — the ref below decides.
+  gitOut(['fetch', '--quiet', 'origin', 'main'], root, run, {
+    timeout: fetchTimeoutMs, env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  const origin = specAt(root, 'origin/main', run);
+  if (!origin) return none('origin-unreadable');
+  if (origin === local) return none('in-step');
+  const forkPoint = gitOut(['merge-base', 'HEAD', 'origin/main'], root, run);
+  if (forkPoint && specAt(root, forkPoint, run) === origin) return none('local-change');
+
+  const say = log || ((s) => process.stderr.write(s + '\n'));
+  const move = { from: local, to: origin };
+  say(`bongos: this project was upgraded to core ${shown(origin)} on GitHub (this checkout has ${shown(local)}).`);
+  const why = blockedReason({
+    branch: gitOut(['symbolic-ref', '--short', '-q', 'HEAD'], root, run),
+    dirty: gitOut(['status', '--porcelain', '--untracked-files=no'], root, run),
+    ahead: Number(gitOut(['rev-list', '--count', 'origin/main..HEAD'], root, run)),
+  });
+  if (why) {
+    say(`  Not updated here: ${why}. ${REMEDY}`);
+    return { action: 'reported', reason: why, ...move };
+  }
+  const wider = notPinOnly(root, run);
+  if (wider) {
+    say(`  Not updated automatically: ${wider}. ${REVIEW_REMEDY}`);
+    return { action: 'reported', reason: wider, ...move };
+  }
+  if (gitOut(['merge', '--ff-only', '--quiet', 'origin/main'], root, run) == null) {
+    say(`  The fast-forward did not go through. ${REMEDY}`);
+    return { action: 'reported', reason: 'ff-failed', ...move };
+  }
+  say('  Fast-forwarded this checkout to it; installing that core next.');
+  return { action: 'fast-forwarded', reason: 'origin-moved', ...move };
+}
+
+// The dispatcher's one call, for `ship` and `start`. Returns an exit code when it handled
+// the command (installed and re-ran, or refused), or null to run the verb as it is.
+// `ship` always checks the running core against the pin (task 1004632); `start` only
+// after a fast-forward actually moved the pin, so a normal session start pays no more
+// than the fetch.
+function ensureCurrentCore({ coreRoot, argv, verb, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, npmCli } = {}) {
+  const followed = followOriginPin({ coreRoot, cwd, env, run, fsImpl, log });
+  if (verb !== 'ship' && followed.action !== 'fast-forwarded') return null;
+  return pinSync.ensurePinnedCore({ coreRoot, argv, cwd, env, run, fsImpl, log, ...(npmCli !== undefined ? { npmCli } : {}) });
+}
+
+module.exports = { followOriginPin, ensureCurrentCore };

package/scripts/bongos/core-pin-sync.js

@@ -0,0 +1,260 @@
+// scripts/bongos/core-pin-sync.js — make `bongos ship` run the core the checkout PINS (task 1004632)
+//
+// WHY. An instance's task worktrees (`.claude/worktrees/task-N`) have no `node_modules`
+// of their own: Node and `npx` walk up to the MAIN checkout's, and so does every
+// `bongos ship`. After a core-update task lands, the next task's branch pins the new
+// core in package.json — but its worktree still resolves the main checkout's install,
+// which is whatever version was there before. On the owner's project that meant a
+// ship ran 1.21.20 against a branch pinned to 1.21.71 and failed on a bug 1.21.71 had
+// already fixed; the AI had to `npm ci` by hand in both places.
+//
+// THE FIX. Before `bongos ship` runs, the dispatcher asks `planCoreSync()` whether the
+// core it is running is the one the checkout it stands in pins. When it is not, it
+// installs the pinned core INTO that checkout (`npm ci`, or `npm install` with no
+// lockfile) and re-runs the same command under it. A worktree that gets its own
+// install keeps resolving it from then on. If the install fails, the builder gets one
+// line that names the command to run — never a silent run on the wrong core. Only
+// `ship` checks: it is the verb that runs the core's land/smoke code against the
+// branch, and it is slow anyway — the many quick verbs (status, recall, exec) pay no
+// git spawn for it.
+//
+// Safety. The pin comes from the branch, and installing it then RUNS it — so a branch
+// must never be able to choose what gets installed. Two gates, both required:
+//   1. the spec is a shape the core itself writes — a vendored
+//      `file:vendor/bongos-core-<v>.tgz` or an exact registry semver;
+//   2. the pin has already LANDED: package.json, package-lock.json and the vendored
+//      tarball in this checkout are byte-identical (same git blob, no local edits) to
+//      the ones on `main` / `origin/main`. That is exactly the case this fixes — a
+//      core update merged, the next task's branch carries it — and a branch that pins
+//      something main does not get the remedy line, never an automatic install.
+// The install also runs with `--ignore-scripts` (the core's dependencies need no
+// install hook), through npm's own JS entry under this node where it can be found, so
+// no shell is involved; only a Windows box without it falls back to `npm.cmd` + shell,
+// with fixed arguments. A `node_modules` that
+// is a LINK (the junction worktree.js gives an outside-repo worktree) is unlinked
+// first — installing through it would rewrite the MAIN checkout's install. It is never
+// followed and a real directory is never removed. The re-run sets BONGOS_CORE_SYNCED
+// so a pin the install still cannot satisfy cannot loop.
+//
+// It does nothing in the core repo itself (the running package is not `@bongos/core`),
+// outside git, or when the checkout pins no core. Pure planner + injectable runner, so
+// tests/core_pin_sync.mjs drives every branch without npm or a network.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const CORE_PKG = '@bongos/core';
+const SYNCED_ENV = 'BONGOS_CORE_SYNCED';
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(String(fsImpl.readFileSync(file, 'utf8')).replace(/^/, '')); } catch { return null; }
+}
+
+// { version, safe } for a dependency spec. `version` reads the same shapes upgrade.js
+// does (kept local so the dispatcher never loads upgrade.js's tree); `safe` is true
+// only for the two shapes the core writes itself — a tarball under vendor/ named for
+// its version, or an EXACT registry semver.
+function parseSpec(spec) {
+  const s = String(spec || '').trim();
+  const tgz = s.match(/bongos-core-(\d+\.\d+\.\d+[^/\\]*)\.tgz$/);
+  if (tgz) return { version: tgz[1], safe: /^file:(\.\/)?vendor\/bongos-core-[^/\\]+\.tgz$/.test(s) };
+  if (/^file:/.test(s)) return { version: null, safe: false };
+  const sem = s.match(/^[\^~>=<\s]*v?(\d+\.\d+\.\d+[A-Za-z0-9.+-]*)$/);
+  if (!sem) return { version: null, safe: false };
+  return { version: sem[1], safe: /^\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$/.test(s) };
+}
+
+function versionFromSpec(spec) { return parseSpec(spec).version; }
+
+function coreSpec(root, fsImpl = fs) {
+  const pkg = readJson(path.join(root, 'package.json'), fsImpl);
+  return pkg ? ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG] || null) : null;
+}
+
+// What the checkout at `root` pins: the lockfile's resolved version first (exact), then
+// the package.json spec.
+function pinnedCoreVersion(root, fsImpl = fs) {
+  const lock = readJson(path.join(root, 'package-lock.json'), fsImpl);
+  const locked = lock && lock.packages && lock.packages[`node_modules/${CORE_PKG}`];
+  if (locked && locked.version) return locked.version;
+  return versionFromSpec(coreSpec(root, fsImpl));
+}
+
+// The refs that count as LANDED for gate 2: a pin is trusted only once it is on one of them.
+const LANDED_REFS = ['main', 'origin/main'];
+
+function gitOut(args, cwd, run) {
+  try {
+    const r = run('git', args, { cwd, encoding: 'utf8' });
+    return r && r.status === 0 ? String(r.stdout || '').trim() : null;
+  } catch { return null; }
+}
+
+// Gate 2: every file that decides what `npm ci` installs — package.json, the lockfile,
+// the project .npmrc (it can redirect the registry), and the vendored tarball the spec
+// names — is in the SAME state as on a landed ref: the same blob as it sits on disk (so
+// an uncommitted edit counts), or absent on both. Deleting a file the landed ref has
+// is a difference too. True when one landed ref matches all of them. The lockfile is
+// also required outright: the install is `npm ci`, whose integrity check is the point.
+const PIN_FILES = ['package.json', 'package-lock.json', '.npmrc'];
+
+function pinLanded(root, { run = spawnSync, fsImpl = fs } = {}) {
+  if (!fsImpl.existsSync(path.join(root, 'package-lock.json'))) return false;
+  const spec = coreSpec(root, fsImpl);
+  const files = [...PIN_FILES];
+  const vendored = String(spec || '').match(/^file:(?:\.\/)?(vendor\/bongos-core-[^/\\]+\.tgz)$/);
+  if (vendored) files.push(vendored[1]);
+  const local = files.map((f) => (fsImpl.existsSync(path.join(root, f)) ? (gitOut(['hash-object', '--', f], root, run) || 'unreadable') : null));
+  return LANDED_REFS.some((ref) => files.every((f, i) => gitOut(['rev-parse', '--verify', '--quiet', `${ref}:${f}`], root, run) === local[i]));
+}
+
+function gitTopLevel(cwd, run = spawnSync) {
+  try {
+    const r = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const top = String(r.stdout || '').trim();
+    return top ? path.resolve(top) : null;
+  } catch { return null; }
+}
+
+// Pure decision. Inputs are facts; output says whether to sync and why.
+//   runningPkg   the running core's package.json ({ name, version })
+//   root         the git top-level of the cwd (null outside git)
+//   pinned       what that checkout pins (null when it pins no core)
+//   specSafe     gate 1: the spec is a shape the core writes itself (parseSpec)
+//   landed       gate 2: the pin is byte-identical to a landed ref's (pinLanded)
+//   env          process env (the re-run guard)
+function planCoreSync({ runningPkg, root, pinned, specSafe = false, landed = false, env = process.env }) {
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return { action: 'none', reason: 'not-installed-core' };
+  if (!root) return { action: 'none', reason: 'no-git' };
+  if (!pinned) return { action: 'none', reason: 'no-pin' };
+  const running = runningPkg.version || null;
+  if (running === pinned) return { action: 'none', reason: 'in-sync', running, pinned };
+  if (env && env[SYNCED_ENV]) return { action: 'refuse', reason: 'still-mismatched', running, pinned, root };
+  if (!specSafe) return { action: 'refuse', reason: 'unrecognised-spec', running, pinned, root };
+  if (!landed) return { action: 'refuse', reason: 'pin-not-landed', running, pinned, root };
+  return { action: 'sync', reason: 'mismatch', running, pinned, root };
+}
+
+function installArgs(hasLock) {
+  return [hasLock ? 'ci' : 'install', '--ignore-scripts', '--no-audit', '--no-fund'];
+}
+
+// npm's own JS entry beside this node (Windows: <dir>/node_modules/npm; POSIX:
+// <prefix>/lib/node_modules/npm), so the install needs no shell. null when absent.
+function npmCliPath(execPath = process.execPath, fsImpl = fs) {
+  const dir = path.dirname(execPath);
+  const candidates = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  return candidates.find((c) => fsImpl.existsSync(c)) || null;
+}
+
+function remedyLine({ root, pinned, running, hasLock = true }) {
+  return `bongos: this checkout pins core ${pinned} but ${running || 'another version'} is running. ` +
+    `Run \`npm ${hasLock ? 'ci' : 'install'}\` in ${root}, then run the command again.`;
+}
+
+// Remove a node_modules LINK without following it — the same move as worktree.js's
+// unlinkNodeModulesLink, kept here rather than required: bin/bongos.js is in the
+// executed closure (tests/executed_closure.mjs), and worktree.js would pull its
+// computed require in with it. unlink takes a symlink and (via libuv) a junction; a
+// Windows reparse point unlink refuses falls back to rmdir, which removes the link only.
+function unlinkLink(linkPath, { platform = process.platform, fsImpl = fs } = {}) {
+  if (!fsImpl.lstatSync(linkPath).isSymbolicLink()) throw new Error(`${linkPath} is not a link`);
+  try { fsImpl.unlinkSync(linkPath); } catch (e) {
+    if (platform !== 'win32' || (e.code !== 'EPERM' && e.code !== 'EISDIR')) throw e;
+    fsImpl.rmdirSync(linkPath);
+  }
+}
+
+// A vendored instance keeps an untracked `scripts -> node_modules/@bongos/core/scripts`
+// link in its main checkout (grading needs it; task 1004728). After an install it must
+// still resolve (task 1004732): a link left dangling is re-pointed at the installed core.
+// Only ever a LINK — a real scripts/ directory (the core repo) is never touched.
+// Returns 'absent' | 'not-a-link' | 'ok' | 'repointed' | 'unresolved'.
+function healScriptsLink(root, { fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), platform = process.platform } = {}) {
+  const link = path.join(root, 'scripts');
+  let st = null;
+  try { st = fsImpl.lstatSync(link); } catch { return 'absent'; }
+  if (!st.isSymbolicLink()) return 'not-a-link';
+  // bongos/ is the CLI folder since task 1004848; an installed core older than that has only gds/.
+  if (fsImpl.existsSync(path.join(link, 'bongos')) || fsImpl.existsSync(path.join(link, 'gds'))) return 'ok';
+  const target = path.join(root, 'node_modules', '@bongos', 'core', 'scripts');
+  const fix = `bongos: the \`scripts\` link in ${root} no longer resolves; point it at ${target}.`;
+  if (!fsImpl.existsSync(target)) { log(fix); return 'unresolved'; }
+  try {
+    unlinkLink(link, { platform, fsImpl });
+    fsImpl.symlinkSync(target, link, 'junction');
+  } catch { log(fix); return 'unresolved'; }
+  log('bongos: re-pointed the `scripts` link at the installed core.');
+  return 'repointed';
+}
+
+// Install the pinned core into `root` and re-run the same bongos command under it.
+// Returns the exit code to use.
+function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), env = process.env, platform = process.platform, npmCli = npmCliPath(process.execPath, fsImpl) } = {}) {
+  const { root, pinned, running } = plan;
+  const hasLock = fsImpl.existsSync(path.join(root, 'package-lock.json'));
+  const remedy = () => log(remedyLine({ root, pinned, running, hasLock }));
+  log(`bongos: this checkout pins core ${pinned}, but ${running} is running — installing ${pinned} here first.`);
+  const nm = path.join(root, 'node_modules');
+  let st = null;
+  try { st = fsImpl.lstatSync(nm); } catch { /* absent */ }
+  if (st && st.isSymbolicLink()) {
+    try { unlinkLink(nm, { platform, fsImpl }); } catch (e) {
+      log(`bongos: could not detach the shared node_modules link (${e.message}).`);
+      remedy();
+      return 1;
+    }
+  }
+  // npm's JS entry under this node — no shell. Fallback: `npm`, which on win32 is
+  // npm.cmd and needs a shell (Node refuses a .cmd without one); the args are fixed
+  // strings, never branch data.
+  // npm's output goes to stderr (task 1004732): `bongos start --widget` hands stdout to
+  // the renderer verbatim, so an install must never print there.
+  const cli = npmCli;
+  const stdio = ['ignore', 2, 2];
+  const inst = cli
+    ? run(process.execPath, [cli, ...installArgs(hasLock)], { cwd: root, stdio, env })
+    : run('npm', installArgs(hasLock), { cwd: root, stdio, env, ...(platform === 'win32' ? { shell: true } : {}) });
+  if (!inst || inst.error || inst.status !== 0) {
+    log(`bongos: installing core ${pinned} failed.`);
+    remedy();
+    return 1;
+  }
+  const bin = path.join(nm, '@bongos', 'core', 'bin', 'bongos.js');
+  if (!fsImpl.existsSync(bin)) { remedy(); return 1; }
+  healScriptsLink(root, { fsImpl, log, platform });
+  const res = run(process.execPath, [bin, ...argv.slice(2)], { stdio: 'inherit', env: { ...env, [SYNCED_ENV]: '1' } });
+  if (!res || res.error) return 1;
+  return res.status == null ? 1 : res.status;
+}
+
+// The dispatcher's one call. Returns an exit code when it handled the command (synced
+// and re-ran, or refused), or null to run the verb on the current core.
+function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log, npmCli } = {}) {
+  if (env && env.BONGOS_SKIP_CORE_SYNC) return null;
+  const runningPkg = readJson(path.join(coreRoot, 'package.json'), fsImpl);
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return null; // fast path: the core repo itself
+  const root = gitTopLevel(cwd, run);
+  const pinned = root ? pinnedCoreVersion(root, fsImpl) : null;
+  const specSafe = root ? parseSpec(coreSpec(root, fsImpl)).safe : false;
+  const out = { runningPkg, root, pinned, specSafe, env };
+  // gate 2 costs git spawns — only pay it when there is a mismatch to act on
+  const pre = planCoreSync({ ...out, landed: true });
+  const plan = pre.action === 'sync' ? planCoreSync({ ...out, landed: pinLanded(root, { run, fsImpl }) }) : pre;
+  if (plan.action === 'none') return null;
+  const say = log || ((s) => process.stderr.write(s + '\n'));
+  if (plan.action === 'refuse') {
+    say(remedyLine({ ...plan, hasLock: fsImpl.existsSync(path.join(root, 'package-lock.json')) }));
+    return 1;
+  }
+  return syncAndRerun(plan, { argv, run, fsImpl, log: say, env, ...(npmCli !== undefined ? { npmCli } : {}) });
+}
+
+module.exports = { CORE_PKG, SYNCED_ENV, LANDED_REFS, pinLanded, npmCliPath, parseSpec, versionFromSpec, installArgs, pinnedCoreVersion, planCoreSync, remedyLine, syncAndRerun, healScriptsLink, ensurePinnedCore };