@bongos/core 1.17.0

package/scripts/gds/provision.js

@@ -0,0 +1,1324 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/provision.js — the INSTANCE-provisioning control-plane runner
+// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944). A sibling of box.js.
+//
+// WHAT IT IS. The trust-boundary-safe executor for the `provisioning` module.
+// The internet-facing web tier can only ENQUEUE a provision/teardown intent into
+// provisioning_intents (modules/provisioning/routes/provisioning.js) — it holds
+// NO cloud tokens. THIS runner, driven by a systemd timer
+// (provision-intent-runner.timer → `provision.js run-intents --apply`), is the
+// SOLE holder of the DigitalOcean / Cloudflare tokens (from a chmod-600
+// /etc/<inst>/box.env via systemd EnvironmentFile=). It drains the queue and
+// composes the docs/recipes/cloudbongos-standup.md runbook into ONE idempotent,
+// dry-run-default, drift-reconciling flow (ADR 0016 / ADR 0031 §9.4 trust boundary):
+//
+//   server (co-tenant process OR dedicated droplet)
+//     → createdb + GDS-only migrate (MEDUSA_GDS_ONLY=1)
+//     → write config + per-instance /etc/<inst>/web.env
+//     → install + enable a per-instance systemd unit (+ allocate a port)
+//     → Caddy site block + reload
+//     → /healthz
+//
+// DESIGN — inherited from box.js / do-api.js:
+//   • DRY-RUN by DEFAULT. Without --apply, every step only PRINTS the command it
+//     WOULD run and mutates nothing (no DB writes, no shell, no cloud call). The
+//     LIVE leg is an explicit operator/timer `--apply`.
+//   • PRIVILEGE model (task 2066, ADR 0128). The intent runner runs as a NON-root
+//     user (User=lars) with passwordless sudo, which cannot itself write under /etc,
+//     reload systemd/Caddy, or peer-auth to Postgres as a superuser. PROVISION_SUDO=1
+//     escalates exactly those steps (sudo install / sudo systemctl / sudo -u postgres);
+//     default OFF = bare commands (root / test / co-tenant-legacy contexts unchanged).
+//   • Injectable executor. `makeExec` returns a `run(cmd)` that is a pure logger
+//     in dry-run and child_process in --apply; tests pass a recording fake, so the
+//     whole runbook composition is unit-tested with no droplet / DB / network.
+//   • Idempotent. Re-running a half-done provision is safe (createdb tolerates
+//     "already exists"; unit/Caddy writes are overwrites; healthz is a poll).
+//   • The step-command generators are PURE functions (exported) → the SAME command
+//     strings drive local exec (co-tenant) AND the dedicated droplet's cloud-init.
+//
+// This is control-plane ops tooling (scripts/), so — like box.js — it may require
+// the core + a module's data slice directly (a module may not, but a CLI may). It
+// reuses modules/provisioning/provisioning.js (the intent queue + state) and
+// scripts/gds/do-api.js (the shared DO client extracted in task #1943).
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const cp = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// The verified OAuth-cred placement helpers (task 1979) — reused by the GitHub App
+// Manifest flow (task 2080) to VALIDATE the creds GitHub returns before writing them
+// and to PARSE the post-restart /healthz auth_configured probe. A sibling script; a
+// plain require (its require.main guard means importing it runs no CLI).
+const oauthSecret = require('./oauth-secret');
+
+// The HTTP User-Agent the manifest conversion stamps its GitHub call with (GitHub
+// requires a UA). Overridable so a fork can identify itself; not secret.
+const MANIFEST_UA = process.env.PROVISION_GITHUB_UA || 'cloudbongos-provisioner';
+
+// The running core version (no caret) — for naming the vendored tarball the standalone
+// scaffold pins. Fail-soft (a partial checkout returns null; the scaffold then errors
+// with guidance rather than pinning a `…-null.tgz`). Mirrors init.js coreVersionSafe().
+function coreVersionSafe() {
+  try { return require(path.join(REPO_ROOT, 'src/module-api')).CORE_VERSION; } catch { return null; }
+}
+
+function numEnv(name, dflt) {
+  const v = process.env[name];
+  if (v == null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+// A boolean env flag: '1'/'true'/'yes'/'on' (case-insensitive) → true, else false.
+function boolEnv(name) {
+  return /^(1|true|yes|on)$/i.test(String(process.env[name] || '').trim());
+}
+function hasFlag(args, name) { return args.includes(name); }
+
+const CONFIG = {
+  // The port range a CO-TENANT instance process binds on the shared box. 3000 (OTB)
+  // and 3002 (cloudbongos.com) are taken; new co-tenant instances start at 3003.
+  portBase: numEnv('PROVISION_PORT_BASE', 3003),
+  reservedPorts: (process.env.PROVISION_RESERVED_PORTS || '3000,3001,3002')
+    .split(',').map((s) => Number(s.trim())).filter(Number.isFinite),
+  // Where a per-instance secrets file lives: /etc/<slug>/web.env (the standup
+  // runbook's /etc/cloudbongos/web.env shape). chmod 600, OUTSIDE the repo.
+  etcBase: process.env.PROVISION_ETC_BASE || '/etc',
+  // The dir holding per-instance Caddy site snippets. Each instance gets its OWN
+  // <slug>.caddy file (idempotent overwrite, no fragile append to a shared file);
+  // the main Caddyfile carries a one-time `import <dir>/*.caddy` (operator setup).
+  caddySnippetDir: process.env.PROVISION_CADDY_SNIPPET_DIR || '/etc/caddy/sites',
+  // Dedicated-droplet defaults (only used for hosting_shape='dedicated').
+  region: process.env.PROVISION_REGION || 'nyc3',
+  baseImage: process.env.PROVISION_BASE_IMAGE || 'ubuntu-24-04-x64',
+  tag: process.env.PROVISION_TAG || 'cloudbongos-instance',
+  doToken: process.env.DO_API_TOKEN || null,
+  sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
+  // The Cloudflare DNS hook (the SAME infra/box-dns-cloudflare.sh box.js uses).
+  // P4 (#1945) formalizes the UPSERT: point the instance's domain at the target
+  // public IP (below), in the domain's OWN Cloudflare zone, proxied=false (see
+  // dnsUpsertEnv). No hook configured → DNS is skipped (a co-tenant instance is
+  // still reachable by IP; TLS then can't be issued until DNS lands).
+  dnsHook: process.env.BOX_DNS_HOOK || null,
+  // This box's PUBLIC IP — the A-record target for a CO-TENANT instance's domain.
+  // Set in the control-plane /etc/<inst>/box.env (never the web tier). A dedicated
+  // instance instead points its A record at the freshly-created droplet's IP. Under
+  // remote-exec (PROVISION_REMOTE_HOST) this is the CO-HOSTING box's IP — where the
+  // co-tenant actually runs (ADR 0130).
+  publicIp: process.env.PROVISION_PUBLIC_IP || process.env.BOX_PUBLIC_IP || null,
+  // The CONTROL PLANE's OWN public IP — the A-record target for a STANDALONE instance
+  // (task 2074). A standalone runs control-plane-LOCAL (its scaffolded repo dir lives
+  // here, not on the remote co-hosting box), so its domain must point at THIS box, not
+  // at publicIp (which, under remote-exec, is the co-hosting box). Only needed when
+  // remote-exec splits the two boxes; all-local (no remoteHost) falls back to publicIp
+  // since the control plane and the run box are then the same machine.
+  controlPlaneIp: process.env.PROVISION_CONTROL_PLANE_IP || null,
+  // Parent dir for a STANDALONE instance's OWN repo checkout (hosting_shape='standalone',
+  // ADR 0108): each lives at <standaloneBase>/<slug> with @cloudbongos/core installed as
+  // an npm dep. Distinct from co-tenant (which shares THIS control-plane checkout).
+  standaloneBase: process.env.PROVISION_STANDALONE_BASE || '/srv/cloudbongos',
+  // ── Privilege escalation (task 2066, ADR 0128) ───────────────────────────
+  // The intent runner runs as a NON-root user (provision-intent-runner.service:
+  // User=lars) that holds passwordless sudo. That user cannot itself write under
+  // /etc, reload systemd/Caddy, or peer-auth to Postgres as a superuser — so the
+  // runbook steps below FAIL as bare commands (the goal-35 blocker). With
+  // PROVISION_SUDO=1 (alias PROVISION_PRIVILEGED=1) the privileged steps escalate:
+  //   • /etc writes         → temp file (lars-writable) + `sudo install -D -m <mode>`
+  //   • systemctl / rm /etc  → `sudo …`
+  //   • createdb / migrate   → `sudo -u postgres …` (postgres peer-auths as the PG
+  //     superuser — the Ubuntu default — so it never needs `lars` to be a PG role)
+  // OFF (default) preserves the run-as-root / test / co-tenant-legacy behavior
+  // (bare commands, direct fs writes), so nothing outside a sudo context changes.
+  // Dry-run ALWAYS logs the exact command either way. NB: the runner unit must NOT
+  // set NoNewPrivileges=true — it blocks sudo (see infra/provision-intent-runner.service).
+  privileged: boolEnv('PROVISION_SUDO') || boolEnv('PROVISION_PRIVILEGED'),
+  // ── Remote orchestration over SSH (task 2065, ADR 0130) ──────────────────
+  // The token-separation endgame (ADR 0126): run this runner ON the token-holding
+  // control-plane box, and have it drive co-tenant workloads that still LIVE on the
+  // co-hosting box over SSH — so the co-hosting box can hold ZERO cloud tokens.
+  // When PROVISION_REMOTE_HOST is set, the BOX-MUTATING steps (createdb, migrate,
+  // /etc writes, systemctl, Caddy, healthz) run on that host over `ssh`; the
+  // TOKEN step (the Cloudflare DNS hook) + the standalone repo scaffold STAY local
+  // on the control plane, where the token + the packaging tools live. UNSET
+  // (default) = every step runs locally, byte-identical to today.
+  remoteHost: process.env.PROVISION_REMOTE_HOST || null,
+  // The co-hosting box's checkout dir — the cwd for the remote migrate (its relative
+  // ./scripts/migrate.sh). Defaults to that box's shared checkout.
+  remoteCwd: process.env.PROVISION_REMOTE_CHECKOUT || '/home/lars/amazonprimea',
+  // ssh options for the control-plane → co-hosting hop. BatchMode so a missing key
+  // fails fast (never hangs on a prompt); accept-new pins the host key on first
+  // connect (the operator can pre-seed known_hosts for strict pinning).
+  sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
+};
+
+const MAX_INTENT_ATTEMPTS = numEnv('PROVISION_INTENT_MAX_ATTEMPTS', 3);
+
+// ---------------------------------------------------------------------------
+// Lazy dep load (so --help / arg errors need no Postgres) — the box.js pattern.
+// ---------------------------------------------------------------------------
+let _deps;
+function loadDeps() {
+  if (_deps) return _deps;
+  // eslint-disable-next-line global-require
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  // eslint-disable-next-line global-require
+  const provisioning = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning'));
+  // eslint-disable-next-line global-require
+  const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
+  _deps = { pool, provisioning, DoApi };
+  return _deps;
+}
+
+// ---------------------------------------------------------------------------
+// PURE step-command generators (exported for tests). Each returns the exact shell
+// command a runbook step runs. Kept pure so local exec (co-tenant) and the
+// dedicated droplet's cloud-init both build from ONE source of truth.
+// ---------------------------------------------------------------------------
+
+// A slug is validated DNS/db-safe upstream (provisioning.isValidSlug), so it is
+// already shell-safe (only [a-z0-9-]). We still never interpolate untrusted text.
+function dbName(inst) { return inst.db_name || inst.slug; }
+
+// Escalate a DB command to run as the postgres OS user (→ PG superuser via peer auth,
+// the Ubuntu default) when privileged — the DB-auth fix (task 2066). The runner's
+// `lars` is not a usable PG role, so bare peer-auth-as-lars fails; `sudo -u postgres`
+// sidesteps it without granting lars a role. PURE given the flag.
+function asPostgres(cmd, privileged) { return privileged ? `sudo -u postgres ${cmd}` : cmd; }
+
+function dbCreateCmd(inst, { privileged = false } = {}) {
+  // Idempotent: the caller runs it allowFail — "database already exists" is success.
+  // Non-privileged = bare `createdb` (peer auth as the running user, same as the
+  // standup runbook / OTB); privileged = `sudo -u postgres createdb` (task 2066).
+  return asPostgres(`createdb ${dbName(inst)}`, privileged);
+}
+function migrateCmd(inst, { privileged = false } = {}) {
+  // GDS-only schema — skips migrations/game/*.sql (no game tables on a vanilla
+  // instance), per the standup runbook (ADR 0105 instance seeds off). Privileged
+  // runs migrate as postgres (task 2066): `sudo` resets env, so the PGDATABASE/
+  // MEDUSA_GDS_ONLY vars ride `env …` and the script runs via `bash …` (a bare
+  // `VAR=val ./script` would be parsed BY sudo as a command). Precondition: the
+  // control-plane checkout must be readable by the postgres user (ADR 0128).
+  return privileged
+    ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ./scripts/migrate.sh`
+    : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh`;
+}
+
+// ── 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 @cloudbongos/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/@cloudbongos/core';
+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`;
+}
+
+// ── 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.
+const INSTANCE_GITIGNORE = ['node_modules/', 'dist/', '.env', '.env.local', '*.log', ''].join('\n');
+
+// Clone the (empty) target_ref → standaloneRoot → materialize config/ + .claude/ + a
+// file:-pinned @cloudbongos/core + lockfile (via `bongos init --vendor-core`, task 2053)
+// → commit + push. Idempotent (skips once the repo carries a package.json) and dry-run
+// safe (every mutation goes through the injected exec/writeFile). ADR 0108 / 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);
+  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.`);
+  }
+  // Idempotent: a completed scaffold leaves package.json (the file:-pinned core). Skip.
+  if (fs.existsSync(path.join(root, 'package.json'))) {
+    log(`  [scaffold] ${root} already scaffolded (package.json present) — 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(`  [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 */ }
+  }
+
+  // 1. clone the (possibly empty) repo, then force the initial branch to `main` (an empty
+  //    clone leaves an unborn HEAD). A re-run after a partial clone reuses the existing dir.
+  if (!fs.existsSync(path.join(root, '.git'))) {
+    exec(`mkdir -p ${path.posix.dirname(root)}`);
+    exec(`git clone ${remote} ${root}`);
+  }
+  exec(`git -C ${root} checkout -B main`);
+
+  // 2. build the installable core tarball from THIS control-plane checkout (the core source).
+  exec(`node scripts/gds/package-core.js`);                       // cwd = REPO_ROOT → dist/cloudbongos-core-<v>.tgz
+  const tgz = path.join(REPO_ROOT, 'dist', `cloudbongos-core-${coreV}.tgz`);
+
+  // 3. materialize config/ + .claude/ + a file:-pinned package.json + lockfile via `bongos init`
+  //    (--vendor-core, task 2053). --no-seed: the instance's own DB is seeded by migrate, not here.
+  const spec = instanceInitSpec(inst, { ownerLogin });
+  const specPath = path.join(os.tmpdir(), `bongos-init-${inst.slug}.json`);
+  writeFile(specPath, JSON.stringify(spec, null, 2));
+  exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --vendor-core ${tgz}`);
+
+  // 4. commit + push the scaffold to the instance's own main (keep node_modules out).
+  writeFile(path.join(root, '.gitignore'), INSTANCE_GITIGNORE);
+  exec(`git -C ${root} config user.name "Cloud Bongos"`);
+  exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
+  exec(`git -C ${root} add -A`);
+  exec(`git -C ${root} commit -m "chore: scaffold ${inst.slug} on a pinned @cloudbongos/core ${coreV} (provision.js, ADR 0108)"`, { allowFail: true });
+  exec(`git -C ${root} push -u origin main`);
+  log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main`);
+  return { ok: true, scaffolded: true };
+}
+
+// The per-instance systemd unit (the infra/cloudbongos.service shape): one Node process
+// bound to the instance's port + DB + brand, secrets from its own env file. SHAPE-AWARE:
+// a STANDALONE instance runs the CORE PACKAGE's platform-server from its OWN repo dir
+// (WorkingDirectory=standaloneRoot → resolveInstanceRoot() resolves to the instance via
+// cwd, deploy-instance.sh §4); co-tenant/dedicated run this control-plane checkout's src/.
+function serviceUnit(inst, { etcBase = CONFIG.etcBase } = {}) {
+  const envFile = path.posix.join(etcBase, inst.slug, 'web.env');
+  const standalone = inst.hosting_shape === 'standalone';
+  const workDir = standalone ? standaloneRoot(inst) : REPO_ROOT;
+  const execStart = standalone
+    ? `/usr/bin/node ${CORE_PKG_DIR}/src/platform-server.js`
+    : `/usr/bin/node src/platform-server.js`;
+  return `[Unit]
+Description=Cloud Bongos instance — ${inst.slug} (provisioned by provision.js, ADR 0111)
+After=network-online.target postgresql.service
+Wants=network-online.target
+Requires=postgresql.service
+
+[Service]
+Type=simple
+User=lars
+Group=lars
+WorkingDirectory=${workDir}
+EnvironmentFile=${envFile}
+Environment=PGDATABASE=${dbName(inst)}
+Environment=PORT=${inst.port}
+ExecStart=${execStart}
+Restart=always
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+function serviceUnitPath(inst) { return `/etc/systemd/system/${inst.slug}.service`; }
+
+// The branding pack a provisioned CO-TENANT instance loads: the shared, committed
+// neutral starter (the co-tenant model shares ONE checkout, differentiated only by
+// env — src/branding.js's GDS_BRANDING_FILE knob). Per-instance identity/domains
+// therefore ride ENV OVERRIDES, not a divergent pack. Kept as a constant so the
+// GDS_BRANDING_FILE line below and the env-var PREFIX (which must equal this pack's
+// envPrefix, or src/branding.js's ENV_OVERRIDES never fire) can't drift apart.
+const PROVISIONED_BRANDING_FILE = 'config/branding.neutral.json';
+
+// The env-var prefix a provisioned instance actually RESOLVES — i.e. the envPrefix
+// of the pack it loads (PROVISIONED_BRANDING_FILE). src/instance-config.resolveEnv
+// reads <envPrefix>_<SUFFIX>, and src/branding.resolveBranding applies
+// <envPrefix>_{PUBLIC,BUILDERS,…}_ORIGIN overrides — so a web.env var only takes
+// effect under THIS prefix. Read from the pack (fail-soft to the vanilla default)
+// so it stays in lockstep instead of a magic string. (The prior slug-based prefix
+// was a latent bug: it never matched the neutral pack's CLOUDBONGOS envPrefix, so
+// the OAuth creds were silently unreadable — task 1972.)
+function provisionedEnvPrefix() {
+  try {
+    const pack = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, PROVISIONED_BRANDING_FILE), 'utf8'));
+    return pack.envPrefix || 'CLOUDBONGOS';
+  } catch { return 'CLOUDBONGOS'; }
+}
+
+// The per-instance secrets file body (the standup runbook's /etc/<inst>/web.env).
+// The OAuth client id/secret are GUIDED/manual inputs (no GitHub create-API) — the
+// runner writes placeholders the owner fills, unless provided via the intent later.
+// A domain (bring-your-own or provisioned) drives the single-host origin overrides:
+// with them set, src/branding.js resolves the instance's REAL buildersOrigin, so the
+// core's single-host router (isBuildersHost === buildersOrigin host, task 1971) serves
+// the hall on this host + OAuth uses the real callback origin — without them the pack
+// stays at neutral localhost and the hall never loads (task 1972). No domain yet
+// (bring-your-own deferred, ADR 0111 §4) ⇒ origins stay neutral until one is set.
+function webEnvBody(inst, { clientId = '', clientSecret = '' } = {}) {
+  const prefix = provisionedEnvPrefix();
+  const origin = inst.domain ? `https://${inst.domain}` : '';
+  const originLines = origin
+    ? `# Single-host origins (task 1972): the hall serves on THIS host + OAuth/redirects
+# use the real address. Resolved by src/branding.js ENV_OVERRIDES under the pack's
+# ${prefix} envPrefix. A single-host instance has no dedicated builders./status.
+# subdomain, so all four point at the one host.
+${prefix}_PUBLIC_ORIGIN=${origin}
+${prefix}_BUILDERS_ORIGIN=${origin}
+${prefix}_STATUS_ORIGIN=${origin}
+${prefix}_OAUTH_ORIGIN=${origin}
+`
+    : `# No domain yet (bring-your-own-domain pending, ADR 0111 §4) — origins stay
+# neutral (localhost); add ${prefix}_{PUBLIC,BUILDERS,OAUTH}_ORIGIN once a domain
+# is set, or the hall won't load on the instance's host.
+`;
+  // The OAuth app creds are filled by ONE of two paths (task 2080): the GitHub App
+  // Manifest flow (placeManifestCreds fetches them control-plane-side + re-writes this
+  // file with clientId/clientSecret set), or the manual oauth-secret.js placement. On
+  // the first provision write they are blank placeholders the flow fills later.
+  const credComment = clientId || clientSecret
+    ? `# Provisioned by scripts/gds/provision.js (ADR 0111). OAuth app creds placed via the
+# GitHub App Manifest flow (ADR 0133) — the owner clicked one link; no secret was pasted.`
+    : `# Provisioned by scripts/gds/provision.js (ADR 0111). Fill the OAuth app creds via the
+# one-click GitHub App Manifest flow (ADR 0133), or manually (oauth-secret.js place):`;
+  return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
+${credComment}
+${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
+${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
+GDS_BRANDING_FILE=${PROVISIONED_BRANDING_FILE}
+${originLines}PORT=${inst.port}
+PGDATABASE=${dbName(inst)}
+`;
+}
+function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
+  return path.posix.join(etcBase, inst.slug, 'web.env');
+}
+
+// The Cloudflare zone a hostname's A record lives in. Cloudflare zones are
+// registrable domains, which for the common case is the last two DNS labels
+// (mercury.example.com → example.com; apex example.com → example.com). Multi-part
+// public suffixes (foo.co.uk) are NOT special-cased here — set CLOUDFLARE_ZONE in
+// the control-plane box.env to override (box-dns-cloudflare.sh honours it). PURE.
+function zoneForDomain(domain) {
+  const d = String(domain || '').trim().toLowerCase().replace(/\.$/, '');
+  if (!d) return '';
+  const labels = d.split('.').filter(Boolean);
+  return labels.length <= 2 ? labels.join('.') : labels.slice(-2).join('.');
+}
+
+// The env a DNS UPSERT invocation of infra/box-dns-cloudflare.sh needs for a
+// PROVISIONED host: the hostname, the target public IP (the A-record content), the
+// zone the record lives in, and whether Cloudflare proxies it.
+//   • proxied=false (default) is LOAD-BEARING for a CO-TENANT/dedicated host: it uses
+//     Caddy on-demand ACME (Let's Encrypt), whose challenge must reach Caddy directly —
+//     Cloudflare proxy ON would intercept :80/:443 at the edge and the challenge would
+//     silently fail (ADR 0003 / docs/recipes/ops-gotchas.md). Do NOT proxy those.
+//   • proxied=true for a STANDALONE host (task 2077): it runs control-plane-local under
+//     the *.cloudbongos.com wildcard Cloudflare Origin cert, so on-demand ACME never
+//     fires (a matching cert already exists) and proxied=false would serve that origin
+//     cert — untrusted to direct clients. Proxying lets the CF edge present a public cert
+//     (origin cert valid behind Full-strict) AND hides the control-plane IP.
+// An explicit `zone` wins over the derived one (for a multi-part-suffix domain). PURE.
+function dnsUpsertEnv(inst, { publicIp, zone, proxied = false } = {}) {
+  return {
+    BOX_HOSTNAME: inst.domain,
+    BOX_IP: publicIp,
+    CLOUDFLARE_ZONE: zone || zoneForDomain(inst.domain),
+    BOX_PROXIED: proxied ? '1' : '0',
+  };
+}
+
+// ── DNS token-scope PREFLIGHT (task 1980) ────────────────────────────────────
+// Onboarding a NEW project on a domain the control-plane's Cloudflare token does NOT
+// cover fails LATE: the DNS UPSERT (step 5) errors mid-provision (the Emersonian
+// standup — the token only covered the platform's original zone, so the new project's
+// record couldn't be created until it was widened MID-FLOW). This preflight detects
+// "the configured token can't reach the project's zone" UP FRONT, before the
+// connect-address step, and GUIDES the fix — instead of a half-done provision. It is
+// READ-ONLY (a CF `GET /zones?name=<zone>`); it never mutates DNS.
+const CF_API_BASE = process.env.CLOUDFLARE_API_BASE || 'https://api.cloudflare.com/client/v4';
+
+// PURE: given the outcome of `GET /zones?name=<zone>` (HTTP status + parsed JSON) and
+// the target zone, decide whether the token can MANAGE that zone, with actionable
+// guidance when it can't. Exported + unit-tested with no network.
+function classifyZoneScope({ status, body, zone }) {
+  const z = String(zone || '');
+  if (status === 401 || status === 403) {
+    return { reachable: false, reason: `Cloudflare rejected the token (HTTP ${status})`,
+      guidance: `The DNS token is invalid or lacks Zone:Read. Set CLOUDFLARE_API_TOKEN in the control-plane box.env to a token scoped to include ${z} (Zone:DNS:Edit + Zone:Read).` };
+  }
+  if (status !== 200 || !body || body.success !== true) {
+    const errs = body && Array.isArray(body.errors) ? body.errors.map((e) => e && e.message).filter(Boolean).join('; ') : '';
+    return { reachable: false, reason: `Cloudflare zone lookup failed (HTTP ${status}${errs ? `: ${errs}` : ''})`,
+      guidance: `Check CLOUDFLARE_API_TOKEN + network from the control plane, then retry.` };
+  }
+  const result = Array.isArray(body.result) ? body.result : [];
+  const match = result.find((r) => r && r.name === z);
+  if (!match) {
+    return { reachable: false, reason: `the token authenticated, but zone "${z}" is not in its scope`,
+      guidance: `Widen the Cloudflare API token to include ${z}: CF dashboard → My Profile → API Tokens → edit the token → Zone Resources → Include → ${z} (or use an account-scoped token). If ${z} is a multi-part public suffix (e.g. foo.co.uk), set CLOUDFLARE_ZONE explicitly in the control-plane box.env.` };
+  }
+  return { reachable: true, reason: `token can manage zone "${z}" (id ${match.id})`, zoneId: match.id };
+}
+
+// Query Cloudflare for the domain's zone with the configured token. Injectable
+// `token`/`fetchImpl` for tests. Returns { zone, reachable, reason, guidance[, zoneId] }.
+// A missing token/fetch/domain is reported as not-reachable-with-guidance — it never
+// throws for a config gap (the caller decides whether to hard-fail).
+async function checkDnsTokenScope(domain, { token = process.env.CLOUDFLARE_API_TOKEN, zoneOverride = process.env.CLOUDFLARE_ZONE, fetchImpl } = {}) {
+  const zone = zoneOverride || zoneForDomain(domain);
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : null);
+  if (!zone) return { zone, reachable: false, reason: 'no domain given', guidance: 'provide a domain before the address step' };
+  if (!token) return { zone, reachable: false, reason: 'no CLOUDFLARE_API_TOKEN configured', guidance: `Set CLOUDFLARE_API_TOKEN (Zone:DNS:Edit on ${zone}) in the control-plane box.env before provisioning DNS for ${domain}.` };
+  if (!doFetch) return { zone, reachable: false, reason: 'no fetch available', guidance: 'run on a Node with global fetch, or inject fetchImpl' };
+  let status = 0; let bodyJson = null;
+  try {
+    const res = await doFetch(`${CF_API_BASE}/zones?name=${encodeURIComponent(zone)}`, {
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    });
+    status = res.status;
+    bodyJson = await res.json().catch(() => null);
+  } catch (e) {
+    return { zone, reachable: false, reason: `Cloudflare request failed: ${e.message}`, guidance: 'check control-plane network + token, then retry' };
+  }
+  return { zone, ...classifyZoneScope({ status, body: bodyJson, zone }) };
+}
+
+// A Caddy reverse-proxy site block for the instance's domain → its local port.
+// TLS = on-demand ACME (P4, ADR 0111 §4): Caddy fetches a Let's Encrypt cert for
+// this host LAZILY, on the first TLS handshake — no manual Cloudflare Origin-Cert
+// console step (the least-automated leg). It is GATED by the global
+// `on_demand_tls { ask … }` allow-list in infra/Caddyfile (→ /api/bongos/
+// provisioning/tls-check), so Caddy only mints a cert for a host this module
+// actually provisioned — never an arbitrary SNI. The A record is proxied=false
+// (dnsUpsertEnv) so the challenge reaches Caddy. No domain → a comment
+// (bring-your-own-domain is deferred per-instance, ADR 0111 §4).
+function caddyBlock(inst) {
+  if (!inst.domain) {
+    return `# ${inst.slug}: no domain yet (bring-your-own-domain pending) — reachable on 127.0.0.1:${inst.port}\n`;
+  }
+  return `${inst.domain} {
+	tls {
+		on_demand
+	}
+	reverse_proxy 127.0.0.1:${inst.port}
+}
+`;
+}
+function caddySnippetPath(inst, { snippetDir = CONFIG.caddySnippetDir } = {}) {
+  return path.posix.join(snippetDir, `${inst.slug}.caddy`);
+}
+function healthzCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/healthz`;
+}
+
+// ---------------------------------------------------------------------------
+// The injectable executor. dry-run → log-only; --apply → child_process.
+// ---------------------------------------------------------------------------
+function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
+  return function run(cmd, { allowFail = false, cwd, env } = {}) {
+    // Extra env is passed to the child (not interpolated into the command), so
+    // values like a hostname/IP never need shell quoting. It's shown in the dry-run
+    // plan for transparency — DNS env (BOX_HOSTNAME/BOX_IP/CLOUDFLARE_ZONE) is not
+    // secret (the token stays in the hook's own EnvironmentFile, out of `env`).
+    const envPrefix = env ? `${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(' ')} ` : '';
+    if (remoteHost) {
+      // Remote step (task 2065): run it on the co-hosting box over SSH. The cwd +
+      // env + command are composed into a small script fed to the remote shell via
+      // STDIN (`ssh … bash -s`), so nothing needs shell-quoting on the way over
+      // (the #1 remote-exec footgun). cwd defaults to the remote checkout so a
+      // relative `./scripts/migrate.sh` resolves there. env goes INTO the script
+      // (a local child env wouldn't cross the ssh hop).
+      const wd = cwd || remoteCwd;
+      const script = `${wd ? `cd ${wd} && ` : ''}${envPrefix}${cmd}`;
+      const sshCmd = `ssh ${sshOpts} ${remoteHost} bash -s`;
+      const shown = `[ssh ${remoteHost}] ${script}`;
+      if (!apply) { log(`    would run: ${shown}`); return { dryRun: true, ok: true, stdout: '' }; }
+      try {
+        const stdout = cp.execSync(sshCmd, { input: script, stdio: ['pipe', 'pipe', 'pipe'], env: process.env }).toString();
+        log(`    ✓ ${shown}`);
+        return { ok: true, stdout };
+      } catch (e) {
+        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${(e.stderr || e.message || '').toString().trim().slice(0, 120)})`); return { ok: true, stdout: '', softFailed: true }; }
+        log(`    ✖ ${shown}`);
+        throw e;
+      }
+    }
+    // Local step (control plane / today's behavior). cwd defaults to REPO_ROOT.
+    const shown = `${envPrefix}${cmd}`;
+    if (!apply) { log(`    would run: ${shown}`); return { dryRun: true, ok: true, stdout: '' }; }
+    try {
+      const stdout = cp.execSync(cmd, { cwd: cwd || REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'], env: env ? { ...process.env, ...env } : process.env }).toString();
+      log(`    ✓ ${cmd}`);
+      return { ok: true, stdout };
+    } catch (e) {
+      if (allowFail) { log(`    ~ ${cmd} (non-fatal: ${(e.stderr || e.message || '').toString().trim().slice(0, 120)})`); return { ok: true, stdout: '', softFailed: true }; }
+      log(`    ✖ ${cmd}`);
+      throw e;
+    }
+  };
+}
+// A file write that respects dry-run (log-only) and applies chmod when asked.
+// When privileged AND the call opts in with { sudo: true } (the /etc destinations
+// the runner's non-root user can't write directly), the body is staged in a temp
+// file (lars-writable) then atomically placed with `sudo install -D -m <mode>`
+// (`-D` creates the parent dir, e.g. /etc/<slug>/). Otherwise a direct fs write
+// (unchanged). `exec` is injected so the install goes through the SAME dry-run/apply
+// + logging path as every other command (task 2066).
+function makeWriteFile({ apply, privileged = false, exec, log = console.log, remoteHost = null }) {
+  return function writeFile(p, body, { mode, sudo = false } = {}) {
+    if (remoteHost) {
+      // Remote file placement (task 2065): base64 the body, decode it ON the
+      // co-hosting box, and `tee` it into place — sudo-escalated when the
+      // destination (/etc/<slug>/…) needs root and we're privileged. base64 keeps
+      // arbitrary bytes/newlines out of the shell. It rides the box `exec` (which
+      // ssh's it), so it shares the same dry-run + logging + ssh path.
+      const dir = path.posix.dirname(p);
+      const sp = (sudo && privileged) ? 'sudo ' : '';
+      const b64 = Buffer.from(body, 'utf8').toString('base64');
+      const steps = [
+        `${sp}mkdir -p ${dir}`,
+        `printf %s '${b64}' | base64 -d | ${sp}tee ${p} >/dev/null`,
+      ];
+      if (mode) steps.push(`${sp}chmod ${mode.toString(8)} ${p}`);
+      const cmd = steps.join(' && ');
+      if (!apply) {
+        log(`    would write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''}) on ${remoteHost}`);
+        if (exec) exec(cmd);
+        return { dryRun: true };
+      }
+      exec(cmd);
+      log(`    ✓ wrote ${p} (on ${remoteHost})`);
+      return { ok: true };
+    }
+    if (sudo && privileged) {
+      // lars can't write under /etc; stage in a temp file then place it as root.
+      const tmp = path.join(os.tmpdir(), `prov-${path.basename(p)}-${process.pid}`);
+      const installCmd = `sudo install -D ${mode ? `-m ${mode.toString(8)} ` : ''}${tmp} ${p}`;
+      if (!apply) {
+        log(`    would write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''}) via temp + sudo install`);
+        if (exec) exec(installCmd);
+        return { dryRun: true };
+      }
+      fs.writeFileSync(tmp, body);
+      try { exec(installCmd); } finally { fs.rmSync(tmp, { force: true }); }
+      log(`    ✓ wrote ${p} (via sudo install)`);
+      return { ok: true };
+    }
+    if (!apply) { log(`    would write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''})`); return { dryRun: true }; }
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, body, mode ? { mode } : undefined);
+    if (mode) fs.chmodSync(p, mode);
+    log(`    ✓ wrote ${p}`);
+    return { ok: true };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Port allocation for a co-tenant instance: the lowest free port ≥ portBase not
+// already taken by another instance row or a reserved port. PURE given the taken set.
+// ---------------------------------------------------------------------------
+function nextFreePort(takenPorts, { portBase = CONFIG.portBase, reserved = CONFIG.reservedPorts } = {}) {
+  const taken = new Set([...(takenPorts || []), ...reserved].map(Number));
+  let p = portBase;
+  while (taken.has(p)) p += 1;
+  return p;
+}
+// Ports held by a LISTENING socket on the box the instance will bind on. A
+// co-tenant/standalone instance binds 127.0.0.1:<port>, so ANY process already
+// listening there — not just another provisioned instance or a CONFIG reserved
+// port — causes an EADDRINUSE crash-loop. Snapshot `ss` and return every listening
+// port so allocatePort can exclude them all → robust to any co-located service
+// (e.g. Grafana on the dedicated control plane, task 2070). `allowFail` degrades to
+// the prior DB-only behavior if `ss` is unavailable rather than blocking provisioning.
+function boundLocalPorts(exec) {
+  if (typeof exec !== 'function') return [];
+  let res;
+  try { res = exec('ss -ltnH 2>/dev/null || ss -ltn 2>/dev/null', { allowFail: true }); }
+  catch { return []; }
+  const ports = [];
+  for (const line of String((res && res.stdout) || '').split('\n')) {
+    const cols = line.trim().split(/\s+/);
+    if (cols.length < 4) continue;              // skip header / blank lines
+    const m = /:(\d+)$/.exec(cols[3]);          // Local Address:Port → 127.0.0.1:3003, *:80, [::1]:3003
+    if (m) ports.push(Number(m[1]));
+  }
+  return ports;
+}
+// Impure: reads the instance table AND (via the injected exec) the box's live
+// listening ports, so a port squatted by a NON-instance co-tenant is never handed
+// out. `exec` is the same executor provisionInstance uses, so for a remote co-tenant
+// it snapshots the remote box (task 2065) — where the instance actually binds.
+async function allocatePort(db, provisioning, { exec } = {}) {
+  const rows = await db.query(`SELECT port FROM provisioning_instances WHERE port IS NOT NULL`);
+  const dbPorts = rows.rows.map((r) => r.port);
+  return nextFreePort([...dbPorts, ...boundLocalPorts(exec)]);
+}
+
+// ---------------------------------------------------------------------------
+// Compose + run the standup runbook for ONE instance (idempotent, dry-run-safe).
+// deps: { db, provisioning, doApi, exec, writeFile, log, apply, privileged }
+// ---------------------------------------------------------------------------
+async function provisionInstance(inst, deps) {
+  const { db, provisioning, exec, writeFile, log, apply, privileged } = deps;
+  // The token step (Cloudflare DNS hook) runs on the control plane where the token
+  // lives — NEVER on the remote box (task 2065). Falls back to `exec` when a caller
+  // (e.g. a test) passes no controlExec — then both are the same local executor.
+  const controlExec = deps.controlExec || exec;
+  // Standalone instances run on the CONTROL PLANE (task 2074): scaffoldStandaloneRepo
+  // created their OWN repo dir here via controlExec, so the box-mutating steps below
+  // (code sync, migrate, /etc writes, systemd, Caddy, healthz) must run on the SAME
+  // box — NOT the remote co-hosting box that PROVISION_REMOTE_HOST routes co-tenant
+  // steps to (that box never had the dir; ADR 0130's remote-exec was co-tenant-only).
+  // So a standalone uses the control-plane executors; co-tenant + dedicated are
+  // unchanged (boxExec === exec, boxWriteFile === writeFile). When no remoteHost is
+  // set, controlExec === exec anyway, so this is a no-op for the all-local default.
+  const standalone = inst.hosting_shape === 'standalone';
+  const boxExec = standalone ? controlExec : exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl escalation prefix (task 2066)
+  log(`provision ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status})`);
+
+  // Idempotency: an already-active instance is a no-op success (re-drained intent).
+  if (inst.status === 'active') { log('  already active — nothing to do'); return { ok: true, already: true }; }
+
+  // ── preflight: DNS token scope (task 1980) ─────────────────────────────────
+  // BEFORE committing to the address (allocating a port / creating a droplet / the
+  // step-5 DNS UPSERT), verify the control-plane Cloudflare token can actually reach
+  // the domain's zone. Turns the Emersonian standup's confusing mid-flow step-5 DNS
+  // failure into an up-front, actionable stop with no half-done provision. Read-only.
+  if (inst.domain && CONFIG.dnsHook) {
+    if (apply) {
+      // Injectable so the composition stays hermetic in tests (deps.checkDnsTokenScope
+      // stubs the CF call); production passes the real checker (network read-only).
+      const scope = await (deps.checkDnsTokenScope || checkDnsTokenScope)(inst.domain);
+      if (!scope.reachable) {
+        throw new Error(`DNS preflight failed for ${inst.domain}: ${scope.reason}. ${scope.guidance}`);
+      }
+      log(`  [preflight] DNS token can reach zone ${scope.zone} ✓`);
+    } else {
+      log(`  [preflight] would verify the Cloudflare token can reach zone ${zoneForDomain(inst.domain)} before the address step`);
+    }
+  }
+
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
+  const patch = {};
+
+  // ── step 1: server ───────────────────────────────────────────────────────
+  // The A-record target for step 5's DNS UPSERT:
+  //   • co-tenant  → PROVISION_PUBLIC_IP (the box it runs on — under remote-exec that
+  //                  is the co-hosting box, ADR 0130).
+  //   • standalone → the CONTROL PLANE's own IP (task 2074): it runs control-plane-
+  //                  local, so its domain must point HERE, not at the co-hosting box.
+  //                  PROVISION_CONTROL_PLANE_IP when remote-exec splits the two boxes;
+  //                  else PROVISION_PUBLIC_IP (all-local: one and the same machine).
+  //                  Remote-exec set but no control-plane IP configured → null, which
+  //                  makes step 5 fail loud rather than point the domain at the wrong box.
+  //   • dedicated  → the droplet's own IP (captured once it settles, below).
+  let recordIp;
+  if (inst.hosting_shape === 'dedicated') recordIp = null;
+  else if (standalone) recordIp = CONFIG.controlPlaneIp || (CONFIG.remoteHost ? null : CONFIG.publicIp);
+  else recordIp = CONFIG.publicIp;
+  if (inst.hosting_shape === 'dedicated') {
+    // Dedicated droplet: create it + settle its public IP via the shared DO client
+    // (do-api, dry-run-default). The on-droplet app standup rides cloud-init
+    // user-data built from the SAME step commands below (mirrors box.js). For the
+    // dry-run plan we surface the intent; --apply creates the droplet.
+    const doApi = deps.doApi;
+    log('  [server] dedicated droplet');
+    if (apply && doApi) {
+      const { droplet } = await doApi.createDroplet({
+        name: `cb-${inst.slug}`, region: CONFIG.region, size: inst.tier || 's-2vcpu-4gb',
+        image: CONFIG.baseImage, tags: [CONFIG.tag], sshKeys: CONFIG.sshKeyIds,
+        userData: dedicatedUserData(inst),
+      });
+      const settled = await doApi.settleDroplet(droplet.id);
+      patch.error_note = null;
+      recordIp = settled.ip || null;   // the droplet's own IP is this instance's A-record target
+      log(`    droplet ${droplet.id} @ ${settled.ip || '(pending)'} — app standup rides cloud-init`);
+    } else {
+      log('    would createDroplet + settle IP, baking cloud-init that runs the standup steps');
+    }
+  } else {
+    // Co-tenant OR standalone: a process bound to an allocated port on the box it runs
+    // on. Co-tenant shares that box's checkout ($0, cloudbongos.com model — under
+    // remote-exec, the co-hosting box); standalone (ADR 0108) runs from its OWN repo
+    // dir with a pinned @cloudbongos/core (synced in step 2) on the CONTROL PLANE.
+    // Allocate against the ports of whichever box it runs on (boxExec: remote for a
+    // co-tenant, local for a standalone — task 2074), then run the rest there.
+    if (!inst.port) {
+      const port = await allocatePort(db, provisioning, { exec: boxExec });
+      patch.port = port;
+      inst = { ...inst, port };
+      log(`  [server] ${inst.hosting_shape} — allocated port ${port}`);
+    } else {
+      log(`  [server] ${inst.hosting_shape} — port ${inst.port}`);
+    }
+    // Standalone: SCAFFOLD its own repo if absent — clone the (empty) target_ref →
+    // materialize config/ + .claude/ + file:-pinned core + lockfile → commit + push
+    // (ADR 0108 / 0125, task 2055). Replaces the old "repo must already be cloned"
+    // throw: the greenfield flow now has no manual clone step. Idempotent + dry-run-safe.
+    if (inst.hosting_shape === 'standalone') {
+      await scaffoldStandaloneRepo(inst, deps);
+    }
+  }
+  if (!inst.db_name) { patch.db_name = inst.slug; inst = { ...inst, db_name: inst.slug }; }
+
+  // The remaining steps run on the instance's box for co-tenant + standalone (boxExec/
+  // boxWriteFile — remote for co-tenant under remote-exec, control-plane-local for
+  // standalone; task 2074); for dedicated they are baked into cloud-init (above) and
+  // re-asserted here as idempotent no-ops on the box.
+  const local = inst.hosting_shape !== 'dedicated';
+
+  // ── step 2: code sync (standalone) + database ─────────────────────────────
+  if (local && standalone) {
+    // Standalone (ADR 0108 / deploy-instance.sh steps 1-2): sync the instance's own
+    // repo + install the pinned @cloudbongos/core, so the migrate + service below run
+    // from the INSTANCE root, not this control-plane checkout. cwd = standaloneRoot.
+    // boxExec = the control plane (where scaffoldStandaloneRepo just created the dir).
+    const root = standaloneRoot(inst);
+    log('  [code] standalone — pull instance repo + npm ci (pinned @cloudbongos/core)');
+    boxExec(standalonePullCmd(), { cwd: root });
+    boxExec(standaloneInstallCmd(), { cwd: root });
+  }
+  log('  [db] create + GDS-only migrate');
+  if (local) {
+    boxExec(dbCreateCmd(inst, { privileged }), { allowFail: true });   // "already exists" is fine
+    if (standalone) boxExec(standaloneMigrateCmd(inst, { privileged }), { cwd: standaloneRoot(inst) });  // instance-root migrate
+    else boxExec(migrateCmd(inst, { privileged }));
+  } else { log('    (runs via cloud-init on the droplet)'); }
+
+  // ── step 3: config + per-instance secrets ─────────────────────────────────
+  log('  [config] per-instance web.env');
+  if (local) boxWriteFile(webEnvPath(inst), webEnvBody(inst), { mode: 0o600, sudo: true });
+  else log('    (baked into cloud-init)');
+
+  // ── step 4: systemd unit + enable ─────────────────────────────────────────
+  log('  [service] install + enable systemd unit');
+  if (local) {
+    boxWriteFile(serviceUnitPath(inst), serviceUnit(inst), { mode: 0o644, sudo: true });
+    boxExec(`${sudoP}systemctl daemon-reload`);
+    boxExec(`${sudoP}systemctl enable --now ${inst.slug}`);
+  } else { log('    (unit baked into cloud-init)'); }
+
+  // ── step 5: DNS — Cloudflare A-record UPSERT for the instance's domain (P4) ──
+  // Formalized in P4 (#1945): the shared box-dns-cloudflare.sh hook UPSERTs an A
+  // record pointing the domain at its target IP (recordIp), in the domain's own
+  // zone, proxied=false so Caddy's on-demand ACME challenge (step 6) reaches the
+  // origin (dnsUpsertEnv). It runs on the CONTROL PLANE for BOTH shapes: the hook
+  // needs the Cloudflare token, which never leaves the control plane, so a dedicated
+  // instance's DNS is upserted from here (not baked into the droplet's cloud-init).
+  // Unlike P3's best-effort allowFail, a DNS FAILURE now SURFACES (the task-1180
+  // lesson: never report provision success while the A record silently didn't land).
+  if (inst.domain && CONFIG.dnsHook) {
+    if (!recordIp) {
+      const ipEnvHint = standalone ? 'PROVISION_CONTROL_PLANE_IP (standalone)' : 'PROVISION_PUBLIC_IP (co-tenant)';
+      if (apply) throw new Error(`cannot UPSERT DNS for ${inst.domain}: no target IP — set ${ipEnvHint} in the control-plane box.env, or the droplet must settle an IP (dedicated)`);
+      log(`  [dns] would upsert A ${inst.domain} once the target IP is known (set ${ipEnvHint})`);
+    } else {
+      // Standalone runs control-plane-local under the *.cloudbongos.com wildcard origin
+      // cert (task 2074/2077) → proxied=true (CF edge fronts it, IP hidden); co-tenant +
+      // dedicated stay proxied=false so their on-demand ACME challenge reaches the origin.
+      const dnsEnv = dnsUpsertEnv(inst, { publicIp: recordIp, proxied: standalone });
+      log(`  [dns] upsert A ${inst.domain} -> ${recordIp} (zone ${dnsEnv.CLOUDFLARE_ZONE}, proxied=${dnsEnv.BOX_PROXIED === '1'}) via ${CONFIG.dnsHook}`);
+      // controlExec, NOT exec: the DNS hook needs the Cloudflare token, which lives
+      // only on the control plane — it must never run on the (token-free) co-hosting
+      // box even when the box-mutating steps above went there over SSH (task 2065).
+      controlExec(CONFIG.dnsHook, { env: dnsEnv });
+    }
+  } else {
+    log('  [dns] skipped (no domain, or BOX_DNS_HOOK unset)');
+  }
+
+  // ── step 6: Caddy per-instance site snippet + reload ──────────────────────
+  // Write the instance's OWN <slug>.caddy snippet (idempotent overwrite via the
+  // injected writeFile — no read-modify-append to a shared Caddyfile), then reload.
+  // The main Caddyfile carries a one-time `import <snippetDir>/*.caddy` (operator
+  // setup). The on-demand-ACME TLS hardening of this block is task P4 (#1945).
+  log('  [caddy] write site snippet + reload');
+  if (local) {
+    boxWriteFile(caddySnippetPath(inst), caddyBlock(inst), { mode: 0o644, sudo: true });
+    boxExec(`${sudoP}systemctl reload caddy`, { allowFail: true });
+  } else { log('    (Caddy on the droplet via cloud-init)'); }
+
+  // ── step 7: healthz ───────────────────────────────────────────────────────
+  log('  [healthz] verify the instance answers');
+  if (local) boxExec(healthzCmd(inst), { allowFail: true });
+  else log('    (verified post-boot)');
+
+  // Mark active.
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'active', { ...patch, provisioned_at: new Date().toISOString() });
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'active', detail: `provisioned (${inst.hosting_shape}, port ${inst.port || '-'})`, actor: 'runner' });
+  }
+  log(`  ✓ ${inst.slug} provisioned`);
+  return { ok: true, port: inst.port };
+}
+
+// The cloud-init user-data for a dedicated droplet: run the co-tenant standup
+// steps on first boot. Kept small (well under DO's 64 KiB cap). Built from the
+// SAME pure command generators so local + dedicated never diverge.
+function dedicatedUserData(inst) {
+  const i = { ...inst, db_name: inst.db_name || inst.slug };
+  return `#cloud-config
+runcmd:
+  - [ bash, -lc, "${dbCreateCmd(i)} || true" ]
+  - [ bash, -lc, "cd ${REPO_ROOT} && ${migrateCmd(i)}" ]
+  - [ bash, -lc, "systemctl daemon-reload && systemctl enable --now ${i.slug}" ]
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Teardown one instance (reverse the runbook; idempotent).
+// ---------------------------------------------------------------------------
+async function teardownInstance(inst, deps) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
+  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
+  // box, where it was never installed (that would allowFail-noop and leave the real
+  // control-plane unit running). Co-tenant + dedicated are unchanged.
+  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
+  log(`teardown ${inst.slug} (status=${inst.status})`);
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
+  if (inst.hosting_shape !== 'dedicated') {
+    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
+    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
+    // DB + Caddy block are left for an explicit operator (data is precious; a
+    // teardown should not silently dropdb). We log the manual follow-ups.
+    log(`  (left for the operator: dropdb ${dbName(inst)}, remove the Caddy block for ${inst.slug})`);
+  } else if (apply && deps.doApi && inst.droplet_id) {
+    await deps.doApi.deleteDroplet(inst.droplet_id);
+  }
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
+  }
+  log(`  ✓ ${inst.slug} torn down`);
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// GitHub App Manifest conversion + cred placement (task 2080, ADR 0133).
+// The web tier stored GitHub's temporary `code` on a provisioning_oauth_manifests
+// row (status 'code_received'); THIS runner — the sole token-holder — exchanges it
+// for the client creds and places them in the instance's web.env, then verifies
+// /healthz. The secret is fetched here and written straight to disk: it never
+// touches the web tier or the browser (ADR 0111 §2 / ADR 0016 trust boundary).
+// ---------------------------------------------------------------------------
+
+// Exchange GitHub's manifest `code` for the App's client creds. UNAUTHENTICATED by
+// design — the single-use code IS the auth (GitHub docs). `fetchImpl` injectable for
+// tests. Throws on a non-2xx or a response missing client_id/client_secret.
+async function convertManifestCode(code, { fetchImpl = globalThis.fetch, userAgent = MANIFEST_UA } = {}) {
+  if (!code) throw new Error('no manifest code to convert');
+  const res = await fetchImpl(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': userAgent,
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+  const text = await res.text();
+  let data; try { data = JSON.parse(text); } catch { data = null; }
+  if (!res.ok) {
+    const msg = (data && (data.message || data.error)) || `HTTP ${res.status}`;
+    throw new Error(`GitHub manifest conversion failed: ${msg}`);
+  }
+  if (!data || !data.client_id || !data.client_secret) {
+    throw new Error('GitHub manifest conversion returned no client_id/client_secret');
+  }
+  return {
+    clientId: String(data.client_id),
+    clientSecret: String(data.client_secret),
+    appId: data.id != null ? Number(data.id) : null,
+    appSlug: data.slug || null,
+  };
+}
+
+// Convert one manifest row's code → creds and PLACE them (rewrite web.env + restart +
+// verify /healthz). Uses the SAME executors provisionInstance does, so co-tenant (local
+// or remote-cohost) and standalone (control-plane-local) are handled identically. A
+// dedicated droplet bakes web.env into cloud-init and has no post-hoc exec path here, so
+// it is refused with guidance. Returns { ok, appId, appSlug } | { ok:false, error }.
+async function placeManifestCreds(inst, mrow, deps) {
+  const { log, apply } = deps;
+  if (inst.hosting_shape === 'dedicated') {
+    return { ok: false, error: 'GitHub App Manifest cred placement is not supported for a dedicated droplet yet — run oauth-secret.js on the droplet instead' };
+  }
+  if (!mrow.github_code) return { ok: false, error: 'manifest row carries no github_code to convert' };
+  const standalone = inst.hosting_shape === 'standalone';
+  const boxExec = standalone ? (deps.controlExec || deps.exec) : deps.exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || deps.writeFile) : deps.writeFile;
+  const sudoP = deps.privileged ? 'sudo ' : '';
+
+  // 1) exchange the code with GitHub (control-plane-side; the secret lands here only).
+  let creds;
+  if (apply) {
+    creds = await (deps.convertManifestCode || convertManifestCode)(mrow.github_code, {});
+  } else {
+    log(`  [oauth-manifest] would POST api.github.com/app-manifests/<code>/conversions for ${inst.slug}`);
+    creds = { clientId: '0'.repeat(20), clientSecret: '0'.repeat(40), appId: null, appSlug: null };
+  }
+
+  // 2) validate the returned creds BEFORE writing (catch a malformed GitHub response —
+  //    the same length/charset guard oauth-secret.js uses against silent truncation).
+  const idV = oauthSecret.validateClientId(creds.clientId);
+  const secV = oauthSecret.validateClientSecret(creds.clientSecret);
+  if (!idV.ok || !secV.ok) {
+    const why = [!idV.ok ? `id: ${idV.reason}` : null, !secV.ok ? `secret: ${secV.reason}` : null].filter(Boolean).join('; ');
+    return { ok: false, error: `GitHub returned unusable creds (${why})` };
+  }
+
+  // 3) rewrite web.env with the creds + restart the unit (never logs the secret — the
+  //    writeFile logs only a byte count; the value is base64/temp-file placed).
+  log(`  [oauth-manifest] place creds in ${webEnvPath(inst)} + restart ${inst.slug}`);
+  boxWriteFile(webEnvPath(inst), webEnvBody(inst, { clientId: creds.clientId, clientSecret: creds.clientSecret }), { mode: 0o600, sudo: true });
+  boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+
+  // 4) verify /healthz reports auth_configured=true (only meaningful under --apply).
+  if (apply) {
+    let authConfigured = false;
+    for (let i = 0; i < 10; i++) {
+      const out = boxExec(healthzCmd(inst), { allowFail: true });
+      if (oauthSecret.parseHealthzAuth(out && out.stdout).authConfigured) { authConfigured = true; break; }
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+    if (!authConfigured) {
+      return { ok: false, error: 'placed creds but /healthz still reports auth_configured=false — sign-in not live yet' };
+    }
+    log('  [oauth-manifest] ✓ /healthz auth_configured=true — sign-in is live');
+  } else {
+    log('  [oauth-manifest] would probe /healthz for auth_configured after restart');
+  }
+  return { ok: true, appId: creds.appId, appSlug: creds.appSlug };
+}
+
+// Drain provisioning_oauth_manifests rows awaiting conversion (status 'code_received').
+// Runs on the SAME timer tick as the intent queue (called from cmdRunIntents). Each row
+// is claimed atomically (status → 'converting', SKIP LOCKED) so overlapping ticks are
+// safe; a retryable failure resets it to 'code_received' for a future tick until the
+// attempt cap, then 'error'. A `seen` set stops a hot re-claim loop within one tick.
+async function drainOAuthManifests(deps) {
+  const { db, provisioning, log, apply } = deps;
+  if (!apply) {
+    const { rows } = await db.query(
+      `SELECT m.id, i.slug FROM provisioning_oauth_manifests m
+         JOIN provisioning_instances i ON i.id = m.instance_id
+        WHERE m.status = 'code_received' ORDER BY m.created_at`);
+    if (rows.length) {
+      log(`oauth-manifest runner (dry-run): ${rows.length} awaiting conversion`);
+      for (const r of rows) log(`  would convert + place creds for ${r.slug} (manifest #${r.id})`);
+    }
+    return { converted: 0, errors: 0 };
+  }
+  let converted = 0, errors = 0;
+  const seen = new Set();
+  for (;;) {
+    const mrow = await provisioning.claimNextOAuthManifest(db);
+    if (!mrow) break;
+    if (seen.has(mrow.id)) {
+      // Already tried this row this tick (a retryable failure reset it). Put it back and
+      // stop, so a persistent failure retries on the NEXT tick instead of hot-looping.
+      await provisioning.resolveOAuthManifest(db, mrow.id, 'code_received', {}).catch(() => {});
+      break;
+    }
+    seen.add(mrow.id);
+    if (mrow.attempts > MAX_INTENT_ATTEMPTS) {
+      await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: `exceeded ${MAX_INTENT_ATTEMPTS} attempts` });
+      errors++; log(`  ✖ oauth-manifest #${mrow.id} retired (too many attempts)`); continue;
+    }
+    try {
+      const inst = await provisioning.getInstanceById(db, mrow.instance_id);
+      if (!inst) { await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: 'instance row vanished' }); errors++; continue; }
+      const result = await placeManifestCreds(inst, mrow, deps);
+      if (result && result.ok === false) {
+        if (mrow.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: result.error });
+        else await provisioning.resolveOAuthManifest(db, mrow.id, 'code_received', { last_error: result.error });
+        errors++; log(`  ✖ oauth-manifest #${mrow.id}: ${result.error}`);
+      } else {
+        await provisioning.resolveOAuthManifest(db, mrow.id, 'done', { app_id: result.appId, app_slug: result.appSlug });
+        await provisioning.recordEvent(db, {
+          instanceId: inst.id, ownerBuilderId: mrow.requested_by, event: 'oauth-manifest-done',
+          detail: `sign-in wired via GitHub App Manifest (app ${result.appSlug || result.appId || '?'})`, actor: 'runner',
+        }).catch(() => {});
+        converted++;
+      }
+    } catch (e) {
+      await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: e.message }).catch(() => {});
+      errors++; log(`  ✖ oauth-manifest #${mrow.id}: ${e.message}`);
+    }
+  }
+  if (converted || errors) log(`oauth-manifest — converted=${converted} errors=${errors}`);
+  return { converted, errors };
+}
+
+// ---------------------------------------------------------------------------
+// run-intents — drain provisioning_intents (the systemd-timer entry point). The
+// box.js cmdRunIntents shape: dry-run lists the pending queue; --apply claims +
+// executes each, with a poison-attempt cap. FOR UPDATE SKIP LOCKED (in
+// provisioning.claimNextIntent) makes overlapping ticks safe. It ALSO drains the
+// GitHub-App-Manifest conversion queue on the same tick (task 2080).
+// ---------------------------------------------------------------------------
+async function cmdRunIntents(deps) {
+  const { db, provisioning, log, apply } = deps;
+  if (!apply) {
+    const { rows } = await db.query(
+      `SELECT pi.*, i.slug FROM provisioning_intents pi
+         JOIN provisioning_instances i ON i.id = pi.instance_id
+        WHERE pi.state = 'pending' ORDER BY pi.created_at`);
+    log(`provision intent runner (dry-run): ${rows.length} pending intent(s)`);
+    for (const r of rows) log(`  would ${r.action} ${r.slug} (intent #${r.id}, attempts=${r.attempts})`);
+    if (rows.length === 0) log('  queue empty — exit clean');
+    await drainOAuthManifests(deps);
+    return { ran: 0 };
+  }
+  let ran = 0, ok = 0, errors = 0;
+  for (;;) {
+    const intent = await provisioning.claimNextIntent(db);
+    if (!intent) break;
+    ran++;
+    if (intent.attempts > MAX_INTENT_ATTEMPTS) {
+      await provisioning.resolveIntent(db, intent.id, 'error', `exceeded ${MAX_INTENT_ATTEMPTS} attempts`);
+      errors++; log(`  ✖ intent #${intent.id} retired (too many attempts)`); continue;
+    }
+    try {
+      const inst = await provisioning.getInstanceById(db, intent.instance_id);
+      if (!inst) { await provisioning.resolveIntent(db, intent.id, 'error', 'instance row vanished'); errors++; continue; }
+      const result = intent.action === 'provision'
+        ? await provisionInstance(inst, deps)
+        : await teardownInstance(inst, deps);
+      if (result && result.ok === false) {
+        if (intent.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
+        else await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
+        errors++;
+      } else { await provisioning.resolveIntent(db, intent.id, 'done', null); ok++; }
+    } catch (e) {
+      await provisioning.resolveIntent(db, intent.id, 'error', e.message).catch(() => {});
+      // Surface the failure on the instance too, so a stuck instance is visible.
+      await provisioning.setInstanceStatus(db, intent.instance_id, 'error', { error_note: e.message }).catch(() => {});
+      errors++; log(`  ✖ intent #${intent.id}: ${e.message}`);
+    }
+  }
+  // Same tick: convert + place any GitHub-App-Manifest creds awaiting the control plane.
+  const m = await drainOAuthManifests(deps);
+  log(`done — ran=${ran} ok=${ok} errors=${errors}; oauth-manifest converted=${m.converted} errors=${m.errors}`);
+  return { ran, ok, errors, manifests: m };
+}
+
+// A light drift reconcile: surface instances stuck mid-flight (provisioning /
+// tearing_down) with no open intent — a runner died mid-op. Reports; --apply
+// re-enqueues a fresh intent so the next tick retries. (Full droplet-vs-DB drift,
+// the box.js reconcile-drift analogue, is a later hardening.)
+async function cmdReconcile(deps) {
+  const { db, provisioning, log, apply } = deps;
+  const { rows } = await db.query(
+    `SELECT i.* FROM provisioning_instances i
+      WHERE i.status IN ('provisioning','tearing_down')
+        AND NOT EXISTS (SELECT 1 FROM provisioning_intents pi
+                         WHERE pi.instance_id = i.id AND pi.state IN ('pending','running'))`);
+  log(`reconcile: ${rows.length} instance(s) stuck mid-flight with no open intent`);
+  for (const inst of rows) {
+    const action = inst.status === 'tearing_down' ? 'teardown' : 'provision';
+    log(`  ${inst.slug} [${inst.status}] → re-enqueue ${action}`);
+    if (apply) await provisioning.enqueueIntent(db, inst.id, action, 'runner:reconcile');
+  }
+  return { stuck: rows.length };
+}
+
+async function cmdStatus(deps) {
+  const { db, log } = deps;
+  const { rows } = await db.query(
+    `SELECT i.slug, i.status, i.hosting_shape, i.port, i.domain, i.cost_estimate_usd, b.github_login
+       FROM provisioning_instances i JOIN builders b ON b.id = i.owner_builder_id
+      ORDER BY i.updated_at DESC LIMIT 200`);
+  if (rows.length === 0) { log('no provisioned instances yet.'); return { count: 0 }; }
+  log('provisioned instances:');
+  let monthly = 0;
+  for (const r of rows) {
+    monthly += Number(r.cost_estimate_usd || 0);
+    log(`  ${String(r.slug).padEnd(20)} ${String(r.status).padEnd(13)} ${r.hosting_shape.padEnd(10)} port=${r.port || '-'} @${r.github_login} $${Number(r.cost_estimate_usd || 0).toFixed(2)}/mo  ${r.domain || ''}`);
+  }
+  log(`\n  estimated run-rate: ~$${monthly.toFixed(2)}/mo`);
+  return { count: rows.length };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function usage() {
+  console.log(`provision.js — instance-provisioning control-plane runner (ADR 0111, #1944)
+
+Usage:
+  node scripts/gds/provision.js <command> [slug] [--apply]
+
+Commands:
+  run-intents            drain provisioning_intents (the systemd-timer entry point):
+                         execute each pending provision/teardown intent
+  provision <slug>       provision one instance by slug (composes the standup runbook)
+  teardown <slug>        tear down one instance by slug
+  reconcile              re-enqueue instances stuck mid-flight with no open intent
+  status                 list provisioned instances + estimated run-rate
+  dns-check <domain>     PREFLIGHT: verify the control-plane Cloudflare token can reach
+                         the domain's zone BEFORE the address step (network-only, no DB)
+
+DRY-RUN by default — nothing mutates without --apply. The LIVE leg (real createdb /
+migrate / systemctl / caddy / DigitalOcean) needs the DO/Cloudflare tokens from
+/etc/<inst>/box.env (systemd EnvironmentFile=) and runs on the control plane only.
+
+Set PROVISION_SUDO=1 (the control-plane runner unit does) to escalate the privileged
+steps via sudo — required when the runner runs as a non-root user (ADR 0128).
+
+Set PROVISION_REMOTE_HOST=<user@host> (+ PROVISION_REMOTE_CHECKOUT, PROVISION_PUBLIC_IP)
+to run the box-mutating steps on a REMOTE co-hosting box over ssh, so the control
+plane can orchestrate co-tenant workloads that live there without that box holding
+any cloud token (ADR 0130). The Cloudflare DNS hook always stays on the control plane.
+
+STANDALONE instances (their own repo dir, ADR 0108) run control-plane-LOCAL even under
+PROVISION_REMOTE_HOST — their scaffolded dir lives on the control plane, not the remote
+box (task 2074). Set PROVISION_CONTROL_PLANE_IP to this box's own public IP so a
+standalone instance's A record points HERE, not at the co-hosting box's PROVISION_PUBLIC_IP.`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  const apply = hasFlag(args, '--apply');
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { usage(); process.exit(0); }
+
+  // dns-check <domain> — the DNS token-scope PREFLIGHT (task 1980). Network-only + no
+  // DB, so onboarding can run it BEFORE the connect-address step (and before any
+  // provision). Exits 0 if the token can reach the domain's zone, 1 with guidance if not.
+  if (cmd === 'dns-check') {
+    const domain = args[1] && !args[1].startsWith('--') ? args[1] : null;
+    if (!domain) { console.error('dns-check needs a <domain>'); process.exit(2); }
+    const scope = await checkDnsTokenScope(domain);
+    if (scope.reachable) { console.log(`✓ DNS token can reach zone ${scope.zone} for ${domain} — ${scope.reason}`); process.exit(0); }
+    console.error(`✖ DNS token cannot reach zone ${scope.zone} for ${domain}: ${scope.reason}`);
+    console.error(`  → ${scope.guidance}`);
+    process.exit(1);
+  }
+
+  const known = ['run-intents', 'provision', 'teardown', 'reconcile', 'status'];
+  if (!known.includes(cmd)) { console.error(`unknown command: ${cmd}\n`); usage(); process.exit(2); }
+  const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
+
+  let pool, provisioning, DoApi;
+  try { ({ pool, provisioning, DoApi } = loadDeps()); }
+  catch (e) { console.error(`cannot load DB layer (run this on the control plane): ${e.message}`); process.exit(1); }
+
+  // Box-target executor (remote over SSH when PROVISION_REMOTE_HOST is set, else
+  // local) for the box-mutating steps; controlExec is ALWAYS local — the token
+  // step (Cloudflare DNS hook) + the standalone repo scaffold run on the control
+  // plane where the token + packaging tools live (task 2065, ADR 0130).
+  const exec = makeExec({ apply, remoteHost: CONFIG.remoteHost, remoteCwd: CONFIG.remoteCwd, sshOpts: CONFIG.sshOpts });
+  const controlExec = makeExec({ apply });
+  const deps = {
+    db: pool, provisioning, apply, privileged: CONFIG.privileged, log: console.log,
+    exec, controlExec,
+    writeFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec, remoteHost: CONFIG.remoteHost }),
+    controlWriteFile: makeWriteFile({ apply, privileged: CONFIG.privileged, exec: controlExec }),
+    doApi: DoApi ? new DoApi({ dryRun: !apply, token: CONFIG.doToken, log: (m) => console.log('    ' + m) }) : null,
+  };
+
+  let result;
+  try {
+    if (cmd === 'run-intents') result = await cmdRunIntents(deps);
+    else if (cmd === 'provision') { const inst = await provisioning.getInstanceBySlug(pool, slug); if (!inst) { console.error(`no instance with slug '${slug}'`); await pool.end().catch(() => {}); process.exit(1); } result = await provisionInstance(inst, deps); }
+    else if (cmd === 'teardown') { const inst = await provisioning.getInstanceBySlug(pool, slug); if (!inst) { console.error(`no instance with slug '${slug}'`); await pool.end().catch(() => {}); process.exit(1); } result = await teardownInstance(inst, deps); }
+    else if (cmd === 'reconcile') result = await cmdReconcile(deps);
+    else if (cmd === 'status') result = await cmdStatus(deps);
+  } catch (e) {
+    console.error('fatal:', e && e.message ? e.message : e);
+    await pool.end().catch(() => {});
+    process.exit(1);
+  }
+  await pool.end().catch(() => {});
+  process.exit(result && result.ok === false ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  CONFIG, MAX_INTENT_ATTEMPTS,
+  // pure step generators (tested directly)
+  dbName, dbCreateCmd, migrateCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
+  standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
+  // standalone scaffold (ADR 0108 / 0125, task 2055)
+  parseTargetRef, instanceRepoRemote, instanceInitSpec, scaffoldStandaloneRepo, coreVersionSafe,
+  zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,
+  caddyBlock, caddySnippetPath, healthzCmd, dedicatedUserData, nextFreePort,
+  // executors + orchestration (injectable deps for tests)
+  makeExec, makeWriteFile, allocatePort, boundLocalPorts, provisionInstance, teardownInstance,
+  cmdRunIntents, cmdReconcile, cmdStatus,
+  // GitHub App Manifest flow (task 2080, ADR 0133)
+  convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
+};