@bongos/core 1.19.332 → 1.19.333

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.332",
+  "version": "1.19.333",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.332",
+      "version": "1.19.333",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.332",
+  "version": "1.19.333",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/box-infra.js

@@ -0,0 +1,280 @@
+// scripts/gds/box-infra.js — the dev-box CONFIG block plus everything that
+// turns it into a bootable droplet: infra/ resolution, naming, the DNS hook,
+// and cloud-init rendering.
+//
+// Carved out of scripts/gds/box.js by task 1003206 (goal 1000079, the R03
+// de-monolith plan) to bring that file under the 1,500-line ratchet. A
+// STRUCTURAL move: the lines below are box.js's originals unchanged, and box.js
+// requires every name straight back, so the operator CLI is untouched.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const { execFileSync } = require('node:child_process');
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const instanceConfig = require(path.join(REPO_ROOT, 'src/instance-config'));
+const BOX_INFRA_TEMPLATE = 'builder-box-cloud-init.yaml';
+
+function boxInfraCandidates({ env = process.env, repoRoot = REPO_ROOT } = {}) {
+  const out = [];
+  const seen = new Set();
+  const add = (d) => { if (d && !seen.has(d)) { seen.add(d); out.push(d); } };
+  // 1. explicit override: <PREFIX>_BOX_INFRA_DIR (operator escape hatch).
+  const override = instanceConfig.resolveEnv('BOX_INFRA_DIR', { env });
+  if (override) add(path.resolve(override));
+  // 2. the instance root via an EXPLICIT pointer (<PREFIX>_INSTANCE_ROOT env or a
+  //    bongos.config.json {"instanceRoot":"."}) — where a vendored instance keeps infra/.
+  const inst = instanceConfig.resolveInstanceRootExplicit({ env });
+  if (inst) add(path.join(inst, 'infra'));
+  // 3. REPO_ROOT/infra — the dev single-checkout (and the ADR 0144 node_modules workaround).
+  add(path.join(repoRoot, 'infra'));
+  // 4. walk up out of node_modules from the core root, so a vendored
+  //    …/node_modules/@bongos/core still finds its host instance's infra/ with no pointer set.
+  let dir = repoRoot;
+  for (let i = 0; i < 6; i += 1) {
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+    add(path.join(dir, 'infra'));
+  }
+  return out;
+}
+
+// The resolved infra/ dir (first candidate holding the template), or null when the
+// box cloud-init cannot be located anywhere — the caller MUST fail loud on null
+// rather than provision a box with empty user-data (ADR 0150).
+function resolveBoxInfraDir(opts = {}) {
+  for (const c of boxInfraCandidates(opts)) {
+    try { if (fs.existsSync(path.join(c, BOX_INFRA_TEMPLATE))) return c; }
+    catch { /* unreadable candidate → try the next */ }
+  }
+  return null;
+}
+
+// task 1002757 — the instance's own apex; null when unconfigured (callers refuse).
+const { instanceApex } = require('./instance-apex');
+
+const CONFIG = {
+  floor: process.env.BOX_PROVISION_MIN_RANK || 'xenos',
+  region: process.env.BOX_REGION || 'nyc3',
+  size: process.env.BOX_SIZE || 's-2vcpu-4gb',
+  baseImage: process.env.BOX_BASE_IMAGE || 'ubuntu-24-04-x64',
+  idleMinutes: numEnv('BOX_IDLE_MINUTES', 10),
+  dormantDays: numEnv('BOX_DORMANT_DAYS', 14),
+  // task 1002727 — how many days BEFORE the reclaim a builder gets warned.
+  dormantWarnLeadDays: numEnv('BOX_DORMANT_WARN_LEAD_DAYS', 3),
+  sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
+  dnsHook: process.env.BOX_DNS_HOOK || null,
+  tag: process.env.BOX_TAG || 'otb-builder-box',
+  // task 1002757 settled this file's old carve-out: an operator-plane DNS zone is
+  // still a FUNCTIONAL DEFAULT, and a founder literal aimed another operator's
+  // fleet at the founder's zone. Derived from the instance apex, null when
+  // unconfigured — hostnameFor() then refuses instead of minting a dead FQDN.
+  dnsZone: process.env.BOX_DNS_ZONE || (instanceApex() ? `dev.${instanceApex()}` : null),
+};
+
+// Named-tunnel automation for the browser terminal (#771, ADR 0038 Part B).
+// OPT-IN, default OFF — an unset BOX_NAMED_TUNNEL leaves the box on the tokenless
+// quick tunnel (trycloudflare.com), the zero-secret #760 default. When the operator
+// turns it on AND supplies a Cloudflare token with Tunnel + DNS scope (the same
+// CLOUDFLARE_API_TOKEN box-dns uses) + the account id, every provision creates a
+// stable term-<login>.<terminalZone> tunnel and bakes its connector token into the
+// box; deprovision tears it down.
+const CF = {
+  enabled: /^(1|true|yes)$/i.test(process.env.BOX_NAMED_TUNNEL || ''),
+  apiToken: process.env.CLOUDFLARE_API_TOKEN || null,
+  accountId: process.env.CLOUDFLARE_ACCOUNT_ID || null,
+  // The Cloudflare ZONE the record lives in (the registrable apex) — the terminal
+  // host is a record WITHIN it, matching box-dns-cloudflare.sh. Distinct from
+  // terminalZone (the host suffix). Both resolve from the instance (task 1002757).
+  zone: process.env.CLOUDFLARE_ZONE || instanceApex(),
+  // Host suffix for term-<login>.<terminalZone>. DEFAULTS TO THE APEX, NOT dev.*:
+  // the terminal rides a PROXIED tunnel, and free Universal SSL covers <apex> +
+  // *.<apex> (ONE label) but not a TWO-label host like term-x.dev.<apex>, which
+  // fails TLS at the edge (verified live, #771). An operator holding an Advanced
+  // Certificate for *.dev.<apex> can override via BOX_TERMINAL_ZONE. (The SSH
+  // A-record path stays on dev.* — proxied=false, so it needs no edge cert.)
+  terminalZone: process.env.BOX_TERMINAL_ZONE || instanceApex(),
+};
+
+// Named-tunnel automation is live only when the operator opted in AND the
+// credentials are present. Missing creds while enabled is a loud config error at
+// provision time (see cmdProvision), not a silent fall-back, so an operator who
+// meant to use named tunnels learns immediately.
+function numEnv(name, dflt) {
+  const v = process.env[name];
+  if (v == null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+function hasFlag(args, name) { return args.includes(name); }
+
+// Lazy + memoized DB + lib load so `--help` and arg errors don't require Postgres
+// (this CLI runs on a non-droplet machine for dry-run planning of pure logic too):
+// nothing is require()d until the first makeDo/makeCf/IIFE call, and repeat calls
+// reuse the first resolution instead of re-running the six requires.
+let _deps;
+function shortStamp() {
+  return new Date().toISOString().replace(/[-:T.Z]/g, '').slice(2, 14);
+}
+
+function dropletName(login) { return `otb-box-${login}`; }
+// Refuses on an unresolved zone (task 1002757) — `box-x.undefined` would mint a
+// DNS record and a box that can never be reached.
+function hostnameFor(login) {
+  if (!CONFIG.dnsZone) throw new Error('box: no DNS zone configured — set BOX_DNS_ZONE, or give this instance a domains.publicOrigin in config/branding.json (task 1002757).');
+  return `box-${login}.${CONFIG.dnsZone}`;
+}
+
+// Run the optional DNS hook so the per-builder hostname tracks the new IP; with no
+// hook configured, print the reminder — the stable-hostname CUTOVER is #599's, #598
+// only records IP + hostname and offers the hook so an operator can wire DNS without
+// editing this file. → { ok, error?, skipped? }. task 1180: callers MUST act on
+// ok:false (box_events row + flag the box), never continue silently — that swallow
+// left @kingaonline's A record pinned at a dead IP while provision reported success.
+// The hook retries transient Cloudflare blips, so ok:false is a real, exhausted
+// failure. `hook` is injectable so the contract is unit-testable (#1034).
+function runDnsHook(hostname, ip, hook = CONFIG.dnsHook) {
+  if (!ip) return { ok: true, skipped: true };
+  if (!hook) {
+    console.log(`  ↳ DNS: point ${hostname} → ${ip} (no BOX_DNS_HOOK set; #599 owns the cutover)`);
+    return { ok: true, skipped: true };
+  }
+  try {
+    execFileSync('bash', ['-c', hook], {
+      cwd: REPO_ROOT, stdio: 'pipe',
+      env: { ...process.env, BOX_HOSTNAME: hostname, BOX_IP: ip },
+    });
+    console.log(`  ↳ DNS hook updated ${hostname} → ${ip}`);
+    return { ok: true };
+  } catch (e) {
+    const msg = (e.stderr && e.stderr.toString().trim()) || e.message;
+    console.log(`  ⚠ DNS hook failed: ${msg} (point ${hostname} → ${ip} manually)`);
+    return { ok: false, error: msg };
+  }
+}
+
+// Blackhole sentinel for a torn-down box's A record (idea 309). 192.0.2.1 is in
+// TEST-NET-1 (RFC 5737) — reserved for documentation and GUARANTEED never to be a
+// routable host, so no recycled DigitalOcean IP can ever land here. A perfect
+// dead end to park a record at.
+const DNS_BLACKHOLE_IP = '192.0.2.1';
+
+// Park the per-builder A record at the blackhole sentinel on deprovision (idea 309,
+// refining task 1180). 1180 DELETED the record so it couldn't dangle at a recycled
+// DO IP, but delete-then-recreate across a reap→rebuild left an NXDOMAIN window that
+// resolvers negative-cache for the zone's SOA neg-TTL (~30 min, not builder-editable)
+// — a client querying then kept getting ENOTFOUND long after the box was back.
+// REPOINTING to a non-routable sentinel keeps the name always-resolving (nothing to
+// negative-cache) while preserving 1180's guarantee that a torn-down box's name can
+// never dial a stranger's recycled IP; the next provision/wake PUTs the live IP
+// in-place at the 60s TTL, no gap. Best-effort like the prior delete. Reuses
+// runDnsHook's UPSERT path; `hook` injectable for tests. → { ok, error?, skipped? }
+function runDnsHookBlackhole(hostname, hook = CONFIG.dnsHook) {
+  if (!hook || !hostname) return { ok: true, skipped: true };
+  return runDnsHook(hostname, DNS_BLACKHOLE_IP, hook);
+}
+
+// Read the cloud-init template and substitute the repo URL from BOX_REPO_URL
+// (kept out of the repo file so no GitHub identity is hardcoded — V3.R12 rule).
+// An unset URL leaves the placeholder; the cloud-init then logs guidance rather
+// than cloning, and #600 wires the scoped credential.
+// Read + render the cloud-init. `authorizedKeysBlock` is the otb-managed block
+// for the builder being provisioned (#685) — base64'd here and baked in so the
+// FIRST SSH login works before the box has a GDS token. An empty/absent block
+// renders an empty managed block (a keyless box; the operator is warned upstream).
+function readCloudInit({ authorizedKeysBlock = '', boxEnv = '', gdsSession = '', infraDir = resolveBoxInfraDir() } = {}) {
+  // Fail loud, never provision a BARE box (ADR 0150). No infra/ located → there is
+  // no cloud-init to render, so THROW here rather than the old silent `return null`
+  // that let cmdProvision ship empty user-data (a box that boots as bare Ubuntu).
+  if (!infraDir) {
+    throw new Error(
+      `box cloud-init not found: no infra/${BOX_INFRA_TEMPLATE} in any candidate location `
+      + `(set <PREFIX>_BOX_INFRA_DIR or <PREFIX>_INSTANCE_ROOT, or ship infra/). A box must `
+      + `never be provisioned without user-data — it would boot bare (ADR 0150).`,
+    );
+  }
+  const p = path.join(infraDir, BOX_INFRA_TEMPLATE);
+  // gzip+base64 a repo file into the cloud-init write_files (`encoding: gz+b64`).
+  // EVERY inlined infra file goes through this: cloud-init gunzips it back to the
+  // exact bytes on the box, so it is byte-identical to plain b64 but ~2-3x smaller,
+  // which keeps the rendered user-data well under DO's 64 KiB cap (#903; the source
+  // -fetch growth in task 1314 had pushed the all-b64-but-source-fetch render to
+  // 67 KB — gz+b64-ing the rest brings it back to ~51 KB, task 1321). Only the
+  // dynamic runtime values (authorized_keys, box.env, gds-session) stay plain b64
+  // below — they are minted per-provision, not read from infra/. A missing inlined
+  // file is COLLECTED and fails loud after the render (ADR 0150) — a half-wired box
+  // (that component silently never boots) is a bug, not something to warn past.
+  const missingInfra = [];
+  const fileGzB64 = (name) => {
+    try {
+      return zlib.gzipSync(fs.readFileSync(path.join(infraDir, name))).toString('base64');
+    } catch {
+      missingInfra.push(name);
+      return '';
+    }
+  };
+  const raw = fs.readFileSync(p, 'utf8');
+  // Inject the rank-gated source-fetch (#600) + authorized-keys-fetch (#685)
+  // scripts as gz+b64 (a single YAML-safe token — no indentation/escaping
+  // pitfalls; cloud-init gunzips encoding: gz+b64 back to the exact file), plus
+  // the baked authorized_keys block. ONE canonical copy of each lives in infra/.
+  const rendered = raw
+    .replace(/__REPO_URL__/g, process.env.BOX_REPO_URL || '')
+    .replace(/__BOX_SOURCE_FETCH_B64__/g, fileGzB64('box-source-fetch.sh'))
+    .replace(/__BOX_AUTHKEYS_FETCH_B64__/g, fileGzB64('box-authorized-keys-fetch.sh'))
+    .replace(/__BUILDER_AUTHORIZED_KEYS_B64__/g, Buffer.from(authorizedKeysBlock || '', 'utf8').toString('base64'))
+    // /etc/otb/box.env — empty by default (quick tunnel); the named-tunnel
+    // connector token + stable hostname when BOX_NAMED_TUNNEL is on (#771).
+    .replace(/__BOX_ENV_B64__/g, Buffer.from(boxEnv || '', 'utf8').toString('base64'))
+    // /root/.config/otb/gds-session.json — the builder's GDS session, minted at
+    // provision so box-source-fetch (#600) can authenticate on FIRST boot and
+    // clone the rank-scoped repo. Without it the box never clones (the #818
+    // chicken-and-egg: the session normally comes from /builder-setup, which
+    // lives in the un-cloned repo).
+    .replace(/__GDS_SESSION_B64__/g, Buffer.from(gdsSession || '', 'utf8').toString('base64'))
+    // #774: the browser-terminal units, inlined so they start at FIRST BOOT
+    // (independent of the repo clone). ONE canonical copy lives in infra/.
+    .replace(/__BOX_TERMINAL_SERVICE_B64__/g, fileGzB64('box-terminal.service'))
+    // #917: credential-drift watcher pair — restarts ttyd when the credential
+    // file lands/changes after the service started (the wake/first-boot race).
+    .replace(/__BOX_TERMINAL_CREDSYNC_SERVICE_B64__/g, fileGzB64('box-terminal-credsync.service'))
+    .replace(/__BOX_TERMINAL_CREDENTIAL_PATH_B64__/g, fileGzB64('box-terminal-credential.path'))
+    .replace(/__CLOUDFLARED_SERVICE_B64__/g, fileGzB64('cloudflared.service'))
+    .replace(/__CLOUDFLARED_RUN_B64__/g, fileGzB64('cloudflared-run.sh'))
+    // #893: the `close-box` teardown command, present at first boot so a bare
+    // browser-only box has it before any repo clone (box-source-fetch refreshes
+    // it on existing boxes). ONE canonical copy lives in infra/close-box.sh.
+    .replace(/__CLOSE_BOX_B64__/g, fileGzB64('close-box.sh'))
+    // task 986: the browser-terminal auto-launcher — runs `claude` on first
+    // connect so the builder skips the "type claude" step. box-source-fetch
+    // refreshes it on existing boxes. ONE canonical copy in infra/otb-box-launch.sh.
+    .replace(/__OTB_BOX_LAUNCH_B64__/g, fileGzB64('otb-box-launch.sh'));
+  if (missingInfra.length) {
+    throw new Error(
+      `box cloud-init is incomplete under ${infraDir}: missing ${missingInfra.join(', ')} `
+      + `— a box would boot half-wired (ADR 0150). Fix the instance infra/ before provisioning.`,
+    );
+  }
+  return rendered;
+}
+
+
+module.exports = {
+  CF,
+  CONFIG,
+  boxInfraCandidates,
+  dropletName,
+  hasFlag,
+  hostnameFor,
+  instanceApex,
+  numEnv,
+  readCloudInit,
+  resolveBoxInfraDir,
+  runDnsHook,
+  runDnsHookBlackhole,
+  shortStamp,
+};

package/scripts/gds/box.js

@@ -58,92 +58,7 @@ const BOX_INFRA_TEMPLATE = 'builder-box-cloud-init.yaml';
 // Ordered candidate infra/ dirs — first that actually holds the cloud-init
 // template wins. Pure (env + repoRoot injected) so it is unit-testable without
 // touching the real filesystem layout.
-function boxInfraCandidates({ env = process.env, repoRoot = REPO_ROOT } = {}) {
-  const out = [];
-  const seen = new Set();
-  const add = (d) => { if (d && !seen.has(d)) { seen.add(d); out.push(d); } };
-  // 1. explicit override: <PREFIX>_BOX_INFRA_DIR (operator escape hatch).
-  const override = instanceConfig.resolveEnv('BOX_INFRA_DIR', { env });
-  if (override) add(path.resolve(override));
-  // 2. the instance root via an EXPLICIT pointer (<PREFIX>_INSTANCE_ROOT env or a
-  //    bongos.config.json {"instanceRoot":"."}) — where a vendored instance keeps infra/.
-  const inst = instanceConfig.resolveInstanceRootExplicit({ env });
-  if (inst) add(path.join(inst, 'infra'));
-  // 3. REPO_ROOT/infra — the dev single-checkout (and the ADR 0144 node_modules workaround).
-  add(path.join(repoRoot, 'infra'));
-  // 4. walk up out of node_modules from the core root, so a vendored
-  //    …/node_modules/@bongos/core still finds its host instance's infra/ with no pointer set.
-  let dir = repoRoot;
-  for (let i = 0; i < 6; i += 1) {
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-    add(path.join(dir, 'infra'));
-  }
-  return out;
-}
-
-// The resolved infra/ dir (first candidate holding the template), or null when the
-// box cloud-init cannot be located anywhere — the caller MUST fail loud on null
-// rather than provision a box with empty user-data (ADR 0150).
-function resolveBoxInfraDir(opts = {}) {
-  for (const c of boxInfraCandidates(opts)) {
-    try { if (fs.existsSync(path.join(c, BOX_INFRA_TEMPLATE))) return c; }
-    catch { /* unreadable candidate → try the next */ }
-  }
-  return null;
-}
-
-// task 1002757 — the instance's own apex; null when unconfigured (callers refuse).
-const { instanceApex } = require('./instance-apex');
-
-const CONFIG = {
-  floor: process.env.BOX_PROVISION_MIN_RANK || 'xenos',
-  region: process.env.BOX_REGION || 'nyc3',
-  size: process.env.BOX_SIZE || 's-2vcpu-4gb',
-  baseImage: process.env.BOX_BASE_IMAGE || 'ubuntu-24-04-x64',
-  idleMinutes: numEnv('BOX_IDLE_MINUTES', 10),
-  dormantDays: numEnv('BOX_DORMANT_DAYS', 14),
-  // task 1002727 — how many days BEFORE the reclaim a builder gets warned.
-  dormantWarnLeadDays: numEnv('BOX_DORMANT_WARN_LEAD_DAYS', 3),
-  sshKeyIds: (process.env.BOX_SSH_KEY_IDS || '').split(',').map((s) => s.trim()).filter(Boolean),
-  dnsHook: process.env.BOX_DNS_HOOK || null,
-  tag: process.env.BOX_TAG || 'otb-builder-box',
-  // task 1002757 settled this file's old carve-out: an operator-plane DNS zone is
-  // still a FUNCTIONAL DEFAULT, and a founder literal aimed another operator's
-  // fleet at the founder's zone. Derived from the instance apex, null when
-  // unconfigured — hostnameFor() then refuses instead of minting a dead FQDN.
-  dnsZone: process.env.BOX_DNS_ZONE || (instanceApex() ? `dev.${instanceApex()}` : null),
-};
-
-// Named-tunnel automation for the browser terminal (#771, ADR 0038 Part B).
-// OPT-IN, default OFF — an unset BOX_NAMED_TUNNEL leaves the box on the tokenless
-// quick tunnel (trycloudflare.com), the zero-secret #760 default. When the operator
-// turns it on AND supplies a Cloudflare token with Tunnel + DNS scope (the same
-// CLOUDFLARE_API_TOKEN box-dns uses) + the account id, every provision creates a
-// stable term-<login>.<terminalZone> tunnel and bakes its connector token into the
-// box; deprovision tears it down.
-const CF = {
-  enabled: /^(1|true|yes)$/i.test(process.env.BOX_NAMED_TUNNEL || ''),
-  apiToken: process.env.CLOUDFLARE_API_TOKEN || null,
-  accountId: process.env.CLOUDFLARE_ACCOUNT_ID || null,
-  // The Cloudflare ZONE the record lives in (the registrable apex) — the terminal
-  // host is a record WITHIN it, matching box-dns-cloudflare.sh. Distinct from
-  // terminalZone (the host suffix). Both resolve from the instance (task 1002757).
-  zone: process.env.CLOUDFLARE_ZONE || instanceApex(),
-  // Host suffix for term-<login>.<terminalZone>. DEFAULTS TO THE APEX, NOT dev.*:
-  // the terminal rides a PROXIED tunnel, and free Universal SSL covers <apex> +
-  // *.<apex> (ONE label) but not a TWO-label host like term-x.dev.<apex>, which
-  // fails TLS at the edge (verified live, #771). An operator holding an Advanced
-  // Certificate for *.dev.<apex> can override via BOX_TERMINAL_ZONE. (The SSH
-  // A-record path stays on dev.* — proxied=false, so it needs no edge cert.)
-  terminalZone: process.env.BOX_TERMINAL_ZONE || instanceApex(),
-};
-
-// Named-tunnel automation is live only when the operator opted in AND the
-// credentials are present. Missing creds while enabled is a loud config error at
-// provision time (see cmdProvision), not a silent fall-back, so an operator who
-// meant to use named tunnels learns immediately.
+const { CF, CONFIG, boxInfraCandidates, dropletName, hasFlag, hostnameFor, numEnv, readCloudInit, resolveBoxInfraDir, runDnsHook, runDnsHookBlackhole, shortStamp } = require('./box-infra.js');
 function namedTunnelEnabled() { return CF.enabled; }
 function namedTunnelConfigured() { return CF.enabled && CF.apiToken && CF.accountId; }
 
@@ -194,20 +109,6 @@ async function preflightCookieStripScope() {
   return scope;
 }
 
-function numEnv(name, dflt) {
-  const v = process.env[name];
-  if (v == null || v === '') return dflt;
-  const n = Number(v);
-  return Number.isFinite(n) && n > 0 ? n : dflt;
-}
-
-function hasFlag(args, name) { return args.includes(name); }
-
-// Lazy + memoized DB + lib load so `--help` and arg errors don't require Postgres
-// (this CLI runs on a non-droplet machine for dry-run planning of pure logic too):
-// nothing is require()d until the first makeDo/makeCf/IIFE call, and repeat calls
-// reuse the first resolution instead of re-running the six requires.
-let _deps;
 function loadDeps() {
   if (_deps) return _deps;
   // eslint-disable-next-line global-require
@@ -274,151 +175,6 @@ async function resolveBuilder(pool, ref) {
 }
 
 // A short, DNS-safe-ish suffix from the current time (CLI context — Date is fine).
-function shortStamp() {
-  return new Date().toISOString().replace(/[-:T.Z]/g, '').slice(2, 14);
-}
-
-function dropletName(login) { return `otb-box-${login}`; }
-// Refuses on an unresolved zone (task 1002757) — `box-x.undefined` would mint a
-// DNS record and a box that can never be reached.
-function hostnameFor(login) {
-  if (!CONFIG.dnsZone) throw new Error('box: no DNS zone configured — set BOX_DNS_ZONE, or give this instance a domains.publicOrigin in config/branding.json (task 1002757).');
-  return `box-${login}.${CONFIG.dnsZone}`;
-}
-
-// Run the optional DNS hook so the per-builder hostname tracks the new IP; with no
-// hook configured, print the reminder — the stable-hostname CUTOVER is #599's, #598
-// only records IP + hostname and offers the hook so an operator can wire DNS without
-// editing this file. → { ok, error?, skipped? }. task 1180: callers MUST act on
-// ok:false (box_events row + flag the box), never continue silently — that swallow
-// left @kingaonline's A record pinned at a dead IP while provision reported success.
-// The hook retries transient Cloudflare blips, so ok:false is a real, exhausted
-// failure. `hook` is injectable so the contract is unit-testable (#1034).
-function runDnsHook(hostname, ip, hook = CONFIG.dnsHook) {
-  if (!ip) return { ok: true, skipped: true };
-  if (!hook) {
-    console.log(`  ↳ DNS: point ${hostname} → ${ip} (no BOX_DNS_HOOK set; #599 owns the cutover)`);
-    return { ok: true, skipped: true };
-  }
-  try {
-    execFileSync('bash', ['-c', hook], {
-      cwd: REPO_ROOT, stdio: 'pipe',
-      env: { ...process.env, BOX_HOSTNAME: hostname, BOX_IP: ip },
-    });
-    console.log(`  ↳ DNS hook updated ${hostname} → ${ip}`);
-    return { ok: true };
-  } catch (e) {
-    const msg = (e.stderr && e.stderr.toString().trim()) || e.message;
-    console.log(`  ⚠ DNS hook failed: ${msg} (point ${hostname} → ${ip} manually)`);
-    return { ok: false, error: msg };
-  }
-}
-
-// Blackhole sentinel for a torn-down box's A record (idea 309). 192.0.2.1 is in
-// TEST-NET-1 (RFC 5737) — reserved for documentation and GUARANTEED never to be a
-// routable host, so no recycled DigitalOcean IP can ever land here. A perfect
-// dead end to park a record at.
-const DNS_BLACKHOLE_IP = '192.0.2.1';
-
-// Park the per-builder A record at the blackhole sentinel on deprovision (idea 309,
-// refining task 1180). 1180 DELETED the record so it couldn't dangle at a recycled
-// DO IP, but delete-then-recreate across a reap→rebuild left an NXDOMAIN window that
-// resolvers negative-cache for the zone's SOA neg-TTL (~30 min, not builder-editable)
-// — a client querying then kept getting ENOTFOUND long after the box was back.
-// REPOINTING to a non-routable sentinel keeps the name always-resolving (nothing to
-// negative-cache) while preserving 1180's guarantee that a torn-down box's name can
-// never dial a stranger's recycled IP; the next provision/wake PUTs the live IP
-// in-place at the 60s TTL, no gap. Best-effort like the prior delete. Reuses
-// runDnsHook's UPSERT path; `hook` injectable for tests. → { ok, error?, skipped? }
-function runDnsHookBlackhole(hostname, hook = CONFIG.dnsHook) {
-  if (!hook || !hostname) return { ok: true, skipped: true };
-  return runDnsHook(hostname, DNS_BLACKHOLE_IP, hook);
-}
-
-// Read the cloud-init template and substitute the repo URL from BOX_REPO_URL
-// (kept out of the repo file so no GitHub identity is hardcoded — V3.R12 rule).
-// An unset URL leaves the placeholder; the cloud-init then logs guidance rather
-// than cloning, and #600 wires the scoped credential.
-// Read + render the cloud-init. `authorizedKeysBlock` is the otb-managed block
-// for the builder being provisioned (#685) — base64'd here and baked in so the
-// FIRST SSH login works before the box has a GDS token. An empty/absent block
-// renders an empty managed block (a keyless box; the operator is warned upstream).
-function readCloudInit({ authorizedKeysBlock = '', boxEnv = '', gdsSession = '', infraDir = resolveBoxInfraDir() } = {}) {
-  // Fail loud, never provision a BARE box (ADR 0150). No infra/ located → there is
-  // no cloud-init to render, so THROW here rather than the old silent `return null`
-  // that let cmdProvision ship empty user-data (a box that boots as bare Ubuntu).
-  if (!infraDir) {
-    throw new Error(
-      `box cloud-init not found: no infra/${BOX_INFRA_TEMPLATE} in any candidate location `
-      + `(set <PREFIX>_BOX_INFRA_DIR or <PREFIX>_INSTANCE_ROOT, or ship infra/). A box must `
-      + `never be provisioned without user-data — it would boot bare (ADR 0150).`,
-    );
-  }
-  const p = path.join(infraDir, BOX_INFRA_TEMPLATE);
-  // gzip+base64 a repo file into the cloud-init write_files (`encoding: gz+b64`).
-  // EVERY inlined infra file goes through this: cloud-init gunzips it back to the
-  // exact bytes on the box, so it is byte-identical to plain b64 but ~2-3x smaller,
-  // which keeps the rendered user-data well under DO's 64 KiB cap (#903; the source
-  // -fetch growth in task 1314 had pushed the all-b64-but-source-fetch render to
-  // 67 KB — gz+b64-ing the rest brings it back to ~51 KB, task 1321). Only the
-  // dynamic runtime values (authorized_keys, box.env, gds-session) stay plain b64
-  // below — they are minted per-provision, not read from infra/. A missing inlined
-  // file is COLLECTED and fails loud after the render (ADR 0150) — a half-wired box
-  // (that component silently never boots) is a bug, not something to warn past.
-  const missingInfra = [];
-  const fileGzB64 = (name) => {
-    try {
-      return zlib.gzipSync(fs.readFileSync(path.join(infraDir, name))).toString('base64');
-    } catch {
-      missingInfra.push(name);
-      return '';
-    }
-  };
-  const raw = fs.readFileSync(p, 'utf8');
-  // Inject the rank-gated source-fetch (#600) + authorized-keys-fetch (#685)
-  // scripts as gz+b64 (a single YAML-safe token — no indentation/escaping
-  // pitfalls; cloud-init gunzips encoding: gz+b64 back to the exact file), plus
-  // the baked authorized_keys block. ONE canonical copy of each lives in infra/.
-  const rendered = raw
-    .replace(/__REPO_URL__/g, process.env.BOX_REPO_URL || '')
-    .replace(/__BOX_SOURCE_FETCH_B64__/g, fileGzB64('box-source-fetch.sh'))
-    .replace(/__BOX_AUTHKEYS_FETCH_B64__/g, fileGzB64('box-authorized-keys-fetch.sh'))
-    .replace(/__BUILDER_AUTHORIZED_KEYS_B64__/g, Buffer.from(authorizedKeysBlock || '', 'utf8').toString('base64'))
-    // /etc/otb/box.env — empty by default (quick tunnel); the named-tunnel
-    // connector token + stable hostname when BOX_NAMED_TUNNEL is on (#771).
-    .replace(/__BOX_ENV_B64__/g, Buffer.from(boxEnv || '', 'utf8').toString('base64'))
-    // /root/.config/otb/gds-session.json — the builder's GDS session, minted at
-    // provision so box-source-fetch (#600) can authenticate on FIRST boot and
-    // clone the rank-scoped repo. Without it the box never clones (the #818
-    // chicken-and-egg: the session normally comes from /builder-setup, which
-    // lives in the un-cloned repo).
-    .replace(/__GDS_SESSION_B64__/g, Buffer.from(gdsSession || '', 'utf8').toString('base64'))
-    // #774: the browser-terminal units, inlined so they start at FIRST BOOT
-    // (independent of the repo clone). ONE canonical copy lives in infra/.
-    .replace(/__BOX_TERMINAL_SERVICE_B64__/g, fileGzB64('box-terminal.service'))
-    // #917: credential-drift watcher pair — restarts ttyd when the credential
-    // file lands/changes after the service started (the wake/first-boot race).
-    .replace(/__BOX_TERMINAL_CREDSYNC_SERVICE_B64__/g, fileGzB64('box-terminal-credsync.service'))
-    .replace(/__BOX_TERMINAL_CREDENTIAL_PATH_B64__/g, fileGzB64('box-terminal-credential.path'))
-    .replace(/__CLOUDFLARED_SERVICE_B64__/g, fileGzB64('cloudflared.service'))
-    .replace(/__CLOUDFLARED_RUN_B64__/g, fileGzB64('cloudflared-run.sh'))
-    // #893: the `close-box` teardown command, present at first boot so a bare
-    // browser-only box has it before any repo clone (box-source-fetch refreshes
-    // it on existing boxes). ONE canonical copy lives in infra/close-box.sh.
-    .replace(/__CLOSE_BOX_B64__/g, fileGzB64('close-box.sh'))
-    // task 986: the browser-terminal auto-launcher — runs `claude` on first
-    // connect so the builder skips the "type claude" step. box-source-fetch
-    // refreshes it on existing boxes. ONE canonical copy in infra/otb-box-launch.sh.
-    .replace(/__OTB_BOX_LAUNCH_B64__/g, fileGzB64('otb-box-launch.sh'));
-  if (missingInfra.length) {
-    throw new Error(
-      `box cloud-init is incomplete under ${infraDir}: missing ${missingInfra.join(', ')} `
-      + `— a box would boot half-wired (ADR 0150). Fix the instance infra/ before provisioning.`,
-    );
-  }
-  return rendered;
-}
-
 // ---- provision -------------------------------------------------------------
 
 async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {