@bongos/core 1.19.331 → 1.19.333

package/scripts/gds/provision.js

@@ -49,1402 +49,11 @@ const path = require('node:path');
 const cp = require('node:child_process');
 const crypto = require('node:crypto');
 
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
+const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbName, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
+const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath } = require('./provision-units.js');
+const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, shouldFederate, zoneForDomain } = require('./provision-net.js');
 
-// The verified OAuth-cred placement helpers (task 1979) — reused by the GitHub App
-// Manifest flow (task 2080) to VALIDATE the creds GitHub returns before writing them
-// and to PARSE the post-restart /healthz auth_configured probe. A sibling script; a
-// plain require (its require.main guard means importing it runs no CLI).
-const oauthSecret = require('./oauth-secret');
-
-// The registry-install gates + env-fed .npmrc (ADR 0134, task 2090). Lets the
-// standalone scaffold OPT IN to pulling the PRIVATE @bongos/core from the npm
-// registry (PROVISION_CORE_FROM_REGISTRY=1) instead of vendoring a tarball, with a
-// fail-soft fallback to the vendored path when no NPM_TOKEN is present.
-const { registryCoreRequested, hasNpmToken } = require('./npmrc');
-
-// The HTTP User-Agent the manifest conversion stamps its GitHub call with (GitHub
-// requires a UA). Overridable so a fork can identify itself; not secret.
-const MANIFEST_UA = process.env.PROVISION_GITHUB_UA || 'cloudbongos-provisioner';
-
-// The running core version (no caret) — for naming the vendored tarball the standalone
-// scaffold pins. Fail-soft (a partial checkout returns null; the scaffold then errors
-// with guidance rather than pinning a `…-null.tgz`). Mirrors init.js coreVersionSafe().
-function coreVersionSafe() {
-  try { return require(path.join(REPO_ROOT, 'src/module-api')).CORE_VERSION; } catch { return null; }
-}
-
-function numEnv(name, dflt) {
-  const v = process.env[name];
-  if (v == null || v === '') return dflt;
-  const n = Number(v);
-  return Number.isFinite(n) && n > 0 ? n : dflt;
-}
-// A boolean env flag: '1'/'true'/'yes'/'on' (case-insensitive) → true, else false.
-function boolEnv(name) {
-  return /^(1|true|yes|on)$/i.test(String(process.env[name] || '').trim());
-}
-function hasFlag(args, name) { return args.includes(name); }
-
-const CONFIG = {
-  // The port range a CO-TENANT instance process binds on the shared box. 3000 (OTB)
-  // and 3002 (cloudbongos.com) are taken; new co-tenant instances start at 3003.
-  portBase: numEnv('PROVISION_PORT_BASE', 3003),
-  reservedPorts: (process.env.PROVISION_RESERVED_PORTS || '3000,3001,3002')
-    .split(',').map((s) => Number(s.trim())).filter(Number.isFinite),
-  // Where a per-instance secrets file lives: /etc/<slug>/web.env (the standup
-  // runbook's /etc/cloudbongos/web.env shape). chmod 600, OUTSIDE the repo.
-  etcBase: process.env.PROVISION_ETC_BASE || '/etc',
-  // The dir holding per-instance Caddy site snippets. Each instance gets its OWN
-  // <slug>.caddy file (idempotent overwrite, no fragile append to a shared file);
-  // the main Caddyfile carries a one-time `import <dir>/*.caddy` (operator setup).
-  caddySnippetDir: process.env.PROVISION_CADDY_SNIPPET_DIR || '/etc/caddy/sites',
-  // Where nightly pg_dump backups land (db-backup-nightly.sh's GDS_BACKUP_DIR
-  // default). Shared across co-tenant instances on one box — dumps are named
-  // `<db>-<ts>.sql.gz`, so each instance's files + retention prune stay scoped to
-  // its own DB. Owned by the app user, mode 0750. (task 2213, productizes 2210.)
-  backupDir: process.env.PROVISION_BACKUP_DIR || '/var/backups/gds',
-  // Dedicated-droplet defaults (only used for hosting_shape='dedicated').
-  region: process.env.PROVISION_REGION || 'nyc3',
-  baseImage: process.env.PROVISION_BASE_IMAGE || 'ubuntu-24-04-x64',
-  tag: process.env.PROVISION_TAG || 'cloudbongos-instance',
-  doToken: process.env.DO_API_TOKEN || null,
-  sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
-  // The Cloudflare DNS hook (the SAME infra/box-dns-cloudflare.sh box.js uses).
-  // P4 (#1945) formalizes the UPSERT: point the instance's domain at the target
-  // public IP (below), in the domain's OWN Cloudflare zone, proxied=false (see
-  // dnsUpsertEnv). No hook configured → DNS is skipped (a co-tenant instance is
-  // still reachable by IP; TLS then can't be issued until DNS lands).
-  dnsHook: process.env.BOX_DNS_HOOK || null,
-  // This box's PUBLIC IP — the A-record target for a CO-TENANT instance's domain.
-  // Set in the control-plane /etc/<inst>/box.env (never the web tier). A dedicated
-  // instance instead points its A record at the freshly-created droplet's IP. Under
-  // remote-exec (PROVISION_REMOTE_HOST) this is the CO-HOSTING box's IP — where the
-  // co-tenant actually runs (ADR 0130).
-  publicIp: process.env.PROVISION_PUBLIC_IP || process.env.BOX_PUBLIC_IP || null,
-  // The CONTROL PLANE's OWN public IP — the A-record target for a STANDALONE instance
-  // (task 2074). A standalone runs control-plane-LOCAL (its scaffolded repo dir lives
-  // here, not on the remote co-hosting box), so its domain must point at THIS box, not
-  // at publicIp (which, under remote-exec, is the co-hosting box). Only needed when
-  // remote-exec splits the two boxes; all-local (no remoteHost) falls back to publicIp
-  // since the control plane and the run box are then the same machine.
-  controlPlaneIp: process.env.PROVISION_CONTROL_PLANE_IP || null,
-  // Parent dir for a STANDALONE instance's OWN repo checkout (hosting_shape='standalone',
-  // ADR 0108): each lives at <standaloneBase>/<slug> with @bongos/core installed as
-  // an npm dep. Distinct from co-tenant (which shares THIS control-plane checkout).
-  standaloneBase: process.env.PROVISION_STANDALONE_BASE || '/srv/cloudbongos',
-  // ── Privilege escalation (task 2066, ADR 0128) ───────────────────────────
-  // The intent runner runs as a NON-root user (provision-intent-runner.service:
-  // User=lars) that holds passwordless sudo. That user cannot itself write under
-  // /etc, reload systemd/Caddy, or peer-auth to Postgres as a superuser — so the
-  // runbook steps below FAIL as bare commands (the goal-35 blocker). With
-  // PROVISION_SUDO=1 (alias PROVISION_PRIVILEGED=1) the privileged steps escalate:
-  //   • /etc writes         → temp file (lars-writable) + `sudo install -D -m <mode>`
-  //   • systemctl / rm /etc  → `sudo …`
-  //   • createdb / migrate   → `sudo -u postgres …` (postgres peer-auths as the PG
-  //     superuser — the Ubuntu default — so it never needs `lars` to be a PG role)
-  // OFF (default) preserves the run-as-root / test / co-tenant-legacy behavior
-  // (bare commands, direct fs writes), so nothing outside a sudo context changes.
-  // Dry-run ALWAYS logs the exact command either way. NB: the runner unit must NOT
-  // set NoNewPrivileges=true — it blocks sudo (see infra/provision-intent-runner.service).
-  privileged: boolEnv('PROVISION_SUDO') || boolEnv('PROVISION_PRIVILEGED'),
-  // ── Remote orchestration over SSH (task 2065, ADR 0130) ──────────────────
-  // The token-separation endgame (ADR 0126): run this runner ON the token-holding
-  // control-plane box, and have it drive co-tenant workloads that still LIVE on the
-  // co-hosting box over SSH — so the co-hosting box can hold ZERO cloud tokens.
-  // When PROVISION_REMOTE_HOST is set, the BOX-MUTATING steps (createdb, migrate,
-  // /etc writes, systemctl, Caddy, healthz) run on that host over `ssh`; the
-  // TOKEN step (the Cloudflare DNS hook) + the standalone repo scaffold STAY local
-  // on the control plane, where the token + the packaging tools live. UNSET
-  // (default) = every step runs locally, byte-identical to today.
-  remoteHost: process.env.PROVISION_REMOTE_HOST || null,
-  // The co-hosting box's checkout dir — the remote migrate's cwd. NO baked-in default
-  // (task 1002756: the founder-pinned path was an identity leak, and a silent wrong
-  // cwd aims mutating SSH steps at a dir that may not exist); remote mode requires it
-  // explicitly (guarded at the makeExec call), local mode never reads it.
-  remoteCwd: process.env.PROVISION_REMOTE_CHECKOUT || null,
-  // ssh options for the control-plane → co-hosting hop. BatchMode so a missing key
-  // fails fast (never hangs on a prompt); accept-new pins the host key on first
-  // connect (the operator can pre-seed known_hosts for strict pinning).
-  sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
-};
-
-// task 1002757 — the provisioner's git identity resolves from the instance's own
-// apex (env → bot@<apex> → neutral), never the hub's address hardcoded.
-const { provisionerBotEmail } = require('./instance-apex');
-
-const MAX_INTENT_ATTEMPTS = numEnv('PROVISION_INTENT_MAX_ATTEMPTS', 3);
-
-// Manifest-placement verification budget (task 1002720 / QA-walk F23): a child
-// instance is a full Node boot away from reporting auth_configured=true, and the
-// old 10×1s poll routinely lost that race — recording a failure for a setup that
-// succeeded, then burning the SINGLE-USE manifest code on the retry. ~3 min of
-// patience; the poll runs after the intent loop, so it delays nothing.
-const MANIFEST_VERIFY_TRIES = numEnv('PROVISION_MANIFEST_VERIFY_TRIES', 90);
-const MANIFEST_VERIFY_INTERVAL_MS = numEnv('PROVISION_MANIFEST_VERIFY_INTERVAL_MS', 2000);
-
-// ---------------------------------------------------------------------------
-// Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
-// ---------------------------------------------------------------------------
-let _deps;
-function loadDeps() {
-  if (_deps) return _deps;
-  // eslint-disable-next-line global-require
-  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
-  // eslint-disable-next-line global-require
-  const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning'));
-  // eslint-disable-next-line global-require
-  const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
-  // Cross-site identity (ADR 0141 §4, task #1002109). Resolve the hub-side module by a
-  // VARIABLE key, gated on isModuleEnabled — the module-loader's own dynamic-dispatch
-  // pattern (the run-unit-tests.js precedent), NOT a static 'modules/platform-identity/'
-  // literal that would couple this publishable core file to an instance-EXCLUDED module
-  // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
-  // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
-  // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
-  let platformIdentity = null, hubKeys = null;
-  const PI_KEY = 'platform-identity';
-  let piEnabled = false;
-  try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
-  if (piEnabled) {
-    const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
-    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
-    catch { platformIdentity = null; hubKeys = null; }
-  }
-  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
-  return _deps;
-}
-
-// ---------------------------------------------------------------------------
-// PURE step-command generators (exported for tests). Each returns the exact shell
-// command a runbook step runs. Kept pure so local exec (co-tenant) and the
-// dedicated droplet's cloud-init both build from ONE source of truth.
-// ---------------------------------------------------------------------------
-
-// A slug is validated DNS/db-safe upstream (provisioning.isValidSlug), so it is
-// already shell-safe (only [a-z0-9-]). We still never interpolate untrusted text.
-function dbName(inst) { return inst.db_name || inst.slug; }
-
-// Escalate a DB command to run as the postgres OS user (→ PG superuser via peer auth,
-// the Ubuntu default) when privileged — the DB-auth fix (task 2066). The runner's
-// `lars` is not a usable PG role, so bare peer-auth-as-lars fails; `sudo -u postgres`
-// sidesteps it without granting lars a role. PURE given the flag.
-function asPostgres(cmd, privileged) { return privileged ? `sudo -u postgres ${cmd}` : cmd; }
-
-function dbCreateCmd(inst, { privileged = false } = {}) {
-  // Idempotent: the caller runs it allowFail — "database already exists" is success.
-  // Non-privileged = bare `createdb` (peer auth as the running user, same as the
-  // standup runbook / OTB); privileged = `sudo -u postgres createdb` (task 2066).
-  return asPostgres(`createdb ${dbName(inst)}`, privileged);
-}
-function migrateCmd(inst, { privileged = false } = {}) {
-  // GDS-only schema — skips migrations/game/*.sql (no game tables on a vanilla
-  // instance), per the standup runbook (ADR 0105 instance seeds off). Privileged
-  // runs migrate as postgres (task 2066): `sudo` resets env, so the PGDATABASE/
-  // MEDUSA_GDS_ONLY vars ride `env …` and the script runs via `bash …` (a bare
-  // `VAR=val ./script` would be parsed BY sudo as a command). Precondition: the
-  // control-plane checkout must be readable by the postgres user (ADR 0128).
-  return privileged
-    ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ./scripts/migrate.sh`
-    : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh`;
-}
-
-// Seed the instance's FIRST version so it can take tasks from minute one (task 2119,
-// goal 35). A freshly-migrated instance DB comes up with an EMPTY versions table —
-// migrate runs instance-seeds-off (ADR 0105) and `bongos init` ran --no-seed — yet
-// every task requires a version (tasks.version_id NOT NULL) and POST /versions is
-// Archon-only (no Archon exists until first sign-in). Without a seed here, a brand-new
-// project has NOWHERE to file a task. This runs on the box's DB path (no rank gate),
-// ONLY IF the versions table is empty: idempotent, safe to re-run, and it never
-// disturbs a project that already has versions. Mirrors seedViaApi's shape — V1
-// (status 'building') + one done-when criterion so /status has a finish line from day
-// one. `track` is set EXPLICITLY: versions.track is NOT NULL with no default (mig 112
-// dropped the CHECK), and 'product' matches the canonical V1 seed in 003_pms.sql.
-//
-// The id/name/done_when come from instanceInitSpec so the starter version has ONE
-// source of truth (the same spec the greenfield `bongos init` seed uses). SQL string
-// literals are DOLLAR-QUOTED ($v$…$v$) so the whole -c argument is single-quoted —
-// the one form that is safe UNCHANGED across all three executors: inline (/bin/sh),
-// over SSH (bash -s), AND embedded in a dedicated droplet's cloud-init (bash -lc "…"),
-// with no nested-quote or $-expansion hazard.
-function seedFirstVersionCmd(inst, { privileged = false } = {}) {
-  const v = instanceInitSpec(inst).version;
-  const q = (s) => `$v$${s}$v$`;                 // dollar-quoted literal (no value contains a single quote or $)
-  const sql =
-    `INSERT INTO versions (id, name, track, status, done_when) ` +
-    `SELECT ${q(v.id)}, ${q(v.name)}, $v$product$v$, $v$building$v$, ${q(v.done_when)} ` +
-    `WHERE NOT EXISTS (SELECT 1 FROM versions); ` +
-    `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order) ` +
-    `SELECT ${q(v.id)}, $v$first-goal$v$, ${q(v.done_when)}, 10 ` +
-    `WHERE EXISTS (SELECT 1 FROM versions WHERE id = ${q(v.id)}) ` +
-    `AND NOT EXISTS (SELECT 1 FROM done_when_criteria WHERE version_id = ${q(v.id)} AND criterion_id = $v$first-goal$v$);`;
-  return asPostgres(`psql -v ON_ERROR_STOP=1 -d ${dbName(inst)} -c '${sql}'`, privileged);
-}
-
-// ── STANDALONE shape (hosting_shape='standalone', ADR 0108, task 1978) ────────
-// A standalone instance runs from its OWN repo checkout (host content: config/,
-// migrations/instance/, the core PIN in package.json) with @bongos/core installed
-// as an npm DEPENDENCY — NOT the shared control-plane checkout the co-tenant shape uses.
-// It is the ADR 0108 DESTINATION model; these generators make provision.js drive the
-// scripts/deploy/deploy-instance.sh runbook API-driven instead of by hand.
-const CORE_PKG_DIR = 'node_modules/@bongos/core';
-// The unix account the instance's Node process + its backup timer run as. Mirrors
-// serviceUnit's hardcoded `User=lars`/`Group=lars` (the droplet's app user); kept as
-// one constant so the backup dir owner + the backup unit's User= can't drift from it.
-const APP_USER = 'lars';
-function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return path.posix.join(base, inst.slug); }
-// Sync the instance's own repo (host content + the core pin). Mirrors deploy-instance.sh
-// step 1 — assumes the repo is already cloned at standaloneRoot (initial clone is a
-// precondition, like the runbook's `git pull`). Run with cwd = standaloneRoot.
-function standalonePullCmd() { return `git pull --ff-only origin main`; }
-// Install the pinned core + instance deps — replaces co-tenant's shared checkout
-// (deploy-instance.sh step 2). Run with cwd = standaloneRoot.
-function standaloneInstallCmd() { return `npm ci --omit=dev`; }
-// Migrate core + instance from the INSTANCE root's copy of the three-root migrate.sh
-// (the installed core's, falling back to an in-tree copy — deploy-instance.sh step 3).
-// Run with cwd = standaloneRoot.
-function standaloneMigrateCmd(inst, { privileged = false } = {}) {
-  // Privileged: run as postgres (task 2066), passing env via `env …` so it survives
-  // sudo's env reset (the instance root must be postgres-readable, ADR 0128).
-  return privileged
-    ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`
-    : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`;
-}
-// Regenerate the instance's whole-file navigation docs (session-log index) from the pinned core,
-// AFTER the pull+install+migrate — the standalone analogue of the monorepo's deploy-prod.sh regen
-// block (ADR 0110 §2, task 1002314). Best-effort + LOUD (the script always exits 0 + prints
-// ::ERROR:: on a generator failure) so a stale/absent nav doc never fails a deploy. Run with
-// cwd = standaloneRoot so resolveInstanceRoot() writes into the instance repo. Without this a
-// standalone instance's docs never refresh on deploy — the gap the owner hit ("docs didn't
-// transfer from primea"): its bespoke pull-deploy regenerated nothing.
-function standaloneRegenDocsCmd() { return `node ${CORE_PKG_DIR}/scripts/gds/regen-instance-docs.js`; }
-
-// ── STANDALONE scaffold (ADR 0108 / 0125, task 2055) ──────────────────────────
-// The MISSING first leg of the greenfield "one guided flow": provision.js used to
-// THROW if the instance repo wasn't already cloned. These generate + run the scaffold
-// that clones an EMPTY target_ref and turns it into an installable, bootable instance.
-
-// Parse an 'owner/repo' (or a github SSH/HTTPS URL) target_ref → { owner, name }.
-// Null when unparseable, so the scaffold can fail with actionable guidance.
-function parseTargetRef(ref) {
-  const m = String(ref || '').trim()
-    .replace(/^git@[^:]+:/, '')
-    .replace(/^https?:\/\/[^/]+\//, '')
-    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/);
-  return m ? { owner: m[1], name: m[2] } : null;
-}
-
-// The git remote for an instance's OWN repo. Reuses the SAME SSH deploy alias the
-// control-plane checkout uses (git@<alias>:<owner>/<repo>.git) — NO secret in the
-// command (SSH-key auth, nothing to leak into journald), consistent with how the
-// platform repo is wired. Standing up a new instance repo therefore needs only that
-// the control plane's deploy key has WRITE access to that repo (ADR 0125). Alias is
-// overridable via PROVISION_GIT_SSH_ALIAS.
-function instanceRepoRemote(repo, { sshAlias = process.env.PROVISION_GIT_SSH_ALIAS || 'github-deploy' } = {}) {
-  return `git@${sshAlias}:${repo.owner}/${repo.name}.git`;
-}
-
-// A minimal, VALID `bongos init` spec (init.validateSpec greenfield) from the
-// provisioning row + the owner's github login. The scaffold produces a bootable,
-// NEUTRAL instance; the owner brands + scopes it later via init's kickoff tasks.
-function instanceInitSpec(inst, { ownerLogin } = {}) {
-  const repo = parseTargetRef(inst.target_ref);
-  return {
-    identity: { productName: inst.slug },
-    repo: repo || { owner: ownerLogin || 'owner', name: inst.slug },
-    firstAdmin: ownerLogin || (repo && repo.owner) || 'owner',
-    currency: { label: 'credits' },
-    domains: { publicOrigin: inst.domain ? `https://${inst.domain}` : `http://localhost:${inst.port || 3000}` },
-    modules: [],
-    version: { id: 'V1', name: 'V1', done_when: 'A task goes claim → grade → ship.' },
-  };
-}
-
-// The .gitignore a scaffolded instance repo carries: keep node_modules + the local
-// dist/ + secrets OUT of the commit, while the vendored core tarball (vendor/*.tgz)
-// and package-lock.json stay IN — `npm ci` on deploy resolves the pinned core from
-// the committed tarball (ADR 0108), so they MUST be tracked.
-//
-// docs/session-log-index.md is a WHOLE-FILE generated navigation doc (ADR 0110): every byte is
-// machine-owned, regenerated at deploy by regen-instance-docs.js (task 1002314) into the served
-// tree. Untracked so `git reset --hard origin/main` never wipes it and no branch can diff it —
-// the same reasoning the core's own .gitignore applies to it. (docs/repo-map.md is listed for
-// parity/forward-compat; it is core-scoped today so a standalone instance doesn't generate its
-// own — see regenerateNavDocs() in upgrade.js — but ignoring it costs nothing and prevents a
-// stray future write from entering the tree.)
-const INSTANCE_GITIGNORE = [
-  'node_modules/', 'dist/', '.env', '.env.local', '*.log',
-  '# Whole-file generated navigation docs — regenerated at deploy (ADR 0110, task 1002314).',
-  'docs/session-log-index.md', 'docs/repo-map.md', '',
-].join('\n');
-
-// A PRE-BUILT @bongos/core tarball this control plane can vendor into a NEW instance
-// WITHOUT rebuilding from source — the consumer-control-plane fix (task 1002275).
-//
-// The scaffold's default core-install path rebuilds the tarball with package-core.js,
-// which enumerates GIT-TRACKED files (`git -C REPO_ROOT ls-tree`). That works from a core
-// SOURCE checkout, but NOT when this runner is ITSELF a consumer instance whose core is an
-// installed npm dependency: provision.js then runs out of node_modules/@bongos/core, so
-// REPO_ROOT points INSIDE gitignored node_modules, git sees ZERO tracked files there, and
-// package-core aborts ("the core set is EMPTY") — the scaffold never pushes and the freshly
-// created repo is left EMPTY (seen live: trial/test on cloudbongos.com).
-//
-// But the exact pinned tarball this instance installed FROM is on disk, named by its own
-// package.json ("@bongos/core": "file:vendor/bongos-core-<v>.tgz"). Reuse it: byte-identical,
-// already proven, and the child pins the SAME core the hub runs. Returns an absolute .tgz
-// path, or null on a source checkout (no `file:` core pin) — where package-core.js is the
-// right, unchanged path. `instanceRoot` defaults to $BONGOS_INSTANCE_ROOT (what
-// infra/core-node.sh resolves against) else process.cwd() (the runner's WorkingDirectory).
-// fs injectable for tests. PURE-ish (fs reads only, no mutation → dry-run safe).
-function installedCoreTarball({ instanceRoot, fsImpl = fs } = {}) {
-  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
-  let pkg;
-  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
-  catch { return null; }               // no/unreadable package.json → treat as a source checkout
-  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
-  // Both scope aliases the loader accepts (infra/core-node.sh checks the same two).
-  for (const name of ['@bongos/core', '@cloudbongos/core']) {
-    const m = /^file:(.+\.tgz)$/.exec(String(deps[name] || '').trim());
-    if (m) {
-      const abs = path.resolve(root, m[1]);
-      if (fsImpl.existsSync(abs)) return abs;   // a dangling pin (tarball pruned) → fall through to null
-    }
-  }
-  return null;
-}
-
-// The REGISTRY-pinned sibling of installedCoreTarball (task 1002706). After a control
-// plane moves its own core pin off the vendored tarball onto the npm registry (the
-// cloudbongos.com cutover, task 1002621), its package.json holds a semver pin — no
-// `file:` — so installedCoreTarball returns null and the scaffold would fall into the
-// package-core.js source rebuild, which ABORTS on a consumer instance (the empty-set
-// abort of task 1002275, resurrected by the cutover). The installed package itself is
-// still the exact core this hub runs: return its node_modules dir + version + the
-// `npm pack` tarball name so the scaffold can pack it into a vendorable .tgz. The child
-// stays file:-pinned — its owner needs no npm token (the registry package is PRIVATE
-// until the ADR 0134 go-public step). Returns { dir, version, tarballName } or null
-// (a file: pin, an uninstalled dep, or a source checkout). fs reads only → dry-run safe.
-function installedCorePackDir({ instanceRoot, fsImpl = fs } = {}) {
-  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
-  let pkg;
-  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
-  catch { return null; }               // no/unreadable package.json → a source checkout
-  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
-  for (const name of ['@bongos/core', '@cloudbongos/core']) {
-    const spec = String(deps[name] || '').trim();
-    if (!spec || spec.startsWith('file:')) continue;   // file: pins belong to installedCoreTarball
-    const dir = path.join(root, 'node_modules', ...name.split('/'));
-    try {
-      const installed = JSON.parse(fsImpl.readFileSync(path.join(dir, 'package.json'), 'utf8'));
-      const version = installed && installed.version ? String(installed.version) : null;
-      if (!version) continue;
-      // npm pack names a scoped tarball <scope>-<name>-<version>.tgz (no @, / → -).
-      const base = String(installed.name || name).replace(/^@/, '').replace(/\//g, '-');
-      return { dir, version, tarballName: `${base}-${version}.tgz` };
-    } catch { /* pinned but not installed → fall through */ }
-  }
-  return null;
-}
-
-// Resolve a vendorable @bongos/core tarball — the three-rung ladder, freshest-correct
-// first, shared by the fresh scaffold and the re-provision pin refresh (task 1003050):
-//   1. a `file:`-pinned control plane reuses its own pinned tarball (task 1002275 —
-//      rebuilding via package-core.js aborts with an EMPTY core set when this runner
-//      IS a consumer instance, leaving new repos empty);
-//   2. a REGISTRY-pinned consumer (the post-1002621 mothership shape) packs the core
-//      it has INSTALLED — the child pins the SAME, CURRENT core the hub runs, ending
-//      the frozen-old-tarball births (task 1002706, gap 13) without requiring the
-//      child's owner to hold a token for the still-private registry package;
-//   3. a genuine core source checkout rebuilds fresh via package-core.js.
-// Returns { tgz, packDest } — packDest (set only on rung 2) is a temp dir the CALLER
-// must `rm -rf` once the tarball has been vendored.
-function resolveVendorableCoreTarball({ instanceRoot, exec, log, coreV, tag = '[core]' }) {
-  let tgz = installedCoreTarball({ instanceRoot });
-  let packDest = null;
-  if (tgz) {
-    log(`  ${tag} reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
-  } else {
-    const packSrc = installedCorePackDir({ instanceRoot });
-    if (packSrc) {
-      // Keyed by VERSION, not slug: no request-derived value enters this command, and
-      // two concurrent scaffolds of the same core pack identical bytes — collision-safe.
-      packDest = path.join(os.tmpdir(), `bongos-core-pack-${packSrc.version}`);
-      log(`  ${tag} packing the registry-installed core this control plane runs (v${packSrc.version}) — no source rebuild (task 1002706)`);
-      exec(`mkdir -p ${packDest}`);
-      exec(`npm pack ${packSrc.dir} --pack-destination ${packDest}`);
-      tgz = path.join(packDest, packSrc.tarballName);
-    } else {
-      log(`  ${tag} building a fresh vendored tarball from source (package-core.js)`);
-      exec(`node scripts/gds/package-core.js`);                    // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
-      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
-    }
-  }
-  return { tgz, packDest };
-}
-
-// The onboard mode a provisioning row carries (migration provisioning_004, task 1002562).
-// 'adopt' means target_ref is a repo the owner ALREADY has, so the scaffold must LAYER
-// onto its history. Anything else — including a row written before the column existed, or
-// an unrecognized value — resolves to 'greenfield', deliberately the SAFE direction:
-// greenfield pushes a fresh tree and (carrying no --force) is REJECTED by a repo with
-// history, whereas wrongly choosing 'adopt' would start rewriting a repo nobody declared.
-function onboardMode(inst) {
-  return String((inst && inst.onboard_mode) || '') === 'adopt' ? 'adopt' : 'greenfield';
-}
-
-// Has the scaffold already completed in `root`? The marker is MODE-DEPENDENT, and reusing
-// the greenfield one for adopt is a real bug: greenfield's marker is "package.json exists"
-// (a fresh empty repo has none until we scaffold it), but an adopted repo is an existing
-// project that almost certainly HAS a package.json already — so the greenfield check would
-// report "already scaffolded" on the very first run and the instance would never become
-// bootable. For adopt the honest marker is the thing the layering itself contributes: a
-// @bongos/core dependency (both scope aliases the loader accepts, matching
-// installedCoreTarball). fs injectable for tests; read-only, so dry-run safe.
-function alreadyScaffolded(root, mode, { fsImpl = fs } = {}) {
-  const pkgPath = path.join(root, 'package.json');
-  if (!fsImpl.existsSync(pkgPath)) return false;
-  if (mode !== 'adopt') return true;
-  let pkg;
-  try { pkg = JSON.parse(fsImpl.readFileSync(pkgPath, 'utf8')); }
-  catch { return false; }   // unparseable → let the adopt layer report it, don't skip
-  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
-  return !!(deps['@bongos/core'] || deps['@cloudbongos/core']);
-}
-
-// Materialize + push the instance's own repo. TWO paths, chosen by onboard_mode:
-//
-//   greenfield — the target_ref repo is EMPTY (github-repos.createUserRepo makes it with
-//                auto_init:false), so there is nothing to clone: `git init` locally,
-//                materialize, and push the first commit at main.
-//   adopt      — the target_ref repo is the owner's OWN existing project. CLONE it (so its
-//                history and files come along), LAYER the instance config additively via
-//                `bongos init --adopt --accept` (which never overwrites a pre-existing
-//                file), and push the layer commit as an ordinary fast-forward on top.
-//
-// Both end at a repo carrying config/ + .claude/ + a file:-pinned @bongos/core + lockfile,
-// which is what makes it `npm ci --omit=dev`-installable by the rest of provisioning.
-//
-// NEITHER PATH EVER USES --force. That is a safety property, not an oversight: since ADR
-// 0155 the credential here can write to every repo the owner owns, so a force-push would
-// be a route to destroying a user's work. A rejected push is the correct, recoverable
-// outcome. Asserted by tests.
-//
-// Idempotent (see alreadyScaffolded) and dry-run safe (every mutation goes through the
-// injected exec/writeFile). ADR 0108 / 0121 / 0125.
-async function scaffoldStandaloneRepo(inst, deps) {
-  // The scaffold BUILDS + pushes the instance's repo (git clone, package-core,
-  // `bongos init`, git push) — control-plane work that needs the packaging tools +
-  // the GitHub deploy key, so it runs LOCALLY even when box-mutating steps go
-  // remote (task 2065). Falls back to exec/writeFile when a caller passes no
-  // control executor (then all are the same local executor — unchanged behavior).
-  const { db, log } = deps;
-  const exec = deps.controlExec || deps.exec;
-  const writeFile = deps.controlWriteFile || deps.writeFile;
-  const root = standaloneRoot(inst);
-  const repo = parseTargetRef(inst.target_ref);
-  const mode = onboardMode(inst);
-  if (!repo) {
-    throw new Error(`standalone instance ${inst.slug}: target_ref "${inst.target_ref || '(unset)'}" is not an owner/repo — set it (e.g. <owner>/${inst.slug}) so the scaffold knows which repo to clone + push.`);
-  }
-  if (alreadyScaffolded(root, mode)) {
-    log(`  [scaffold] ${root} already scaffolded (mode=${mode}) — skipping`);
-    return { already: true };
-  }
-  const coreV = coreVersionSafe();
-  if (!coreV) {
-    throw new Error('cannot resolve the core version (src/module-api CORE_VERSION) — run the scaffold from the control-plane checkout.');
-  }
-  const remote = instanceRepoRemote(repo);
-  log(mode === 'adopt'
-    ? `  [scaffold] ${repo.owner}/${repo.name} → ${root} (ADOPT: clone → layer additively → pin core ${coreV} → commit → fast-forward push)`
-    : `  [scaffold] ${repo.owner}/${repo.name} → ${root} (clone → materialize → pin core ${coreV} → commit → push)`);
-
-  // Owner login = the founding firstAdmin. Best-effort; the spec falls back to the repo owner.
-  let ownerLogin = null;
-  if (inst.owner_builder_id && db) {
-    try {
-      const r = await db.query('SELECT github_login FROM builders WHERE id = $1', [inst.owner_builder_id]);
-      ownerLogin = r && r.rows && r.rows[0] ? r.rows[0].github_login : null;
-    } catch { /* fall back to the repo owner */ }
-  }
-
-  // Resolve the instance owner's OAuth token BEFORE any git network op.
-  //
-  // Greenfield only needed it at PUSH time, so the lookup used to live down beside the
-  // push. Adopt needs it EARLIER: its first act is to clone the owner's own repo, and a
-  // PRIVATE one is unreadable by the control plane's shared deploy key (a deploy key is
-  // per-repo). Since ADR 0155 this token carries the `repo` scope, so it can both read and
-  // write the owner's private repos — which is what makes adopt possible at all.
-  //
-  // A GitHub DEPLOY KEY is per-repo, so the box's shared key also can't WRITE to a new
-  // project repo — the second empty-repo cause (task 1002317) — hence preferring this
-  // token on both paths. It rides a chmod-600 git credential-store file, never the logged
-  // command or makeExec's env (makeExec surfaces both), and is removed in a `finally` so a
-  // failed git op can't leave it on disk. No token (org-owned repo, or secret-box off) →
-  // fall back to the SSH `origin` remote.
-  const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[scaffold]' });
-  // The credential-store file + the credential-LESS URL git resolves against it. The URL
-  // carries only the `x-access-token` username (no secret), so it is safe in a logged argv.
-  const credFile = ownerToken ? path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`) : null;
-  const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
-  const credOpt = credFile ? `-c credential.helper='store --file=${credFile}' ` : '';
-  if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
-
-  try {
-    // 1. Materialize the working tree.
-    //
-    //    ADOPT — CLONE the owner's existing repo, so its history + files come along and the
-    //    layer commit lands as an ordinary descendant of its current tip. This is the whole
-    //    point: `git init`ing a fresh tree here produces an UNRELATED history, which the
-    //    remote rejects as a non-fast-forward (and, were it ever forced, would erase the
-    //    owner's work). Cloning over the token's HTTPS URL also covers the private case the
-    //    shared deploy key cannot read.
-    //
-    //    GREENFIELD — a freshly-created instance repo is EMPTY (github-repos.createUserRepo,
-    //    auto_init:false), so there is NOTHING to clone; and the shared PROVISION_GIT_SSH_ALIAS
-    //    deploy key can't even READ a consumer's brand-new repo under their own account
-    //    (`git clone` fails "Repository not found" — the clone-side twin of the task-1002317
-    //    push bug). So `git init` locally and set `origin` to the SSH remote for the no-token
-    //    fallback push. Unchanged behavior.
-    //
-    //    Either way a re-run after a partial attempt reuses the existing dir.
-    const hasGit = fs.existsSync(path.join(root, '.git'));
-    if (mode === 'adopt') {
-      if (!hasGit) {
-        exec(`mkdir -p ${root}`);
-        exec(`git ${credOpt}clone ${credFile ? httpsUrl : remote} ${root}`);
-        // Normalize `origin` to the SSH remote, matching what the greenfield path leaves
-        // behind. Two reasons: the clone URL would otherwise persist as origin, and the
-        // ongoing deploy (standalonePullCmd → `git pull --ff-only origin main`, and the box
-        // timer's `git reset --hard origin/main`) reads origin — it must be a form that can
-        // authenticate durably, which the one-shot token URL cannot (its credential file is
-        // deleted below). Nothing durable ever holds the token either way; the pushes here
-        // always pass an explicit URL.
-        if (credFile) exec(`git -C ${root} remote set-url origin ${remote}`);
-      } else {
-        exec(`git -C ${root} ${credOpt}fetch ${credFile ? httpsUrl : 'origin'} main`);
-      }
-      // The rest of provisioning is main-only (standalonePullCmd is `git pull --ff-only
-      // origin main`, and the box's deploy timer does `git reset --hard origin/main`), so a
-      // repo whose default branch is not `main` would be layered and pushed somewhere the
-      // deploy never reads. Fail loudly with the fix rather than silently half-working.
-      const head = exec(`git -C ${root} rev-parse --abbrev-ref HEAD`, { allowFail: true });
-      const branch = String((head && head.stdout) || '').trim();
-      if (branch && branch !== 'main' && branch !== 'HEAD') {
-        throw new Error(`standalone instance ${inst.slug}: adopting ${repo.owner}/${repo.name} but its default branch is "${branch}", not "main". The instance deploy only ever reads origin/main, so the layer would never be served. Rename the default branch to main (or point target_ref at a repo whose default is main) and re-run.`);
-      }
-      exec(`git -C ${root} checkout main`, { allowFail: true });
-    } else {
-      if (!hasGit) {
-        exec(`mkdir -p ${root}`);
-        exec(`git -C ${root} init -q`);
-        exec(`git -C ${root} remote add origin ${remote}`);
-      }
-      exec(`git -C ${root} checkout -B main`);
-    }
-
-    // Core-install path (ADR 0134, task 2090). DEFAULT = vendor a tarball built from THIS
-    // control-plane checkout (offline, proven — task 2053). OPT-IN = pull the PRIVATE
-    // @bongos/core from the npm registry (PROVISION_CORE_FROM_REGISTRY=1). The registry
-    // path needs NPM_TOKEN at `npm ci` time; if the flag is set but no token is present we
-    // FAIL SOFT to the vendored path so a tokenless standup still works (never a broken
-    // instance). The env is injectable for tests; the runner falls back to process.env.
-    const env = deps.env || process.env;
-    const wantRegistry = registryCoreRequested(env);
-    const useRegistry = wantRegistry && hasNpmToken(env);
-    if (wantRegistry && !useRegistry) {
-      log('  [scaffold] PROVISION_CORE_FROM_REGISTRY set but no NPM_TOKEN in env — falling back to the vendored-tarball core (ADR 0134 fail-soft).');
-    }
-
-    // materialize config/ + .claude/ + a pinned package.json + lockfile via `bongos init`.
-    // --no-seed: the instance's own DB is seeded by migrate, not here (and on the adopt path
-    // the REAL-state seeding + backlog import happen when the owner runs `bongos init --adopt`
-    // themselves, against the live instance — the step the wizard walks them through).
-    //
-    // MODE FLAGS. Greenfield passes --force (overwrite is safe on an empty repo). Adopt passes
-    // --adopt --accept instead and NEVER --force: --adopt takes init's layering path, which
-    // writes each config only where absent and leaves pre-existing files untouched, and
-    // --accept clears the interactive pre-flight gate for this non-interactive runner (a
-    // BLOCKING pre-flight finding still hard-stops — it cannot be waved through). init refuses
-    // --adopt together with --force, so the two flag sets are mutually exclusive by design.
-    //
-    // Two mutually exclusive core-resolution shapes, orthogonal to the mode:
-    //   registry (--registry-core): caret pin + env-fed .npmrc; `npm ci` pulls from the
-    //     registry. init generates the lockfile (NPM_TOKEN is present — we gated on it).
-    //   vendored (--vendor-core, default): a tarball built from this checkout, file:-pinned.
-    const modeFlags = mode === 'adopt' ? '--adopt --accept' : '--force';
-    const spec = instanceInitSpec(inst, { ownerLogin });
-    const specPath = path.join(os.tmpdir(), `bongos-init-${inst.slug}.json`);
-    writeFile(specPath, JSON.stringify(spec, null, 2));
-    if (useRegistry) {
-      log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
-      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --registry-core`);
-    } else {
-      // Vendored tarball — resolveVendorableCoreTarball's three-rung ladder (shared
-      // with the re-provision pin refresh, task 1003050).
-      const { tgz, packDest } = resolveVendorableCoreTarball({
-        instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[scaffold] core install:',
-      });
-      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --vendor-core ${tgz}`);
-      // init --vendor-core COPIED the tarball into the child's vendor/ — the temp pack dir is spent.
-      if (packDest) exec(`rm -rf ${packDest}`);
-    }
-
-    // 4. commit + push to the instance's own main (keep node_modules out).
-    //
-    // .gitignore: greenfield OWNS the file. Adopt must not clobber the owner's existing
-    // ignores, so it only writes one where none exists — and where one does, it APPENDS the
-    // entries we actually require (node_modules/, the vendored-core exceptions, the generated
-    // nav docs) if they are missing, since `npm ci` + `git reset --hard` on the box depend on
-    // them. Duplicate lines in a .gitignore are harmless, so the append is idempotent-safe.
-    const giPath = path.join(root, '.gitignore');
-    if (mode === 'adopt' && fs.existsSync(giPath)) {
-      const existing = fs.readFileSync(giPath, 'utf8');
-      const missing = INSTANCE_GITIGNORE.split('\n')
-        .filter((l) => l.trim() && !l.startsWith('#'))
-        .filter((l) => !existing.split('\n').some((e) => e.trim() === l.trim()));
-      if (missing.length) {
-        writeFile(giPath, `${existing.replace(/\n*$/, '\n')}\n# Added by Cloud Bongos (adopt) — required by the instance deploy.\n${missing.join('\n')}\n`);
-        log(`  [scaffold] appended ${missing.length} required .gitignore entr(ies) — existing rules left intact`);
-      } else {
-        log('  [scaffold] .gitignore already covers the required entries — left untouched');
-      }
-    } else {
-      writeFile(giPath, INSTANCE_GITIGNORE);
-    }
-    exec(`git -C ${root} config user.name "Cloud Bongos"`);
-    exec(`git -C ${root} config user.email "${provisionerBotEmail()}"`);
-    exec(`git -C ${root} add -A`);
-    const commitMsg = mode === 'adopt'
-      ? `chore: adopt Cloud Bongos onto ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0121)`
-      : `chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)`;
-    exec(`git -C ${root} commit -m "${commitMsg}"`, { allowFail: true });
-
-    // Push. NO --force on either path, ever (see the function header): the ADR 0155 `repo`
-    // credential can write to every repo the owner owns, so a force here would be a route to
-    // destroying their work. Adopt's commit is a descendant of the tip it cloned, so an
-    // ordinary push fast-forwards; if the remote moved underneath us the rejection is the
-    // correct outcome and a re-run picks up the new tip.
-    if (credFile) {
-      exec(`git -C ${root} ${credOpt}push ${httpsUrl} HEAD:main`);
-      log(`  [scaffold] ${mode === 'adopt' ? 'pushed the adopt layer' : 'pushed'} to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
-    } else {
-      exec(`git -C ${root} push -u origin main`);
-      log(`  [scaffold] pushed ${mode === 'adopt' ? 'the adopt layer' : 'initial scaffold'} to ${repo.owner}/${repo.name}@main (SSH origin)`);
-    }
-    return { ok: true, scaffolded: true, mode };
-  } finally {
-    // Always remove the credential file — a failed clone/push must not leave it on disk.
-    if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
-  }
-}
-
-// ── private-repo deploy key (ADR 0176, task 1002735; walk finding N4) ────────────
-
-// The instance owner's stored `repo`-scoped OAuth token (ADR 0155), or null (none
-// stored, org-owned repo, secret-box off). Shared by the scaffold push, the
-// private-repo deploy-key wiring, and the teardown revoke. `deps.getGithubToken` is
-// injectable for tests; production resolves it lazily against the core db slice
-// with the runner's pool.
-async function resolveOwnerGithubToken(inst, deps, { tag = '[repo-auth]' } = {}) {
-  if (!inst.owner_builder_id) return null;
-  try {
-    const fetchTok = deps.getGithubToken
-      || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db }));
-    const r = await fetchTok(inst.owner_builder_id);
-    return r && r.token ? r.token : null;
-  } catch (e) {
-    (deps.log || (() => {}))(`  ${tag} owner OAuth token lookup failed (${e && e.message})`);
-    return null;
-  }
-}
-
-function deployKeyTitle(inst) { return `cloudbongos-deploy-${inst.slug}`; }
-// Beside the checkout's own metadata: untracked by definition, survives the deploy's
-// `git reset --hard`, and dies with the checkout rather than accreting in ~/.ssh.
-function deployKeyPath(inst) { return path.posix.join(standaloneRoot(inst), '.git', 'cloudbongos-deploy-key'); }
-
-// Make a PRIVATE target_ref durably readable by the recurring deploy pull. The
-// owner's token covers only the ONE-SHOT clone/push (its credential file is deleted
-// after the scaffold), while `origin` rides the shared SSH alias — which GitHub
-// answers "Repository not found" for a private repo it isn't registered on. That
-// mismatch is walk finding N4: every private standup failed at `git pull --ff-only
-// origin main`, token or not (seen live: mercury, 2026-08-17).
-//
-// The fix (ADR 0176): mint the instance its OWN ed25519 deploy key, register it
-// READ-ONLY on the repo with the owner's token (idempotent by title; a stale
-// same-title key is replaced), then wire the CHECKOUT — origin re-pointed at plain
-// github.com and core.sshCommand pinned to the key with -F /dev/null so no
-// ~/.ssh/config identity can shadow it. Public repos return untouched; no token →
-// skip (the request-time refusal is task 1002909's preflight). Dry-run plans only.
-async function ensurePrivateRepoAccess(inst, deps) {
-  const { log, apply } = deps;
-  const exec = deps.controlExec || deps.exec;
-  if (inst.hosting_shape !== 'standalone') return { skipped: 'shape' };
-  const repo = parseTargetRef(inst.target_ref);
-  if (!repo) return { skipped: 'no_repo' };
-  // Dry-run stays OFFLINE like every other plan path here (the checkDnsTokenScope
-  // preflight is apply-gated for the same reason): no token read, no GitHub call —
-  // a plan run must stay a safe inspection tool for a snagged instance.
-  if (!apply) {
-    log(`  [repo-auth] would check ${repo.owner}/${repo.name} visibility with the owner's credential and, if PRIVATE, mint + register a read-only deploy key and wire origin + core.sshCommand to it (ADR 0176)`);
-    return { planned: true };
-  }
-  const ownerToken = await resolveOwnerGithubToken(inst, deps);
-  if (!ownerToken) {
-    log('  [repo-auth] no usable owner GitHub credential (none stored, or it could not be read) — a PRIVATE repo would fail at the deploy pull (public repos are unaffected)');
-    return { skipped: 'no_token' };
-  }
-  const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
-  let info;
-  try {
-    info = await ghRepos.getUserRepo(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
-  } catch (e) {
-    if (e && e.code === 'repo_not_found') {
-      // Plain sentence: this rides error_note onto the owner's project card.
-      throw new Error(`repository not found: GitHub answered 404 for ${repo.owner}/${repo.name} even with your granted credential — the repository may have been renamed or deleted, or the credential lost access. Check it on GitHub, then try again.`);
-    }
-    log(`  [repo-auth] could not read ${repo.owner}/${repo.name} (${e && e.message}) — continuing; a PRIVATE repo would fail at the deploy pull`);
-    return { skipped: 'github_unreachable' };
-  }
-
-  const root = standaloneRoot(inst);
-  const keyPath = deployKeyPath(inst);
-  const title = deployKeyTitle(inst);
-  const fsImpl = deps.fsImpl || fs;
-
-  if (!info.private) {
-    // Flipped private → public since we wired it: un-wire, or the checkout stays
-    // pinned (IdentitiesOnly + -F /dev/null admit no other identity) to a key the
-    // owner is now free to delete from their repo settings. Keyed on our key file
-    // so the common public path stays zero-mutation.
-    if (fsImpl.existsSync(keyPath)) {
-      log(`  [repo-auth] ${repo.owner}/${repo.name} is public again — un-wiring its deploy key`);
-      try {
-        const keys = await ghRepos.listDeployKeys(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
-        const ours = keys.find((k) => k.title === title);
-        if (ours) await ghRepos.deleteDeployKey(ownerToken, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
-      } catch (e) { log(`  [repo-auth] (remote key revoke skipped: ${e && e.message})`); }
-      exec(`git -C ${root} remote set-url origin ${instanceRepoRemote(repo)}`);
-      exec(`git -C ${root} config --unset core.sshCommand`, { allowFail: true });
-      exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
-      return { private: false, unwired: true };
-    }
-    return { private: false };   // the shared-alias path reads public repos as-is
-  }
-
-  // Registering a deploy key needs repository ADMIN; getUserRepo already told us.
-  // Refuse up front with the fix, instead of a raw 403 mid-standup.
-  if (info.admin === false) {
-    throw new Error(`repository access is not admin: your granted credential can read ${repo.owner}/${repo.name}, but registering its deploy key needs repository ADMIN. Ask a repository admin to raise your access (or make the repository public), then try again.`);
-  }
-
-  log(`  [repo-auth] ${repo.owner}/${repo.name} is PRIVATE — wiring its own read-only deploy key (ADR 0176)`);
-  if (!fsImpl.existsSync(keyPath) || !fsImpl.existsSync(`${keyPath}.pub`)) {
-    exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
-    exec(`ssh-keygen -q -t ed25519 -N '' -C ${title} -f ${keyPath}`);
-    exec(`chmod 600 ${keyPath}`);   // ssh-keygen's 0600 default, made an explicit invariant
-  }
-  const pubKey = String(fsImpl.readFileSync(`${keyPath}.pub`, 'utf8')).trim();
-  // Compare algorithm+key only — GitHub stores the key without the local comment.
-  const keyBody = (k) => String(k || '').trim().split(/\s+/).slice(0, 2).join(' ');
-  let minted = false;
-  try {
-    const keys = await ghRepos.listDeployKeys(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
-    const ours = keys.find((k) => k.title === title);
-    const current = !!(ours && keyBody(ours.key) === keyBody(pubKey));
-    if (ours && !current) {
-      // GitHub 422s a duplicate title/key, and a stale registration is a dead credential —
-      // replace, never accumulate.
-      await ghRepos.deleteDeployKey(ownerToken, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
-      log(`  [repo-auth] removed the stale "${title}" key on ${repo.owner}/${repo.name} (local key changed)`);
-    }
-    if (!current) {
-      try {
-        await ghRepos.addDeployKey(ownerToken, { owner: repo.owner, name: repo.name, title, key: pubKey, readOnly: true, fetchImpl: deps.fetchImpl });
-      } catch (e) {
-        if (!e || e.code !== 'key_in_use') throw e;
-        // The keypair is slug-keyed but the repo can change underneath it (renamed
-        // then recreated, target_ref re-pointed): the key is registered SOMEWHERE
-        // else, so retrying with this pair can never succeed. Mint fresh, try once.
-        log('  [repo-auth] GitHub holds this key elsewhere (422) — minting a fresh keypair and retrying once');
-        exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
-        exec(`ssh-keygen -q -t ed25519 -N '' -C ${title} -f ${keyPath}`);
-        exec(`chmod 600 ${keyPath}`);
-        const freshPub = String(fsImpl.readFileSync(`${keyPath}.pub`, 'utf8')).trim();
-        await ghRepos.addDeployKey(ownerToken, { owner: repo.owner, name: repo.name, title, key: freshPub, readOnly: true, fetchImpl: deps.fetchImpl });
-      }
-      minted = true;
-      log(`  [repo-auth] registered read-only deploy key "${title}" on ${repo.owner}/${repo.name}`);
-    } else {
-      log(`  [repo-auth] deploy key "${title}" already registered — nothing to mint`);
-    }
-  } catch (e) {
-    if (e && e.code === 'not_repo_admin') {
-      throw new Error(`repository access is not admin: your granted credential can read ${repo.owner}/${repo.name}, but registering its deploy key needs repository ADMIN. Ask a repository admin to raise your access (or make the repository public), then try again.`);
-    }
-    // Plain sentence for the owner card — a transient GitHub hiccup must not read as jargon.
-    throw new Error(`deploy-key setup failed for ${repo.owner}/${repo.name}: ${e && e.message}. Nothing is wrong on your side — try again, and if it keeps failing make the repository public and retry.`);
-  }
-  exec(`git -C ${root} remote set-url origin git@github.com:${repo.owner}/${repo.name}.git`);
-  exec(`git -C ${root} config core.sshCommand "ssh -F /dev/null -i ${keyPath} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`);
-  return { private: true, minted };
-}
-
-// ── re-provision core-pin refresh (gap-list W3, task 1003050) ────────────────────
-//
-// The hazard: a standalone instance's RUNNING core can move ahead of its repo's
-// committed `file:` pin (an out-of-band `bongos upgrade`, a pre-fix re-provision that
-// refreshed the box without committing) — seen live on Spike Harbor, running a modern
-// core while the repo still pinned 1.19.2. The deploy path is repo-driven
-// (`git reset --hard origin/main` + `npm ci`), so the NEXT deploy silently rolls the
-// instance back against a DB the newer core has already migrated. ADR 0168 fixed
-// fresh scaffolds only; this closes the re-provision leg: every provision of an
-// already-scaffolded instance heals the committed pin to the core this control plane
-// runs, as a commit pushed to the instance repo.
-
-// The PURE decision half (tested in tests/provision.mjs). Registry pins are npm's to
-// resolve; an absent dep is not ours to invent; only `file:` pins are healed.
-function planCorePinRefresh({ pinnedDep, coreVersion }) {
-  const dep = String(pinnedDep || '').trim();
-  if (!dep) return { action: 'skip', reason: 'no @bongos/core dependency in the instance package.json' };
-  if (!/^file:/.test(dep)) return { action: 'skip', reason: `registry pin (${dep}) — npm ci resolves it; nothing to vendor` };
-  const upgrade = require('./upgrade');
-  const pinned = upgrade.versionFromTgzPath(dep);
-  if (pinned && pinned === coreVersion) return { action: 'current', pinned };
-  return { action: 'refresh', pinned: pinned || null };
-}
-
-// Coerce a version label to a semver-safe charset BEFORE it is interpolated into any
-// shell string. The "from" label ultimately derives from the INSTANCE's own repo
-// package.json `file:` pin (lower trust than the shared control plane) via
-// versionFromTgzPath, whose regex admits any char but `/` — including `"`, backtick,
-// `$()`, `;`. A crafted pin (e.g. `file:vendor/bongos-core-1.0.0";touch x;echo".tgz`)
-// would otherwise break out of a `git commit -m "…"` argument and run as the
-// control-plane user. This chokepoint rejects anything outside semver's own alphabet
-// (task 1003050 grade — command-injection block). PURE.
-function safeVersionLabel(v) {
-  const s = String(v == null ? '' : v).trim();
-  return /^[0-9A-Za-z.+-]{1,64}$/.test(s) ? s : '(unversioned)';
-}
-
-// The commit + push command sequence for a pin refresh — PURE, so tests/provision.mjs
-// covers "the runner's commit step" (task 1003050 AC) deterministically. Version
-// labels pass through safeVersionLabel (the one interpolation-safety chokepoint); the
-// push prefers the owner's OAuth token URL (the shared deploy key can't write a
-// consumer repo — task 1002317) and falls back to the SSH origin.
-function buildCorePinRefreshCommit({ root, fromVersion, toVersion, repo, ownerToken, credFile }) {
-  const from = safeVersionLabel(fromVersion);
-  const to = safeVersionLabel(toVersion);
-  const msg = `chore: re-provision refreshes the pinned @bongos/core ${from} -> ${to} (task 1003050)`;
-  const push = (ownerToken && repo && credFile)
-    ? `git -C ${root} -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:main`
-    : `git -C ${root} push origin main`;
-  return {
-    config: [
-      `git -C ${root} config user.name "Cloud Bongos"`,
-      `git -C ${root} config user.email "${provisionerBotEmail()}"`,
-    ],
-    add: `git -C ${root} add -A`,
-    commit: `git -C ${root} commit -m "${msg}"`,
-    push,
-  };
-}
-
-async function refreshStandaloneCorePin(inst, deps) {
-  const { log } = deps;
-  const exec = deps.controlExec || deps.exec;
-  const writeFile = deps.controlWriteFile || deps.writeFile;
-  const upgrade = require('./upgrade');
-  const root = standaloneRoot(inst);
-  const coreV = coreVersionSafe();
-  if (!coreV) { log('  [core-pin] cannot resolve the running core version — leaving the committed pin alone'); return { action: 'skip', reason: 'no core version' }; }
-  let pkg = null;
-  try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* unreadable → skip below */ }
-  const pinnedDep = pkg && ((pkg.dependencies || {})['@bongos/core'] || (pkg.devDependencies || {})['@bongos/core']);
-  const plan = planCorePinRefresh({ pinnedDep, coreVersion: coreV });
-  if (plan.action === 'skip') { log(`  [core-pin] ${plan.reason}`); return plan; }
-  if (plan.action === 'current') { log(`  [core-pin] committed pin already matches the running core (${coreV})`); return plan; }
-  log(`  [core-pin] committed pin ${safeVersionLabel(plan.pinned)} trails this control plane's core ${coreV} — refreshing so the next repo-driven deploy cannot roll the instance back (task 1003050)`);
-
-  const { tgz, packDest } = resolveVendorableCoreTarball({
-    instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[core-pin]',
-  });
-  try {
-    const targetVersion = upgrade.versionFromTgzPath(path.basename(tgz)) || coreV;
-    const vendorRel = upgrade.vendorTarball({ instanceDir: root, fromTgz: tgz, targetVersion });
-    // Prune superseded vendored tarballs (+ manifests) so the repo carries exactly ONE
-    // core. fs.rmSync, NOT exec — a filename comes off the instance's own (lower-trust)
-    // vendor/ dir, so shelling `rm -f ${f}` would be the same injection vector as the
-    // commit label (a committed file named `bongos-core-x";touch pwn;".tgz`). A direct
-    // fs call takes the name as data, never as shell (task 1003050 grade).
-    const vendorDir = path.join(root, 'vendor');
-    const keep = new Set([`${upgrade.ARTIFACT}-${targetVersion}.tgz`, `${upgrade.ARTIFACT}-${targetVersion}.manifest.json`]);
-    // vendorTarball just mkdirSync'd this, so it exists on the happy path; guard anyway
-    // so an unexpectedly-absent dir prunes nothing instead of crashing the whole provision.
-    if (fs.existsSync(vendorDir)) {
-      for (const f of fs.readdirSync(vendorDir)) {
-        if (f.startsWith(`${upgrade.ARTIFACT}-`) && !keep.has(f)) fs.rmSync(path.join(vendorDir, f), { force: true });
-      }
-    }
-    upgrade.writePin(root, vendorRel);
-    // `npm install` (NOT ci): the pin just changed, the lockfile must be regenerated.
-    const instRes = upgrade.npmInstall(root);
-    if (!instRes.ok) {
-      throw new Error(`npm install after the core-pin refresh failed (${instRes.reason || `exit ${instRes.code}`}) — lockfile not regenerated; the pin refresh cannot be committed half-done.`);
-    }
-
-    // Commit + push the refresh to the instance repo — the shared deploy key cannot
-    // write a consumer's repo (task 1002317), so prefer the owner's OAuth token,
-    // exactly like the scaffold's push.
-    const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[core-pin]' });
-    const repo = parseTargetRef(inst.target_ref);
-    const credFile = ownerToken && repo ? path.join(os.tmpdir(), `bongos-gitcred-pin-${inst.slug}-${process.pid}`) : null;
-    const cmd = buildCorePinRefreshCommit({ root, fromVersion: plan.pinned, toVersion: targetVersion, repo, ownerToken, credFile });
-    try {
-      cmd.config.forEach((c) => exec(c));
-      exec(cmd.add);
-      exec(cmd.commit, { allowFail: true });
-      if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
-      exec(cmd.push);
-    } finally {
-      if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
-    }
-    log(`  [core-pin] refreshed + pushed: @bongos/core ${safeVersionLabel(plan.pinned)} → ${targetVersion}`);
-    return { ...plan, refreshed: true, toVersion: targetVersion };
-  } finally {
-    if (packDest) exec(`rm -rf ${packDest}`);
-  }
-}
-
-// The per-instance systemd unit (the infra/cloudbongos.service shape): one Node process
-// bound to the instance's port + DB + brand, secrets from its own env file. SHAPE-AWARE:
-// a STANDALONE instance runs the CORE PACKAGE's platform-server from its OWN repo dir
-// (WorkingDirectory=standaloneRoot → resolveInstanceRoot() resolves to the instance via
-// cwd, deploy-instance.sh §4); co-tenant/dedicated run this control-plane checkout's src/.
-function serviceUnit(inst, { etcBase = CONFIG.etcBase } = {}) {
-  const envFile = path.posix.join(etcBase, inst.slug, 'web.env');
-  const standalone = inst.hosting_shape === 'standalone';
-  const workDir = standalone ? standaloneRoot(inst) : REPO_ROOT;
-  const execStart = standalone
-    ? `/usr/bin/node ${CORE_PKG_DIR}/src/platform-server.js`
-    : `/usr/bin/node src/platform-server.js`;
-  return `[Unit]
-Description=Cloud Bongos instance — ${inst.slug} (provisioned by provision.js, ADR 0111)
-After=network-online.target postgresql.service
-Wants=network-online.target
-Requires=postgresql.service
-
-[Service]
-Type=simple
-User=lars
-Group=lars
-WorkingDirectory=${workDir}
-EnvironmentFile=${envFile}
-Environment=PGDATABASE=${dbName(inst)}
-Environment=PORT=${inst.port}
-ExecStart=${execStart}
-Restart=always
-RestartSec=3
-StandardOutput=journal
-StandardError=journal
-NoNewPrivileges=true
-
-[Install]
-WantedBy=multi-user.target
-`;
-}
-function serviceUnitPath(inst) { return `/etc/systemd/system/${inst.slug}.service`; }
-
-// ── nightly DB backup: per-instance timer + service (task 2213) ─────────────
-// PRODUCTIZES the manual task-2210 fix: a newly-provisioned instance was born with
-// NO backups (dir absent, GDS_BACKUP_DB unset → the script fell back to the
-// nonexistent `amazonprimea` default, and the repo's global gds-db-backup units
-// hardcode /home/lars/amazonprimea — wrong for the consumer node_modules/@bongos/
-// core layout). These generators emit a PER-INSTANCE unit pair that fixes all three:
-//   • name  → `<slug>-db-backup.{service,timer}` so co-tenant instances on one box
-//             never collide (each dumps its OWN db; the script's retention prune is
-//             already `<db>-*.sql.gz`-scoped, so a shared backupDir is safe).
-//   • DB    → Environment=GDS_BACKUP_DB=<instance db>, set on the unit (not read from
-//             the web.env) so the dump targets the right database with no fallback.
-//   • path  → ExecStart resolves the canonical script INSIDE the instance's pinned
-//             @bongos/core (standalone) or this control-plane checkout (co-tenant),
-//             the SAME workDir/CORE_PKG_DIR split serviceUnit uses — never the old
-//             monorepo path.
-function backupUnitName(inst) { return `${inst.slug}-db-backup`; }
-function backupServicePath(inst) { return `/etc/systemd/system/${backupUnitName(inst)}.service`; }
-function backupTimerPath(inst) { return `/etc/systemd/system/${backupUnitName(inst)}.timer`; }
-// The consumer-layout-correct absolute path to db-backup-nightly.sh. Standalone runs
-// it from the instance's own pinned core; co-tenant/dedicated from this checkout's
-// scripts/gds/ — mirrors serviceUnit's execStart resolution so they can't diverge.
-function backupScriptPath(inst) {
-  const rel = 'scripts/gds/db-backup-nightly.sh';
-  return inst.hosting_shape === 'standalone'
-    ? path.posix.join(standaloneRoot(inst), CORE_PKG_DIR, rel)
-    : path.posix.join(REPO_ROOT, rel);
-}
-function backupService(inst, { backupDir = CONFIG.backupDir } = {}) {
-  return `[Unit]
-Description=Nightly pg_dump of the ${inst.slug} GDS DB (provisioned by provision.js, task 2213)
-After=postgresql.service
-Requires=postgresql.service
-
-[Service]
-Type=oneshot
-User=${APP_USER}
-Group=${APP_USER}
-# The DB to dump + where dumps land — set on the unit (not via the instance web.env)
-# so the dump targets the right database with no fallback to a stale default (root
-# cause of the task-2210 breakage). db-backup-nightly.sh reads both as env.
-Environment=GDS_BACKUP_DB=${dbName(inst)}
-Environment=GDS_BACKUP_DIR=${backupDir}
-# Consumer-layout path: the canonical script inside this instance's pinned core.
-ExecStart=/bin/bash ${backupScriptPath(inst)}
-# Modest hardening — the script only needs read on the pg socket + write on the
-# backup dir. Mirrors the repo's gds-db-backup.service.
-NoNewPrivileges=true
-ProtectSystem=strict
-ReadWritePaths=${backupDir}
-ProtectHome=read-only
-PrivateTmp=true
-
-[Install]
-# Not socket-activated; the timer drives this. The timer's WantedBy is what enables.
-`;
-}
-function backupTimer(inst) {
-  return `[Unit]
-Description=Daily timer for the ${inst.slug} GDS DB pg_dump (provisioned by provision.js, task 2213)
-
-[Timer]
-# 04:00 UTC daily, mirroring the repo's gds-db-backup.timer (low-traffic window).
-OnCalendar=*-*-* 04:00:00 UTC
-# Catch up on next boot if the box was off when the timer was due.
-Persistent=true
-# Jitter so simultaneous timers don't dogpile the disk at exactly 04:00.
-RandomizedDelaySec=300
-Unit=${backupUnitName(inst)}.service
-
-[Install]
-WantedBy=timers.target
-`;
-}
-
-// The branding pack a provisioned CO-TENANT instance loads: the shared, committed
-// neutral starter (the co-tenant model shares ONE checkout, differentiated only by
-// env — src/branding.js's GDS_BRANDING_FILE knob). Per-instance identity/domains
-// therefore ride ENV OVERRIDES, not a divergent pack. Kept as a constant so the
-// GDS_BRANDING_FILE line below and the env-var PREFIX (which must equal this pack's
-// envPrefix, or src/branding.js's ENV_OVERRIDES never fire) can't drift apart.
-const PROVISIONED_BRANDING_FILE = 'config/branding.neutral.json';
-
-// The env-var prefix a provisioned instance actually RESOLVES — i.e. the envPrefix
-// of the pack it loads (PROVISIONED_BRANDING_FILE). src/instance-config.resolveEnv
-// reads <envPrefix>_<SUFFIX>, and src/branding.resolveBranding applies
-// <envPrefix>_{PUBLIC,BUILDERS,…}_ORIGIN overrides — so a web.env var only takes
-// effect under THIS prefix. Read from the pack (fail-soft to the vanilla default)
-// so it stays in lockstep instead of a magic string. (The prior slug-based prefix
-// was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
-// the OAuth creds were silently unreadable — task 1972.)
-function provisionedEnvPrefix() {
-  try {
-    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
-    return pack.envPrefix || 'CLOUDBONGOS';
-  } catch { return 'CLOUDBONGOS'; }
-}
-
-// The per-instance secrets file body (the standup runbook's /etc/<inst>/web.env).
-// The OAuth client id/secret are GUIDED/manual inputs (no GitHub create-API) — the
-// runner writes placeholders the owner fills, unless provided via the intent later.
-// A domain (bring-your-own or provisioned) drives the single-host origin overrides:
-// with them set, src/branding.js resolves the instance's REAL buildersOrigin, so the
-// core's single-host router (isBuildersHost === buildersOrigin host, task 1971) serves
-// the hall on this host + OAuth uses the real callback origin — without them the pack
-// stays at neutral localhost and the hall never loads (task 1972). No domain yet
-// (bring-your-own deferred, ADR 0111 §4) ⇒ origins stay neutral until one is set.
-function webEnvBody(inst, { clientId = '', clientSecret = '', appId = null, appPem = null, federation = null } = {}) {
-  const prefix = provisionedEnvPrefix(), { settingsEnvLines } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
-  const origin = inst.domain ? `https://${inst.domain}` : '';
-  const originLines = origin
-    ? `# Single-host origins (task 1972): the hall serves on THIS host + OAuth/redirects
-# use the real address. Resolved by src/branding.js ENV_OVERRIDES under the pack's
-# ${prefix} envPrefix. A single-host instance has no dedicated builders./status.
-# subdomain, so all four point at the one host.
-${prefix}_PUBLIC_ORIGIN=${origin}
-${prefix}_BUILDERS_ORIGIN=${origin}
-${prefix}_STATUS_ORIGIN=${origin}
-${prefix}_OAUTH_ORIGIN=${origin}
-`
-    : `# No domain yet (bring-your-own-domain pending, ADR 0111 §4) — origins stay
-# neutral (localhost); add ${prefix}_{PUBLIC,BUILDERS,OAUTH}_ORIGIN once a domain
-# is set, or the hall won't load on the instance's host.
-`;
-  // The OAuth app creds are filled by ONE of two paths (task 2080): the GitHub App
-  // Manifest flow (placeManifestCreds fetches them control-plane-side + re-writes this
-  // file with clientId/clientSecret set), or the manual oauth-secret.js placement. On
-  // the first provision write they are blank placeholders the flow fills later.
-  const credComment = federation
-    ? `# Provisioned by scripts/gds/provision.js (ADR 0111). This instance FEDERATES sign-in
-# through the Cloud Bongos hub (ADR 0141 §4) — it needs no GitHub app of its own, so the
-# GitHub client id/secret below stay blank; the ${prefix}_HUB_* block drives sign-in.`
-    : clientId || clientSecret
-    ? `# Provisioned by scripts/gds/provision.js (ADR 0111). OAuth app creds placed via the
-# GitHub App Manifest flow (ADR 0133) — the owner clicked one link; no secret was pasted.`
-    : `# Provisioned by scripts/gds/provision.js (ADR 0111). Fill the OAuth app creds via the
-# one-click GitHub App Manifest flow (ADR 0133), or manually (oauth-secret.js place):`;
-  // The founding owner (firstAdmin): the GitHub login src/bongos/auth.js seats as the
-  // instance's first Archon on first sign-in (maybeSeatFirstAdmin checks
-  // <prefix>_FIRST_ADMIN before branding.firstAdmin). WITHOUT it a provisioned instance
-  // has NO owner — first sign-in is refused / lands rankless and the owner can never
-  // claim their own instance (goal 35 / criterion 165 regression, caught live 2026-07-07:
-  // demo had every origin override but no FIRST_ADMIN, so the owner could not be seated).
-  // Derived from the instance repo owner (target_ref = "<owner>/<repo>"), the SAME source
-  // instanceInitSpec uses for the scaffold's branding.firstAdmin — so this env override and
-  // the scaffolded config/branding.json agree. (Org-owned repo: the org login is not a
-  // sign-in identity, so it is left unset; the owner sets <prefix>_FIRST_ADMIN by hand.)
-  const ownerRepo = parseTargetRef(inst.target_ref);
-  const firstAdminLine = ownerRepo && ownerRepo.owner
-    ? `${prefix}_FIRST_ADMIN=${ownerRepo.owner}\n`
-    : '';
-  // Cross-site identity federation block (ADR 0141 §4, task #1002109). Present only for
-  // a HOSTED (federated) instance: flips auth.idp ON via the env override branding.js
-  // reads (idpEnabled), and carries the hub origin, this instance's per-client secret
-  // (authenticates it TO the hub, server-to-server), and the hub's PUBLIC key (verifies
-  // the CLI's hub-signed assertion offline). All written straight to this chmod-600
-  // file — never through a browser or chat (the ADR 0133 secret-placement posture).
-  const fedLines = federation
-    ? `${prefix}_AUTH_IDP=true
-${prefix}_HUB_ORIGIN=${federation.hubOrigin}
-${prefix}_HUB_CLIENT_ID=${federation.clientId}
-${prefix}_HUB_CLIENT_SECRET=${federation.clientSecret}
-${prefix}_HUB_PUBLIC_KEY=${federation.hubPublicKey}
-`
-    : '';
-  // The publish credential (task 1003049, ADR 0055): the manifest-born App's id +
-  // private key, read BARE (no prefix) by modules/lifecycle/github-push.js. The
-  // pem is env-file-flattened to a single line with literal \n (the ADR 0055
-  // rotation convention; normalizePem restores it). The installation id is NOT
-  // written — the server discovers it from the repo once the owner installs the
-  // App (the onboarding app-install step).
-  const appLines = appId && appPem
-    ? `# Publish credential (ADR 0055): the sign-in GitHub App doubles as it. The server
-# mints short-lived installation tokens once the App is INSTALLED on the repo.
-GITHUB_APP_ID=${appId}
-GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
-`
-    : '';
-  return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
-${credComment}
-${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
-${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
-${firstAdminLine}GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
-${originLines}${appLines}PORT=${inst.port}
-PGDATABASE=${dbName(inst)}
-${fedLines}${settingsEnvLines(inst, prefix)}`;
-}
-function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
-  return path.posix.join(etcBase, inst.slug, 'web.env');
-}
-
-// ── Cross-site identity: federate a hosted instance's sign-in through the hub ───
-// (ADR 0141 §4, task #1002109). The control plane IS the hub (cloudbongos.com), so
-// registration is a direct in-process call against the hub pool — no HTTP hop.
-
-// The hub's own public origin, written into each federated instance as
-// <PREFIX>_HUB_ORIGIN (what auth.js loadIdpConfig reads). Explicit PROVISION_HUB_ORIGIN
-// wins; otherwise the control plane's OWN public origin (<PREFIX>_PUBLIC_ORIGIN, the
-// env the hub already runs under). Null → not hub-configured → shouldFederate is false.
-function federationHubOrigin() {
-  const explicit = process.env.PROVISION_HUB_ORIGIN;
-  if (explicit) return String(explicit).replace(/\/+$/, '');
-  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
-  return own ? String(own).replace(/\/+$/, '') : null;
-}
-
-// Whether provisioning should federate this instance's sign-in through the hub.
-// Dormant-by-default: true ONLY when the control plane is hub-configured (the
-// platform-identity module is present, a signing key is loadable, AND a hub origin
-// resolves), the instance is a CO-TENANT (the mothership-hosted shape whose web.env is
-// written locally — a `standalone` is owner-hosted and keeps its own GitHub app, the
-// self-hosted path; a `dedicated` droplet has no local web.env write yet, same gap the
-// ADR 0133 manifest flow leaves — see placeManifestCreds), and it has a public domain
-// (the origin the hub binds the CLI mint audience to — the #1002108 account-takeover
-// fix). Returns { federate, reason } so the caller can log WHY it skipped. PURE-ish
-// (reads env + the injected module handles; no DB, no I/O).
-function shouldFederate(inst, deps) {
-  const { platformIdentity, hubKeys } = deps;
-  if (!platformIdentity || !hubKeys) return { federate: false, reason: 'platform-identity module not present (control plane is not the hub)' };
-  if (!hubKeys.hubSigningConfigured()) return { federate: false, reason: 'hub signing key not configured (<PREFIX>_HUB_SIGNING_KEY unset)' };
-  if (!federationHubOrigin()) return { federate: false, reason: 'hub origin not resolvable (set PROVISION_HUB_ORIGIN or <PREFIX>_PUBLIC_ORIGIN)' };
-  if (inst.hosting_shape !== 'co-tenant') return { federate: false, reason: `${inst.hosting_shape} keeps its own GitHub app (not the co-tenant hosted path)` };
-  if (!inst.domain) return { federate: false, reason: 'no domain yet — federation needs the instance public origin' };
-  return { federate: true, reason: null };
-}
-
-// Register this hosted instance as an sso_clients row on the HUB (fresh per-client
-// secret) and return the federation block to bake into its web.env (ADR 0141 §4).
-// SECURITY: `origin` MUST be the instance's EXACT public origin — the hub binds the
-// CLI-federation mint audience to it (the #1002108 fix), so a mismatch would break
-// device sign-in (and a wrong origin would be a takeover vector). client_id is the
-// (unique, DNS-safe) slug, so a re-provision rotates the SAME row's secret via
-// registerClient's ON CONFLICT rather than orphaning a client. redirect_uri lists both
-// callback prefixes the core may emit (/api/gds is what auth.js builds today) so the
-// hub's exact-match allow-list accepts the browser leg. --apply gates the real hub
-// write; dry-run returns a placeholder block (so webEnvBody can still be composed) + logs.
-async function federateInstance(inst, deps) {
-  const { db, platformIdentity, hubKeys, log, apply } = deps;
-  const origin = `https://${inst.domain}`;
-  const clientId = inst.slug;
-  const hubOrigin = federationHubOrigin();
-  const hubPublicKey = hubKeys.hubPublicKeyB64();
-  if (!hubPublicKey) throw new Error('hub signing key is set but unreadable — cannot derive HUB_PUBLIC_KEY');
-  const redirectUris = [
-    `${origin}/api/gds/auth/web/callback`,
-    `${origin}/api/bongos/auth/web/callback`,
-  ];
-  if (!apply) {
-    log(`  [federate] would register client '${clientId}' on the hub (origin ${origin}) + write ${provisionedEnvPrefix()}_HUB_* + AUTH_IDP into web.env`);
-    return { hubOrigin, clientId, clientSecret: '0'.repeat(43), hubPublicKey };
-  }
-  const clientSecret = crypto.randomBytes(32).toString('base64url');
-  // Best-effort owner github_id — nice for the hub catalog's ownership link, but
-  // nullable in registerClient, so a lookup miss must never fail the provision.
-  let ownerGithubId = null;
-  try {
-    const { rows } = await db.query('SELECT github_id FROM builders WHERE id = $1', [inst.owner_builder_id]);
-    ownerGithubId = rows[0] ? rows[0].github_id : null;
-  } catch { /* non-fatal */ }
-  await platformIdentity.registerClient(
-    // type: the owner's declaration rides the instance row from the create
-    // wizard (task 1002772) and lands on the catalog row here — never guessed.
-    { clientId, secret: clientSecret, name: inst.slug, redirectUris, origin, ownerGithubId, type: inst.type },
-    { pool: db },
-  );
-  log(`  [federate] registered client '${clientId}' on the hub (origin ${origin})`);
-  return { hubOrigin, clientId, clientSecret, hubPublicKey };
-}
-
-// The Cloudflare zone a hostname's A record lives in. Cloudflare zones are
-// registrable domains, which for the common case is the last two DNS labels
-// (mercury.example.com → example.com; apex example.com → example.com). Multi-part
-// public suffixes (foo.co.uk) are NOT special-cased here — set CLOUDFLARE_ZONE in
-// the control-plane box.env to override (box-dns-cloudflare.sh honours it). PURE.
-function zoneForDomain(domain) {
-  const d = String(domain || '').trim().toLowerCase().replace(/\.$/, '');
-  if (!d) return '';
-  const labels = d.split('.').filter(Boolean);
-  return labels.length <= 2 ? labels.join('.') : labels.slice(-2).join('.');
-}
-
-// The env a DNS UPSERT invocation of infra/box-dns-cloudflare.sh needs for a
-// PROVISIONED host: the hostname, the target public IP (the A-record content), the
-// zone the record lives in, and whether Cloudflare proxies it.
-//   • proxied=false (default) is LOAD-BEARING for a CO-TENANT/dedicated host: it uses
-//     Caddy on-demand ACME (Let's Encrypt), whose challenge must reach Caddy directly —
-//     Cloudflare proxy ON would intercept :80/:443 at the edge and the challenge would
-//     silently fail (ADR 0003 / docs/recipes/ops-gotchas.md). Do NOT proxy those.
-//   • proxied=true for a STANDALONE host (task 2077): it runs control-plane-local under
-//     the *.cloudbongos.com wildcard Cloudflare Origin cert, so on-demand ACME never
-//     fires (a matching cert already exists) and proxied=false would serve that origin
-//     cert — untrusted to direct clients. Proxying lets the CF edge present a public cert
-//     (origin cert valid behind Full-strict) AND hides the control-plane IP.
-// An explicit `zone` wins over the derived one (for a multi-part-suffix domain). PURE.
-function dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {}) {
-  return {
-    BOX_HOSTNAME: inst.domain,
-    BOX_IP: publicIp,
-    CLOUDFLARE_ZONE: zone || zoneForDomain(inst.domain),
-    BOX_PROXIED: proxied ? '1' : '0',
-  };
-}
-
-// ── DNS token-scope PREFLIGHT (task 1980) ────────────────────────────────────
-// Onboarding a NEW project on a domain the control-plane's Cloudflare token does NOT
-// cover fails LATE: the DNS UPSERT (step 5) errors mid-provision (the Emersonian
-// standup — the token only covered the platform's original zone, so the new project's
-// record couldn't be created until it was widened MID-FLOW). This preflight detects
-// "the configured token can't reach the project's zone" UP FRONT, before the
-// connect-address step, and GUIDES the fix — instead of a half-done provision. It is
-// READ-ONLY (a CF `GET /zones?name=<zone>`); it never mutates DNS.
-const CF_API_BASE = process.env.CLOUDFLARE_API_BASE || 'https://api.cloudflare.com/client/v4';
-
-// PURE: given the outcome of `GET /zones?name=<zone>` (HTTP status + parsed JSON) and
-// the target zone, decide whether the token can MANAGE that zone, with actionable
-// guidance when it can't. Exported + unit-tested with no network.
-function classifyZoneScope({ status, body, zone }) {
-  const z = String(zone || '');
-  if (status === 401 || status === 403) {
-    return { reachable: false, reason: `Cloudflare rejected the token (HTTP ${status})`,
-      guidance: `The DNS token is invalid or lacks Zone:Read. Set CLOUDFLARE_API_TOKEN in the control-plane box.env to a token scoped to include ${z} (Zone:DNS:Edit + Zone:Read).` };
-  }
-  if (status !== 200 || !body || body.success !== true) {
-    const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
-    return { reachable: false, reason: `Cloudflare zone lookup failed (HTTP ${status}${errs ? `: ${errs}` : ''})`,
-      guidance: `Check CLOUDFLARE_API_TOKEN + network from the control plane, then retry.` };
-  }
-  const result = Array.isArray(body.result) ? body.result : [];
-  const match = result.find((r) => r && r.name === z);
-  if (!match) {
-    return { reachable: false, reason: `the token authenticated, but zone "${z}" is not in its scope`,
-      guidance: `Widen the Cloudflare API token to include ${z}: CF dashboard → My Profile → API Tokens → edit the token → Zone Resources → Include → ${z} (or use an account-scoped token). If ${z} is a multi-part public suffix (e.g. foo.co.uk), set CLOUDFLARE_ZONE explicitly in the control-plane box.env.` };
-  }
-  return { reachable: true, reason: `token can manage zone "${z}" (id ${match.id})`, zoneId: match.id };
-}
-
-// Query Cloudflare for the domain's zone with the configured token. Injectable
-// `token`/`fetchImpl` for tests. Returns { zone, reachable, reason, guidance[, zoneId] }.
-// A missing token/fetch/domain is reported as not-reachable-with-guidance — it never
-// throws for a config gap (the caller decides whether to hard-fail).
-async function checkDnsTokenScope(domain, { token = process.env.CLOUDFLARE_API_TOKEN, zoneOverride = process.env.CLOUDFLARE_ZONE, fetchImpl } = {}) {
-  const zone = zoneOverride || zoneForDomain(domain);
-  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
-  if (!zone) return { zone, reachable: false, reason: 'no domain given', guidance: 'provide a domain before the address step' };
-  if (!token) return { zone, reachable: false, reason: 'no CLOUDFLARE_API_TOKEN configured', guidance: `Set CLOUDFLARE_API_TOKEN (Zone:DNS:Edit on ${zone}) in the control-plane box.env before provisioning DNS for ${domain}.` };
-  if (!doFetch) return { zone, reachable: false, reason: 'no fetch available', guidance: 'run on a Node with global fetch, or inject fetchImpl' };
-  let status = 0; let bodyJson = null;
-  try {
-    const res = await doFetch(`${CF_API_BASE}/zones?name=${encodeURIComponent(zone)}`, {
-      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
-    });
-    status = res.status;
-    bodyJson = await res.json().catch(() => null);
-  } catch (e) {
-    return { zone, reachable: false, reason: `Cloudflare request failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
-  }
-  return { zone, ...classifyZoneScope({ status, body: bodyJson, zone }) };
-}
-
-// A Caddy reverse-proxy site block for the instance's domain → its local port.
-// TLS = on-demand ACME (P4, ADR 0111 §4): Caddy fetches a Let's Encrypt cert for
-// this host LAZILY, on the first TLS handshake — no manual Cloudflare Origin-Cert
-// console step (the least-automated leg). It is GATED by the global
-// `on_demand_tls { ask … }` allow-list in infra/Caddyfile (→ /api/bongos/
-// provisioning/tls-check), so Caddy only mints a cert for a host this module
-// actually provisioned — never an arbitrary SNI. The A record is proxied=false
-// (dnsUpsertEnv) so the challenge reaches Caddy. No domain → a comment
-// (bring-your-own-domain is deferred per-instance, ADR 0111 §4).
-function caddyBlock(inst) {
-  if (!inst.domain) {
-    return `# ${inst.slug}: no domain yet (bring-your-own-domain pending) — reachable on 127.0.0.1:${inst.port}\n`;
-  }
-  return `${inst.domain} {
-	tls {
-		on_demand
-	}
-	reverse_proxy 127.0.0.1:${inst.port}
-}
-`;
-}
-function caddySnippetPath(inst, { snippetDir = CONFIG.caddySnippetDir } = {}) {
-  return path.posix.join(snippetDir, `${inst.slug}.caddy`);
-}
-function healthzCmd(inst) {
-  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/healthz`;
-}
-
-// ---------------------------------------------------------------------------
-// The injectable executor. dry-run → log-only; --apply → child_process.
-// ---------------------------------------------------------------------------
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   return function run(cmd, { allowFail = false, cwd, env } = {}) {
     // Extra env is passed to the child (not interpolated into the command), so