@bongos/core 1.21.175 → 1.21.177

package/scripts/gds/provision-repo.js

@@ -1,1337 +1,6 @@
-// scripts/gds/provision-repo.js — everything that makes an instance's own repo
-// and database real: the db create/migrate/seed commands, the standalone repo
-// scaffold, adopt-vs-greenfield detection, the private-repo deploy key, and the
-// re-provision core-pin refresh.
-//
-// Carved out of scripts/gds/provision.js by task 1003206 (goal 1000079, the R03
-// de-monolith plan) to bring the control-plane CLI under the 1,500-line ratchet.
-// A STRUCTURAL move: bodies unchanged, provision.js requires every name back, so
-// the intent runner and its unit templates behave exactly as before.
-
+// scripts/gds/provision-repo.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-repo.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const { CONFIG, REPO_ROOT, coreVersionSafe, provisionerBotEmail, provisionerBotName } = require('./provision-config.js');
-// The repo-identity + owner-credential leaf (task 1003081). Carved OUT of this file so
-// upgrade.js can reach these three without pulling provision*.js into the merge
-// resolver's executed closure; re-exported below so every existing caller is unchanged.
-const { instanceRepoRemote, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo-auth.js');
-const { normalizePackEnvPrefix } = require('./pack-env-prefix.js');   // an adopted pack's envPrefix (task 1004573)
-const { CORE_PKG, compareSemver, isStable } = require('./update-channel.js');
-
-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. No `track` column: the two-track model was retired (task 1002006, unwound
-// by task 1003665). The seed runs on a freshly-MIGRATED database, so core_205's
-// DEFAULT 'product' is in place and an INSERT that omits the column is legal.
-//
-// 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 both executors: inline (/bin/sh) and
-// over SSH (bash -s), 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, status, done_when) ` +
-    `SELECT ${q(v.id)}, ${q(v.name)}, $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);
-}
-
-// ── The CLOUD-HOST shape (hosting_shape='cloud-host', ADR 0108, task 1978) ────
-//
-// TWO SENSES OF "STANDALONE", AND THIS FILE USES BOTH. The ADR 0108 sense is a repo
-// TOPOLOGY: an instance running from its own checkout with the core as an npm dependency,
-// as opposed to co-tenant's shared control-plane checkout. That is what `standaloneRoot`,
-// `standaloneBase` and `PROVISION_STANDALONE_BASE` name, and those keep their spelling —
-// `PROVISION_STANDALONE_BASE` in particular is a live environment variable on the control
-// plane and is documented in the /new-project skill. The other sense was the HOSTING SHAPE
-// once stored as 'standalone'; task 1004182 renamed that value to 'cloud-host'. Only the
-// stored value moved. Do not "finish the rename" by touching the topology names.
-//
-// A cloud-host 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 plane's app user: the unix account that owns the control-plane checkout, owns the
-// backup dir, runs the backup timers, and whose GROUP every instance account joins to read
-// the checkout. One resolver, so those four can't drift apart.
-//
-// Derived, never named (task 1002719). It used to be the founder's own account as a
-// literal, and a standup on any host that account did not exist on died `invalid user` at
-// the backup step. PROVISION_APP_USER pins it; otherwise it is the account this runner
-// executes as, which on a plane IS the app user (the runner unit runs as it), so the live
-// box resolves exactly what the literal said. A runner driving a different box over SSH
-// (remoteHost) should pin it. root is refused, not resolved: the instance
-// accounts join this account's group, and group root is not a read grant to hand a tenant.
-// Validated because it is interpolated into shell commands and unit files.
-const UNIX_ACCOUNT_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
-function appUser({ env = process.env, userInfo = os.userInfo } = {}) {
-  let name = String(env.PROVISION_APP_USER || '').trim();
-  if (!name) {
-    try { name = userInfo().username; } catch { name = ''; } // a uid with no passwd entry
-  }
-  if (name === 'root' || !UNIX_ACCOUNT_RE.test(name)) {
-    const why = name === 'root' ? 'is root' : 'is not a usable unix account name';
-    throw new Error(`provisioning: the app user ${JSON.stringify(name)} ${why} — set PROVISION_APP_USER to the unprivileged account that owns this checkout`);
-  }
-  return name;
-}
-// The app user's PRIMARY group, looked up by the shell on the box the command runs on. It
-// need not share the account's name (a service account created into `users`), so it is
-// never spelled as the account name.
-function appGroupExpr() { return `$(id -gn ${appUser()})`; }
-function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return path.posix.join(base, inst.slug); }
-// WHERE THE INSTANCE THIS CORE SERVES ACTUALLY LIVES (task 1004123).
-//
-// REPO_ROOT is `path.resolve(__dirname, '..', '..')` — it points at whatever copy of
-// the core is EXECUTING, which is not the same place as the instance being upgraded.
-// Two shapes, and the code had only ever met the first:
-//
-//   • a core CHECKOUT run in place (`/home/lars/cloudbongos`) — the instance root IS
-//     the checkout, so REPO_ROOT was right by coincidence;
-//   • a VENDORED core (`<instance>/node_modules/@bongos/core`) — REPO_ROOT is the
-//     package, and the instance is three directories up.
-//
-// The live control plane became the second shape when its runner unit was re-homed
-// (`WorkingDirectory=/home/lars/cloudbongos-instance`, ExecStart into the vendored
-// core), and nothing noticed: REPO_ROOT still resolved, just to the wrong tree. So
-// `readInstalledCoreVersion` answered null instead of 1.19.917, every guard that
-// reads `installed` silently stopped guarding, and an upgrade would have pinned and
-// npm-installed INSIDE the core package while the instance's own pin stayed put.
-//
-// This is a string question, not a filesystem one: the vendored layout is the only
-// way a core ends up under `node_modules/`, so the suffix IS the answer. Keeping it
-// pure means the control-plane path is testable without a box.
-// Either separator counts as a segment boundary (task 1004663): a suffix built from
-// path.sep alone never matched a POSIX-shaped path on Windows, so the suite went red
-// there while the Linux box (the only place this runs for real) stayed green.
-function selfInstanceRoot(repoRoot = REPO_ROOT) {
-  const segs = CORE_PKG_DIR.split('/');
-  const tail = repoRoot.split(/[\\/]/).slice(-(segs.length + 1));
-  const isVendored = tail.length === segs.length + 1 && segs.every((s, i) => tail[i + 1] === s);
-  return isVendored ? repoRoot.slice(0, -(segs.join('/').length + 1)) : repoRoot;
-}
-// 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`; }
-
-// ── Per-instance identity: its OWN unix account + its OWN password-authed PG role ──
-// (task 1003369, audit ref B3 of the 2026-08-29 security audit.)
-//
-// THE HOLE THIS CLOSES. Every instance service used to run as the one shared app user, and
-// co-tenant is the DEFAULT shape — so on a shared box every instance ran as the SAME
-// unix user. A unix user may read /proc/<pid>/environ of its own processes, which means
-// any instance could read every SIBLING's environment: GITHUB_APP_PRIVATE_KEY, the
-// <PREFIX>_HUB_CLIENT_SECRET, every OAuth secret web.env carries. The DB half was the
-// same shape one layer down: pool.js connected by PASSWORDLESS peer auth, so any code
-// running as lars could open a pool against any sibling database — including the control
-// plane's own `builders` and `builder_sessions`. Neither was a bug in a route; it was the
-// identity every instance shared. Giving each instance its own unix account and its own
-// password-authed role is what makes the boundary real.
-//
-// NAME SHAPE. A unix account name is capped at 32 chars (utmp) and must match
-// [a-z_][a-z0-9_-]*; a slug is 2–40 of [a-z0-9-] (isValidSlug). So the name cannot be
-// the slug verbatim, and it must not be the BARE slug either — that would let a project
-// named `postgres` or `lars` claim an existing account. Prefixed + length-folded:
-//   short slug → bongos-<slug>
-//   long slug  → bongos-<slug truncated>-<8 hex of sha256(slug)>   (still <= 32)
-// The hash suffix keeps two slugs that share a 16-char prefix from folding onto one
-// account — which would hand each the other's identity, the very thing being fixed.
-const INSTANCE_USER_PREFIX = 'bongos-';
-const INSTANCE_USER_MAX = 32;              // utmp's cap; useradd enforces it
-
-// The unix account an instance's service (and only that instance's service) runs as.
-// Deterministic — the runner derives it fresh every run rather than storing it, so a
-// re-provision can never address a different account than the one it created. PURE.
-function instanceUser(inst) {
-  const slug = String((inst && inst.slug) || '');
-  if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(slug)) {
-    throw new Error(`instanceUser: refusing to derive an account name from an invalid slug ${JSON.stringify(slug)}`);
-  }
-  const whole = INSTANCE_USER_PREFIX + slug;
-  if (whole.length <= INSTANCE_USER_MAX) return whole;
-  const digest = crypto.createHash('sha256').update(slug).digest('hex').slice(0, 8);
-  // Budget: prefix + head + '-' + 8 hex === INSTANCE_USER_MAX. Trailing dashes are
-  // stripped so the fold can never emit `--` (which useradd's NAME_REGEX rejects).
-  const head = slug.slice(0, INSTANCE_USER_MAX - INSTANCE_USER_PREFIX.length - 9).replace(/-+$/, '');
-  return `${INSTANCE_USER_PREFIX}${head}-${digest}`;
-}
-
-// The instance account's HOME — and the ONE directory the hardened unit leaves
-// writable. It is deliberately NOT under /home: the unit sets ProtectHome=read-only
-// (so one instance cannot read the operator's or a sibling's home), and the server DOES
-// write inside its config home at runtime — src/bongos/secret-box.js provisions
-// builder-secret.key under ~/.config/<configDir> on first boot. A /home account would
-// make that write EROFS and the instance would come up unable to hold a secret. PURE.
-function instanceStateDir(inst) { return path.posix.join('/var/lib', instanceUser(inst)); }
-
-// The instance's OWN Postgres login role. Same name as the unix account so an operator
-// reading `ps` and `pg_stat_activity` sees one identity, not two — a dash is legal in a
-// quoted PG identifier, and every SQL site below quotes it. PURE.
-function instanceDbRole(inst) { return instanceUser(inst); }
-
-// A fresh password for that role. base64url ([A-Za-z0-9_-]) on purpose: it needs no
-// escaping in the env file that carries it, in the dollar-quoted SQL literal that sets
-// it, or in a connection URL — the three places it travels. 32 bytes ~ 256 bits.
-// Generated per provision run, not stored: every run ALTERs the role and rewrites
-// web.env in the same pass, so the credential rotates on its own.
-function generateDbPassword() { return crypto.randomBytes(32).toString('base64url'); }
-
-// Create the instance's unix account if it is not already there, with its state dir.
-// IDEMPOTENT by construction — `id -u` short-circuits an existing account, and the
-// `install -d` re-asserts ownership and mode on every run, so a re-provision repairs a
-// hand-edited box instead of failing on it. A SYSTEM account with /usr/sbin/nologin:
-// nothing should ever log in as an instance.
-function ensureInstanceUserCmd(inst, { privileged = false } = {}) {
-  const user = instanceUser(inst), dir = instanceStateDir(inst), sudo = privileged ? 'sudo ' : '';
-  return `id -u ${user} >/dev/null 2>&1 || ${sudo}useradd --system --shell /usr/sbin/nologin --home-dir ${dir} ${user}; ` +
-         `${sudo}install -d -o ${user} -g ${user} -m 0700 ${dir}`;
-}
-
-// Let the instance account READ the checkout it runs from. The co-tenant shape's
-// WorkingDirectory is this control-plane checkout and the standalone shape's is
-// /srv/<base>/<slug>; both are owned by the app user, and a fresh system account is in
-// neither the owner nor the group, so without this the unit fails at exec with EACCES.
-// Group membership grants exactly the read the app user's group already has — it does
-// NOT re-open the two vectors this task closes: /proc/<pid>/environ stays readable only
-// by the process's own uid, and the DB now demands a password no sibling holds.
-function grantInstanceRepoReadCmd(inst, { privileged = false } = {}) {
-  return `${privileged ? 'sudo ' : ''}usermod -aG ${appGroupExpr()} ${instanceUser(inst)}`;
-}
-
-// Can this plane give a child instance its OWN unix account AT ALL? (task 1004018, ADR 0317)
-//
-// ensureInstanceUserCmd above needs uid 0 — directly, or through the `privileged` sudo
-// prefix. The self-host image runs `USER node` and installs no sudo, so there it cannot
-// run, and every child on that plane would share one uid: exactly the /proc/<pid>/environ
-// vector ADR 0281 exists to close. Probed, not configured — a runner either reaches root
-// on this plane or it does not, and an operator who wants provisioning to proceed needs
-// privilege, not a flag that says to pretend.
-//
-// The probe runs the SAME escalation the mutation will, so a pass is evidence rather than
-// inference. Read-only, no mutation, and no pipeline: a pipeline's exit status is the last
-// stage's, which would erase the difference below.
-//
-// A shell that RAN AND ANSWERED is the only failure that proves the plane cannot. Under
-// remote exec boxExec is `ssh <host> bash -s`, so an unreachable co-hosting box throws
-// here too — and answering that with "this plane cannot create accounts, provision
-// elsewhere" would be a confident wrong diagnosis that burns the intent's retry budget on
-// a network blip. Exit 1 (not root) and 127 (no sudo binary) are read as proof; ssh
-// reports its own failures as 255, so both still mean what they say across the hop.
-const ACCOUNT_PROOF_STATUS = new Set([1, 127, 9009]);
-function accountPlaneGap(exec, { privileged = false } = {}) {
-  // sh -c, not a bare test: under sudo the outer (unprivileged) shell would expand
-  // $(id -u) before sudo ever ran, and the probe would answer about the wrong user.
-  const cmd = `${privileged ? 'sudo ' : ''}sh -c 'test "$(id -u)" = 0'`;
-  try { exec(cmd); return null; } catch (e) {
-    // e.stderr is a zero-length Buffer when the command failed SILENTLY — truthy, and
-    // String()s to '' — so it has to be length-checked or it shadows the only cause there
-    // is. `test` exiting 1 writes nothing, and that is this probe's commonest refusal.
-    const stderr = e && e.stderr && e.stderr.length ? e.stderr : null;
-    const why = String(stderr || (e && e.message) || e).trim().slice(0, 200) || `exit status ${e && e.status}`;
-    if (!ACCOUNT_PROOF_STATUS.has(e && e.status)) {
-      return `could not confirm the runner can create a per-instance unix account on this plane: '${cmd}' failed (${why}). Every instance is given its own account, so provisioning refuses rather than assume — re-run once the box answers.`;
-    }
-    return `this plane cannot create a per-instance unix account, so every child instance would run as one uid and could read its siblings' secrets: '${cmd}' failed (${why}). Provision from a host where the runner is root or holds sudo (PROVISION_SUDO=1) — a shared uid is the isolation ADR 0281 exists to provide, not a detail.`;
-  }
-}
-
-// The preflight around accountPlaneGap: the narration its sibling preflights carry,
-// including the dry-run line without which the plan prints step 1c's useradd as though it
-// will work. Returns the refusal, or null to proceed. Lives here beside the account it guards.
-function accountPreflight({ exec, apply, log, privileged = false, probe = accountPlaneGap }) {
-  if (!apply) { log('  [preflight] would probe whether the runner can create this instance\'s own unix account'); return null; }
-  const missing = probe(exec, { privileged });
-  if (missing) return `Account preflight failed: ${missing}`;
-  log('  [preflight] the runner can create the instance\'s own unix account ✓');
-  return null;
-}
-
-// Create-or-rotate the instance's PG login role and hand it its OWN database — and
-// nothing else. Three statements, one psql, ON_ERROR_STOP:
-//   1. CREATE ROLE ... LOGIN PASSWORD, or ALTER ... PASSWORD when it already exists (the
-//      re-provision path — this is what rotates the credential).
-//   2. ALTER DATABASE ... OWNER TO — the role owns its own DB, so the app's DDL needs no
-//      superuser, and in PG15+ it inherits the public schema through pg_database_owner.
-//   3. REVOKE CONNECT ... FROM PUBLIC — the half that actually isolates. Postgres grants
-//      CONNECT on every database to PUBLIC by default, so per-role passwords ALONE would
-//      still leave a sibling one peer-auth hop from any other instance's data.
-// NOT a superuser and NOT CREATEDB/CREATEROLE: an instance that is compromised gets its
-// own data and no path to anyone else's.
-//
-// Runs against `postgres`, not the instance DB: ALTER DATABASE ... OWNER cannot run from
-// inside the database it renames the owner of.
-//
-// QUOTING, which is load-bearing in a way that is easy to undo by accident. Every literal
-// is DOLLAR-QUOTED and every identifier goes through format(%I), so the rendered command
-// contains no single quote and NO DOUBLE QUOTE, so it survives both executors unchanged —
-// inline /bin/sh and `bash -s` over SSH. seedFirstVersionCmd dollar-quotes for the same
-// reason; a test asserts the absence.
-function dbRoleCmd(inst, { password = null, privileged = false } = {}) {
-  const role = instanceDbRole(inst), db = dbName(inst);
-  if (!/^[A-Za-z0-9_-]+$/.test(String(password || ''))) {
-    throw new Error('dbRoleCmd: password must be a non-empty base64url string (generateDbPassword)');
-  }
-  const sql =
-    `DO $do$ BEGIN ` +
-    `IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = $r$${role}$r$) THEN ` +
-    `EXECUTE format($f$ALTER ROLE %I WITH LOGIN PASSWORD %L$f$, $r$${role}$r$, $p$${password}$p$); ` +
-    `ELSE ` +
-    `EXECUTE format($f$CREATE ROLE %I WITH LOGIN PASSWORD %L$f$, $r$${role}$r$, $p$${password}$p$); ` +
-    `END IF; ` +
-    `EXECUTE format($f$ALTER DATABASE %I OWNER TO %I$f$, $d$${db}$d$, $r$${role}$r$); ` +
-    `EXECUTE format($f$REVOKE CONNECT ON DATABASE %I FROM PUBLIC$f$, $d$${db}$d$); ` +
-    `END $do$;`;
-  return asPostgres(`psql -v ON_ERROR_STOP=1 -d postgres -c '${sql}'`, privileged);
-}
-
-// What the runner LOGS in place of dbRoleCmd, whose SQL embeds the password. Lives here,
-// beside the command, so the two cannot drift: a `shown` that outlived the secret it hides
-// would be a silent re-leak. Names every effect the real command has. PURE.
-function dbRoleCmdShown(inst) {
-  return `psql -d postgres -c '<upsert role ${instanceDbRole(inst)} + own ${dbName(inst)} + revoke PUBLIC connect>' (password redacted)`;
-}
-
-// Hand the instance role the objects the migrate just created. This is NOT belt-and-braces:
-// the privileged migrate runs as `postgres`, so every table and sequence it creates is
-// OWNED BY postgres. Owning the DATABASE does not carry ownership of objects inside it, so
-// without these grants the instance would authenticate perfectly and then fail its first
-// SELECT. The ALTER DEFAULT PRIVILEGES pair is the same statement aimed forward: it applies
-// to objects the CURRENT role creates later, which is exactly what the next migrate does —
-// so a schema migration shipped six months from now needs no second visit here.
-//
-// Runs against the instance DB (schema grants are per-database), and AFTER the migrate.
-function dbRoleGrantsCmd(inst, { privileged = false } = {}) {
-  const role = instanceDbRole(inst), db = dbName(inst);
-  // Same quoting rule as dbRoleCmd: format(%I), never a double-quoted identifier.
-  const g = (stmt) => `EXECUTE format($f$${stmt} %I$f$, $r$${role}$r$); `;
-  const sql =
-    `DO $do$ BEGIN ` +
-    g('GRANT ALL ON SCHEMA public TO') +
-    g('GRANT ALL ON ALL TABLES IN SCHEMA public TO') +
-    g('GRANT ALL ON ALL SEQUENCES IN SCHEMA public TO') +
-    g('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO') +
-    g('ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO') +
-    `END $do$;`;
-  return asPostgres(`psql -v ON_ERROR_STOP=1 -d ${db} -c '${sql}'`, privileged);
-}
-
-// Hand OWNERSHIP of everything in the schema to the instance role (task 1004735). The grants
-// above are not enough: GRANT ALL carries no right to ALTER a table or CREATE OR REPLACE a
-// function, which only the OWNER has. Later core moves migrate AS the instance role
-// (--migrate-as, task 1004512), so the first migration that changed an existing table failed
-// with "must be owner of table tasks" and the move rolled back — toast, 2026-10-14.
-//
-// Object by object, never REASSIGN OWNED BY postgres: that also reassigns every SHARED object
-// postgres owns — sibling projects' whole databases included. Skipped on purpose:
-//   • objects an EXTENSION owns (pg_depend deptype e) — not the project's, and ALTER errors;
-//   • sequences linked to a table column (deptype a/i) — they follow their table, and an
-//     ALTER SEQUENCE on one errors;
-//   • row types of tables and auto-made array types — they follow their table / element.
-// Idempotent: only objects not already owned by the role are touched, so a re-run is a no-op.
-//
-// Same quoting rule as the commands above: dollar-quoted literals, format(%I)/regclass for
-// identifiers — no single or double quote, so it rides psql -c '…' and bash -s unchanged. And
-// never the text $p$: that marks a password for the runner's log redaction (provision.mjs), which
-// is why kind lists are array literals and a procedure is the ELSE of f/w/a.
-// Run as postgres, in the instance's own database: provision.js step 2b (right after the
-// grants), and the migrate_not_owner remedy in wedge-remedy.js for projects provisioned before.
-function dbOwnershipSql(role, schema = 'public') {
-  if (!/^[A-Za-z0-9_-]{1,63}$/.test(String(role || ''))) throw new Error(`dbOwnershipSql: role ${JSON.stringify(role)} is not a plain role name`);
-  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(String(schema))) throw new Error(`dbOwnershipSql: schema ${JSON.stringify(schema)} is not a plain schema name`);
-  const r = `$r$${role}$r$`;
-  const ns = `$s$${schema}$s$::regnamespace`;
-  const notExt = (cat, col, types = '$e$e$e$') =>
-    `NOT EXISTS (SELECT 1 FROM pg_depend d WHERE d.classid = $c$${cat}$c$::regclass AND d.objid = ${col} AND d.deptype IN (${types}))`;
-  const k = (x) => `$k$${x}$k$`;
-  const t = (x) => `$t$${x}$t$`;
-  const anyOf = (list) => '$k${' + list + '}$k$::char[]'; // an array literal, not $k$p$k$ — see the $p$ note above
-  return `DO $own$ DECLARE o record; BEGIN ` +
-    // tables, partitions, views, materialized views, foreign tables — their indexes, row types
-    // and column-owned sequences follow them
-    `FOR o IN SELECT c.oid::regclass AS obj, c.relkind FROM pg_class c WHERE c.relnamespace = ${ns} ` +
-    `AND c.relkind = ANY (${anyOf('r,p,v,m,f')}) AND c.relowner <> ${r}::regrole AND ${notExt('pg_class', 'c.oid')} LOOP ` +
-    `EXECUTE format($f$ALTER %s %s OWNER TO %I$f$, CASE o.relkind WHEN ${k('v')} THEN ${t('VIEW')} WHEN ${k('m')} THEN ${t('MATERIALIZED VIEW')} WHEN ${k('f')} THEN ${t('FOREIGN TABLE')} ELSE ${t('TABLE')} END, o.obj, ${r}); END LOOP; ` +
-    // free-standing sequences
-    `FOR o IN SELECT c.oid::regclass AS obj FROM pg_class c WHERE c.relnamespace = ${ns} AND c.relkind = ${k('S')} ` +
-    `AND c.relowner <> ${r}::regrole AND ${notExt('pg_class', 'c.oid', '$e$e$e$, $e$a$e$, $e$i$e$')} LOOP ` +
-    `EXECUTE format($f$ALTER SEQUENCE %s OWNER TO %I$f$, o.obj, ${r}); END LOOP; ` +
-    // functions, procedures, aggregates — what CREATE OR REPLACE needs to own
-    `FOR o IN SELECT p.oid::regprocedure AS obj, p.prokind FROM pg_proc p WHERE p.pronamespace = ${ns} ` +
-    `AND p.proowner <> ${r}::regrole AND ${notExt('pg_proc', 'p.oid')} LOOP ` +
-    `EXECUTE format($f$ALTER %s %s OWNER TO %I$f$, CASE o.prokind WHEN ${k('f')} THEN ${t('FUNCTION')} WHEN ${k('w')} THEN ${t('FUNCTION')} WHEN ${k('a')} THEN ${t('AGGREGATE')} ELSE ${t('PROCEDURE')} END, o.obj, ${r}); END LOOP; ` +
-    // free-standing types: enums, domains, ranges, and composite types made by CREATE TYPE
-    `FOR o IN SELECT y.oid::regtype AS obj, y.typtype FROM pg_type y WHERE y.typnamespace = ${ns} AND y.typowner <> ${r}::regrole ` +
-    `AND (y.typtype = ANY (${anyOf('e,d,r')}) OR (y.typtype = ${k('c')} AND EXISTS (SELECT 1 FROM pg_class c WHERE c.oid = y.typrelid AND c.relkind = ${k('c')}))) ` +
-    `AND ${notExt('pg_type', 'y.oid')} LOOP ` +
-    `EXECUTE format($f$ALTER %s %s OWNER TO %I$f$, CASE o.typtype WHEN ${k('d')} THEN ${t('DOMAIN')} ELSE ${t('TYPE')} END, o.obj, ${r}); END LOOP; ` +
-    `END $own$;`;
-}
-
-// The ownership handover as a command (task 1004735): provisioning runs it after the grants,
-// and the migrate_not_owner remedy runs it for a project provisioned before that. PURE.
-function dbOwnershipCmd(inst, { privileged = false } = {}) {
-  return asPostgres(`psql -v ON_ERROR_STOP=1 -d ${dbName(inst)} -c '${dbOwnershipSql(instanceDbRole(inst))}'`, privileged);
-}
-
-// ── 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.
-
-// parseTargetRef + instanceRepoRemote (and resolveOwnerGithubToken, below the scaffold)
-// now live in the ./provision-repo-auth.js leaf and are re-exported unchanged from here —
-// upgrade.js needs them and is inside the merge resolver's executed closure, which a require of
-// this file would have widened by five (task 1003081; see that module's header).
-
-// 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. (That was originally because the
-// registry package was PRIVATE; since ADR 0283 it is public and a token would buy
-// nothing either way. The file: pin is kept for the reason in ADR 0168 — a child is born
-// on the core its parent actually runs — not for access control.) 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;
-}
-
-// Can package-core.js enumerate this checkout from GIT? It builds the core set from
-// `git ls-tree` at a ref, so a checkout with no `.git` aborts at `git rev-parse HEAD` —
-// and that is not a broken install, it is the SHIPPED SELF-HOST IMAGE: .dockerignore
-// excludes .git by design, so /app is a complete core source tree with no history
-// (task 1003995). The presence of `.git` — a directory in a clone, a file in a linked
-// worktree — is the whole question. fs injectable for tests; read-only → dry-run safe.
-function coreCheckoutHasGit({ repoRoot = REPO_ROOT, fsImpl = fs } = {}) {
-  return fsImpl.existsSync(path.join(repoRoot, '.git'));
-}
-
-// The core version THIS control plane runs — what the ladder below would vend: the
-// pinned tarball's version, else the registry-installed package's, else the checkout's
-// CORE_VERSION. fs reads only → dry-run safe.
-function runningCoreVersion({ instanceRoot, coreV }) {
-  const pinned = installedCoreTarball({ instanceRoot });
-  if (pinned) return require('./upgrade').versionFromTgzPath(path.basename(pinned)) || coreV;
-  const packSrc = installedCorePackDir({ instanceRoot });
-  return packSrc ? packSrc.version : coreV;
-}
-
-// Which core a hosted project is given (task 1004299, ADR 0361 D5). PURE. Since merges
-// publish as candidates, the platform hall runs ahead of the registry's `latest` label by
-// design — and the ladder below vends whatever the hall runs, so every new project would
-// be born on a version nobody released. When the hall is AHEAD of the release, the project
-// gets the release instead. Equal → the running core, byte-exact, as before.
-//
-// BEHIND the release is real too (task 1004556): the runner that scaffolds is not always
-// the platform hall. On cloudbongos.com it ran from a patch-channel install that could not
-// cross the 1.21.0 minor, so it sat on 1.20.82 and every new project was born there,
-// without founding mode (1.21+). The release is what ADR 0361 D5 promises a new project,
-// and a released core has already run on the platform hall, so the runner's lag must not
-// set the project's version: behind → the release, packed from the registry, too.
-//
-// No readable label → the running core, deliberately (fail-open). Until candidates are
-// armed the running core IS the release; vendoring is the path that works with no
-// registry at all (ADR 0292); and refusing project creation over a registry blip is worse
-// for the person creating it than a newer-than-released core in the rare outage window.
-function projectCoreDecision({ running, released }) {
-  if (!released || !isStable(released)) return { version: running, source: 'running', reason: 'no readable released (latest) label — using the core this hall runs' };
-  if (compareSemver(running, released) > 0) return { version: released, source: 'released', reason: `this hall runs ${running}, ahead of the release` };
-  if (compareSemver(running, released) < 0) return { version: released, source: 'released', reason: `this runner is on ${running}, behind the release` };
-  return { version: running, source: 'running', reason: `this hall runs the released core ${released}` };
-}
-
-// The I/O half: read the `latest` label through the injected exec (so a dry run and the
-// test harness's stub exec never touch the network), then decide. `npm view` is fine
-// here — provisioning is a runner script, not a request handler (ADR 0293's objection).
-function projectCoreTarget({ instanceRoot, coreV, exec, log, tag = '[core]' }) {
-  const running = runningCoreVersion({ instanceRoot, coreV });
-  const res = exec(`npm view ${CORE_PKG} dist-tags.latest`, { allowFail: true });
-  const label = String((res && res.ok !== false && res.stdout) || '').trim();
-  const decision = projectCoreDecision({ running, released: label || null });
-  log(`  ${tag} ${decision.source === 'released' ? `giving the project the RELEASED core ${decision.version}` : `giving the project core ${decision.version}`} — ${decision.reason} (task 1004299)`);
-  return decision;
-}
-
-// Resolve a vendorable @bongos/core tarball — the four-rung ladder, freshest-correct
-// first, shared by the fresh scaffold and the re-provision pin refresh (task 1003050).
-// A `target` from projectCoreTarget with source 'released' short-circuits it: the
-// project gets the released version packed from the registry, not this hall's core.
-//   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;
-//   4. a core checkout with NO git history — the self-host image — packs its working
-//      tree via package-core.js --from-worktree (task 1003995). LAST because it is the
-//      only rung with no commit to anchor the artifact to: whenever history is there,
-//      rung 3's reproducible build is the better answer for the identical file set.
-// 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, repoRoot = REPO_ROOT, exec, log, coreV, tag = '[core]', target = null }) {
-  if (target && target.source === 'released') {
-    // target.version passed isStable (digits and dots only), so it is shell-safe.
-    const v = target.version;
-    const packDest = path.join(os.tmpdir(), `bongos-core-released-${v}`);
-    log(`  ${tag} packing the released core ${v} from the registry — not the candidate this hall runs (task 1004299)`);
-    exec(`mkdir -p ${packDest}`);
-    exec(`npm pack ${CORE_PKG}@${v} --pack-destination ${packDest}`);
-    return { tgz: path.join(packDest, `bongos-core-${v}.tgz`), packDest };
-  }
-  const pinned = installedCoreTarball({ instanceRoot });
-  if (pinned) {
-    log(`  ${tag} reusing the pinned core tarball this control plane runs (${path.basename(pinned)}) — no source rebuild (task 1002275)`);
-    return { tgz: pinned, packDest: null };
-  }
-  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.
-    const 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}`);
-    return { tgz: path.join(packDest, packSrc.tarballName), packDest };
-  }
-  if (coreCheckoutHasGit({ repoRoot })) {
-    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
-  } else {
-    log(`  ${tag} this checkout IS the core and carries no git history — packing the working tree (package-core.js --from-worktree, task 1003995)`);
-    exec(`node scripts/gds/package-core.js --from-worktree`);
-  }
-  return { tgz: path.join(repoRoot, 'dist', `bongos-core-${coreV}.tgz`), packDest: null };
-}
-
-// 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.
-// The signed-in builder who owns the instance — the founding firstAdmin. Best-effort:
-// no db, no row, or a query error → null, and callers fall back to the repo owner in
-// target_ref. Shared by the scaffold's branding.firstAdmin and web.env's
-// <prefix>_FIRST_ADMIN (task 1003240) so the two can never disagree.
-async function ownerLoginOf(inst, db) {
-  if (!inst || !inst.owner_builder_id || !db || typeof db.query !== 'function') return null;
-  try {
-    const r = await db.query('SELECT github_login FROM builders WHERE id = $1', [inst.owner_builder_id]);
-    return r && r.rows && r.rows[0] && r.rows[0].github_login ? r.rows[0].github_login : null;
-  } catch { return null; }
-}
-
-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)) {
-    const resumed = deps.apply ? await resumeUnpushedScaffold(inst, deps, { root, repo, mode }) : null;
-    if (resumed) return resumed;
-    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);
-  // The released core, not this hall's candidate (task 1004299).
-  const target = projectCoreTarget({ instanceRoot: deps.instanceRoot, coreV, exec, log, tag: '[scaffold] core:' });
-  const pinV = target.version;
-  log(mode === 'adopt'
-    ? `  [scaffold] ${repo.owner}/${repo.name} → ${root} (ADOPT: clone → layer additively → pin core ${pinV} → commit → fast-forward push)`
-    : `  [scaffold] ${repo.owner}/${repo.name} → ${root} (clone → materialize → pin core ${pinV} → commit → push)`);
-
-  // Owner login = the founding firstAdmin. Best-effort; the spec falls back to the repo owner.
-  const ownerLogin = await ownerLoginOf(inst, db);
-
-  // 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 cred = await scaffoldCredential(inst, repo, deps, writeFile);
-  const { credFile, httpsUrl, credOpt } = cred;
-
-  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: vendor a tarball built from THIS control-plane checkout
-    // (offline, proven — task 2053).
-    //
-    // This used to be a fork: an opt-in env var selected the registry, and a missing npm
-    // credential silently failed it soft back to vendored. Both halves were auth-era and both
-    // are gone (task 1003878) — @bongos/core is public, so nothing needs a credential, and an
-    // env var that silently changed which install path ran is the divergence behind task
-    // 1003520. tests/provision.mjs pins both retired names and proves they are inert.
-    //
-    // Vendored stays the default here for a reason that has nothing to do with auth and
-    // survives the package going public: THIS CHECKOUT IS ROUTINELY AHEAD OF THE REGISTRY.
-    // A control plane on an unreleased CORE_VERSION has no published version to install, so
-    // the registry path would 404 on exactly the commits an operator most wants to stand up.
-    // Whether the vendored path still earns its keep at all is gate 6's call (task 1003879).
-
-    // 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.
-    //
-    // Core resolution is vendored (--vendor-core): a tarball built from this checkout,
-    // file:-pinned. init still accepts --registry-core for an operator who explicitly wants
-    // a published version, and that flag no longer needs any credential.
-    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));
-    // Vendored tarball — resolveVendorableCoreTarball's four-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:', target,
-    });
-    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);
-    }
-    // Adopt layers config only where ABSENT, so an owner's existing config/branding.json
-    // keeps whatever envPrefix it carried — and web.env is written under the platform's.
-    // Mercury's said CLOUDBONGOS: it read none of its credentials or settings (task 1004573).
-    // Rewrite just that one value, in this same commit, so the repo and web.env agree.
-    const packPath = path.join(root, 'config', 'branding.json');
-    if (mode === 'adopt' && fs.existsSync(packPath)) {
-      const fixed = normalizePackEnvPrefix(fs.readFileSync(packPath, 'utf8'));
-      if (fixed) {
-        writeFile(packPath, fixed.text);
-        log(`  [scaffold] config/branding.json envPrefix ${fixed.from} → the platform's, so the project reads the settings it is given`);
-      }
-    }
-    exec(`git -C ${root} config user.name "${provisionerBotName()}"`);
-    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 ${pinV} (provision.js, ADR 0121)`
-      : `chore: scaffold ${inst.slug} on a pinned @bongos/core ${pinV} (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.
-    pushScaffold({ exec, log, root, repo, mode, cred });
-    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 });
-  }
-}
-
-// The owner-token credential the scaffold's git network ops ride (rationale at the call site in
-// scaffoldStandaloneRepo). The URL carries only the `x-access-token` username, so it is safe in a
-// logged argv. credFile null → no token → SSH origin fallback; the caller `rm -f`s it in a finally.
-async function scaffoldCredential(inst, repo, deps, writeFile) {
-  const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[scaffold]' });
-  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 });
-  return { credFile, httpsUrl, credOpt };
-}
-
-function pushScaffold({ exec, log, root, repo, mode, cred }) {
-  if (cred.credFile) {
-    exec(`git -C ${root} ${cred.credOpt}push ${cred.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)`);
-  }
-}
-
-// alreadyScaffolded is a LOCAL marker, and a scaffold whose push failed leaves it behind: the
-// re-run skipped the never-done push, then wedged at step 2's `git pull --ff-only` against the
-// still-empty remote (task 1002718, F12). Only a remote that ANSWERS with no main re-pushes — an
-// unreachable one keeps the old skip, as it can't tell "never pushed" from "offline". Returns
-// null when there is nothing to resume.
-async function resumeUnpushedScaffold(inst, deps, { root, repo, mode }) {
-  const exec = deps.controlExec || deps.exec;
-  const writeFile = deps.controlWriteFile || deps.writeFile;
-  let cred = null;
-  let probe = { softFailed: true };
-  try {
-    // This runs on every re-provision of a LIVE instance, so a probe that cannot even start
-    // (token lookup, credential write) must keep the skip — never fail a healthy instance.
-    try {
-      cred = await scaffoldCredential(inst, repo, deps, writeFile);
-      probe = exec(`git -C ${root} ${cred.credOpt}ls-remote --heads ${cred.credFile ? cred.httpsUrl : 'origin'} main`, { allowFail: true });
-    } catch { deps.log(`  [scaffold] could not probe ${repo.owner}/${repo.name} for main — keeping the skip`); }
-    if (probe.softFailed || String(probe.stdout || '').trim()) return null;
-    deps.log(`  [scaffold] ${root} is scaffolded but ${repo.owner}/${repo.name} has no main — re-pushing the scaffold that never landed`);
-    pushScaffold({ exec, log: deps.log, root, repo, mode, cred });
-    return { ok: true, resumed: true, mode };
-  } finally {
-    if (cred && cred.credFile) exec(`rm -f ${cred.credFile}`, { allowFail: true });
-  }
-}
-
-// ── private-repo deploy key (ADR 0176, task 1002735; walk finding N4) ────────────
-
-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.
-//
-// `deps.intendedPrivate` (task 1004167) declares that the repo is ABOUT to be made
-// private, so the wiring runs before the flip rather than after it. Opt-in, and it
-// widens only WHEN we wire: the key stays read-only and repository ADMIN is still
-// required. It also HARDENS the two soft skips — no credential, GitHub unreachable —
-// into refusals, because a caller that has committed to flipping cannot be handed an
-// unwired checkout. Its one caller is the `repo-private` runner leg
-// (provision-repo-private.js, task 1004193); the owner-facing route that enqueues that
-// intent is what remains (split (c) of task 1003078).
-async function ensurePrivateRepoAccess(inst, deps) {
-  const { log, apply } = deps;
-  const exec = deps.controlExec || deps.exec;
-  if (inst.hosting_shape !== 'cloud-host') 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(deps.intendedPrivate === true
-      ? `  [repo-auth] would treat ${repo.owner}/${repo.name} as ABOUT TO BE MADE PRIVATE (pre-flip) and mint + register a read-only deploy key, wiring origin + core.sshCommand to it before the flip (ADR 0176)`
-      : `  [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) {
-    // With an intent declared the caller is ABOUT to flip, so a soft skip hands back
-    // an unwired checkout and the flip then breaks the recurring pull for good. The
-    // same missing credential is only a warning when nobody has committed to flipping.
-    if (deps.intendedPrivate === true) {
-      throw new Error(`${repo.owner}/${repo.name} cannot be made private: there is no usable GitHub credential stored for this project, and without one its deploy key cannot be registered — which would break the next deploy. Reconnect the project's GitHub access, then try again.`);
-    }
-    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.`);
-    }
-    // Same asymmetry as the missing credential above: soft when nothing is committed,
-    // hard once the caller has declared the flip.
-    if (deps.intendedPrivate === true) {
-      throw new Error(`${repo.owner}/${repo.name} cannot be made private right now: GitHub could not be reached to set up its deploy key (${e && e.message}). Nothing has been changed — 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;
-
-  // A flip-to-private must wire BEFORE it flips — a deploy key authenticates fine
-  // against a still-public repo, so wiring first leaves no broken window, while
-  // flipping first breaks the very next deploy pull. At that moment GitHub still
-  // answers `private: false`, so the observed value is the wrong thing to branch on:
-  // untouched, this takes the public path and (worse, if a key file exists) actively
-  // UN-wires. `intendedPrivate` is the caller declaring where the repo is going.
-  // Opt-in: absent, every path below is exactly what it was.
-  const treatPrivate = info.private || deps.intendedPrivate === true;
-
-  if (!treatPrivate) {
-    // 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(info.private
-    ? `  [repo-auth] ${repo.owner}/${repo.name} is PRIVATE — wiring its own read-only deploy key (ADR 0176)`
-    : `  [repo-auth] ${repo.owner}/${repo.name} is ABOUT TO BE MADE PRIVATE — wiring its own read-only deploy key first (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.`, { cause: e });
-  }
-  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 "${provisionerBotName()}"`,
-      `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']);
-  if (!/^file:/.test(String(pinnedDep || '').trim())) {
-    const plan = planCorePinRefresh({ pinnedDep, coreVersion: coreV });
-    log(`  [core-pin] ${plan.reason}`); return plan;
-  }
-  // Heal toward the core a project is GIVEN — the release when this hall runs ahead of it —
-  // or the pin a brand-new project was just born on is bumped straight back to the
-  // candidate in the same provisioning run (task 1004299).
-  const target = projectCoreTarget({ instanceRoot: deps.instanceRoot, coreV, exec, log, tag: '[core-pin]' });
-  const plan = planCorePinRefresh({ pinnedDep, coreVersion: target.version });
-  if (plan.action === 'current') { log(`  [core-pin] committed pin already matches the core this project is given (${target.version})`); return plan; }
-  log(`  [core-pin] committed pin ${safeVersionLabel(plan.pinned)} differs from the core this project is given (${target.version}) — 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]', target,
-  });
-  try {
-    const targetVersion = upgrade.versionFromTgzPath(path.basename(tgz)) || target.version;
-    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 runs this control-plane checkout's src/.
-
-module.exports = {
-  appGroupExpr,
-  appUser,
-  accountPlaneGap,
-  accountPreflight,
-  CORE_PKG_DIR,
-  INSTANCE_GITIGNORE,
-  alreadyScaffolded,
-  ownerLoginOf,
-  asPostgres,
-  buildCorePinRefreshCommit,
-  coreCheckoutHasGit,
-  dbCreateCmd,
-  dbName,
-  dbRoleCmd,
-  dbRoleCmdShown,
-  dbRoleGrantsCmd,
-  dbOwnershipCmd,
-  dbOwnershipSql,
-  deployKeyPath,
-  deployKeyTitle,
-  ensureInstanceUserCmd,
-  ensurePrivateRepoAccess,
-  generateDbPassword,
-  grantInstanceRepoReadCmd,
-  installedCorePackDir,
-  installedCoreTarball,
-  instanceDbRole,
-  instanceInitSpec,
-  instanceRepoRemote,
-  instanceStateDir,
-  instanceUser,
-  migrateCmd,
-  onboardMode,
-  parseTargetRef,
-  planCorePinRefresh,
-  refreshStandaloneCorePin,
-  resolveOwnerGithubToken,
-  resolveVendorableCoreTarball,
-  projectCoreDecision,
-  projectCoreTarget,
-  runningCoreVersion,
-  safeVersionLabel,
-  scaffoldStandaloneRepo,
-  seedFirstVersionCmd,
-  selfInstanceRoot,
-  standaloneInstallCmd,
-  standaloneMigrateCmd,
-  standalonePullCmd,
-  standaloneRegenDocsCmd,
-  standaloneRoot,
-};
+require('../bongos/forwarder.js').forward(module, 'provision-repo.js');