@bongos/core 1.19.331 → 1.19.333

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.331",
+  "version": "1.19.333",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.331",
+      "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.331",
+  "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/public-landing/assets/cosmos.css

@@ -414,6 +414,10 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
 /* ── page-level bits ── */
 .alert{display:none;background:var(--err-soft);border:2px solid color-mix(in srgb,var(--err) 25%,transparent);color:var(--err);font-weight:600;font-size:14px;border-radius:14px;padding:12px 16px;margin-bottom:18px;}
 .alert.on{display:block;}
+/* the raw server text folds under the alert's plain sentence (task 1003244) */
+.alert details{margin-top:8px;}
+.alert summary{cursor:pointer;font-size:12.5px;font-weight:700;}
+.alert details p{margin-top:6px;font-family:var(--font-mono);font-size:12px;font-weight:500;overflow-wrap:anywhere;}
 .loading{font-size:14.5px;font-weight:600;color:var(--ink-faint);padding:14px 0;}
 .empty{border:2px dashed var(--line);border-radius:18px;padding:22px;text-align:center;}
 .empty p{font-size:14.5px;font-weight:600;color:var(--ink-soft);margin-bottom:14px;line-height:1.55;}

package/public-landing/projects.html

@@ -614,7 +614,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
              stripFor/errMarkup/canRetry/canRevive the list card reads -->
         <div id="mStrip"></div>
         <div class="projMsg err" id="mErr" hidden></div>
-        <div class="projMsg" id="mMsg"></div>
+        <div class="projMsg" id="mMsg" role="status" aria-live="polite"></div>
         <div class="actions" id="mActs" hidden></div>
       </div>
 
@@ -683,7 +683,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
   <div class="wrap viewWrap">
     <div class="card">
       <ol class="steps" aria-label="Creation steps">
-        <li class="now" data-step="1"><span class="snum">1</span><span class="slbl">Name</span></li>
+        <li class="now" data-step="1" aria-current="step"><span class="snum">1</span><span class="slbl">Name</span></li>
         <li data-step="2"><span class="snum">2</span><span class="slbl">Type</span></li>
         <li data-step="3"><span class="snum">3</span><span class="slbl">Home</span></li>
         <li data-step="4"><span class="snum">4</span><span class="slbl">Address</span></li>
@@ -2400,16 +2400,27 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
        Six steps since task 1002772: gate 0 · name 1 · type 2 · home 3 ·
        address 4 · review 5 · done 6 (the rail shows 1-5; done marks it all). */
     var panels = { 0: 'panel-gate', 1: 'panel-name', 2: 'panel-type', 3: 'panel-home', 4: 'panel-address', 5: 'panel-review', 6: 'panel-done' };
+    /* the rail at the done panel (task 1003244): "done" is the Create step
+       still running — the marker stays on 5 until the project actually
+       answers, and only then does the whole rail read finished. aria-current
+       tells a screen reader the same thing. */
+    function paintRail(step) {
+      var landed = step === 6 && !!(live && live.instStatus === 'active');
+      var cur = step === 6 ? 5 : step;
+      root.querySelectorAll('.steps li').forEach(function (li) {
+        var n = Number(li.getAttribute('data-step'));
+        var now = !landed && n === cur;
+        li.classList.toggle('now', now);
+        li.classList.toggle('done', landed || n < cur);
+        if (now) li.setAttribute('aria-current', 'step'); else li.removeAttribute('aria-current');
+      });
+    }
     function show(step, moveFocus) {
       state.step = step;
       Object.keys(panels).forEach(function (k) {
         $(panels[k]).classList.toggle('on', Number(k) === step);
       });
-      root.querySelectorAll('.steps li').forEach(function (li) {
-        var n = Number(li.getAttribute('data-step'));
-        li.classList.toggle('now', n === step);
-        li.classList.toggle('done', n < step || step === 6);
-      });
+      paintRail(step);
       saveDraft();
       /* the done step takes the whole card — the bongo pair steps aside */
       root.querySelector('.createSplit').classList.toggle('wizDone', step === 6);
@@ -2782,14 +2793,24 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
     }
 
     /* ── create ── */
