@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/doctor.js

@@ -1,493 +1,7 @@
 #!/usr/bin/env node
-// GDS Doctor — one-shot health check for a builder's local machine.
-//
-// Usage:
-//   node scripts/gds/doctor.js
-//
-// No arguments. Prints a green/red checklist covering:
-//   - Session validity (file present, /me returns 200, identity + rank)
-//   - Toolchain (Node >= 22; the `claude` CLI the grader spawns is launchable —
-//     this is the check that would have surfaced Xenos's Windows grader failure
-//     up front instead of after a deep manual dig)
-//   - Git plumbing (core.hooksPath resolves to a real directory, hook executable)
-//   - Repo state (on a known branch, no uncommitted matches against a held
-//     claim's touches[])
-//   - Environment (.env.local present in main checkout, art-pipeline key
-//     present at ~/.config/otb/env)
-//
-// Exits 0 if every check passes, 1 if any red finding (so it's safe to wire
-// into hooks or CI smoke). Intended to be run by a builder when something
-// feels off ("am I authed? are my hooks installed? is my worktree clean?")
-// and to be the single command we point new builders at first.
-//
-// Designed not to throw — every check catches its own exceptions and renders
-// a red row with the error message rather than blowing up the whole report.
-
-const fs = require('node:fs');
-const path = require('node:path');
-const os = require('node:os');
-const { execSync, spawnSync } = require('node:child_process');
-const { cliClient, SESSION_PATH, loadSession } = require('./cli-lib');
-const { classifyMergeDriverState, MERGE_DRIVER_NAME } = require('./install-git-hooks.js');
-const { preflightChecks } = require('./preflight');
-const { resolveEnv } = require('../../src/instance-config');
-
-// ANSI helpers (only if stdout is a TTY; otherwise emit plain text)
-const TTY = process.stdout.isTTY;
-const C = {
-  green: TTY ? '\x1b[32m' : '',
-  red: TTY ? '\x1b[31m' : '',
-  yellow: TTY ? '\x1b[33m' : '',
-  bold: TTY ? '\x1b[1m' : '',
-  reset: TTY ? '\x1b[0m' : '',
-};
-
-// Accumulate findings across all checks. Each finding has a status (ok / warn /
-// fail), a section name, and a one-line description. Only "fail" rows count
-// toward the non-zero exit code; "warn" is for things that are mildly off but
-// the builder can still work (e.g. art-pipeline key missing — only matters if
-// they touch the pipeline).
-const findings = [];
-
-function ok(section, msg) {
-  findings.push({ status: 'ok', section, msg });
-  console.log(`  ${C.green}✓${C.reset} ${msg}`);
-}
-function warn(section, msg) {
-  findings.push({ status: 'warn', section, msg });
-  console.log(`  ${C.yellow}!${C.reset} ${msg}`);
-}
-function fail(section, msg) {
-  findings.push({ status: 'fail', section, msg });
-  console.log(`  ${C.red}✖${C.reset} ${msg}`);
-}
-
-function section(title) {
-  console.log('');
-  console.log(`${C.bold}${title}${C.reset}`);
-}
-
-function gitOut(cmd, opts = {}) {
-  try {
-    return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts }).trim();
-  } catch (_) {
-    return null;
-  }
-}
-
-// --------------------------------------------------------------------------
-// Check 1 — Session
-// --------------------------------------------------------------------------
-async function checkSession() {
-  section('Session');
-  let s;
-  try {
-    s = await loadSession();
-  } catch (err) {
-    fail('session', `Could not read session file: ${err.message}`);
-    return;
-  }
-  if (!s || !s.token) {
-    fail('session', `No session file at ${SESSION_PATH} (or the legacy fallback).`);
-    fail('session', `Recover with: node scripts/gds/setup.js`);
-    return;
-  }
-  ok('session', `Session file present (${SESSION_PATH.replace(os.homedir(), '~')})`);
-  // Ping /me with allowUnauthenticated so we can render a red row instead of
-  // exiting via the global 401 short-circuit.
-  let me;
-  try {
-    const api = await cliClient({ allowUnauthenticated: true });
-    me = await api.me.getMe();
-  } catch (err) {
-    fail('session', `Could not reach the GDS to verify the token: ${err.message}`);
-    return;
-  }
-  if (me.status === 401) {
-    fail('session', `Token rejected (HTTP 401). Recover with: node scripts/gds/setup.js --force`);
-    return;
-  }
-  if (me.status !== 200) {
-    fail('session', `Unexpected /me response (HTTP ${me.status}). Try: node scripts/gds/setup.js --force`);
-    return;
-  }
-  const b = me.data?.builder || {};
-  ok('session', `Authenticated as ${b.github_login} (id #${b.id}, rank=${b.rank}, ${b.total_credits ?? 0} credits)`);
-  ok('session', `Session is rolling: every authenticated request resets the 1h TTL.`);
-}
-
-// --------------------------------------------------------------------------
-// Check 2 — Toolchain (Node + the claude CLI the grader spawns)
-// --------------------------------------------------------------------------
-//
-// The grader (src/bongos/grader.js) spawns one `claude` subprocess per worker. If
-// that binary can't be launched, every ship fails the grade with
-// SUBAGENT_SPAWN_FAILED (can't launch) or SUBAGENT_NONZERO_EXIT (launches but
-// misbehaves — e.g. the Windows "App execution alias" desktop stub). On Windows
-// this bit a real builder twice and was only diagnosed after a long manual dig.
-// This check makes it the FIRST thing doctor reports, with the one-line fix.
-//
-// Resolution mirrors the grader EXACTLY (<PREFIX>_CLAUDE_BIN / CLAUDE_BIN / 'claude',
-// shell:true on win32 so a `claude.cmd` shim resolves) so a green row here means
-// the grader's spawn will work too. Mac/Linux: shell:false, identical to today.
-function checkToolchain() {
-  section('Toolchain');
-
-  // Node + deps + `claude` come from the shared onboarding preflight (preflight.js)
-  // — the single source of truth also run up front at /builder-setup (task 1002401),
-  // so doctor and setup can never drift. (This also gives doctor the node_modules
-  // check it previously lacked.)
-  const results = preflightChecks();
-  for (const r of results) {
-    if (r.level === 'ok') {
-      ok('toolchain', `${r.title}: ${r.detail}`);
-    } else {
-      const emit = r.level === 'warn' ? warn : fail;
-      emit('toolchain', `${r.title}: ${r.detail}`);
-      if (r.fix) emit('toolchain', `Fix: ${r.fix}`);
-    }
-  }
-
-  // Windows-only extra (beyond the shared preflight): even when `claude` launches,
-  // warn if it resolves to the WindowsApps desktop "App execution alias" stub — it
-  // can pass --version yet misbehave under the grader's stdio redirection
-  // (SUBAGENT_NONZERO_EXIT). Learning #42.
-  const claudeOk = results.some((r) => r.title === 'claude CLI' && r.level === 'ok');
-  if (claudeOk && process.platform === 'win32' && !resolveEnv('CLAUDE_BIN') && !process.env.CLAUDE_BIN) {
-    try {
-      const where = spawnSync('where', ['claude'], { encoding: 'utf8', shell: true, timeout: 8000 });
-      if (where.status === 0 && /WindowsApps/i.test(where.stdout || '')) {
-        warn('toolchain', `claude resolves to the WindowsApps desktop alias, which can fail headless grading (SUBAGENT_NONZERO_EXIT). Prefer a real CLI: npm i -g @anthropic-ai/claude-code (learning #42).`);
-      }
-    } catch (_) { /* best-effort */ }
-  }
-}
-
-// --------------------------------------------------------------------------
-// Check 3 — Git plumbing
-// --------------------------------------------------------------------------
-// Pure verdict for the hooks gate, extracted so the truth table is testable
-// (tests/doctor_hooks.mjs).
-//
-// `.husky/` is INSTANCE topology, not shipped in the portable core (README
-// "Secrets scanning"). So its absence is not a builder error: it means ADR 0043
-// layer 1 has nothing to activate here, and CI + the post-push main audit are
-// the enforcing layers. Recommending `.husky` regardless is what produced the
-// unbreakable red loop this replaces — doctor demanded a dir that wasn't there,
-// then failed on the dangling path it had just told you to set.
-function classifyHooksState({ hooksPath, worktreeRoot, exists = fs.existsSync }) {
-  const huskyDir = worktreeRoot ? path.join(worktreeRoot, '.husky') : '.husky';
-  const huskyPresent = exists(huskyDir);
-  const installer = 'node scripts/gds/install-git-hooks.js';
-
-  if (!hooksPath) {
-    if (!huskyPresent) {
-      return {
-        status: 'warn',
-        code: 'no-hooks-dir',
-        resolved: null,
-        message:
-          'No hooks dir in this checkout (.husky/ is instance topology, not shipped in the portable core), '
-          + 'so the local pre-commit/pre-push gates are inactive. CI secrets-scan and the post-push main audit still enforce.',
-      };
-    }
-    return {
-      status: 'fail',
-      code: 'inactive',
-      resolved: null,
-      message: `.husky/ is present but core.hooksPath is unset — the secrets + permission gates are not running. Activate with: ${installer}`,
-    };
-  }
-
-  // Relative hooksPath resolves against the worktree root (git's behavior);
-  // absolute resolves as-is.
-  const resolved = path.isAbsolute(hooksPath) || !worktreeRoot
-    ? hooksPath
-    : path.join(worktreeRoot, hooksPath);
-
-  if (!exists(resolved)) {
-    return {
-      status: 'fail',
-      code: 'dangling',
-      resolved,
-      message: huskyPresent
-        ? `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}. Repoint it with: ${installer}`
-        : `core.hooksPath="${hooksPath}" resolves to a non-existent path: ${resolved}, and this checkout has no .husky/ to point at. Clear it with: git config --unset core.hooksPath`,
-    };
-  }
-  return { status: 'ok', code: 'active', resolved, message: `core.hooksPath="${hooksPath}" → ${resolved} (exists)` };
-}
-
-// The pre-commit verdict, extracted pure so it can be tested (the classifyHooksState
-// precedent above, task 1002524).
-//
-// ABSENT IS NOT A FAULT (task 1003773). The core ships `.husky/pre-push` and
-// `.husky/post-merge` and nothing else — `.husky/pre-commit` has never existed in git
-// history, and install-git-hooks.js says outright that an instance MAY add one. Doctor
-// used to warn unconditionally that the "secrets-guard hook will not fire", which asserts
-// a live hole in the walls on every clean clone. That trains builders to skim this very
-// section — the one carrying the REAL fault, an unset core.hooksPath that genuinely does
-// disable pre-push. A false positive beside a true positive degrades the true one.
-//
-// Secrets are enforced by .claude/hooks/secret-gate.js and the CI secrets-scan in
-// .github/workflows/main-audit.yml, neither of which the old warning mentioned.
-//
-// A pre-commit file that EXISTS but is not executable is still a real fault: someone
-// installed a gate that silently does not run.
-function classifyPreCommitState({ preCommitPath, present, executable }) {
-  if (!present) {
-    return {
-      status: 'ok',
-      code: 'absent-by-design',
-      message: 'no pre-commit hook — the core ships pre-push only, by design. '
-        + 'Secrets are enforced by .claude/hooks/secret-gate.js and the CI secrets-scan.',
-    };
-  }
-  if (!executable) {
-    return {
-      status: 'warn',
-      code: 'not-executable',
-      message: `pre-commit exists but is not executable: ${preCommitPath}`,
-    };
-  }
-  return { status: 'ok', code: 'active', message: 'pre-commit hook is executable.' };
-}
-
-function checkGitPlumbing() {
-  section('Git plumbing');
-
-  // The merge-driver section is reported FIRST and unconditionally — it is checked
-  // even when core.hooksPath is unset, because the two are independent and the
-  // half-written-section wedge (task 1003846) is silent until a merge dies with
-  // `fatal: custom merge driver ... lacks command line`. A builder who hits that has
-  // no reason to connect it to a setup step that ran days ago, so doctor naming it
-  // is the whole point. Early-returning before this line would hide it on exactly
-  // the clones most likely to be mis-set-up.
-  const md = classifyMergeDriverState({
-    name: gitOut(`git config --get merge.${MERGE_DRIVER_NAME}.name`),
-    driver: gitOut(`git config --get merge.${MERGE_DRIVER_NAME}.driver`),
-  });
-  ({ ok, warn, fail }[md.status])('git', md.message);
-
-  const verdict = classifyHooksState({
-    hooksPath: gitOut('git config --get core.hooksPath'),
-    worktreeRoot: gitOut('git rev-parse --show-toplevel'),
-  });
-  const report = { ok, warn, fail }[verdict.status];
-  report('git', verdict.message);
-  if (verdict.status !== 'ok') return;
-  const preCommit = path.join(verdict.resolved, 'pre-commit');
-  const present = fs.existsSync(preCommit);
-  let executable = false;
-  if (present) {
-    try { fs.accessSync(preCommit, fs.constants.X_OK); executable = true; } catch (_) { executable = false; }
-  }
-  const pre = classifyPreCommitState({ preCommitPath: preCommit, present, executable });
-  ({ ok, warn, fail }[pre.status])('git', pre.message);
-}
-
-// --------------------------------------------------------------------------
-// Check 4 — Repo state
-// --------------------------------------------------------------------------
-async function checkRepoState() {
-  section('Repo state');
-  const branch = gitOut('git rev-parse --abbrev-ref HEAD');
-  if (!branch) {
-    fail('repo', `Could not determine current git branch. Are we inside a git repo?`);
-    return;
-  }
-  if (branch === 'HEAD') {
-    warn('repo', `Detached HEAD — most workflows expect a named branch.`);
-  } else {
-    ok('repo', `On branch ${branch}.`);
-  }
-  // If we have a session AND an active claim, optionally surface a touches[]
-  // drift hint. Skip silently if we don't (the /me data is already lost by
-  // this point of the check sequence; we'd have to re-fetch and that's more
-  // failure surface area for marginal value).
-  // (Left as a quiet ok-row to keep the section honest.)
-  const porcelain = gitOut('git status --porcelain');
-  if (!porcelain) {
-    ok('repo', `Working tree clean.`);
-  } else {
-    const lines = porcelain.split('\n').filter(Boolean);
-    warn('repo', `${lines.length} uncommitted change(s) in the working tree.`);
-  }
-}
-
-// --------------------------------------------------------------------------
-// Check 5 — Environment
-// --------------------------------------------------------------------------
-function checkEnvironment() {
-  section('Environment');
-  // Find the main checkout root via the shared common-dir trick (works from
-  // any worktree, survives folder renames).
-  const commonDir = gitOut('git rev-parse --git-common-dir');
-  if (!commonDir) {
-    warn('env', `Could not resolve git common-dir; skipping .env.local check.`);
-    return;
-  }
-  const mainRoot = path.dirname(path.resolve(commonDir));
-  const envLocal = path.join(mainRoot, '.env.local');
-  if (fs.existsSync(envLocal)) {
-    ok('env', `.env.local present in main checkout (${mainRoot.replace(os.homedir(), '~')}/.env.local)`);
-  } else {
-    warn('env', `No .env.local in the main checkout. If you need local secrets, run /builder-setup.`);
-  }
-  // Art-pipeline key — survives worktree churn at ~/.config/otb/env
-  const otbEnv = path.join(os.homedir(), '.config/otb/env');
-  if (fs.existsSync(otbEnv)) {
-    ok('env', `Art-pipeline env present (~/.config/otb/env)`);
-  } else {
-    warn('env', `No ~/.config/otb/env — art pipeline calls will fail if you try them.`);
-  }
-}
-
-// --------------------------------------------------------------------------
-// Check — Deploy tooling (the GitHub CLI the 'ci' deploy mode spawns)
-//
-// #857 / ADR 0042: in 'ci' deploy mode, ship.js's ciLand opens a PR + enables
-// auto-merge via the `gh` CLI on THIS machine. If gh is missing or not
-// authenticated, the ship reaches `confirmed` then fails to land with a cryptic
-// `gh pr create` error. Surface it here as an actionable row so a builder fixes
-// it before shipping. In 'laptop' mode gh isn't used → informational only.
-// (The eventual fix that drops this dependency — server-mediated PR creation —
-// is tracked separately; until then this check is the guardrail.)
-function checkDeployTooling() {
-  section('Deploy tooling');
-
-  // Resolve the mode exactly as ship.js will (env > committed config > laptop).
-  // Lazy + guarded require so doctor never throws if ship.js's load changes.
-  let mode = 'laptop';
-  try {
-    mode = require('./ship.js').resolveDeployMode();
-  } catch (_) {
-    /* keep the safe default; ship.js load is not doctor's concern */
-  }
-
-  if (mode !== 'ci') {
-    ok('deploy', `Deploy mode: laptop — the operator lands ships; the gh CLI is not required here.`);
-    return;
-  }
-
-  // ADR 0055 / task 1025: in ci mode there are two publish paths. A machine with
-  // no GitHub push credential ships SERVER-MEDIATED — it uploads its
-  // branch to the GDS, which pushes + opens the PR with the server's credential —
-  // so gh is NOT needed here. Resolve the same path ship.js will take and skip the
-  // gh requirement when it's server-mediated.
-  let via = 'local';
-  try {
-    via = require('./ship.js').pushVia();
-  } catch (_) {
-    /* keep 'local'; the gh checks below are the safe, stricter default */
-  }
-  if (via === 'server') {
-    ok('deploy', `Deploy mode: ci (server-mediated publish) — this machine has no GitHub push credential, so the GDS pushes your branch + opens the PR for you. gh is not required here.`);
-    return;
-  }
-
-  // ci mode, local push path → gh is on the critical path for this builder's own ship.
-  let installed = false;
-  try {
-    const v = spawnSync('gh', ['--version'], {
-      encoding: 'utf8',
-      shell: process.platform === 'win32',
-      windowsHide: true,
-      timeout: 15000,
-    });
-    installed = !!v && !v.error && v.status === 0;
-  } catch (_) {
-    installed = false;
-  }
-  if (!installed) {
-    fail('deploy', `Deploy mode is 'ci' but the GitHub CLI (gh) is not launchable. ci-mode ship opens a PR via gh — install it (https://cli.github.com) then 'gh auth login', or ships will reach confirmed and fail to land.`);
-    return;
-  }
-
-  let authed = false;
-  try {
-    const a = spawnSync('gh', ['auth', 'status'], {
-      encoding: 'utf8',
-      shell: process.platform === 'win32',
-      windowsHide: true,
-      timeout: 15000,
-    });
-    authed = !!a && !a.error && a.status === 0;
-  } catch (_) {
-    authed = false;
-  }
-  if (authed) {
-    ok('deploy', `Deploy mode: ci — gh CLI present + authenticated; ci-mode ship can open + auto-merge its PR.`);
-  } else {
-    fail('deploy', `Deploy mode is 'ci' and gh is installed but NOT authenticated. Run 'gh auth login' (needs repo scope) or ci-mode ships will fail at 'gh pr create'.`);
-  }
-}
-
-// Intent-runner drift (task 1002722): a runner on a stale core once turned a domain-attach
-// into a teardown (task 1002716). Only a host with *intent-runner* units shows this section,
-// so a builder laptop sees nothing.
-function runnerDriftRows(results) {
-  return (results || []).map((r) => {
-    const msg = `${r.name}: ${r.reason}`;
-    if (r.status === 'ok') return { status: 'ok', msg };
-    if (r.status === 'drift') return { status: 'fail', msg: `${msg} — repoint the unit's WorkingDirectory + ExecStart at the installed core (a systemd drop-in, as task 1002716 did).` };
-    return { status: 'warn', msg };
-  });
-}
-
-function checkRunnerDrift() {
-  let rows = [];
-  try {
-    const { collectRunnerDrift } = require('./runner-drift.js');
-    rows = runnerDriftRows(collectRunnerDrift({ instanceRoot: process.env.BONGOS_INSTANCE_ROOT || process.cwd() }));
-  } catch (_) {
-    return;
-  }
-  if (!rows.length) return;
-  section('Intent runners');
-  const emit = { ok, warn, fail };
-  for (const row of rows) emit[row.status]('runners', row.msg);
-}
-
-// --------------------------------------------------------------------------
-// main
-// --------------------------------------------------------------------------
-// Guarded so requiring this file for its pure helpers (tests/doctor_hooks.mjs)
-// does not run the checks, which shell out to git and hit the network.
-module.exports = { classifyHooksState, classifyMergeDriverState, classifyPreCommitState, runnerDriftRows };
-
-if (require.main === module) (async () => {
-  console.log(`${C.bold}GDS Doctor${C.reset} — local-machine health check`);
-  await checkSession();
-  checkToolchain();
-  checkDeployTooling();
-  checkGitPlumbing();
-  await checkRepoState();
-  checkEnvironment();
-  checkRunnerDrift();
-
-  const fails = findings.filter((f) => f.status === 'fail').length;
-  const warns = findings.filter((f) => f.status === 'warn').length;
-  const oks = findings.filter((f) => f.status === 'ok').length;
-
-  console.log('');
-  if (fails === 0 && warns === 0) {
-    console.log(`${C.green}All ${oks} checks green.${C.reset}`);
-    process.exit(0);
-  }
-  const parts = [];
-  if (fails > 0) parts.push(`${C.red}${fails} fail${C.reset}`);
-  if (warns > 0) parts.push(`${C.yellow}${warns} warn${C.reset}`);
-  parts.push(`${oks} ok`);
-  console.log(`Summary: ${parts.join(', ')}.`);
-  if (fails > 0) {
-    console.log(`Address the fail rows above before continuing builder work.`);
-    process.exit(1);
-  }
-  process.exit(0);
-})().catch((err) => {
-  // Doctor's job is to NEVER throw — every check catches its own exceptions.
-  // If we got here, something is genuinely wrong with the doctor itself.
-  console.error('doctor: unexpected fatal:', err);
-  process.exit(1);
-});
+// scripts/gds/doctor.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/doctor.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';
+require('../bongos/forwarder.js').forward(module, 'doctor.js');

