@bongos/core 1.21.174 → 1.21.176

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

@@ -1,185 +1,6 @@
-// scripts/gds/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.
-
+// scripts/gds/core-origin-follow.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/core-origin-follow.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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 };
+require('../bongos/forwarder.js').forward(module, 'core-origin-follow.js');

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

@@ -1,259 +1,6 @@
-// scripts/gds/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.
-
+// scripts/gds/core-pin-sync.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/core-pin-sync.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 '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';
-  if (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 };
+require('../bongos/forwarder.js').forward(module, 'core-pin-sync.js');