+    /* the mapped codes are headline-only; anything else gets a fixed owner
+       sentence with the raw text folded under Technical details (direction
+       §5.1, task 1003244) — operator text is never the headline */
     function friendlyCreateError(err) {
       var code = err && err.data && err.data.error && (err.data.error.code || '');
       if (code === 'slug_taken') return 'That handle is already taken by another project. Pick a different one.';
       if (code === 'bad_slug') return 'The handle didn’t pass the server’s checks — 2–40 lowercase letters, numbers, or dashes.';
-      if (code === 'domain_reserved') return 'That address is reserved for the platform itself. Pick a different handle, or bring a domain you own.';
+      /* both server branches: a reserved hostname, and any name under the platform's own apex */
+      if (code === 'domain_reserved') return 'That address belongs to the platform’s own domain — your project already gets its own address there from its handle. Use a domain you own instead.';
       if (code === 'domain_taken') return 'That address is already held by another project. Pick a different handle or domain.';
       if (code === 'bad_domain') return 'The domain didn’t parse as a real hostname — use something like myproject.example.com.';
-      return 'Couldn’t file the request: ' + (err && err.message ? err.message : 'something went sideways. Try again.');
+      if (code === 'repo_scope_required') return 'GitHub hasn’t granted repository access for this session. Sign in again — it asks for repository access — and try once more.';
+      if (code === 'request_failed') return 'The platform couldn’t file the request. Nothing was created — try again in a moment.';
+      return '';
+    }
+    function createFailureMarkup(err) {
+      return 'We couldn’t file the request just now. Nothing was created — you can try again.' +
+        '<details><summary>Technical details</summary><p>' + esc(err && err.message ? err.message : 'no detail came back') + '</p></details>';
     }
 
     /* Fresh + repo access: auto-create the empty GitHub repo NOW (the commit moment),
@@ -2901,7 +2922,9 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
           $('h-home').className = 'hint err';
           return;
         }
-        alertBox.textContent = friendlyCreateError(err);
+        var friendly = friendlyCreateError(err);
+        if (friendly) alertBox.textContent = friendly;
+        else alertBox.innerHTML = createFailureMarkup(err);
         alertBox.classList.add('on');
       });
     });
@@ -2918,7 +2941,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
     var GH_ICON = '<svg class="gh" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27s1.36.09 2 .27c1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8z"/></svg>';
 
     var instanceId = null;             /* set when a create lands / a resumed watch starts */
-    var live = { instStatus: null, manifest: null, manifestMsg: '', appSlug: null };
+    var live = { instStatus: null, manifest: null, manifestMsg: '', manifestCode: '', appSlug: null };
     var planPromises = {};             /* mode|domain → Promise<steps[]> */
     var lastStepsHtml = '';
     var FALLBACK_HUMAN_KEYS = ['github-repo', 'oauth-app', 'device-flow', 'app-install', 'first-sign-in', 'enter-hall'];
@@ -3000,8 +3023,15 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
         return '<li class="sdone" data-onboard-step="oauth-app"><b>GitHub sign-in is wired</b><p>Credentials placed and verified — sign-in on <code style="font-family:var(--font-mono)">' + esc(domain) + '</code> is live.</p></li>';
       }
       if (live.manifest === 'error' || live.manifest === 'expired') {
-        return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>' +
-          (live.manifest === 'expired' ? 'That setup link expired (they last 30 minutes) — mint a fresh one.' : 'GitHub setup hit a snag' + (live.manifestMsg ? ': ' + esc(live.manifestMsg) : '') + '. Try again.') + '</p>' +
+        /* a plain sentence first; the raw route text folds under Technical
+           details (task 1003244). The one refusal a founder can act on — no
+           address yet — says where to go instead of what the server said. */
+        var snag, raw = '';
+        if (live.manifest === 'expired') snag = 'That setup link expired (they last 30 minutes) — mint a fresh one.';
+        else if (live.manifestCode === 'domain_required') snag = 'This project needs an address first — attach one from <a href="?view=mine">your projects page</a>, then come back to this step.';
+        else { snag = 'GitHub setup didn’t start. Nothing was changed on GitHub — try again.'; raw = live.manifestMsg; }
+        return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>' + snag + '</p>' +
+          (raw ? '<details><summary>Technical details</summary><p>' + esc(raw) + '</p></details>' : '') +
           '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Set up GitHub sign-in</button>' + manualOauthDetails() + '</li>';
       }
       if (live.manifest === 'code_received') {
@@ -3186,6 +3216,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
         return res.json().catch(function () { return {}; }).then(function (d) {
           if (!res.ok) {
             var e = new Error((d.error && (d.error.message || d.error.code)) || ('HTTP ' + res.status));
+            e.code = (d.error && d.error.code) || '';
             throw e;
           }
           return d;
@@ -3206,6 +3237,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
         if (String(err && err.message) === 'signing in') return;
         if (tab) { try { tab.close(); } catch (e) {} }
         live.manifest = 'error'; live.manifestMsg = String((err && err.message) || 'could not start');
+        live.manifestCode = String((err && err.code) || '');
         renderSteps();
       });
     }