package/scripts/gds/enroll-control-plane.js

@@ -1,101 +1,7 @@
 #!/usr/bin/env node
+// scripts/gds/enroll-control-plane.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/enroll-control-plane.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';
-
-// scripts/gds/enroll-control-plane.js — give the platform a row so its own pin can move
-// (task 1003159, ADR 0293 D2).
-//
-// WHY THIS EXISTS AT ALL. `provisioning_intents.instance_id` is NOT NULL REFERENCES
-// provisioning_instances(id), so every intent must name a row. That table has only ever
-// held tenant projects — the box this software runs on has no row — which is the
-// mechanical reason the owner had no deploy door: there was nothing to point the door at.
-//
-// IDEMPOTENT, AND ONLY EVER ONE. provisioning_instances_one_control_plane_idx makes a
-// second control-plane row impossible at the database, because "which row is me?" must
-// have exactly one answer; this script resolves the existing row and reports it rather
-// than racing that index.
-//
-// RUN ONCE PER INSTALL, by whoever already has the box — the same person who runs
-// migrations. This is deliberately NOT something the web tier does for itself: a process
-// that could mint its own control-plane row could mint a second one, and the whole value
-// of the self row is that it is a thing someone decided to create. See
-// docs/recipes/core-release-pipeline.md.
-//
-//   node scripts/gds/enroll-control-plane.js --owner <builderId> [--slug cloudbongos]
-//                                            [--port 3002] [--domain cloudbongos.com] [--apply]
-//
-// Without --apply it prints what it would do and changes nothing, matching provision.js.
-
-const { Pool } = require('pg');
-const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
-
-function arg(flag, argv, fallback = null) {
-  const i = argv.indexOf(flag);
-  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
-}
-const hasFlag = (flag, argv) => argv.includes(flag);
-
-async function enrollControlPlane(db, { ownerBuilderId, slug, port, domain, apply }) {
-  // The slug ends up as a systemd unit name and inside the runner's shell commands,
-  // so it is validated at the door rather than left to whoever runs this. The runner
-  // re-checks it at the point of use too — this one is so the operator hears about a
-  // typo now, instead of as a refused upgrade weeks later.
-  if (!isValidSlug(slug)) {
-    return { ok: false, created: false, error: `'${slug}' is not a valid slug — lowercase letters, digits and single hyphens, 2-40 characters` };
-  }
-  const { rows: existing } = await db.query(
-    "SELECT * FROM provisioning_instances WHERE hosting_shape = 'control-plane'");
-  if (existing[0]) {
-    return { ok: true, created: false, instance: existing[0], reason: 'already enrolled' };
-  }
-  if (!apply) return { ok: true, created: false, wouldCreate: { slug, port, domain, ownerBuilderId } };
-  // status 'active' because it IS active — this process is the proof. A row parked at
-  // 'requested' would be refused by the upgrade leg's own status gate, so enrolling it
-  // any other way would produce a door that is visible and permanently refuses.
-  const { rows } = await db.query(
-    `INSERT INTO provisioning_instances
-       (owner_builder_id, slug, hosting_shape, domain, port, status, onboard_mode, description)
-     VALUES ($1, $2, 'control-plane', $3, $4, 'active', 'adopt', $5)
-     RETURNING *`,
-    [ownerBuilderId, slug, domain || null, port,
-     'The control plane itself — the box this platform runs on. Enrolled so its core pin can be moved from the hall (ADR 0293); it is not a tenant project and cannot be torn down.']);
-  return { ok: true, created: true, instance: rows[0] };
-}
-
-async function main() {
-  const argv = process.argv.slice(2);
-  if (hasFlag('--help', argv)) {
-    console.log('usage: node scripts/gds/enroll-control-plane.js --owner <builderId> [--slug <slug>] [--port <port>] [--domain <domain>] [--apply]');
-    return 0;
-  }
-  const ownerBuilderId = arg('--owner', argv);
-  if (!ownerBuilderId) {
-    console.error('enroll-control-plane: --owner <builderId> is required — the self row needs an owner like any other, and an unattributed one is exactly what ADR 0293 D5 refuses.');
-    return 2;
-  }
-  const url = process.env.DATABASE_URL;
-  if (!url) { console.error('enroll-control-plane: DATABASE_URL is not set.'); return 2; }
-  const apply = hasFlag('--apply', argv);
-  const pool = new Pool({ connectionString: url });
-  try {
-    const r = await enrollControlPlane(pool, {
-      ownerBuilderId,
-      slug: arg('--slug', argv, 'cloudbongos'),
-      port: Number(arg('--port', argv, '3002')),
-      domain: arg('--domain', argv),
-      apply,
-    });
-    if (r.error) { console.error(`enroll-control-plane: ${r.error}`); return 2; }
-    if (r.created) console.log(`enrolled the control plane as instance #${r.instance.id} (${r.instance.slug}, port ${r.instance.port})`);
-    else if (r.instance) console.log(`already enrolled: instance #${r.instance.id} (${r.instance.slug}, port ${r.instance.port})`);
-    else console.log(`would enroll the control plane as ${JSON.stringify(r.wouldCreate)} — re-run with --apply`);
-    return 0;
-  } finally {
-    try { await pool.end(); } catch { /* ignore */ }
-  }
-}
-
-if (require.main === module) {
-  main().then((c) => process.exit(c)).catch((e) => { console.error(e.message); process.exit(1); });
-}
-
-module.exports = { enrollControlPlane };
+require('../bongos/forwarder.js').forward(module, 'enroll-control-plane.js');