@bongos/core 1.19.332 → 1.19.334

package/scripts/gds/provision-repo.js

@@ -0,0 +1,849 @@
+// 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.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { CONFIG, REPO_ROOT, coreVersionSafe, hasNpmToken, provisionerBotEmail, registryCoreRequested } = require('./provision-config.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. `track` is set EXPLICITLY: versions.track is NOT NULL with no default (mig 112
+// dropped the CHECK), and 'product' matches the canonical V1 seed in 003_pms.sql.
+//
+// The id/name/done_when come from instanceInitSpec so the starter version has ONE
+// source of truth (the same spec the greenfield `bongos init` seed uses). SQL string
+// literals are DOLLAR-QUOTED ($v$…$v$) so the whole -c argument is single-quoted —
+// the one form that is safe UNCHANGED across all three executors: inline (/bin/sh),
+// over SSH (bash -s), AND embedded in a dedicated droplet's cloud-init (bash -lc "…"),
+// with no nested-quote or $-expansion hazard.
+function seedFirstVersionCmd(inst, { privileged = false } = {}) {
+  const v = instanceInitSpec(inst).version;
+  const q = (s) => `$v$${s}$v$`;                 // dollar-quoted literal (no value contains a single quote or $)
+  const sql =
+    `INSERT INTO versions (id, name, track, status, done_when) ` +
+    `SELECT ${q(v.id)}, ${q(v.name)}, $v$product$v$, $v$building$v$, ${q(v.done_when)} ` +
+    `WHERE NOT EXISTS (SELECT 1 FROM versions); ` +
+    `INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, sort_order) ` +
+    `SELECT ${q(v.id)}, $v$first-goal$v$, ${q(v.done_when)}, 10 ` +
+    `WHERE EXISTS (SELECT 1 FROM versions WHERE id = ${q(v.id)}) ` +
+    `AND NOT EXISTS (SELECT 1 FROM done_when_criteria WHERE version_id = ${q(v.id)} AND criterion_id = $v$first-goal$v$);`;
+  return asPostgres(`psql -v ON_ERROR_STOP=1 -d ${dbName(inst)} -c '${sql}'`, privileged);
+}
+
+// ── STANDALONE shape (hosting_shape='standalone', ADR 0108, task 1978) ────────
+// A standalone instance runs from its OWN repo checkout (host content: config/,
+// migrations/instance/, the core PIN in package.json) with @bongos/core installed
+// as an npm DEPENDENCY — NOT the shared control-plane checkout the co-tenant shape uses.
+// It is the ADR 0108 DESTINATION model; these generators make provision.js drive the
+// scripts/deploy/deploy-instance.sh runbook API-driven instead of by hand.
+const CORE_PKG_DIR = 'node_modules/@bongos/core';
+// The unix account the instance's Node process + its backup timer run as. Mirrors
+// serviceUnit's hardcoded `User=lars`/`Group=lars` (the droplet's app user); kept as
+// one constant so the backup dir owner + the backup unit's User= can't drift from it.
+const APP_USER = 'lars';
+function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return path.posix.join(base, inst.slug); }
+// Sync the instance's own repo (host content + the core pin). Mirrors deploy-instance.sh
+// step 1 — assumes the repo is already cloned at standaloneRoot (initial clone is a
+// precondition, like the runbook's `git pull`). Run with cwd = standaloneRoot.
+function standalonePullCmd() { return `git pull --ff-only origin main`; }
+// Install the pinned core + instance deps — replaces co-tenant's shared checkout
+// (deploy-instance.sh step 2). Run with cwd = standaloneRoot.
+function standaloneInstallCmd() { return `npm ci --omit=dev`; }
+// Migrate core + instance from the INSTANCE root's copy of the three-root migrate.sh
+// (the installed core's, falling back to an in-tree copy — deploy-instance.sh step 3).
+// Run with cwd = standaloneRoot.
+function standaloneMigrateCmd(inst, { privileged = false } = {}) {
+  // Privileged: run as postgres (task 2066), passing env via `env …` so it survives
+  // sudo's env reset (the instance root must be postgres-readable, ADR 0128).
+  return privileged
+    ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`
+    : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`;
+}
+// Regenerate the instance's whole-file navigation docs (session-log index) from the pinned core,
+// AFTER the pull+install+migrate — the standalone analogue of the monorepo's deploy-prod.sh regen
+// block (ADR 0110 §2, task 1002314). Best-effort + LOUD (the script always exits 0 + prints
+// ::ERROR:: on a generator failure) so a stale/absent nav doc never fails a deploy. Run with
+// cwd = standaloneRoot so resolveInstanceRoot() writes into the instance repo. Without this a
+// standalone instance's docs never refresh on deploy — the gap the owner hit ("docs didn't
+// transfer from primea"): its bespoke pull-deploy regenerated nothing.
+function standaloneRegenDocsCmd() { return `node ${CORE_PKG_DIR}/scripts/gds/regen-instance-docs.js`; }
+
+// ── STANDALONE scaffold (ADR 0108 / 0125, task 2055) ──────────────────────────
+// The MISSING first leg of the greenfield "one guided flow": provision.js used to
+// THROW if the instance repo wasn't already cloned. These generate + run the scaffold
+// that clones an EMPTY target_ref and turns it into an installable, bootable instance.
+
+// Parse an 'owner/repo' (or a github SSH/HTTPS URL) target_ref → { owner, name }.
+// Null when unparseable, so the scaffold can fail with actionable guidance.
+function parseTargetRef(ref) {
+  const m = String(ref || '').trim()
+    .replace(/^git@[^:]+:/, '')
+    .replace(/^https?:\/\/[^/]+\//, '')
+    .match(/^([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/);
+  return m ? { owner: m[1], name: m[2] } : null;
+}
+
+// The git remote for an instance's OWN repo. Reuses the SAME SSH deploy alias the
+// control-plane checkout uses (git@<alias>:<owner>/<repo>.git) — NO secret in the
+// command (SSH-key auth, nothing to leak into journald), consistent with how the
+// platform repo is wired. Standing up a new instance repo therefore needs only that
+// the control plane's deploy key has WRITE access to that repo (ADR 0125). Alias is
+// overridable via PROVISION_GIT_SSH_ALIAS.
+function instanceRepoRemote(repo, { sshAlias = process.env.PROVISION_GIT_SSH_ALIAS || 'github-deploy' } = {}) {
+  return `git@${sshAlias}:${repo.owner}/${repo.name}.git`;
+}
+
+// A minimal, VALID `bongos init` spec (init.validateSpec greenfield) from the
+// provisioning row + the owner's github login. The scaffold produces a bootable,
+// NEUTRAL instance; the owner brands + scopes it later via init's kickoff tasks.
+function instanceInitSpec(inst, { ownerLogin } = {}) {
+  const repo = parseTargetRef(inst.target_ref);
+  return {
+    identity: { productName: inst.slug },
+    repo: repo || { owner: ownerLogin || 'owner', name: inst.slug },
+    firstAdmin: ownerLogin || (repo && repo.owner) || 'owner',
+    currency: { label: 'credits' },
+    domains: { publicOrigin: inst.domain ? `https://${inst.domain}` : `http://localhost:${inst.port || 3000}` },
+    modules: [],
+    version: { id: 'V1', name: 'V1', done_when: 'A task goes claim → grade → ship.' },
+  };
+}
+
+// The .gitignore a scaffolded instance repo carries: keep node_modules + the local
+// dist/ + secrets OUT of the commit, while the vendored core tarball (vendor/*.tgz)
+// and package-lock.json stay IN — `npm ci` on deploy resolves the pinned core from
+// the committed tarball (ADR 0108), so they MUST be tracked.
+//
+// docs/session-log-index.md is a WHOLE-FILE generated navigation doc (ADR 0110): every byte is
+// machine-owned, regenerated at deploy by regen-instance-docs.js (task 1002314) into the served
+// tree. Untracked so `git reset --hard origin/main` never wipes it and no branch can diff it —
+// the same reasoning the core's own .gitignore applies to it. (docs/repo-map.md is listed for
+// parity/forward-compat; it is core-scoped today so a standalone instance doesn't generate its
+// own — see regenerateNavDocs() in upgrade.js — but ignoring it costs nothing and prevents a
+// stray future write from entering the tree.)
+const INSTANCE_GITIGNORE = [
+  'node_modules/', 'dist/', '.env', '.env.local', '*.log',
+  '# Whole-file generated navigation docs — regenerated at deploy (ADR 0110, task 1002314).',
+  'docs/session-log-index.md', 'docs/repo-map.md', '',
+].join('\n');
+
+// A PRE-BUILT @bongos/core tarball this control plane can vendor into a NEW instance
+// WITHOUT rebuilding from source — the consumer-control-plane fix (task 1002275).
+//
+// The scaffold's default core-install path rebuilds the tarball with package-core.js,
+// which enumerates GIT-TRACKED files (`git -C REPO_ROOT ls-tree`). That works from a core
+// SOURCE checkout, but NOT when this runner is ITSELF a consumer instance whose core is an
+// installed npm dependency: provision.js then runs out of node_modules/@bongos/core, so
+// REPO_ROOT points INSIDE gitignored node_modules, git sees ZERO tracked files there, and
+// package-core aborts ("the core set is EMPTY") — the scaffold never pushes and the freshly
+// created repo is left EMPTY (seen live: trial/test on cloudbongos.com).
+//
+// But the exact pinned tarball this instance installed FROM is on disk, named by its own
+// package.json ("@bongos/core": "file:vendor/bongos-core-<v>.tgz"). Reuse it: byte-identical,
+// already proven, and the child pins the SAME core the hub runs. Returns an absolute .tgz
+// path, or null on a source checkout (no `file:` core pin) — where package-core.js is the
+// right, unchanged path. `instanceRoot` defaults to $BONGOS_INSTANCE_ROOT (what
+// infra/core-node.sh resolves against) else process.cwd() (the runner's WorkingDirectory).
+// fs injectable for tests. PURE-ish (fs reads only, no mutation → dry-run safe).
+function installedCoreTarball({ instanceRoot, fsImpl = fs } = {}) {
+  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
+  catch { return null; }               // no/unreadable package.json → treat as a source checkout
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  // Both scope aliases the loader accepts (infra/core-node.sh checks the same two).
+  for (const name of ['@bongos/core', '@cloudbongos/core']) {
+    const m = /^file:(.+\.tgz)$/.exec(String(deps[name] || '').trim());
+    if (m) {
+      const abs = path.resolve(root, m[1]);
+      if (fsImpl.existsSync(abs)) return abs;   // a dangling pin (tarball pruned) → fall through to null
+    }
+  }
+  return null;
+}
+
+// The REGISTRY-pinned sibling of installedCoreTarball (task 1002706). After a control
+// plane moves its own core pin off the vendored tarball onto the npm registry (the
+// cloudbongos.com cutover, task 1002621), its package.json holds a semver pin — no
+// `file:` — so installedCoreTarball returns null and the scaffold would fall into the
+// package-core.js source rebuild, which ABORTS on a consumer instance (the empty-set
+// abort of task 1002275, resurrected by the cutover). The installed package itself is
+// still the exact core this hub runs: return its node_modules dir + version + the
+// `npm pack` tarball name so the scaffold can pack it into a vendorable .tgz. The child
+// stays file:-pinned — its owner needs no npm token (the registry package is PRIVATE
+// until the ADR 0134 go-public step). Returns { dir, version, tarballName } or null
+// (a file: pin, an uninstalled dep, or a source checkout). fs reads only → dry-run safe.
+function installedCorePackDir({ instanceRoot, fsImpl = fs } = {}) {
+  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
+  catch { return null; }               // no/unreadable package.json → a source checkout
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  for (const name of ['@bongos/core', '@cloudbongos/core']) {
+    const spec = String(deps[name] || '').trim();
+    if (!spec || spec.startsWith('file:')) continue;   // file: pins belong to installedCoreTarball
+    const dir = path.join(root, 'node_modules', ...name.split('/'));
+    try {
+      const installed = JSON.parse(fsImpl.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      const version = installed && installed.version ? String(installed.version) : null;
+      if (!version) continue;
+      // npm pack names a scoped tarball <scope>-<name>-<version>.tgz (no @, / → -).
+      const base = String(installed.name || name).replace(/^@/, '').replace(/\//g, '-');
+      return { dir, version, tarballName: `${base}-${version}.tgz` };
+    } catch { /* pinned but not installed → fall through */ }
+  }
+  return null;
+}
+
+// Resolve a vendorable @bongos/core tarball — the three-rung ladder, freshest-correct
+// first, shared by the fresh scaffold and the re-provision pin refresh (task 1003050):
+//   1. a `file:`-pinned control plane reuses its own pinned tarball (task 1002275 —
+//      rebuilding via package-core.js aborts with an EMPTY core set when this runner
+//      IS a consumer instance, leaving new repos empty);
+//   2. a REGISTRY-pinned consumer (the post-1002621 mothership shape) packs the core
+//      it has INSTALLED — the child pins the SAME, CURRENT core the hub runs, ending
+//      the frozen-old-tarball births (task 1002706, gap 13) without requiring the
+//      child's owner to hold a token for the still-private registry package;
+//   3. a genuine core source checkout rebuilds fresh via package-core.js.
+// Returns { tgz, packDest } — packDest (set only on rung 2) is a temp dir the CALLER
+// must `rm -rf` once the tarball has been vendored.
+function resolveVendorableCoreTarball({ instanceRoot, exec, log, coreV, tag = '[core]' }) {
+  let tgz = installedCoreTarball({ instanceRoot });
+  let packDest = null;
+  if (tgz) {
+    log(`  ${tag} reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
+  } else {
+    const packSrc = installedCorePackDir({ instanceRoot });
+    if (packSrc) {
+      // Keyed by VERSION, not slug: no request-derived value enters this command, and
+      // two concurrent scaffolds of the same core pack identical bytes — collision-safe.
+      packDest = path.join(os.tmpdir(), `bongos-core-pack-${packSrc.version}`);
+      log(`  ${tag} packing the registry-installed core this control plane runs (v${packSrc.version}) — no source rebuild (task 1002706)`);
+      exec(`mkdir -p ${packDest}`);
+      exec(`npm pack ${packSrc.dir} --pack-destination ${packDest}`);
+      tgz = path.join(packDest, packSrc.tarballName);
+    } else {
+      log(`  ${tag} building a fresh vendored tarball from source (package-core.js)`);
+      exec(`node scripts/gds/package-core.js`);                    // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
+      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    }
+  }
+  return { tgz, packDest };
+}
+
+// The onboard mode a provisioning row carries (migration provisioning_004, task 1002562).
+// 'adopt' means target_ref is a repo the owner ALREADY has, so the scaffold must LAYER
+// onto its history. Anything else — including a row written before the column existed, or
+// an unrecognized value — resolves to 'greenfield', deliberately the SAFE direction:
+// greenfield pushes a fresh tree and (carrying no --force) is REJECTED by a repo with
+// history, whereas wrongly choosing 'adopt' would start rewriting a repo nobody declared.
+function onboardMode(inst) {
+  return String((inst && inst.onboard_mode) || '') === 'adopt' ? 'adopt' : 'greenfield';
+}
+
+// Has the scaffold already completed in `root`? The marker is MODE-DEPENDENT, and reusing
+// the greenfield one for adopt is a real bug: greenfield's marker is "package.json exists"
+// (a fresh empty repo has none until we scaffold it), but an adopted repo is an existing
+// project that almost certainly HAS a package.json already — so the greenfield check would
+// report "already scaffolded" on the very first run and the instance would never become
+// bootable. For adopt the honest marker is the thing the layering itself contributes: a
+// @bongos/core dependency (both scope aliases the loader accepts, matching
+// installedCoreTarball). fs injectable for tests; read-only, so dry-run safe.
+function alreadyScaffolded(root, mode, { fsImpl = fs } = {}) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fsImpl.existsSync(pkgPath)) return false;
+  if (mode !== 'adopt') return true;
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(pkgPath, 'utf8')); }
+  catch { return false; }   // unparseable → let the adopt layer report it, don't skip
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  return !!(deps['@bongos/core'] || deps['@cloudbongos/core']);
+}
+
+// Materialize + push the instance's own repo. TWO paths, chosen by onboard_mode:
+//
+//   greenfield — the target_ref repo is EMPTY (github-repos.createUserRepo makes it with
+//                auto_init:false), so there is nothing to clone: `git init` locally,
+//                materialize, and push the first commit at main.
+//   adopt      — the target_ref repo is the owner's OWN existing project. CLONE it (so its
+//                history and files come along), LAYER the instance config additively via
+//                `bongos init --adopt --accept` (which never overwrites a pre-existing
+//                file), and push the layer commit as an ordinary fast-forward on top.
+//
+// Both end at a repo carrying config/ + .claude/ + a file:-pinned @bongos/core + lockfile,
+// which is what makes it `npm ci --omit=dev`-installable by the rest of provisioning.
+//
+// NEITHER PATH EVER USES --force. That is a safety property, not an oversight: since ADR
+// 0155 the credential here can write to every repo the owner owns, so a force-push would
+// be a route to destroying a user's work. A rejected push is the correct, recoverable
+// outcome. Asserted by tests.
+//
+// Idempotent (see alreadyScaffolded) and dry-run safe (every mutation goes through the
+// injected exec/writeFile). ADR 0108 / 0121 / 0125.
+async function scaffoldStandaloneRepo(inst, deps) {
+  // The scaffold BUILDS + pushes the instance's repo (git clone, package-core,
+  // `bongos init`, git push) — control-plane work that needs the packaging tools +
+  // the GitHub deploy key, so it runs LOCALLY even when box-mutating steps go
+  // remote (task 2065). Falls back to exec/writeFile when a caller passes no
+  // control executor (then all are the same local executor — unchanged behavior).
+  const { db, log } = deps;
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile;
+  const root = standaloneRoot(inst);
+  const repo = parseTargetRef(inst.target_ref);
+  const mode = onboardMode(inst);
+  if (!repo) {
+    throw new Error(`standalone instance ${inst.slug}: target_ref "${inst.target_ref || '(unset)'}" is not an owner/repo — set it (e.g. <owner>/${inst.slug}) so the scaffold knows which repo to clone + push.`);
+  }
+  if (alreadyScaffolded(root, mode)) {
+    log(`  [scaffold] ${root} already scaffolded (mode=${mode}) — skipping`);
+    return { already: true };
+  }
+  const coreV = coreVersionSafe();
+  if (!coreV) {
+    throw new Error('cannot resolve the core version (src/module-api CORE_VERSION) — run the scaffold from the control-plane checkout.');
+  }
+  const remote = instanceRepoRemote(repo);
+  log(mode === 'adopt'
+    ? `  [scaffold] ${repo.owner}/${repo.name} → ${root} (ADOPT: clone → layer additively → pin core ${coreV} → commit → fast-forward push)`
+    : `  [scaffold] ${repo.owner}/${repo.name} → ${root} (clone → materialize → pin core ${coreV} → commit → push)`);
+
+  // Owner login = the founding firstAdmin. Best-effort; the spec falls back to the repo owner.
+  let ownerLogin = null;
+  if (inst.owner_builder_id && db) {
+    try {
+      const r = await db.query('SELECT github_login FROM builders WHERE id = $1', [inst.owner_builder_id]);
+      ownerLogin = r && r.rows && r.rows[0] ? r.rows[0].github_login : null;
+    } catch { /* fall back to the repo owner */ }
+  }
+
+  // Resolve the instance owner's OAuth token BEFORE any git network op.
+  //
+  // Greenfield only needed it at PUSH time, so the lookup used to live down beside the
+  // push. Adopt needs it EARLIER: its first act is to clone the owner's own repo, and a
+  // PRIVATE one is unreadable by the control plane's shared deploy key (a deploy key is
+  // per-repo). Since ADR 0155 this token carries the `repo` scope, so it can both read and
+  // write the owner's private repos — which is what makes adopt possible at all.
+  //
+  // A GitHub DEPLOY KEY is per-repo, so the box's shared key also can't WRITE to a new
+  // project repo — the second empty-repo cause (task 1002317) — hence preferring this
+  // token on both paths. It rides a chmod-600 git credential-store file, never the logged
+  // command or makeExec's env (makeExec surfaces both), and is removed in a `finally` so a
+  // failed git op can't leave it on disk. No token (org-owned repo, or secret-box off) →
+  // fall back to the SSH `origin` remote.
+  const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[scaffold]' });
+  // The credential-store file + the credential-LESS URL git resolves against it. The URL
+  // carries only the `x-access-token` username (no secret), so it is safe in a logged argv.
+  const credFile = ownerToken ? path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`) : null;
+  const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+  const credOpt = credFile ? `-c credential.helper='store --file=${credFile}' ` : '';
+  if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+
+  try {
+    // 1. Materialize the working tree.
+    //
+    //    ADOPT — CLONE the owner's existing repo, so its history + files come along and the
+    //    layer commit lands as an ordinary descendant of its current tip. This is the whole
+    //    point: `git init`ing a fresh tree here produces an UNRELATED history, which the
+    //    remote rejects as a non-fast-forward (and, were it ever forced, would erase the
+    //    owner's work). Cloning over the token's HTTPS URL also covers the private case the
+    //    shared deploy key cannot read.
+    //
+    //    GREENFIELD — a freshly-created instance repo is EMPTY (github-repos.createUserRepo,
+    //    auto_init:false), so there is NOTHING to clone; and the shared PROVISION_GIT_SSH_ALIAS
+    //    deploy key can't even READ a consumer's brand-new repo under their own account
+    //    (`git clone` fails "Repository not found" — the clone-side twin of the task-1002317
+    //    push bug). So `git init` locally and set `origin` to the SSH remote for the no-token
+    //    fallback push. Unchanged behavior.
+    //
+    //    Either way a re-run after a partial attempt reuses the existing dir.
+    const hasGit = fs.existsSync(path.join(root, '.git'));
+    if (mode === 'adopt') {
+      if (!hasGit) {
+        exec(`mkdir -p ${root}`);
+        exec(`git ${credOpt}clone ${credFile ? httpsUrl : remote} ${root}`);
+        // Normalize `origin` to the SSH remote, matching what the greenfield path leaves
+        // behind. Two reasons: the clone URL would otherwise persist as origin, and the
+        // ongoing deploy (standalonePullCmd → `git pull --ff-only origin main`, and the box
+        // timer's `git reset --hard origin/main`) reads origin — it must be a form that can
+        // authenticate durably, which the one-shot token URL cannot (its credential file is
+        // deleted below). Nothing durable ever holds the token either way; the pushes here
+        // always pass an explicit URL.
+        if (credFile) exec(`git -C ${root} remote set-url origin ${remote}`);
+      } else {
+        exec(`git -C ${root} ${credOpt}fetch ${credFile ? httpsUrl : 'origin'} main`);
+      }
+      // The rest of provisioning is main-only (standalonePullCmd is `git pull --ff-only
+      // origin main`, and the box's deploy timer does `git reset --hard origin/main`), so a
+      // repo whose default branch is not `main` would be layered and pushed somewhere the
+      // deploy never reads. Fail loudly with the fix rather than silently half-working.
+      const head = exec(`git -C ${root} rev-parse --abbrev-ref HEAD`, { allowFail: true });
+      const branch = String((head && head.stdout) || '').trim();
+      if (branch && branch !== 'main' && branch !== 'HEAD') {
+        throw new Error(`standalone instance ${inst.slug}: adopting ${repo.owner}/${repo.name} but its default branch is "${branch}", not "main". The instance deploy only ever reads origin/main, so the layer would never be served. Rename the default branch to main (or point target_ref at a repo whose default is main) and re-run.`);
+      }
+      exec(`git -C ${root} checkout main`, { allowFail: true });
+    } else {
+      if (!hasGit) {
+        exec(`mkdir -p ${root}`);
+        exec(`git -C ${root} init -q`);
+        exec(`git -C ${root} remote add origin ${remote}`);
+      }
+      exec(`git -C ${root} checkout -B main`);
+    }
+
+    // Core-install path (ADR 0134, task 2090). DEFAULT = vendor a tarball built from THIS
+    // control-plane checkout (offline, proven — task 2053). OPT-IN = pull the PRIVATE
+    // @bongos/core from the npm registry (PROVISION_CORE_FROM_REGISTRY=1). The registry
+    // path needs NPM_TOKEN at `npm ci` time; if the flag is set but no token is present we
+    // FAIL SOFT to the vendored path so a tokenless standup still works (never a broken
+    // instance). The env is injectable for tests; the runner falls back to process.env.
+    const env = deps.env || process.env;
+    const wantRegistry = registryCoreRequested(env);
+    const useRegistry = wantRegistry && hasNpmToken(env);
+    if (wantRegistry && !useRegistry) {
+      log('  [scaffold] PROVISION_CORE_FROM_REGISTRY set but no NPM_TOKEN in env — falling back to the vendored-tarball core (ADR 0134 fail-soft).');
+    }
+
+    // materialize config/ + .claude/ + a pinned package.json + lockfile via `bongos init`.
+    // --no-seed: the instance's own DB is seeded by migrate, not here (and on the adopt path
+    // the REAL-state seeding + backlog import happen when the owner runs `bongos init --adopt`
+    // themselves, against the live instance — the step the wizard walks them through).
+    //
+    // MODE FLAGS. Greenfield passes --force (overwrite is safe on an empty repo). Adopt passes
+    // --adopt --accept instead and NEVER --force: --adopt takes init's layering path, which
+    // writes each config only where absent and leaves pre-existing files untouched, and
+    // --accept clears the interactive pre-flight gate for this non-interactive runner (a
+    // BLOCKING pre-flight finding still hard-stops — it cannot be waved through). init refuses
+    // --adopt together with --force, so the two flag sets are mutually exclusive by design.
+    //
+    // Two mutually exclusive core-resolution shapes, orthogonal to the mode:
+    //   registry (--registry-core): caret pin + env-fed .npmrc; `npm ci` pulls from the
+    //     registry. init generates the lockfile (NPM_TOKEN is present — we gated on it).
+    //   vendored (--vendor-core, default): a tarball built from this checkout, file:-pinned.
+    const modeFlags = mode === 'adopt' ? '--adopt --accept' : '--force';
+    const spec = instanceInitSpec(inst, { ownerLogin });
+    const specPath = path.join(os.tmpdir(), `bongos-init-${inst.slug}.json`);
+    writeFile(specPath, JSON.stringify(spec, null, 2));
+    if (useRegistry) {
+      log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
+      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --registry-core`);
+    } else {
+      // Vendored tarball — resolveVendorableCoreTarball's three-rung ladder (shared
+      // with the re-provision pin refresh, task 1003050).
+      const { tgz, packDest } = resolveVendorableCoreTarball({
+        instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[scaffold] core install:',
+      });
+      exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed ${modeFlags} --vendor-core ${tgz}`);
+      // init --vendor-core COPIED the tarball into the child's vendor/ — the temp pack dir is spent.
+      if (packDest) exec(`rm -rf ${packDest}`);
+    }
+
+    // 4. commit + push to the instance's own main (keep node_modules out).
+    //
+    // .gitignore: greenfield OWNS the file. Adopt must not clobber the owner's existing
+    // ignores, so it only writes one where none exists — and where one does, it APPENDS the
+    // entries we actually require (node_modules/, the vendored-core exceptions, the generated
+    // nav docs) if they are missing, since `npm ci` + `git reset --hard` on the box depend on
+    // them. Duplicate lines in a .gitignore are harmless, so the append is idempotent-safe.
+    const giPath = path.join(root, '.gitignore');
+    if (mode === 'adopt' && fs.existsSync(giPath)) {
+      const existing = fs.readFileSync(giPath, 'utf8');
+      const missing = INSTANCE_GITIGNORE.split('\n')
+        .filter((l) => l.trim() && !l.startsWith('#'))
+        .filter((l) => !existing.split('\n').some((e) => e.trim() === l.trim()));
+      if (missing.length) {
+        writeFile(giPath, `${existing.replace(/\n*$/, '\n')}\n# Added by Cloud Bongos (adopt) — required by the instance deploy.\n${missing.join('\n')}\n`);
+        log(`  [scaffold] appended ${missing.length} required .gitignore entr(ies) — existing rules left intact`);
+      } else {
+        log('  [scaffold] .gitignore already covers the required entries — left untouched');
+      }
+    } else {
+      writeFile(giPath, INSTANCE_GITIGNORE);
+    }
+    exec(`git -C ${root} config user.name "Cloud Bongos"`);
+    exec(`git -C ${root} config user.email "${provisionerBotEmail()}"`);
+    exec(`git -C ${root} add -A`);
+    const commitMsg = mode === 'adopt'
+      ? `chore: adopt Cloud Bongos onto ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0121)`
+      : `chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)`;
+    exec(`git -C ${root} commit -m "${commitMsg}"`, { allowFail: true });
+
+    // Push. NO --force on either path, ever (see the function header): the ADR 0155 `repo`
+    // credential can write to every repo the owner owns, so a force here would be a route to
+    // destroying their work. Adopt's commit is a descendant of the tip it cloned, so an
+    // ordinary push fast-forwards; if the remote moved underneath us the rejection is the
+    // correct outcome and a re-run picks up the new tip.
+    if (credFile) {
+      exec(`git -C ${root} ${credOpt}push ${httpsUrl} HEAD:main`);
+      log(`  [scaffold] ${mode === 'adopt' ? 'pushed the adopt layer' : 'pushed'} to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
+    } else {
+      exec(`git -C ${root} push -u origin main`);
+      log(`  [scaffold] pushed ${mode === 'adopt' ? 'the adopt layer' : 'initial scaffold'} to ${repo.owner}/${repo.name}@main (SSH origin)`);
+    }
+    return { ok: true, scaffolded: true, mode };
+  } finally {
+    // Always remove the credential file — a failed clone/push must not leave it on disk.
+    if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
+  }
+}
+
+// ── private-repo deploy key (ADR 0176, task 1002735; walk finding N4) ────────────
+
+// The instance owner's stored `repo`-scoped OAuth token (ADR 0155), or null (none
+// stored, org-owned repo, secret-box off). Shared by the scaffold push, the
+// private-repo deploy-key wiring, and the teardown revoke. `deps.getGithubToken` is
+// injectable for tests; production resolves it lazily against the core db slice
+// with the runner's pool.
+async function resolveOwnerGithubToken(inst, deps, { tag = '[repo-auth]' } = {}) {
+  if (!inst.owner_builder_id) return null;
+  try {
+    const fetchTok = deps.getGithubToken
+      || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db }));
+    const r = await fetchTok(inst.owner_builder_id);
+    return r && r.token ? r.token : null;
+  } catch (e) {
+    (deps.log || (() => {}))(`  ${tag} owner OAuth token lookup failed (${e && e.message})`);
+    return null;
+  }
+}
+
+function deployKeyTitle(inst) { return `cloudbongos-deploy-${inst.slug}`; }
+// Beside the checkout's own metadata: untracked by definition, survives the deploy's
+// `git reset --hard`, and dies with the checkout rather than accreting in ~/.ssh.
+function deployKeyPath(inst) { return path.posix.join(standaloneRoot(inst), '.git', 'cloudbongos-deploy-key'); }
+
+// Make a PRIVATE target_ref durably readable by the recurring deploy pull. The
+// owner's token covers only the ONE-SHOT clone/push (its credential file is deleted
+// after the scaffold), while `origin` rides the shared SSH alias — which GitHub
+// answers "Repository not found" for a private repo it isn't registered on. That
+// mismatch is walk finding N4: every private standup failed at `git pull --ff-only
+// origin main`, token or not (seen live: mercury, 2026-08-17).
+//
+// The fix (ADR 0176): mint the instance its OWN ed25519 deploy key, register it
+// READ-ONLY on the repo with the owner's token (idempotent by title; a stale
+// same-title key is replaced), then wire the CHECKOUT — origin re-pointed at plain
+// github.com and core.sshCommand pinned to the key with -F /dev/null so no
+// ~/.ssh/config identity can shadow it. Public repos return untouched; no token →
+// skip (the request-time refusal is task 1002909's preflight). Dry-run plans only.
+async function ensurePrivateRepoAccess(inst, deps) {
+  const { log, apply } = deps;
+  const exec = deps.controlExec || deps.exec;
+  if (inst.hosting_shape !== 'standalone') return { skipped: 'shape' };
+  const repo = parseTargetRef(inst.target_ref);
+  if (!repo) return { skipped: 'no_repo' };
+  // Dry-run stays OFFLINE like every other plan path here (the checkDnsTokenScope
+  // preflight is apply-gated for the same reason): no token read, no GitHub call —
+  // a plan run must stay a safe inspection tool for a snagged instance.
+  if (!apply) {
+    log(`  [repo-auth] would check ${repo.owner}/${repo.name} visibility with the owner's credential and, if PRIVATE, mint + register a read-only deploy key and wire origin + core.sshCommand to it (ADR 0176)`);
+    return { planned: true };
+  }
+  const ownerToken = await resolveOwnerGithubToken(inst, deps);
+  if (!ownerToken) {
+    log('  [repo-auth] no usable owner GitHub credential (none stored, or it could not be read) — a PRIVATE repo would fail at the deploy pull (public repos are unaffected)');
+    return { skipped: 'no_token' };
+  }
+  const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
+  let info;
+  try {
+    info = await ghRepos.getUserRepo(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+  } catch (e) {
+    if (e && e.code === 'repo_not_found') {
+      // Plain sentence: this rides error_note onto the owner's project card.
+      throw new Error(`repository not found: GitHub answered 404 for ${repo.owner}/${repo.name} even with your granted credential — the repository may have been renamed or deleted, or the credential lost access. Check it on GitHub, then try again.`);
+    }
+    log(`  [repo-auth] could not read ${repo.owner}/${repo.name} (${e && e.message}) — continuing; a PRIVATE repo would fail at the deploy pull`);
+    return { skipped: 'github_unreachable' };
+  }
+
+  const root = standaloneRoot(inst);
+  const keyPath = deployKeyPath(inst);
+  const title = deployKeyTitle(inst);
+  const fsImpl = deps.fsImpl || fs;
+
+  if (!info.private) {
+    // Flipped private → public since we wired it: un-wire, or the checkout stays
+    // pinned (IdentitiesOnly + -F /dev/null admit no other identity) to a key the
+    // owner is now free to delete from their repo settings. Keyed on our key file
+    // so the common public path stays zero-mutation.
+    if (fsImpl.existsSync(keyPath)) {
+      log(`  [repo-auth] ${repo.owner}/${repo.name} is public again — un-wiring its deploy key`);
+      try {
+        const keys = await ghRepos.listDeployKeys(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+        const ours = keys.find((k) => k.title === title);
+        if (ours) await ghRepos.deleteDeployKey(ownerToken, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
+      } catch (e) { log(`  [repo-auth] (remote key revoke skipped: ${e && e.message})`); }
+      exec(`git -C ${root} remote set-url origin ${instanceRepoRemote(repo)}`);
+      exec(`git -C ${root} config --unset core.sshCommand`, { allowFail: true });
+      exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
+      return { private: false, unwired: true };
+    }
+    return { private: false };   // the shared-alias path reads public repos as-is
+  }
+
+  // Registering a deploy key needs repository ADMIN; getUserRepo already told us.
+  // Refuse up front with the fix, instead of a raw 403 mid-standup.
+  if (info.admin === false) {
+    throw new Error(`repository access is not admin: your granted credential can read ${repo.owner}/${repo.name}, but registering its deploy key needs repository ADMIN. Ask a repository admin to raise your access (or make the repository public), then try again.`);
+  }
+
+  log(`  [repo-auth] ${repo.owner}/${repo.name} is PRIVATE — wiring its own read-only deploy key (ADR 0176)`);
+  if (!fsImpl.existsSync(keyPath) || !fsImpl.existsSync(`${keyPath}.pub`)) {
+    exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
+    exec(`ssh-keygen -q -t ed25519 -N '' -C ${title} -f ${keyPath}`);
+    exec(`chmod 600 ${keyPath}`);   // ssh-keygen's 0600 default, made an explicit invariant
+  }
+  const pubKey = String(fsImpl.readFileSync(`${keyPath}.pub`, 'utf8')).trim();
+  // Compare algorithm+key only — GitHub stores the key without the local comment.
+  const keyBody = (k) => String(k || '').trim().split(/\s+/).slice(0, 2).join(' ');
+  let minted = false;
+  try {
+    const keys = await ghRepos.listDeployKeys(ownerToken, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+    const ours = keys.find((k) => k.title === title);
+    const current = !!(ours && keyBody(ours.key) === keyBody(pubKey));
+    if (ours && !current) {
+      // GitHub 422s a duplicate title/key, and a stale registration is a dead credential —
+      // replace, never accumulate.
+      await ghRepos.deleteDeployKey(ownerToken, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
+      log(`  [repo-auth] removed the stale "${title}" key on ${repo.owner}/${repo.name} (local key changed)`);
+    }
+    if (!current) {
+      try {
+        await ghRepos.addDeployKey(ownerToken, { owner: repo.owner, name: repo.name, title, key: pubKey, readOnly: true, fetchImpl: deps.fetchImpl });
+      } catch (e) {
+        if (!e || e.code !== 'key_in_use') throw e;
+        // The keypair is slug-keyed but the repo can change underneath it (renamed
+        // then recreated, target_ref re-pointed): the key is registered SOMEWHERE
+        // else, so retrying with this pair can never succeed. Mint fresh, try once.
+        log('  [repo-auth] GitHub holds this key elsewhere (422) — minting a fresh keypair and retrying once');
+        exec(`rm -f ${keyPath} ${keyPath}.pub`, { allowFail: true });
+        exec(`ssh-keygen -q -t ed25519 -N '' -C ${title} -f ${keyPath}`);
+        exec(`chmod 600 ${keyPath}`);
+        const freshPub = String(fsImpl.readFileSync(`${keyPath}.pub`, 'utf8')).trim();
+        await ghRepos.addDeployKey(ownerToken, { owner: repo.owner, name: repo.name, title, key: freshPub, readOnly: true, fetchImpl: deps.fetchImpl });
+      }
+      minted = true;
+      log(`  [repo-auth] registered read-only deploy key "${title}" on ${repo.owner}/${repo.name}`);
+    } else {
+      log(`  [repo-auth] deploy key "${title}" already registered — nothing to mint`);
+    }
+  } catch (e) {
+    if (e && e.code === 'not_repo_admin') {
+      throw new Error(`repository access is not admin: your granted credential can read ${repo.owner}/${repo.name}, but registering its deploy key needs repository ADMIN. Ask a repository admin to raise your access (or make the repository public), then try again.`);
+    }
+    // Plain sentence for the owner card — a transient GitHub hiccup must not read as jargon.
+    throw new Error(`deploy-key setup failed for ${repo.owner}/${repo.name}: ${e && e.message}. Nothing is wrong on your side — try again, and if it keeps failing make the repository public and retry.`);
+  }
+  exec(`git -C ${root} remote set-url origin git@github.com:${repo.owner}/${repo.name}.git`);
+  exec(`git -C ${root} config core.sshCommand "ssh -F /dev/null -i ${keyPath} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`);
+  return { private: true, minted };
+}
+
+// ── re-provision core-pin refresh (gap-list W3, task 1003050) ────────────────────
+//
+// The hazard: a standalone instance's RUNNING core can move ahead of its repo's
+// committed `file:` pin (an out-of-band `bongos upgrade`, a pre-fix re-provision that
+// refreshed the box without committing) — seen live on Spike Harbor, running a modern
+// core while the repo still pinned 1.19.2. The deploy path is repo-driven
+// (`git reset --hard origin/main` + `npm ci`), so the NEXT deploy silently rolls the
+// instance back against a DB the newer core has already migrated. ADR 0168 fixed
+// fresh scaffolds only; this closes the re-provision leg: every provision of an
+// already-scaffolded instance heals the committed pin to the core this control plane
+// runs, as a commit pushed to the instance repo.
+
+// The PURE decision half (tested in tests/provision.mjs). Registry pins are npm's to
+// resolve; an absent dep is not ours to invent; only `file:` pins are healed.
+function planCorePinRefresh({ pinnedDep, coreVersion }) {
+  const dep = String(pinnedDep || '').trim();
+  if (!dep) return { action: 'skip', reason: 'no @bongos/core dependency in the instance package.json' };
+  if (!/^file:/.test(dep)) return { action: 'skip', reason: `registry pin (${dep}) — npm ci resolves it; nothing to vendor` };
+  const upgrade = require('./upgrade');
+  const pinned = upgrade.versionFromTgzPath(dep);
+  if (pinned && pinned === coreVersion) return { action: 'current', pinned };
+  return { action: 'refresh', pinned: pinned || null };
+}
+
+// Coerce a version label to a semver-safe charset BEFORE it is interpolated into any
+// shell string. The "from" label ultimately derives from the INSTANCE's own repo
+// package.json `file:` pin (lower trust than the shared control plane) via
+// versionFromTgzPath, whose regex admits any char but `/` — including `"`, backtick,
+// `$()`, `;`. A crafted pin (e.g. `file:vendor/bongos-core-1.0.0";touch x;echo".tgz`)
+// would otherwise break out of a `git commit -m "…"` argument and run as the
+// control-plane user. This chokepoint rejects anything outside semver's own alphabet
+// (task 1003050 grade — command-injection block). PURE.
+function safeVersionLabel(v) {
+  const s = String(v == null ? '' : v).trim();
+  return /^[0-9A-Za-z.+-]{1,64}$/.test(s) ? s : '(unversioned)';
+}
+
+// The commit + push command sequence for a pin refresh — PURE, so tests/provision.mjs
+// covers "the runner's commit step" (task 1003050 AC) deterministically. Version
+// labels pass through safeVersionLabel (the one interpolation-safety chokepoint); the
+// push prefers the owner's OAuth token URL (the shared deploy key can't write a
+// consumer repo — task 1002317) and falls back to the SSH origin.
+function buildCorePinRefreshCommit({ root, fromVersion, toVersion, repo, ownerToken, credFile }) {
+  const from = safeVersionLabel(fromVersion);
+  const to = safeVersionLabel(toVersion);
+  const msg = `chore: re-provision refreshes the pinned @bongos/core ${from} -> ${to} (task 1003050)`;
+  const push = (ownerToken && repo && credFile)
+    ? `git -C ${root} -c credential.helper='store --file=${credFile}' push https://x-access-token@github.com/${repo.owner}/${repo.name}.git HEAD:main`
+    : `git -C ${root} push origin main`;
+  return {
+    config: [
+      `git -C ${root} config user.name "Cloud Bongos"`,
+      `git -C ${root} config user.email "${provisionerBotEmail()}"`,
+    ],
+    add: `git -C ${root} add -A`,
+    commit: `git -C ${root} commit -m "${msg}"`,
+    push,
+  };
+}
+
+async function refreshStandaloneCorePin(inst, deps) {
+  const { log } = deps;
+  const exec = deps.controlExec || deps.exec;
+  const writeFile = deps.controlWriteFile || deps.writeFile;
+  const upgrade = require('./upgrade');
+  const root = standaloneRoot(inst);
+  const coreV = coreVersionSafe();
+  if (!coreV) { log('  [core-pin] cannot resolve the running core version — leaving the committed pin alone'); return { action: 'skip', reason: 'no core version' }; }
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* unreadable → skip below */ }
+  const pinnedDep = pkg && ((pkg.dependencies || {})['@bongos/core'] || (pkg.devDependencies || {})['@bongos/core']);
+  const plan = planCorePinRefresh({ pinnedDep, coreVersion: coreV });
+  if (plan.action === 'skip') { log(`  [core-pin] ${plan.reason}`); return plan; }
+  if (plan.action === 'current') { log(`  [core-pin] committed pin already matches the running core (${coreV})`); return plan; }
+  log(`  [core-pin] committed pin ${safeVersionLabel(plan.pinned)} trails this control plane's core ${coreV} — refreshing so the next repo-driven deploy cannot roll the instance back (task 1003050)`);
+
+  const { tgz, packDest } = resolveVendorableCoreTarball({
+    instanceRoot: deps.instanceRoot, exec, log, coreV, tag: '[core-pin]',
+  });
+  try {
+    const targetVersion = upgrade.versionFromTgzPath(path.basename(tgz)) || coreV;
+    const vendorRel = upgrade.vendorTarball({ instanceDir: root, fromTgz: tgz, targetVersion });
+    // Prune superseded vendored tarballs (+ manifests) so the repo carries exactly ONE
+    // core. fs.rmSync, NOT exec — a filename comes off the instance's own (lower-trust)
+    // vendor/ dir, so shelling `rm -f ${f}` would be the same injection vector as the
+    // commit label (a committed file named `bongos-core-x";touch pwn;".tgz`). A direct
+    // fs call takes the name as data, never as shell (task 1003050 grade).
+    const vendorDir = path.join(root, 'vendor');
+    const keep = new Set([`${upgrade.ARTIFACT}-${targetVersion}.tgz`, `${upgrade.ARTIFACT}-${targetVersion}.manifest.json`]);
+    // vendorTarball just mkdirSync'd this, so it exists on the happy path; guard anyway
+    // so an unexpectedly-absent dir prunes nothing instead of crashing the whole provision.
+    if (fs.existsSync(vendorDir)) {
+      for (const f of fs.readdirSync(vendorDir)) {
+        if (f.startsWith(`${upgrade.ARTIFACT}-`) && !keep.has(f)) fs.rmSync(path.join(vendorDir, f), { force: true });
+      }
+    }
+    upgrade.writePin(root, vendorRel);
+    // `npm install` (NOT ci): the pin just changed, the lockfile must be regenerated.
+    const instRes = upgrade.npmInstall(root);
+    if (!instRes.ok) {
+      throw new Error(`npm install after the core-pin refresh failed (${instRes.reason || `exit ${instRes.code}`}) — lockfile not regenerated; the pin refresh cannot be committed half-done.`);
+    }
+
+    // Commit + push the refresh to the instance repo — the shared deploy key cannot
+    // write a consumer's repo (task 1002317), so prefer the owner's OAuth token,
+    // exactly like the scaffold's push.
+    const ownerToken = await resolveOwnerGithubToken(inst, deps, { tag: '[core-pin]' });
+    const repo = parseTargetRef(inst.target_ref);
+    const credFile = ownerToken && repo ? path.join(os.tmpdir(), `bongos-gitcred-pin-${inst.slug}-${process.pid}`) : null;
+    const cmd = buildCorePinRefreshCommit({ root, fromVersion: plan.pinned, toVersion: targetVersion, repo, ownerToken, credFile });
+    try {
+      cmd.config.forEach((c) => exec(c));
+      exec(cmd.add);
+      exec(cmd.commit, { allowFail: true });
+      if (credFile) writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+      exec(cmd.push);
+    } finally {
+      if (credFile) exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+    log(`  [core-pin] refreshed + pushed: @bongos/core ${safeVersionLabel(plan.pinned)} → ${targetVersion}`);
+    return { ...plan, refreshed: true, toVersion: targetVersion };
+  } finally {
+    if (packDest) exec(`rm -rf ${packDest}`);
+  }
+}
+
+// The per-instance systemd unit (the infra/cloudbongos.service shape): one Node process
+// bound to the instance's port + DB + brand, secrets from its own env file. SHAPE-AWARE:
+// a STANDALONE instance runs the CORE PACKAGE's platform-server from its OWN repo dir
+// (WorkingDirectory=standaloneRoot → resolveInstanceRoot() resolves to the instance via
+// cwd, deploy-instance.sh §4); co-tenant/dedicated run this control-plane checkout's src/.
+
+module.exports = {
+  APP_USER,
+  CORE_PKG_DIR,
+  INSTANCE_GITIGNORE,
+  alreadyScaffolded,
+  asPostgres,
+  buildCorePinRefreshCommit,
+  dbCreateCmd,
+  dbName,
+  deployKeyPath,
+  deployKeyTitle,
+  ensurePrivateRepoAccess,
+  installedCorePackDir,
+  installedCoreTarball,
+  instanceInitSpec,
+  instanceRepoRemote,
+  migrateCmd,
+  onboardMode,
+  parseTargetRef,
+  planCorePinRefresh,
+  refreshStandaloneCorePin,
+  resolveOwnerGithubToken,
+  resolveVendorableCoreTarball,
+  safeVersionLabel,
+  scaffoldStandaloneRepo,
+  seedFirstVersionCmd,
+  standaloneInstallCmd,
+  standaloneMigrateCmd,
+  standalonePullCmd,
+  standaloneRegenDocsCmd,
+  standaloneRoot,
+};