@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/doctor.js

@@ -0,0 +1,493 @@
+#!/usr/bin/env node
+// GDS Doctor — one-shot health check for a builder's local machine.
+//
+// Usage:
+//   node scripts/bongos/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/bongos/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/bongos/setup.js --force`);
+    return;
+  }
+  if (me.status !== 200) {
+    fail('session', `Unexpected /me response (HTTP ${me.status}). Try: node scripts/bongos/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/bongos/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);
+});

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/bongos/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/bongos/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/bongos/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 };