@bongos/core 1.17.0

package/tests/provision.mjs

@@ -0,0 +1,805 @@
+// tests/provision.mjs
+//
+// Hermetic unit smoke for the instance-provisioning control-plane runner
+// (scripts/gds/provision.js, ADR 0111 §2/§3, task #1944). Covers the PURE runbook
+// step-command generators, port allocation, and the dry-run COMPOSITION of
+// provisionInstance / teardownInstance / cmdRunIntents — all with NO database, NO
+// DigitalOcean, NO shell, NO network (exec + writeFile + db are recording fakes).
+// The LIVE leg (real createdb/migrate/systemctl/caddy) is exercised on the control
+// plane in --apply; the composition + ordering it relies on are pinned here.
+//
+// Run:  node tests/provision.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const P = require('../scripts/gds/provision.js');
+
+// The env-var prefix a provisioned instance resolves = the envPrefix of the pack
+// webEnvBody points GDS_BRANDING_FILE at (config/branding.neutral.json). Read it
+// here so these assertions stay in lockstep with the code (both derive it), not a
+// pinned literal that would rot if the neutral default ever changed.
+const NEUTRAL_PREFIX =
+  JSON.parse(readFileSync(new URL('../config/branding.neutral.json', import.meta.url), 'utf8')).envPrefix || 'CLOUDBONGOS';
+const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const coTenant = { id: 1, slug: 'mercury', hosting_shape: 'co-tenant', status: 'requested', owner_builder_id: 7, port: 3003, db_name: 'mercury', domain: null };
+
+console.log('pure step generators:');
+
+t('dbCreateCmd / migrateCmd use the slug db + GDS-only migrate', () => {
+  assert.equal(P.dbCreateCmd(coTenant), 'createdb mercury');
+  assert.match(P.migrateCmd(coTenant), /PGDATABASE=mercury MEDUSA_GDS_ONLY=1 \.\/scripts\/migrate\.sh/);
+});
+
+t('serviceUnit binds the instance port + DB + per-instance env file, runs platform-server', () => {
+  const u = P.serviceUnit(coTenant, { etcBase: '/etc' });
+  assert.match(u, /Environment=PORT=3003/);
+  assert.match(u, /Environment=PGDATABASE=mercury/);
+  assert.match(u, /EnvironmentFile=\/etc\/mercury\/web\.env/);
+  assert.match(u, /ExecStart=\/usr\/bin\/node src\/platform-server\.js/);
+  assert.match(u, /WantedBy=multi-user\.target/);
+});
+
+t('serviceUnit(standalone) runs the CORE PACKAGE server from the instance\'s OWN repo dir (ADR 0108)', () => {
+  const inst = { ...coTenant, hosting_shape: 'standalone' };
+  const u = P.serviceUnit(inst, { etcBase: '/etc' });
+  const root = P.standaloneRoot(inst);
+  assert.match(u, new RegExp('WorkingDirectory=' + reEsc(root)), 'runs from the instance\'s own repo dir');
+  assert.match(u, /ExecStart=\/usr\/bin\/node node_modules\/@cloudbongos\/core\/src\/platform-server\.js/, 'runs the pinned core package server');
+  assert.match(u, /Environment=PORT=3003/);
+  assert.match(u, /EnvironmentFile=\/etc\/mercury\/web\.env/);
+});
+
+t('standalone step generators: root under standaloneBase + pull / npm-ci / instance-root migrate', () => {
+  const inst = { ...coTenant, hosting_shape: 'standalone' };
+  assert.match(P.standaloneRoot(inst), /\/mercury$/);
+  assert.equal(P.standalonePullCmd(), 'git pull --ff-only origin main');
+  assert.equal(P.standaloneInstallCmd(), 'npm ci --omit=dev');
+  assert.match(P.standaloneMigrateCmd(inst), /PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash node_modules\/@cloudbongos\/core\/scripts\/migrate\.sh/);
+});
+
+t('webEnvBody: OAuth creds use the LOADED pack\'s envPrefix (not the slug) + brand/port/db', () => {
+  const b = P.webEnvBody(coTenant); // coTenant.domain === null
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_SECRET=`));
+  assert.match(b, /GDS_BRANDING_FILE=config\/branding\.neutral\.json/);
+  assert.match(b, /PORT=3003/);
+  assert.match(b, /PGDATABASE=mercury/);
+  // The prior slug prefix was a latent bug: it never matched the neutral pack's
+  // envPrefix, so resolveEnv could not read the OAuth creds. It must be gone.
+  assert.doesNotMatch(b, /MERCURY_GITHUB_CLIENT_ID=/);
+  // No domain ⇒ NO origin overrides (writing them would pin neutral/localhost wrongly).
+  assert.doesNotMatch(b, /_BUILDERS_ORIGIN=/);
+});
+
+t('webEnvBody: a domain writes the single-host origin overrides so the hall loads (task 1972)', () => {
+  const b = P.webEnvBody({ ...coTenant, domain: 'mercury.example.com' });
+  const O = reEsc('https://mercury.example.com');
+  // publicOrigin + buildersOrigin (the hall) + statusOrigin + oauthOrigin all → the one host,
+  // under the prefix src/branding.js's ENV_OVERRIDES actually reads.
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_PUBLIC_ORIGIN=${O}`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_BUILDERS_ORIGIN=${O}`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_STATUS_ORIGIN=${O}`));
+  assert.match(b, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_OAUTH_ORIGIN=${O}`));
+});
+
+t('caddyBlock: a domain → on-demand-TLS reverse_proxy to the local port; no domain → a comment', () => {
+  const withDomain = P.caddyBlock({ ...coTenant, domain: 'mercury.example.com' });
+  assert.match(withDomain, /mercury\.example\.com \{/);
+  assert.match(withDomain, /reverse_proxy 127\.0\.0\.1:3003/);
+  // P4: on-demand ACME TLS (no manual Origin-Cert leg), gated by on_demand_tls ask.
+  assert.match(withDomain, /tls \{/);
+  assert.match(withDomain, /on_demand/);
+  const noDomain = P.caddyBlock(coTenant);
+  assert.match(noDomain, /^#/);
+  assert.doesNotMatch(noDomain, /reverse_proxy/);
+  assert.doesNotMatch(noDomain, /on_demand/);
+});
+
+console.log('\nDNS UPSERT helpers (P4):');
+
+t('zoneForDomain: registrable (last two labels), apex, trailing dot, empty', () => {
+  assert.equal(P.zoneForDomain('mercury.example.com'), 'example.com');
+  assert.equal(P.zoneForDomain('example.com'), 'example.com');
+  assert.equal(P.zoneForDomain('a.b.c.example.com'), 'example.com');
+  assert.equal(P.zoneForDomain('EXAMPLE.COM.'), 'example.com');
+  assert.equal(P.zoneForDomain(''), '');
+  assert.equal(P.zoneForDomain(null), '');
+});
+
+t('dnsUpsertEnv: hostname + target IP + derived zone; an explicit zone wins', () => {
+  const e = P.dnsUpsertEnv({ domain: 'mercury.example.com' }, { publicIp: '203.0.113.5' });
+  assert.equal(e.BOX_HOSTNAME, 'mercury.example.com');
+  assert.equal(e.BOX_IP, '203.0.113.5');
+  assert.equal(e.CLOUDFLARE_ZONE, 'example.com');
+  // A multi-part public suffix (foo.co.uk) can't be derived — the operator overrides.
+  const e2 = P.dnsUpsertEnv({ domain: 'x.foo.co.uk' }, { publicIp: '1.2.3.4', zone: 'foo.co.uk' });
+  assert.equal(e2.CLOUDFLARE_ZONE, 'foo.co.uk');
+});
+
+t('dnsUpsertEnv: BOX_PROXIED defaults off (co-tenant on-demand ACME); proxied:true opts in (standalone behind the wildcard origin cert, task 2077)', () => {
+  assert.equal(P.dnsUpsertEnv({ domain: 'mercury.example.com' }, { publicIp: '203.0.113.5' }).BOX_PROXIED, '0');
+  assert.equal(P.dnsUpsertEnv({ domain: 'mercury.example.com' }, { publicIp: '203.0.113.5', proxied: false }).BOX_PROXIED, '0');
+  assert.equal(P.dnsUpsertEnv({ domain: 'demo.cloudbongos.com' }, { publicIp: '161.35.132.201', proxied: true }).BOX_PROXIED, '1');
+});
+
+t('healthzCmd hits the instance port /healthz', () => {
+  assert.match(P.healthzCmd(coTenant), /127\.0\.0\.1:3003\/healthz/);
+});
+
+t('dedicatedUserData bakes createdb + migrate into cloud-init', () => {
+  const ud = P.dedicatedUserData(coTenant);
+  assert.match(ud, /^#cloud-config/);
+  assert.match(ud, /createdb mercury/);
+  assert.match(ud, /MEDUSA_GDS_ONLY=1/);
+});
+
+console.log('\nport allocation:');
+
+t('nextFreePort skips reserved + taken, returns the lowest free ≥ base', () => {
+  assert.equal(P.nextFreePort([], { portBase: 3003, reserved: [3000, 3001, 3002] }), 3003);
+  assert.equal(P.nextFreePort([3003, 3004], { portBase: 3003, reserved: [3000, 3001, 3002] }), 3005);
+  assert.equal(P.nextFreePort([3005], { portBase: 3003, reserved: [3003] }), 3004);
+});
+
+t('boundLocalPorts parses ss output — skips header, handles wildcard + IPv6, degrades safely', () => {
+  const exec = () => ({ ok: true, stdout:
+    'State  Recv-Q Send-Q Local Address:Port Peer Address:Port Process\n' +
+    'LISTEN 0      4096   127.0.0.1:3003     0.0.0.0:*\n' +
+    'LISTEN 0      511    127.0.0.1:3002     0.0.0.0:*\n' +
+    'LISTEN 0      128    0.0.0.0:22         0.0.0.0:*\n' +
+    'LISTEN 0      128    [::1]:3000         [::]:*\n' });
+  assert.deepEqual(P.boundLocalPorts(exec).sort((a, b) => a - b), [22, 3000, 3002, 3003]);
+  assert.deepEqual(P.boundLocalPorts(null), []);                                     // no exec → safe empty
+  assert.deepEqual(P.boundLocalPorts(() => { throw new Error('ss missing'); }), []); // ss unavailable → safe empty
+});
+
+await ta('allocatePort excludes OS-bound ports (regression: Grafana squatting :3003 on the co-located control plane, task 2070)', async () => {
+  const db = { query: async () => ({ rows: [{ port: 3004 }] }) };                    // an existing instance already on 3004
+  const grafanaOn3003 = () => ({ ok: true, stdout: 'LISTEN 0 4096 127.0.0.1:3003 0.0.0.0:*\n' });
+  // reserved 3000-3002 + instance 3004 + OS-bound 3003 → lowest free ≥ base is 3005
+  assert.equal(await P.allocatePort(db, null, { exec: grafanaOn3003 }), 3005);
+  // WITHOUT the OS view the allocator would hand out 3003 → the exact EADDRINUSE collision this fixes
+  assert.equal(await P.allocatePort(db, null), 3003);
+});
+
+console.log('\nco-tenant composition (dry-run, recording fakes):');
+
+// A recording harness: exec + writeFile capture what the runbook WOULD do; db is a
+// fake whose only query (allocatePort) returns no rows; provisioning is a no-op
+// (apply:false skips the status writes anyway).
+function recorder({ apply = false } = {}) {
+  const cmds = [], writes = [], statuses = [];
+  const deps = {
+    apply, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: {
+      setInstanceStatus: async (_db, _id, s) => { statuses.push(s); },
+      recordEvent: async () => {},
+      getInstanceBySlug: async () => null,
+      claimNextIntent: async () => null,
+      resolveIntent: async () => {},
+      enqueueIntent: async () => ({ created: true }),
+      getInstanceById: async () => null,
+    },
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: '' }; },
+    writeFile: (p) => { writes.push(p); return { ok: true }; },
+    doApi: null,
+    // Stub the DNS token-scope preflight (task 1980) so the composition stays hermetic
+    // (no real CF call). Default: reachable; a test overrides it to exercise the block.
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+  };
+  return { deps, cmds, writes, statuses };
+}
+
+await ta('provisionInstance(co-tenant) composes db → migrate → service → healthz in order', async () => {
+  const { deps, cmds, writes } = recorder();
+  const r = await P.provisionInstance(coTenant, deps);
+  assert.equal(r.ok, true);
+  // the runbook command sequence
+  const joined = cmds.join('\n');
+  assert.match(joined, /createdb mercury/);
+  assert.match(joined, /MEDUSA_GDS_ONLY=1/);
+  assert.match(joined, /systemctl daemon-reload/);
+  assert.match(joined, /systemctl enable --now mercury/);
+  assert.match(joined, /healthz/);
+  // ordering: createdb before migrate before enable before healthz
+  const idx = (re) => cmds.findIndex((c) => re.test(c));
+  assert.ok(idx(/createdb/) < idx(/migrate\.sh/), 'createdb before migrate');
+  assert.ok(idx(/migrate\.sh/) < idx(/enable --now/), 'migrate before service enable');
+  assert.ok(idx(/enable --now/) < idx(/healthz/), 'service before healthz');
+  // writes: the per-instance env file + the systemd unit
+  assert.ok(writes.some((w) => /\/mercury\/web\.env$/.test(w)), 'wrote web.env');
+  assert.ok(writes.some((w) => /\/mercury\.service$/.test(w)), 'wrote systemd unit');
+  assert.ok(writes.some((w) => /\/mercury\.caddy$/.test(w)), 'wrote per-instance Caddy snippet');
+});
+
+await ta('provisionInstance(standalone) SCAFFOLDS its repo, then syncs (pull + npm ci) + migrates from the instance root', async () => {
+  const { deps, cmds, writes } = recorder();
+  const r = await P.provisionInstance({ ...coTenant, hosting_shape: 'standalone', target_ref: 'lars589/mercury' }, deps);
+  assert.equal(r.ok, true);
+  const joined = cmds.join('\n');
+  // scaffold leg (task 2055): clone → package-core → init --vendor-core → push
+  assert.match(joined, /git clone git@github-deploy:lars589\/mercury\.git/, 'clones the instance repo');
+  assert.match(joined, /node scripts\/gds\/package-core\.js/, 'builds the core tarball');
+  assert.match(joined, /init\.js --from .* --dir .* --no-seed --force --vendor-core /, 'materializes + file:-pins the core');
+  assert.match(joined, /git -C .* push -u origin main/, 'pushes the scaffold');
+  // then the code sync + migrate
+  assert.match(joined, /git pull --ff-only origin main/, 'pulls the instance repo');
+  assert.match(joined, /npm ci --omit=dev/, 'installs the pinned core');
+  assert.match(joined, /createdb mercury/);
+  assert.match(joined, /node_modules\/@cloudbongos\/core\/scripts\/migrate\.sh/, 'migrates from the INSTANCE root\'s core');
+  assert.ok(!cmds.some((c) => /\.\/scripts\/migrate\.sh/.test(c)), 'standalone does NOT use the control-plane checkout migrate');
+  // ordering: clone → package-core → init → push → pull → npm ci → migrate → service
+  const idx = (re) => cmds.findIndex((c) => re.test(c));
+  assert.ok(idx(/git clone/) < idx(/package-core/), 'clone before tarball build');
+  assert.ok(idx(/package-core/) < idx(/init\.js/), 'tarball before init');
+  assert.ok(idx(/init\.js/) < idx(/push -u origin main/), 'init before push');
+  assert.ok(idx(/push -u origin main/) < idx(/git pull/), 'scaffold push before the deploy pull');
+  assert.ok(idx(/git pull/) < idx(/npm ci/), 'pull before npm ci');
+  assert.ok(idx(/npm ci/) < idx(/migrate\.sh/), 'npm ci before migrate');
+  assert.ok(idx(/migrate\.sh/) < idx(/enable --now/), 'migrate before service enable');
+  assert.ok(writes.some((w) => /\/mercury\.service$/.test(w)), 'wrote the (standalone) systemd unit');
+});
+
+// ── standalone scaffold helpers + guards (task 2055) ──────────────────────────
+t('parseTargetRef: owner/repo, SSH + HTTPS URLs, .git suffix; garbage → null', () => {
+  assert.deepEqual(P.parseTargetRef('lars589/demo'), { owner: 'lars589', name: 'demo' });
+  assert.deepEqual(P.parseTargetRef('git@github-deploy:lars589/demo.git'), { owner: 'lars589', name: 'demo' });
+  assert.deepEqual(P.parseTargetRef('https://github.com/lars589/demo.git'), { owner: 'lars589', name: 'demo' });
+  assert.equal(P.parseTargetRef('garbage'), null);
+  assert.equal(P.parseTargetRef(''), null);
+  assert.equal(P.parseTargetRef(null), null);
+});
+
+t('instanceRepoRemote: reuses the SSH deploy alias (no secret in the URL); alias overridable', () => {
+  assert.equal(P.instanceRepoRemote({ owner: 'lars589', name: 'demo' }), 'git@github-deploy:lars589/demo.git');
+  assert.equal(P.instanceRepoRemote({ owner: 'o', name: 'r' }, { sshAlias: 'gh-alt' }), 'git@gh-alt:o/r.git');
+});
+
+t('instanceInitSpec: builds a VALID greenfield init spec from the row + owner login', () => {
+  const spec = P.instanceInitSpec(
+    { slug: 'demo', target_ref: 'lars589/demo', domain: 'demo.cloudbongos.com', port: 3003 },
+    { ownerLogin: 'lars589' },
+  );
+  assert.equal(spec.identity.productName, 'demo');
+  assert.deepEqual(spec.repo, { owner: 'lars589', name: 'demo' });
+  assert.equal(spec.firstAdmin, 'lars589');
+  assert.equal(spec.domains.publicOrigin, 'https://demo.cloudbongos.com');
+  // it must satisfy init.validateSpec (greenfield) — the scaffold feeds it to `bongos init`
+  const init = require('../scripts/gds/init.js');
+  assert.deepEqual(init.validateSpec(init.normalizeSpec(spec)), [], 'spec passes greenfield validation');
+});
+
+t('instanceInitSpec: falls back to the repo owner as firstAdmin when no owner login', () => {
+  const spec = P.instanceInitSpec({ slug: 'demo', target_ref: 'acme/demo' }, {});
+  assert.equal(spec.firstAdmin, 'acme');
+});
+
+await ta('scaffoldStandaloneRepo: refuses when target_ref is not owner/repo', async () => {
+  const { deps } = recorder({ apply: true });
+  await assert.rejects(
+    () => P.scaffoldStandaloneRepo({ slug: 'demo', hosting_shape: 'standalone', target_ref: null }, deps),
+    /target_ref .* is not an owner\/repo/,
+  );
+});
+
+await ta('scaffoldStandaloneRepo: idempotent — a repo that already carries package.json is skipped', async () => {
+  const tmp = mkdtempSync(join(tmpdir(), 'scaffold-'));
+  const origBase = P.CONFIG.standaloneBase;
+  P.CONFIG.standaloneBase = tmp;               // standaloneRoot() reads CONFIG.standaloneBase at call time
+  try {
+    mkdirSync(join(tmp, 'demo'), { recursive: true });
+    writeFileSync(join(tmp, 'demo', 'package.json'), '{}\n');   // sign of a completed scaffold
+    const { deps, cmds } = recorder({ apply: true });
+    const res = await P.scaffoldStandaloneRepo({ slug: 'demo', hosting_shape: 'standalone', target_ref: 'lars589/demo' }, deps);
+    assert.equal(res.already, true);
+    assert.equal(cmds.length, 0, 'no clone/build/push when already scaffolded');
+  } finally {
+    P.CONFIG.standaloneBase = origBase;
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+await ta('provisionInstance is idempotent: an already-active instance is a no-op', async () => {
+  const { deps, cmds } = recorder();
+  const r = await P.provisionInstance({ ...coTenant, status: 'active' }, deps);
+  assert.equal(r.already, true);
+  assert.equal(cmds.length, 0, 'no commands run for an active instance');
+});
+
+await ta('provisionInstance(dedicated) does NOT run local createdb/migrate (they ride cloud-init)', async () => {
+  const { deps, cmds } = recorder();
+  await P.provisionInstance({ ...coTenant, hosting_shape: 'dedicated', tier: 's-2vcpu-4gb' }, deps);
+  assert.ok(!cmds.some((c) => /createdb/.test(c)), 'dedicated does not run createdb locally');
+});
+
+console.log('\nDNS UPSERT composition (P4, CONFIG override):');
+
+// A recorder that also captures each exec's env (so we can assert the DNS hook env).
+function dnsRecorder({ apply = false } = {}) {
+  const cmds = [], envs = [];
+  const deps = {
+    apply, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+    exec: (cmd, opts) => { cmds.push(cmd); envs.push(opts && opts.env); return { ok: true, stdout: '' }; },
+    writeFile: () => ({ ok: true }), doApi: null,
+    // Preflight (task 1980) stubbed reachable so --apply DNS tests reach the step-5
+    // behavior they assert (the preflight itself is covered by its own test below).
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+  };
+  return { deps, cmds, envs };
+}
+
+await ta('a co-tenant WITH a domain UPSERTs DNS: the hook is invoked BY PATH with the control-plane env (proxied=false)', async () => {
+  const savedIp = P.CONFIG.publicIp, savedHook = P.CONFIG.dnsHook;
+  P.CONFIG.publicIp = '203.0.113.5';
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps, cmds, envs } = dnsRecorder();
+    await P.provisionInstance({ ...coTenant, domain: 'mercury.example.com' }, deps);
+    const i = cmds.indexOf('/opt/infra/box-dns-cloudflare.sh');
+    assert.ok(i >= 0, 'dns hook invoked by path (not string-interpolated)');
+    assert.equal(envs[i].BOX_HOSTNAME, 'mercury.example.com');
+    assert.equal(envs[i].BOX_IP, '203.0.113.5');
+    assert.equal(envs[i].CLOUDFLARE_ZONE, 'example.com');
+    assert.equal(envs[i].BOX_PROXIED, '0', 'co-tenant stays UNPROXIED — its on-demand ACME challenge must reach the origin (task 2077 only proxies standalone)');
+  } finally { P.CONFIG.publicIp = savedIp; P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('--apply THROWS if a domain has no target IP (task-1180: never report success on a silent DNS skip)', async () => {
+  const savedIp = P.CONFIG.publicIp, savedHook = P.CONFIG.dnsHook;
+  P.CONFIG.publicIp = null;
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps } = dnsRecorder({ apply: true });
+    await assert.rejects(
+      () => P.provisionInstance({ ...coTenant, domain: 'mercury.example.com' }, deps),
+      /no target IP|PROVISION_PUBLIC_IP/,
+    );
+  } finally { P.CONFIG.publicIp = savedIp; P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('no domain → DNS is skipped even with a hook + IP configured', async () => {
+  const savedIp = P.CONFIG.publicIp, savedHook = P.CONFIG.dnsHook;
+  P.CONFIG.publicIp = '203.0.113.5';
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps, cmds } = dnsRecorder();
+    await P.provisionInstance({ ...coTenant, domain: null }, deps);
+    assert.ok(!cmds.includes('/opt/infra/box-dns-cloudflare.sh'), 'no DNS hook without a domain');
+  } finally { P.CONFIG.publicIp = savedIp; P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('provisionInstance(--apply) FAILS FAST when the DNS token can\'t reach the zone (task 1980 preflight)', async () => {
+  const savedHook = P.CONFIG.dnsHook; P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps, cmds } = dnsRecorder({ apply: true });
+    deps.checkDnsTokenScope = async () => ({ reachable: false, zone: 'newproject.com', reason: 'not in scope', guidance: 'widen the token' });
+    await assert.rejects(
+      () => P.provisionInstance({ ...coTenant, domain: 'app.newproject.com' }, deps),
+      /DNS preflight failed.*widen the token/,
+      'a non-reachable token must fail the provision up front',
+    );
+    assert.ok(!cmds.some((c) => /createdb/.test(c)), 'nothing is provisioned when the preflight fails');
+  } finally { P.CONFIG.dnsHook = savedHook; }
+});
+
+console.log('\nintent drain loop:');
+
+await ta('cmdRunIntents (dry-run) lists the pending queue, runs nothing', async () => {
+  const deps = {
+    apply: false, log: () => {},
+    db: { query: async () => ({ rows: [{ id: 1, action: 'provision', slug: 'mercury', attempts: 0 }] }) },
+    provisioning: {}, exec: () => {}, writeFile: () => {},
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.ran, 0);
+});
+
+await ta('cmdRunIntents (--apply) claims → provisions → resolves the intent done', async () => {
+  let claims = 0; const resolved = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0 ? { id: 5, instance_id: 1, action: 'provision', attempts: 1 } : null),
+      getInstanceById: async () => ({ ...coTenant }),
+      resolveIntent: async (_db, id, state) => { resolved.push({ id, state }); },
+      setInstanceStatus: async () => {},
+      recordEvent: async () => {},
+      // The same tick also drains the GitHub-App-Manifest conversion queue (task 2080);
+      // nothing awaiting conversion here → a clean no-op.
+      claimNextOAuthManifest: async () => null,
+      resolveOAuthManifest: async () => {},
+    },
+    exec: () => ({ ok: true }), writeFile: () => ({ ok: true }), doApi: null,
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.ran, 1);
+  assert.equal(r.ok, 1);
+  assert.deepEqual(resolved, [{ id: 5, state: 'done' }]);
+  assert.deepEqual(r.manifests, { converted: 0, errors: 0 }, 'the manifest drain ran with nothing to do');
+});
+
+console.log('\nGitHub App Manifest conversion + placement (task 2080, ADR 0133):');
+
+t('webEnvBody fills the OAuth cred lines when creds are given; blank placeholders otherwise', () => {
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  const blank = P.webEnvBody(inst);
+  assert.match(blank, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=\\n`), 'blank id line by default');
+  const filled = P.webEnvBody(inst, { clientId: 'Iv1.abc123def456ghi7', clientSecret: 's'.repeat(40) });
+  assert.match(filled, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_ID=Iv1\\.abc123def456ghi7`));
+  assert.match(filled, new RegExp(`${reEsc(NEUTRAL_PREFIX)}_GITHUB_CLIENT_SECRET=s{40}`));
+});
+
+await ta('convertManifestCode POSTs the unauthenticated conversion endpoint + maps the response', async () => {
+  let calledUrl = '', calledInit = null;
+  const fetchImpl = async (url, init) => {
+    calledUrl = url; calledInit = init;
+    return { ok: true, text: async () => JSON.stringify({ id: 42, slug: 'mercury-signin', client_id: 'Iv1.abcdef0123456789', client_secret: 'x'.repeat(40) }) };
+  };
+  const creds = await P.convertManifestCode('THECODE', { fetchImpl });
+  assert.equal(calledUrl, 'https://api.github.com/app-manifests/THECODE/conversions');
+  assert.equal(calledInit.method, 'POST');
+  assert.ok(calledInit.headers['User-Agent'], 'stamps a User-Agent (GitHub requires one)');
+  assert.ok(!('Authorization' in calledInit.headers), 'unauthenticated — the code IS the auth');
+  assert.deepEqual(creds, { clientId: 'Iv1.abcdef0123456789', clientSecret: 'x'.repeat(40), appId: 42, appSlug: 'mercury-signin' });
+});
+
+await ta('convertManifestCode throws on a non-2xx or a creds-less response', async () => {
+  const bad = async () => ({ ok: false, text: async () => JSON.stringify({ message: 'code expired' }) });
+  await assert.rejects(P.convertManifestCode('X', { fetchImpl: bad }), /code expired/);
+  const empty = async () => ({ ok: true, text: async () => JSON.stringify({ id: 1 }) });
+  await assert.rejects(P.convertManifestCode('X', { fetchImpl: empty }), /no client_id/);
+});
+
+await ta('placeManifestCreds (--apply): converts, rewrites web.env with the creds, restarts, verifies /healthz', async () => {
+  const inst = { ...coTenant, hosting_shape: 'co-tenant', domain: 'mercury.example.com' };
+  const writes = []; const cmds = [];
+  const deps = {
+    apply: true, privileged: false, log: () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 9, appSlug: 'm-signin' }),
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: '{"ok":true,"auth_configured":true}' }; },
+    writeFile: (p, body) => { writes.push({ p, body }); return { ok: true }; },
+  };
+  const r = await P.placeManifestCreds(inst, { github_code: 'CODE', attempts: 1 }, deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.appSlug, 'm-signin');
+  // web.env rewritten WITH the creds
+  const env = writes.find((w) => /web\.env$/.test(w.p));
+  assert.ok(env, 'web.env was written');
+  assert.match(env.body, /_GITHUB_CLIENT_SECRET=z{40}/);
+  // the unit was restarted, and /healthz was probed
+  assert.ok(cmds.some((c) => /systemctl restart mercury/.test(c)), 'restarts the unit');
+  assert.ok(cmds.some((c) => /\/healthz/.test(c)), 'probes healthz');
+});
+
+await ta('placeManifestCreds rejects a dedicated droplet (no post-hoc exec path) and creds-less rows', async () => {
+  const deps = { apply: true, log: () => {}, exec: () => ({ ok: true }), writeFile: () => ({}) };
+  const ded = await P.placeManifestCreds({ ...coTenant, hosting_shape: 'dedicated', domain: 'd.example.com' }, { github_code: 'C' }, deps);
+  assert.equal(ded.ok, false); assert.match(ded.error, /dedicated/);
+  const noCode = await P.placeManifestCreds({ ...coTenant, domain: 'm.example.com' }, {}, deps);
+  assert.equal(noCode.ok, false); assert.match(noCode.error, /no github_code/);
+});
+
+await ta('placeManifestCreds fails when /healthz never reports auth_configured (never claims success)', async () => {
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  const deps = {
+    apply: true, privileged: false, log: () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 1, appSlug: 's' }),
+    exec: () => ({ ok: true, stdout: '{"ok":true,"auth_configured":false}' }),
+    writeFile: () => ({ ok: true }),
+  };
+  const r = await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, deps);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /auth_configured=false/);
+});
+
+await ta('drainOAuthManifests (--apply): claims a code_received row, places creds, resolves done', async () => {
+  let claims = 0; const resolved = []; const events = [];
+  const deps = {
+    apply: true, privileged: false, log: () => {},
+    db: {}, exec: () => ({ ok: true, stdout: '{"auth_configured":true}' }), writeFile: () => ({ ok: true }),
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 3, appSlug: 'app-3' }),
+    provisioning: {
+      claimNextOAuthManifest: async () => (claims++ === 0 ? { id: 11, instance_id: 1, github_code: 'CODE', attempts: 1 } : null),
+      getInstanceById: async () => ({ ...coTenant, hosting_shape: 'co-tenant', domain: 'mercury.example.com' }),
+      resolveOAuthManifest: async (_db, id, status, patch) => { resolved.push({ id, status, patch }); },
+      recordEvent: async (_db, e) => { events.push(e.event); },
+    },
+  };
+  const r = await P.drainOAuthManifests(deps);
+  assert.deepEqual(r, { converted: 1, errors: 0 });
+  assert.equal(resolved.length, 1);
+  assert.equal(resolved[0].status, 'done');
+  assert.equal(resolved[0].patch.app_slug, 'app-3');
+  assert.ok(events.includes('oauth-manifest-done'));
+});
+
+console.log('\nprivileged mode (PROVISION_SUDO — task 2066):');
+
+t('dbCreateCmd: privileged runs createdb as the postgres role; default is bare (peer auth)', () => {
+  assert.equal(P.dbCreateCmd(coTenant), 'createdb mercury');
+  assert.equal(P.dbCreateCmd(coTenant, { privileged: false }), 'createdb mercury');
+  assert.equal(P.dbCreateCmd(coTenant, { privileged: true }), 'sudo -u postgres createdb mercury');
+});
+
+t('migrateCmd: privileged runs migrate as postgres via env+bash (survives sudo env reset); default unchanged', () => {
+  assert.equal(P.migrateCmd(coTenant), 'PGDATABASE=mercury MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh');
+  const priv = P.migrateCmd(coTenant, { privileged: true });
+  assert.equal(priv, 'sudo -u postgres env PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash ./scripts/migrate.sh');
+  // A bare `sudo -u postgres VAR=val ./script` would have sudo treat VAR=val as a
+  // command — the env MUST ride `env …` and the script run via `bash …`.
+  assert.doesNotMatch(priv, /sudo -u postgres PGDATABASE=/);
+});
+
+t('standaloneMigrateCmd: privileged runs the instance-root migrate as postgres; default unchanged', () => {
+  const inst = { ...coTenant, hosting_shape: 'standalone' };
+  assert.equal(P.standaloneMigrateCmd(inst), 'PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash node_modules/@cloudbongos/core/scripts/migrate.sh');
+  assert.equal(P.standaloneMigrateCmd(inst, { privileged: true }), 'sudo -u postgres env PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash node_modules/@cloudbongos/core/scripts/migrate.sh');
+});
+
+t('makeWriteFile(privileged): a { sudo:true } write stages a temp file + `sudo install -D -m <mode>` (never writes /etc directly)', () => {
+  const cmds = [];
+  const exec = (cmd) => { cmds.push(cmd); return { ok: true }; };
+  const wf = P.makeWriteFile({ apply: true, privileged: true, exec, log: () => {} });
+  const dest = '/etc/mercury/web.env';               // NEVER actually written (install is the fake exec)
+  const r = wf(dest, 'PORT=3003\n', { mode: 0o600, sudo: true });
+  assert.equal(r.ok, true);
+  assert.equal(cmds.length, 1, 'the write is a single sudo install');
+  // temp file (lars-writable) → atomic root placement with -D (creates /etc/mercury/) + mode.
+  assert.match(cmds[0], /^sudo install -D -m 600 .+ \/etc\/mercury\/web\.env$/);
+  const tmp = cmds[0].split(' ')[5];                 // sudo install -D -m 600 <tmp> <dest>
+  assert.ok(tmp.startsWith(tmpdir()), 'temp file staged under the OS tmpdir, not /etc');
+  assert.ok(!existsSync(tmp), 'temp file cleaned up after the install');
+  assert.ok(!existsSync(dest), 'the /etc destination is placed by install, never fs.writeFileSync');
+});
+
+t('makeWriteFile(privileged): a NON-sudo write (scaffold temp / .gitignore) still writes directly, no exec', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'wf-'));
+  const exec = () => { throw new Error('exec must not be called for a direct write'); };
+  const wf = P.makeWriteFile({ apply: true, privileged: true, exec, log: () => {} });
+  const p = join(dir, 'sub', 'file.json');           // parent dir does not exist yet
+  wf(p, '{}\n');                                      // no { sudo:true } → direct fs write (mkdir -p)
+  assert.equal(readFileSync(p, 'utf8'), '{}\n');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+t('makeWriteFile(non-privileged): a { sudo:true } write falls back to a direct fs write (knob off → no sudo)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'wf-'));
+  const exec = () => { throw new Error('no exec — non-privileged writes go direct'); };
+  const wf = P.makeWriteFile({ apply: true, privileged: false, exec, log: () => {} });
+  const p = join(dir, 'web.env');
+  wf(p, 'PORT=1\n', { mode: 0o600, sudo: true });
+  assert.equal(readFileSync(p, 'utf8'), 'PORT=1\n');
+  rmSync(dir, { recursive: true, force: true });
+});
+
+// A recorder for the privileged path: captures each exec string + each writeFile's
+// (path, opts), so we can assert the sudo shapes AND that the /etc writes opt into
+// escalation. Mirrors recorder() but with privileged:true (and opts-capturing writes).
+function privRecorder({ apply = false } = {}) {
+  const cmds = [], writes = [];
+  const deps = {
+    apply, privileged: true, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: '' }; },
+    writeFile: (p, _body, opts) => { writes.push({ p, opts: opts || {} }); return { ok: true }; },
+    doApi: null,
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+  };
+  return { deps, cmds, writes };
+}
+
+await ta('provisionInstance(co-tenant, privileged): createdb/migrate run as postgres, systemctl is sudo-prefixed, /etc writes request escalation', async () => {
+  const { deps, cmds, writes } = privRecorder();
+  await P.provisionInstance(coTenant, deps);
+  const joined = cmds.join('\n');
+  assert.match(joined, /sudo -u postgres createdb mercury/, 'createdb as postgres');
+  assert.match(joined, /sudo -u postgres env PGDATABASE=mercury MEDUSA_GDS_ONLY=1 bash \.\/scripts\/migrate\.sh/, 'migrate as postgres');
+  assert.match(joined, /sudo systemctl daemon-reload/, 'daemon-reload sudo-prefixed');
+  assert.match(joined, /sudo systemctl enable --now mercury/, 'enable sudo-prefixed');
+  assert.match(joined, /sudo systemctl reload caddy/, 'reload caddy sudo-prefixed');
+  // the three /etc writes must opt into escalation (sudo:true) so makeWriteFile installs them.
+  for (const suffix of ['/mercury/web.env', '/mercury.service', '/mercury.caddy']) {
+    const w = writes.find((x) => x.p.endsWith(suffix));
+    assert.ok(w, `wrote ${suffix}`);
+    assert.equal(w.opts.sudo, true, `${suffix} requests sudo escalation`);
+  }
+});
+
+await ta('provisionInstance(co-tenant, default): NO sudo anywhere (bare commands — co-tenant/root/test unaffected)', async () => {
+  const { deps, cmds } = recorder();                 // recorder() sets no privileged flag → falsy
+  await P.provisionInstance(coTenant, deps);
+  assert.ok(!cmds.some((c) => /(^|\s)sudo(\s|$)/.test(c)), 'no sudo in the non-privileged composition');
+  assert.ok(cmds.includes('createdb mercury'), 'bare createdb (peer auth)');
+});
+
+await ta('teardownInstance(privileged): systemctl + rm-under-/etc are sudo-prefixed', async () => {
+  const { deps, cmds } = privRecorder();
+  await P.teardownInstance(coTenant, deps);
+  const joined = cmds.join('\n');
+  assert.match(joined, /sudo systemctl disable --now mercury/);
+  assert.match(joined, /sudo rm -f \/etc\/systemd\/system\/mercury\.service/);
+  assert.match(joined, /sudo systemctl daemon-reload/);
+});
+
+await ta('teardownInstance(default): NO sudo (bare, unchanged)', async () => {
+  const { deps, cmds } = recorder();
+  await P.teardownInstance(coTenant, deps);
+  assert.ok(!cmds.some((c) => /(^|\s)sudo(\s|$)/.test(c)), 'no sudo when the knob is off');
+});
+
+// ── remote-exec over SSH (task 2065, ADR 0130) ─────────────────────────────
+console.log('\nremote orchestration over SSH (task 2065):');
+
+t('makeExec(remoteHost): a step is ssh-wrapped and cd\'s to the remote checkout (dry-run)', () => {
+  const logs = [];
+  const run = P.makeExec({ apply: false, log: (m) => logs.push(m), remoteHost: 'lars@10.0.0.9', remoteCwd: '/home/lars/amazonprimea', sshOpts: '-o BatchMode=yes' });
+  run('createdb mercury');
+  const line = logs.join('\n');
+  assert.match(line, /\[ssh lars@10\.0\.0\.9\]/, 'shows the ssh target');
+  assert.match(line, /cd \/home\/lars\/amazonprimea && createdb mercury/, 'cd to the remote checkout, then the command');
+});
+
+t('makeExec(remoteHost): explicit cwd overrides the default; env is composed INTO the remote script (crosses the ssh hop)', () => {
+  const logs = [];
+  const run = P.makeExec({ apply: false, log: (m) => logs.push(m), remoteHost: 'host', remoteCwd: '/default' });
+  run('./scripts/migrate.sh', { cwd: '/srv/x', env: { PGDATABASE: 'x' } });
+  const line = logs.join('\n');
+  assert.match(line, /cd \/srv\/x && PGDATABASE=x \.\/scripts\/migrate\.sh/, 'explicit cwd + env prefix inside the remote script');
+});
+
+t('makeExec(no remoteHost): a step runs locally, never ssh-wrapped (default, unchanged)', () => {
+  const logs = [];
+  const run = P.makeExec({ apply: false, log: (m) => logs.push(m) });
+  run('createdb mercury');
+  const line = logs.join('\n');
+  assert.doesNotMatch(line, /\[ssh/, 'no ssh wrapping when remoteHost is unset');
+  assert.match(line, /would run: createdb mercury/);
+});
+
+t('makeWriteFile(remoteHost): a sudo write base64-pipes the body to `sudo tee` on the box via exec (no raw secret, no local fs write)', () => {
+  const cmds = [];
+  const exec = (cmd) => { cmds.push(cmd); return { ok: true }; };
+  const wf = P.makeWriteFile({ apply: true, privileged: true, exec, remoteHost: 'host', log: () => {} });
+  wf('/etc/mercury/web.env', 'SECRET=hunter2\n', { mode: 0o600, sudo: true });
+  assert.equal(cmds.length, 1, 'exactly one remote command (no local fs write)');
+  const c = cmds[0];
+  assert.match(c, /sudo mkdir -p \/etc\/mercury/, 'creates the parent dir as root');
+  assert.match(c, /base64 -d \| sudo tee \/etc\/mercury\/web\.env/, 'decodes + tees into place as root');
+  assert.match(c, /sudo chmod 600 \/etc\/mercury\/web\.env/, 'applies the mode as root');
+  assert.doesNotMatch(c, /hunter2/, 'the raw secret is base64-encoded, never inlined');
+});
+
+await ta('provisionInstance(co-tenant, remote): box steps use the box `exec`, but the DNS hook uses `controlExec` — the token step never crosses to the box', async () => {
+  const savedIp = P.CONFIG.publicIp, savedHook = P.CONFIG.dnsHook;
+  P.CONFIG.publicIp = '203.0.113.5';                       // the CO-HOSTING box's IP (task 2065: point PROVISION_PUBLIC_IP at where the co-tenant runs)
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const box = [], control = [];
+    const deps = {
+      apply: false, log: () => {},
+      db: { query: async () => ({ rows: [] }) },
+      provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+      exec: (cmd) => { box.push(cmd); return { ok: true, stdout: '' }; },
+      controlExec: (cmd) => { control.push(cmd); return { ok: true, stdout: '' }; },
+      writeFile: () => ({ ok: true }),
+      controlWriteFile: () => ({ ok: true }),
+      doApi: null,
+      checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+    };
+    await P.provisionInstance({ ...coTenant, domain: 'mercury.example.com' }, deps);
+    // box-mutating steps → the box executor (which, in prod, ssh's to the co-hosting box)
+    assert.ok(box.some((c) => /createdb/.test(c)), 'createdb via the box exec');
+    assert.ok(box.some((c) => /migrate\.sh/.test(c)), 'migrate via the box exec');
+    assert.ok(box.some((c) => /systemctl enable --now/.test(c)), 'systemctl via the box exec');
+    assert.ok(box.some((c) => /healthz/.test(c)), 'healthz via the box exec');
+    // the DNS hook (needs the Cloudflare token) → the control executor, NEVER the box
+    assert.ok(control.includes('/opt/infra/box-dns-cloudflare.sh'), 'DNS hook ran on the control executor');
+    assert.ok(!box.includes('/opt/infra/box-dns-cloudflare.sh'), 'DNS hook NEVER on the box exec — the token stays on the control plane');
+  } finally { P.CONFIG.publicIp = savedIp; P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('provisionInstance(standalone, remote): EVERY box step runs control-plane-local — nothing crosses to the co-hosting box; the A record points at the control plane (task 2074)', async () => {
+  const savedPub = P.CONFIG.publicIp, savedCp = P.CONFIG.controlPlaneIp, savedHook = P.CONFIG.dnsHook, savedRemote = P.CONFIG.remoteHost;
+  P.CONFIG.remoteHost = 'cohost';              // remote-exec mode: co-tenant steps WOULD go to the co-hosting box
+  P.CONFIG.publicIp = '104.236.254.243';       // the co-hosting box's IP (where co-tenants run)
+  P.CONFIG.controlPlaneIp = '161.35.132.201';  // the control plane's OWN IP (where a standalone runs)
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const box = [], control = [], boxWrites = [], controlWrites = [], dnsEnvs = [];
+    const deps = {
+      apply: false, log: () => {},
+      db: { query: async () => ({ rows: [] }) },
+      provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+      exec: (cmd) => { box.push(cmd); return { ok: true, stdout: '' }; },                       // the REMOTE (co-hosting box) executor
+      controlExec: (cmd, opts) => { control.push(cmd); if (opts && opts.env) dnsEnvs.push({ cmd, env: opts.env }); return { ok: true, stdout: '' }; },
+      writeFile: (p) => { boxWrites.push(p); return { ok: true }; },                            // the REMOTE writer
+      controlWriteFile: (p) => { controlWrites.push(p); return { ok: true }; },                 // the control-plane writer
+      doApi: null,
+      checkDnsTokenScope: async () => ({ reachable: true, zone: 'cloudbongos.com' }),
+    };
+    await P.provisionInstance({ ...coTenant, hosting_shape: 'standalone', target_ref: 'lars589/mercury', domain: 'mercury.cloudbongos.com' }, deps);
+    // The bug (task 2074): these landed on the REMOTE box, which never had the scaffolded
+    // dir. They must ALL be on the control-plane executor now.
+    for (const re of [/git pull --ff-only/, /npm ci/, /createdb mercury/, /migrate\.sh/, /systemctl enable --now/, /systemctl reload caddy/, /healthz/]) {
+      assert.ok(control.some((c) => re.test(c)), `${re} runs on the control-plane executor`);
+      assert.ok(!box.some((c) => re.test(c)), `${re} does NOT cross to the co-hosting box`);
+    }
+    // The scaffold leg was already control-local; confirm it stayed there.
+    assert.ok(control.some((c) => /git clone /.test(c)) && control.some((c) => /push -u origin main/.test(c)), 'scaffold clone+push stay control-local');
+    // NOTHING crosses to the remote box for a standalone — the whole point of the fix.
+    assert.equal(box.length, 0, 'zero remote (co-hosting box) commands for a standalone');
+    assert.equal(boxWrites.length, 0, 'zero remote writes for a standalone');
+    // writes (web.env, systemd unit, caddy snippet) all go to the control-plane writer.
+    assert.ok(controlWrites.some((w) => /\/mercury\/web\.env$/.test(w)), 'web.env written control-local');
+    assert.ok(controlWrites.some((w) => /\/mercury\.service$/.test(w)), 'systemd unit written control-local');
+    assert.ok(controlWrites.some((w) => /\/mercury\.caddy$/.test(w)), 'caddy snippet written control-local');
+    // DNS: the A record points at the CONTROL PLANE's IP (not the co-hosting box's publicIp).
+    const dns = dnsEnvs.find((e) => e.cmd === '/opt/infra/box-dns-cloudflare.sh');
+    assert.ok(dns, 'DNS hook ran on the control executor');
+    assert.equal(dns.env.BOX_IP, '161.35.132.201', 'A record → the control-plane IP, NOT the co-hosting box');
+    assert.equal(dns.env.BOX_PROXIED, '1', 'standalone A record is PROXIED (behind the wildcard origin cert; task 2077) — publicly-trusted cert + hidden IP');
+  } finally { P.CONFIG.publicIp = savedPub; P.CONFIG.controlPlaneIp = savedCp; P.CONFIG.dnsHook = savedHook; P.CONFIG.remoteHost = savedRemote; }
+});
+
+await ta('provisionInstance(standalone, remote, --apply): FAILS LOUD when the control-plane IP is unset (never silently points the domain at the co-hosting box)', async () => {
+  const savedPub = P.CONFIG.publicIp, savedCp = P.CONFIG.controlPlaneIp, savedHook = P.CONFIG.dnsHook, savedRemote = P.CONFIG.remoteHost;
+  P.CONFIG.remoteHost = 'cohost';              // split-box mode
+  P.CONFIG.publicIp = '104.236.254.243';       // co-hosting box — must NOT be used for a standalone A record
+  P.CONFIG.controlPlaneIp = null;              // operator forgot to set it
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const deps = {
+      apply: true, log: () => {},
+      db: { query: async () => ({ rows: [] }) },
+      provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+      exec: () => ({ ok: true, stdout: '' }), controlExec: () => ({ ok: true, stdout: '' }),
+      writeFile: () => ({ ok: true }), controlWriteFile: () => ({ ok: true }), doApi: null,
+      checkDnsTokenScope: async () => ({ reachable: true, zone: 'cloudbongos.com' }),
+    };
+    await assert.rejects(
+      () => P.provisionInstance({ ...coTenant, hosting_shape: 'standalone', target_ref: 'lars589/mercury', domain: 'mercury.cloudbongos.com' }, deps),
+      /PROVISION_CONTROL_PLANE_IP/,
+      'must demand the control-plane IP, not fall back to the co-hosting box',
+    );
+  } finally { P.CONFIG.publicIp = savedPub; P.CONFIG.controlPlaneIp = savedCp; P.CONFIG.dnsHook = savedHook; P.CONFIG.remoteHost = savedRemote; }
+});
+
+await ta('teardownInstance(standalone, remote): tears down on the CONTROL PLANE — the box it ran on — not the co-hosting box (task 2074)', async () => {
+  const box = [], control = [];
+  const deps = {
+    apply: false, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: { setInstanceStatus: async () => {}, recordEvent: async () => {} },
+    exec: (cmd) => { box.push(cmd); return { ok: true }; },
+    controlExec: (cmd) => { control.push(cmd); return { ok: true }; },
+    writeFile: () => ({ ok: true }), controlWriteFile: () => ({ ok: true }), doApi: null,
+  };
+  await P.teardownInstance({ ...coTenant, hosting_shape: 'standalone' }, deps);
+  assert.ok(control.some((c) => /systemctl disable --now mercury/.test(c)), 'disable runs on the control plane');
+  assert.ok(control.some((c) => /rm -f .*mercury\.service/.test(c)), 'unit removed on the control plane');
+  assert.equal(box.length, 0, 'nothing crosses to the co-hosting box for a standalone teardown');
+});
+
+console.log(`\nprovision: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);