@@ -3380,7 +3412,10 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
             /* the checklist reflects live state (task 1002694): a status transition —
                e.g. the scaffold landing — re-renders the steps (change-only, so the
                5s tick never clobbers an open dropdown or mid-flight button) */
-            if (inst && inst.status !== live.instStatus) { live.instStatus = inst.status; renderSteps(); }
+            if (inst && inst.status !== live.instStatus) {
+              live.instStatus = inst.status; renderSteps();
+              if (state.step === 6) paintRail(6);   /* the rail finishes only when the project answers */
+            }
             var terminal = renderProgress(inst);
             if (!terminal) pollTimer = setTimeout(tick, 5000);
             else stopPolling();
@@ -3412,7 +3447,7 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
         instanceId = null;
         watchPending = false; manifestPending = false; manifestState = null;
         manifestStartedAt = 0; manifestStale = false;
-        live = { instStatus: null, manifest: null, manifestMsg: '', appSlug: null };
+        live = { instStatus: null, manifest: null, manifestMsg: '', manifestCode: '', appSlug: null };
         lastStepsHtml = '';
         try { sessionStorage.removeItem(CREATED_KEY); sessionStorage.removeItem(DRAFT_KEY); } catch (e) {}
         state = { step: 1, name: '', projType: null, mode: 'greenfield', owner: '', ownerTouched: false, repo: '', repoTouched: false, slug: '', slugTouched: false, domain: '', noAddress: false };
@@ -3882,7 +3917,9 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
           : '. The repository is still yours, and its database is kept — bringing it back takes one click. Or <a href="?view=new">start another</a>.</div>');
     }
     var lm = lastMsg[inst.id];
-    body += '<div class="projMsg' + (lm && lm.cls ? ' ' + lm.cls : '') + '" id="msg-' + iid + '">' + (lm ? lm.text : '') + '</div>';
+    /* a live region: an action's result is announced where the pointer is,
+       not only painted (task 1003244) */
+    body += '<div class="projMsg' + (lm && lm.cls ? ' ' + lm.cls : '') + '" id="msg-' + iid + '" role="status" aria-live="polite">' + (lm ? lm.text : '') + '</div>';
     /* every owned card opens its manage view (task 1003041) — a real link, so
        middle/ctrl-click works; the delegated handler upgrades a plain click */
     var acts = ['<a class="btn small ghost" data-manage="' + iid + '" href="?view=manage&id=' + iid + '">Manage</a>'];
@@ -3903,12 +3940,51 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
     var keepOpen = !!(oldFold && oldFold.open);
     var typed = oldInput && oldInput.value !== oldInput.defaultValue ? oldInput.value : '';
     var hadFocus = !!oldInput && document.activeElement === oldInput;
+    /* focus anywhere else on the card (a door, a confirm, the fold's summary)
+       comes back to the same control — or the nearest one — after the swap;
+       quietActions() leaves a note when a disabled button already let go */
+    var wasInside = li.contains(document.activeElement) && document.activeElement !== li;
+    var prefer = wasInside ? focusKeyOf(document.activeElement) : null;
+    var focusBack = wasInside || li.hasAttribute('data-focus-back');
+    li.removeAttribute('data-focus-back');
     li.innerHTML = orbFor(inst) + '<div class="projBody">' + body + '</div>';
     var fold = li.querySelector('details.attachFold');
     var input = fold ? fold.querySelector('input') : null;
     if (fold && keepOpen) fold.open = true;
     if (input && typed) input.value = typed;
     if (input && hadFocus) input.focus();
