@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/provision.js

@@ -0,0 +1,1479 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/provision.js — the INSTANCE-provisioning control-plane runner
+// (ADR 0111 §2/§3, BONGOS-V1 goal 32, task #1944).
+//
+// 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):
+//
+//   DNS A record FIRST (task 1004505 — the name must exist before anyone is shown it)
+//     → server (a process on an allocated port — co-tenant or cloud-host)
+//     → 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 — shared with 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 (the app user) 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 box / 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), tested directly.
+//
+// This is control-plane ops tooling (scripts/), so 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).
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const cp = require('node:child_process');
+const crypto = require('node:crypto');
+
+const retry = require('./intent-retry.js'); // when a failed intent is tried again (task 1004447)
+const { CONFIG, MANIFEST_UA, softFailResult, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, MAX_INTENT_ATTEMPTS, REPO_ROOT, coreVersionSafe, hasFlag, loadDeps, oauthSecret, provisionerBotEmail } = require('./provision-config.js');
+const { accountPreflight, appUser, alreadyScaffolded, buildCorePinRefreshCommit, coreCheckoutHasGit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, dbOwnershipCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
+const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, envPrefixMismatch, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, renamedEnvCarry, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
+const { caddyBlock, caddySnippetPath, checkCaddyWiring, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, ingressPlaneGap, ingressPreflight, shouldFederate, zoneForDomain } = require('./provision-net.js');
+const { resolveProcessManager } = require('./provision-process.js');
+const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
+const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { disconnectInstance } = require('./provision-disconnect.js');
+const { coreUpgradeInstance, preflightCoreUpgrade, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
+const { isByoHost, recordByoHost } = require('./provision-byo-host.js'); // stand up NOTHING for a byo-host row, ADR 0323
+
+// WHAT supervises an instance's service (ADR 0306). systemd on every box we run — the
+// seam exists so a plane without systemd is not a dead end. Injectable for tests.
+const pmFor = (deps) => (deps && deps.processManager) || resolveProcessManager();
+
+function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
+  // `shown` (task 1003140): what to LOG in place of the command text — for a command
+  // that carries a secret (a remote file placement embeds the base64 body), so the
+  // journal records "write <path> (N bytes)" and never the payload.
+  return function run(cmd, { allowFail = false, cwd, env, shown: shownAs } = {}) {
+    // 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}] ${shownAs || 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) {
+        // The script rides STDIN, so e.message names only the ssh hop — but a
+        // `shown` call site is secret-bearing by declaration: log the exit status
+        // alone, never stderr (a remote shell may echo the failing line back).
+        const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
+        if (allowFail) { log(`    ~ ${shown} (non-fatal: ${why})`); return softFailResult(e, !!shownAs); }
+        log(`    ✖ ${shown}`);
+        throw e;
+      }
+    }
+    // Local step (control plane / today's behavior). cwd defaults to REPO_ROOT.
+    const shown = shownAs || `${envPrefix}${cmd}`;
+    const label = shownAs || 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(`    ✓ ${label}`);
+      return { ok: true, stdout };
+    } catch (e) {
+      // With `shown` set the command text is considered secret-bearing, so the
+      // non-fatal line carries only the exit status — never e.message, whose
+      // "Command failed: <cmd>" would echo the command back into the journal.
+      const why = shownAs ? `exit status ${e && e.status != null ? e.status : '?'}` : (e.stderr || e.message || '').toString().trim().slice(0, 120);
+      if (allowFail) { log(`    ~ ${label} (non-fatal: ${why})`); return softFailResult(e, !!shownAs); }
+      log(`    ✖ ${label}`);
+      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(' && ');
+      // The command text embeds the (base64) body — a web.env carries the OAuth
+      // secret and the App private key — so the exec logs THIS instead (task 1003140).
+      const shown = `write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''})`;
+      if (!apply) {
+        log(`    would write ${p} (${body.length} bytes${mode ? `, mode ${mode.toString(8)}` : ''}) on ${remoteHost}`);
+        if (exec) exec(cmd, { shown });
+        return { dryRun: true };
+      }
+      exec(cmd, { shown });
+      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 };
+      }
+      // Owner-only while staged: the destination is 0600 and the body may carry secrets.
+      fs.writeFileSync(tmp, body, { mode: 0o600 });
+      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, 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 is
+  // 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 === 'cloud-host';
+  const boxExec = standalone ? controlExec : exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl escalation prefix (task 2066)
+  // One fresh per-instance DB password per run (task 1003369, see provision-repo.js): step
+  // 2b sets it on the role, step 3 writes it to web.env, so the two cannot disagree.
+  const dbPassword = generateDbPassword();
+  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 }; }
+
+  if (isByoHost(inst.hosting_shape)) return recordByoHost(inst, deps); // stand up NOTHING, ABOVE every preflight — reasoning in provision-byo-host.js's header (ADR 0323)
+  // ── preflight: DNS token scope (task 1980) ─────────────────────────────────
+  // BEFORE committing to the address (the step-0 DNS UPSERT /
+  // allocating a port), 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`);
+    }
+  }
+  const room = await capacityPreflight(inst, deps);   // box capacity (ADR 0285, task 1003927): an honest refusal BEFORE the status flip — never a silent oversubscribe
+  if (room.ok === false) return room;
+  // Ingress preflight (task 1004017, ADR 0315). Ordered capacity → ingress → wiring, all three
+  // before any mutation: ingress asks whether this plane has a proxy AT ALL, 0303 below whether
+  // that proxy is wired for THIS domain. Deliberately NOT domain-gated — a domainless child
+  // skipped 0303 entirely, reached step 6 and died on the snippet write.
+  const ingressGap = ingressPreflight({ exec: boxExec, apply, log, probe: deps.ingressPlaneGap });
+  if (ingressGap) return { ok: false, error: ingressGap };
+  // Account preflight (task 1004018, ADR 0317). The third and last PLANE question — can this
+  // box give the child its own unix account? — before 0303 below asks the per-DOMAIN one. A
+  // plane that cannot would run every child as one uid, the ADR 0281 vector, and step 1c's
+  // useradd would crash mid-provision instead of refusing.
+  const accountGap = accountPreflight({ exec: boxExec, apply, log, privileged, probe: deps.accountPlaneGap });
+  if (accountGap) return { ok: false, error: accountGap };
+  // App-user preflight (task 1002719): steps below name the app user, and appUser() refuses
+  // root or an unusable name. Refuse HERE, before the status flip, not midway through.
+  try { appUser(); } catch (e) { return { ok: false, error: e.message }; }
+  // Caddy preflight (task 1002860, ADR 0303): a box whose base Caddyfile has no tls-check ask
+  // can never certify this domain, so refuse before touching it. Injectable like the DNS check.
+  const caddyCheck = deps.checkCaddyWiring || checkCaddyWiring;
+  if (inst.domain && apply) {
+    const gap = caddyCheck(boxExec, { domain: inst.domain });
+    if (gap) return { ok: false, error: `Caddy preflight failed: ${gap}` };
+  }
+  // ── step 0: DNS FIRST — Cloudflare A-record UPSERT for the instance's domain (P4) ──
+  // The first mutation of a standup, ahead of the status flip and every step after it
+  // (task 1004505, BV2.PS17). The hub can show a project's address from the moment it
+  // is created, and a lookup made before the record exists is cached as "not found" by
+  // the visitor's resolver for the zone's negative TTL (30 min on cloudbongos.com) — a
+  // founder's first click used to lock their own home network out of the project for
+  // half an hour. Created here, the name answers before any surface can offer it; the
+  // hub also holds every link until a platform lookup has seen it answer (dns_resolves).
+  // The A-record target (recordIp):
+  //   • 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 this step fail loud rather than point the domain at the wrong box.
+  const recordIp = standalone ? CONFIG.controlPlaneIp || (CONFIG.remoteHost ? null : CONFIG.publicIp) : CONFIG.publicIp;
+  // Formalized in P4 (#1945): the shared box-dns-cloudflare.sh hook UPSERTs an A
+  // record pointing the domain at recordIp, in the domain's own zone. It runs on the
+  // CONTROL PLANE for every shape: the hook needs the Cloudflare token, which never
+  // leaves the control plane. A DNS FAILURE SURFACES (the task-1180 lesson: never
+  // report provision success while the A record silently didn't land) — and, being
+  // first, it now fails before anything else was touched.
+  let dnsUpserted = false;
+  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`);
+      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
+      // stays proxied=false so their on-demand ACME challenge (step 6) 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 below go there over SSH (task 2065).
+      controlExec(CONFIG.dnsHook, { env: dnsEnv });
+      dnsUpserted = true;
+      // The clear half of the birth-path note (F16): a revive after the operator
+      // configured the hook must retire the stale "point your A record" sentence.
+      if (apply && provisioning.recordDnsNote) {
+        await provisioning.recordDnsNote(db, inst.id, null).catch(() => {});
+      }
+    }
+  } else {
+    log('  [dns] skipped (no domain, or BOX_DNS_HOOK unset)');
+    // Birth-path twin of the domain-attach note (F16): a domain with no hook is
+    // the same silent skip here, so the owner card gets the same sentence.
+    if (apply && inst.domain) {
+      if (provisioning.recordDnsNote) await provisioning.recordDnsNote(db, inst.id,
+        `Automatic DNS isn't set up on this platform — point ${inst.domain}'s A record at ${recordIp || 'your server'}, and this card will show when it answers.`
+      ).catch(() => {});
+    }
+  }
+
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
+  const patch = {};
+
+  // ── cross-site identity: register hub federation (ADR 0141 §4, task #1002109) ──
+  // Computed BEFORE the shape steps so the co-tenant web.env write (step 3) bakes it
+  // in — the instance comes up already federated, no post-hoc restart. Dormant unless
+  // the control plane is hub-configured AND the shape/domain qualify (shouldFederate);
+  // otherwise the instance owns its auth (direct GitHub), byte-identically to today.
+  let federation = null;
+  {
+    const fed = shouldFederate(inst, deps);
+    if (fed.federate) {
+      federation = await federateInstance(inst, deps);
+      log(`  [federate] ${inst.slug} → hub sign-in (auth.idp on) — no GitHub app of its own`);
+      if (apply) {
+        await provisioning.recordEvent(db, {
+          instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'federated',
+          detail: `sign-in federated to the hub (client ${inst.slug}, origin https://${inst.domain})`, actor: 'runner',
+        }).catch(() => {});
+      }
+    } else {
+      log(`  [federate] skipped (${fed.reason}) — instance owns its auth (direct GitHub)`);
+    }
+  }
+
+  // ── step 1: server ───────────────────────────────────────────────────────
+  // 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 @bongos/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 === 'cloud-host') {
+    await scaffoldStandaloneRepo(inst, deps);
+    // A PRIVATE target_ref gets its own read-only deploy key BEFORE step 2's `git pull
+    // --ff-only origin main`, which failed unauthenticated on every private standup (N4; ADR 0176).
+    await ensurePrivateRepoAccess(inst, deps);
+    await require('./provision-pin-key.js').ensurePinWriteKey(inst, deps); // the hub's WRITE key for later pin pushes, public repos too (task 1004291, ADR 0350)
+  }
+  if (!inst.db_name) { patch.db_name = inst.slug; inst = { ...inst, db_name: inst.slug }; }
+
+  // The remaining steps run on the instance's box (boxExec/boxWriteFile — remote for
+  // co-tenant under remote-exec, control-plane-local for standalone; task 2074).
+
+  // ── step 2: code sync (standalone) + database ─────────────────────────────
+  if (standalone) {
+    // Standalone (ADR 0108 / deploy-instance.sh steps 1-2): sync the instance's own
+    // repo + install the pinned @bongos/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).
+    // CORE RESOLUTION: the vendored default needs no network at all (the tarball is
+    // committed). A registry pin resolves from the public registry — @bongos/core is public
+    // (task 1003872), so `npm ci` needs no credential either way (task 1003878).
+    const root = standaloneRoot(inst);
+    log('  [code] standalone — pull instance repo + npm ci (pinned @bongos/core)');
+    boxExec(standalonePullCmd(), { cwd: root });
+    // W3 (task 1003050): heal a committed `file:` pin that trails this control plane's
+    // running core BEFORE npm ci, so a re-provision can never leave running != pinned
+    // (the silent-rollback hazard: the next `git reset --hard` + `npm ci` deploy would
+    // otherwise revert the instance against an already-migrated DB). Gated on apply —
+    // the refresh writes through upgrade.js fs/npm calls, not the dry-run-safe exec.
+    if (apply) await refreshStandaloneCorePin(inst, deps);
+    else log('  [code] would refresh the committed @bongos/core pin if it trails the running core (task 1003050)');
+    boxExec(standaloneInstallCmd(), { cwd: root });
+  }
+  // ── step 1c: the instance's OWN unix account (task 1003369, audit B3) ─────
+  // Idempotent; the group-add is what lets a fresh system account READ the checkout it runs
+  // from — without it the unit fails at exec with EACCES. Rationale: provision-repo.js.
+  log(`  [user] ensure unix account ${instanceUser(inst)} + its state dir`);
+  boxExec(ensureInstanceUserCmd(inst, { privileged }));
+  boxExec(grantInstanceRepoReadCmd(inst, { privileged }));
+
+  log('  [db] create + GDS-only migrate');
+  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 }));
+  // Seed the first version so the instance can take tasks from minute one (task 2119,
+  // goal 35). Only fires if the versions table is empty — idempotent, never disturbs an
+  // existing project. NOT allowFail: a re-run is a clean 0-row no-op, so a real failure
+  // here should surface.
+  log('  [seed] first version (only if versions is empty)');
+  boxExec(seedFirstVersionCmd(inst, { privileged }));
+  // Regenerate the whole-file navigation docs from the pinned core so a fresh/redeployed
+  // standalone instance's docs/ stays live (ADR 0110 §2, task 1002314) — the deploy-regen the
+  // bespoke pull scripts were missing. Best-effort: regen-instance-docs.js exits 0 even on a
+  // generator hiccup (LOUD ::ERROR::), so a stale nav doc never fails a provision.
+  if (standalone) {
+    log('  [docs] regenerate whole-file navigation docs (session-log index)');
+    boxExec(standaloneRegenDocsCmd(), { cwd: standaloneRoot(inst), allowFail: true });
+  }
+
+  // ── step 2b: the instance's OWN password-authed PG role (task 1003369, audit B3) ──
+  // AFTER the migrate: it runs as `postgres`, which therefore OWNS the tables it creates.
+  log('  [db] create/rotate the per-instance role + revoke PUBLIC connect');
+  // `shown` is MANDATORY: dbRoleCmd embeds the password, and run() logs the raw command
+  // on BOTH the dry-run and success paths — the exact leak this task exists to prevent
+  // (makeWriteFile passes `shown` for the web.env body for the same reason, and a `shown`
+  // call site also suppresses stderr). The GRANTS carry no secret and log in full.
+  boxExec(dbRoleCmd(inst, { password: dbPassword, privileged }), { shown: dbRoleCmdShown(inst) });
+  boxExec(dbRoleGrantsCmd(inst, { privileged }));
+  // Grants are not ownership: later moves migrate AS this role and must ALTER what the migrate
+  // above created as postgres (task 1004735). Non-fatal on purpose — if it ever fails, the
+  // project still serves, and the first move that needs it applies it (migrate_not_owner).
+  const own = boxExec(dbOwnershipCmd(inst, { privileged }), { allowFail: true });
+  if (own && own.softFailed) log('  ⚠ [db] could not hand the schema to the instance role — its first core move that ALTERs a table will retry it (migrate_not_owner)');
+
+  // ── step 3: config + per-instance secrets ─────────────────────────────────
+  log('  [config] per-instance web.env');
+  boxWriteFile(webEnvPath(inst), webEnvBody(inst, { federation, ownerLogin: await ownerLoginOf(inst, deps.db), dbPassword }), { mode: 0o600, sudo: true });
+
+  // ── step 4: install + enable the instance's service ───────────────────────
+  const pm = pmFor(deps);
+  log(`  [service] install + enable the ${pm.key} service`);
+  pm.installService(inst, { exec: boxExec, writeFile: boxWriteFile, sudoP, log });
+
+  // ── step 4b: nightly DB backup — dir + consumer-layout timer/service (task 2213) ──
+  // Every instance must be born WITH backups (the task-2210 gap: cloudbongos was
+  // provisioned without any). Create the app-user-owned backup dir, install the
+  // per-instance timer/service (correct db + consumer-layout script path), enable
+  // the timer. Idempotent: `install -d` no-ops on an existing dir, unit writes are
+  // overwrites, `enable --now` is idempotent.
+  log('  [backup] create backup dir + install + enable nightly DB backup timer');
+  pm.installBackup(inst, { exec: boxExec, writeFile: boxWriteFile, sudoP, log });
+
+  // (step 5, the DNS UPSERT, moved to step 0 at the top — task 1004505.)
+  // A re-point on a PRE-ACTIVE instance records its release here and never
+  // reaches the attach leg (that one no-ops for anything but 'active'), so this
+  // run owns the drain — and an `error` row is frequently a partial standup that
+  // already UPSERTed the address it is now leaving (ADR 0181 §1, task 1003237).
+  await releaseAbandonedDomains(inst, { controlExec, log, apply, db, provisioning });
+
+  // ── 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) — verified after the write, since only a written snippet proves the import
+  // reaches it. The reload is loud: Caddy keeps its old config when it rejects the new one.
+  log('  [caddy] write site snippet + reload');
+  boxWriteFile(caddySnippetPath(inst), caddyBlock(inst), { mode: 0o644, sudo: true });
+  const gap = inst.domain && apply ? caddyCheck(boxExec, { domain: inst.domain, requireHost: true }) : null;
+  if (gap) return { ok: false, error: `Caddy wiring failed: ${gap}` };
+  boxExec(`${sudoP}systemctl reload caddy`);
+
+  // ── step 7: healthz ───────────────────────────────────────────────────────
+  // The probe RESULT is recorded, not discarded (task 1002720 / QA-walk F15: a
+  // refused connection used to ride silently into 'active' and the card said
+  // live). Bounded retry so a slow first boot is not slandered — the
+  // placeManifestCreds loop shape. Still ok:true either way: a failed probe
+  // must not flip the intent to failed (cmdRunIntents would burn the 3-attempt
+  // budget on an instance that may simply be slow); the liveness overlay is
+  // what tells the owner the truth.
+  log('  [healthz] verify the instance answers');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let healthy = null;                     // null = not observed (dry-run)
+  const tries = apply ? 10 : 1;
+  for (let i = 0; i < tries; i++) {
+    const res = boxExec(healthzCmd(inst), { allowFail: true });
+    if (!apply) break;                  // dry-run: exactly one plan line
+    if (res && !res.softFailed) { healthy = true; break; }
+    healthy = false;
+    if (i < tries - 1) await sleep(1000);
+  }
+
+  // ── step 7b: identity ─────────────────────────────────────────────────────
+  // Does it answer as ITSELF? A live instance that serves the platform's name instead of its own
+  // is invisible to healthz — it is perfectly healthy and telling every newcomer the wrong project
+  // (task 1003740, which went unnoticed across every hosted instance for months). A WARNING, never
+  // a failure: an owner may legitimately name a project after the platform, and a name must not
+  // fail a working standup.
+  if (apply && healthy !== false) {
+    const res = boxExec(identityCmd(inst), { allowFail: true });
+    const raw = res && !res.softFailed ? (res.stdout || '') : '';
+    let manifest = null;
+    try { manifest = raw ? JSON.parse(raw) : null; } catch (_) { manifest = null; }
+    if (manifest) {
+      let neutralName = null;
+      try {
+        neutralName = (JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'config/branding.neutral.json'), 'utf8'))
+          .identity || {}).productName || null;
+      } catch (_) { /* no neutral pack readable → the check simply cannot fire */ }
+      const verdict = identityVerdict({ manifest, slug: inst.slug, neutralName });
+      if (verdict.ok === false) {
+        log(`  ⚠ ${inst.slug} ${verdict.reason} — check its config/branding.json and that no env var pins its branding pack`);
+      } else if (verdict.ok) {
+        log(`  [identity] answers as "${verdict.name}"`);
+      }
+    }
+  }
+
+  // Mark active. error_note: null — a stale note from an earlier failed run
+  // must not ride into the active state (F15's second half; the co-tenant +
+  // standalone paths never cleared it). The runner hands its own observation
+  // to the liveness overlay so the card gets an honest verdict immediately
+  // instead of waiting ~5 min for the first sweep.
+  // ── step 7c: the platform's own lookup (task 1004505) ─────────────────────
+  // The record went in at step 0, minutes ago, so this lookup cannot race it into a
+  // cached miss. An answer lets the hub link the address the moment the row reads
+  // active, instead of waiting for the first liveness sweep. Only for a record this
+  // run created: a manual-DNS domain is the owner's to point, and the sweep finds it.
+  if (apply && dnsUpserted && provisioning.lookupAnswers && provisioning.recordDnsResolved) {
+    if (await provisioning.lookupAnswers(inst.domain, { lookup: deps.lookup })) {
+      await provisioning.recordDnsResolved(db, inst.id).catch(() => {});
+      log(`  [dns] ${inst.domain} answers — the hub may link it now`);
+    } else {
+      log(`  [dns] ${inst.domain} does not answer the control plane yet — the hub holds its link until the sweep sees it`);
+    }
+  }
+
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'active', { ...patch, error_note: null, provisioned_at: new Date().toISOString() });
+    // The overlay column is DOMAIN-scoped when a domain exists (the sweep
+    // probes https://<domain>; loopback only when there is none), and the card
+    // renders up=true as "Answering at <domain>". This probe is loopback, so:
+    // a FAILURE is a verdict on any shape (a dead process answers nowhere),
+    // but a PASS proves only the process — for a domain-bearing instance the
+    // address claim stays "not checked yet" until the sweep earns it.
+    const probeIsVerdict = healthy === false || (healthy === true && !inst.domain);
+    if (probeIsVerdict && provisioning.recordLivenessProbe) {
+      await provisioning.recordLivenessProbe(db, inst.id, healthy).catch(() => {});
+    }
+    await provisioning.recordEvent(db, {
+      instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'active',
+      detail: `provisioned (${inst.hosting_shape}, port ${inst.port || '-'})` +
+              (healthy === false ? ' — not answering /healthz yet' : ''),
+      actor: 'runner',
+    });
+  }
+  log(healthy === false
+    ? `  ⚠ ${inst.slug} provisioned, but it is not answering /healthz yet — its card will read "unreachable"`
+    : `  ✓ ${inst.slug} provisioned`);
+  return { ok: true, port: inst.port, healthy };
+}
+
+// The addresses a re-point left behind and this run still owes a release on
+// (task 1003237). The one guard this tier can make on its own, and the one that
+// matters: the address the instance is CURRENTLY on is never released, so a row
+// that somehow queued its own domain can never blackhole a live project.
+// WHICH addresses reach the queue is the ENQUEUE site's job (the route's
+// `releasing`, ADR 0200 as amended by task 1002902). PURE.
+function releasableDomains(inst) {
+  const here = String((inst && inst.domain) || '').toLowerCase();
+  return (Array.isArray(inst && inst.released_domains) ? inst.released_domains : [])
+    .map((d) => String(d || '').toLowerCase())
+    .filter((d) => d && d !== here);
+}
+
+// Park every address a re-point moved off at the blackhole sentinel, then empty
+// the queue (task 1003237, ADR 0200). Called by BOTH legs that wire a domain —
+// domain-attach for an ACTIVE instance, and the provision run that owns
+// PRE-ACTIVE ones, since an `error` row is frequently a partial standup that
+// already UPSERTed the address it is now leaving (ADR 0181 §1).
+//
+// BEST-EFFORT in the teardown sense: a hook that fails leaves the queue intact
+// so the next run retries, and never fails the wiring that already landed. EVERY
+// queued address is attempted — one host whose zone the token cannot reach must
+// not strand the others behind it — and the queue is emptied only when all of
+// them landed; a re-park of an address already at the sentinel is an idempotent
+// UPSERT, so retrying the whole list costs nothing but the call. The list is
+// capped at the enqueue site (MAX_RELEASED_DOMAINS), which is what bounds this
+// loop. Returns the first host that failed, or null. Runs on the CONTROL PLANE —
+// the hook needs the Cloudflare token, which never leaves it (ADR 0111 §2).
+async function releaseAbandonedDomains(inst, { controlExec, log, apply, db, provisioning }) {
+  const hosts = releasableDomains(inst);
+  if (!hosts.length) return null;
+  if (!CONFIG.dnsHook) {
+    log(`  [dns] cannot release ${hosts.join(', ')} (BOX_DNS_HOOK unset) — remove their A records manually`);
+    return null;
+  }
+  let firstFailed = null;
+  for (const host of hosts) {
+    // task 1003954: the route frees a name once this row moves off it, so another
+    // project may have attached it since — parking it now would blackhole THAT
+    // project. A name we cannot check is kept for the next run, never parked on a guess.
+    let holder = null;
+    try { holder = provisioning.getInstanceByDomain ? await provisioning.getInstanceByDomain(db, host) : null; }
+    catch (e) {
+      log(`  ⚠ could not check who holds ${host}: ${(e && e.message) || e} — left for the next run`);
+      if (!firstFailed) firstFailed = host;
+      continue;
+    }
+    if (holder && String(holder.id) !== String(inst.id) && holder.status !== 'torn_down') {
+      log(`  [dns] leave ${host} alone — ${holder.slug} holds it now`);
+      continue;
+    }
+    const relEnv = dnsReleaseEnv(host);
+    log(`  [dns] release ${host} -> ${relEnv.BOX_IP} (blackhole, zone ${relEnv.CLOUDFLARE_ZONE}) via ${CONFIG.dnsHook}`);
+    if (!apply) continue;
+    try { controlExec(CONFIG.dnsHook, { env: relEnv }); }
+    catch (e) {
+      log(`  ⚠ could not release ${host}: ${(e && e.message) || e} — its A record still points here`);
+      if (!firstFailed) firstFailed = host;
+    }
+  }
+  if (firstFailed) return firstFailed;
+  if (apply && provisioning.clearReleasedDomains) await provisioning.clearReleasedDomains(db, inst.id).catch(() => {});
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Attach a late-arriving domain to an ALREADY-ACTIVE instance (task 1002692):
+// re-assert exactly the domain-dependent runbook legs — web.env origins (+ a
+// service RESTART so the process re-reads them), the Cloudflare A-record UPSERT
+// (step 5), the Caddy site snippet (step 6) — then healthz. Expected failures
+// RETURN { ok:false } instead of throwing: the drain loop's catch flips the
+// instance to 'error', which must never happen to a healthy ACTIVE instance
+// over a domain hiccup.
+//
+// This leg ALSO carries a RE-POINT (task 1003237, ADR 0200) — the same intent,
+// because the wiring is the same wiring. Two things follow from that:
+//   • The origin lines are patched IN PLACE (upsertEnvVars), never regenerated
+//     from the row. A template re-write via webEnvBody would blank the OAuth
+//     creds placeManifestCreds placed, the App private key and the federation
+//     block — none of which the row knows (ADR 0190 §2). A first attach was
+//     MASKED by wizard order (address first, GitHub App second); a re-point runs
+//     on a project the founder is already signed in to, so the same move would
+//     break sign-in on the exact project they just corrected (idea 1000842).
+//   • Every address on the row's release queue is parked at the blackhole
+//     sentinel AFTER the new one is wired — best-effort, never fatal.
+// ---------------------------------------------------------------------------
+async function domainAttachInstance(inst, deps) {
+  const { db, provisioning, exec, writeFile, log, apply, privileged } = deps;
+  const controlExec = deps.controlExec || exec;
+  // Same box routing as provisionInstance: a standalone runs control-plane-local
+  // (task 2074), so its env/caddy/service live HERE, not on the co-hosting box.
+  const standalone = inst.hosting_shape === 'cloud-host';
+  const boxExec = standalone ? controlExec : exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';
+  log(`domain-attach ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status}, domain=${inst.domain || '-'})`);
+
+  if (!inst.domain) return { ok: false, error: 'no domain recorded on the instance — nothing to wire' };
+  // Pre-active states are the provision run's job; post-active states have nothing
+  // to address. A clean no-op (not an error) so a raced teardown/re-request never
+  // burns the intent's retry budget.
+  if (inst.status !== 'active') {
+    log(`  instance is '${inst.status}' — nothing to wire now (provision owns pre-active domains)`);
+    return { ok: true, noop: true };
+  }
+  // DNS preflight (the task-1980 stance): verify token reach BEFORE touching the box.
+  if (CONFIG.dnsHook && apply) {
+    const scope = await (deps.checkDnsTokenScope || checkDnsTokenScope)(inst.domain);
+    if (!scope.reachable) {
+      return { ok: false, error: `DNS preflight failed for ${inst.domain}: ${scope.reason}. ${scope.guidance}` };
+    }
+    log(`  [preflight] DNS token can reach zone ${scope.zone} ✓`);
+  }
+  const ingressGap = ingressPreflight({ exec: boxExec, apply, log, probe: deps.ingressPlaneGap, before: 're-writing the Caddy snippet' });
+  if (ingressGap) return { ok: false, error: ingressGap };   // Ingress preflight (task 1004017, ADR 0315)
+  const caddyCheck = deps.checkCaddyWiring || checkCaddyWiring;   // Caddy preflight (task 1002860, ADR 0303)
+  if (apply) {
+    const gap = caddyCheck(boxExec, { domain: inst.domain });
+    if (gap) return { ok: false, error: `Caddy preflight failed: ${gap}` };
+  }
+
+  // The A-record target — the same derivation as provisionInstance step 1.
+  const recordIp = standalone
+    ? (CONFIG.controlPlaneIp || (CONFIG.remoteHost ? null : CONFIG.publicIp))
+    : CONFIG.publicIp;
+
+  // Patch ONLY the origin lines (the settingsApplyInstance shape, ADR 0190 §2).
+  // Dry-run has no file to read, so it PLANS the patch rather than writing a
+  // synthetic body. An unreadable or empty file is refused, never "patched":
+  // writing four origins over a missing PORT/PGDATABASE would take the instance
+  // down — and this leg runs against instances that are ALREADY serving.
+  const origins = originEnvVarsFor(inst);
+  const read = boxExec(`${sudoP}cat ${webEnvPath(inst)}`, { allowFail: true });
+  const currentEnv = String((read && read.stdout) || '');
+  if (!apply) {
+    log(`  [config] would patch ${Object.keys(origins).join(', ')} in ${webEnvPath(inst)} in place (creds + federation untouched)`);
+  } else if (!read || read.softFailed || !currentEnv.trim()) {
+    return { ok: false, error: `cannot read ${webEnvPath(inst)} — nothing to patch (was this instance provisioned by the runner?)` };
+  } else {
+    log('  [config] patch the origin lines of web.env in place (creds + federation untouched)');
+    boxWriteFile(webEnvPath(inst), upsertEnvVars(currentEnv, origins), { mode: 0o600, sudo: true });
+  }
+  log('  [service] restart to pick up the new origins');
+  pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+
+  // DNS A-record UPSERT — mirrors provisionInstance step 5 (control-plane exec only:
+  // the hook needs the Cloudflare token, which never leaves the control plane).
+  let dnsSkipped = false;
+  if (CONFIG.dnsHook) {
+    if (!recordIp) {
+      const ipEnvHint = standalone ? 'PROVISION_CONTROL_PLANE_IP (standalone)' : 'PROVISION_PUBLIC_IP (co-tenant)';
+      if (apply) return { ok: false, error: `cannot UPSERT DNS for ${inst.domain}: no target IP — set ${ipEnvHint} in the control-plane box.env` };
+      log(`  [dns] would upsert A ${inst.domain} once the target IP is known (set ${ipEnvHint})`);
+    } else {
+      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(CONFIG.dnsHook, { env: dnsEnv });
+    }
+  } else {
+    // Still ok:true below — an unset hook is unretryable, and ok:false would
+    // burn the intent's retry budget on it. The skip is surfaced to the OWNER
+    // via dns_note (F16), not just this operator log line.
+    dnsSkipped = true;
+    log(`  [dns] skipped (BOX_DNS_HOOK unset) — point ${inst.domain}'s A record at ${recordIp || 'this server'} manually`);
+  }
+
+  // The snippet is per-SLUG and always carries the CURRENT domain, so a re-point
+  // takes the old vhost away in the same write — Caddy stops serving the old host
+  // (and tls-check stops vouching for it) with no separate un-wire step.
+  log('  [caddy] write site snippet + reload');
+  boxWriteFile(caddySnippetPath(inst), caddyBlock(inst), { mode: 0o644, sudo: true });
+  const gap = apply ? caddyCheck(boxExec, { domain: inst.domain, requireHost: true }) : null;
+  if (gap) return { ok: false, error: `Caddy wiring failed: ${gap}` };
+  boxExec(`${sudoP}systemctl reload caddy`);
+
+  // Release what the re-point moved off, AFTER the new address is wired: the DNS
+  // record is the only half of an abandoned address the platform still holds, and
+  // it points at platform infra.
+  const releaseFailed = await releaseAbandonedDomains(inst, { controlExec, log, apply, db, provisioning });
+  if (releaseFailed) return { ok: true, releaseFailed };
+
+  log('  [healthz] verify the instance answers');
+  boxExec(healthzCmd(inst), { allowFail: true });
+
+  if (apply) {
+    // Written BOTH ways so a later successful attach clears a stale note.
+    if (provisioning.recordDnsNote) await provisioning.recordDnsNote(db, inst.id, dnsSkipped
+      ? `Automatic DNS isn't set up on this platform — point ${inst.domain}'s A record at ${recordIp || 'your server'}, and this card will show when it answers.`
+      : null).catch(() => {});
+    // Release the F19 latch: this run SUCCEEDED, so a "we stopped trying" note
+    // from an earlier retired attach must not outlive its own recovery.
+    if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id, 'domain-attach').catch(() => {});
+    await provisioning.recordEvent(db, {
+      instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'domain-attached',
+      detail: dnsSkipped
+        ? `domain ${inst.domain} wired (env + caddy); DNS SKIPPED — no hook configured`
+        : `domain ${inst.domain} wired (env + DNS + caddy re-asserted)`,
+      actor: 'runner',
+    }).catch(() => {});
+  }
+  log(dnsSkipped
+    ? `  ✓ ${inst.slug} configured for ${inst.domain} — DNS still needs your A record`
+    : `  ✓ ${inst.slug} addressed as ${inst.domain}`);
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Push a changed per-project setting to an ALREADY-ACTIVE instance (task
+// 1003140 — the live-push half of the platform→instance settings channel; task
+// 1003139 built the standup half). The branding pack is memoized + deep-frozen
+// for the process lifetime, so a change reaches a running instance only by
+// re-writing its web.env and RESTARTING the service: the domain-attach shape
+// minus the DNS legs. The settings lines are patched IN PLACE (upsertEnvVars) —
+// a template re-write via webEnvBody would blank the OAuth creds that
+// placeManifestCreds placed, which this leg has no way to know. EVERY expected
+// failure — an unreadable file, a refused write, a restart that exits non-zero —
+// RETURNS { ok:false } instead of throwing: the drain loop's catch flips the
+// instance to 'error', which must never happen to a healthy ACTIVE instance over
+// a settings push (ADR 0190).
+// ---------------------------------------------------------------------------
+async function settingsApplyInstance(inst, deps) {
+  const { db, provisioning, exec, writeFile, log, apply, privileged } = deps;
+  // A standalone runs control-plane-local; the control plane's own row IS this box (task 1004334).
+  const onControlBox = inst.hosting_shape === 'cloud-host' || inst.hosting_shape === 'control-plane';
+  const boxExec = onControlBox ? (deps.controlExec || exec) : exec;
+  const boxWriteFile = onControlBox ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';
+  const vars = settingsEnvVarsFor(inst); // the self row's prefix is re-read from the live file at the write
+  const shown = Object.entries(vars).map(([k, v]) => `${k}=${v}`).join(' ');
+  log(`settings-apply ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status}): ${shown}`);
+
+  // Pre-active states get these values at standup from the same row; post-active
+  // ones have nothing to restart. A clean no-op (not an error) so a raced
+  // teardown never burns the intent's retry budget.
+  if (inst.status !== 'active') {
+    log(`  instance is '${inst.status}' — nothing to push now (standup writes the same values)`);
+    return { ok: true, noop: true };
+  }
+  // Read the file as it stands so ONLY the settings lines change. Dry-run runs no
+  // command, so it has no file to patch — it PLANS the patch instead of writing a
+  // synthetic two-line body (which would read as the exact overwrite this leg
+  // exists to avoid). An unreadable or empty file is refused, never "patched":
+  // writing two lines over a missing PORT/PGDATABASE would take the instance down.
+  const read = boxExec(`${sudoP}cat ${webEnvPath(inst)}`, { allowFail: true });
+  const current = String((read && read.stdout) || ''), carry = renamedEnvCarry(current); // task 1004395: only its NAMES are ever logged
+  if (!apply) {
+    log(`  [config] would patch ${Object.keys(vars).join(', ')} in ${webEnvPath(inst)} in place (every other line untouched)`);
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+    boxExec(healthzCmd(inst), { allowFail: true });
+    log(`  ✓ would restart ${inst.slug} with the new settings (dry-run — nothing ran)`);
+    return { ok: true, healthy: null, consumed: null };
+  }
+  if (!read || read.softFailed || !current.trim()) {
+    return { ok: false, error: `cannot read ${webEnvPath(inst)} — nothing to patch (was this instance provisioned by the runner?)` };
+  }
+  try {
+    log(`  [config] patch the settings lines of web.env in place (creds + origins untouched)${carry.carried.length ? `; carry the renamed env forward: ${carry.carried.join(', ')} (value copied on the box, never shown)` : ''}`);
+    boxWriteFile(webEnvPath(inst), upsertEnvVars(current, { ...settingsEnvVarsFor(inst, current), ...carry.vars }), { mode: 0o600, sudo: true });
+    log('  [service] restart so the memoized branding pack re-reads them');
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  } catch (e) {
+    // ok:false, never a throw: the retry re-reads the file (the upsert is
+    // idempotent) and restarts again; the instance's status is left alone.
+    return { ok: false, error: `could not apply the settings on ${inst.slug}: ${(e && e.message) || e}` };
+  }
+
+  // Verify it came back. PATIENT (the F23 lesson — the manifest probe's budget):
+  // the child must boot before it can answer, and a false "down" here is not
+  // cosmetic — it arms the owner's re-kick paths. Silence after the WHOLE budget
+  // is a verdict on any shape and is recorded immediately (provisionInstance step
+  // 7's rule); a loopback PASS proves the process, not the address — the
+  // domain-scoped sweep earns that claim.
+  log('  [healthz] verify the instance answers after the restart');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let healthy = false;
+  for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
+    const res = boxExec(healthzCmd(inst), { allowFail: true });
+    if (res && !res.softFailed) { healthy = true; break; }
+    if (i < MANIFEST_VERIFY_TRIES - 1) await sleep(MANIFEST_VERIFY_INTERVAL_MS);
+  }
+  // Answering is not the same as having READ the new values: a core that predates
+  // task 1003139 restarts fine and ignores them. Ask the instance's own manifest
+  // (the read-back ADR 0190 names) and record what it says — never a success it
+  // did not earn. null = the manifest carries no project block (unknown).
+  let consumed = null;
+  if (healthy) {
+    const m = boxExec(instanceManifestCmd(inst), { allowFail: true });
+    consumed = settingsConsumed(m && m.stdout, inst);
+  }
+  const outcome = !healthy ? 'restarted, but not answering /healthz yet'
+    : consumed === true ? 'restarted and reads the new values'
+    : consumed === false ? 'restarted, but still reports the OLD values — its core may predate the settings channel'
+    : 'restarted; its core does not publish its settings yet (pin predates task 1003139), so whether it reads them is unknown';
+  const probeIsVerdict = healthy === false || (healthy === true && !inst.domain);
+  if (probeIsVerdict && provisioning.recordLivenessProbe) await provisioning.recordLivenessProbe(db, inst.id, healthy).catch(() => {});
+  // Release the F19 latch: this run SUCCEEDED, so a "we stopped trying" note
+  // from an earlier retired push must not outlive its own recovery.
+  if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id, 'settings-apply').catch(() => {});
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'settings-applied',
+    detail: `settings pushed (${shown}) — web.env patched in place${carry.carried.length ? `; carried ${carry.carried.join(', ')}` : ''}; ${outcome}`,
+    actor: 'runner',
+  }).catch(() => {});
+  log(healthy && consumed !== false
+    ? `  ✓ ${inst.slug} ${outcome}`
+    : `  ⚠ ${inst.slug} ${outcome}${healthy ? '' : ' — its card will read "unreachable"'}`);
+  return { ok: true, healthy, consumed };
+}
+
+// ---------------------------------------------------------------------------
+// Restart an ALREADY-ACTIVE instance the heartbeat cannot reach (task 1003238 —
+// the honest owner action behind the card's "unreachable" line). This is
+// settingsApplyInstance minus the env patch: nothing about the instance's
+// configuration changes, so there is no file to read and no file to write — just
+// the restart and the same PATIENT healthz verify, whose result is recorded on
+// the liveness overlay so the card that sent the owner here updates itself.
+//
+// Why its own leg rather than a re-provision: PROVISION_ENQUEUE_FROM deliberately
+// excludes 'active' (task 1002691), and provisionInstance is a no-op on an active
+// instance by design — a full standup is the wrong tool for "turn it off and on
+// again". Why not settings-apply: that leg only runs behind a value that actually
+// CHANGED, which is exactly the case a stuck project does not have.
+//
+// Like the settings push, EVERY expected failure RETURNS { ok:false } instead of
+// throwing: the drain loop's catch flips the instance to 'error', and an instance
+// that is merely unreachable must not be relabelled broken by the very action
+// meant to recover it — that would drop it off the liveness sweep and leave a
+// re-provision as its only exit (ADR 0190 §2).
+// ---------------------------------------------------------------------------
+async function restartInstance(inst, deps) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  // Same box routing as settingsApplyInstance: a standalone runs control-plane-local, and the
+  // control plane's own row IS this box (task 1004463).
+  const onControlBox = inst.hosting_shape === 'cloud-host' || inst.hosting_shape === 'control-plane';
+  const boxExec = onControlBox ? (deps.controlExec || exec) : exec;
+  const sudoP = privileged ? 'sudo ' : '';
+  log(`restart ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status})`);
+
+  // A clean no-op (not an error) so a teardown that raced the restart never burns
+  // the intent's retry budget: every non-active state either has nothing running
+  // yet or is being reclaimed.
+  if (inst.status !== 'active') {
+    log(`  instance is '${inst.status}' — nothing running to restart`);
+    return { ok: true, noop: true };
+  }
+  if (!apply) {
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+    boxExec(healthzCmd(inst), { allowFail: true });
+    log(`  ✓ would restart ${inst.slug} and wait for it to answer (dry-run — nothing ran)`);
+    return { ok: true, healthy: null };
+  }
+  try {
+    log('  [service] restart');
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  } catch (e) {
+    // ok:false, never a throw — the retry simply restarts again (idempotent).
+    return { ok: false, error: `could not restart ${inst.slug}: ${(e && e.message) || e}` };
+  }
+
+  // Verify it came back, with the manifest probe's patience (the F23 lesson). A
+  // false "down" is never cosmetic here: this instance is ALREADY flagged
+  // unreachable, and a hasty verdict would tell the owner their restart failed.
+  log('  [healthz] verify the instance answers after the restart');
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let healthy = false;
+  for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
+    const res = boxExec(healthzCmd(inst), { allowFail: true });
+    if (res && !res.softFailed) { healthy = true; break; }
+    if (i < MANIFEST_VERIFY_TRIES - 1) await sleep(MANIFEST_VERIFY_INTERVAL_MS);
+  }
+  // Same narrowness as the settings push: a loopback PASS proves the process, not
+  // the address, so only the domain-scoped sweep may claim "up" for an instance
+  // that HAS a domain. Silence after the whole budget is a verdict on any shape.
+  const probeIsVerdict = healthy === false || (healthy === true && !inst.domain);
+  if (probeIsVerdict && provisioning.recordLivenessProbe) await provisioning.recordLivenessProbe(db, inst.id, healthy).catch(() => {});
+  // A restart that worked retires the "we stopped trying" note a failed restart
+  // left (the F19 latch); another action's note stays (task 1004197).
+  // DELIBERATELY gated on `healthy`, NOT on probeIsVerdict: the two answer
+  // different questions. probeIsVerdict asks "may this run claim the instance is
+  // UP?" — a loopback pass may not, for an instance whose address the sweep owns.
+  // The note asks "did work stop partway?", and a process that restarted and
+  // answered is that work finishing, whatever the public address does next.
+  // Holding the note until the sweep agrees would leave a stale "nothing more
+  // will happen" on the card of a project that just visibly recovered.
+  if (healthy && provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id, 'restart').catch(() => {});
+  // Name WHAT was observed, not a verdict this probe cannot reach. healthzCmd is
+  // loopback (127.0.0.1:<port>) while the liveness sweep probes the PUBLIC
+  // https://<domain>/healthz — so an instance can answer here while DNS, Caddy or
+  // TLS is the thing actually broken. "Answering again" on a domained instance
+  // would contradict the card still reading "unreachable"; the same asymmetry is
+  // why probeIsVerdict above declines to write an up-verdict for that case.
+  const outcome = !healthy ? 'restarted, but it is not answering on the box — something there needs a look'
+    : inst.domain ? 'restarted and answering on the box; whether its public address answers is for the next liveness sweep to say'
+    : 'restarted and answering again';
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'restarted',
+    detail: `restart requested — ${outcome}`,
+    actor: 'runner',
+  }).catch(() => {});
+  log(healthy ? `  ✓ ${inst.slug} ${outcome}` : `  ⚠ ${inst.slug} ${outcome}`);
+  // ok:true either way: the restart RAN. A project that stays down is a truthful
+  // observation for the card, not a failed intent to retry MAX_INTENT_ATTEMPTS
+  // times — restarting a broken instance four more times fixes nothing and would
+  // end by stamping an error_note over the owner's own deliberate action.
+  return { ok: true, healthy };
+}
+
+// ---------------------------------------------------------------------------
+// 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,
+    // The App private key (task 1003049): with the manifest now requesting the
+    // ADR 0055 repo scopes, this pem + the app id ARE the instance's publish
+    // credential — placed into web.env alongside the OAuth creds, never logged.
+    appPem: data.pem ? String(data.pem) : null,
+  };
+}
+
+// The sign-in probe: the project's JSON health answer, which carries auth_configured
+// (src/bongos/routes/healthz.js). NOT healthzCmd — the root /healthz answers a plain "ok",
+// which never parses, so every setup that worked was recorded FAILED (task 1004577).
+function authHealthzCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/api/bongos/healthz`;
+}
+
+// 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. Returns { ok, appId, appSlug } | { ok:false, error }.
+async function placeManifestCreds(inst, mrow, deps) {
+  const { log, apply } = deps;
+  if (!mrow.github_code) return { ok: false, error: 'manifest row carries no github_code to convert' };
+  const standalone = inst.hosting_shape === 'cloud-host';
+  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, appPem: 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).
+  // From here on the single-use manifest code is SPENT (the conversion POST
+  // consumed it) — every return carries codeSpent:true so the drain never
+  // resets the row for a retry that would re-convert a burned code and 404.
+  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, codeSpent: apply, 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}`);
+  try {
+    boxWriteFile(webEnvPath(inst), webEnvBody(inst, {
+      clientId: creds.clientId, clientSecret: creds.clientSecret, ownerLogin: await ownerLoginOf(inst, deps.db),
+      // The App id + private key double as the ADR 0055 publish credential (task
+      // 1003049); older Apps (pre-permission manifests) return a pem too — placing
+      // it is harmless and heals once the owner grants the permissions + installs.
+      appId: creds.appId, appPem: creds.appPem,
+    }), { mode: 0o600, sudo: true });
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  } catch (e) {
+    // The code is spent and the keys are not placed: a retry would re-convert a burned
+    // code, so say so (codeSpent) and name the app GitHub made for the platform team
+    // (task 1004652 — the wizard offers to send it to them; the slug stays OFF the row,
+    // because a recorded slug reads as "keys placed").
+    return { ok: false, codeSpent: apply, error: `GitHub made the app ${creds.appSlug || creds.appId || '?'}, but placing its keys failed: ${e.message}` };
+  }
+  // The app now exists AND its credentials are placed — the checklist's first tick, and the
+  // slug the callback page needs to send the founder on to installing it (task 1004649).
+  if (apply && deps.onCredsPlaced) await Promise.resolve().then(() => deps.onCredsPlaced({ appId: creds.appId, appSlug: creds.appSlug })).catch(() => {});
+
+  // 4) verify the project reports auth_configured=true (only meaningful under --apply).
+  //    PATIENT (F23): the child must boot before it can answer; losing this race
+  //    used to record a failure for a setup that had succeeded. The JSON answer lives
+  //    at /api/bongos/healthz — the root /healthz says a plain "ok" (task 1004577).
+  if (apply) {
+    const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let authConfigured = false;
+    for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
+      const out = boxExec(authHealthzCmd(inst), { allowFail: true });
+      if (oauthSecret.parseHealthzAuth(out && out.stdout).authConfigured) { authConfigured = true; break; }
+      await sleep(MANIFEST_VERIFY_INTERVAL_MS);
+    }
+    if (!authConfigured) {
+      // The App now EXISTS on the owner's account — keep its id + slug on the row so
+      // the wizard can name it and say why "try again" makes a second one (task 1004572).
+      // Say WHY when we can see it: an adopted repo's own pack may read other names (task 1004573).
+      // A cloud-host checkout lives on the control plane (the scaffold reads it the same way), so
+      // this is a plain file read — no shell. An unreadable or non-JSON pack names nothing.
+      let packText = null;
+      if (standalone) { try { packText = (deps.readFile || fs.readFileSync)(path.join(standaloneRoot(inst), 'config', 'branding.json'), 'utf8'); } catch { packText = null; } }
+      const why = envPrefixMismatch(packText);
+      return { ok: false, codeSpent: true, appId: creds.appId, appSlug: creds.appSlug, error: `the credentials are placed, but the project did not report sign-in ready in time${why ? ` — ${why}` : ''}` };
+    }
+    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, codeSpent: apply, 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; }
+      // the slug lands on the row the moment the credentials are placed (task 1004649)
+      const onCredsPlaced = (c) => provisioning.resolveOAuthManifest(db, mrow.id, 'converting', { app_id: c.appId, app_slug: c.appSlug });
+      const result = await placeManifestCreds(inst, mrow, { ...deps, onCredsPlaced });
+      if (result && result.ok === false) {
+        // A SPENT code is terminal, always (F23): GitHub's manifest code is
+        // single-use, so resetting the row to 'code_received' guarantees the
+        // next tick re-converts a burned code and 404s forever. Only failures
+        // that happened BEFORE the conversion stay retryable.
+        if (result.codeSpent) await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: result.error, github_code: null, ...(result.appSlug ? { app_id: result.appId, app_slug: result.appSlug } : {}) });
+        else 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 {
+        // github_code: null on done too — a finished row holds no re-convertible code.
+        await provisioning.resolveOAuthManifest(db, mrow.id, 'done', { app_id: result.appId, app_slug: result.appSlug, github_code: null });
+        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) {
+      // GitHub's 404 means the code is used or past its hour: drop it, so "pick up where it
+      // stopped" (task 1004652) never re-queues a dead code. Any other failure keeps it.
+      const dead = /conversion failed: (Not Found|HTTP 404)/.test(String(e.message));
+      await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: e.message, ...(dead ? { github_code: null } : {}) }).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).
+// 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;
+  const instanceRoot = deps.instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  log(runnerBanner({ runnerVersion: coreVersionSafe(), runnerRoot: REPO_ROOT, instanceVersion: installedCoreVersion(instanceRoot), instanceRoot }));
+  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 > retry.maxAttemptsFor(intent, MAX_INTENT_ATTEMPTS)) { // a transient core move gets one try per backoff step (task 1004447)
+      await provisioning.resolveIntent(db, intent.id, 'error', `exceeded ${retry.maxAttemptsFor(intent, 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; }
+      // Dispatch EXPLICITLY per action — an unrecognized action must surface as an
+      // error, never fall through to the destructive teardown leg (task 1002692).
+      let result;
+      if (intent.action === 'provision') result = await require('./provision-render.js').afterProvision(inst, deps, intent, await provisionInstance(inst, deps)); // then the app on Render, when the wizard lent a key (task 1004352)
+      else if (intent.action === 'teardown') result = await teardownInstance(inst, deps);
+      else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, deps);
+      else if (intent.action === 'settings-apply') result = await settingsApplyInstance(inst, deps);
+      else if (intent.action === 'restart') result = await restartInstance(inst, deps);
+      else if (intent.action === 'disconnect') result = await disconnectInstance(inst, deps);
+      else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
+      else if (intent.action === 'core-upgrade-preflight') result = await preflightCoreUpgrade(inst, deps, intent); // changes nothing; caches what the move WOULD say (task 1004121)
+      else if (intent.action === 'repo-private' || intent.action === 'render-standup') result = intent.action === 'repo-private' ? await require('./provision-repo-private.js').repoPrivateInstance(inst, deps) : await require('./provision-render.js').renderStandupInstance(inst, deps, intent); // wire the deploy key, THEN flip (task 1004193) · spend the borrowed Render key once (task 1004183); required here — this file is at the size ratchet
+      else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
+      if (result && result.ok === false) {
+        // WAIT OR RETIRE (task 1004447, intent-retry.js): a transient failure waits ~15m/1h/6h; a
+        // classified non-transient one is retired at once (retrying cannot change its answer);
+        // an unclassified one keeps its budget but never re-runs in the same tick.
+        const fix = await require('./wedge-remedy.js').remedyAfterFailure({ intent, inst, result, deps }); // a KNOWN snag: fix it, try once more (task 1004448)
+        if (fix.repended) { errors++; continue; }
+        Object.assign(result, { failure: fix.failure, error: fix.error });
+        const next = retry.retryDecision({ attempts: intent.attempts, failure: result.failure, terminal: result.terminal, maxAttempts: MAX_INTENT_ATTEMPTS });
+        if (next.action === 'retire') { // terminal: a leg that must not be retried unattended (the Render leg's key is already gone — task 1004183)
+          await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
+          // A retired intent stops silently otherwise (F19): record the reason
+          // on the instance WITHOUT changing its lifecycle status — passing the
+          // CURRENT status makes the status write a no-op, so a healthy active
+          // instance is never marked broken over a domain hiccup, but the card
+          // can say why the work stopped.
+          await provisioning.setInstanceStatus(db, intent.instance_id, inst.status, { error_note: result.error || 'op failed', error_note_action: intent.action }).catch(() => {});
+          if (result.failure) await recordFailureClass(db, intent.id, result.failure); // WHAT KIND of failure, beside the sentence (task 1004446)
+          await require('./move-escalation.js').afterRetire({ intent, inst, result, deps }); // nobody can heal it: one blocker + one notice per move (task 1004449)
+        } else {
+          await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, not_before = now() + ($3 * interval '1 millisecond'), updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed', next.delayMs]);
+          if (result.failure) await recordFailureClass(db, intent.id, result.failure);
+        }
+        errors++;
+      } else { await provisioning.resolveIntent(db, intent.id, 'done', (result && result.doneNote) || null); ok++; await require('./move-escalation.js').afterSuccess({ intent, inst, result, deps }); } // done WITH a note: it landed, and this is what it could not finish (task 1004065)
+    } 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, error_note_action: intent.action }).catch(() => {});
+      errors++; log(`  ✖ intent #${intent.id}: ${e.message}`);
+    }
+  }
+  await snapshotAllCoreVersions(deps); // refresh what the deploy control reads, AFTER the drain (ADR 0293 D3/D6)
+  await require('./provision-auto-upgrade.js').autoUpgradeTick(deps); // then act on each hosted project's update rule: preflight, then move, one per tick (task 1004729, ADR 0381)
+  const m = await drainOAuthManifests(deps); // same tick: convert + place any GitHub-App-Manifest creds awaiting the control plane
+  await require('./provision-github-setup.js').verifyGithubAppSetups(deps).catch((e) => log(`  github-setup check failed (non-blocking): ${e.message}`)); // install + device flow, asked of GitHub with the app's key (task 1004649)
+  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 box-vs-DB drift
+// 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\n${await statusCapacityLine(db)}`);   // + "box at N of M" (ADR 0285, task 1003927)
+  return { count: rows.length };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function usage() {
+  console.log(`provision.js — instance-provisioning control-plane runner (ADR 0111, #1944)
+
+Usage:
+  node scripts/bongos/provision.js <command> [slug] [--apply]
+
+Commands:
+  run-intents            drain provisioning_intents (the systemd-timer entry point):
+                         execute each pending provision / teardown / domain-attach /
+                         settings-apply 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
+  apply-caps             cap every active hosted project's memory/CPU/tasks live (task 1004414)
+  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.`);
+}
+
+// Store an intent's failure class + reason code (migration provisioning_030, task 1004446),
+// only for a result that carries one. Best-effort: a runner on a schema without the columns
+// must still drain, so a failed write is swallowed — last_error still says it either way. A
+// class left on a row that later lands 'done' is harmless: readers ignore it on a done row.
+async function recordFailureClass(db, intentId, failure) {
+  await db.query('UPDATE provisioning_intents SET failure_class = $2, failure_reason = $3 WHERE id = $1',
+    [intentId, failure ? failure.class : null, failure ? failure.reason : null]).catch(() => {});
+}
+
+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', 'apply-caps'];
+  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, platformIdentity, hubKeys, projectCatalog;
+  try { ({ pool, provisioning, platformIdentity, hubKeys, projectCatalog } = 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).
+  // Remote mode needs an explicit checkout dir (task 1002756 — no founder default).
+  if (CONFIG.remoteHost && !CONFIG.remoteCwd) { console.error('PROVISION_REMOTE_HOST is set but PROVISION_REMOTE_CHECKOUT is not — name the co-hosting box\'s checkout dir (the old hardcoded default was removed, task 1002756).'); process.exit(2); }
+  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 }),
+    // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
+    // dormant; shouldFederate() then skips and the instance owns its auth (as today).
+    platformIdentity, hubKeys,
+    projectCatalog,   // the disconnect leg's catalog forget (task 1003249); null off the hub
+  };
+
+  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);
+    else if (cmd === 'apply-caps') result = await require('./provision-caps.js').cmdApplyCaps(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, provisionerBotEmail,
+  // pure step generators (tested directly)
+  dbName, dbCreateCmd, migrateCmd, seedFirstVersionCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
+  // per-instance unix account + password-authed PG role (task 1003369, audit B3)
+  instanceUser, instanceStateDir, instanceDbRole, generateDbPassword, ensureInstanceUserCmd, grantInstanceRepoReadCmd, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd,
+  backupUnitName, backupServicePath, backupTimerPath, backupScriptPath, backupService, backupTimer,
+  standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
+  // standalone scaffold (ADR 0108 / 0125, task 2055; consumer-core fix task 1002275)
+  parseTargetRef, instanceRepoRemote, instanceInitSpec, installedCoreTarball, installedCorePackDir, scaffoldStandaloneRepo, coreVersionSafe,
+  // re-provision core-pin refresh (gap-list W3, task 1003050)
+  resolveVendorableCoreTarball, planCorePinRefresh, safeVersionLabel, buildCorePinRefreshCommit, refreshStandaloneCorePin,
+  // the git-less core checkout — the self-host image's rung (task 1003995)
+  coreCheckoutHasGit,
+  // adopt vs greenfield onboarding (ADR 0121, task 1002562)
+  onboardMode, alreadyScaffolded,
+  // private-repo deploy key (ADR 0176, task 1002735)
+  resolveOwnerGithubToken, deployKeyTitle, deployKeyPath, ensurePrivateRepoAccess,
+  zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,
+  caddyBlock, caddySnippetPath, healthzCmd, nextFreePort,
+  // executors + orchestration (injectable deps for tests)
+  makeExec, makeWriteFile, allocatePort, boundLocalPorts, provisionInstance, teardownInstance,
+  domainAttachInstance, releasableDomains, cmdRunIntents, cmdReconcile, cmdStatus,
+  // live settings push (task 1003140) + the in-place env patch + read-back it rides on
+  settingsApplyInstance, upsertEnvVars, renamedEnvCarry, settingsEnvVarsFor, settingsConsumed, instanceManifestCmd,
+  // restart an unreachable ACTIVE instance (task 1003238) — the settings leg minus the env patch
+  restartInstance,
+  // GitHub App Manifest flow (task 2080, ADR 0133)
+  convertManifestCode, placeManifestCreds, drainOAuthManifests, authHealthzCmd, MANIFEST_UA,
+  // cross-site identity federation (ADR 0141 §4, task #1002109)
+  federationHubOrigin, shouldFederate, federateInstance,
+};