@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/provision-repo.js

@@ -0,0 +1,1337 @@
+// scripts/bongos/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/bongos/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.
+
+'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/bongos/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/bongos/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/bongos/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/bongos/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,
+};