+    else if (focusBack) focusCardControl(inst.id, prefer);
+  }
+
+  /* ── keeping focus on the card through a re-render (task 1003244) ── */
+
+  /* which control had focus, as a selector the rebuilt card can answer;
+     a confirm's Yes/Keep lands back on the door that opened it */
+  function focusKeyOf(el) {
+    if (!el || !el.getAttribute) return null;
+    if (el.tagName === 'SUMMARY') return 'details.attachFold summary';
+    if (el.hasAttribute('data-teardown-yes') || el.hasAttribute('data-teardown-no')) return '[data-teardown]';
+    var keys = ['data-manage', 'data-attach', 'data-retry', 'data-revive', 'data-teardown'];
+    for (var i = 0; i < keys.length; i++) if (el.hasAttribute(keys[i])) return '[' + keys[i] + ']';
+    return null;
+  }
+  function focusCardControl(id, prefer) {
+    var li = liFor(id);
+    if (!li) return;
+    var t = (prefer && li.querySelector(prefer)) ||
+      li.querySelector('.actions a, .actions button') ||
+      li.querySelector('details.attachFold summary');
+    if (t) t.focus();
+  }
+  /* an action in flight: the row stays put and its buttons go quiet, so
+     nothing under the pointer is deleted mid-click; a button that held
+     focus lets go when disabled, so the card remembers to take it back */
+  function quietActions(id) {
+    var act = $('act-' + id);
+    if (!act) return;
+    var li = liFor(id);
+    if (li && act.contains(document.activeElement)) li.setAttribute('data-focus-back', '');
+    act.querySelectorAll('button').forEach(function (b) { b.disabled = true; });
   }
 
   function render(instances) {
@@ -4465,16 +4541,20 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
     var act = $('act-' + id);
     if (!act) return;
     cardAsking = String(id);
-    act.innerHTML = '<div class="confirmRow">' +
+    act.innerHTML = '<div class="confirmRow" tabindex="-1">' +
       '<span class="plain">Tear it down? ' + teardownTruth(byId[id]) + '</span>' +
       '<button type="button" class="btn small danger" data-teardown-yes="' + esc(id) + '">Yes, tear it down</button>' +
       '<button type="button" class="linklike" data-teardown-no="' + esc(id) + '">Keep it running</button></div>';
+    /* the pressed button is gone — focus lands on the question itself, so
+       the truth is read before Tab reaches Yes (task 1003244) */
+    var row = act.firstChild;
+    if (row && row.focus) row.focus();
   }
   function unAskTeardown(id) { cardAsking = null; var inst = byId[id]; if (inst) renderCard(inst); }
   function doTeardown(id) {
     cardAsking = null;
-    var act = $('act-' + id);
-    if (act) act.innerHTML = '<span class="projMsg">Asking…</span>';
+    quietActions(id);
+    msg(id, 'Asking…');
     fetch(API + '/provisioning/instances/' + encodeURIComponent(id) + '/teardown', {
       method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: '{}'
     }).then(function (res) {
@@ -4501,8 +4581,8 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
     }).catch(function () {
       msg(id, 'Couldn’t reach the platform — check your connection and try again.', 'err');
     }).then(function () {
-      /* restore the actions row ("Asking…" replaced it) even when the state
-         didn't change, then pick up whatever DID change */
+      /* wake the quieted row even when the state didn't change (renderCard
+         also hands focus back), then pick up whatever DID change */
       if (byId[id]) renderCard(byId[id]);
       watchOnce(id);
     });
@@ -4515,8 +4595,8 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
   function reProvision(id, verb) {
     var inst = byId[id];
     if (!inst) return;
-    var act = $('act-' + id);
-    if (act) act.innerHTML = '<span class="projMsg">Asking…</span>';
+    quietActions(id);
+    msg(id, 'Asking…');
     var body = { slug: inst.slug, hosting_shape: inst.hosting_shape || 'standalone' };
     if (inst.onboard_mode) body.onboard_mode = inst.onboard_mode;
     if (inst.target_ref) body.target_ref = inst.target_ref;

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,
+};