@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/cost-report.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Read the spend rollup: total spend, and totals by month, category and source.
+//
+// The read half of cost.js, which only LOGS spend — task 1001621 (ADR 0092
+// finding): nothing rolled it up where a person could size hosting against real
+// numbers. The endpoint it reads is public, so no RANK is needed — but the base
+// URL still comes from your CLI session (or <PREFIX>_API_BASE), which is what
+// says WHICH instance to ask.
+//
+// Usage:
+//   node scripts/bongos/cost-report.js [--source X] [--category Y] [--days N] [--json]
+//
+// The filters scope the BREAKDOWNS only — the header total stays project-wide,
+// which is how the server's treasury filter already behaves.
+
+const { cliClient, arg, readSessionToken } = require('./cli-lib');
+// A CLI may require a module directly (the backfill-cost.js / cost-classify
+// precedent, BV1.R77 / ADR 0093 §1-2). The rendering is pure and lives there so
+// it is testable without a server (tests/cost_report.mjs).
+const { formatCostReport } = require('../../modules/economy/cost-report');
+
+// arg() hands back whatever follows the flag, so `--source --json` would filter
+// on the literal '--json' and silently report $0 — a wrong answer, not an error.
+function value(name, args) {
+  const v = arg(name, args);
+  if (v == null) return null;
+  if (String(v).startsWith('--')) {
+    console.error(`${name} needs a value (got '${v}')`);
+    process.exit(2);
+  }
+  return v;
+}
+
+(async () => {
+  const args = process.argv.slice(2);
+  const query = {};
+  const source = value('--source', args);
+  const category = value('--category', args);
+  const days = value('--days', args);
+  if (source) query.source = source;
+  if (category) query.category = category;
+  if (days) query.days = days;
+
+  const api = await cliClient();
+  const r = await api.public.getPublicCostSummary({ query });
+  if (!r.ok) {
+    console.error(`cost report failed (HTTP ${r.status}):`, r.data);
+    process.exit(1);
+  }
+  console.log(args.includes('--json') ? JSON.stringify(r.data, null, 2) : formatCostReport(r.data));
+})().catch((err) => {
+  // A session-less or offline run lands here, and a raw fetch stack says nothing
+  // about WHICH instance was tried. readSessionToken() returns null when not
+  // signed in, which is itself the answer in that case.
+  const session = readSessionToken();
+  const msg = (err && err.message) || String(err);
+  console.error(`cost-report failed (instance: ${session ? session.apiBase : 'no session — falling back to this checkout\'s default'}).`);
+  console.error(`  cause: ${msg}`);
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|EAI_AGAIN/.test(msg)) {
+    console.error('  The instance could not be reached. Sign in with `node scripts/bongos/setup.js`, or name one with <PREFIX>_API_BASE.');
+  }
+  process.exit(1);
+});

package/scripts/bongos/cost.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Log a cost entry (API spend, infra, art, etc.).
+//
+// Usage:
+//   node scripts/bongos/cost.js <amount-usd> <category> [--task-id N] [--description "..."] [--source "..."] [--skill <name>]
+//
+// Categories: api | compute | infra | domain | art | other
+
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+(async () => {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const amount = Number(args[0]);
+  const category = args[1];
+  if (!Number.isFinite(amount) || !category) {
+    console.error('usage: node scripts/bongos/cost.js <amount-usd> <category> [--task-id N] [--description "..."]');
+    console.error('categories: api | compute | infra | domain | art | other');
+    process.exit(2);
+  }
+  const taskIdStr = arg('--task-id', args);
+  const taskId = taskIdStr ? Number(taskIdStr) : null;
+  const description = arg('--description', args);
+  const source = arg('--source', args) || 'manual';
+  const skillName = arg('--skill', args) || null;
+
+  const api = await cliClient();
+  const r = await api.cost.postCost({
+    body: {
+      task_id: taskId,
+      amount_usd: amount,
+      category,
+      description,
+      source,
+      skill_name: skillName,
+    },
+  });
+  if (!r.ok) {
+    console.error(`cost log failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  console.log(`Logged $${amount.toFixed(2)} (${category})${taskId ? ` for task #${taskId}` : ''}${skillName ? ` [skill: ${skillName}]` : ''}`);
+})().catch((err) => {
+  console.error('fatal:', err);
+  process.exit(1);
+});

package/scripts/bongos/credential-presence.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// scripts/bongos/credential-presence.js — which credentials does this HOST hold? Names and
+// presence only, never a value (task 1002880, from idea 1000630).
+//
+// Run ON THE HOST, as the user that can read the instance's env files (usually via sudo):
+//   node scripts/bongos/credential-presence.js                 # reads /etc/<configDir>/*.env
+//   node scripts/bongos/credential-presence.js --etc /etc/example --json
+//
+// WHY. The owner was asked to create GitHub credentials at least three times, and each
+// time the credential already existed — nothing could answer "what does this instance
+// need, what is set, what is missing". docs/credentials.md is the written half (what each
+// credential is for, where it lives, who may hold it); this is the one-command half, run
+// where the values actually live. doctor.js cannot do it: it runs on a builder's laptop,
+// which never sees the host's env files, and that is by design.
+//
+// THE ONE RULE: A VALUE NEVER LEAVES THE FILE. The report says set / empty / missing and
+// the NAME of the variable that satisfied each row — never the value, never a prefix,
+// never a length. tests/credential_presence.mjs asserts no fragment of any value reaches
+// the output. If this is ever surfaced over HTTP it must be Archon-gated, and it still
+// returns names only.
+//
+// Deeper than presence: `node scripts/bongos/publish-credential-check.js` (task 1002733)
+// probes whether the publish credential can actually read the Actions API. This file
+// does not call GitHub — presence is the question it answers, offline.
+//
+// Exit: 0 = every REQUIRED row is satisfied · 1 = a required row is missing ·
+// 2 = an env file this host should have could not be read (the answer is unknown).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveEnv, envPrefix, configDirName, configPath, LEGACY_ENV_PREFIXES } = require('../../src/instance-config');
+const { arg, hasFlag, cliExit } = require('./cli-lib');
+
+// ---- the inventory -------------------------------------------------------------------
+//
+// One row per credential this instance's HOST may hold. `names` are the env var(s) that
+// must ALL be non-empty for the row to count as set; `prefixed` names resolve through the
+// instance's own env prefix (and its legacy spellings) the way the server reads them.
+// Rows sharing a `group` are alternatives: the group is satisfied when any member is.
+// `file` is the env file the value lives in on a control-plane host:
+//   web.env    — the web tier (the cloudbongos.service EnvironmentFile)
+//   box.env    — the control-plane runners; deliberately unreadable by the web tier
+//                (InaccessiblePaths=, task 1004176 / ADR 0327 §5)
+//   spaces.env — the offsite-backup timer
+// `need`: required (the instance is broken without it) · recommended (a named feature
+// is off without it) · optional.
+//
+// Every name here is documented in docs/credentials.md; the test fails if either side
+// gains a name the other lacks. Non-host credentials (GitHub Actions secrets, a
+// builder's own machine) are in the doc only — no host sweep can see them.
+const CREDENTIALS = [
+  {
+    id: 'github-sign-in', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['GITHUB_CLIENT_ID', 'GITHUB_CLIENT_SECRET'], prefixed: true,
+    purpose: 'GitHub OAuth app that signs builders in (src/bongos/auth-config.js)',
+  },
+  {
+    id: 'hub-federation', group: 'sign-in', file: 'web.env', need: 'required',
+    names: ['HUB_ORIGIN', 'HUB_CLIENT_ID', 'HUB_CLIENT_SECRET', 'HUB_PUBLIC_KEY'], prefixed: true,
+    purpose: 'sign-in federated through the Cloud Bongos hub instead of an own GitHub app (ADR 0141 §4)',
+  },
+  {
+    id: 'publish-app', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_APP_ID', 'GITHUB_APP_PRIVATE_KEY'],
+    purpose: 'GitHub App the server publishes builder branches and PRs with (modules/lifecycle/github-push.js); preferred',
+  },
+  {
+    id: 'publish-pat', group: 'publish', file: 'web.env', need: 'required',
+    names: ['GITHUB_PUSH_TOKEN'],
+    purpose: 'fine-grained PAT fallback for the same publish path, kept for cutover',
+  },
+  {
+    id: 'repo-pin', file: 'web.env', need: 'required',
+    names: ['GITHUB_OWNER', 'GITHUB_REPO'], prefixed: true, notSecret: true,
+    purpose: "which GitHub repo this instance is — mandatory where the core runs from node_modules, which has no git remote to read (src/bongos/repo-info.js)",
+  },
+  {
+    id: 'secret-box-key', file: 'web.env', need: 'required',
+    names: ['BUILDER_SECRET_KEY'], keyFile: 'builder-secret.key',
+    purpose: "master key encrypting builders' stored AI keys and GitHub tokens (src/bongos/secret-box.js); the key file in the service user's config dir also counts",
+  },
+  {
+    id: 'database-password', file: 'web.env', need: 'optional',
+    names: ['PGPASSWORD'],
+    purpose: "the instance's own Postgres role (src/bongos/pool.js); absent means local peer auth",
+  },
+  {
+    id: 'database-url', file: 'web.env', need: 'optional',
+    names: ['DATABASE_URL'],
+    purpose: 'a full Postgres connection string, when the database is not local',
+  },
+  {
+    id: 'discord-bot', file: 'web.env', need: 'recommended',
+    names: ['DISCORD_BOT_TOKEN'],
+    purpose: 'the Discord bot (modules/discord); also readable from discord-bot.json in the config dir',
+  },
+  {
+    id: 'discord-support', file: 'web.env', need: 'optional',
+    names: ['DISCORD_SUPPORT_ANTHROPIC_API_KEY'],
+    purpose: 'the #support answerer (modules/discord/discord-support.js, ADR 0367); its own key, never a host-wide ANTHROPIC_API_KEY',
+  },
+  {
+    id: 'discord-oauth', file: 'web.env', need: 'optional',
+    names: ['DISCORD_CLIENT_ID', 'DISCORD_CLIENT_SECRET'],
+    purpose: 'linking a Discord account at sign-in (src/bongos/auth-discord.js)',
+  },
+  {
+    id: 'discord-ship-news', file: 'web.env', need: 'optional',
+    names: ['DISCORD_SHIP_NEWS_WEBHOOK'],
+    purpose: '#ship-news posts (scripts/discord/lib.js); discord-webhooks.json in the config dir also works',
+  },
+  {
+    id: 'prelaunch-password', file: 'web.env', need: 'optional',
+    names: ['PRELAUNCH_PASSWORD'], legacyNames: ['STEALTH_PASSWORD'],
+    purpose: 'the pre-launch site password (src/bongos/prelaunch-gate.js); STEALTH_PASSWORD is the deprecated alias',
+  },
+  {
+    id: 'metrics-token', file: 'web.env', need: 'optional',
+    names: ['METRICS_TOKEN'],
+    purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
+  },
+  {
+    id: 'module-test-runner', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REPO', 'MODULE_TEST_TOKEN'],
+    purpose: "runs store modules' own tests in a separate private GitHub repo (scripts/bongos/module-test-runner.js, blocker 1000195); unset leaves Tests pending",
+  },
+  {
+    id: 'module-test-ref', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REF'], notSecret: true,
+    purpose: "the test repo branch holding the module-tests workflow (default main)",
+  },
+  {
+    id: 'hub-signing-key', file: 'web.env', need: 'optional',
+    names: ['HUB_SIGNING_KEY'], prefixed: true,
+    purpose: 'the HUB only: signs the assertions federated instances verify (modules/platform-identity/hub-keys.js)',
+  },
+  {
+    id: 'digitalocean', file: 'box.env', need: 'recommended',
+    names: ['DO_API_TOKEN'],
+    purpose: 'creates and destroys project servers (scripts/bongos/do-api.js, provisioning); control plane only',
+  },
+  {
+    id: 'cloudflare', file: 'box.env', need: 'recommended',
+    names: ['CLOUDFLARE_API_TOKEN'],
+    purpose: 'DNS records for project addresses (scripts/bongos/provision-net.js); control plane only',
+  },
+  {
+    id: 'offsite-backup', file: 'spaces.env', need: 'optional',
+    names: ['SPACES_KEY', 'SPACES_SECRET', 'SPACES_BUCKET'],
+    // The same file also carries the region, the endpoint and the age RECIPIENT the dumps
+    // are encrypted to. None is a secret (a recipient is a public key), so none is swept.
+    purpose: 'the weekly offsite copy of the database dumps (scripts/bongos/db-backup-offsite.sh)',
+  },
+];
+
+const ENV_FILES = ['web.env', 'box.env', 'spaces.env'];
+
+// ---- pure core ------------------------------------------------------------------------
+
+// parseEnvFile(text) → { NAME: value } for a systemd EnvironmentFile: KEY=VALUE lines,
+// `#` comments, blank lines, optional surrounding quotes. Values are held only long enough
+// to test for emptiness; nothing returned by the report functions below contains one.
+function parseEnvFile(text) {
+  const out = {};
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+    let value = line.slice(eq + 1).trim();
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value[value.length - 1] === value[0]) {
+      value = value.slice(1, -1);
+    }
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) out[key] = value;
+  }
+  return out;
+}
+
+// Every spelling a name answers to, in the order the server tries them.
+function spellingsOf(name, row, prefix) {
+  if (row.prefixed) return [...new Set([prefix, ...LEGACY_ENV_PREFIXES])].map((p) => `${p}_${name}`);
+  return [name, ...(row.legacyNames || [])];
+}
+
+// checkRow(row, env, { prefix, keyFileExists }) → { state, satisfiedBy, missing }
+// state: 'set' | 'empty' | 'missing'. satisfiedBy / missing are variable NAMES.
+function checkRow(row, env, { prefix = envPrefix(), keyFileExists = false } = {}) {
+  const satisfiedBy = [];
+  const missing = [];
+  let anyEmpty = false;
+  for (const name of row.names) {
+    const spellings = spellingsOf(name, row, prefix);
+    const value = row.prefixed ? resolveEnv(name, { env, prefix, warn: () => {} }) : spellings.map((s) => env[s]).find((v) => v);
+    if (value) {
+      satisfiedBy.push(spellings.find((s) => env[s] === value) || spellings[0]);
+    } else {
+      if (spellings.some((s) => s in env)) anyEmpty = true;
+      missing.push(spellings[0]);
+    }
+  }
+  if (missing.length && row.keyFile && keyFileExists) {
+    return { state: 'set', satisfiedBy: [`${row.keyFile} (key file)`], missing: [] };
+  }
+  const state = missing.length === 0 ? 'set' : anyEmpty ? 'empty' : 'missing';
+  return { state, satisfiedBy, missing };
+}
+
+// sweep({ files, prefix, keyFileExists }) → { rows, groups, unreadable, ok }
+// files: { 'web.env': { env } | { error } } — the parsed files, or why one could not be read.
+function sweep({ files, prefix = envPrefix(), keyFileExists = false, credentials = CREDENTIALS }) {
+  const unreadable = Object.entries(files).filter(([, f]) => f.error).map(([name, f]) => ({ file: name, error: f.error }));
+  const rows = credentials.map((row) => {
+    const f = files[row.file];
+    if (!f || f.error) return { ...pick(row), state: 'unknown', satisfiedBy: [], missing: [] };
+    return { ...pick(row), ...checkRow(row, f.env, { prefix, keyFileExists }) };
+  });
+  // A group is satisfied when any member is; its members are not individually required.
+  const groups = {};
+  for (const r of rows) {
+    if (!r.group) continue;
+    groups[r.group] = groups[r.group] || { satisfied: false, unknown: false, members: [] };
+    groups[r.group].members.push(r.id);
+    if (r.state === 'set') groups[r.group].satisfied = true;
+    if (r.state === 'unknown') groups[r.group].unknown = true;
+  }
+  const requiredMissing = rows.filter((r) => r.need === 'required' && r.state !== 'set' && r.state !== 'unknown'
+    && !(r.group && groups[r.group].satisfied));
+  const ok = requiredMissing.length === 0 && unreadable.length === 0;
+  return { rows, groups, unreadable, requiredMissing: requiredMissing.map((r) => r.id), ok };
+}
+
+function pick(row) {
+  return { id: row.id, file: row.file, need: row.need, group: row.group || null, purpose: row.purpose, notSecret: !!row.notSecret };
+}
+
+// format(result) → the human report. Built only from ids, names, states and the fixed
+// purpose text — never from a parsed value.
+function format(result, { etc } = {}) {
+  const mark = { set: '✓', empty: '!', missing: '✗', unknown: '?' };
+  const lines = [`Credential presence — names only, never values (${etc || 'env files'})`, ''];
+  for (const file of ENV_FILES) {
+    const rows = result.rows.filter((r) => r.file === file);
+    if (!rows.length) continue;
+    const bad = result.unreadable.find((u) => u.file === file);
+    lines.push(`  ${file}${bad ? `  — could not read: ${bad.error}` : ''}`);
+    for (const r of rows) {
+      const grp = r.group ? result.groups[r.group] : null;
+      const covered = grp && grp.satisfied && r.state !== 'set' ? ` (not needed: another ${r.group} option is set)` : '';
+      const detail = r.state === 'set' ? `via ${r.satisfiedBy.join(', ')}`
+        : r.state === 'unknown' ? 'file unreadable'
+        : `${r.state === 'empty' ? 'set but EMPTY' : 'not set'}: ${r.missing.join(', ')}`;
+      lines.push(`    ${mark[r.state]} ${r.id.padEnd(20)} ${r.need.padEnd(11)} ${detail}${covered}`);
+    }
+    lines.push('');
+  }
+  if (result.requiredMissing.length) lines.push(`REQUIRED and missing: ${result.requiredMissing.join(', ')} — see docs/credentials.md for what each is and where it comes from.`);
+  if (result.unreadable.length) lines.push('Some env files could not be read, so this answer is incomplete — rerun as a user that can read them (usually sudo).');
+  if (result.ok) lines.push('Every required credential is present.');
+  lines.push('Deeper check of the publish credential (can it read Actions?): node scripts/bongos/publish-credential-check.js');
+  return lines.join('\n');
+}
+
+// readFiles(etc) → the `files` shape sweep() takes, read from <etc>/<name>.
+function readFiles(etc, { fsImpl = fs } = {}) {
+  const files = {};
+  for (const name of ENV_FILES) {
+    const p = path.join(etc, name);
+    try {
+      files[name] = { env: parseEnvFile(fsImpl.readFileSync(p, 'utf8')) };
+    } catch (e) {
+      // An absent spaces.env just means offsite backups were never set up; an absent
+      // web.env means this is not the host (or the wrong --etc).
+      files[name] = e.code === 'ENOENT' && name !== 'web.env' ? { env: {} } : { error: e.code || e.message };
+    }
+  }
+  return files;
+}
+
+module.exports = { CREDENTIALS, ENV_FILES, parseEnvFile, checkRow, sweep, format, readFiles };
+
+if (require.main === module) {
+  const etcArg = arg('--etc');
+  const etc = etcArg && etcArg !== true ? etcArg : path.join('/etc', configDirName());
+  const files = readFiles(etc);
+  const keyArg = arg('--secret-key-file');
+  const keyFile = keyArg && keyArg !== true ? keyArg : configPath('builder-secret.key');
+  let keyFileExists = false;
+  try { keyFileExists = fs.statSync(keyFile).isFile(); } catch (_) { /* absent */ }
+  const result = sweep({ files, keyFileExists });
+  if (hasFlag('--json')) console.log(JSON.stringify({ etc, ...result }, null, 2));
+  else console.log(format(result, { etc }));
+  cliExit(result.unreadable.length ? 2 : result.ok ? 0 : 1);
+}

package/scripts/bongos/cutover-codemod.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+'use strict';
+// cutover-codemod.js — rewrite HOST files' core-internal require()s to the @bongos/core
+// package subpaths at cutover (R89 / task 2159 [F1], task 2161 [F3]).
+//
+// WHY. Post-split (task 1728) a host file lives at `<instance>/…` with NO co-located `src/`.
+// Its relative core require()s — `require('../../src/module-api')` (host modules, F1),
+// `require('./src/bongos/…')` (the game entrypoint server.js, F3) — point at the DELETED
+// instance `src/` → boot crash (the 2026-07-10 rehearsal, findings F1+F3:
+// docs/reviews/2026-07-10-example-decouple-r89-rehearsal.md). Core modules are UNAFFECTED:
+// they ship INSIDE @bongos/core, where `src/` sits next to `modules/`, so their identical
+// relative requires still resolve. The fix is to rewrite the host files' core requires to the
+// package's EXPORTED subpaths (`@bongos/core/module-api`, `@bongos/core/serve-internal`, …).
+//
+// WHY A CUTOVER TRANSFORM, NOT AN IN-PLACE MONOLITH EDIT. In the monolith `@bongos/core` is not
+// a dependency (the specifier resolves nowhere) and fitness's "modules import only
+// src/module-api.js" check would fail the rewritten form. So this must run AT CUTOVER on the
+// partitioned consumer tree — never on the committed monolith source. Mirrors the `.claude/hooks`
+// `_core-resolve.js` step (task 2139); `claude-materialize.js` rewrites `.claude/`, this rewrites
+// host-module + server.js source — the gap that rehearsal F1/F3 named.
+//
+// TWO GUARDS make it structurally impossible to corrupt the monolith:
+//   1. SCOPE ORACLE = publish-manifest. A file is rewritten only when `isPublishable(rel) === false`
+//      (host: game / art-pipeline / character-anim / demo + server.js). Core files (publishable)
+//      ship with the package and are left untouched — reusing the exact partition logic as the
+//      core-vs-host oracle, so this can never drift from what the cutover actually deletes/keeps.
+//   2. PRECONDITION = post-split consumer. Refuse unless the instance core doorway is gone
+//      (`src/module-api.js` absent at the root) — the definitive signal core was partitioned out.
+//      In the monolith that file exists, so the codemod refuses. `--force` overrides for a
+//      read-only preview only.
+//
+// The rewrite is TABLE-DRIVEN (CORE_INTERNAL_MAP), not a blind `src/X → @bongos/core/X` path swap,
+// because the core's export names do not all mirror the src layout: `src/bongos/serve-internal.js`
+// is exported as `./serve-internal`, not `./bongos/serve-internal`. The table encodes each mapping
+// so a rewrite can never produce a specifier the package doesn't export. Idempotent (a rewritten
+// `@bongos/core/*` require no longer matches the relative-into-src pattern) and quote-preserving.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { isPublishable } = require('./publish-manifest');
+
+const CORE_PKG = '@bongos/core';
+
+// <subpath after `src/` in the relative require> → <the @bongos/core export subpath>.
+// The core exports map (scripts/bongos/package-core.js buildPackageJson) MUST export every value
+// here, or the rewritten require won't resolve. Kept deliberately small + explicit.
+//   F1 (task 2159): the host-module doorway.
+//   F3 (task 2161): the six core internals the game entrypoint server.js wires — added there,
+//     in lockstep with widening the core exports map, so a rewrite never outruns an export.
+const CORE_INTERNAL_MAP = {
+  // F1 — every host module imports the core doorway; the ONLY core import a module is allowed.
+  'module-api': 'module-api',
+  // F3 (task 2161) — the core internals the game entrypoint server.js wires. Each LHS is the
+  // subpath after `src/` in server.js's relative require; each RHS is the core's EXPORTED subpath
+  // (widened in package-core.js buildPackageJson in lockstep). Note the divergence: the file at
+  // `src/bongos/serve-internal.js` is exported as `./serve-internal` (a curated name), NOT
+  // `./bongos/serve-internal` — this table encodes that so the rewrite can't emit an unexported
+  // specifier. The others mirror their src/ path.
+  'bongos/api-path-404': 'bongos/api-path-404',
+  'bongos/serve-internal': 'serve-internal',
+  'module-loader/loader': 'module-loader/loader',
+  'modules': 'modules',
+  'module-seams': 'module-seams',
+};
+
+// require('<./ or ../…>src/<key>')  — a RELATIVE require that reaches into a `src/` dir.
+// Group 1 = quote (preserved), group 2 = the `./`/`../…` prefix, group 3 = the key after `src/`.
+// An already-rewritten `require('@bongos/core/…')` has no `../src/` and never matches → idempotent.
+const REQUIRE_RE = /require\((['"])((?:\.\.?\/)+)src\/([^'"]+)\1\)/g;
+
+// Pure. Rewrite the core-internal require()s in one file's text per `map`.
+// Returns { text, changes:[{from,to,key}], unmapped:[{key,spec}] }.
+//   - changes: requires rewritten to `@bongos/core/<mapped>`.
+//   - unmapped: relative-into-`src/` requires whose key is NOT in the table — left UNCHANGED and
+//     surfaced so a new core internal a host file starts depending on can't be silently missed
+//     (it would still crash at boot; the codemod flags "add an export + a table entry").
+function rewriteCoreRequires(text, map = CORE_INTERNAL_MAP) {
+  const changes = [];
+  const unmapped = [];
+  const out = String(text == null ? '' : text).replace(REQUIRE_RE, (whole, q, _prefix, key) => {
+    const mapped = Object.prototype.hasOwnProperty.call(map, key) ? map[key] : null;
+    if (mapped == null) {
+      unmapped.push({ key, spec: whole });
+      return whole; // leave unknown core internals untouched — never guess a specifier
+    }
+    const to = `require(${q}${CORE_PKG}/${mapped}${q})`;
+    changes.push({ from: whole, to, key });
+    return to;
+  });
+  return { text: out, changes, unmapped };
+}
+
+// A file is in scope iff the partition classifies it HOST (not shipped in the core package).
+function isHostFile(rel, isPublishableFn = isPublishable) {
+  return isPublishableFn(rel) === false;
+}
+
+// Post-split consumer signal: the instance's own core doorway is gone. In the monolith
+// `src/module-api.js` exists, so this is false and the CLI refuses (protecting the monolith).
+function looksLikeConsumer(root, { existsFn = fs.existsSync } = {}) {
+  return !existsFn(path.join(root, 'src', 'module-api.js'));
+}
+
+// Skip vendored deps, VCS metadata, the `.claude/` topology surface (materialize's job), and
+// build output. `dist/` in particular holds an extracted @bongos/core tarball whose bundled
+// core modules carry the SAME `../../src/module-api` requires — scanning it would be noise
+// (it's gitignored throwaway, never part of the consumer).
+const SKIP_DIRS = new Set(['node_modules', '.git', '.claude', 'dist', 'coverage']);
+
+// Preferred source scope: git-TRACKED *.js files. A consumer tree is a git repo at cutover, and
+// tracking is the honest "source" oracle — it excludes every gitignored build artifact (dist/,
+// coverage/, …) without enumerating them. Returns repo-relative POSIX paths, or null when git is
+// unavailable / this isn't a repo (→ caller falls back to the filesystem walk).
+function gitTrackedJsFiles(root, { runGit } = {}) {
+  const run = runGit || ((args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }));
+  let out;
+  try { out = run(['ls-files', '-z', '*.js']); } catch { return null; }
+  if (typeof out !== 'string') return null;
+  return out.split('\0').filter(Boolean).map((p) => p.split(path.sep).join('/')).sort();
+}
+
+// Recursively collect *.js files under `root`, skipping SKIP_DIRS. Returns repo-relative POSIX
+// paths (what isPublishable expects). The fallback when git tracking is unavailable.
+function collectJsFiles(root, { fsImpl = fs } = {}) {
+  const found = [];
+  const walk = (absDir) => {
+    let entries;
+    try { entries = fsImpl.readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        walk(path.join(absDir, ent.name));
+      } else if (ent.isFile() && ent.name.endsWith('.js')) {
+        found.push(path.relative(root, path.join(absDir, ent.name)).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+
+function underSkipDir(rel) {
+  return SKIP_DIRS.has(rel.split('/')[0]);
+}
+
+// The candidate *.js set to consider: git-tracked source when available, else the filesystem walk.
+// SKIP_DIRS is enforced on BOTH paths — git ls-files does not know about it, and `.claude/` in
+// particular is materialize's + _core-resolve.js's domain (task 2139), never the codemod's.
+function candidateJsFiles(root, { fsImpl = fs, runGit } = {}) {
+  const tracked = gitTrackedJsFiles(root, { runGit });
+  const list = tracked && tracked.length ? tracked : collectJsFiles(root, { fsImpl });
+  return list.filter((rel) => !underSkipDir(rel));
+}
+
+// Plan the codemod over a consumer `root`: which host files change, and any unmapped core requires.
+// Pure-ish (reads disk via injectable deps for tests). Does NOT write.
+function planCodemod({ root, fsImpl = fs, runGit, isPublishableFn = isPublishable, map = CORE_INTERNAL_MAP } = {}) {
+  const files = [];
+  const unmapped = [];
+  for (const rel of candidateJsFiles(root, { fsImpl, runGit })) {
+    if (!isHostFile(rel, isPublishableFn)) continue; // core file → ships with the package, leave it
+    let raw;
+    try { raw = fsImpl.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    const res = rewriteCoreRequires(raw, map);
+    if (res.unmapped.length) for (const u of res.unmapped) unmapped.push({ rel, ...u });
+    if (res.changes.length) files.push({ rel, changes: res.changes, newText: res.text });
+  }
+  return { files, unmapped };
+}
+
+// ---- CLI -------------------------------------------------------------------
+function parseArgs(argv) {
+  const a = { root: process.cwd(), apply: false, force: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') a.root = argv[++i];
+    else if (argv[i] === '--apply') a.apply = true;
+    else if (argv[i] === '--force') a.force = true;
+  }
+  return a;
+}
+
+function main(argv = process.argv.slice(2), { log = console.log, err = console.error } = {}) {
+  const args = parseArgs(argv);
+  const root = path.resolve(args.root);
+
+  if (!looksLikeConsumer(root) && !args.force) {
+    err(`[cutover-codemod] REFUSING: ${path.join(root, 'src/module-api.js')} still exists — this looks like the monolith,`);
+    err('  not a post-split consumer. This codemod is a CUTOVER transform and must not edit the monolith');
+    err('  (there @bongos/core is not a dep and fitness would reject the rewrite). Run it after the partition,');
+    err('  or pass --force for a read-only preview only.');
+    return 2;
+  }
+
+  const plan = planCodemod({ root });
+
+  for (const u of plan.unmapped) {
+    err(`[cutover-codemod] WARNING ${u.rel}: unmapped core-internal require ${u.spec} — add a CORE_INTERNAL_MAP`);
+    err(`  entry + a matching core export before cutover, or this require will crash at boot.`);
+  }
+
+  if (!plan.files.length) {
+    log('[cutover-codemod] no host files need rewriting (already converted, or none present).');
+    return 0;
+  }
+
+  const verb = args.apply ? 'rewrote' : 'would rewrite';
+  for (const f of plan.files) {
+    log(`[cutover-codemod] ${verb} ${f.rel} (${f.changes.length} require${f.changes.length === 1 ? '' : 's'}):`);
+    for (const c of f.changes) log(`    ${c.from}  →  ${c.to}`);
+    if (args.apply) fs.writeFileSync(path.join(root, f.rel), f.newText);
+  }
+
+  const total = plan.files.reduce((n, f) => n + f.changes.length, 0);
+  if (args.apply) {
+    log(`[cutover-codemod] ✓ rewrote ${total} require(s) across ${plan.files.length} host file(s).`);
+  } else {
+    log(`[cutover-codemod] dry-run: ${total} require(s) across ${plan.files.length} host file(s). Re-run with --apply to write.`);
+  }
+  return 0;
+}
+
+module.exports = {
+  CORE_PKG,
+  CORE_INTERNAL_MAP,
+  REQUIRE_RE,
+  rewriteCoreRequires,
+  isHostFile,
+  looksLikeConsumer,
+  gitTrackedJsFiles,
+  collectJsFiles,
+  candidateJsFiles,
+  planCodemod,
+  parseArgs,
+  main,
+};
+
+if (require.main === module) {
+  process.exit(main());
+}